@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/clients/cli/commands/docs.mjs

@@ -7,8 +7,7 @@
  * open one section by its key, and `--full` prints the whole topic. `--json`
  * keeps the docs() contract: a topic returns its whole doc, and `--index` its
  * sections.
- * Supports --detail (full|compact|brief) and --lang (en|zh|dense). A code
- * block's label prints above its fence, and table cells escape their pipes.
+ * Supports --detail (full|compact|brief) and --lang (en|zh|dense).
  *
  * Usage:
  *   astryx docs                          List available topics
@@ -43,35 +42,21 @@ import {doc as docsFn} from '../../../api/docs/docs.doc.mjs';
 
 // ─── Formatting ──────────────────────────────────────────────────────────────
 
-/**
- * A table cell with its pipes escaped. Columns are separated by ` | `, and a
- * union type such as `'light' | 'dark'` is spelled with the same character,
- * so an unescaped cell reads as extra columns. `astryx component` escapes its
- * prop tables the same way.
- * @param {string | undefined} cell
- * @returns {string}
- */
-function tableCell(cell) {
-  return (cell || '').replaceAll('|', '\\|');
-}
-
 /**
  * @param {string[]} headers
  * @param {string[][]} rows
  * @returns {string}
  */
 function formatTable(headers, rows) {
-  const head = headers.map(tableCell);
-  const cells = rows.map(r => r.map(tableCell));
-  const widths = head.map((h, i) =>
-    Math.max(h.length, ...cells.map(r => (r[i] || '').length)),
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map(r => (r[i] || '').length)),
   );
   const sep = widths.map(w => '-'.repeat(w)).join(' | ');
-  const top = head.map((h, i) => h.padEnd(widths[i])).join(' | ');
-  const body = cells
-    .map(r => r.map((c, i) => c.padEnd(widths[i])).join(' | '))
+  const head = headers.map((h, i) => h.padEnd(widths[i])).join(' | ');
+  const body = rows
+    .map(r => r.map((c, i) => (c || '').padEnd(widths[i])).join(' | '))
     .join('\n');
-  return `${top}\n${sep}\n${body}`;
+  return `${head}\n${sep}\n${body}`;
 }
 
 /**
@@ -80,19 +65,15 @@ function formatTable(headers, rows) {
  * @returns {string}
  */
 function formatTableCompact(headers, rows) {
-  // An empty cell, such as a Default with none, adds nothing to the line.
-  return rows
-    .map(r => r.filter(cell => String(cell ?? '').trim() !== '').join(' = '))
-    .join('\n');
+  return rows.map(r => r.join(' = ')).join('\n');
 }
 
 /**
- * One content block as text. Exported for its tests.
  * @param {import('@astryxdesign/cli/authoring').ReferenceContentBlock} block
  * @param {'full' | 'compact' | 'brief'} detail
  * @returns {string | null}
  */
-export function formatBlock(block, detail) {
+function formatBlock(block, detail) {
   switch (block.type) {
     case 'prose':
       return block.text;
@@ -103,20 +84,13 @@ export function formatBlock(block, detail) {
     case 'code':
       if (detail === 'compact' || detail === 'brief') return null;
       {
-        // The label names the block, so it prints above the fence, not
-        // inside it: `// label` is not a comment in bash, CSS, JSON, or
-        // HTML, and a reader who copies the block would copy it too.
-        const label = block.label
-          ? `${block.label.replace(/:\s*$/, '')}:\n`
-          : '';
-        return `${label}\`\`\`${block.lang}\n${block.code}\n\`\`\``;
+        const label = block.label ? `// ${block.label}\n` : '';
+        return `\`\`\`${block.lang}\n${label}${block.code}\n\`\`\``;
       }
 
     case 'table':
       if (detail === 'brief') {
-        return block.rows
-          .map(r => r.slice(0, 2).map(tableCell).join('='))
-          .join(' | ');
+        return block.rows.map(r => r.slice(0, 2).join('=')).join(' | ');
       }
       if (detail === 'compact') {
         return formatTableCompact(block.headers, block.rows);
@@ -228,23 +202,16 @@ function emitIndex(index, run) {
 }
 
 /**
- * One child row of a namespace. Namespace and guide route names are already
- * readable, so repeating their titles adds noise (`start-a-template  Start a
- * template`). Typed docs keep a distinct title when it carries the real symbol
- * name (`assert-response  assertResponse()`).
+ * One child row of a namespace: its route name, then the doc's own title when
+ * it is not the route name (`assertResponse()`, `search()`), then its summary.
  * @param {import('../../../api/docs/docs.type.mjs').DocsNodeChild} child
  * @returns {{name: string, summary: string}}
  */
 function childRow(child) {
-  const titleAddsIdentity =
-    child.kind !== 'namespace' &&
-    child.kind !== 'generic' &&
-    child.title !== child.name;
   return {
     name: child.name,
-    summary: titleAddsIdentity
-      ? `${child.title}: ${child.summary}`
-      : child.summary,
+    summary:
+      child.title === child.name ? child.summary : `${child.title}: ${child.summary}`,
   };
 }
 
@@ -260,17 +227,6 @@ function emitNode(node, detail, run) {
   if (node.kind === 'namespace') {
     emit(
       section(node.title, wrapText(node.summary)),
-      // A namespace may author intro `blocks`; they render above its children.
-      ...(node.content?.length
-        ? [
-            text(
-              node.content
-                .map(b => formatBlock(b, detail))
-                .filter(Boolean)
-                .join('\n\n'),
-            ),
-          ]
-        : []),
       ...node.slots.flatMap(slot => [
         // A namespace with one slot titled like itself needs no second heading.
         ...(node.slots.length === 1 && slot.title === node.title
@@ -279,6 +235,7 @@ function emitNode(node, detail, run) {
         records(slot.children.map(childRow), {
           fields: ['name', 'summary'],
           layout: 'inline',
+          overflow: 'truncate',
         }),
       ]),
       text(

package/clients/cli/commands/docs.test.mjs

@@ -0,0 +1,294 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {Command} from 'commander';
+import {registerDocs} from './docs.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {displayWidth} from '../formatters/index.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-docs-test-'));
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+  vi.restoreAllMocks();
+});
+
+function createProgram() {
+  const program = new Command();
+  program.exitOverride(); // Throw instead of calling process.exit
+  registerDocs(program);
+  return program;
+}
+
+describe('registerDocs', () => {
+  it('lists available topics when no topic given', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'docs']);
+
+    const output = console.log.mock.calls.map(c => c[0]).join('\n');
+    expect(output).toContain('principles');
+    expect(output).toContain('tokens');
+    expect(output).not.toContain('shadcn-compatibility');
+  });
+
+  it('errors for unknown topic', async () => {
+    const program = createProgram();
+    vi.spyOn(process, 'exit').mockImplementation(code => {
+      throw new Error(`exit ${code}`);
+    });
+
+    await expect(
+      program.parseAsync(['node', 'astryx', 'docs', 'nonexistent']),
+    ).rejects.toThrow('exit 1');
+
+    const errorOutput = console.error.mock.calls.map(c => c[0]).join('\n');
+    expect(errorOutput).toContain('Unknown topic');
+  });
+});
+
+describe('hyphenated doc filenames', () => {
+  it('lists hyphenated topics like getting-started', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'docs']);
+
+    const output = console.log.mock.calls.map(c => c[0]).join('\n');
+    expect(output).toContain('getting-started');
+  });
+
+  it('loads a hyphenated topic by name', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'docs', 'getting-started']);
+
+    const output = console.log.mock.calls.map(c => c[0]).join('\n');
+    expect(output.length).toBeGreaterThan(0);
+    expect(console.error).not.toHaveBeenCalled();
+  });
+
+  it('returns docs.detail via API for hyphenated topic', async () => {
+    const {docs: docsApi} = await import('../../../api/docs/docs.mjs');
+    const result = await docsApi('getting-started', undefined, {full: true});
+    expect(result.type).toBe('docs.detail');
+    expect(result.data).toBeDefined();
+    expect(result.data.description).toBeDefined();
+  });
+});
+
+describe('migration docs', () => {
+  it('lists the migration topic', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'docs']);
+
+    const output = console.log.mock.calls.map(c => c[0]).join('\n');
+    expect(output).toContain('migration');
+    expect(output).toContain('Tailwind');
+  });
+
+  it('loads migration docs by topic name', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'docs', 'migration']);
+
+    const output = console.log.mock.calls.map(c => c[0]).join('\n');
+    expect(output).toContain('Migration Guide');
+    expect(output).toContain('Recommended Order');
+    expect(output).toContain('Map shadcn and Radix Primitives');
+  });
+});
+
+describe('progressive reads', () => {
+  const SLOW = 60_000;
+  /** @param {string} out */
+  const widest = out => Math.max(...out.split('\n').map(line => line.length));
+
+  it('lists every topic on one line each', async () => {
+    const {status, stdout} = await runCli(['docs']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^principles +\S/m);
+    expect(widest(stdout)).toBeLessThanOrEqual(120);
+    expect(stdout).toContain('Usage: pnpm exec astryx docs <topic>');
+  }, SLOW);
+
+  it("prints a topic's section index with the keys to read by", async () => {
+    const {status, stdout} = await runCli(['docs', 'theme', '--index']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^quick-start +Quick Start/m);
+    expect(stdout).toContain('docs theme <section>');
+    expect(stdout).toMatch(/Read everything: +\S.* docs theme --full$/m);
+    expect(widest(stdout)).toBeLessThanOrEqual(120);
+  }, SLOW);
+
+  it('prints one section by its key', async () => {
+    const {status, stdout} = await runCli(['docs', 'theme', 'quick-start']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^## Quick Start/m);
+  }, SLOW);
+
+  it("lists a topic's sections by default; --full prints the whole topic", async () => {
+    const index = await runCli(['docs', 'theme', '--index']);
+    expect((await runCli(['docs', 'theme'])).stdout).toBe(index.stdout);
+    const full = await runCli(['docs', 'theme', '--full']);
+    expect(full.status).toBe(0);
+    expect(full.stdout).toMatch(/^## Quick Start/m);
+    expect(full.stdout.length).toBeGreaterThan(index.stdout.length * 3);
+    expect((await runCli(['--detail', 'full', 'docs', 'theme', '--full'])).stdout).toBe(
+      full.stdout,
+    );
+  }, SLOW);
+
+  it('returns the matching envelopes as JSON', async () => {
+    const envelope = async args => JSON.parse((await runCli([...args, '--json'])).stdout);
+    // JSON keeps docs(): a bare read is the whole topic.
+    expect((await envelope(['docs', 'theme'])).type).toBe('docs.detail');
+    expect((await envelope(['docs', 'theme', '--full'])).type).toBe('docs.detail');
+    expect((await envelope(['docs', 'theme', '--index'])).type).toBe(
+      'docs.index',
+    );
+    expect((await envelope(['docs', 'theme', 'quick-start'])).type).toBe(
+      'docs.detail.section',
+    );
+  }, SLOW);
+});
+
+describe('the docs tree, one level at a time', () => {
+  const SLOW = 60_000;
+  /** @param {string} out */
+  const widest = out => Math.max(...out.split('\n').map(line => line.length));
+
+  it('lists the docs tree first, under its own heading, then the topics', async () => {
+    const {status, stdout} = await runCli(['docs']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^Docs tree$/m);
+    expect(stdout).toMatch(/^Topics$/m);
+    expect(stdout).toMatch(/^cli +Commands, programmatic APIs/m);
+    expect(stdout.indexOf('\ncli ')).toBeLessThan(stdout.indexOf('\nprinciples '));
+    expect(stdout).not.toMatch(/^cli-integrations /m);
+  }, SLOW);
+
+  it("shows a child's own name when its route name does not spell it", async () => {
+    const {status, stdout} = await runCli(['docs', 'cli/api/functions']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^assert-response +assertResponse\(\): \S/m);
+    expect(stdout).toMatch(/^search +search\(\): Unified ranked search/m);
+  }, SLOW);
+
+  it('prints a namespace: each slot, its children, and how to go down and up', async () => {
+    const {status, stdout} = await runCli(['docs', 'cli/api']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^API$/m);
+    expect(stdout).toMatch(/^Reference$/m);
+    expect(stdout).toMatch(/^functions +Functions: Every function/m);
+    expect(stdout).toMatch(/^schemas +/m);
+    expect(stdout).toMatch(/^enums +/m);
+    // One level only: no function is listed on the api page.
+    expect(stdout).not.toMatch(/^search +/m);
+    expect(stdout).toMatch(/Open one: .*docs cli\/api\/<name>$/m);
+    expect(stdout).toMatch(/Up: .*docs cli$/m);
+    expect(widest(stdout)).toBeLessThanOrEqual(120);
+  }, SLOW);
+
+  it('prints a typed doc and the way back up', async () => {
+    const {status, stdout} = await runCli(['docs', 'cli/api/functions/search']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^## search\(\)/m);
+    expect(stdout).toContain('Read it with `astryx docs cli/commands/search`.');
+    expect(stdout).toMatch(/Up: .*docs cli\/api\/functions$/m);
+  }, SLOW);
+
+  it('reads the dense variant whole, asked with --dense or with --lang dense', async () => {
+    for (const args of [['--dense', 'docs', 'theme'], ['--lang', 'dense', 'docs', 'theme']]) {
+      const {status, stdout} = await runCli(args);
+      expect(status).toBe(0);
+      expect(stdout).not.toContain('Read one section:');
+    }
+  }, SLOW);
+
+  it('refuses --index with --full', async () => {
+    const both = await runCli(['docs', 'theme', '--index', '--full', '--json']);
+    expect(both.status).toBe(1);
+    expect(JSON.parse(both.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+  }, SLOW);
+
+  it('reads the integration guide by its route, and not by its old name', async () => {
+    const guide = await runCli(['docs', 'cli/integrations', '--index']);
+    expect(guide.status).toBe(0);
+    expect(guide.stdout).toMatch(/Read one section: .*docs cli\/integrations <section>/);
+    // A bare read is one level too: the sections, and how to read it all.
+    const bare = await runCli(['docs', 'cli/integrations']);
+    expect(bare.status).toBe(0);
+    expect(bare.stdout).toBe(guide.stdout);
+    expect(bare.stdout).toMatch(/Read everything: +.*docs cli\/integrations --full$/m);
+    const one = await runCli(['docs', 'cli/integrations', 'codemods']);
+    expect(one.status).toBe(0);
+    expect(one.stdout).toMatch(/^## Codemods$/m);
+    expect(one.stdout).toMatch(/^Up: .*docs cli\/integrations --index$/m);
+    expect(one.stdout).toMatch(/^Previous: .*docs cli\/integrations agent-docs$/m);
+    expect(one.stdout).toMatch(/^Next: .*docs cli\/integrations recording-runs$/m);
+    const full = await runCli(['docs', 'cli/integrations', '--full']);
+    expect(full.status).toBe(0);
+    expect(full.stdout).toMatch(/^## Overview$/m);
+    expect(full.stdout.length).toBeGreaterThan(bare.stdout.length * 4);
+    const old = await runCli(['docs', 'cli-integrations']);
+    expect(old.status).toBe(1);
+    expect(old.stderr).toContain('Unknown topic "cli-integrations"');
+  }, SLOW);
+
+  it('returns docs.node as JSON, and fails a section of a namespace', async () => {
+    const node = JSON.parse((await runCli(['docs', 'cli', '--json'])).stdout);
+    expect(node).toMatchObject({
+      type: 'docs.node',
+      data: {route: 'cli', kind: 'namespace', breadcrumb: []},
+    });
+    expect(node.data.slots.map(slot => slot.name)).toEqual(['guides', 'reference']);
+    const section = await runCli(['docs', 'cli', 'commands', '--json']);
+    expect(section.status).toBe(1);
+    const error = JSON.parse(section.stdout);
+    expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});
+    expect(error.suggestions.map(s => s.name)).toEqual([
+      'cli/integrations',
+      'cli/writing-docs',
+      'cli/commands',
+      'cli/api',
+    ]);
+  }, SLOW);
+});
+
+describe('text width in every language', () => {
+  const SLOW = 60_000;
+  /** Widest line outside code blocks, in terminal columns. */
+  const widest = out => {
+    let inCode = false;
+    let max = 0;
+    for (const line of out.split('\n')) {
+      if (/^\s*```/.test(line)) {
+        inCode = !inCode;
+        continue;
+      }
+      // A single unbreakable token (a long URL) cannot wrap without breaking it.
+      const oneToken = !/\s/.test(line.trim());
+      if (!inCode && !line.startsWith('#') && !oneToken) {
+        max = Math.max(max, displayWidth(line));
+      }
+    }
+    return max;
+  };
+
+  it('keeps the additive section index within 120 columns', async () => {
+    const {status, stdout} = await runCli([
+      'docs',
+      'theme',
+      '--index',
+      '--lang',
+      'zh',
+    ]);
+    expect(status).toBe(0);
+    expect(widest(stdout)).toBeLessThanOrEqual(120);
+  }, SLOW);
+});

package/clients/cli/commands/doctor-integration-docs.doc.mjs

@@ -10,10 +10,9 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Check an integration\'s docs: the docs tree they add, every link, and overlaps with Core topics',
   description:
-    'Checks the docs tree the package adds, every link in its docs, and overlaps with Core topics. ' +
-    'Intentional replacements and extensions are information. ' +
+    'Reports intentional Core topic replacements and extensions as information. ' +
     'A same-name topic without `replaces` or `extends` is an accidental conflict ' +
-    'and fails until the author declares the relationship or renames it. See {@link generic:check-your-docs}.',
+    'and fails until the author declares the relationship or renames it.',
   fn: 'integrationDocConflicts',
   args: [
     {

package/clients/cli/commands/doctor-integration.test.mjs

@@ -13,7 +13,6 @@ vi.mock('../../../foundation/discovery/template-conflict-release.mjs', () => ({
   expandedTemplateConflictSchemaActive: () => true,
 }));
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
 import {Command} from 'commander';
 import {discoverCoreTemplates} from '../../../foundation/discovery/template-adapter.mjs';
@@ -345,35 +344,6 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBe(1);
   });
 
-  it('components exits 1 when Core is missing, with no [ok] after the failure', async () => {
-    // Outside the repo, so nothing above the package resolves Core.
-    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-core-'));
-    const previousTmp = tmpDir;
-    tmpDir = outside;
-    try {
-      writeComponentIntegration('AcmeCarousel');
-      expect(findCoreDir(outside)).toBeNull();
-      process.chdir(outside);
-
-      await createProgram().parseAsync([
-        'node',
-        'astryx',
-        'doctor',
-        'integration',
-        'components',
-      ]);
-
-      const printed = logCalls.join('\n');
-      expect(printed).toContain('core_not_found');
-      expect(printed).not.toContain('[ok]');
-      expect(process.exitCode).toBe(1);
-    } finally {
-      tmpDir = previousTmp;
-      process.chdir(previousCwd);
-      fs.rmSync(outside, {recursive: true, force: true});
-    }
-  });
-
   it('components warns with the exact package-qualified command', async () => {
     const coreDir = findCoreDir(tmpDir);
     expect(coreDir).not.toBeNull();
@@ -463,29 +433,6 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBeUndefined();
   });
 
-  it('docs exits 1 for a placement that hides a guide, with no [ok] after the failure', async () => {
-    writeDocIntegration({name: 'deploying'});
-    fs.writeFileSync(
-      path.join(tmpDir, 'docs', 'deploying.doc.mjs'),
-      "export default {type: 'generic', name: 'deploying', title: 'Deploying', description: 'Deploy.', placement: {parent: 'namespace:nope', slot: 'guides'}, sections: [{title: 'Deploy', content: [{type: 'prose', text: 'Deploy.'}]}]};\n",
-    );
-    process.chdir(tmpDir);
-
-    await createProgram().parseAsync([
-      'node',
-      'astryx',
-      'doctor',
-      'integration',
-      'docs',
-    ]);
-
-    const printed = logCalls.join('\n');
-    expect(printed).toContain('[fail]');
-    expect(printed).toContain('invalid_doc_graph');
-    expect(printed).not.toContain('[ok]');
-    expect(process.exitCode).toBe(1);
-  });
-
   it('docs exits 1 for an accidental same-name Core topic', async () => {
     const [coreTopic] = Object.keys(discoverBuiltinTopics());
     writeDocIntegration({name: coreTopic});

package/clients/cli/commands/doctor.doc.mjs

@@ -16,9 +16,7 @@ export const doc = {
   summary: 'Diagnose Astryx projects and integration packages',
   description:
     'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +
-    'install and version alignment, themes, config, integrations (linked without a config entry, ' +
-    'provider identity, contribution issues), agent docs, core peer dependencies, package manager, ' +
-    "and the docs the CLI reads. It writes nothing, but loading astryx.config runs that file's code. " +
+    'install and version alignment, themes, config, agent docs, and package manager. ' +
     'The `integration` subcommands provide authoring checks for one integration package.',
   fn: 'doctor',
   subcommands: ['integration'],

package/clients/cli/commands/doctor.mjs

@@ -36,8 +36,6 @@ import {doc as integrationTemplateConflictsFn} from '../../../api/integration/in
 import {doc as integrationComponentConflictsFn} from '../../../api/integration/integrationComponentConflicts.doc.mjs';
 import {doc as integrationDocConflictsFn} from '../../../api/integration/integrationDocConflicts.doc.mjs';
 import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 
 const STATUS = {
   pass: '[ok]',
@@ -183,10 +181,8 @@ function printComponentConflicts(data) {
     ),
     ...issueBlocks(data.issues),
   ];
-  // An [ok] after a failed check reads as a pass: say nothing it could not check.
-  const failed = data.issues.some(issue => issue.severity === 'error');
   if (data.conflicts.length === 0) {
-    if (!failed) output.push(text('[ok] No component names conflict with Core.'));
+    output.push(text('[ok] No component names conflict with Core.'));
   } else {
     output.push(
       records(data.conflicts, {
@@ -228,9 +224,7 @@ function printDocConflicts(data) {
     );
   }
   if (data.findings.length === 0) {
-    if (!data.issues.some(issue => issue.severity === 'error')) {
-      output.push(text('[ok] No doc topics overlap with Core.'));
-    }
+    output.push(text('[ok] No doc topics overlap with Core.'));
   } else {
     output.push(
       records(data.findings, {
@@ -321,57 +315,19 @@ async function runAuthoringCheck(program, pkg, kind) {
   return NO_RESULT_SET;
 }
 
-/**
- * The first word after a command group, which names a subcommand it does not
- * have, or null.
- * @param {import('commander').Command | undefined} invoked
- * @returns {string | null}
- */
-function unknownWord(invoked) {
-  const word = (invoked?.args ?? []).find(arg => !String(arg).startsWith('-'));
-  return word == null ? null : String(word);
-}
-
-/**
- * Report an unknown subcommand, in text as in JSON, with the ones the group has.
- * @param {import('commander').Command} group
- * @param {string} label the group's full name
- * @param {string} word
- */
-function unknownSubcommand(group, label, word) {
-  return cliError(`unknown subcommand '${label} ${word}'`, {
-    suggestions: group.commands.map(child => ({
-      name: child.name(),
-      reason: 'available subcommand',
-    })),
-    code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,
-  });
-}
-
 /**
  * Register `astryx doctor` and its integration-authoring leaves.
  * @param {import('commander').Command} program
  */
 export function registerDoctor(program) {
-  /** @type {import('commander').Command} */
-  let doctorCmd;
-  doctorCmd = defineCommand(program, doctorCommand, {
+  const doctorCmd = defineCommand(program, doctorCommand, {
     fn: doctorFn,
-    // `doctor integrations` is a mistyped subcommand, not a project check.
-    action: async (options, invoked) => {
-      const word = unknownWord(invoked);
-      if (word != null) return unknownSubcommand(doctorCmd, 'doctor', word);
-      return runProjectDoctor(program);
-    },
+    action: async () => runProjectDoctor(program),
   });
   /** @type {import('commander').Command} */
   let integrationCmd;
   integrationCmd = defineCommand(doctorCmd, doctorIntegrationGroup, {
-    action: (options, invoked) => {
-      const word = unknownWord(invoked);
-      if (word != null) {
-        return unknownSubcommand(integrationCmd, 'doctor integration', word);
-      }
+    action: () => {
       integrationCmd.outputHelp();
       return NO_RESULT_SET;
     },