@astryxdesign/cli 0.1.7-canary.e486729 → 0.1.7-canary.eb8e07b

package/docs/getting-started.doc.mjs

@@ -40,7 +40,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "Then run `astryx init` to install the AI agent cheat sheet (AGENTS.md/CLAUDE.md). It's non-interactive — no prompts — so it's safe for AI agents, CI, and scripts. Add `--all` for pointers to the theme and page-building workflows.",
+          text: 'Then run the init wizard to set up AI agent docs, pick a starter template, and learn about theming.',
         },
         {
           type: 'code',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.7-canary.e486729",
+  "version": "0.1.7-canary.eb8e07b",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -72,16 +72,17 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
+    "@clack/prompts": "^1.7.0",
     "commander": "^12.1.0",
     "jiti": "^2.7.0",
     "jscodeshift": "^17.3.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.7-canary.e486729",
-    "@astryxdesign/core": "0.1.7-canary.e486729",
-    "@astryxdesign/lab": "0.1.7-canary.e486729",
-    "@astryxdesign/theme-neutral": "0.1.7-canary.e486729",
+    "@astryxdesign/charts": "0.1.7-canary.eb8e07b",
+    "@astryxdesign/core": "0.1.7-canary.eb8e07b",
+    "@astryxdesign/lab": "0.1.7-canary.eb8e07b",
+    "@astryxdesign/theme-neutral": "0.1.7-canary.eb8e07b",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -99,10 +100,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.7-canary.e486729",
-    "@astryxdesign/core": "0.1.7-canary.e486729",
-    "@astryxdesign/lab": "0.1.7-canary.e486729",
-    "@astryxdesign/theme-neutral": "0.1.7-canary.e486729",
+    "@astryxdesign/charts": "0.1.7-canary.eb8e07b",
+    "@astryxdesign/core": "0.1.7-canary.eb8e07b",
+    "@astryxdesign/lab": "0.1.7-canary.eb8e07b",
+    "@astryxdesign/theme-neutral": "0.1.7-canary.eb8e07b",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/src/codemods/ensure-jscodeshift.mjs

@@ -3,15 +3,16 @@
 /**
  * @file Lazy jscodeshift installer
  *
- * Checks if jscodeshift is available and installs it on-demand.
+ * Checks if jscodeshift is available and offers to install it on-demand.
  * Keeps the CLI lean — jscodeshift is only needed for codemods.
  *
- * Non-interactive by default (no prompts): pass `installDeps: true` to
- * auto-install, otherwise the command fails fast with a helpful error.
+ * In non-interactive environments (CI, LLM agents), the interactive prompt
+ * is skipped. Pass `installDeps: true` to auto-install without prompting,
+ * or the command will fail with a helpful error message.
  */
 
 import {execSync} from 'node:child_process';
-import * as p from '../lib/term-log.mjs';
+import * as p from '@clack/prompts';
 import {detectPackageManager} from '../utils/package-manager.mjs';
 
 /**
@@ -29,17 +30,32 @@ export async function ensureJscodeshift({installDeps = false, silent = false} =
   } catch {
     log.warn('jscodeshift is required for codemods but not installed.');
 
+    const isInteractive = process.stdout.isTTY && !process.env.CI;
+
     if (installDeps) {
-      // Explicit opt-in — install without prompting.
+      // Explicit opt-in — install without prompting
       return installJscodeshift(silent);
     }
 
-    // Non-interactive by default: fail fast with a helpful message instead of
-    // prompting (the CLI never blocks on a TTY).
-    log.error(
-      'Cannot run codemods without jscodeshift. Use --install-deps to auto-install.',
-    );
-    return false;
+    if (!isInteractive || silent) {
+      // Non-interactive environment (or --json) — fail fast with a helpful message
+      log.error(
+        'Cannot run codemods without jscodeshift. ' +
+          'Use --install-deps to auto-install in non-interactive environments.',
+      );
+      return false;
+    }
+
+    // Interactive TTY — prompt as before
+    const shouldInstall = await p.confirm({
+      message: 'Install jscodeshift now?',
+      initialValue: true,
+    });
+    if (p.isCancel(shouldInstall) || !shouldInstall) {
+      p.log.error('Cannot run codemods without jscodeshift.');
+      return false;
+    }
+    return installJscodeshift(silent);
   }
 }
 

package/src/codemods/run-codemod.mjs

@@ -29,7 +29,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as p from '../lib/term-log.mjs';
+import * as p from '@clack/prompts';
 import {findConfigPath} from '../lib/project.mjs';
 import {fixDirectiveCorruption, validateOutput} from './runner.mjs';
 

package/src/codemods/runner.mjs

@@ -10,7 +10,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as p from '../lib/term-log.mjs';
+import * as p from '@clack/prompts';
 import {humanLog} from '../lib/json.mjs';
 import {runConfigCodemod} from './run-codemod.mjs';
 
@@ -184,7 +184,7 @@ export async function runCodemods(
   versionManifests,
   {apply, path: srcPath, codemod, skipCodemods, silent = false},
 ) {
-  // No-op stub object so silent mode skips log output entirely without
+  // No-op stub object so silent mode skips clack stdout entirely without
   // littering the body with `if (!silent)` guards.
   const log = silent
     ? {step() {}, info() {}, success() {}, warn() {}, error() {}, message() {}}

package/src/commands/agent-docs.mjs

@@ -392,7 +392,7 @@ export function removeAgentDocs(targetDir) {
 
 /**
  * Programmatic entry point for installing agent docs.
- * Used by the init command, upgrade command, and agent-docs command.
+ * Used by the init wizard, upgrade command, and agent-docs command.
  *
  * Strategy (when no agent/paths specified):
  * - Discover all existing agent doc files and update them

package/src/commands/build-theme.mjs

@@ -21,11 +21,12 @@ import {getRunPrefix} from '../utils/package-manager.mjs';
 import {
   sanitizeName,
   PathSafetyError,
+  isNonInteractive,
 } from '../utils/path-safety.mjs';
 import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {themeAdd} from '../api/theme-add.mjs';
+import {themeAdd, listThemes} from '../api/theme-add.mjs';
 
 // Import shared theme processing from core. `astryx theme build` MUST produce the
 // exact same CSS as the `<Theme>` runtime, so it has exactly one generation
@@ -1140,9 +1141,32 @@ Or with a <link> tag:
     .action(async (slug, targetPath, options) => {
       const json = program.opts().json || false;
 
-      // The CLI is non-interactive: never prompt to confirm an overwrite.
-      // Existing files require an explicit --overwrite; otherwise themeAdd's
-      // ERR_FILE_EXISTS guard rejects the write.
+      // Only prompt with a real TTY on stdin — a piped/redirected stdin would
+      // make clack hang. Non-interactive callers fall through to the API's
+      // ERR_FILE_EXISTS guard.
+      const interactive =
+        !json && !isNonInteractive({json}) && Boolean(process.stdin.isTTY);
+      if (slug && !options.list && !options.overwrite && interactive) {
+        const collision = await detectThemeCollision(slug, targetPath);
+        if (collision) {
+          const rel = path.relative(process.cwd(), collision) || collision;
+          const p = await import('@clack/prompts');
+          const confirmed = await p.confirm({
+            message: `Overwrite existing file ${rel}?`,
+            initialValue: false,
+          });
+          if (p.isCancel(confirmed)) {
+            p.cancel('Cancelled.');
+            return;
+          }
+          if (!confirmed) {
+            humanLog('Aborted. Re-run with --overwrite to replace the file.');
+            return;
+          }
+          options.overwrite = true;
+        }
+      }
+
       let result;
       try {
         result = await themeAdd(slug, {
@@ -1195,3 +1219,40 @@ This is your copy of the ${displayName} theme — edit ${entry} to make it your
     });
 }
 
+/**
+ * First existing file that scaffolding <slug> into <targetPath> would clobber,
+ * or null. Used to prompt before invoking the API; the API re-validates and
+ * owns any authoritative error.
+ *
+ * @param {string} slug
+ * @param {string} [targetPath]
+ * @returns {Promise<string|null>}
+ */
+async function detectThemeCollision(slug, targetPath) {
+  let themes;
+  try {
+    themes = listThemes();
+  } catch {
+    return null;
+  }
+  const match = themes.find(t => t.slug.toLowerCase() === slug.toLowerCase());
+  if (!match) return null;
+
+  const rawTarget = targetPath || path.join('src', 'themes', match.slug);
+  let resolvedDir;
+  try {
+    // Fail soft (null) on traversal; the API surfaces the real error.
+    const {assertWithin} = await import('../utils/path-safety.mjs');
+    resolvedDir = assertWithin(rawTarget, process.cwd(), {
+      label: 'theme target path',
+    });
+  } catch {
+    return null;
+  }
+
+  for (const name of match.files) {
+    const dest = path.join(resolvedDir, name);
+    if (fs.existsSync(dest)) return dest;
+  }
+  return null;
+}

package/src/commands/init.mjs

@@ -1,20 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file init command — non-interactive setup + feature installer
+ * @file init command — Interactive initialization wizard + feature installer
  *
- * `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`
+ * Interactive: `astryx init` walks through all features
+ * Non-interactive: `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    — Point to the theme workflow (`astryx theme`)
+ *   theme    — Scaffold a custom theme file
  *   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';
@@ -25,6 +24,7 @@ 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();
@@ -60,9 +60,17 @@ export function getNextSteps(runPrefix) {
   ];
 }
 
+function isCancel(value) {
+  if (p.isCancel(value)) {
+    p.cancel('Setup cancelled.');
+    process.exit(0);
+  }
+  return value;
+}
+
 // ─── Feature: agents ─────────────────────────────────────────────────────────
 
-function runAgents(targetDir, {agent, agentDocsPath} = {}) {
+function runAgents(targetDir, {interactive = true, agent, agentDocsPath} = {}) {
   try {
     const paths = agentDocsPath
       ? Array.isArray(agentDocsPath)
@@ -71,55 +79,114 @@ function runAgents(targetDir, {agent, agentDocsPath} = {}) {
       : undefined;
     const written = installAgentDocs(targetDir, {agent, paths});
     const summary = written.join(', ');
-    humanLog(`✓ AI agent docs installed → ${summary}`);
+    if (interactive) {
+      p.log.success(`AI agent docs installed → ${summary}`);
+    } else {
+      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) {
-      console.error(`Error: ${err.message}`);
+      const msg = `Error: ${err.message}`;
+      if (interactive) {
+        p.log.error(msg);
+      } else {
+        console.error(msg);
+      }
       process.exitCode = 1;
       return;
     }
-    console.error(`Could not install agent docs. Try again with \`${run} astryx init --features agents\`.`);
+    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);
+    }
   }
 }
 
 // ─── Feature: theme ──────────────────────────────────────────────────────────
 
-function runTheme() {
-  humanLog(`✓ For a custom theme, run \`${run} astryx theme\` (browse) or \`${run} astryx theme add <slug>\` (scaffold).`);
+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',
+  );
 }
 
 // ─── Feature: template ───────────────────────────────────────────────────────
 
-function runTemplate(targetDir, {templateName} = {}) {
+async function runTemplate(targetDir, {interactive = true, templateName} = {}) {
   const templates = listTemplates();
   if (templates.length === 0) return;
 
-  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 (!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;
+    }
 
-  if (!templates.includes(templateName)) {
-    cliError(`Unknown template "${templateName}". Available: ${templates.join(', ')}`, {code: ERROR_CODES.ERR_UNKNOWN_TEMPLATE});
+    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`);
     return;
   }
 
-  const outputDir = path.resolve(targetDir, `./src/pages/${templateName}`);
-  const srcPath = path.join(CLI_ROOT, 'templates', 'pages', templateName, 'page.tsx');
+  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');
+
   fs.mkdirSync(outputDir, {recursive: true});
   fs.copyFileSync(srcPath, path.join(outputDir, 'page.tsx'));
-  humanLog(`✓ Template created at ${path.relative(targetDir, outputDir)}/page.tsx`);
+
+  p.log.success(`Template created at ${path.relative(targetDir, outputDir)}/page.tsx`);
 }
 
 // ─── Command ─────────────────────────────────────────────────────────────────
@@ -133,7 +200,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((options) => {
+    .action(async (options) => {
       const targetDir = process.cwd();
 
       // Remove mode
@@ -157,25 +224,62 @@ 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') runTheme();
-          if (feature === 'template') runTemplate(targetDir, {});
+          if (feature === 'theme') await runTheme({interactive: false});
+          if (feature === 'template') await runTemplate(targetDir, {interactive: false});
         }
         return;
       }
 
-      // 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,
+      // 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\``,
       });
-      humanLog('');
-      humanLog(`  Tip: \`${run} astryx init --all\` also points you to the theme and page-building workflows.`);
+
+      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!');
 
       for (const line of getNextSteps(run)) {
         humanLog(line);

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

@@ -1,13 +1,15 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Subprocess no-hang tests for `astryx init`.
+ * @file Subprocess no-hang tests for the interactivity contract.
  *
- * 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.
+ * 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.
  */
 
 import {describe, it, expect, beforeEach, afterEach} from 'vitest';
@@ -40,24 +42,25 @@ afterEach(() => {
   fs.rmSync(tmpDir, {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', () => {
+describe('init non-interactive safety', () => {
+  it('fails fast (exit 1, no hang) and writes no files', () => {
     const r = runCli(['init']);
-    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
+    expect(r.signal).toBeNull();
+    expect(r.status).toBe(1);
+    expect(fs.readdirSync(tmpDir)).toEqual([]);
   });
 
-  it('writes an agent-doc file containing the ASTRYX cheat-sheet marker', () => {
-    runCli(['init']);
-    // init injects into AGENTS.md/CLAUDE.md if present, else creates .claude/CLAUDE.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('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('still runs --features agents non-interactively', () => {
+  it('still runs --features agents non-interactively (guard does not over-catch)', () => {
     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
-  // (log output, console.log strings, etc.) JSON.parse will throw —
+  // (clack 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);
 }

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 === '-') {
+  if (expr === '-' || (!expr && !process.stdin.isTTY)) {
     const chunks = [];
     for await (const chunk of process.stdin) chunks.push(chunk);
     return Buffer.concat(chunks).toString('utf-8');

package/src/commands/swizzle.mjs

@@ -15,10 +15,12 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import * as p from '@clack/prompts';
 import {findCoreDir, listComponents} from '../utils/paths.mjs';
 import {
   assertWithin,
   PathSafetyError,
+  isNonInteractive,
 } from '../utils/path-safety.mjs';
 import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
@@ -97,6 +99,14 @@ function buildFeedback(component, issuesUrl) {
   return feedback;
 }
 
+function isCancel(value) {
+  if (p.isCancel(value)) {
+    p.cancel('Cancelled.');
+    process.exit(0);
+  }
+  return value;
+}
+
 /**
  * Load the configured integrations + core issues URL for `cwd`, swallowing any
  * config errors so swizzle never hard-fails on a malformed/absent config. An
@@ -304,11 +314,25 @@ export function registerSwizzle(program) {
 
       if (existingFiles.length > 0 && !options.overwrite) {
         const relOutputForMsg = path.relative(process.cwd(), outputDir) || '.';
-        const msg =
-          `Refusing to overwrite ${existingFiles.length} existing file(s) in ${relOutputForMsg}/. ` +
-          `Re-run with --overwrite (or -f) to replace them.`;
-        cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
-        return;
+        if (json || isNonInteractive({json})) {
+          const msg =
+            `Refusing to overwrite ${existingFiles.length} existing file(s) in ${relOutputForMsg}/. ` +
+            `Re-run with --overwrite (or -f) to replace them.`;
+          cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
+          return;
+        }
+        const confirmed = isCancel(
+          await p.confirm({
+            message:
+              `Overwrite ${existingFiles.length} existing file(s) in ${relOutputForMsg}/? ` +
+              `(${existingFiles.slice(0, 3).join(', ')}${existingFiles.length > 3 ? ', …' : ''})`,
+            initialValue: false,
+          }),
+        );
+        if (!confirmed) {
+          humanLog('Aborted. Re-run with --overwrite to replace files.');
+          return;
+        }
       }
 
       fs.mkdirSync(outputDir, {recursive: true});

package/src/commands/template.mjs

@@ -6,6 +6,8 @@
 
 import * as path from 'node:path';
 import * as fs from 'node:fs';
+import * as p from '@clack/prompts';
+import {isNonInteractive} from '../utils/path-safety.mjs';
 import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
@@ -15,6 +17,14 @@ import {warnOnIntegrationIssues} from '../lib/integration-warnings.mjs';
 
 export {discoverTemplates, listTemplates} from '../api/template.mjs';
 
+function isCancel(value) {
+  if (p.isCancel(value)) {
+    p.cancel('Cancelled.');
+    process.exit(0);
+  }
+  return value;
+}
+
 export function registerTemplate(program) {
   program
     .command('template [name] [path]')
@@ -49,11 +59,23 @@ export function registerTemplate(program) {
         const collision = await detectTemplateCollision(name, targetPath);
         if (collision && !options.overwrite) {
           const rel = path.relative(process.cwd(), collision) || collision;
-          const msg =
-            `Refusing to overwrite existing file ${rel}. ` +
-            `Re-run with --overwrite (or -f) to replace it.`;
-          cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
-          return;
+          if (json || isNonInteractive({json})) {
+            const msg =
+              `Refusing to overwrite existing file ${rel}. ` +
+              `Re-run with --overwrite (or -f) to replace it.`;
+            cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
+            return;
+          }
+          const confirmed = isCancel(
+            await p.confirm({
+              message: `Overwrite existing file ${rel}?`,
+              initialValue: false,
+            }),
+          );
+          if (!confirmed) {
+            humanLog('Aborted. Re-run with --overwrite to replace the file.');
+            return;
+          }
         }
       }
 

package/src/commands/upgrade.mjs

@@ -37,7 +37,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {execFile} from 'node:child_process';
 import {promisify} from 'node:util';
-import * as p from '../lib/term-log.mjs';
+import * as p from '@clack/prompts';
 import {ensureJscodeshift} from '../codemods/ensure-jscodeshift.mjs';
 import {getTransformsBetween, latestVersion} from '../codemods/registry.mjs';
 import {runCodemods} from '../codemods/runner.mjs';

package/src/commands/upgrade.test.mjs

@@ -24,7 +24,7 @@ beforeEach(() => {
     logCalls.push(args.join(' '));
   });
   vi.spyOn(console, 'error').mockImplementation(() => {});
-  // Some human logs are written straight to process.stdout — capture that too.
+  // @clack/prompts writes directly to process.stdout — capture that too.
   vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
     stdoutCalls.push(typeof chunk === 'string' ? chunk : chunk.toString());
     return true;

package/src/index.mjs

@@ -174,7 +174,7 @@ function fullCommandName(actionCommand) {
  *
  * If --json is set on a command that is not on the JSON_SUPPORTED allowlist,
  * emit a structured error envelope and exit 1 — without running the command's
- * action (so no filesystem mutations, no interactive prompts, no spawned processes).
+ * action (so no filesystem mutations, no clack prompts, no spawned processes).
  *
  * This is the single source of truth for "command does not support --json".
  * Individual commands should NOT re-check this; they may assume that if their
@@ -323,7 +323,7 @@ ${line('')}
 ${line('  Design system installed!')}
 ${line('')}
 ${line('  Get started:')}
-${line(`    ${r} init          Setup + AI agent docs`)}
+${line(`    ${r} init          Interactive setup`)}
 ${line(`    ${r} --help        See all commands`)}
 ${line('')}
 ${line('  Or run directly:')}

package/src/utils/interactive.mjs

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Interactivity contract for the CLI.
+ *
+ * A single source of truth for "can this process prompt the user?". Several
+ * commands launch @clack/prompts wizards; in a non-interactive context (CI,
+ * piped stdin/stdout, no TTY) those prompts block forever. Historically each
+ * command answered this question differently — some checked `stdout.isTTY`,
+ * one checked `stdin.isTTY`, one added `!process.env.CI`, and some had no
+ * guard at all. This module centralizes the check so every command behaves
+ * identically.
+ *
+ * Two entry points, for two situations:
+ *
+ *   - `requireInteractive()` — for commands whose prompt IS the work
+ *     (e.g. `astryx init`, `astryx theme`). With no TTY there is nothing to do, so
+ *     fail fast (exit 1) with actionable, non-interactive guidance.
+ *
+ *   - `isInteractive()` — for commands with an OPTIONAL secondary prompt
+ *     that runs after the primary work has already succeeded; callers use
+ *     this to skip the prompt gracefully in non-interactive contexts.
+ */
+
+/**
+ * True when the process can safely run an interactive prompt.
+ *
+ * Requires BOTH stdin and stdout to be TTYs (clack reads stdin and renders to
+ * stdout) and that we are not in a CI environment. A CI runner may allocate a
+ * pseudo-TTY, so `process.env.CI` is an explicit override: never prompt in CI.
+ *
+ * @param {object} [env] - Override hook for tests.
+ * @param {boolean} [env.stdinTTY=process.stdin.isTTY]
+ * @param {boolean} [env.stdoutTTY=process.stdout.isTTY]
+ * @param {boolean} [env.ci=Boolean(process.env.CI)]
+ * @returns {boolean}
+ */
+export function isInteractive({
+  stdinTTY = Boolean(process.stdin && process.stdin.isTTY),
+  stdoutTTY = Boolean(process.stdout && process.stdout.isTTY),
+  ci = Boolean(process.env.CI),
+} = {}) {
+  if (ci) return false;
+  return stdinTTY && stdoutTTY;
+}
+
+/**
+ * Guard for commands whose primary action is an interactive wizard. When the
+ * process is non-interactive, prints an actionable error and exits 1 instead
+ * of hanging on a prompt that will never receive input.
+ *
+ * @param {object} options
+ * @param {string} options.command - Command name for the message, e.g. 'init'.
+ * @param {string} options.hint - Concrete non-interactive invocation, e.g.
+ *   '`pnpm astryx init --all` or `--features agents,theme,template`'.
+ * @param {boolean} [options.json=false] - When true, the command does not
+ *   support --json; we still exit 1 but skip the human-formatted guidance.
+ * @param {object} [env] - Forwarded to isInteractive (test hook).
+ * @returns {void} Returns when interactive; otherwise calls process.exit(1).
+ */
+export function requireInteractive({command, hint, json = false} = {}, env) {
+  if (isInteractive(env)) return;
+  const name = command ? `astryx ${command}` : 'this command';
+  console.error(
+    `Error: \`${name}\` with no flags is interactive and requires a TTY.`,
+  );
+  if (hint) {
+    console.error(`Run non-interactively with: ${hint}`);
+  }
+  if (!json) {
+    console.error(
+      'Detected a non-interactive environment (no TTY, piped I/O, or CI=1).',
+    );
+  }
+  process.exit(1);
+}

package/src/utils/interactive.test.mjs

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit tests for the interactivity contract.
+ *
+ * isInteractive() is pure given its injected env, so these are fast unit
+ * tests. The "does the command actually fail fast instead of hanging" proof
+ * lives in the per-command subprocess tests (init/theme non-interactive).
+ */
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {isInteractive, requireInteractive} from './interactive.mjs';
+
+describe('isInteractive', () => {
+  it('is true only when stdin AND stdout are TTYs and not CI', () => {
+    expect(isInteractive({stdinTTY: true, stdoutTTY: true, ci: false})).toBe(true);
+  });
+
+  it('is false when stdin is not a TTY (piped input)', () => {
+    expect(isInteractive({stdinTTY: false, stdoutTTY: true, ci: false})).toBe(false);
+  });
+
+  it('is false when stdout is not a TTY (piped output)', () => {
+    expect(isInteractive({stdinTTY: true, stdoutTTY: false, ci: false})).toBe(false);
+  });
+
+  it('is false in CI even with a pseudo-TTY on both streams', () => {
+    expect(isInteractive({stdinTTY: true, stdoutTTY: true, ci: true})).toBe(false);
+  });
+});
+
+describe('requireInteractive', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns (does not exit) when interactive', () => {
+    const exit = vi.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('exit should not be called');
+    });
+    expect(() =>
+      requireInteractive(
+        {command: 'init', hint: '`astryx init --all`'},
+        {stdinTTY: true, stdoutTTY: true, ci: false},
+      ),
+    ).not.toThrow();
+    expect(exit).not.toHaveBeenCalled();
+  });
+
+  it('exits 1 with actionable guidance when non-interactive', () => {
+    const exit = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => {
+        throw new Error('__exit__');
+      });
+    const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() =>
+      requireInteractive(
+        {command: 'theme', hint: '`astryx theme <preset>`'},
+        {stdinTTY: false, stdoutTTY: false, ci: false},
+      ),
+    ).toThrow('__exit__');
+    expect(exit).toHaveBeenCalledWith(1);
+    const output = err.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(output).toMatch(/requires a TTY/i);
+    expect(output).toMatch(/astryx theme <preset>/);
+    expect(output).toMatch(/`astryx theme`/);
+    expect(output).not.toMatch(/\bxds\b/);
+  });
+});

package/src/utils/path-safety.mjs

@@ -165,3 +165,21 @@ export function isFilePathArg(pathArg) {
   const ext = path.extname(base).toLowerCase();
   return ext.length > 0 && FILE_EXTENSIONS.has(ext);
 }
+
+/**
+ * True when the process is running non-interactively (no TTY) or when the
+ * caller has signaled JSON / scripted use. Commands consult this before
+ * prompting for confirmation; in scripted mode they require an explicit
+ * `--overwrite` flag instead.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.json] - Caller's --json flag.
+ * @returns {boolean}
+ */
+export function isNonInteractive({json = false} = {}) {
+  if (json) return true;
+  // stdin not a TTY means piped input or scripted execution.
+  if (process.stdin && process.stdin.isTTY === false) return true;
+  if (process.stdout && process.stdout.isTTY === false) return true;
+  return false;
+}

package/templates/blocks/components/TabList/TabListTabsWithActions.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'TabList — With Actions',
   displayName: 'TabList — With Actions',
   description:
-    'Page header pattern with tabs on the left and action buttons pushed to the right. When hasDivider is true, match the Button size to the TabList size so the tabs and actions align to a shared baseline above the divider.',
+    'Page header pattern with tabs on the left and action buttons pushed to the right. When hasDivider is true, pair with a smaller button size (sm) so actions don\'t overpower the tab row.',
   isReady: true,
   aspectRatio: 4 / 3,
   componentsUsed: ['TabList', 'Tab', 'Button'],

package/templates/blocks/components/TabList/TabListTabsWithActions.tsx

@@ -55,11 +55,16 @@ export default function TabListTabsWithActions() {
         <Button
           label="Filter"
           variant="ghost"
-          size="lg"
+          size="sm"
           icon={FilterIcon}
           isIconOnly
         />
-        <Button label="New item" variant="primary" size="lg" icon={PlusIcon} />
+        <Button
+          label="New item"
+          variant="primary"
+          size="sm"
+          icon={PlusIcon}
+        />
       </div>
     </TabList>
   );

package/src/lib/term-log.mjs

@@ -1,48 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Minimal non-interactive terminal logger.
- *
- * @input  message strings from CLI commands/codemods
- * @output plain lines on stdout via humanLog (suppressed in --json mode)
- * @position src/lib — shared output helper, no side effects on import
- *
- * The CLI is fully non-interactive: it never prompts, so it only needs plain,
- * unbuffered output. This provides the *output-only* surface (`log.*`, `intro`,
- * `outro`) the CLI needs, so it has no dependency on any prompt library.
- *
- * All output is routed through `humanLog`, the CLI's stdout-discipline
- * primitive, which is a no-op in `--json` mode — so these human logs can never
- * corrupt a JSON envelope.
- *
- * Call sites use it as `import * as p from '../lib/term-log.mjs'` and call
- * `p.log.info(...)`, `p.intro(...)`, `p.outro(...)`.
- */
-
-import {humanLog} from './json.mjs';
-
-const toStr = (msg) => (msg === undefined || msg === null ? '' : String(msg));
-
-/**
- * Human-facing log surface (the small `log` API the CLI uses). All lines go to
- * stdout via humanLog; the level prefixes are cosmetic. `--json` mode suppresses
- * every one of these, keeping machine-readable stdout clean.
- */
-export const log = {
-  message: (msg) => humanLog(toStr(msg)),
-  info: (msg) => humanLog(toStr(msg)),
-  step: (msg) => humanLog(toStr(msg)),
-  success: (msg) => humanLog(`✓ ${toStr(msg)}`),
-  warn: (msg) => humanLog(`⚠ ${toStr(msg)}`),
-  error: (msg) => humanLog(`✗ ${toStr(msg)}`),
-};
-
-/** Banner printed at the start of a multi-step command. */
-export function intro(title) {
-  humanLog(`\n${toStr(title)}`);
-}
-
-/** Footer printed at the end of a multi-step command. */
-export function outro(message) {
-  humanLog(`${toStr(message)}\n`);
-}