@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

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

@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for the `astryx layout` command group. A parent group with no
+ * behavior of its own; it dispatches to the expand/check/grammar subcommands,
+ * which carry the actual args, flags, and wrapped functions.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'layout',
+  displayName: 'astryx layout',
+  namespace: 'cli/commands',
+  summary: 'Generate XDS layouts from compressed expressions (XLE/XLO)',
+  description:
+    'The layout command group. Running astryx layout with no subcommand prints the ' +
+    'subcommand list; the work happens in the subcommands: expand an expression into ' +
+    'TSX (expand), validate one (check), or print the grammar cheatsheet (grammar).',
+  subcommands: ['expand', 'check', 'grammar'],
+  examples: [
+    {label: 'Print the grammar', cli: 'astryx layout grammar'},
+    {
+      label: 'Expand to TSX',
+      cli: "astryx layout expand 'V[g6] > C{card-callout}*4' ./src/Page.tsx",
+    },
+  ],
+  exitCodes: [
+    {code: 0, when: 'a subcommand succeeded, or --help'},
+    {code: 1, when: 'no subcommand (help is printed) or an unknown subcommand'},
+  ],
+  related: ['template', 'build'],
+};

package/clients/cli/commands/layout.error-codes.test.mjs

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Error-code contract tests for the layout command wrapper. Locks the
+ * two foreseeable input errors to STABLE ERR_* codes (never ERR_UNKNOWN or a
+ * raw fs errno) and asserts --json/human exit parity:
+ *   - empty expression  → ERR_MISSING_ARGUMENT
+ *   - --file <missing>  → ERR_FILE_NOT_FOUND (not raw ENOENT), no stack leak
+ * Spawns the real binary so the bin error boundary is exercised faithfully.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../bin/astryx.mjs');
+
+function run(args) {
+  const res = spawnSync('node', [CLI_BIN, ...args], {
+    encoding: 'utf-8',
+    timeout: 20_000,
+  });
+  return {status: res.status, stdout: res.stdout || '', stderr: res.stderr || ''};
+}
+
+describe('layout --json error codes', () => {
+  for (const sub of ['expand', 'check']) {
+    it(`layout ${sub} "" → ERR_MISSING_ARGUMENT (not ERR_UNKNOWN)`, () => {
+      const r = run(['--json', 'layout', sub, '']);
+      expect(r.status).toBe(1);
+      const env = JSON.parse(r.stdout);
+      expect(env.code).toBe('ERR_MISSING_ARGUMENT');
+      expect(r.stderr).toBe('');
+      expect(r.stdout).not.toMatch(/\n\s+at /); // no stack frames
+    });
+
+    it(`layout ${sub} --file <missing> → ERR_FILE_NOT_FOUND (not ENOENT)`, () => {
+      const r = run([
+        '--json',
+        'layout',
+        sub,
+        '--file',
+        '/tmp/definitely-missing-astryx-xyz.mjs',
+      ]);
+      expect(r.status).toBe(1);
+      const env = JSON.parse(r.stdout);
+      expect(env.code).toBe('ERR_FILE_NOT_FOUND');
+      expect(r.stderr).toBe('');
+    });
+
+    it(`layout ${sub}: --json and human agree on exit code (empty input)`, () => {
+      const human = run(['layout', sub, '']);
+      const json = run(['--json', 'layout', sub, '']);
+      expect(json.status).toBe(human.status);
+      expect(json.status).toBe(1);
+    });
+
+    it(`layout ${sub} --file <missing> in human mode leaks no stack trace`, () => {
+      const r = run(['layout', sub, '--file', '/tmp/definitely-missing-astryx-xyz.mjs']);
+      expect(r.status).toBe(1);
+      expect(r.stderr).not.toMatch(/\n\s+at /);
+    });
+  }
+});

package/clients/cli/commands/layout.exit-parity.test.mjs

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CLI-level tests for `astryx layout check` exit-code parity.
+ *
+ * The exit code is the contract and must NOT depend on --json vs human mode:
+ * an invalid (but parseable) layout exits 1 in BOTH modes so `layout check`
+ * works as a CI gate / agent check without parsing stdout. Runs the real
+ * program in-process via the shared runCli harness.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const SLOW = 30_000;
+// Parses fine, but references an unknown component -> data.valid: false
+// (a semantic error, surfaced as data, not a thrown ERR_LAYOUT_PARSE).
+const INVALID = 'ZzzUnknownComponent[foo=bar]';
+const VALID = 'K';
+
+describe('layout check — exit-code parity (--json vs human)', () => {
+  it('human mode exits 1 for an invalid (parseable) expression', async () => {
+    const {status} = await runCli(['layout', 'check', INVALID]);
+    expect(status).toBe(1);
+  }, SLOW);
+
+  it('--json exits 1 for the SAME invalid expression (modes agree)', async () => {
+    const {status, stdout} = await runCli(['layout', 'check', INVALID, '--json']);
+    const env = JSON.parse(stdout);
+    expect(env.type).toBe('layout.check');
+    expect(env.data.valid).toBe(false);
+    expect(status).toBe(1);
+  }, SLOW);
+
+  it('a valid expression exits 0 in both modes', async () => {
+    expect((await runCli(['layout', 'check', VALID])).status).toBe(0);
+    const {status, stdout} = await runCli(['layout', 'check', VALID, '--json']);
+    expect(JSON.parse(stdout).data.valid).toBe(true);
+    expect(status).toBe(0);
+  }, SLOW);
+});

package/clients/cli/commands/layout.mjs

@@ -0,0 +1,275 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layout command — thin CLI wrapper around api/layout.mjs.
+ *
+ * Subcommands:
+ *   astryx layout expand "<expr>" [path]   compressed expression → validated TSX
+ *   astryx layout check "<expr>"           validate + echo both canonical surfaces
+ *   astryx layout grammar                  agent cheatsheet (alias table is branch-generated)
+ *
+ * The expression argument may also come from --file or stdin (`-`),
+ * which is how multi-line outline (XLO) input usually arrives.
+ *
+ * The command surface (group + subcommand descriptions, args, flags) is sourced
+ * from the colocated CommandDocs via `defineCommand`; this file supplies only the
+ * actions.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, list, record, code, WARN} from '../formatters/index.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {layoutExpand, layoutCheck, layoutGrammar} from '../../../api/layout/layout.mjs';
+import {defineCommand} from '../lib/define-command.mjs';
+import {doc as layoutGroup} from './layout.doc.mjs';
+import {doc as layoutExpandCommand} from './layout-expand.doc.mjs';
+import {doc as layoutCheckCommand} from './layout-check.doc.mjs';
+import {doc as layoutGrammarCommand} from './layout-grammar.doc.mjs';
+import {doc as layoutExpandFn} from '../../../api/layout/layoutExpand.doc.mjs';
+import {doc as layoutCheckFn} from '../../../api/layout/layoutCheck.doc.mjs';
+import {doc as layoutGrammarFn} from '../../../api/layout/layoutGrammar.doc.mjs';
+import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
+
+/**
+ * The api layer's @returns for these functions widen the `type` discriminator
+ * to `string`, so annotate the command-local result with the precise response
+ * shapes from the colocated api/layout/layout.type.mjs so narrowing + jsonOut
+ * typecheck.
+ *
+ * @typedef {import('../../../api/layout/layout.type.mjs').LayoutExpandResponse} LayoutExpandResponse
+ * @typedef {import('../../../api/layout/layout.type.mjs').LayoutCheckResponse} LayoutCheckResponse
+ * @typedef {import('../../../api/layout/layout.type.mjs').LayoutGrammarResponse} LayoutGrammarResponse
+ */
+
+/**
+ * @typedef {object} LayoutExpandOptions
+ * @property {string} [file]
+ * @property {'compact'|'outline'|'auto'} [form]
+ * @property {string} [name]
+ * @property {boolean} [loose]
+ */
+
+/**
+ * @typedef {object} LayoutCheckOptions
+ * @property {string} [file]
+ * @property {'compact'|'outline'|'auto'} [form]
+ * @property {boolean} [loose]
+ */
+
+/** The largest layout expression read from --file or stdin. */
+const MAX_EXPRESSION_BYTES = 5 * 1024 * 1024; // 5 MB
+
+/**
+ * Resolve the expression from arg, --file, or stdin ('-').
+ * @param {string} [expr]
+ * @param {{file?: string}} [options]
+ * @returns {Promise<string>}
+ */
+async function readExpression(expr, options = {}) {
+  if (options.file) {
+    // Validate the file exists + is a regular file + is reasonably sized.
+    // We intentionally do NOT confine the read path (the user running the CLI
+    // controls --file; this is a read, not a write). The size cap prevents OOM
+    // from infinite streams like /dev/zero.
+    const filePath = path.resolve(process.cwd(), options.file);
+    const stat = fs.statSync(filePath, {throwIfNoEntry: false});
+    if (!stat || !stat.isFile()) {
+      cliError(`File not found: ${options.file}`, {
+        code: ERROR_CODES.ERR_FILE_NOT_FOUND,
+      });
+    }
+    if (stat.size > MAX_EXPRESSION_BYTES) {
+      cliError(
+        `File "${options.file}" is too large (${(stat.size / 1024 / 1024).toFixed(1)} MB, max 5 MB)`,
+        {code: ERROR_CODES.ERR_FILE_NOT_FOUND},
+      );
+    }
+    try {
+      return fs.readFileSync(filePath, 'utf-8');
+    } catch (e) {
+      const errno = /** @type {NodeJS.ErrnoException} */ (e);
+      if (errno && errno.code === 'ENOENT') {
+        // A --file pointing at a missing file is foreseeable — surface a
+        // stable code, not the raw ENOENT errno (and no stack in human mode).
+        cliError(`File not found: ${options.file}`, {
+          code: ERROR_CODES.ERR_FILE_NOT_FOUND,
+        });
+      }
+      throw e;
+    }
+  }
+  if (expr === '-') {
+    // Capped like --file: an endless stream must not be buffered whole.
+    /** @type {Buffer[]} */
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+      size += /** @type {Buffer} */ (chunk).length;
+      if (size > MAX_EXPRESSION_BYTES) {
+        cliError('The layout expression on stdin is too large (max 5 MB)', {
+          code: ERROR_CODES.ERR_INVALID_ARGUMENT,
+        });
+      }
+      chunks.push(/** @type {Buffer} */ (chunk));
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+  }
+  return expr ?? '';
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+export function registerLayout(program) {
+  const layoutCmd = defineCommand(program, layoutGroup);
+
+  defineCommand(layoutCmd, layoutExpandCommand, {
+    fn: layoutExpandFn,
+    action: async (/** @type {string} */ expression, /** @type {string} */ targetPath, /** @type {LayoutExpandOptions} */ options) => {
+      const json = program.opts().json || false;
+      const source = await readExpression(expression, options);
+      if (!source || source.trim() === '') {
+        return cliError(
+          'No layout expression given — pass it as an argument, via --file, or on stdin',
+          {code: ERROR_CODES.ERR_MISSING_ARGUMENT},
+        );
+      }
+      /** @type {LayoutExpandResponse} */
+      let result;
+      try {
+        result = /** @type {LayoutExpandResponse} */ (await layoutExpand(source, {
+          targetPath,
+          form: options.form,
+          loose: options.loose || false,
+          name: options.name,
+          cwd: process.cwd(),
+        }));
+      } catch (e) {
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
+      }
+      // Expanding turns an expression into TSX — a transformation, not a
+      // lookup. What it produced is in the output; there is no set to count.
+      if (json) {
+        jsonOut(result);
+        return NO_RESULT_SET;
+      }
+
+      /** @type {import('../formatters/index.mjs').Block[]} */
+      const out = [];
+      if (result.data.warnings.length > 0) {
+        out.push(text(result.data.warnings.map(w => `${WARN} ${w}`).join('\n')));
+      }
+      if (result.data.written) {
+        out.push(
+          text(`[ok] Expanded to ${result.data.written}`),
+          // Field names are the JSON keys; todos are summarised, not listed.
+          record(
+            {componentsUsed: result.data.componentsUsed, todos: result.data.todos},
+            {
+              format: {
+                todos: (/** @type {string[]} */ todos) =>
+                  `${todos.length} (search for "TODO(xle)")`,
+              },
+            },
+          ),
+        );
+      } else {
+        // Raw expanded TSX (no target path) — preformatted, emitted verbatim.
+        out.push(code(result.data.code));
+      }
+      emit(...out);
+      return NO_RESULT_SET;
+    },
+  });
+
+  defineCommand(layoutCmd, layoutCheckCommand, {
+    fn: layoutCheckFn,
+    action: async (/** @type {string} */ expression, /** @type {LayoutCheckOptions} */ options) => {
+      const json = program.opts().json || false;
+      const source = await readExpression(expression, options);
+      if (!source || source.trim() === '') {
+        return cliError(
+          'No layout expression given — pass it as an argument, via --file, or on stdin',
+          {code: ERROR_CODES.ERR_MISSING_ARGUMENT},
+        );
+      }
+      /** @type {LayoutCheckResponse} */
+      let result;
+      try {
+        result = /** @type {LayoutCheckResponse} */ (await layoutCheck(source, {
+          form: options.form,
+          loose: options.loose || false,
+          cwd: process.cwd(),
+        }));
+      } catch (e) {
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
+      }
+      // Exit code is the contract and must NOT depend on --json vs human: an
+      // invalid (but parseable) layout exits 1 in BOTH modes so `layout check`
+      // works as a CI gate / agent check without parsing stdout. Decide it
+      // before the JSON return (parity with doctor integration validate).
+      if (!result.data.valid) process.exitCode = 1;
+
+      // A verdict on one expression: valid or not, with the errors that made
+      // it so. Nothing was looked up.
+      if (json) {
+        jsonOut(result);
+        return NO_RESULT_SET;
+      }
+
+      const {valid, form, errors, warnings, compact, outline} = result.data;
+      if (!valid) {
+        // Each error: the formatted issue, with a hanging "did you mean" line.
+        const items = errors.map(e =>
+          e.suggestions && e.suggestions.length > 0
+            ? [e.formatted, `did you mean: ${e.suggestions.join(', ')}?`]
+            : [e.formatted],
+        );
+        emit(
+          text(`[fail] Invalid (${errors.length} error${errors.length === 1 ? '' : 's'}):`),
+          list(items),
+        );
+        return NO_RESULT_SET;
+      }
+
+      /** @type {import('../formatters/index.mjs').Block[]} */
+      const out = [text(`[ok] Valid (parsed as ${form})`)];
+      if (warnings.length > 0) {
+        out.push(text(warnings.map(w => `${WARN} ${w}`).join('\n')));
+      }
+      // The canonical compact/outline surfaces are preformatted — emit verbatim.
+      out.push(section('compact'), code(compact), section('outline'), code(outline));
+      emit(...out);
+      return NO_RESULT_SET;
+    },
+  });
+
+  defineCommand(layoutCmd, layoutGrammarCommand, {
+    fn: layoutGrammarFn,
+    action: async () => {
+      const json = program.opts().json || false;
+      /** @type {LayoutGrammarResponse} */
+      let result;
+      try {
+        result = /** @type {LayoutGrammarResponse} */ (await layoutGrammar({cwd: process.cwd()}));
+      } catch (e) {
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
+      }
+      // One document, the same one every time: the grammar cheatsheet.
+      const answered = resultSet({count: 1, resultKind: 'doc'});
+      if (json) {
+        jsonOut(result);
+        return answered;
+      }
+      // The cheatsheet is a preformatted document — emit verbatim.
+      emit(code(result.data.text));
+      return answered;
+    },
+  });
+}

package/clients/cli/commands/layout.path-help.test.mjs

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout expand` and `layout check` document their input modes (the
+ * argument, `-` for stdin, --file) and where `layout expand` writes.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {isFilePathArg} from '../../../foundation/fs/path-safety.mjs';
+
+const SLOW = 30_000;
+
+describe('layout argument behavior is documented', () => {
+  it('layout expand help covers stdin, --file precedence and the output path rule', async () => {
+    const {status, stdout} = await runCli(['layout', 'expand', '--help']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Pass - to read it from stdin/);
+    expect(stdout).toMatch(/instead of the argument/);
+    expect(stdout).toContain('<Name>.tsx');
+    expect(stdout).toMatch(/existing file there is replaced/);
+    const exts = [...(stdout.match(/ends in ([.\w, ]+ or \.\w+)/)?.[1] ?? '').matchAll(/\.\w+/g)];
+    expect(exts.length).toBeGreaterThan(0);
+    for (const [ext] of exts) expect(isFilePathArg(`src/Page${ext}`)).toBe(true);
+  }, SLOW);
+
+  it('layout check help covers stdin and --file precedence', async () => {
+    const {status, stdout} = await runCli(['layout', 'check', '--help']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Pass - to read it from stdin/);
+    expect(stdout).toMatch(/instead of the argument/);
+  }, SLOW);
+});

package/clients/cli/commands/layout.stdin-cap.test.mjs

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout check -` reads the expression from stdin under the same 5 MB
+ * cap as --file, instead of buffering whatever the pipe delivers. Spawns the
+ * real bin, since the in-process harness has no stdin.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.resolve(HERE, '../bin/astryx.mjs');
+// Run against the monorepo root so @astryxdesign/core is discoverable.
+const REPO = path.resolve(HERE, '../../../..');
+const SLOW = 60_000;
+
+/** @param {string} input @param {string[]} [extra] */
+function checkFromStdin(input, extra = []) {
+  return spawnSync(process.execPath, [BIN, 'layout', 'check', '-', ...extra], {
+    cwd: REPO,
+    input,
+    encoding: 'utf-8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+describe('layout check - (stdin)', () => {
+  it('refuses more than 5 MB with ERR_INVALID_ARGUMENT, in both modes', () => {
+    // Valid once trimmed, so only the cap can reject it.
+    const big = ' '.repeat(5 * 1024 * 1024 + 1) + 'V';
+    const json = checkFromStdin(big, ['--json']);
+    expect(json.status).toBe(1);
+    expect(JSON.parse(json.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+    const human = checkFromStdin(big);
+    expect(human.status).toBe(1);
+    expect(human.stderr + human.stdout).toMatch(/too large/);
+  }, SLOW);
+
+  it('still reads a normal expression', () => {
+    const r = checkFromStdin('V > B', ['--json']);
+    expect(r.status).toBe(0);
+    expect(JSON.parse(r.stdout).data.valid).toBe(true);
+  }, SLOW);
+});

package/clients/cli/commands/layout.text-fields.test.mjs

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout expand` text output names its fields after the JSON keys, so
+ * the two views stay greppable against each other.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const SLOW = 60_000;
+
+describe('layout expand text fields mirror the JSON keys', () => {
+  let cwd;
+  beforeEach(() => {
+    // Inside the workspace so @astryxdesign/core resolves.
+    cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-text-fields-'));
+  });
+  afterEach(() => fs.rmSync(cwd, {recursive: true, force: true}));
+
+  it('labels every record field with a key of the layout.expand data', async () => {
+    const expr = 'V > B + {not-a-real-block}';
+    const json = await runCli(['layout', 'expand', expr, './a', '--loose', '--json'], cwd);
+    expect(json.status).toBe(0);
+    const {data} = JSON.parse(json.stdout);
+    expect(data.todos.length).toBeGreaterThan(0);
+
+    const human = await runCli(['layout', 'expand', expr, './b', '--loose'], cwd);
+    expect(human.status).toBe(0);
+    const fields = human.stdout
+      .split('\n')
+      .map(line => /^([A-Za-z]+):\s/.exec(line)?.[1])
+      .filter(Boolean);
+    expect(fields).toEqual(['componentsUsed', 'todos']);
+    for (const field of fields) expect(Object.keys(data)).toContain(field);
+  }, SLOW);
+});

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

@@ -20,7 +20,7 @@ export const doc = {
     'tooling to introspect. Intended to be run with --json.',
   examples: [
     {label: 'Full manifest', cli: 'astryx manifest --json'},
-    {label: 'The same manifest, under data.manifest (type "help")', cli: 'astryx --json'},
+    {label: 'Shorthand', cli: 'astryx --json'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},

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

@@ -16,12 +16,9 @@ export const doc = {
   summary: 'Search components, hooks, docs, and templates in one ranked list',
   description:
     'Terminal front-end to search(): prints one ranked, greppable list across ' +
-    'every content domain, each row carrying a follow-up command to act on it. ' +
-    'Outside an app, where @astryxdesign/core is not installed, it searches the docs.',
+    'every content domain, each row carrying a follow-up command to act on it.',
   fn: 'search',
-  // Every word after `search` is the query: `astryx search dark mode` searches
-  // for "dark mode", with no quotes needed.
-  args: [{name: 'query', param: 'query', required: true, variadic: true}],
+  args: [{name: 'query', param: 'query', required: true}],
   options: [
     {
       flag: '--type <domain>',
@@ -41,10 +38,6 @@ export const doc = {
   ],
   examples: [
     {label: 'Ranked results', cli: 'astryx search button'},
-    {
-      label: 'Several words, no quotes',
-      cli: 'astryx search dark mode --type doc',
-    },
     {
       label: 'Filter + JSON',
       cli: 'astryx search "data table" --type template --json',
@@ -54,7 +47,7 @@ export const doc = {
     {code: 0, when: 'success (including zero matches)'},
     {
       code: 1,
-      when: 'invalid --type, a --limit that is not a positive integer, or --type component, hook, or template where @astryxdesign/core cannot be found',
+      when: 'invalid --type, a --limit that is not a positive integer, or @astryxdesign/core cannot be found',
     },
   ],
   related: ['component', 'hook', 'docs', 'template', 'build'],

package/clients/cli/commands/search.mjs

@@ -14,7 +14,6 @@
  *
  * Usage:
  *   astryx search button                 Ranked results across all domains
- *   astryx search dark mode              Every word is part of the query
  *   astryx search modal --type component Filter to a single domain
  *   astryx search forms --limit 5        Cap the result count
  *   astryx search button --verbose       Also print score / reason
@@ -32,7 +31,6 @@ import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {search as searchApi} from '../../../api/search/search.mjs';
 import {Project} from '../../../foundation/config/project.mjs';
-import {findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
 import {doc as searchCommand} from './search.doc.mjs';
 import {doc as searchFn} from '../../../api/search/search.doc.mjs';
@@ -44,13 +42,10 @@ export function registerSearch(program) {
   defineCommand(program, searchCommand, {
     fn: searchFn,
     action: async (
-      /** @type {string[] | string} */ words,
+      /** @type {string} */ query,
       /** @type {{type?: import('../../../api/search/search.type.mjs').SearchDomain, limit?: string, verbose?: boolean}} */ options,
     ) => {
       const json = program.opts().json || false;
-      // The query is variadic: `astryx search dark mode` is one query, "dark
-      // mode". Taking only the first word dropped the rest without a word.
-      const query = Array.isArray(words) ? words.join(' ') : words;
 
       try {
         const project = await Project.load(process.cwd());
@@ -104,25 +99,12 @@ export function registerSearch(program) {
       // ── Text output ──────────────────────────────────────────────
       const run = getCliInvocation();
       const {query: q, matchCount, results} = result.data;
-      // Outside an app an open search covers the docs alone. Say so, so a
-      // docs-only list does not read as "Astryx has no such component".
-      const note =
-        !options.type && !findCoreDir(process.cwd())
-          ? [
-              text(
-                '@astryxdesign/core is not installed here, so only the docs were searched.',
-              ),
-            ]
-          : [];
 
       // No matches is a valid, successful outcome — clean message, exit 0.
       if (results.length === 0) {
         emit(
           text(`No results for "${q}".`),
-          ...note,
-          text(
-            `Try a broader term, or browse: ${run} ${note.length > 0 ? 'docs' : 'component --list'}`,
-          ),
+          text(`Try a broader term, or browse: ${run} component --list`),
         );
         return answered;
       }
@@ -173,7 +155,6 @@ export function registerSearch(program) {
           fields,
           format: {command: formatCliCommand, parent: formatCliCommand},
         }),
-        ...note,
       );
       return answered;
     },