@astryxdesign/cli 0.6.4 → 0.6.5-canary.00f1ed9

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

@@ -3,10 +3,11 @@
 
 /**
  * @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.
+ * envelope. The vocabulary equals the manifest's response types (each
+ * command's FunctionDoc returns; see `clients/cli/lib/manifest.mjs`) plus
+ * ROOT_RESPONSE_TYPES (help, version) there; 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

@@ -2,10 +2,11 @@
 
 /**
  * @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.
+ * envelope. The vocabulary equals the manifest's response types (each
+ * command's FunctionDoc returns; see `clients/cli/lib/manifest.mjs`) plus
+ * ROOT_RESPONSE_TYPES (help, version) there; 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
@@ -172,7 +184,7 @@ export const doc = {
     {
       value: 'template.show',
       description:
-        "The resolved template's raw source plus its description, kind, and the component names it composes.",
+        "The resolved template's source, exactly as a copy writes it, plus its description, kind, the component names it composes, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media).",
     },
     {
       value: 'template.skeleton',
@@ -182,7 +194,7 @@ export const doc = {
     {
       value: 'template.copy',
       description:
-        'A scaffold receipt: template id, output directory, written file name, and file count.',
+        'A scaffold receipt: template id, output directory, written file name, file count, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media).',
     },
 
     {
@@ -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:
@@ -259,7 +276,7 @@ export const doc = {
     {
       value: 'upgrade.run',
       description:
-        'The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.',
+        'The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors.',
     },
 
     // manifest
@@ -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
@@ -290,29 +320,29 @@ export const doc = {
     {
       value: 'integration.validate',
       description:
-        'The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message}.',
+        'The validation result: validated (false when no integration manifest was found, so nothing was checked and the empty issues list proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message}.',
     },
     {
       value: 'integration.template-conflicts',
       description:
-        'The integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.',
+        'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.',
     },
     {
       value: 'integration.component-conflicts',
       description:
-        'The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.',
+        'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.',
     },
     {
       value: 'integration.doc-conflicts',
       description:
-        'The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` | `error`) and `relationship` (`replaces` | `extends` | `accidental`).',
+        'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` | `error`) and `relationship` (`replaces` | `extends` | `accidental`).',
     },
 
     // layout (XLE/XLO)
     {
       value: 'layout.expand',
       description:
-        'The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).',
+        'The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, written (the output path, or null when nothing was written), and demoMediaReplaced (count of demo media placeholders).',
     },
     {
       value: 'layout.check',

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.00f1ed9",
   "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.00f1ed9",
+    "@astryxdesign/core": "0.6.5-canary.00f1ed9",
+    "@astryxdesign/lab": "0.6.5-canary.00f1ed9",
+    "@astryxdesign/theme-neutral": "0.6.5-canary.00f1ed9"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/charts": {
@@ -121,10 +121,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.6.5-canary.00f1ed9",
+    "@astryxdesign/core": "0.6.5-canary.00f1ed9",
+    "@astryxdesign/lab": "0.6.5-canary.00f1ed9",
+    "@astryxdesign/theme-neutral": "0.6.5-canary.00f1ed9",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",

package/assets/docs/tree/integrations.test.mjs

@@ -1,62 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, expect, it} from 'vitest';
-import {docs as integrationGuide} from './integrations.doc.mjs';
-import {doc as integrationSchema} from '../../../authoring/integration/integration.doc.mjs';
-import {doc as templateSchema} from '../../../authoring/doctypes/template/template.doc.mjs';
-
-function guideText() {
-  return integrationGuide.sections
-    .flatMap(section => section.content)
-    .flatMap(block => {
-      if (block.type === 'prose') return [block.text];
-      if (block.type === 'code') return [block.label ?? '', block.code];
-      if (block.type === 'list') return block.items;
-      return [];
-    })
-    .join('\n');
-}
-
-describe('integration template replacement docs', () => {
-  it('documents the complete author and consumer contract', () => {
-    const text = guideText();
-
-    for (const required of [
-      "replaces: 'shell-side-nav'",
-      'acme-app-shell',
-      'astryx --json template --list --package @astryxdesign/core',
-      'astryx template shell-side-nav --package @astryxdesign/core',
-      'astryx template acme-app-shell --package @acme/navigation',
-      'templates/acme-app-shell.doc.mjs',
-      'AcmeSideNav',
-      'AcmeTopNav',
-      '<Card>Product content</Card>',
-      'fail closed',
-      'configured later wins',
-      'wins over an autolinked one',
-      'listed later in package.json dependencies',
-      'valid siblings',
-      'Without `replaces`',
-      '@astryxdesign/cli >=0.7.0',
-      'templates and doc topics are withheld',
-      '`template.list` JSON response',
-    ]) {
-      expect(text, required).toContain(required);
-    }
-  });
-
-  it('declares a replacement on the template, never in the manifest', () => {
-    expect(guideText()).not.toContain('templateReplacements');
-    expect(
-      integrationSchema.fields.some(field => /replac/i.test(field.name)),
-    ).toBe(false);
-
-    const field = templateSchema.fields.find(
-      candidate => candidate.name === 'replaces',
-    );
-    expect(field).toMatchObject({type: 'string'});
-    expect(field.description).toContain('Integration templates only');
-    expect(field.description).toContain('--package @astryxdesign/core');
-    expect(field.description).toContain('0.7.0');
-  });
-});