An open source design system that's fully customizable and agent ready
TypeScript
spec(cli-surface): INV30, how a host's package set serves the CLI (#7412)
Joeyd21609796b07
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.mdindex 0150cc3e23..7c5035628d 100644--- a/docs/architecture/cli-surface.md+++ b/docs/architecture/cli-surface.md@@ -23,6 +23,8 @@ verified_by:clients/cli/commands/init.behavior.test.mjs,api/init/remove/remove.test.mjs,foundation/integrations/autolink.test.mjs,+ foundation/runtime/package-set.test.mjs,+ foundation/runtime/hosted-runtime.test.mjs,foundation/integrations/manifest-writer.test.mjs,foundation/integrations/contribution-inventory.test.mjs,foundation/discovery/theme-discovery.test.mjs,@@ -93,6 +95,19 @@ loaded independently. A manifest load failure withdraws that package. An errorin one contribution kind does not hide other valid kinds, and invalid templateor component files do not hide valid siblings.+A programmatic host (`spec:AST-081` FR1) can serve the CLI from package sets it+keeps elsewhere: package roots whose `node_modules` each hold a CLI, the Core+equal to it, and the integrations the host installs with them. The host entry,+`@astryxdesign/cli/host`, activates the root that serves a run in-process,+through the package-private implementation in `foundation/runtime`. The working+folder stays the caller's: the project, its config, local themes, and the+package being authored resolve as they do without a host, and no write lands in+a package root. Core lookups, and integration lookups outside a project, consult+the active root only after the project's own resolution misses. With no active+set, every lookup behaves exactly as it does without the seam (INV30). Which+release answers a hosted run, the host entry's inputs, and the lines a hosted+run prints are `spec:AST-081`'s.+AST-017 DEC-4 owns stable response-entry fields and requires their complete type,test, applicable text, and consumer-documentation projections. A `template.list`entry can carry optional `replaces`, naming the Core id that a winning@@ -319,10 +334,12 @@ and remains available through explicit Core package selection.autolinking it can only add.** A dependency the project DECLARES inpackage.json, and that ships a root `astryx.integration.*` manifest, isloaded; `node_modules` is never walked, so nothing the project did not declare- can contribute. Only the dependency KEY is read, never its value, so an npm- alias or a non-semver protocol resolves like any other. A config entry keeps- precedence over the same package autolinked, and a dependency whose manifest- fails to load is dropped rather than raised as the consuming project's issue.+ can contribute. Enumeration reads only the dependency KEY, never its value, so+ an npm alias or a non-semver protocol resolves like any other. A config entry+ keeps precedence over the same package autolinked, and a dependency whose+ manifest fails to load is dropped rather than raised as the consuming+ project's issue. Outside a project, a hosted run also loads each integration+ its host approves, by name, from the package root that serves it (INV30).Integrations installed for the computer (`spec:AST-081` FR12) contributeonly outside a project, from the packages installed beside the global copy.Inside a project they contribute nothing: `discover` and `doctor` load the@@ -473,6 +490,52 @@ and remains available through explicit Core package selection.`--showcase`, and a template's source) keeps stdout to the source alone, soit pipes byte for byte, and names the package on stderr.+- **INV30 — A host's package set fills only what the project leaves open, from+ one root.** A package set is a package root whose `node_modules` holds a CLI,+ the Core equal to it, and the integrations installed with them. A programmatic+ host passes its package sets, in its order of preference, through the host+ entry (`spec:AST-081` FR1); which release answers a hosted run, and every line+ a hosted run prints, are `spec:AST-081` FR2, FR3, FR5, and FR9's. Only the+ host entry activates a package set: no CLI flag, environment variable, config+ key, or command does, and no `foundation/runtime` module is exported.+ - A project's installed packages always resolve from the project. Inside a+ project, a root fills only the `@astryxdesign/*` packages the project leaves+ uninstalled whose copy in the root ships no integration manifest, so it+ contributes no integration (`spec:AST-081` FR12). A run resolves from at+ most one root, so a CLI never pairs with a Core or an integration from+ another set. A run handed to the project's own CLI (`spec:AST-081` FR9) uses+ no root.+ - Whenever the copy that started the run answers, outside a project, in a+ project that installs no CLI of its own, as the release `spec:AST-081` FR2+ names, or as FR2's fallback, the root that holds that copy serves the run.+ - When `spec:AST-081` FR2 has a hosted run in a project answered by a named+ release other than the copy that started the run, the matched release or the+ release of a project CLI the host declined, a root qualifies only when its+ CLI is that release and it holds, for every package the project declares+ that a root may fill, the version the project would install: the valid+ lockfile version, else a published version that satisfies the declared+ range. A declared value that is not a version range, such as a path or a+ protocol, matches only through its lockfile version, and an unrequested+ prerelease does not satisfy a range. The first root in the host's order that+ qualifies serves.+ - A hosted run installs nothing: a release `spec:AST-081` FR2 names comes only+ from the copy that started the run, when it is that release, or from a root+ that qualifies; when neither does, that release cannot be obtained and FR2's+ fallback applies.+ - Outside a project, each integration the host approves resolves by name from+ the root that serves the run, in addition to what `spec:AST-081` FR12 finds+ there, and loads with FR12's validation, peer-range check, and provider+ identity rules. An approved name that root does not hold is left out.+ - Enumeration through a root reads only the packages INV14 or `spec:AST-081`+ FR12 name, and a root's own config is never read.+ - Every run a package set serves records, for each package it resolves, its+ name, version, and whether it comes from the project or the package set, and+ the host entry returns that record with the run's result (`spec:AST-081`+ FR1); results still name each artifact's package (INV28).+ - Project health APIs (`doctor` and its integration checks) judge only the+ project's own install: a package set never satisfies or fails a project+ check, and `spec:AST-081` FR12 decides what they list as available.+Some modules predate INV20–INV23 and do not meet them yet; `spec:AST-042` liststhe known gaps.@@ -503,6 +566,9 @@ updated in the same pull request when it moves an invariant:- adding `--strict`, or any other way to fail on warnings, to a command(INV32);- changing local, configured, or autolinked integration precedence;+- changing how a host's package set is matched to a project, which+ integrations it contributes, what a run it serves records, or which lookups+ consult it (INV30);- changing an integration item descriptor, the theme directory boundary, or the consumer copy contract;- changing which files hold the agent-docs block, how init finds the projectroot, where it refuses to write agent docs, or where it removes them (INV31);@@ -530,6 +596,12 @@ non-interactive guarantee.`toErrorEnvelope`, `humanLog`, `humanWarn`, the JSON-mode flag.- `foundation/response/error-codes.mjs` — the frozen, append-only code set.- `foundation/config` — the `Project` discovery seam and integration precedence.+- `host/index.mjs` and `host/index.d.ts` — the supported programmatic host+ entry, `@astryxdesign/cli/host` (`spec:AST-081` FR1).+- `foundation/runtime` — the package-private package-set implementation: the+ active set and the lookups that consult it (`package-root.mjs`), matching a+ project to a root, the approved integrations, and provenance+ (`package-set.mjs`), and lockfile pins (`locked-versions.mjs`).- `foundation/integrations/manifest-writer.mjs` — safe manifest-root patching,verification, and rollback.- `foundation/integrations/contribution-inventory.mjs` — the shared local and@@ -710,6 +782,7 @@ the destination.| INV25 | `foundation/discovery/cli-self-docs.test.mjs`, `api/doctor/doctor.test.mjs` | A CLI doc with no namespace, a namespace no topic reads, or no section in its topic passes doctor. || INV28 | `test/inv28-package-provenance.test.mjs`, `clients/cli/commands/text-json-parity.test.mjs`, `cli-api-types-verify` | A result about one artifact has no envelope `package`, a listed artifact has no `package`, or text omits the package the envelope names. || INV29 | `api/doctor/doctor.test.mjs` (configured-integrations: not installed, no manifest, manifest throws; self-named authored package, direct and through a symlinked `node_modules` or `cwd`; provider-conflict set-aside; an astryx.config that imports but cannot load the project → failed `config` check) | A configured integration that cannot load leaves `doctor` at exit 0, or an installed-but-unnamed one fails it |+| INV30 | `foundation/runtime/package-set.test.mjs`, `foundation/runtime/hosted-runtime.test.mjs` | A run resolves from two roots; a root contributes an integration inside a project, including an `@astryxdesign/*` package that ships an integration manifest; a run the starting copy answers resolves from a root other than the one that holds it, or is announced as a fallback when that copy is the release `spec:AST-081` FR2 names; a run another named release answers resolves from a root whose CLI is not that release, from one that lacks a version the project would install, or from a later root when an earlier one qualifies; a hosted run installs a release, or a named-release run with no qualifying root does not fall back as FR2 says; a lookup consults a root before the project's own install, or with no set active; an approved integration resolves from another root or skips its validation; a root's config is read; a run writes into a package root or outside the places `spec:AST-081` FR7 names; the host entry's result lacks a resolved package or its source; or a project check judges the package set. || INV31 | `foundation/agent-docs/agent-docs.test.mjs`, `foundation/agent-docs/agent-docs.path-safety.test.mjs`, `clients/cli/commands/init.behavior.test.mjs`, `api/init/remove/remove.test.mjs`, `clients/cli/commands/doctor.test.mjs` | A layout test finds the block missing from a file INV31 names or present in a file it excludes, a managed import of a block-less `AGENTS.md` passes doctor, agent docs land in the home folder or in a settings folder outside a project, or `--remove-agents` leaves a block at the project root or in the working folder. || INV32 | `test/cli-strict-guard.test.mjs` lists every command offering `--strict` and every command whose exit depends on warnings; `api/integration/check/check.test.mjs` compares a strict run with the default run | A second command offers `--strict`, a command exits 1 on a warning alone without `--strict`, or a strict run reports a finding the default run does not or outside the command's issue format. || INV33 | `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/type-text.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-prop-docs.test.mjs` | A removed or renamed prop or a changed union passes unreported, a missing compiler reads as a pass, or a table that leaves out `ref`, `key`, `xstyle`, `className`, `style`, `data-testid`, or an `@internal` prop draws a warning. |diff --git a/docs/specs/AST-081-global-mode/spec.md b/docs/specs/AST-081-global-mode/spec.mdindex cc512ee1a2..92da6ab6c7 100644--- a/docs/specs/AST-081-global-mode/spec.md+++ b/docs/specs/AST-081-global-mode/spec.md@@ -159,7 +159,10 @@ works on is `spec:AST-040` FR9's.- When the project's own CLI is installed but cannot start, the matchedrelease answers: the copy that started the run when it is that release,otherwise the release in the per-user cache, installed there through the- package manager the first time a project needs it. The package manager is+ package manager the first time a project needs it; a hosted run takes it+ only from a package set that qualifies under `architecture:cli-surface`+ INV30 and installs nothing, so with no such set the release cannot be+ obtained. The package manager isstarted without a shell, and a declared Core range is read only when it is aplain version range, so nothing a project declares reaches a shell. While arelease installs, or while the run waits for another run installing it, a