An open source design system that's fully customizable and agent ready
TypeScript
[Spec] AST-048: scaffold readiness for template and build (#7266)
Joeyaa286c86d209
diff --git a/docs/specs/AST-048-build-recommendation/spec.md b/docs/specs/AST-048-build-recommendation/spec.mdindex d2492bddab..e021164449 100644--- a/docs/specs/AST-048-build-recommendation/spec.md+++ b/docs/specs/AST-048-build-recommendation/spec.md@@ -1,13 +1,13 @@---schema_version: 4-template_version: 1+template_version: 2kind: system-specid: spec:AST-048authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: josephfarina-approved_at: 2026-10-01+approved_at: 2026-10-09phase: acceptedowners: [josephfarina]affects_architecture: [architecture:cli-surface]@@ -18,6 +18,8 @@ affects_consumer_docs: [cli]# Build recommendation system spec+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->+## IntentA builder, a person or a coding agent, describes the UI they want in words and@@ -28,20 +30,33 @@ a template: it names one page template to scaffold, the command that scaffoldsexactly that template, the next best templates, and the blocks and componentsthat fill it.-This record owns what build recommends and how the recommendation reads, in-text and JSON. `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.+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 theranking algorithm are implementation; this record states what therecommendation must be and how a reader can act on it.-- Which templates exist, or how they look.-- Writing files. Build recommends; `astryx template` scaffolds.-- New commands, options, or flags. Build's options and exit codes are not- changed by this record.+- 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 thiscontract.@@ -101,47 +116,146 @@ and template owners own what each template is.MUST describe the same workflow: scaffold the named template, fill it withblocks, and compose only what is left. No surface tells builders to composea 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.+- **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.### Platform support- Supported floor: every shell and package manager the CLI already supports.Commands are printed with the project's run prefix in text and without it in- JSON, as the CLI does for every command it prints.-- Unsupported behavior: none; build writes nothing, so there is nothing to- degrade.-- Browser evidence: not applicable; the recommendation is CLI output.+ 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-Before this record, build named a template to scaffold only when one matched a-request almost by name. A looser match got a layout skeleton to use as a-reference, and a request with no page match was told to frame with an app-shell component and compose from primitives.--When this ships:+This record changes these surfaces:-- the `build.kit` response gains the start, with its command, basis, reason,+- 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 andthe components;- the build playbook, the generated agent docs, and the consumer guides that- describe building a page start from a template.+ 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 part with no page starting from a page template, or a change to an existing page starting from that page's template |-| FR4 | Build kit tests | search's direct match is not ready | An unready template as the start or an alternative, or a reason that hides it |-| 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 | direct, closest, and fallback starts | A start without a basis or reason, or without its alternatives |-| 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 |+| 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 part with no page starting from a page template, or a change to an existing page starting from that page's template |+| FR4 | Build kit tests | search's direct match is not ready | An unready template as the start or an alternative, or a reason that hides it |+| 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 | direct, closest, and fallback starts | A start without a basis or reason, or without its alternatives |+| 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, and a URL | An import inside a comment or a string that counts, 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 |## Decision log@@ -204,6 +318,67 @@ may change with the recommendation.Rejected: replacing existing fields with the recommendation, which breaks JSONcallers 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.++### DEC-8 — Every recommended template says what it needs++**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.+## Open questions- **OQ1 — How recommendation quality is measured.** Whether changes to what