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.mdnew file mode 100644index 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).++@josephfarinadiff --git a/packages/cli/README.md b/packages/cli/README.mdindex 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`.+## ConfigurationThe CLI reads an optional `astryx.config.{ts,mjs,js}` from your project rootdiff --git a/packages/cli/api/doctor/doctor.type.mjs b/packages/cli/api/doctor/doctor.type.mjsindex 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} datadiff --git a/packages/cli/authoring/integration/integration.doc.mjs b/packages/cli/authoring/integration/integration.doc.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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'),