@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/clients/cli/commands/interactive-guard.test.mjs

@@ -1,17 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Subprocess no-hang tests for `astryx init`.
+ * @file Subprocess no-hang tests: the CLI never waits on stdin (INV1).
  *
- * TTY was removed from the CLI: `init` is non-interactive by default and must
- * run cleanly (exit 0, writing the agent cheat sheet) instead of hanging on a
- * prompt. These tests spawn the CLI with stdin/stdout NOT a TTY (the CI / piped
- * / agent condition). A hang would show as signal SIGTERM + status null; we
- * assert `signal === null && status === 0` to prove it exits cleanly and works.
+ * Every run gets a stdin pipe that stays open and silent, the way an agent's
+ * harness holds it. A prompt or a stdin read for control flow then blocks until
+ * the deadline, and the run ends with signal SIGTERM and status null. With stdin
+ * ignored or closed, the same read would see EOF at once and pass.
+ *
+ * Every command and group in the manifest runs once, with a placeholder for
+ * each required argument so its action is reached, plus the bare `astryx`.
  */
 
 import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import {spawnSync} from 'node:child_process';
+import {spawn, spawnSync} from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
@@ -19,37 +21,112 @@ import {fileURLToPath} from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI = path.resolve(__dirname, '..', 'bin', 'astryx.mjs');
+const DEADLINE_MS = 20_000;
+// Keeps every run offline: `blog` fetches its feed when run bare.
+const OFFLINE = `data:text/javascript,${encodeURIComponent(
+  "globalThis.fetch = () => Promise.reject(new TypeError('fetch failed'));",
+)}`;
+
+/**
+ * Run `node <argv>` with a stdin pipe that is never written or ended.
+ * @param {string[]} argv
+ * @param {string} cwd
+ * @param {number} [deadline]
+ * @returns {Promise<{status: number | null, signal: NodeJS.Signals | null, output: string}>}
+ */
+function runHeld(argv, cwd, deadline = DEADLINE_MS) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, argv, {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {...process.env, FORCE_COLOR: '0', CI: ''},
+    });
+    // Never written or ended; a late EPIPE after exit is not a result.
+    child.stdin.on('error', () => {});
+    let output = '';
+    child.stdout.setEncoding('utf8').on('data', chunk => (output += chunk));
+    child.stderr.setEncoding('utf8').on('data', chunk => (output += chunk));
+    const timer = setTimeout(() => child.kill('SIGTERM'), deadline);
+    child.on('error', error => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on('close', (status, signal) => {
+      clearTimeout(timer);
+      resolve({status, signal, output});
+    });
+  });
+}
 
-let tmpDir;
+/**
+ * @param {string[]} args
+ * @param {string} cwd
+ */
+function runCli(args, cwd) {
+  return runHeld(['--import', OFFLINE, CLI, ...args], cwd);
+}
 
-function runCli(args) {
-  return spawnSync(process.execPath, [CLI, ...args], {
-    cwd: tmpDir,
+/** @returns {Array<[string, string[]]>} */
+function manifestInvocations() {
+  const manifest = spawnSync(process.execPath, [CLI, 'manifest', '--json'], {
     encoding: 'utf8',
-    timeout: 20_000,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    env: {...process.env, FORCE_COLOR: '0', CI: ''},
   });
+  /** @type {string[][]} */
+  const invocations = [[]];
+  /** @param {any[]} commands */
+  const walk = commands => {
+    for (const command of commands) {
+      invocations.push([
+        ...command.name.split(' '),
+        ...command.arguments.filter((/** @type {any} */ a) => a.required).map(() => 'x'),
+      ]);
+      walk(command.subcommands ?? []);
+    }
+  };
+  walk(JSON.parse(manifest.stdout).data.commands);
+  return invocations.map(args => [['astryx', ...args].join(' '), args]);
 }
 
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
+describe('the harness holds stdin open', () => {
+  it('so a stdin read is reported as a hang', async () => {
+    const r = await runHeld(['-e', 'process.stdin.resume()'], os.tmpdir(), 1_000);
+    expect(r.signal).toBe('SIGTERM');
+    expect(r.status).toBeNull();
+  });
 });
 
-afterEach(() => {
-  fs.rmSync(tmpDir, {recursive: true, force: true});
+describe('every command exits without waiting on stdin', () => {
+  it.concurrent.for(manifestInvocations())('%s', async ([label, args], {expect}) => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
+    try {
+      const r = await runCli(args, cwd);
+      expect(r.signal, `${label} waited on stdin:\n${r.output.slice(-500)}`).toBeNull();
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  });
 });
 
 describe('init is non-interactive by default (no TTY needed)', () => {
-  it('runs cleanly (exit 0, no hang) and writes agent docs', () => {
-    const r = runCli(['init']);
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, {recursive: true, force: true});
+  });
+
+  it('runs cleanly (exit 0, no hang) and writes agent docs', async () => {
+    const r = await runCli(['init'], tmpDir);
     expect(r.signal).toBeNull(); // did not hang
     expect(r.status).toBe(0); // succeeded without a TTY
     expect(fs.readdirSync(tmpDir).length).toBeGreaterThan(0); // wrote the cheat sheet
   });
 
-  it('writes an agent-doc file containing the ASTRYX cheat-sheet marker', () => {
-    runCli(['init']);
+  it('writes an agent-doc file containing the ASTRYX cheat-sheet marker', async () => {
+    await runCli(['init'], tmpDir);
     // init injects into existing agent-doc files if present, else creates AGENTS.md
     const candidates = ['AGENTS.md', 'CLAUDE.md', '.cursorrules', path.join('.claude', 'CLAUDE.md')];
     const doc = candidates.find(f => fs.existsSync(path.join(tmpDir, f)));
@@ -57,8 +134,8 @@ describe('init is non-interactive by default (no TTY needed)', () => {
     expect(fs.readFileSync(path.join(tmpDir, doc), 'utf8')).toMatch(/ASTRYX:START/);
   });
 
-  it('still runs --features agents non-interactively', () => {
-    const r = runCli(['init', '--features', 'agents']);
+  it('still runs --features agents non-interactively', async () => {
+    const r = await runCli(['init', '--features', 'agents'], tmpDir);
     expect(r.signal).toBeNull();
     expect(r.status).toBe(0);
     expect(fs.readdirSync(tmpDir).length).toBeGreaterThan(0);

package/clients/cli/commands/json-contract.test.mjs

@@ -172,3 +172,36 @@ describe('--json contract: supported commands emit valid envelopes', () => {
     expect(parsed.data.summary.fail).toBeGreaterThan(0);
   });
 });
+
+describe('--json contract: the flag describes the envelopes it emits', () => {
+  /** @param {string} shape e.g. ` apiVersion, error, code, suggestions? ` */
+  const fields = shape => shape.split(',').map(f => f.trim().replace(/\?$/, ''));
+
+  it('names every field of the success and error envelopes', async () => {
+    const manifest = parseJson((await runCli(['manifest', '--json'], {cwd: tmpDir})).stdout);
+    const {description} = manifest.data.globalOptions.find(o => o.flag === '--json');
+    const match = /Success envelope: \{([^}]*)\}.*Error envelope: \{([^}]*)\}/.exec(description);
+    expect(match, description).not.toBeNull();
+    const [, success, error] = /** @type {RegExpExecArray} */ (match);
+
+    for (const key of Object.keys(manifest)) expect(fields(success)).toContain(key);
+    expect(fields(success)).toContain('meta');
+
+    // An unknown command's envelope carries every error field, suggestions included.
+    const failure = parseJson((await runCli(['bogus-cmd', '--json'], {cwd: tmpDir})).stdout);
+    expect(Object.keys(failure)).toContain('suggestions');
+    for (const key of Object.keys(failure)) expect(fields(error)).toContain(key);
+  });
+
+  it('the CLI README describes the same envelopes', () => {
+    const readme = fs.readFileSync(new URL('../../../README.md', import.meta.url), 'utf8');
+    const line = readme
+      .split('\n')
+      .find(l => l.startsWith('- `--json`: Output as typed JSON envelope:'));
+    expect(line, 'README global --json line').toBeDefined();
+    const [success, error] = [...String(line).matchAll(/`\{([^}]*)\}`/g)].map(m => fields(m[1]));
+    expect(success).toEqual(expect.arrayContaining(['apiVersion', 'type', 'data', 'meta']));
+    expect(error).toEqual(expect.arrayContaining(['apiVersion', 'error', 'code', 'suggestions']));
+    expect(readme).toContain('{"apiVersion": 1, "type": "component.detail"');
+  });
+});

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, ' +

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,7 +12,7 @@ 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 ' +
@@ -29,11 +29,11 @@ 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: [
@@ -45,7 +45,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 @astryxdesign/core cannot be found',
+    },
   ],
   related: ['component', 'hook', 'docs', 'template', 'build'],
 };

package/clients/cli/commands/search.mjs

@@ -16,7 +16,7 @@
  *   astryx search button                 Ranked results across all domains
  *   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
  */
 
@@ -49,16 +49,15 @@ export function registerSearch(program) {
 
       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;
@@ -116,15 +115,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 +151,10 @@ 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},
+        }),
       );
       return answered;
     },

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

@@ -11,6 +11,8 @@
  */
 
 import {describe, it, expect} 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 {search, scoreCandidate, SEARCH_DOMAINS} from '../../../api/search/search.mjs';
@@ -28,6 +30,33 @@ const OPTS = {cwd: REPO_ROOT};
 // the vitest per-test timeout. Give both the same generous scan budget.
 const SCAN_TIMEOUT = 30_000;
 
+/**
+ * A JSON value as the formatters print it (they normalize typography to ASCII).
+ * @param {unknown} value
+ */
+function asText(value) {
+  return (Array.isArray(value) ? value.join(', ') : String(value))
+    .replace(/[\u2014\u2013]/g, '-')
+    .replace(/[\u2018\u2019]/g, "'")
+    .replace(/[\u201C\u201D]/g, '"')
+    .replace(/\u2026/g, '...')
+    .replace(/\u00a0/g, ' ')
+    .trimEnd();
+}
+
+/**
+ * Whether some text line prints `key:` with this value. The command field gains
+ * the caller's invocation prefix, so the value is matched as the line's end; a
+ * multi-line value is matched by its first line.
+ * @param {string[]} lines
+ * @param {string} key
+ * @param {unknown} value
+ */
+function printsField(lines, key, value) {
+  const shown = asText(value).split('\n')[0].trimEnd();
+  return lines.some(line => line.startsWith(`${key}:`) && line.trimEnd().endsWith(shown));
+}
+
 describe('search() API — ranking', () => {
   it('ranks an exact component name match first', async () => {
     const {data} = await search('button', OPTS);
@@ -172,6 +201,20 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.status).toBe(1);
   });
 
+  it.each(['1.5', '5abc'])(
+    'refuses --limit %s like search({limit}) does, in both modes',
+    async value => {
+      await expect(
+        search('x', {...OPTS, limit: Number(value)}),
+      ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+      const json = await runCli(['--json', 'search', 'x', '--limit', value], REPO_ROOT);
+      expect(json.status).toBe(1);
+      expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+      const text = await runCli(['search', 'x', '--limit', value], REPO_ROOT);
+      expect(text.status).toBe(1);
+    },
+  );
+
   it('emits a valid --json envelope', async () => {
     const r = await runCli(['--json', 'search', 'button'], REPO_ROOT);
     expect(r.status).toBe(0);
@@ -223,6 +266,25 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.stdout).toContain('description:');
   });
 
+  it('prints every result field under its JSON key (score and reason with --verbose)', async () => {
+    // One query that reaches all four domains, so every per-domain field shows.
+    const args = ['search', 'theme', '--limit', '60'];
+    const env = JSON.parse((await runCli(['--json', ...args], REPO_ROOT)).stdout);
+    expect(new Set(env.data.results.map(r => r.domain))).toEqual(new Set(SEARCH_DOMAINS));
+    const plain = (await runCli(args, REPO_ROOT)).stdout.split('\n');
+    const verbose = (await runCli([...args, '--verbose'], REPO_ROOT)).stdout.split('\n');
+    for (const result of env.data.results) {
+      for (const [key, value] of Object.entries(result)) {
+        if (value == null || value === '') continue;
+        const label = `${result.domain} ${result.name}: ${key}`;
+        expect(printsField(verbose, key, value), label).toBe(true);
+        if (key !== 'score' && key !== 'reason') {
+          expect(printsField(plain, key, value), label).toBe(true);
+        }
+      }
+    }
+  }, 90_000);
+
   it('--verbose exits 0 and prints import/match detail', async () => {
     // Regression: the boolean verbose flag was named --detail, which collided
     // with the value-taking global `--detail <level>` — a bare `search
@@ -236,4 +298,17 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.stdout).toContain('score:');
     expect(r.stdout).toContain('reason:');
   });
+
+  it('exits 1 with ERR_CORE_NOT_FOUND when no @astryxdesign/core is reachable', async () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-cli-no-core-'));
+    try {
+      const json = await runCli(['--json', 'search', 'button'], empty);
+      expect(json.status).toBe(1);
+      expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_CORE_NOT_FOUND'});
+      const text = await runCli(['search', 'button'], empty);
+      expect(text.status).toBe(1);
+    } finally {
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+  });
 }, SCAN_TIMEOUT);

package/clients/cli/commands/setup-nudge.test.mjs

@@ -89,6 +89,12 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
   });
 
+  it('is quiet in an integration package, which is not an app', async () => {
+    asProject();
+    write('astryx.integration.mjs', 'export default {};\n');
+    expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
+  });
+
   it('does not nudge for the installer command itself', async () => {
     asProject();
     expect((await runCli(['init'], tmp)).stderr).not.toMatch(NUDGE);

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'swizzle',
   displayName: 'astryx swizzle',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Copy component source for customization',
   description:
     "Ejects a component's source from the resolved @astryxdesign/core (or its owning " +
@@ -40,7 +40,8 @@ export const doc = {
     {
       flag: '-f, --overwrite',
       param: 'options.overwrite',
-      description: 'Overwrite existing files without prompting',
+      description:
+        'Replace existing files. Without it, existing files fail the command with ERR_FILE_EXISTS and nothing is written',
     },
   ],
   examples: [

package/clients/cli/commands/swizzle.path-safety.test.mjs

@@ -74,6 +74,37 @@ describe('swizzle path safety', () => {
     expect(fs.existsSync(absTarget)).toBe(false);
   });
 
+  it('rejects a component directory that is a symlink out of the project', async () => {
+    const {project, outside} = buildFakeRepo(tmpDir);
+    const base = path.join(project, 'components', 'astryx');
+    fs.mkdirSync(base, {recursive: true});
+    fs.symlinkSync(outside, path.join(base, 'Button'));
+
+    const result = await runCli(['--json', 'swizzle', 'Button'], project);
+
+    expect(result.code).not.toBe(0);
+    expect(JSON.parse(result.stdout).code).toBe('ERR_PATH_TRAVERSAL');
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('rejects an existing file that is a symlink out of the project, even with --overwrite', async () => {
+    const {project, outside} = buildFakeRepo(tmpDir);
+    const outDir = path.join(project, 'components', 'astryx', 'Button');
+    fs.mkdirSync(outDir, {recursive: true});
+    const target = path.join(outside, 'kept.txt');
+    fs.writeFileSync(target, 'kept\n');
+    fs.symlinkSync(target, path.join(outDir, 'Button.tsx'));
+
+    const result = await runCli(
+      ['--json', 'swizzle', 'Button', '--overwrite'],
+      project,
+    );
+
+    expect(result.code).not.toBe(0);
+    expect(JSON.parse(result.stdout).code).toBe('ERR_PATH_TRAVERSAL');
+    expect(fs.readFileSync(target, 'utf-8')).toBe('kept\n');
+  });
+
   it('requires --overwrite in non-interactive mode when files already exist', async () => {
     const {project} = buildFakeRepo(tmpDir);
     const outDir = path.join(project, 'components', 'astryx', 'Button');
@@ -92,4 +123,15 @@ describe('swizzle path safety', () => {
     // Existing file unchanged
     expect(fs.readFileSync(existingPath, 'utf-8')).toBe('// my customizations\n');
   });
+
+  // The CLI never prompts: without --overwrite it refuses with a code, and the
+  // manifest agents read must say so.
+  it('describes --overwrite by its refusal, not a prompt', async () => {
+    const {project} = buildFakeRepo(tmpDir);
+    const result = await runCli(['--json', 'manifest'], project);
+    const swizzle = JSON.parse(result.stdout).data.commands.find(c => c.name === 'swizzle');
+    const overwrite = swizzle.options.find(o => o.flag.includes('--overwrite'));
+    expect(overwrite.description).not.toMatch(/prompt/i);
+    expect(overwrite.description).toContain('ERR_FILE_EXISTS');
+  });
 });