An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-040): upgrade works on its project from any folder, and reports a CLI older than Core (#7543)
Joey5a96bf95bb0c
diff --git a/docs/specs/AST-040-consumer-file-modification/spec.md b/docs/specs/AST-040-consumer-file-modification/spec.mdindex 31979304f3..5c6077fbae 100644--- a/docs/specs/AST-040-consumer-file-modification/spec.md+++ b/docs/specs/AST-040-consumer-file-modification/spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: josephfarina-approved_at: 2026-09-23+approved_at: 2026-10-20phase: acceptedowners: [josephfarina]affects_architecture: [architecture:cli-surface]@@ -29,7 +29,10 @@ and that anything Astryx could not change is reported instead of hidden.This record owns what an operation may modify in an existing consumer file, whatcounts as evidence, and how skipped or blocked changes are reported. It appliesto every operation that modifies or replaces an existing file in a consumer-project, including core, integration, and configuration codemods.+project, including core, integration, and configuration codemods. For+`astryx upgrade`, it also owns which project the operation works on, which+installed Core it migrates to, how its result names files, and how it reports a+CLI too old to finish the migration.## Non-goals@@ -42,6 +45,8 @@ project, including core, integration, and configuration codemods.this record owns how a consumer-file transform edits safely.- Choosing a command for inspecting effective settings; `spec:AST-017` FR20requires one.+- Where other commands look for the project, including where `init` writes+ agent docs. FR9–FR13 govern `astryx upgrade` only.- Equivalent internal implementations remain valid when they satisfy this contract.## Requirements@@ -112,12 +117,67 @@ project, including core, integration, and configuration codemods.and configuration codemods, and any other operation that modifies existingconsumer files, MUST apply FR1–FR7 identically. A new modification path cannotopt out, consistent with `spec:AST-017` FR16.+- **FR9 — An upgrade works on its project.** `astryx upgrade` MUST operate on+ the project of the folder it runs in: the nearest folder at or above that+ folder whose `package.json` declares an Astryx package, or that its workspace+ lists as a member when the workspace root's `package.json` declares one. A+ `package.json` declares an Astryx package when any of its dependency fields,+ peer dependencies included, names an `@astryxdesign/*` package or a legacy+ `@xds/*` one. A folder's workspace root is the one `spec:AST-048` FR15 finds+ from it, and the workspace lists the folder when a pattern in the root+ `package.json` `workspaces` field or in `pnpm-workspace.yaml` `packages`+ matches the folder and no exclusion pattern removes it. A folder that installs+ Core but qualifies neither way is not a project: an upgrade run there works on+ the project above it, if any. The search MUST NOT continue past a folder that+ holds version-control metadata, and MUST end at the home folder without+ counting it as a project or as a workspace root. The project root is the+ operation root (FR2): the upgrade reads the project's configuration, agent+ docs, and protection sources (FR3, FR4) there. When no folder qualifies, the+ folder the command runs in is the operation root.+- **FR10 — A named source folder is read where the command runs.** By default,+ an upgrade MUST scan the `src` folder of the operation root. A source folder+ the caller names MUST be resolved from the folder the command runs in, and+ MUST be inside the operation root; one outside it fails with+ `ERR_PATH_TRAVERSAL` before any write.+- **FR11 — A workspace member migrates to the Core its workspace installs.**+ The version an upgrade migrates to MUST be that of the Core+ (`@astryxdesign/core`, or the legacy `@xds/core`) the project installs: in the+ `node_modules` of the project root; for a member its workspace lists, in the+ nearest `node_modules` from the project root up to the workspace root; and for+ a project installed without `node_modules`, the copy its package manager+ resolves for it. A Core above a project that no workspace lists MUST NOT+ count. When no folder qualifies under FR9, the target is the Core in the+ `node_modules` of the folder the command runs in. With no installed Core, the+ upgrade fails with `ERR_VERSION_DETECT` before any write.+- **FR12 — The result names files from where the command runs.** The+ machine-readable result of an upgrade MUST name its modified, protected, and+ declined files (FR7), the files its errors name, its agent-doc files, and the+ files of its copied-composition summary by paths relative to the folder the+ command runs in, so each resolves from there. When the command runs at the+ operation root, the copied-composition summary instead names its files+ relative to the source folder the upgrade scanned. When the operation root is+ another folder, the human-readable output MUST name it.+- **FR13 — A CLI older than the installed Core reports an incomplete upgrade.**+ When the installed `@astryxdesign/core` is newer than both the running CLI and+ the version the upgrade starts from, the upgrade MUST run the codemods the+ running CLI has for the range, and its human-readable output MUST report the+ upgrade as incomplete and MUST NOT say the code is up to date. The+ machine-readable result MUST carry the optional `cliBehindCore` field, present+ only in this case, with the running CLI's version and one command that+ finishes the upgrade with the CLI release matching the installed Core. That+ command MUST work from any folder it is run in, upgrading the same project; it+ MUST repeat the run's options, MUST name the source folder the run scanned,+ and MUST quote each argument for the shell it targets. The human-readable+ output MUST print the command on a line of its own, and MUST name that shell+ unless it is a POSIX shell. This case does not change the exit status, or what+ `complete` and `errorCode` report under FR6.### Platform support- Supported feature/engine floor: every supported CLI runtime on Linux, macOS,- and Windows; Git, Sapling, and Mercurial checkouts; and directories with no- version control.+ and Windows; Git, Sapling, and Mercurial checkouts; directories with no+ version control; and the workspaces and install layouts of npm, pnpm, Yarn+ (Plug'n'Play included), and Bun.- Unsupported behavior: a version-control declaration that exists only inrepository metadata outside the working tree is not read; the project addsprotection under FR4 when a reproduced case needs it.@@ -140,13 +200,18 @@ and needs no Changeset.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |-| FR1 | Transform fixtures | named, aliased, default, namespace, re-exported, type-only in a type position and a value position, shadowed, wrong-package, unrelated literal | A same-named local or unrelated literal changes, or a proven usage is not edited |-| FR2–FR4 | Protection fixtures in each checkout kind | nested attributes, unset or false attribute, negated ignore, marker after code, partial marker, ignored path, symlink, config and integration additions, attempted removal, bad source | A protected file changes, a result differs by version control, or a bad source allows writes |-| FR5–FR6 | Upgrade runs with a generated file and a regeneration hook | hook succeeds, hook fails, dry run, second run | Protected bytes change, exit is zero with a blocked change, or a second run edits twice |-| FR7 | Result snapshots in JSON and text | modified, blocked, declined | A blocked or declined candidate is missing from either output |-| FR8 | Inventory of every operation that modifies existing files | core, integration, config codemods, new path | A path bypasses FR1–FR7 |+| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Transform fixtures | named, aliased, default, namespace, re-exported, type-only in a type position and a value position, shadowed, wrong-package, unrelated literal | A same-named local or unrelated literal changes, or a proven usage is not edited |+| FR2–FR4 | Protection fixtures in each checkout kind | nested attributes, unset or false attribute, negated ignore, marker after code, partial marker, ignored path, symlink, config and integration additions, attempted removal, bad source | A protected file changes, a result differs by version control, or a bad source allows writes |+| FR5–FR6 | Upgrade runs with a generated file and a regeneration hook | hook succeeds, hook fails, dry run, second run | Protected bytes change, exit is zero with a blocked change, or a second run edits twice |+| FR7 | Result snapshots in JSON and text | modified, blocked, declined | A blocked or declined candidate is missing from either output |+| FR8 | Inventory of every operation that modifies existing files | core, integration, config codemods, new path | A path bypasses FR1–FR7 |+| FR9 | Upgrade runs from folders inside and around projects | a subfolder; a listed and an unlisted workspace member; a folder whose `package.json` declares no Astryx package; a folder with no `package.json` inside a home folder that installs Astryx; a nested checkout; no qualifying folder | The upgrade operates on another project, the home folder, or a folder past version-control metadata |+| FR10 | Upgrade runs with a named source folder | the default from a subfolder; one folder named from a subfolder in each spelling; a folder outside the operation root | A named folder read from another folder than the one the command runs in, or a folder outside the operation root that is scanned |+| FR11 | Upgrade target detection | a member whose workspace forces Core, or that declares another range or only a peer range; an unlisted project below an installed Core; a Core in a parent folder; an install without `node_modules`; no qualifying folder | A member that misses the Core its workspace installs, or a Core above an unlisted project that counts |+| FR12 | Result snapshots from a subfolder and from the root | modified, protected, declined, error, agent-doc, and copied-composition paths | A path that does not resolve from the folder the command runs in, or a root run whose copied-composition paths change |+| FR13 | Upgrade runs with a CLI older than the installed Core | no codemods left; part of the range covered; each option; the printed command run inside the project, above it, and in an unrelated folder; a folder name with shell metacharacters in each targeted shell | An up-to-date or complete report, a dropped option, a command that misses the project elsewhere, or an unnamed non-POSIX shell |## Decision log