Skip to content

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

TypeScript

docs(cli): align Doctor docs and help (#6197)

Joeya599070618d4
diff --git a/.changeset/doctor-help-audit.md b/.changeset/doctor-help-audit.md
new file mode 100644
index 0000000000..60a711af27
--- /dev/null
+++ b/.changeset/doctor-help-audit.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] Align Doctor help and README examples with the shipped command tree and output format (#6197).
+
+@josephfarina
diff --git a/packages/cli/README.md b/packages/cli/README.md
index ac51c5537b..2b48e07062 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -65,7 +65,7 @@ Options:
| `component` | List components or print component docs |
| `discover` | Discover external packages and components |
| `docs` | Print reference docs |
-| `doctor` | Diagnose your XDS setup and report problems with fixes |
+| `doctor` | Diagnose Astryx projects and integration packages |
| `hook` | List hooks or print hook docs |
| `init` | Initialize the design system in your project |
| `layout` | Generate XDS layouts from compressed expressions (XLE/XLO) |
@@ -444,51 +444,43 @@ Every response has a `type` discriminant. The full set is below (generated from
## Doctor
-`astryx doctor` runs a series of health checks against your project and
-environment and reports `PASS` / `WARN` / `FAIL` for each, with an actionable
-fix for anything that isn't passing. It's read-only; it never installs or
-mutates anything, so it's safe to run anywhere, including CI.
+`astryx doctor` runs read-only health checks against your project and
+environment. Each record uses `[ok]`, `[warn]`, `[fail]`, or `[info]`, and
+includes an actionable `fix` when one is available. The exact checks and values
+depend on the project; the output shape is stable:
```
$ astryx doctor
-astryx doctor — diagnosing your setup
-
- ✓ Node.js version
- Node v22.13.0 meets the minimum (>=22.13.0).
- ✓ @astryxdesign/core installed
- @astryxdesign/core resolved (v0.0.14).
- ✓ @astryxdesign/core <-> @astryxdesign/cli alignment
- @astryxdesign/core v0.0.14 is in step with @astryxdesign/cli v0.0.14.
- ⚠ Theme packages
- No @astryxdesign/theme-* packages are installed.
- → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.
- ℹ astryx.config.mjs
- No astryx.config.mjs found — using defaults.
- ℹ AI agent docs
- No agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.
- → fix: Generate agent docs with `astryx init --features agents`.
- ✓ @astryxdesign/core peer dependencies
- All peer dependencies satisfied (react, react-dom).
- ℹ Package manager
- Detected package manager: yarn.
-
-Summary: 4 passed, 1 warning, 0 failures, 3 info
-
-No failures — but review the ⚠ warnings above when you can.
+astryx doctor - diagnosing your setup
+
+status: [ok]
+check: Node.js version
+message: Node v24.18.1 meets the minimum (>=22.13.0).
+
+status: [warn]
+check: Theme packages
+message: No @astryxdesign/theme-* packages are installed.
+fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.
+
+...
+
+Summary: 4 passed, 2 warnings, 0 failures, 2 info
+
+No failures - but review the [warn] warnings above when you can.
```
### Checks
-| Check | Status it can return | What it verifies |
-| ---------------------------- | -------------------- | -------------------------------------------------------------------- |
-| Node.js version | pass / fail | Running Node meets the CLI's minimum |
-| @astryxdesign/core installed | pass / fail | `@astryxdesign/core` is resolvable from the project |
-| Version alignment | pass / warn / info | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli` |
-| Theme packages | pass / warn | An `@astryxdesign/theme-*` package is installed and a theme is wired |
-| astryx.config.mjs | pass / fail / info | Config (if present) loads cleanly with a valid shape |
-| AI agent docs | pass / warn / info | Agent docs exist and contain the Astryx section markers |
-| Peer dependencies | pass / warn / info | `@astryxdesign/core`'s peer deps (react, …) are installed |
-| Package manager | info | Reports the detected package manager |
+| Check | Status it can return | What it verifies |
+| ---------------------------- | -------------------- | ---------------------------------------------------------------------------- |
+| Node.js version | pass / fail | Running Node meets the CLI's minimum |
+| @astryxdesign/core installed | pass / fail | `@astryxdesign/core` is resolvable from the project |
+| Version alignment | pass / warn / info | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli` |
+| Theme packages | pass / warn | An `@astryxdesign/theme-*` package is installed and a theme is wired |
+| astryx.config.mjs | pass / fail / info | Config (if present) loads cleanly with a valid shape |
+| AI agent docs | pass / warn / info | Agent docs exist and contain the Astryx section markers |
+| Peer dependencies | pass / warn / info | `@astryxdesign/core`'s peer deps (react, …) are installed |
+| Package manager | info / warn / fail | Reports the selected package manager and ambiguous or contradictory evidence |
### CI gate
@@ -503,6 +495,24 @@ usable directly as a CI step:
Use `--json` for a structured envelope (`{ apiVersion, type: "doctor",
data: { checks, summary } }`) that AI agents and scripts can parse.
+### Integration authoring
+
+`astryx doctor integration` checks one integration package without changing it.
+Omit `[package]` to inspect the package at the current directory, or pass an
+installed package name:
+
+| Command | What it checks | Exit `1` when |
+| ----------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
+| `doctor integration validate [package]` | Manifest shape and every declared contribution | A structural issue has error severity |
+| `doctor integration templates [package]` | Template IDs shared with Core | The integration is invalid; ID conflicts are warnings |
+| `doctor integration components [package]` | Component names shared with Core | The integration is invalid; name conflicts are warnings |
+| `doctor integration docs [package]` | Core topic replacements, extensions, and same-name conflicts | A Core overlap is accidental or the docs are invalid |
+
+Template and component conflicts include the exact `--package` command needed
+to select the integration contribution. Doc replacements and extensions are
+reported as intentional; a same-name topic without an explicit relationship is
+an error. Every leaf supports `--json`.
+
## Configuration
The CLI reads an optional `astryx.config.{ts,mjs,js}` from your project root
diff --git a/packages/cli/api/doctor/doctor.type.mjs b/packages/cli/api/doctor/doctor.type.mjs
index 42b895d756..cecdb22dbe 100644
--- a/packages/cli/api/doctor/doctor.type.mjs
+++ b/packages/cli/api/doctor/doctor.type.mjs
@@ -32,7 +32,7 @@
*/
/**
- * xds --json doctor
+ * `astryx --json doctor`
* @typedef {object} DoctorResponse
* @property {'doctor'} type
* @property {object} data
diff --git a/packages/cli/authoring/integration/integration.doc.mjs b/packages/cli/authoring/integration/integration.doc.mjs
index da40b7fd0d..a197675f03 100644
--- a/packages/cli/authoring/integration/integration.doc.mjs
+++ b/packages/cli/authoring/integration/integration.doc.mjs
@@ -95,12 +95,13 @@ export const doc = {
{
type: 'prose',
text:
- 'Validate a manifest with `astryx doctor integration validate`. It is checked ' +
- 'at the load boundary (parseIntegration): a known field of the wrong ' +
- 'type is an error, and issuesUrl must be a valid URL. A field this CLI ' +
- 'does not know is ignored with a warning rather than rejected, so a ' +
- 'manifest written against a newer CLI still contributes everything ' +
- 'this one understands.',
+ 'Validate the manifest with `astryx doctor integration validate`. At the ' +
+ 'load boundary, a known field of the wrong type is an error, issuesUrl ' +
+ 'must be a valid URL, and unknown fields become warnings so an older CLI ' +
+ 'can still load the fields it understands. Before publishing, also run ' +
+ '`templates`, `components`, and `docs` under the same `doctor integration` ' +
+ 'group. Those leaves compare authored identities with Core and explain ' +
+ 'whether an overlap is intentional or needs a rename.',
},
],
};
diff --git a/packages/cli/clients/cli/commands/doctor-integration-components.doc.mjs b/packages/cli/clients/cli/commands/doctor-integration-components.doc.mjs
index 1f63ff3fa8..b69977782e 100644
--- a/packages/cli/clients/cli/commands/doctor-integration-components.doc.mjs
+++ b/packages/cli/clients/cli/commands/doctor-integration-components.doc.mjs
@@ -14,7 +14,15 @@ export const doc = {
'conflict is allowed and exits successfully, but the report recommends ' +
'renaming and gives the exact --package command for an intentional overlap.',
fn: 'integrationComponentConflicts',
- args: [{name: 'package', param: 'pkg', required: false}],
+ args: [
+ {
+ name: 'package',
+ param: 'pkg',
+ required: false,
+ description:
+ 'Installed integration package name; omit to check the package in the current directory.',
+ },
+ ],
examples: [
{label: 'Check the local integration', cli: 'astryx doctor integration components'},
{
diff --git a/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjs b/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjs
index 08f791558c..95d98f9968 100644
--- a/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjs
+++ b/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjs
@@ -14,7 +14,15 @@ export const doc = {
'A same-name topic without `replaces` or `extends` is an accidental conflict ' +
'and fails until the author declares the relationship or renames it.',
fn: 'integrationDocConflicts',
- args: [{name: 'package', param: 'pkg', required: false}],
+ args: [
+ {
+ name: 'package',
+ param: 'pkg',
+ required: false,
+ description:
+ 'Installed integration package name; omit to check the package in the current directory.',
+ },
+ ],
examples: [
{label: 'Check the local integration', cli: 'astryx doctor integration docs'},
{
diff --git a/packages/cli/clients/cli/commands/doctor-integration-templates.doc.mjs b/packages/cli/clients/cli/commands/doctor-integration-templates.doc.mjs
index b74408a7a5..0425f9c957 100644
--- a/packages/cli/clients/cli/commands/doctor-integration-templates.doc.mjs
+++ b/packages/cli/clients/cli/commands/doctor-integration-templates.doc.mjs
@@ -17,7 +17,15 @@ export const doc = {
'report recommends renaming and gives the exact --package command required ' +
'to select the integration template when the overlap is intentional.',
fn: 'integrationTemplateConflicts',
- args: [{name: 'package', param: 'pkg', required: false}],
+ args: [
+ {
+ name: 'package',
+ param: 'pkg',
+ required: false,
+ description:
+ 'Installed integration package name; omit to check the package in the current directory.',
+ },
+ ],
examples: [
{
label: 'Check the local integration',
diff --git a/packages/cli/clients/cli/commands/doctor-integration-validate.doc.mjs b/packages/cli/clients/cli/commands/doctor-integration-validate.doc.mjs
index 1d048d758d..c1d79e19e0 100644
--- a/packages/cli/clients/cli/commands/doctor-integration-validate.doc.mjs
+++ b/packages/cli/clients/cli/commands/doctor-integration-validate.doc.mjs
@@ -16,7 +16,15 @@ export const doc = {
'installed package resolved by name. It schema-checks the manifest, verifies ' +
'every declared contribution root, and reports every finding. Safe as a CI gate.',
fn: 'validateIntegration',
- args: [{name: 'package', param: 'pkg', required: false}],
+ args: [
+ {
+ name: 'package',
+ param: 'pkg',
+ required: false,
+ description:
+ 'Installed integration package name; omit to validate the package in the current directory.',
+ },
+ ],
examples: [
{
label: 'Validate the local package',
diff --git a/packages/cli/clients/cli/commands/doctor-integration.doc.mjs b/packages/cli/clients/cli/commands/doctor-integration.doc.mjs
index e0090fe108..309b96a55c 100644
--- a/packages/cli/clients/cli/commands/doctor-integration.doc.mjs
+++ b/packages/cli/clients/cli/commands/doctor-integration.doc.mjs
@@ -25,10 +25,18 @@ export const doc = {
label: 'Check template ids against Core',
cli: 'astryx doctor integration templates',
},
+ {
+ label: 'Check component names against Core',
+ cli: 'astryx doctor integration components',
+ },
+ {
+ label: 'Classify doc overlaps with Core',
+ cli: 'astryx doctor integration docs',
+ },
],
exitCodes: [
{code: 0, when: 'help is shown or the selected check has no errors'},
{code: 1, when: 'the selected check reports an error'},
],
- related: ['doctor', 'template'],
+ related: ['doctor', 'component', 'template', 'docs'],
};
diff --git a/packages/cli/clients/cli/commands/doctor-integration.test.mjs b/packages/cli/clients/cli/commands/doctor-integration.test.mjs
index d1f1af075a..3e9fd64bb6 100644
--- a/packages/cli/clients/cli/commands/doctor-integration.test.mjs
+++ b/packages/cli/clients/cli/commands/doctor-integration.test.mjs
@@ -134,6 +134,23 @@ describe('doctor integration — command', () => {
expect(process.exitCode).toBeUndefined();
});
+ it('explains the optional package argument in every leaf help', () => {
+ const program = createProgram();
+ const doctor = program.commands.find(command => command.name() === 'doctor');
+ const integration = doctor?.commands.find(
+ command => command.name() === 'integration',
+ );
+
+ for (const leafName of ['validate', 'templates', 'components', 'docs']) {
+ const leaf = integration?.commands.find(
+ command => command.name() === leafName,
+ );
+ expect(leaf?.helpInformation(), leafName).toContain(
+ 'Installed integration package name; omit to',
+ );
+ }
+ });
+
it('templates explains how to check an installed package when no local manifest exists', async () => {
fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'plain'}));
process.chdir(tmpDir);
diff --git a/packages/cli/clients/cli/commands/doctor.doc.mjs b/packages/cli/clients/cli/commands/doctor.doc.mjs
index d717b33049..3c6953128b 100644
--- a/packages/cli/clients/cli/commands/doctor.doc.mjs
+++ b/packages/cli/clients/cli/commands/doctor.doc.mjs
@@ -13,9 +13,9 @@ export const doc = {
name: 'doctor',
displayName: 'astryx doctor',
namespace: 'cli',
- summary: 'Diagnose your XDS setup and report problems with fixes',
+ summary: 'Diagnose Astryx projects and integration packages',
description:
- 'Runs read-only project diagnostics by default: Node version, @astryxdesign/core ' +
+ 'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +
'install and version alignment, themes, config, agent docs, and package manager. ' +
'The `integration` subcommands provide authoring checks for one integration package.',
fn: 'doctor',
@@ -31,6 +31,14 @@ export const doc = {
label: 'Check template ids against Core',
cli: 'astryx doctor integration templates @acme/widgets',
},
+ {
+ label: 'Check component names against Core',
+ cli: 'astryx doctor integration components @acme/widgets',
+ },
+ {
+ label: 'Classify doc overlaps with Core',
+ cli: 'astryx doctor integration docs @acme/widgets',
+ },
],
exitCodes: [
{code: 0, when: 'no checks failed (warnings are allowed)'},
diff --git a/packages/cli/clients/cli/commands/doctor.mjs b/packages/cli/clients/cli/commands/doctor.mjs
index 34d24411a4..a8c4c5053a 100644
--- a/packages/cli/clients/cli/commands/doctor.mjs
+++ b/packages/cli/clients/cli/commands/doctor.mjs
@@ -61,7 +61,7 @@ function printHuman(report) {
? 'Some checks failed. Address the items marked [fail] above.'
: warn > 0
? 'No failures — but review the [warn] warnings above when you can.'
- : 'All checks passed. Your XDS setup looks healthy.';
+ : 'All checks passed. Your Astryx setup looks healthy.';
emit(
section('astryx doctor — diagnosing your setup'),