Skip to content

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.md
index 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 error
in one contribution kind does not hide other valid kinds, and invalid template
or 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 in
package.json, and that ships a root `astryx.integration.*` manifest, is
loaded; `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) contribute
only 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, so
it 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` lists
the 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 project
root, 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.md
index 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 matched
release 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 is
started without a shell, and a declared Core range is read only when it is a
plain version range, so nothing a project declares reaches a shell. While a
release installs, or while the run waits for another run installing it, a