Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(cli-surface): doctor fails on a configured integration that cannot load; INV11 is about command runs (#7383)

Cindy Zhange48e2ef042c1
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.md
index 1388ab74a2..c12f662764 100644
--- a/docs/architecture/cli-surface.md
+++ b/docs/architecture/cli-surface.md
@@ -126,8 +126,22 @@ and remains available through explicit Core package selection.
- **INV10 — Every write is confined.** Output paths pass `assertWithin`, which
canonicalises symlinks and rejects a NUL byte; an escape is
`ERR_PATH_TRAVERSAL`. Bounded inputs are capped rather than trusted.
-- **INV11 — A broken integration degrades, it does not fail the run.** The
- `Project` seam loads each integration independently and records the failure.
+- **INV11 — A broken integration degrades a command run, it does not fail
+ it.** The `Project` seam loads each integration independently and records
+ the failure, and the command's own work proceeds without that integration's
+ contributions. The diagnostic command is the exception by purpose (INV29).
+- **INV29 — `astryx doctor` fails on a configured integration that cannot
+ load.** An integration named in `astryx.config` that is not installed, has
+ no manifest, or whose manifest throws or fails its schema is a failed
+ `configured-integrations` check, so `doctor` exits 1; an `astryx.config`
+ that imports but from which the CLI cannot load the project is a failed
+ `config` check with the same exit. What counts as configured is every name
+ `astryx.config` lists, including a package set aside for a provider-ID
+ conflict and the package being authored when its own config names it (its
+ load error is the outcome that counts). An installed integration the config
+ does not name stays informational. This invariant covers loading only; what
+ `doctor` reports about the contributions of an integration that loads is
+ owned by the checks that read them.
- **INV12 — Human chatter never touches stdout in JSON mode.** `humanLog` and
`humanWarn` are the only chatter primitives, and both are no-ops under
`--json`.
@@ -354,6 +368,22 @@ non-interactive guarantee.
- `spec:AST-042/DEC-2` — every command's text output uses one shared block
vocabulary.
+### DEC-1 — Doctor is the one command a broken configured integration fails
+
+**Decider:** `cixzhang`, `2026-10-12`
+
+A project owner who names an integration in `astryx.config` and then cannot
+load it — not installed, no manifest, a manifest that throws or fails its
+schema — gets a red `doctor` run that names the package and the reason,
+instead of a green one while every command silently runs without that
+integration's components, templates, and docs. Command runs keep degrading
+(INV11): a broken integration must never take a build or a read down with it,
+and `doctor` exists to say what is wrong. Rejected: `doctor` warns and exits 0
+(the owner's CI stays green over a misconfigured project); every command fails
+on a broken integration (a read or a build stops for a problem it can work
+around); counting only the integrations that happened to load (a package set
+aside or replaced by the package being authored would vanish from the count).
+
## Verification
| Invariant | Evidence | Failure signal |
@@ -377,6 +407,7 @@ non-interactive guarantee.
| INV24 | `api/integration/add-contribution.test.mjs`, `api/integration/add-theme.test.mjs`, `foundation/discovery/theme-discovery.test.mjs` | New authoring emits an untyped or non-`.doc.mjs` item, adding one item edits a shared file, or an item catalog becomes authoritative. |
| 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 |
## Open questions