@astryxdesign/cli 0.6.4 → 0.6.5-canary.031021b

package/foundation/response/batch.type.mjs

@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared published types for complete multi-selector lookup receipts.
+ * Adopting API subjects specialize these types with their single-result and
+ * ambiguity-candidate types instead of defining command-specific row shapes.
+ *
+ * @input One exact selector, its single-result response, and its candidate shape.
+ * @output BatchRow and BatchResponse for every AST-053 lookup adopter.
+ * @position packages/cli/foundation/response — shared JSON response types
+ */
+
+/**
+ * One complete row for an accepted selector.
+ * @template TResult
+ * @template TCandidate
+ * @typedef {(
+ *   | {selector: string; status: 'found'; result: TResult}
+ *   | {selector: string; status: 'ambiguous'; code: string; error: string; candidates: TCandidate[]}
+ *   | {selector: string; status: 'not_found' | 'error'; code: string; error: string; suggestions?: import('./base').Suggestion[]}
+ * )} BatchRow
+ */
+
+/**
+ * One ordered batch receipt inside the shared `{type, data}` success envelope.
+ * @template {string} TType
+ * @template TResult
+ * @template TCandidate
+ * @typedef {object} BatchResponse
+ * @property {TType} type
+ * @property {{count: number; results: BatchRow<TResult, TCandidate>[]}} data
+ */
+
+export {};

package/foundation/response/error-codes.doc.mjs

@@ -36,17 +36,16 @@ export const doc = {
     {
       value: 'ERR_INVALID_OPTION',
       description:
-        'An unknown flag/option was passed (Commander `unknownOption`).',
+        'An unknown option was passed, --json was given to a command without JSON output, or layout --form got a value other than compact, outline, or auto.',
     },
     {
       value: 'ERR_INVALID_ARGUMENT',
       description:
-        "An option/argument had a value Commander's parser rejected.",
+        'An argument or option value is invalid: wrong type, out of range, an unknown choice, an extra argument, or a conflicting combination.',
     },
     {
       value: 'ERR_MISSING_ARGUMENT',
-      description:
-        'A required positional argument was omitted (Commander `missingArgument`).',
+      description: 'A required argument or option value was omitted.',
     },
     {
       value: 'ERR_INVALID_LANG',
@@ -134,12 +133,11 @@ export const doc = {
     },
     {
       value: 'ERR_UNKNOWN_PACKAGE',
-      description: 'No package matched the requested name (discover).',
+      description: 'No package matched the requested name.',
     },
     {
       value: 'ERR_UNKNOWN_AGENT',
-      description:
-        'An unrecognized `--agent` value was passed to agent-docs/init.',
+      description: 'An unrecognized `--agent` value was passed to init.',
     },
     {
       value: 'ERR_UNKNOWN_FEATURE',
@@ -272,7 +270,7 @@ export const doc = {
     {
       value: 'ERR_UNCLASSIFIED_EXIT',
       description:
-        'Recorded in the debug log, never printed: a command exited non-zero without going through cliError/jsonError, so no stable code was available.',
+        'Recorded in the debug log, never printed: a command exited non-zero without reporting an error code.',
     },
     {
       value: 'ERR_SIGNAL_TERMINATED',

package/foundation/response/error-codes.test.mjs

@@ -195,9 +195,16 @@ describe('error codes: end-to-end JSON envelopes', () => {
     // is rejected at the preAction gate with a stable invalid-option code.
     {
       name: 'json not supported',
-      args: ['theme', 'bogus-sub', '--json'],
+      args: ['theme', '--json'],
       code: 'ERR_INVALID_OPTION',
     },
+    // A group given a word it does not have names the unknown subcommand,
+    // in JSON as in text.
+    {
+      name: 'unknown subcommand of a group',
+      args: ['theme', 'bogus-sub', '--json'],
+      code: 'ERR_UNKNOWN_SUBCOMMAND',
+    },
   ];
 
   for (const {name, args, code} of cases) {
@@ -249,13 +256,31 @@ describe('error codes: human mode stays clean', () => {
     expect(stdout).not.toContain('ERR_UNKNOWN_COMPONENT');
   });
 
-  it('unknown subcommand exits 1 in human mode (code carried internally)', async () => {
-    // `theme` is not JSON-capable, so this path is human-only; we assert the
-    // failure surfaces with exit 1 and a helpful message. The stable
-    // ERR_UNKNOWN_SUBCOMMAND code rides along on the cliError call.
+  it('unknown subcommand exits 1, with the code in JSON and not in text', async () => {
+    // A group that is not JSON-capable itself still answers an unknown
+    // subcommand in JSON, so a JSON caller learns the subcommands it has.
     const {status, stderr} = await runCli(['theme', 'bogus-sub']);
     expect(status).toBe(1);
     expect(stderr).toContain("unknown subcommand 'theme bogus-sub'");
     expect(stderr).not.toContain('ERR_UNKNOWN_SUBCOMMAND');
+    for (const args of [
+      ['--json', 'theme', 'bogus-sub'],
+      ['theme', 'bogus-sub', '--json'],
+      ['--json', 'doctor', 'integration', 'bogus-sub'],
+    ]) {
+      const json = await runCli(args);
+      expect(json.status, args.join(' ')).toBe(1);
+      expect(JSON.parse(json.stdout), args.join(' ')).toMatchObject({
+        code: 'ERR_UNKNOWN_SUBCOMMAND',
+        suggestions: expect.arrayContaining([expect.objectContaining({reason: 'available subcommand'})]),
+      });
+    }
+    // Text and JSON agree for a group that shows help when run bare.
+    const text = await runCli(['doctor', 'integration', 'bogus-sub']);
+    expect(text.status).toBe(1);
+    expect(text.stderr).toContain("unknown subcommand 'doctor integration bogus-sub'");
+    const doctor = await runCli(['doctor', 'integrations']);
+    expect(doctor.status).toBe(1);
+    expect(doctor.stderr).toContain("unknown subcommand 'doctor integrations'");
   });
 });

package/foundation/response/response-types.doc.d.mts

@@ -4,9 +4,10 @@
 /**
  * @file EnumDoc for the `type` discriminant carried on every --json success
  * envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
- * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
- * switches on `type` to narrow the `data` payload. Descriptions follow the
- * currently published response projection, not a future package-version boundary.
+ * `jsonOut(...)` call sites) plus ROOT_RESPONSE_TYPES (help, version) in
+ * `clients/cli/lib/manifest.mjs`; a consumer switches on `type` to narrow the
+ * `data` payload. Descriptions follow the currently published response
+ * projection, not a future package-version boundary.
  *
  * @input Public response discriminants and their currently released payloads.
  * @output Generated consumer reference for every typed JSON success response.

package/foundation/response/response-types.doc.mjs

@@ -3,9 +3,10 @@
 /**
  * @file EnumDoc for the `type` discriminant carried on every --json success
  * envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
- * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
- * switches on `type` to narrow the `data` payload. Descriptions follow the
- * currently published response projection, not a future package-version boundary.
+ * `jsonOut(...)` call sites) plus ROOT_RESPONSE_TYPES (help, version) in
+ * `clients/cli/lib/manifest.mjs`; a consumer switches on `type` to narrow the
+ * `data` payload. Descriptions follow the currently published response
+ * projection, not a future package-version boundary.
  *
  * @input Public response discriminants and their currently released payloads.
  * @output Generated consumer reference for every typed JSON success response.
@@ -35,7 +36,12 @@ export const doc = {
     {
       value: 'component.list',
       description:
-        'The component catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.',
+        "The component catalog grouped by component group (each component's group field): `detail` (the level: names | compact | full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.",
+    },
+    {
+      value: 'component.batch',
+      description:
+        'The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found | not_found | ambiguous | error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}).',
     },
     {
       value: 'component.detail',
@@ -104,21 +110,27 @@ export const doc = {
     {
       value: 'discover.list',
       description:
-        'The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
+        'The integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
     },
     {
       value: 'discover.detail',
-      description: 'A single external package entry, for an @scope/name query.',
+      description:
+        'One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it.',
     },
     {
       value: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.',
+        'The validated ComponentDoc for one installed component, for an @scope/name/Component query.',
+    },
+    {
+      value: 'discover.item',
+      description:
+        'One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package.',
     },
     {
       value: 'discover.search',
       description:
-        'The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.',
+        'The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list.',
     },
 
     // search
@@ -149,7 +161,7 @@ export const doc = {
     {
       value: 'swizzle.copy',
       description:
-        'An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.',
+        'An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling.',
     },
 
     // gap reports
@@ -251,6 +263,11 @@ export const doc = {
       description:
         'Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.',
     },
+    {
+      value: 'upgrade.registry',
+      description:
+        'The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items.',
+    },
     {
       value: 'upgrade.status',
       description:
@@ -269,11 +286,24 @@ export const doc = {
         'The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.',
     },
 
+    // help and version, which no single command owns
+    {
+      value: 'help',
+      description:
+        'Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). ' +
+        "`--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). " +
+        'data.manifest marks the first shape; data.usage marks the second.',
+    },
+    {
+      value: 'version',
+      description: 'The CLI version, for `astryx --version --json`: {version}.',
+    },
+
     // doctor
     {
       value: 'doctor',
       description:
-        'The health-check report: `checks` (each with id, label, status: pass | warn | fail | info, a message, and a fix when not passing) plus a `summary` of counts per status.',
+        'The health-check report: `checks` (each with id, label, status: pass | warn | fail | info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status.',
     },
 
     // integration authoring

package/foundation/response/response-types.doc.test.mjs

@@ -53,6 +53,29 @@ function expectNamed(type, fields) {
 }
 
 describe('response-types EnumDoc names every field', () => {
+  it('component.batch names every row field and state', async () => {
+    const res = await data(['component', 'Button', 'Badge']);
+    expect(res.type).toBe('component.batch');
+    expect(describedAs('component.batch')).toMatch(/BatchResponse.*BatchRow/);
+    expectNamed('component.batch', [
+      'count',
+      'results',
+      'selector',
+      'status',
+      'result',
+      'code',
+      'error',
+      'candidates',
+      'package',
+      'component',
+      'kind',
+      'installed',
+      'suggestions',
+      'name',
+      'reason',
+    ]);
+  });
+
   it('component.detail: the ownership fields and parentDoc', async () => {
     const res = await data(['component', 'HStack']);
     expect(res.type).toBe('component.detail');

package/foundation/response/response.doc.mjs

@@ -39,16 +39,13 @@ export const doc = {
           name: 'type',
           type: 'string',
           description:
-            'Discriminator naming the payload shape. Each command guarantees ' +
-            'its own `type` at its return; there is no central union.',
+            'Names the payload shape. Every value is listed in the response-types enum.',
           required: true,
         },
         {
           name: 'data',
           type: 'unknown',
-          description:
-            "The command's payload. Structural by design, narrowed by the " +
-            'per-command return type, not by a map in the serializer.',
+          description: "The command's payload; its shape depends on `type`.",
           required: true,
         },
         {
@@ -64,7 +61,7 @@ export const doc = {
       type: '{ apiVersion: number; error: string; code: ErrorCode; suggestions?: Suggestion[] }',
       description:
         'Emitted for every failure in --json mode, including uncaught throws ' +
-        'and Commander parse errors, which are converted to this shape.',
+        'and command-line parse errors, which are converted to this shape.',
       fields: [
         {
           name: 'apiVersion',
@@ -121,7 +118,7 @@ export const doc = {
       label: 'Success',
       code: `{
   "apiVersion": 1,
-  "type": "component",
+  "type": "component.detail",
   "data": { "name": "Button" }
 }`,
     },
@@ -153,9 +150,13 @@ export const doc = {
     {
       type: 'prose',
       text:
-        'The process exit code is part of the contract too: successful commands ' +
-        'exit 0, and a JSON error envelope is accompanied by a non-zero exit ' +
-        '(jsonError exits 1).',
+        'The process exit code is part of the contract too. Exit 0 means success, ' +
+        'and every error envelope exits 1. Some commands also exit 1 with a success ' +
+        'envelope when what they report failed: a failed check (layout check, doctor ' +
+        'and its integration subcommands, integration verify, theme build ' +
+        '--check), a gap report that was not delivered, an upgrade left incomplete, ' +
+        'or init agent docs refused for a path outside the project. Read the ' +
+        'envelope, not the exit code, to tell them apart.',
     },
   ],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.6.4",
+  "version": "0.6.5-canary.031021b",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -101,10 +101,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*"
+    "@astryxdesign/charts": "0.6.5-canary.031021b",
+    "@astryxdesign/core": "0.6.5-canary.031021b",
+    "@astryxdesign/lab": "0.6.5-canary.031021b",
+    "@astryxdesign/theme-neutral": "0.6.5-canary.031021b"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/charts": {
@@ -121,10 +121,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.6.5-canary.031021b",
+    "@astryxdesign/core": "0.6.5-canary.031021b",
+    "@astryxdesign/lab": "0.6.5-canary.031021b",
+    "@astryxdesign/theme-neutral": "0.6.5-canary.031021b",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",

package/api/docs/docs.test.mjs

@@ -1,243 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Dispatcher-level tests for docs() — the argument-shape routing that
- * sits above the list/detail/section leaves. The leaves have their own tests;
- * this pins the router: docs() -> list, docs(topic) -> detail,
- * docs(topic, section) -> section, plus the unknown-topic/section error codes.
- * Runs against the real CLI-bundled docs (no cwd/project needed).
- */
-
-import {describe, it, expect} from 'vitest';
-import {docs} from './docs.mjs';
-import {AstryxError} from '../error.mjs';
-
-const SLOW = 30_000;
-
-describe('docs() dispatcher routing', () => {
-  it('no topic -> docs.list', async () => {
-    const r = await docs();
-    expect(r.type).toBe('docs.list');
-    expect(Array.isArray(r.data)).toBe(true);
-    expect(r.data.length).toBeGreaterThan(0);
-  }, SLOW);
-
-  it('empty topic -> docs.list (falsy topic routes to list)', async () => {
-    expect((await docs('')).type).toBe('docs.list');
-  }, SLOW);
-
-  it('topic only -> docs.detail, the whole doc', async () => {
-    const {data} = await docs();
-    expect((await docs(data[0].topic)).type).toBe('docs.detail');
-  }, SLOW);
-
-  it('topic + index -> docs.index', async () => {
-    const {data} = await docs();
-    const r = await docs(data[0].topic, undefined, {index: true});
-    expect(r.type).toBe('docs.index');
-  }, SLOW);
-
-  it('topic + section -> docs.detail.section', async () => {
-    const {data} = await docs();
-    let routed = null;
-    for (const {topic} of data) {
-      const detail = await docs(topic);
-      const sections = detail.data.sections;
-      if (Array.isArray(sections) && sections.length > 0) {
-        routed = await docs(topic, sections[0].title);
-        break;
-      }
-    }
-    expect(routed).not.toBeNull();
-    expect(routed.type).toBe('docs.detail.section');
-  }, SLOW);
-
-  it('unknown topic -> ERR_UNKNOWN_TOPIC', async () => {
-    await expect(docs('zzz-not-a-real-topic')).rejects.toBeInstanceOf(AstryxError);
-    await expect(docs('zzz-not-a-real-topic')).rejects.toMatchObject({
-      code: 'ERR_UNKNOWN_TOPIC',
-    });
-  }, SLOW);
-
-  it('known topic + unknown section -> ERR_UNKNOWN_SECTION', async () => {
-    const {data} = await docs();
-    const topic = data[0].topic;
-    await expect(docs(topic, 'zzz-not-a-real-section')).rejects.toMatchObject({
-      code: 'ERR_UNKNOWN_SECTION',
-    });
-  }, SLOW);
-
-  it("lists the docs tree's namespaces in meta, so every data entry reads as a topic", async () => {
-    const res = await docs();
-    expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'unorganized']);
-    for (const entry of res.data) {
-      expect((await docs(entry.topic)).type).toBe('docs.detail');
-    }
-  }, SLOW);
-
-  it('opens a route typed in another case', async () => {
-    const r = await docs('CLI/API');
-    expect(r.type).toBe('docs.node');
-    expect(r.data).toMatchObject({route: 'cli/api', links: {up: 'astryx docs cli'}});
-  }, SLOW);
-
-  it('a section of a typed doc -> ERR_UNKNOWN_SECTION, suggesting the doc itself', async () => {
-    const err = await docs('cli/api/functions/search', 'x').catch(e => e);
-    expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    expect(err.message).toContain('astryx docs cli/api/functions/search');
-    expect(err.suggestions.map(s => s.name)).toEqual(['cli/api/functions/search']);
-  }, SLOW);
-
-  it('a namespace route -> docs.node, one level of children', async () => {
-    const r = await docs('cli/api');
-    expect(r.type).toBe('docs.node');
-    expect(r.data).toMatchObject({
-      id: 'astryx:artifact:v1/%40astryxdesign%2Fcli/namespace/api',
-      route: 'cli/api',
-      kind: 'namespace',
-      package: '@astryxdesign/cli',
-      breadcrumb: [{route: 'cli', title: 'Astryx CLI'}],
-      content: [],
-    });
-    expect(r.data.slots.flatMap(slot => slot.children.map(c => c.route))).toEqual([
-      'cli/api/functions',
-      'cli/api/schemas',
-      'cli/api/enums',
-    ]);
-  }, SLOW);
-
-  it('a typed doc route -> docs.node with its content', async () => {
-    const r = await docs('cli/api/functions/search');
-    expect(r.type).toBe('docs.node');
-    expect(r.data).toMatchObject({
-      id: 'astryx:artifact:v1/%40astryxdesign%2Fcli/function/search',
-      kind: 'function',
-      title: 'search()',
-      slots: [],
-    });
-    expect(r.data.breadcrumb.map(link => link.route)).toEqual([
-      'cli',
-      'cli/api',
-      'cli/api/functions',
-    ]);
-    expect(JSON.stringify(r.data.content)).toContain(
-      '`astryx search` runs it. Read it with `astryx docs cli/commands/search`.',
-    );
-  }, SLOW);
-
-  it('a guide the tree places reads like a topic: the whole doc, its index, a section', async () => {
-    expect((await docs('cli/integrations')).type).toBe('docs.detail');
-    const index = await docs('cli/integrations', undefined, {index: true});
-    expect(index).toMatchObject({type: 'docs.index', data: {name: 'cli/integrations'}});
-    expect(index.data.sections.length).toBeGreaterThan(1);
-    expect((await docs('cli/integrations', 'components')).type).toBe(
-      'docs.detail.section',
-    );
-  }, SLOW);
-
-  it('every read carries its moves (spec:AST-047)', async () => {
-    const root = (await docs('cli')).data;
-    expect(root.links).toEqual({up: 'astryx docs'});
-    const leaf = (await docs('cli/api/functions/search')).data;
-    expect(leaf.links.up).toBe('astryx docs cli/api/functions');
-    expect(leaf.links.previous).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
-    expect(leaf.links.next).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
-    const index = await docs('cli/integrations', undefined, {index: true});
-    // A guide moves across its namespace's slot, as any tree node does.
-    expect(index.data.links).toEqual({
-      up: 'astryx docs cli',
-      next: 'astryx docs cli/writing-docs',
-    });
-    const first = (await docs('cli/integrations', index.data.sections[0].id)).data;
-    expect(first.links).toEqual({
-      up: 'astryx docs cli/integrations --index',
-      next: `astryx docs cli/integrations ${index.data.sections[1].id}`,
-    });
-    const last = index.data.sections.at(-1).id;
-    const end = (await docs('cli/integrations', last)).data;
-    expect(end.links.next).toBeUndefined();
-    expect(end.links.previous).toBe(
-      `astryx docs cli/integrations ${index.data.sections.at(-2).id}`,
-    );
-    // A flat topic's home is the Unorganized level, and it moves across it.
-    const flat = (await docs('principles')).data.links;
-    expect(flat.up).toBe('astryx docs unorganized');
-    expect(flat.previous).toMatch(/^astryx docs [a-z-]+$/);
-    expect(flat.next).toMatch(/^astryx docs [a-z-]+$/);
-    const home = (await docs('unorganized')).data;
-    expect(home).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
-    expect(home.slots[0].children.map(child => child.route)).toEqual(
-      (await docs()).data.map(entry => entry.topic),
-    );
-  }, SLOW);
-
-  it('names a node by its doc identity; a generated level has id null', async () => {
-    const level = (await docs('cli/api/functions')).data;
-    expect(level).toHaveProperty('id', null);
-    expect(level.route).toBe('cli/api/functions');
-  }, SLOW);
-
-  it("offers a typed doc's related docs as moves", async () => {
-    const fn = (await docs('cli/api/functions/search')).data;
-    expect(fn.links.related).toContain('astryx docs cli/commands/search');
-    const cmd = (await docs('cli/commands/search')).data;
-    expect(cmd.links.related).toContain('astryx docs cli/api/functions/search');
-  }, SLOW);
-
-  it('a topic read returns the whole doc; index returns its sections', async () => {
-    expect((await docs('principles')).type).toBe('docs.detail');
-    const index = await docs('principles', undefined, {index: true});
-    expect(index.type).toBe('docs.index');
-    expect(index.data.sections.length).toBeGreaterThan(1);
-    expect((await docs('principles', undefined, {dense: true})).type).toBe(
-      'docs.detail',
-    );
-  }, SLOW);
-
-  it("the guide's old flat name is gone, and its error names the new route", async () => {
-    await expect(docs('cli-integrations')).rejects.toMatchObject({
-      code: 'ERR_UNKNOWN_TOPIC',
-      suggestions: [expect.objectContaining({name: 'cli/integrations'})],
-    });
-    expect((await docs()).data.map(entry => entry.topic)).not.toContain(
-      'cli-integrations',
-    );
-  }, SLOW);
-
-  it('a section of a namespace -> ERR_UNKNOWN_SECTION, naming its children', async () => {
-    const err = await docs('cli', 'commands').catch(e => e);
-    expect(err).toBeInstanceOf(AstryxError);
-    expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    expect(err.suggestions.map(s => s.name)).toEqual([
-      'cli/integrations',
-      'cli/writing-docs',
-      'cli/commands',
-      'cli/api',
-    ]);
-  }, SLOW);
-
-  it('an unknown route suggests the children of the deepest namespace it reaches', async () => {
-    const err = await docs('cli/api/functions/serch').catch(e => e);
-    expect(err.code).toBe('ERR_UNKNOWN_TOPIC');
-    expect(err.suggestions.map(s => s.name)).toContain('cli/api/functions/search');
-    expect(err.suggestions.every(s => s.name.startsWith('cli/api/functions/'))).toBe(true);
-  }, SLOW);
-
-  it('non-string topic -> ERR_UNKNOWN_TOPIC (not a raw TypeError)', async () => {
-    for (const bad of [123, {}, ['tokens'], true]) {
-      const err = await docs(/** @type {any} */ (bad)).catch(e => e);
-      expect(err).toBeInstanceOf(AstryxError);
-      expect(err.code).toBe('ERR_UNKNOWN_TOPIC');
-    }
-  }, SLOW);
-
-  it('non-string section -> ERR_UNKNOWN_SECTION (not a raw TypeError)', async () => {
-    const {data} = await docs();
-    const topic = data[0].topic;
-    for (const bad of [456, {}, ['x']]) {
-      const err = await docs(topic, /** @type {any} */ (bad)).catch(e => e);
-      expect(err).toBeInstanceOf(AstryxError);
-      expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    }
-  }, SLOW);
-});