@astryxdesign/cli 0.1.7 → 0.1.8-canary.4942fe4

package/src/commands/cli-postinstall.test.mjs

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guardrail tests for the @astryxdesign/cli postinstall nudge (layer 2).
+ *
+ * Tests the pure decision matrix (shouldNudge) — nudges for a real dependency
+ * install when not set up; stays quiet in the monorepo/source, during npx's
+ * transient fetch (path _npx or npm_command=exec), and once set up.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {shouldNudge} from '../../scripts/postinstall.mjs';
+
+const DEP = '/proj/node_modules/@astryxdesign/cli/scripts/postinstall.mjs'; // real dep install
+const NPX = '/Users/x/.npm/_npx/a1b2/node_modules/@astryxdesign/cli/scripts/postinstall.mjs';
+const REPO = '/repo/packages/cli/scripts/postinstall.mjs'; // monorepo/source
+
+describe('cli postinstall — shouldNudge', () => {
+  it('nudges for a real dependency install when not set up', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: false})).toBe(true);
+  });
+
+  it('quiet in the monorepo/source (not under node_modules)', () => {
+    expect(shouldNudge({scriptPath: REPO, npmCommand: 'install', isSetUp: false})).toBe(false);
+  });
+
+  it('quiet during npx transient install (path contains _npx)', () => {
+    expect(shouldNudge({scriptPath: NPX, npmCommand: 'install', isSetUp: false})).toBe(false);
+  });
+
+  it('quiet during npx (npm_command=exec) — avoids double-nudge before init', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'exec', isSetUp: false})).toBe(false);
+  });
+
+  it('quiet once the project is already set up', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: true})).toBe(false);
+  });
+
+  it('quiet with no script path (defensive)', () => {
+    expect(shouldNudge({})).toBe(false);
+  });
+});

package/src/commands/component/index.mjs

@@ -18,7 +18,7 @@ import {
   formatBriefAll,
 } from '../../lib/component-format.mjs';
 import {resolveTheme} from '../../lib/resolve-theme.mjs';
-import {getRunPrefix} from '../../utils/package-manager.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
 import {jsonOut, humanLog} from '../../lib/json.mjs';
 import {cliError} from '../../lib/cli-error.mjs';
 import {ERROR_CODES} from '../../lib/error-codes.mjs';
@@ -39,7 +39,7 @@ export function registerComponent(program) {
     .option('--blocks', 'List example blocks: showcase, examples, and related')
     .option('--package <name>', 'Scope lookup to an external package (e.g. @acme/xds-widgets)')
     .action(async (name, options) => {
-      const run = getRunPrefix();
+      const run = getCliInvocation();
       const zh = program.opts().zh || false;
       const dense = program.opts().dense || false;
       const lang = program.opts().lang || null;
@@ -142,7 +142,7 @@ export function registerComponent(program) {
             }
             humanLog('');
             humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
-            humanLog(`Usage: ${run} astryx component <name>`);
+            humanLog(`Usage: ${run} component <name>`);
             humanLog('');
           }
           break;
@@ -165,7 +165,7 @@ export function registerComponent(program) {
             humanLog('');
           }
           humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
-          humanLog(`Usage: ${run} astryx component <name>`);
+          humanLog(`Usage: ${run} component <name>`);
           humanLog('');
           break;
         }

package/src/commands/discover.mjs

@@ -14,6 +14,7 @@ import {formatFull, formatBrief, formatCompact} from '../lib/component-format.mj
 import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {discover as discoverApi} from '../api/discover.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
 
 export function registerDiscover(program) {
   program
@@ -25,6 +26,7 @@ export function registerDiscover(program) {
       const json = program.opts().json || false;
       const lang = program.opts().lang || null;
       const zh = program.opts().zh || false;
+      const run = getCliInvocation();
 
       let result;
       try {
@@ -80,9 +82,9 @@ export function registerDiscover(program) {
               humanLog('');
             }
             humanLog('Usage:');
-            humanLog('  astryx discover <package>            Browse a package');
-            humanLog('  astryx discover <package>/Component  View component docs');
-            humanLog('  astryx discover <search>             Search all packages');
+            humanLog(`  ${run} discover <package>            Browse a package`);
+            humanLog(`  ${run} discover <package>/Component  View component docs`);
+            humanLog(`  ${run} discover <search>             Search all packages`);
             humanLog('');
           }
           break;
@@ -99,7 +101,7 @@ export function registerDiscover(program) {
           humanLog('');
           for (const comp of result.data.components) humanLog('  ' + comp);
           humanLog('');
-          humanLog('Usage: astryx discover ' + result.data.name + '/<ComponentName>');
+          humanLog(`Usage: ${run} discover ` + result.data.name + '/<ComponentName>');
           humanLog('');
           break;
         }
@@ -122,7 +124,7 @@ export function registerDiscover(program) {
           humanLog('Found ' + result.data.matches.length + ' matches for "' + result.data.query + '":');
           humanLog('');
           for (const m of result.data.matches) {
-            humanLog('  astryx discover ' + m.package + '/' + m.component);
+            humanLog(`  ${run} discover ` + m.package + '/' + m.component);
           }
           humanLog('');
           break;

package/src/commands/docs.mjs

@@ -12,7 +12,7 @@
  *   astryx docs <topic> <section>        Print one section
  */
 
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
 import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {docs as docsApi} from '../api/docs.mjs';
@@ -105,7 +105,7 @@ export function registerDocs(program) {
     .command('docs [topic] [section]')
     .description('Print reference docs')
     .action(async (topic, section) => {
-      const run = getRunPrefix();
+      const run = getCliInvocation();
       const lang = program.opts().lang || null;
       const zh = program.opts().zh || false;
       const dense = program.opts().dense || false;
@@ -130,8 +130,8 @@ export function registerDocs(program) {
           for (const entry of result.data) {
             humanLog(`  ${entry.topic.padEnd(14)} ${entry.description}`);
           }
-          humanLog(`\nUsage: ${run} astryx docs <topic>`);
-          humanLog(`       ${run} astryx docs <topic> <section>\n`);
+          humanLog(`\nUsage: ${run} docs <topic>`);
+          humanLog(`       ${run} docs <topic> <section>\n`);
           break;
         }
 

package/src/commands/hook/index.mjs

@@ -12,7 +12,7 @@ import {
   formatHookBrief,
   formatHookParams,
 } from '../../lib/hook-format.mjs';
-import {getRunPrefix} from '../../utils/package-manager.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
 import {jsonOut, humanLog} from '../../lib/json.mjs';
 import {cliError} from '../../lib/cli-error.mjs';
 import {ERROR_CODES} from '../../lib/error-codes.mjs';
@@ -27,7 +27,7 @@ export function registerHook(program) {
     .option('--category <category>', 'List hooks in a specific category')
     .option('--params', 'Print only the parameters table')
     .action(async (name, options) => {
-      const run = getRunPrefix();
+      const run = getCliInvocation();
       const zh = program.opts().zh || false;
       const lang = program.opts().lang || null;
       const detailSource = program.getOptionValueSource('detail');
@@ -76,7 +76,7 @@ export function registerHook(program) {
               for (const h of hookNames) humanLog(`  ${h}`);
             }
             humanLog('');
-            humanLog(`Usage: ${run} astryx hook <name>`);
+            humanLog(`Usage: ${run} hook <name>`);
             humanLog('');
           }
           break;
@@ -93,7 +93,7 @@ export function registerHook(program) {
             }
             humanLog('');
           }
-          humanLog(`Usage: ${run} astryx hook <name>`);
+          humanLog(`Usage: ${run} hook <name>`);
           humanLog('');
           break;
         }

package/src/commands/init.mjs

@@ -1,33 +1,33 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file init command — Interactive initialization wizard + feature installer
+ * @file init command — non-interactive setup + feature installer
  *
- * Interactive: `astryx init` walks through all features
- * Non-interactive: `astryx init --features agents,theme,template`
+ * `astryx init` is non-interactive by default: it installs the AGENTS.md/
+ * CLAUDE.md cheat sheet with NO prompts, so it behaves identically for humans,
+ * AI agents, CI, and piped I/O — it never hangs or errors on a missing TTY.
+ * Non-interactive feature install: `astryx init --features agents,theme,template`
  * Re-runnable: safe to run multiple times, idempotent
  *
  * Features:
  *   agents   — Install AGENTS.md/CLAUDE.md cheat sheet for AI coding agents
- *   theme    — Scaffold a custom theme file
+ *   theme    — Point to the theme workflow (`astryx theme`)
  *   template — Copy a starter page template
  */
 
-import * as p from '@clack/prompts';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import {CLI_ROOT} from '../utils/paths.mjs';
 import {PathSafetyError} from '../utils/path-safety.mjs';
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
 import {installAgentDocs, removeAgentDocs} from './agent-docs.mjs';
 import {listTemplates} from './template.mjs';
 import {humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {requireInteractive} from '../utils/interactive.mjs';
 
 const VALID_FEATURES = ['agents', 'theme', 'template'];
-const run = getRunPrefix();
+const run = getCliInvocation();
 
 /**
  * Build the "Next steps" lines printed at the end of `astryx init`.
@@ -40,10 +40,10 @@ const run = getRunPrefix();
  *
  * Exported for testing.
  *
- * @param {string} runPrefix package-manager run prefix (e.g. `npx`)
+ * @param {string} invocation install-aware CLI invocation stem (e.g. `npx astryx`, `pnpm exec astryx`, or `npx @astryxdesign/cli` for one-off runs)
  * @returns {string[]} ordered list of human-facing lines
  */
-export function getNextSteps(runPrefix) {
+export function getNextSteps(invocation) {
   return [
     '',
     '  Next steps:',
@@ -54,23 +54,15 @@ export function getNextSteps(runPrefix) {
     "       import { neutralTheme } from '@astryxdesign/theme-neutral/built'",
     "       import '@astryxdesign/theme-neutral/theme.css'",
     '       <Theme theme={neutralTheme}>...</Theme>',
-    `       For custom themes, run \`${runPrefix} astryx theme build <file>\` to generate the built artifacts.`,
-    `    4. ${runPrefix} astryx --help for all commands`,
+    `       For custom themes, run \`${invocation} theme build <file>\` to generate the built artifacts.`,
+    `    4. ${invocation} --help for all commands`,
     '',
   ];
 }
 
-function isCancel(value) {
-  if (p.isCancel(value)) {
-    p.cancel('Setup cancelled.');
-    process.exit(0);
-  }
-  return value;
-}
-
 // ─── Feature: agents ─────────────────────────────────────────────────────────
 
-function runAgents(targetDir, {interactive = true, agent, agentDocsPath} = {}) {
+function runAgents(targetDir, {agent, agentDocsPath} = {}) {
   try {
     const paths = agentDocsPath
       ? Array.isArray(agentDocsPath)
@@ -79,114 +71,55 @@ function runAgents(targetDir, {interactive = true, agent, agentDocsPath} = {}) {
       : undefined;
     const written = installAgentDocs(targetDir, {agent, paths});
     const summary = written.join(', ');
-    if (interactive) {
-      p.log.success(`AI agent docs installed → ${summary}`);
-    } else {
-      humanLog(`✓ AI agent docs installed → ${summary}`);
-    }
+    humanLog(`✓ AI agent docs installed → ${summary}`);
   } catch (err) {
     // PathSafetyError carries a precise, user-actionable message —
     // surface it instead of the generic "could not install" warning so
     // misconfigured --agent-docs-path values aren't silently swallowed.
     if (err instanceof PathSafetyError) {
-      const msg = `Error: ${err.message}`;
-      if (interactive) {
-        p.log.error(msg);
-      } else {
-        console.error(msg);
-      }
+      console.error(`Error: ${err.message}`);
       process.exitCode = 1;
       return;
     }
-    const msg = `Could not install agent docs. Try again with \`${run} astryx init --features agents\`.`;
-    if (interactive) {
-      p.log.warning(msg);
-    } else {
-      console.error(msg);
-    }
+    console.error(`Could not install agent docs. Try again with \`${run} init --features agents\`.`);
   }
 }
 
 // ─── Feature: theme ──────────────────────────────────────────────────────────
 
-async function runTheme({interactive = true} = {}) {
-  if (!interactive) {
-    humanLog(`✓ Theme scaffolding requires interactive mode. Run \`${run} astryx theme\` instead.`);
-    return;
-  }
-
-  p.note(
-    'Create a custom theme with your brand colors.\n' +
-    `Run \`${run} astryx theme\` for the full theme wizard.\n` +
-    `Run \`${run} astryx theme --list\` to see existing themes.`,
-    'Themes',
-  );
+function runTheme() {
+  humanLog(`✓ For a custom theme, run \`${run} theme\` (browse) or \`${run} theme add <slug>\` (scaffold).`);
 }
 
 // ─── Feature: template ───────────────────────────────────────────────────────
 
-async function runTemplate(targetDir, {interactive = true, templateName} = {}) {
+function runTemplate(targetDir, {templateName} = {}) {
   const templates = listTemplates();
   if (templates.length === 0) return;
 
-  if (!interactive) {
-    if (!templateName) {
-      // Point agents at the build workflow rather than dumping page-template
-      // names — `build` surfaces pages AND blocks AND components for an idea,
-      // and `build` with no args is the full how-to-build playbook.
-      humanLog('✓ To build UI, use these commands:');
-      humanLog('');
-      humanLog(`    ${run} astryx build "<what you're building>"   build a page — kit: closest template + blocks + components`);
-      humanLog(`    ${run} astryx build                            the how-to-build workflow (read this first)`);
-      humanLog(`    ${run} astryx search <query>                   find anything — components, docs, templates, blocks`);
-      humanLog('');
-      return;
-    }
-
-    if (!templates.includes(templateName)) {
-      cliError(`Unknown template "${templateName}". Available: ${templates.join(', ')}`, {code: ERROR_CODES.ERR_UNKNOWN_TEMPLATE});
-      return;
-    }
-
-    const outputDir = path.resolve(targetDir, `./src/pages/${templateName}`);
-    const srcPath = path.join(CLI_ROOT, 'templates', 'pages', templateName, 'page.tsx');
-    fs.mkdirSync(outputDir, {recursive: true});
-    fs.copyFileSync(srcPath, path.join(outputDir, 'page.tsx'));
-    humanLog(`✓ Template created at ${path.relative(targetDir, outputDir)}/page.tsx`);
+  if (!templateName) {
+    // Point agents at the build workflow rather than dumping page-template
+    // names — `build` surfaces pages AND blocks AND components for an idea,
+    // and `build` with no args is the full how-to-build playbook.
+    humanLog('✓ To build UI, use these commands:');
+    humanLog('');
+    humanLog(`    ${run} build "<what you're building>"   build a page — kit: closest template + blocks + components`);
+    humanLog(`    ${run} build                            the how-to-build workflow (read this first)`);
+    humanLog(`    ${run} search <query>                   find anything — components, docs, templates, blocks`);
+    humanLog('');
     return;
   }
 
-  const TEMPLATE_OPTIONS = [
-    {value: 'skip', label: 'Skip — No template'},
-    {value: 'blank', label: 'Blank Page — Minimal scaffold'},
-    {value: 'table', label: 'Table Page — Data table with actions'},
-    {value: 'login', label: 'Login Page — Auth form with inputs'},
-  ];
-
-  const templateChoice = isCancel(
-    await p.select({
-      message: 'Start with a page template?',
-      options: TEMPLATE_OPTIONS,
-    }),
-  );
-
-  if (templateChoice === 'skip') return;
-
-  const targetPath = isCancel(
-    await p.text({
-      message: 'Where should the template be created?',
-      initialValue: `./src/pages/${templateChoice}`,
-      placeholder: `./src/pages/${templateChoice}`,
-    }),
-  );
-
-  const outputDir = path.resolve(targetDir, targetPath);
-  const srcPath = path.join(CLI_ROOT, 'templates', 'pages', templateChoice, 'page.tsx');
+  if (!templates.includes(templateName)) {
+    cliError(`Unknown template "${templateName}". Available: ${templates.join(', ')}`, {code: ERROR_CODES.ERR_UNKNOWN_TEMPLATE});
+    return;
+  }
 
+  const outputDir = path.resolve(targetDir, `./src/pages/${templateName}`);
+  const srcPath = path.join(CLI_ROOT, 'templates', 'pages', templateName, 'page.tsx');
   fs.mkdirSync(outputDir, {recursive: true});
   fs.copyFileSync(srcPath, path.join(outputDir, 'page.tsx'));
-
-  p.log.success(`Template created at ${path.relative(targetDir, outputDir)}/page.tsx`);
+  humanLog(`✓ Template created at ${path.relative(targetDir, outputDir)}/page.tsx`);
 }
 
 // ─── Command ─────────────────────────────────────────────────────────────────
@@ -200,7 +133,7 @@ export function registerInit(program) {
     .option('--remove-agents', 'Remove AI agent docs from all agent doc files')
     .option('--agent <tool>', 'Target AI tool for agent docs: claude, cursor, codex, hermes, all')
     .option('--agent-docs-path <path...>', 'Explicit file path(s) for agent docs')
-    .action(async (options) => {
+    .action((options) => {
       const targetDir = process.cwd();
 
       // Remove mode
@@ -224,62 +157,25 @@ export function registerInit(program) {
 
         for (const feature of features) {
           if (feature === 'agents') runAgents(targetDir, {
-            interactive: false,
             agent: options.agent,
             agentDocsPath: options.agentDocsPath,
           });
-          if (feature === 'theme') await runTheme({interactive: false});
-          if (feature === 'template') await runTemplate(targetDir, {interactive: false});
+          if (feature === 'theme') runTheme();
+          if (feature === 'template') runTemplate(targetDir, {});
         }
         return;
       }
 
-      // Interactive wizard
-      //
-      // Guard: this wizard blocks on prompts. In a non-interactive context
-      // (CI, piped stdin/stdout, no TTY) it would hang forever. Fail fast
-      // with actionable guidance via the shared interactivity contract.
-      requireInteractive({
-        command: 'init',
-        hint: `\`${run} astryx init --all\` or \`--features agents,theme,template\``,
+      // No flags: TTY-free default. `astryx init` installs the AI agent cheat
+      // sheet with NO prompts, so it behaves identically for humans, agents, CI,
+      // and piped I/O — it never hangs or errors on a missing TTY. (A guided
+      // `--interactive` setup may return later as an explicit opt-in.)
+      runAgents(targetDir, {
+        agent: options.agent,
+        agentDocsPath: options.agentDocsPath,
       });
-
-      p.intro('Welcome to the design system');
-
-      p.note(
-        'A design system for building internal tools\nwith 300+ React components.',
-        'About',
-      );
-
-      // Feature: agents
-      const shouldInstallAgents = isCancel(
-        await p.confirm({
-          message: 'Install AI agent support? (adds a design system cheat sheet to AGENTS.md)',
-          initialValue: true,
-        }),
-      );
-
-      if (shouldInstallAgents) {
-        const s = p.spinner();
-        s.start('Installing agent docs');
-        runAgents(targetDir);
-        s.stop('Done');
-      }
-
-      // Feature: swizzle awareness
-      p.note(
-        `You can customize any component with:\n  ${run} astryx swizzle Button\n  ${run} astryx swizzle --list`,
-        'Component Customization',
-      );
-
-      // Feature: template
-      await runTemplate(targetDir);
-
-      // Feature: theme awareness
-      await runTheme();
-
-      // Outro
-      p.outro('Design system initialized!');
+      humanLog('');
+      humanLog(`  Tip: \`${run} init --all\` also points you to the theme and page-building workflows.`);
 
       for (const line of getNextSteps(run)) {
         humanLog(line);

package/src/commands/init.next-steps.test.mjs

@@ -23,7 +23,7 @@ import {describe, it, expect} from 'vitest';
 import {getNextSteps} from './init.mjs';
 
 describe('init Next steps theme guidance', () => {
-  const text = getNextSteps('npx').join('\n');
+  const text = getNextSteps('npx astryx').join('\n');
 
   it('mentions the base CSS imports so the app is not left unstyled', () => {
     expect(text).toContain("'@astryxdesign/core/reset.css'");

package/src/commands/interactive-guard.test.mjs

@@ -1,15 +1,13 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Subprocess no-hang tests for the interactivity contract.
+ * @file Subprocess no-hang tests for `astryx init`.
  *
- * The wizard command `init` blocks on @clack/prompts. In a
- * non-interactive context it must fail fast (exit 1) instead of hanging.
- * These tests spawn the CLI as a real subprocess with stdin/stdout NOT a TTY
- * (stdio 'ignore'/'pipe'), which is exactly the CI / piped condition. If the
- * guard were missing, spawnSync would hit the timeout (signal SIGTERM,
- * status null) — so asserting `signal === null && status === 1` proves the
- * process exited cleanly rather than hanging.
+ * 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.
  */
 
 import {describe, it, expect, beforeEach, afterEach} from 'vitest';
@@ -42,25 +40,24 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
-describe('init non-interactive safety', () => {
-  it('fails fast (exit 1, no hang) and writes no files', () => {
+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']);
-    expect(r.signal).toBeNull();
-    expect(r.status).toBe(1);
-    expect(fs.readdirSync(tmpDir)).toEqual([]);
+    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('prints actionable guidance (--all / --features)', () => {
-    const out = (() => {
-      const r = runCli(['init']);
-      return r.stderr + r.stdout;
-    })();
-    expect(out).toMatch(/requires a TTY/i);
-    expect(out).toMatch(/--all/);
-    expect(out).toMatch(/--features/);
+  it('writes an agent-doc file containing the ASTRYX cheat-sheet marker', () => {
+    runCli(['init']);
+    // 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)));
+    expect(doc).toBeTruthy();
+    expect(fs.readFileSync(path.join(tmpDir, doc), 'utf8')).toMatch(/ASTRYX:START/);
   });
 
-  it('still runs --features agents non-interactively (guard does not over-catch)', () => {
+  it('still runs --features agents non-interactively', () => {
     const r = runCli(['init', '--features', 'agents']);
     expect(r.signal).toBeNull();
     expect(r.status).toBe(0);

package/src/commands/json-contract.test.mjs

@@ -45,7 +45,7 @@ function runCli(args, {cwd} = {}) {
 
 function parseJson(stdout) {
   // CLI emits a single JSON document. If anything else snuck onto stdout
-  // (clack output, console.log strings, etc.) JSON.parse will throw —
+  // (log output, console.log strings, etc.) JSON.parse will throw —
   // which is exactly the failure mode we want to catch in tests.
   return JSON.parse(stdout);
 }
@@ -61,7 +61,7 @@ afterEach(() => {
 });
 
 describe('--json contract: rejects before side effects', () => {
-  it('astryx init --json --features agents does not write .claude/CLAUDE.md', () => {
+  it('astryx init --json --features agents does not write agent docs', () => {
     const before = fs.readdirSync(tmpDir);
     expect(before).toEqual([]);
 

package/src/commands/layout.mjs

@@ -20,7 +20,7 @@ import {layoutExpand, layoutCheck, layoutGrammar} from '../api/layout.mjs';
 /** Resolve the expression from arg, --file, or stdin ('-'). */
 async function readExpression(expr, options) {
   if (options.file) return fs.readFileSync(options.file, 'utf-8');
-  if (expr === '-' || (!expr && !process.stdin.isTTY)) {
+  if (expr === '-') {
     const chunks = [];
     for await (const chunk of process.stdin) chunks.push(chunk);
     return Buffer.concat(chunks).toString('utf-8');

package/src/commands/search.mjs

@@ -16,7 +16,7 @@
  *   astryx search button --json          Typed JSON envelope
  */
 
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation, formatCliCommand} from '../utils/package-manager.mjs';
 import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {search as searchApi, SEARCH_DOMAINS} from '../api/search.mjs';
@@ -63,7 +63,7 @@ export function registerSearch(program) {
       if (json) return jsonOut(result.type, result.data);
 
       // ── Text output ──────────────────────────────────────────────
-      const run = getRunPrefix();
+      const run = getCliInvocation();
       const {query: q, results} = result.data;
 
       // No matches is a valid, successful outcome — clean message, exit 0.
@@ -71,7 +71,7 @@ export function registerSearch(program) {
         humanLog('');
         humanLog(`No results for "${q}".`);
         humanLog('');
-        humanLog(`Try a broader term, or browse: ${run} astryx component --list`);
+        humanLog(`Try a broader term, or browse: ${run} component --list`);
         humanLog('');
         return;
       }
@@ -86,7 +86,7 @@ export function registerSearch(program) {
         if (r.description) {
           humanLog(`               ${r.description}`);
         }
-        humanLog(`               → ${run} ${r.command}`);
+        humanLog(`               → ${formatCliCommand(r.command)}`);
         if (options.detail) {
           if (r.import) humanLog(`               import: ${r.import}`);
           humanLog(`               match: ${r.reason} (score ${r.score})`);