跳转至

Build recommendation system spec

Intent

A builder, a person or a coding agent, describes the UI they want in words and asks astryx build where to begin. A page template already carries the frame, the spacing, and the section rhythm the system decided on; a page composed from components has to rediscover all of that. So build's answer always starts from a template: it names one page template to scaffold, the command that scaffolds exactly that template, the next best templates, and the blocks and components that fill it.

A scaffolded template builds only when the project has what its source needs. So the template.copy receipt from astryx template, and the start and each alternative build recommends, also state that template's scaffold readiness: the packages its source imports that the project does not declare, one command that installs them, and whether the project lacks a StyleX compiler the source needs. Scaffold readiness is separate from a template's ready mark (FR1, FR4): a ready template can still need packages a project lacks.

This record owns what build recommends, how the recommendation reads in text and JSON, and the scaffold readiness that the scaffold receipt and build's recommended templates report. spec:AST-017 owns compatibility and response-field rules, spec:AST-042 owns command admission, search owns its own ranking and output, and template owners own what each template is.

Non-goals

  • How candidates are ranked. Word matching, weights, thresholds, and the ranking algorithm are implementation; this record states what the recommendation must be and how a reader can act on it.
  • Which templates exist, how they look, or what they import.
  • Writing files. Build recommends; astryx template scaffolds. This record owns only what the scaffold receipt says the project lacks.
  • Installing packages or setting up a compiler. Readiness names what is missing and how to install it; neither command installs or configures anything.
  • New commands, options, flags, or exit codes for build or template; readiness never sets an exit status (FR22).
  • Equivalent internal implementations remain valid when they satisfy this contract.

Requirements

  • FR1 — Always one start. A build that can return pages MUST name exactly one page template to start from, chosen among the ready page templates the project can scaffold, including the ones its integrations provide. A build narrowed to components or hooks names no start, and neither does a project that offers no page template.
  • FR2 — A shell when nothing leads. When no template has the evidence to lead, the start MUST be the app shell, or a blank page template when the project has no shell. The app shell is the ready, shown Shell-family template the request describes when one leads, and otherwise the default shell; a request describes a shell variant only when it names one of that variant's own keywords as a whole phrase. The start never falls back to "compose from components".
  • FR3 — A part starts where it lives. A request for a part of a page (a control, a state, a widget, a section) MUST start from the page template the request places that part in, when the request gives that page, and from the app shell (FR2) when it gives no page. A family's base template is that page only when the ranker leads with it, and never when the family word heads the request and also ends a component's name: the request then asks for that piece, not for a part of the family's page (DEC-13). The blocks and components in the kit carry the part itself. A request that changes a page the builder already has starts from the app shell (FR2): the page is the builder's to keep (FR9), and no template scaffolds it. A request that adds something to a place that names no page, only the app or product as a whole, changes no page the builder has: build reads what it adds as if the request gave no place. One exception: when the start would be the app shell, search matched no ready template directly, and build's fixed shell-start decision reads the request as a whole page (DEC-10), the start is the best-ranked page template even when the request reads as a part. A request with an edit phrase keeps the app shell.
  • FR4 — Never an unready start. A template marked not ready MUST NOT be the start or an alternative. When the request names one that search matches directly, the start's reason MUST say it is not ready yet and name the template build started from instead. A not-ready template the request does not name MUST NOT appear anywhere in build's response, and a not-ready template MUST NOT change which template build starts from: it is never search's direct match for build, and it never holds back the shell lift.
  • FR5 — The start is exact and runnable. The start and every alternative MUST carry the scaffold command that selects exactly that template in the project where build ran. A template an integration provides in place of a Core one is selected the way astryx template addresses it, and the command names the page kind so a block with the same id cannot make it ambiguous.
  • FR6 — The start says why. The start MUST carry a basis and a one-line reason. The basis is direct when the start is also search's direct match, closest when no template is exactly this page, and fallback for the shell.
  • FR7 — The builder can overrule. Beside every start, build MUST offer the next best page templates, at most two, each with its scaffold command. Templates that rank the same keep one fixed order on every host, so the same request gets the same start and alternatives on any machine.
  • FR8 — The kit fills the template. Build MUST list the blocks that fill the start before the components, and name the always-on frame and foundation components. The order of the listed blocks follows spec:AST-083.
  • FR9 — An existing page is kept. Build's text output MUST tell a builder who is changing a page they already have to keep it and use only the blocks and components.
  • FR10 — The recommendation is data. The JSON response MUST carry the recommendation itself (the start with its name, command, basis, reason, and alternatives), so no caller derives it from other fields.
  • FR11 — Additive JSON. Changes to the recommendation MUST keep the build JSON additive under spec:AST-017: new data arrives as new fields, and every existing field keeps its shape and meaning. A ranking change may move values (which templates, blocks, or components appear, and in what order); it does not change a field's shape or meaning.
  • FR12 — Text leads with the start. Build's text output MUST lead with the start, then the alternatives, then the blocks, then the components. Every response field keeps a text projection as spec:AST-017 requires: short by default, and whole under --verbose.
  • FR13 — Every agent-facing surface agrees. The build playbook, the generated agent docs, and the consumer guides that describe building a page MUST describe the same workflow: scaffold the named template, fill it with blocks, and compose only what is left. No surface tells builders to compose a page from primitives first.
  • FR14 — The written source names what it needs. The packages a template needs MUST be the packages named by the imports in the source the command writes: its import declarations, type-only ones included, its export-from declarations, and its import() and require() calls. An import that sits inside a comment, a string, or a template literal is text and names nothing. A bare specifier names one package, by its scope and name (@scope/name) or by its first segment; a Node built-in module, a relative or absolute path, a # subpath import, and a URL name none. A specifier that starts with ~/ is a path alias and names no package, because an npm package name has no ~; so does any other specifier that is not an npm package name, such as @/components.
  • FR15 — The project declares what its package.json files list. The packages a project declares MUST be the union of the dependencies, devDependencies, peerDependencies, and optionalDependencies of every package.json from the target directory up to the workspace root. The target directory is the directory the command writes into, or for build the directory where it ran (FR21). The workspace root is the nearest directory at or above the target directory that declares a workspace, by a pnpm-workspace.yaml or a package.json workspaces field; outside a workspace it is the directory of the nearest package.json, and with no package.json the project declares nothing. missingPackages MUST list each needed package (FR14) that the project does not declare, once, and is empty when none is missing.
  • FR16 — Astryx packages count like any other. An Astryx package MUST count under FR14 and FR15 like any other package: a source that imports one the project does not declare lists it in missingPackages, and in the install command when there is one (FR17). No package is exempt by name.
  • FR17 — One install command, in the project's package manager. When missingPackages is not empty and the package manager is not ambiguous (FR19), installCommand MUST be one command that installs every missing package with the project's package manager; otherwise it is null. The nearest directory, from the target directory up to the workspace root, that has a package.json packageManager field or a lockfile decides the package manager. The field names it. Without the field, the lockfiles name the package manager they belong to; when they belong to several, the directory names the one of those that its files read by only one package manager (such as pnpm-workspace.yaml or .yarnrc.yml) point to, when they point to exactly one of them. When no directory there has a field or a lockfile, the project's package manager is npm, which ships with Node.
  • FR18 — The command runs as printed. Each package in the install command MUST carry the version range declared for it by the package that ships the template's source file, which is not always the package the receipt names as the template's owner: its peerDependencies range, else its dependencies, optionalDependencies, or devDependencies range, in that order. The shipping package itself, when the source imports it, carries the version the template was read from. Any other package it declares no version range for, by declaring nothing or only a protocol value such as workspace: or catalog:, is named without a range. Run as printed, from the directory where the command ran, in any common shell (Platform support), the command MUST hand every argument to the package manager unchanged and MUST add every missing package to the package.json nearest the target directory, so FR15 then finds it declared.
  • FR19 — No command when the package manager is ambiguous. When the directory that decides the package manager (FR17) has no packageManager field and holds lockfiles of several package managers, and its files read by only one package manager point to none of those or to more than one, the package manager is ambiguous. installCommand MUST then be null, missingPackages still lists every missing package, and notes MUST name them and say why there is no command: the directory and the lockfiles that disagree.
  • FR20 — A missing StyleX compiler gets a note. When the source imports StyleX (@stylexjs/stylex) by an import that is not type-only, and no package the project declares (FR15) is a StyleX compiler, a package that compiles StyleX at build time, notes MUST say that the project needs a StyleX compiler and name the docs that set one up. The compiler stays out of missingPackages and the install command, because setting it up takes configuration as well as a package.
  • FR21 — Every recommended template carries the same readiness. The template.copy receipt MUST carry notes, missingPackages, and installCommand, and build's start and each alternative MUST carry the same fields, with the values the receipt carries when that template is scaffolded into the directory where build ran, from the source its scaffold command (FR5) writes. notes holds one line for each thing the project lacks: the missing packages with their install command or the reason there is none (FR19), and a missing StyleX compiler (FR20); the receipt's notes is empty when the project lacks nothing. One exception keeps build's response additive (FR22): on build's start and alternatives, notes is present only when it holds a line. Text shows each template's readiness beside it, as FR12 and spec:AST-017/FR13 require.
  • FR22 — Readiness reports and never fails. Readiness MUST NOT change either command's exit status: with packages or a compiler missing, astryx template writes its file and astryx build returns its recommendation, each with the exit status it has without them. JSON changes MUST stay additive under spec:AST-017: every existing field keeps its name and type, and new data arrives as new fields. FR14–FR21 decide the values that notes, missingPackages, and installCommand carry (which packages, which ranges, and whether there is a command), as ranking decides values under FR11; spec:AST-017 classifies a change in those values.
  • FR23 — Docs and themes point to search. A build kit has no doc or theme group. With --type doc or --type theme, build MUST return what it returns without the note: the empty kit for a query, the playbook without one, with the same stdout, JSON response and exit status. In text mode, with or without a query, build MUST also print one stderr note naming astryx search <query> --type doc or --type theme; JSON mode prints no note.

Platform support

  • Supported floor: every shell and package manager the CLI already supports. Commands are printed in text with the command name spec:AST-081 FR5 picks, and without it in JSON, as the CLI does for every command it prints; the install command (FR17) is the package manager's own and reads the same in both. The common shells an install command runs in as printed (FR18) are sh-compatible shells such as bash and zsh, fish, PowerShell (Windows PowerShell 5.1 and PowerShell 7), and the Windows command prompt.
  • Unsupported behavior: none; build writes nothing, and readiness only reports (FR22), so there is nothing to degrade. An ambiguous package manager gets a note instead of a command (FR19).
  • Browser evidence: not applicable; the recommendation and the receipt are CLI output.

Current-state impact

This record changes these surfaces:

  • the build.kit response carries the start, with its command, basis, reason, and alternatives; every existing field keeps its shape and meaning;
  • build's text leads with the start and the alternatives, then the blocks and the components;
  • the build playbook, the generated agent docs, and the consumer guides that describe building a page start from a template;
  • the template.copy receipt reports scaffold readiness as FR14–FR20 state, and build's start and each alternative carry the same fields (FR21);
  • the canonical response types and the response docs for template.copy and build.kit describe notes, missingPackages, and installCommand as FR14–FR22 state.

architecture:cli-surface keeps the command envelope and its rules unchanged.

Verification

Contract Verification Representative states Mutation or failure expectation
FR1, FR2 Build kit tests a request that names a template; a loose request; a request no template fits A page build with no start, or a start that is not a page template
FR3 Build kit tests a part placed in a page; a part with no page; a change to an existing page; a whole page the kind call reads as a part A part with no page starting from a page template when the shell-start decision does not read it as a whole page, or a request with an edit phrase or a change to an existing page starting from a page template
FR4 Build kit tests search's direct match is not ready, named and not named by the request An unready template as the start or an alternative, a reason that hides one the request names, or one the request does not name anywhere in the response, or a start, direct match or shell lift that changes when a not-ready template leads search
FR5 Template integration tests an integration template that replaces a Core one; a block sharing a page template's id A start or alternative command that selects another template, or none
FR6, FR7 Build kit tests; the build.test.mjs host-locale check direct, closest, and fallback starts; the same requests under English, Czech, Hawaiian and Turkish host locales A start without a basis or reason, or without its alternatives; a start or alternatives that differ between host locales
FR8, FR12 Text field tests default and --verbose text for a build with every field populated A response field the text never shows, or text out of the required order
FR9 CLI text tests any page build Text without the keep-your-page line
FR10, FR11 Response type and build tests the canonical response type, the response docs, and existing fields on a page build A missing recommendation field, or an existing field whose shape changes
FR13 Playbook and agent docs tests the playbook steps and the generated agent docs block A surface that tells builders to compose a page from primitives before a template
FR14 Readiness fixture tests every import form, a type-only import, and a scoped subpath; an import inside a comment, a string, and a template literal; a Node built-in, a relative path, a URL, and a ~/ path alias An import inside a comment or a string that counts, a path alias that counts as a package, or a real import that does not
FR15 Readiness fixture tests a package declared only at the workspace root; one in each dependency field; a target in a nested package; a package.json above the workspace root; no package.json A declared package reported missing, or a package.json above the workspace root that counts
FR16 Readiness fixture tests a source that imports an Astryx package and a framework package the project does not declare An undeclared package left out of missingPackages because of its name
FR17 Readiness fixture tests a lockfile only at the workspace root; a packageManager field beside another lockfile; two lockfiles and a workspace file; no lockfile A command in a package manager the deciding directory does not name
FR18 Readiness fixture tests and shell quoting tests ranges with spaces, a caret, comparison operators, a wildcard, and a union; a protocol value; a template an integration ships that imports its own package; a command run outside the target's package A range the shipping package does not declare, an argument a common shell splits, expands, or redirects, or a package not added to the package.json nearest the target
FR19 Readiness fixture tests two lockfiles in one directory: with and without a packageManager field, with one file only one package manager reads, with two such files for different package managers, and with only a package.json workspaces field A command printed for an ambiguous package manager, or a note that names no lockfile
FR20 Readiness fixture tests a source that imports StyleX at run time and one that imports only its types, with and without a declared compiler A missing compiler with no note, a note beside a declared compiler or for a type-only import, or a compiler in the install command
FR21 Build kit and template copy tests the start and each alternative against the receipt for the same template and directory; default and --verbose text A recommended template without the fields, a value the receipt would not carry, an empty notes on a build entry, or a field the text never shows
FR22 CLI exit-code and response type tests a scaffold and a build with packages and a compiler missing A changed exit status, or an existing field whose name or type changes
FR23 CLI text and JSON tests --type doc and --type theme, with and without a query, in text and JSON mode; --type component A note on stdout, a second note, a note in JSON mode or for a kind the kit has, or stdout, JSON or exit status that differs from the same build without the note

Decision log

DEC-1 — Start from a template, always

Reference: spec:AST-048/DEC-1 Decider: josephfarina, 2026-09-28

Templates carry the spacing judgment and a kit of loose parts does not, so the recommendation is always a full page template, and blocks and components fill it.

Rejected: naming a template only on an exact match and a layout reference otherwise, which leaves most builders composing from primitives.

DEC-2 — A shell when nothing leads

Reference: spec:AST-048/DEC-2 Decider: josephfarina, 2026-09-28

When no template has the evidence to lead, the start is a neutral app shell, so even an unusual request starts from a frame the system decided.

Rejected: no start at all, which hands the builder primitives; and the best weak match, which lets one incidental word pick the page.

DEC-3 — The builder can overrule the pick

Reference: spec:AST-048/DEC-3 Decider: josephfarina, 2026-09-28

The builder judges meaning better than word matching does, so every start comes with the next best templates and their commands.

Rejected: a single pick with no alternatives.

DEC-4 — A part starts where it lives

Reference: spec:AST-048/DEC-4 Decider: josephfarina, 2026-10-01

A part is built inside a page. When the request gives that page, its template is where the part goes; when it gives none, the app shell is the frame, and the blocks and components carry the part. A change to an existing page is the same case: the page is the builder's own, so no template is its start.

Rejected: starting a part from whichever page template shares a word with it, which scaffolds an unrelated page for a single control; and giving a part no start, which breaks DEC-1.

DEC-5 — The response stays additive

Reference: spec:AST-048/DEC-5 Decider: josephfarina, 2026-09-29

Callers read build's JSON, so the recommendation arrives as new data beside the existing fields, and ranking changes move values rather than shapes. Text may change with the recommendation.

Rejected: replacing existing fields with the recommendation, which breaks JSON callers for a policy change they did not ask for.

DEC-6 — The source and the workspace say what is missing

Reference: spec:AST-048/DEC-6 Decider: josephfarina, 2026-10-09

The source a command writes is the only authority on what it imports, and the package.json files from the target directory up to the workspace root are the authority on what the project declares; a workspace keeps shared packages at its root, so they count for every package below it. What is missing is the difference, and no package is exempt by name, because an exemption hides a missing package exactly when the project lacks it. A source that uses StyleX also needs a compiler, which takes configuration as well as a package, so the compiler gets a note and stays out of the install command.

Rejected: a list of packages assumed installed, Astryx or framework packages among them, which hides what a fresh project lacks; and matching text that looks like an import, which counts imports inside comments and strings.

DEC-7 — One runnable command, or none

Reference: spec:AST-048/DEC-7 Decider: josephfarina, 2026-10-09

A builder or an agent copies the install command and runs it, so it is one command in the project's own package manager that reaches that package manager unchanged from every common shell and leaves nothing missing. Its versions are the ranges the package that ships the template declares, with that package itself at the version the template came from, and a peer range comes first because it states what that package supports beside the project's code. Installing with the wrong package manager writes a second lockfile and a second dependency tree, so when the project's package manager is ambiguous the receipt names what to install and why there is no command, and the builder picks the tool.

Rejected: falling back to npm when lockfiles disagree, which deepens the conflict the receipt reports.

Reference: spec:AST-048/DEC-8 Decider: josephfarina, 2026-10-09

The builder chooses among the start and its alternatives (DEC-3), and what a template needs is part of that choice, so each one carries the receipt's fields with the values its scaffold would report.

Rejected: readiness on the start only, which hides what an alternative needs until it is scaffolded.

DEC-9 — Readiness reports and never fails

Reference: spec:AST-048/DEC-9 Decider: josephfarina, 2026-10-09

A missing package is the next step after a scaffold, not a failure of it, so neither command's exit status depends on readiness, and callers keep reading the existing fields as they are (DEC-5).

Rejected: failing the scaffold when a package is missing, which blocks a builder who installs afterwards.

DEC-10 — A whole page reads past the part call

Reference: spec:AST-048/DEC-10 Decider: josephfarina, 2026-11-13

Build's kind call reads some whole-page requests as parts, which leaves them on the empty app shell. When the start would be the app shell and search matched no ready template directly, a fixed decision over build's own ranking scores and a fixed word table reads the whole request; when its whole-page probability is at least 0.30, the start is the best-ranked page template. This is not DEC-2's best weak match: one shared word never decides it, and it never applies to a direct match or to a request with an edit phrase, so DEC-4 still holds for changes to an existing page.

Rejected: lifting only requests the kind call reads as pages, which keeps whole pages the kind call misreads on the empty shell.

DEC-11 — The page pick reads past weak ranker evidence

Reference: spec:AST-048/DEC-11 Decider: josephfarina, 2026-11-14

When build's fixed word tables read a request as a whole page, its page-pick model chooses among the ready page templates even when the page ranker's own evidence is too weak for the ranker to lead alone. The pick model reads the whole request, so its choice rests on many words rather than one shared word, and across representative requests its starts on weak ranker evidence help the builder more often than the empty app shell does. DEC-2 still holds when no part of build's ranking leads: the start is the app shell. Requests build reads as parts or as changes to an existing page keep their placement rules (DEC-4); the edit-phrase check belongs to DEC-10's shell lift, not to the page pick.

Rejected: sending every start the ranker cannot lead alone to the app shell, which leaves more whole pages on the empty shell than it keeps parts off a page template.

DEC-13 — A family base hosts a part only as the place it goes

Reference: spec:AST-048/DEC-13 Decider: josephfarina, 2026-11-16

A part starts from a family's base template only when the ranker leads with that base and the request names the family as where the part goes. A family word that heads the request and also ends a component's name names the piece itself: "a sortable table" asks for a table, not for a part of the table page. Both facts come from the catalog: the families from the page templates, and the piece words from the components' names. So a new family or a new component follows the rule with no list to update.

Rejected: hosting on any base whose family word appears anywhere in the request, which starts every request that mentions a table from the table page once a table base is ready; and a list of family words that never host, which needs an update for each new family.

Open questions

  • OQ1 — How recommendation quality is measured. Whether changes to what build recommends must report their effect on a checked-in set of representative requests with accepted templates, separately for requests that describe a whole page and requests that describe a part of one. (human-design)

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx