@astryxdesign/cli 0.6.3-canary.d0d49a4 → 0.6.3-canary.db4e378

package/api/integration/add-contribution.mjs

@@ -35,6 +35,7 @@ import {
 } from '../../foundation/integrations/integrations.mjs';
 import {isValidSemver} from '../../foundation/env/semver.mjs';
 import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
+import {findIntegrationComponentDoc} from '../../foundation/discovery/component-discovery.mjs';
 import {parseAgentDocsField} from '../../authoring/integration/schema.mjs';
 import {integrationAddTheme} from './add-theme.mjs';
 import {
@@ -248,6 +249,16 @@ async function addComponent(name, options) {
       ERROR_CODES.ERR_FILE_EXISTS,
     );
   }
+  // Discovery keys components by doc stem anywhere under the root, so a second
+  // doc with this name would shadow one of the two.
+  const existingDoc = findIntegrationComponentDoc({components: root}, name);
+  if (existingDoc != null) {
+    throw new AstryxError(
+      `Refusing to add component "${name}": ${projectPath(path.relative(packageDir, existingDoc))} already defines it.`,
+      undefined,
+      ERROR_CODES.ERR_FILE_EXISTS,
+    );
+  }
 
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
   const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');

package/api/integration/add-contribution.test.mjs

@@ -731,3 +731,83 @@ describe('public dispatcher', () => {
     ).rejects.toThrow(/component, doc, template, codemod, agent-doc, or theme/);
   });
 });
+
+describe('dry-run receipts match the real write', () => {
+  /** Package states each writer has to plan for. */
+  const STATES = {
+    'no manifest': {pkg: {files: ['dist']}},
+    'an empty manifest': {pkg: {}, manifest: 'export default {};\n'},
+    'declared roots and an exports map': {
+      pkg: {files: ['dist'], exports: {'.': './dist/index.js'}},
+      manifest:
+        "export default {\n  components: './components',\n  docs: './docs',\n  templates: './templates',\n  codemods: './codemods',\n  themes: './themes',\n};\n",
+    },
+  };
+  /** @type {Array<[any, string, Record<string, unknown>]>} */
+  const KINDS = [
+    ['component', 'AcmeWidget', {}],
+    ['doc', 'deploying', {}],
+    ['template', 'account-page', {}],
+    ['template', 'account-card', {templateType: 'block'}],
+    ['codemod', 'rename-widget', {to: '1.2.0'}],
+    ['agent-doc', 'Run acme verify before finishing.', {}],
+    ['theme', 'ocean', {}],
+  ];
+
+  /** Every file under the package, keyed by project path, with its bytes. */
+  function snapshot() {
+    /** @type {Record<string, string>} */
+    const files = {};
+    /** @param {string} dir */
+    const walk = dir => {
+      for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else {
+          files[path.relative(tmpDir, full).split(path.sep).join('/')] =
+            fs.readFileSync(full, 'base64');
+        }
+      }
+    };
+    walk(tmpDir);
+    return files;
+  }
+
+  for (const [stateName, state] of Object.entries(STATES)) {
+    for (const [kind, name, options] of KINDS) {
+      it(`${kind} ${name} in a package with ${stateName}`, async () => {
+        fs.writeFileSync(
+          path.join(tmpDir, 'package.json'),
+          `${JSON.stringify({name: '@acme/integration', version: '1.0.0', ...state.pkg}, null, 2)}\n`,
+        );
+        if (state.manifest != null) {
+          fs.writeFileSync(
+            path.join(tmpDir, 'astryx.integration.mjs'),
+            state.manifest,
+          );
+        }
+        const before = snapshot();
+
+        const plan = await integrationAdd(kind, name, {
+          cwd: tmpDir,
+          dryRun: true,
+          ...options,
+        });
+        expect(snapshot()).toEqual(before);
+
+        const written = await integrationAdd(kind, name, {
+          cwd: tmpDir,
+          ...options,
+        });
+        const after = snapshot();
+        const changed = Object.keys(after)
+          .filter(file => after[file] !== before[file])
+          .sort();
+
+        expect(written.data.root).toEqual(plan.data.root);
+        expect(written.data.files).toEqual(plan.data.files);
+        expect([...written.data.files].sort()).toEqual(changed);
+      });
+    }
+  }
+});

package/api/integration/integrationAdd.doc.mjs

@@ -33,7 +33,8 @@ export const doc = {
     {
       name: 'name',
       type: 'string',
-      description: 'Contribution name, or the literal agent-doc line.',
+      description:
+        'Contribution name: PascalCase for component, lowercase kebab-case for template, codemod, and theme, letters, digits, _ and - for doc, or the literal agent-doc line.',
       required: true,
     },
     {
@@ -56,17 +57,19 @@ export const doc = {
     {
       name: 'options.replaces',
       type: 'string',
-      description: 'Existing topic to replace. Only valid for doc.',
+      description:
+        'Existing topic to replace. Only valid for doc, and not with options.extends.',
     },
     {
       name: 'options.extends',
       type: 'string',
-      description: 'Existing topic to extend. Only valid for doc.',
+      description:
+        'Existing topic to extend. Only valid for doc, and not with options.replaces.',
     },
     {
       name: 'options.to',
       type: 'string',
-      description: 'Exact target semver. Required for codemod.',
+      description: 'Exact target semver (e.g. 1.2.0). Required for codemod and only valid there.',
     },
   ],
   returns: [

package/api/integration/integrationAddComponent.doc.mjs

@@ -8,7 +8,7 @@ export const doc = {
   displayName: 'integrationAddComponent()',
   summary: 'Add a complete component contribution.',
   description:
-    'Creates the same-stem component source and metadata pair, declares the components root on first use, preserves existing package allowlists, and publishes an exact source subpath when the package already has an exports map.',
+    'Creates the same-stem component source and metadata pair, declares the components root on first use, preserves existing package allowlists, and publishes an exact source subpath when the package already has an exports map. Refuses with ERR_FILE_EXISTS when a component doc anywhere under the components root already uses the name.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationAddComponent(name: string, options?: IntegrationAddComponentOptions): Promise<IntegrationAddResponse>',

package/api/integration/validate-integration.mjs

@@ -400,8 +400,10 @@ export async function validateLocalIntegration(cwd = process.cwd()) {
   try {
     pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
   } catch (err) {
+    // A null name means "no manifest here"; this package has one.
     return {
       found: true,
+      name: '(local package)',
       manifestFile: manifests[0],
       issues: [
         error(

package/api/integration/validate-integration.test.mjs

@@ -13,10 +13,16 @@ import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {
+  validateIntegration,
   validateLocalIntegration,
   validateInstalledIntegration,
   summarizeIssues,
 } from './validate-integration.mjs';
+import {
+  integrationComponentConflicts,
+  integrationDocConflicts,
+  integrationTemplateConflicts,
+} from './authoring-checks.mjs';
 
 let tmpDir;
 
@@ -472,3 +478,88 @@ describe('validate-integration API', () => {
     expect(byCode(result.issues, 'invalid_package_spec')).toHaveLength(1);
   });
 });
+
+describe('integration diagnostics are read-only', () => {
+  /** Every directory and file under `dir`, with file bytes. */
+  function snapshot(dir) {
+    /** @type {Record<string, string>} */
+    const entries = {};
+    /** @param {string} current */
+    const walk = current => {
+      for (const entry of fs.readdirSync(current, {withFileTypes: true})) {
+        const full = path.join(current, entry.name);
+        const key = path.relative(dir, full);
+        if (entry.isDirectory()) {
+          entries[`${key}/`] = '';
+          walk(full);
+        } else {
+          entries[key] = fs.readFileSync(full, 'base64');
+        }
+      }
+    };
+    walk(dir);
+    return entries;
+  }
+
+  /** A package with valid, broken, conflicting, and unreachable contributions. */
+  function writeDiagnosedPackage(dir) {
+    writePackage(dir, {
+      manifest:
+        "export default {\n  components: './components',\n  templates: './templates',\n  docs: './docs',\n  codemods: './gone',\n  themes: './themes',\n};\n",
+    });
+    const write = (relative, contents) => {
+      fs.mkdirSync(path.dirname(path.join(dir, relative)), {recursive: true});
+      fs.writeFileSync(path.join(dir, relative), contents);
+    };
+    write(
+      'components/Card.doc.mjs',
+      "export default {type: 'component', name: 'Card', props: []};\n",
+    );
+    write('components/Card.tsx', 'export function Card() { return null; }\n');
+    write(
+      'components/Orphan.doc.mjs',
+      "export default {type: 'component', name: 'Orphan', props: []};\n",
+    );
+    write('templates/dash.doc.mjs', "export default {type: 'page', name: 'Dash'};\n");
+    write(
+      'docs/theme.doc.mjs',
+      "export default {type: 'generic', name: 'theme', title: 'Theme', description: 'x', sections: [{title: 'A', content: [{type: 'prose', text: 'x'}]}]};\n",
+    );
+    write('themes/manifest.json', '{"version": 1, "themes": [{"slug": 7}]}\n');
+    write(
+      'stray/Stray.doc.mjs',
+      "export default {type: 'component', name: 'Stray', props: []};\n",
+    );
+  }
+
+  it('leaves local and installed packages byte-for-byte unchanged', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writeDiagnosedPackage(pkgDir);
+    const consumer = path.join(tmpDir, 'consumer');
+    fs.mkdirSync(consumer, {recursive: true});
+    fs.writeFileSync(
+      path.join(consumer, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    writeDiagnosedPackage(path.join(consumer, 'node_modules', '@acme', 'widgets'));
+    const before = {pkg: snapshot(pkgDir), consumer: snapshot(consumer)};
+
+    const local = await validateIntegration(undefined, {cwd: pkgDir});
+    const installed = await validateIntegration('@acme/widgets', {
+      cwd: consumer,
+    });
+    for (const [pkg, cwd] of [
+      [undefined, pkgDir],
+      ['@acme/widgets', consumer],
+    ]) {
+      await integrationTemplateConflicts(pkg, {cwd});
+      await integrationComponentConflicts(pkg, {cwd});
+      await integrationDocConflicts(pkg, {cwd});
+    }
+
+    expect(summarizeIssues(local.data.issues).errors).toBeGreaterThan(0);
+    expect(byCode(local.data.issues, 'unreachable_contribution')).toHaveLength(1);
+    expect(summarizeIssues(installed.data.issues).errors).toBeGreaterThan(0);
+    expect({pkg: snapshot(pkgDir), consumer: snapshot(consumer)}).toEqual(before);
+  });
+});

package/api/integration/validateIntegration.doc.mjs

@@ -45,7 +45,7 @@ export const doc = {
     {
       type: 'integration.validate',
       description:
-        'The result envelope: `data.name` and `data.version` of the validated package (both null when no local manifest is found), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
+        'The result envelope: `data.name` and `data.version` of the validated package (both null only when no local manifest is found; `data.name` is `(local package)` when the local package.json has no readable name), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
     },
   ],
   examples: [

package/api/json/envelope-types.test.mjs

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The published `@astryxdesign/cli/json` envelope types carry
+ * `apiVersion`, the field every `--json` envelope has. Type-checks a consumer
+ * fixture that reads it from each envelope shape.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+import {fileURLToPath} from 'node:url';
+
+const INDEX = fileURLToPath(new URL('./index.ts', import.meta.url));
+const TSC = createRequire(import.meta.url).resolve('typescript/bin/tsc');
+
+const FIXTURE = `
+import type {
+  assertResponse,
+  CLIError,
+  CLIUnsupportedError,
+  parseResponse,
+} from ${JSON.stringify(INDEX)};
+
+declare const error: CLIError;
+declare const unsupported: CLIUnsupportedError;
+declare const parsed: Exclude<ReturnType<typeof parseResponse>, CLIError | CLIUnsupportedError>;
+declare const asserted: ReturnType<typeof assertResponse<'manifest'>>;
+
+export const versions: number[] = [
+  error.apiVersion,
+  unsupported.apiVersion,
+  parsed.apiVersion,
+  asserted.apiVersion,
+];
+`;
+
+describe('@astryxdesign/cli/json envelope types', () => {
+  it('declare apiVersion on the success and error envelopes', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-envelope-types-'));
+    try {
+      fs.writeFileSync(path.join(dir, 'fixture.ts'), FIXTURE);
+      fs.writeFileSync(
+        path.join(dir, 'tsconfig.json'),
+        JSON.stringify({
+          compilerOptions: {
+            target: 'ES2022',
+            module: 'ESNext',
+            moduleResolution: 'bundler',
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+            allowImportingTsExtensions: true,
+            // index.ts re-exports JSDoc types from .type.mjs files; read them
+            // from source, as tsconfig.json-api.json does, not from generated
+            // declarations that exist only after a build.
+            allowJs: true,
+            types: [],
+          },
+          files: ['fixture.ts'],
+        }),
+      );
+      const res = spawnSync(process.execPath, [TSC, '-p', dir], {
+        encoding: 'utf-8',
+        timeout: 60_000,
+      });
+      expect(res.stdout + res.stderr).toBe('');
+      expect(res.status).toBe(0);
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  });
+});

package/api/json/parseResponse.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   description:
     'The entry point for consuming the CLI as a subprocess. A JSON string is parsed; ' +
     'an already-parsed object is passed through unchanged, so it is safe to call on ' +
-    'either. It returns the structural { type, data, meta? } envelope without narrowing: ' +
+    'either. It returns the structural { apiVersion, type, data, meta? } envelope without narrowing: ' +
     '`data` stays unknown until you discriminate on `type` (or use assertResponse).',
   importPath: '@astryxdesign/cli/json',
   signature: 'parseResponse(raw: unknown): any',
@@ -34,7 +34,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
+        'The { apiVersion, type, data, meta? } envelope, or a CLIError envelope ({ apiVersion, error, code, suggestions? }). The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
     },
   ],
   throws: [

package/api/layout/expand/expand.mjs

@@ -120,18 +120,20 @@ export async function layoutExpand(expression, options = {}) {
 
   let written = null;
   if (targetPath) {
-    let resolved;
+    // The guard sees the file that will be written, not only its directory:
+    // a symlink at that name would otherwise carry the write outside the root.
+    const fileTarget = isFilePathArg(targetPath)
+      ? targetPath
+      : path.join(targetPath, `${componentName}.tsx`);
+    let filePath;
     try {
-      resolved = assertWithin(targetPath, cwd, {label: 'layout target path'});
+      filePath = assertWithin(fileTarget, cwd, {label: 'layout target path'});
     } catch (err) {
       if (err instanceof PathSafetyError) {
         throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
       }
       throw err;
     }
-    const filePath = isFilePathArg(targetPath)
-      ? resolved
-      : path.join(resolved, `${componentName}.tsx`);
     fs.mkdirSync(path.dirname(filePath), {recursive: true});
     fs.writeFileSync(filePath, result.code);
     written = path.relative(cwd, filePath);

package/api/layout/expand/expand.path-safety.test.mjs

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Path-safety tests for the `layout.expand` write. The file written, not
+ * only the directory it lands in, must stay inside the project root.
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {layoutExpand} from '../layout.mjs';
+import {buildRegistry} from '../../../foundation/xle/registry.mjs';
+
+const SLOW = 30_000;
+
+// The registry imports every component doc on first use; warm it once.
+beforeAll(async () => {
+  await buildRegistry();
+}, 120_000);
+
+describe('layout.expand — write confinement', () => {
+  it('rejects a directory target whose generated file is a symlink leading outside cwd', async () => {
+    // Inside the workspace so @astryxdesign/core resolves.
+    const cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-confine-test-'));
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'xle-confine-outside-'));
+    try {
+      const victim = path.join(outside, 'victim.tsx');
+      fs.writeFileSync(victim, 'OUTSIDE');
+      fs.mkdirSync(path.join(cwd, 'out'));
+      fs.symlinkSync(victim, path.join(cwd, 'out', 'GeneratedLayout.tsx'));
+
+      await expect(
+        layoutExpand('V > B', {targetPath: './out', cwd}),
+      ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+      expect(fs.readFileSync(victim, 'utf-8')).toBe('OUTSIDE');
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  }, SLOW);
+
+  it('still writes <Name>.tsx into a plain directory target', async () => {
+    const cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-confine-test-'));
+    try {
+      const result = await layoutExpand('V > B', {targetPath: './out', name: 'Demo', cwd});
+      expect(result.data.written).toBe(path.join('out', 'Demo.tsx'));
+      expect(fs.existsSync(path.join(cwd, 'out', 'Demo.tsx'))).toBe(true);
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  }, SLOW);
+});

package/api/layout/grammar/grammar.mjs

@@ -10,6 +10,7 @@
  */
 
 import {buildRegistry} from '../../../foundation/xle/registry.mjs';
+import {MAX_REPEAT} from '../../../foundation/xle/expand.mjs';
 
 /**
  * `astryx layout grammar` — the agent cheatsheet, with the alias table
@@ -50,7 +51,7 @@ NODE ANATOMY   Name#id.enum"payload"[attrs]{hint}*N > children
   .enum        unique enum value of any prop:  Bd.success  Tx.lg  B.primary
   "payload"    primary text prop (label/title/heading) or text child:  TI"Email"  B"Save"
   {hint}       kebab-case template/component reference (see TEMPLATE REFERENCING) — NEVER text
-  *N / xN      repeat (use $ for the counter:  Tk"item-$"*3)
+  *N / xN      repeat, at most ${MAX_REPEAT} copies (use $ for the counter:  Tk"item-$"*3)
   trailing !   initial selection for scaffolded state:  Tab"Overview"!
 
 ATTRS [...] (outline: bare tokens after the name, no brackets)

package/api/layout/layoutExpand.doc.mjs

@@ -36,7 +36,7 @@ export const doc = {
       name: 'options.targetPath',
       type: 'string',
       description:
-        'Write the generated TSX here (validated to stay within cwd). A directory gets <name>.tsx; a file path is used as-is. Omit to return the code without writing.',
+        'Write the generated TSX here (validated to stay within cwd). A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is used as-is; any other path is a directory that gets <name>.tsx. An existing file is replaced. Omit to return the code without writing.',
     },
     {
       name: 'options.form',

package/api/search/search-return-type.test.mjs

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The declared return type of `search()` is the canonical SearchResponse.
+ * Consumers of `@astryxdesign/cli/api` type-check against it; an `object` entry
+ * type erases every result field from their view.
+ */
+
+import {createRequire} from 'node:module';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+
+const require = createRequire(import.meta.url);
+const ts = require('typescript');
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SEARCH = path.join(HERE, 'search.mjs');
+const TYPES = path.join(HERE, 'search.type.mjs');
+
+describe('search() declared return type', () => {
+  it('types each result as the canonical SearchResultEntry', () => {
+    const program = ts.createProgram([SEARCH, TYPES], {
+      allowJs: true,
+      noEmit: true,
+      skipLibCheck: true,
+      types: [],
+      module: ts.ModuleKind.NodeNext,
+      moduleResolution: ts.ModuleResolutionKind.NodeNext,
+      target: ts.ScriptTarget.ES2022,
+    });
+    const checker = program.getTypeChecker();
+    const source = program.getSourceFile(SEARCH);
+    /** @param {string} file @param {string} name */
+    const exportOf = (file, name) =>
+      checker
+        .getExportsOfModule(checker.getSymbolAtLocation(program.getSourceFile(file)))
+        .find((/** @type {any} */ s) => s.name === name);
+    /** @param {any} type @param {string} name */
+    const prop = (type, name) =>
+      checker.getTypeOfSymbolAtLocation(type.getProperty(name), source);
+    /** @param {any} type */
+    const names = type => type.getProperties().map((/** @type {any} */ p) => p.name).sort();
+
+    const fn = checker.getTypeOfSymbolAtLocation(exportOf(SEARCH, 'search'), source);
+    const response = checker.getAwaitedType(fn.getCallSignatures()[0].getReturnType());
+    const data = prop(response, 'data');
+    expect(names(data)).toEqual(['matchCount', 'query', 'results']);
+    const entry = checker.getIndexTypeOfType(prop(data, 'results'), ts.IndexKind.Number);
+    const canonical = checker.getDeclaredTypeOfSymbol(exportOf(TYPES, 'SearchResultEntry'));
+    expect(names(canonical)).toContain('command');
+    expect(names(entry)).toEqual(names(canonical));
+  }, 30_000);
+});

package/api/search/search.d.mts

@@ -68,20 +68,13 @@ export function scoreCandidate(term: string, { name, keywords, weakKeywords, des
  * @param {string} [options.cwd]
  * @param {'component'|'hook'|'doc'|'template'} [options.type] - Restrict to one domain.
  * @param {number} [options.limit] - Max results (default 20).
- * @returns {Promise<{type: 'search', data: {query: string, matchCount: number, results: Array<object>}}>}
+ * @returns {Promise<import('./search.type.mjs').SearchResponse>}
  */
 export function search(query: string, options?: {
     cwd?: string | undefined;
     type?: "component" | "hook" | "doc" | "template" | undefined;
     limit?: number | undefined;
-}): Promise<{
-    type: "search";
-    data: {
-        query: string;
-        matchCount: number;
-        results: Array<object>;
-    };
-}>;
+}): Promise<import("./search.type.mjs").SearchResponse>;
 /** Valid domain filters for `--type`. */
 export const SEARCH_DOMAINS: string[];
 /**

package/api/search/search.doc.mjs

@@ -53,7 +53,7 @@ export const doc = {
     {
       type: 'search',
       description:
-        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit` (domain, name, score, reason, description, follow-up command, and import path where relevant).',
+        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, and `displayName` and `kind` for templates.',
     },
   ],
   throws: [
@@ -61,6 +61,10 @@ export const doc = {
       code: 'ERR_INVALID_ARGUMENT',
       when: 'the query is empty, --type is unknown, or --limit is not a positive integer',
     },
+    {
+      code: 'ERR_CORE_NOT_FOUND',
+      when: '@astryxdesign/core cannot be found from the cwd',
+    },
   ],
   examples: [
     {label: 'Find a component', code: "const r = await search('button');"},

package/api/search/search.mjs

@@ -884,7 +884,7 @@ function toResult(c, score, reason, matchedTerms, queryTerms) {
  * @param {string} [options.cwd]
  * @param {'component'|'hook'|'doc'|'template'} [options.type] - Restrict to one domain.
  * @param {number} [options.limit] - Max results (default 20).
- * @returns {Promise<{type: 'search', data: {query: string, matchCount: number, results: Array<object>}}>}
+ * @returns {Promise<import('./search.type.mjs').SearchResponse>}
  */
 export async function search(query, options = {}) {
   const {cwd = process.cwd(), type, limit = 20} = options;
@@ -921,7 +921,11 @@ export async function search(query, options = {}) {
 
   const coreDir = findCoreDir(cwd);
   if (!coreDir) {
-    throw new AstryxError('Could not find @astryxdesign/core package');
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
   }
 
   // Gather candidates from each requested domain in parallel.
@@ -971,7 +975,10 @@ export async function search(query, options = {}) {
     data: {
       query: String(query).trim(),
       matchCount: scored.length,
-      results: limited,
+      // toResult gives every domain its command and domain fields.
+      results: /** @type {import('./search.type.mjs').SearchResultEntry[]} */ (
+        limited
+      ),
     },
   };
 }