@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout expand',
   displayName: 'astryx layout expand',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Expand a layout expression into validated XDS TSX',
   description:
     'Parses and validates a compressed XLE/XLO expression, then expands it into ' +
@@ -21,11 +21,28 @@ export const doc = {
     'interactive controls, and splicing referenced blocks. Writes to a path, or returns the code.',
   fn: 'layoutExpand',
   args: [
-    {name: 'expression', param: 'expression', required: false},
-    {name: 'path', param: 'options.targetPath', required: false},
+    {
+      name: 'expression',
+      param: 'expression',
+      required: false,
+      description:
+        'The XLE/XLO expression. Pass - to read it from stdin; --file reads it from a file instead.',
+    },
+    {
+      name: 'path',
+      param: 'options.targetPath',
+      required: false,
+      description:
+        'Where to write the TSX, relative to the project root. A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is the file to write; ' +
+        'any other path is a directory, which receives <Name>.tsx (see --name). An existing file there is replaced. ' +
+        'Omit it to print the code.',
+    },
   ],
   options: [
-    {flag: '--file <file>', description: 'Read the expression from a file'},
+    {
+      flag: '--file <file>',
+      description: 'Read the expression from a file (used instead of the argument when both are given)',
+    },
     {
       flag: '--form <form>',
       param: 'options.form',
@@ -59,7 +76,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'a missing/empty expression, a bad --name or --form, a parse/validation error, or a path escape',
+      when: 'a missing, empty or over-5 MB expression (from stdin or --file), a bad --name or --form, a parse/validation error, or a path escape',
     },
   ],
   related: ['layout check', 'layout grammar'],

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout grammar',
   displayName: 'astryx layout grammar',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary:
     'Print the XLE/XLO cheatsheet (alias table generated from this branch)',
   description:

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'layout',
   displayName: 'astryx layout',
-  namespace: 'cli',
+  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 ' +
@@ -27,8 +27,8 @@ export const doc = {
     },
   ],
   exitCodes: [
-    {code: 0, when: 'success (help shown, or a subcommand succeeded)'},
-    {code: 1, when: 'an unknown subcommand'},
+    {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.mjs

@@ -59,6 +59,9 @@ import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
  * @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]
@@ -78,8 +81,7 @@ async function readExpression(expr, options = {}) {
         code: ERROR_CODES.ERR_FILE_NOT_FOUND,
       });
     }
-    const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5 MB
-    if (stat.size > MAX_FILE_SIZE) {
+    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},
@@ -100,9 +102,19 @@ async function readExpression(expr, options = {}) {
     }
   }
   if (expr === '-') {
+    // Capped like --file: an endless stream must not be buffered whole.
     /** @type {Buffer[]} */
     const chunks = [];
-    for await (const chunk of process.stdin) chunks.push(/** @type {Buffer} */ (chunk));
+    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 ?? '';
@@ -154,15 +166,15 @@ export function registerLayout(program) {
       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},
             {
-              components: result.data.componentsUsed,
-              todos:
-                result.data.todos.length > 0
-                  ? `${result.data.todos.length} (search for "TODO(xle)")`
-                  : '',
+              format: {
+                todos: (/** @type {string[]} */ todos) =>
+                  `${todos.length} (search for "TODO(xle)")`,
+              },
             },
-            {labels: {components: 'Components', todos: 'TODOs'}},
           ),
         );
       } else {

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'manifest',
   displayName: 'astryx manifest',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Print the full CLI capability manifest (use with --json).',
   description:
     'Emits the complete CLI surface: every command with its arguments, options, ' +
@@ -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: 'Shorthand', cli: 'astryx --json'},
+    {label: 'The same manifest, under data.manifest (type "help")', cli: 'astryx --json'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},

package/clients/cli/commands/no-prompt-wording.test.mjs

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The CLI never asks a question, so no help text, manifest entry or
+ * error-code description may say a flag skips a prompt. Each flag's text states
+ * what happens without it instead, and the CLI does that.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {doc as errorCodesDoc} from '../../../foundation/response/error-codes.doc.mjs';
+import {doc as upgradeFn} from '../../../api/upgrade/upgrade.doc.mjs';
+
+const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+const SLOW = 30_000;
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-prompt-'));
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * One option's description from the manifest (subcommands are nested).
+ * @param {string} command @param {string} flag
+ */
+async function optionText(command, flag) {
+  const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
+  /** @typedef {{name: string, options: Array<{flag: string, description: string}>, subcommands?: ManifestCommand[]}} ManifestCommand */
+  /** @param {ManifestCommand[]} list @returns {ManifestCommand | undefined} */
+  const find = list => {
+    for (const c of list) {
+      const hit = c.name === command ? c : find(c.subcommands ?? []);
+      if (hit) return hit;
+    }
+    return undefined;
+  };
+  const cmd = find(JSON.parse(stdout).data.commands);
+  return cmd?.options.find(o => o.flag.includes(flag))?.description ?? '';
+}
+
+describe('no help text describes a prompt', () => {
+  it('theme add --overwrite states the refusal, and a refused run writes nothing', async () => {
+    const help = await optionText('theme add', '--overwrite');
+    expect(help).not.toMatch(/prompt/i);
+    expect(help).toContain('ERR_FILE_EXISTS');
+    expect(help).toMatch(/nothing is written/);
+
+    const first = await runCli(['--json', 'theme', 'add', 'matcha'], tmpDir);
+    expect(first.status).toBe(0);
+    const {outputDir, files} = JSON.parse(first.stdout).data;
+    expect(files.length).toBeGreaterThan(1);
+    const dir = path.join(tmpDir, outputDir);
+    fs.writeFileSync(path.join(dir, files[0]), '// edited\n');
+    fs.rmSync(path.join(dir, files[1]));
+
+    const refused = await runCli(['--json', 'theme', 'add', 'matcha'], tmpDir);
+    expect(refused.status).toBe(1);
+    expect(JSON.parse(refused.stdout).code).toBe('ERR_FILE_EXISTS');
+    expect(fs.readFileSync(path.join(dir, files[0]), 'utf8')).toBe('// edited\n');
+    expect(fs.existsSync(path.join(dir, files[1]))).toBe(false);
+  }, SLOW);
+
+  it('upgrade --install-deps names the failure without it, in help and in the API doc', async () => {
+    const help = await optionText('upgrade', '--install-deps');
+    const param = upgradeFn.params?.find(p => p.name === 'options.installDeps')?.description ?? '';
+    for (const text of [help, param]) {
+      expect(text).not.toMatch(/prompt/i);
+      expect(text).toContain('ERR_DEP_MISSING');
+    }
+  }, SLOW);
+
+  it('ERR_FILE_EXISTS is described without an interactive mode, in the code set, its doc and the README table', () => {
+    const member = errorCodesDoc.members.find(m => m.value === 'ERR_FILE_EXISTS');
+    expect(member?.description).toBe('Refused to overwrite an existing file.');
+
+    const source = fs.readFileSync(path.join(CLI_ROOT, 'foundation/response/error-codes.mjs'), 'utf8');
+    expect(source).toMatch(/\/\*\* Refused to overwrite an existing file\. \*\/\s*ERR_FILE_EXISTS:/);
+
+    const readme = fs.readFileSync(path.join(CLI_ROOT, 'README.md'), 'utf8');
+    const row = readme.split('\n').find(line => line.startsWith('| `ERR_FILE_EXISTS`'));
+    expect(row).toMatch(/\| Refused to overwrite an existing file\.\s+\|$/);
+  });
+});

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

@@ -12,13 +12,16 @@ export const doc = {
   type: 'command',
   name: 'search',
   displayName: 'astryx search',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   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.',
+    '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.',
   fn: 'search',
-  args: [{name: 'query', param: 'query', required: true}],
+  // 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}],
   options: [
     {
       flag: '--type <domain>',
@@ -29,15 +32,19 @@ export const doc = {
     {
       flag: '--limit <n>',
       param: 'options.limit',
-      description: 'Max number of results (default 20)',
+      description: 'Max number of results, a positive integer (default 20)',
     },
     {
       flag: '--verbose',
-      description: 'Verbose output (include import paths and match reason)',
+      description: "Also print each result's score and match reason",
     },
   ],
   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',
@@ -45,7 +52,10 @@ export const doc = {
   ],
   exitCodes: [
     {code: 0, when: 'success (including zero matches)'},
-    {code: 1, when: 'invalid --type or a non-positive --limit'},
+    {
+      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',
+    },
   ],
   related: ['component', 'hook', 'docs', 'template', 'build'],
 };

package/clients/cli/commands/search.mjs

@@ -14,9 +14,10 @@
  *
  * 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       Verbose (include import / reason)
+ *   astryx search button --verbose       Also print score / reason
  *   astryx search button --json          Typed JSON envelope
  */
 
@@ -31,6 +32,7 @@ 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';
@@ -42,23 +44,25 @@ export function registerSearch(program) {
   defineCommand(program, searchCommand, {
     fn: searchFn,
     action: async (
-      /** @type {string} */ query,
+      /** @type {string[] | string} */ words,
       /** @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());
-        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+        await warnOnIntegrationIssues(project, {json});
       } catch {
         // Never let the nudge break the command.
       }
 
-      // Parse --limit to a number; the API validates it (positive integer) and
-      // throws ERR_INVALID_ARGUMENT, so we pass NaN through rather than
-      // pre-rejecting with a generic code here.
-      const limit =
-        options.limit != null ? Number.parseInt(options.limit, 10) : 20;
+      // Number(), not parseInt(): parseInt truncates `1.5` and `5abc` into
+      // integers the API would reject. The API validates the value, so the
+      // flag and `search({limit})` accept and refuse the same inputs.
+      const limit = options.limit != null ? Number(options.limit) : 20;
 
       /** @type {import('../../../api/search/search.type.mjs').SearchResponse} */
       let result;
@@ -100,12 +104,25 @@ 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}".`),
-          text(`Try a broader term, or browse: ${run} component --list`),
+          ...note,
+          text(
+            `Try a broader term, or browse: ${run} ${note.length > 0 ? 'docs' : 'component --list'}`,
+          ),
         );
         return answered;
       }
@@ -116,15 +133,32 @@ export function registerSearch(program) {
       const fields = options.verbose
         ? [
             'name',
+            'section',
             'domain',
+            'package',
+            'title',
             'displayName',
+            'kind',
             'score',
             'reason',
             'import',
             'description',
             'command',
+            'parent',
           ]
-        : ['name', 'domain', 'displayName', 'import', 'description', 'command'];
+        : [
+            'name',
+            'section',
+            'domain',
+            'package',
+            'title',
+            'displayName',
+            'kind',
+            'import',
+            'description',
+            'command',
+            'parent',
+          ];
 
       // The heading mirrors the JSON: `matchCount` is what matched, and the
       // records below are the slice `--limit` allowed. Saying only "(20)" when
@@ -135,7 +169,11 @@ export function registerSearch(program) {
             ? `Results for "${q}" (${results.length} of ${matchCount})`
             : `Results for "${q}" (${results.length})`,
         ),
-        records(results, {fields, format: {command: formatCliCommand}}),
+        records(results, {
+          fields,
+          format: {command: formatCliCommand, parent: formatCliCommand},
+        }),
+        ...note,
       );
       return answered;
     },