@astryxdesign/cli 0.1.7-canary.fb9c68c → 0.1.7

package/src/commands/swizzle.mjs

@@ -15,16 +15,18 @@
 
 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';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
 import {checkGhCli} from '../utils/github.mjs';
-import {getCliInvocation} from '../utils/package-manager.mjs';
+import {getRunPrefix} from '../utils/package-manager.mjs';
 import {Project} from '../lib/project.mjs';
 import {
   CORE_PACKAGE,
@@ -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
@@ -180,7 +190,6 @@ export function registerSwizzle(program) {
     .action(async (component, options) => {
       const coreDir = findCoreDir(process.cwd());
       const json = program.opts().json || false;
-      const run = getCliInvocation();
 
       if (!coreDir) {
         cliError(
@@ -198,10 +207,10 @@ export function registerSwizzle(program) {
         for (const name of components) {
           humanLog(`  ${name}`);
         }
-        humanLog(`\nUsage: ${run} swizzle <component>\n`);
-        humanLog(`Example: ${run} swizzle Button`);
+        humanLog(`\nUsage: astryx swizzle <component>\n`);
+        humanLog('Example: astryx swizzle Button');
         humanLog(
-          `         ${run} swizzle XDSButton  (XDS prefix also works)\n`,
+          '         astryx swizzle XDSButton  (XDS prefix also works)\n',
         );
         return;
       }
@@ -305,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});
@@ -388,7 +411,7 @@ export function registerSwizzle(program) {
         humanLog(
           '  Without one they render unstyled (no error). See setup per framework:',
         );
-        humanLog(`  ${run} docs styling`);
+        humanLog(`  ${getRunPrefix()} astryx docs styling`);
         humanLog(
           '  Next.js note: the StyleX Babel plugin disables SWC and breaks next/font —',
         );

package/src/commands/template.mjs

@@ -6,16 +6,25 @@
 
 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';
 import {template as templateApi} from '../api/template.mjs';
 import {Project} from '../lib/project.mjs';
 import {warnOnIntegrationIssues} from '../lib/integration-warnings.mjs';
-import {getCliInvocation} from '../utils/package-manager.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]')
@@ -27,7 +36,6 @@ export function registerTemplate(program) {
     .option('-f, --overwrite', 'Overwrite existing files without prompting')
     .action(async (name, targetPath, options) => {
       const json = program.opts().json || false;
-      const run = getCliInvocation();
 
       // Non-blocking nudge: if any configured integration has validation
       // issues, print one compact line to stderr pointing at
@@ -51,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;
+          }
         }
       }
 
@@ -100,10 +120,10 @@ export function registerTemplate(program) {
             for (const t of blocks) renderEntry(t);
           }
           humanLog('\nUsage:');
-          humanLog(`  ${run} template <id> [target-path]     Scaffold page or block`);
-          humanLog(`  ${run} template <id> --skeleton        Layout reference`);
-          humanLog(`  ${run} template --list --type block    List only blocks`);
-          humanLog(`  ${run} template --list --package <pkg> List from one package\n`);
+          humanLog('  astryx template <id> [target-path]     Scaffold page or block');
+          humanLog('  astryx template <id> --skeleton        Layout reference');
+          humanLog('  astryx template --list --type block    List only blocks');
+          humanLog('  astryx template --list --package <pkg> List from one package\n');
           break;
         }
 

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';
@@ -47,7 +47,7 @@ import {
 } from '../codemods/integration-discovery.mjs';
 import {runIntegrationCodemods} from '../codemods/integration-runner.mjs';
 import {installAgentDocs, discoverAgentDocs} from './agent-docs.mjs';
-import {getCliInvocation, formatCliCommand} from '../utils/package-manager.mjs';
+import {getRunPrefix} from '../utils/package-manager.mjs';
 import {isValidSemver, semverGte} from '../utils/semver.mjs';
 import {jsonOut, jsonError} from '../lib/json.mjs';
 import {Project} from '../lib/project.mjs';
@@ -176,7 +176,7 @@ export function registerUpgrade(program) {
 
       if (!options.list && !options.from) {
         const msg =
-          `Missing required --from. Install the target version first, then run \`${getCliInvocation()} upgrade --from <old-version>\`.`;
+          'Missing required --from. Install the target version first, then run `astryx upgrade --from <old-version>`.';
         if (json)
           return jsonError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);
         p.log.error(msg);
@@ -237,7 +237,7 @@ export function registerUpgrade(program) {
       const installed = detectInstalledTargetVersion();
       if (!installed) {
         const msg =
-          `Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun \`${getCliInvocation()} upgrade --from <old-version>\`.`;
+          'Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun `astryx upgrade --from <old-version>`.';
         if (json)
           return jsonError(msg, undefined, ERROR_CODES.ERR_VERSION_DETECT);
         p.log.error(msg);
@@ -390,9 +390,6 @@ export function registerUpgrade(program) {
           const codemodFlags = coreConfigCodemodNames
             .map(name => `--codemod ${name}`)
             .join(' ');
-          // Canonical (bare) form — this is a structured, machine-executable
-          // field in the --json envelope. The human print below is made
-          // install-aware via formatCliCommand.
           const suggestedCommand = `astryx upgrade --from ${currentVersion} ${codemodFlags} --apply`;
           const guidance =
             'Your astryx.config currently fails strict validation, but a pending ' +
@@ -412,7 +409,7 @@ export function registerUpgrade(program) {
             });
           }
           p.log.warn(guidance);
-          p.log.info(`  ${formatCliCommand(suggestedCommand)}`);
+          p.log.info(`  ${suggestedCommand}`);
           p.log.info(
             'Integrations are skipped in this preview; they will be processed on the --apply run.',
           );
@@ -622,7 +619,7 @@ export function registerUpgrade(program) {
         } catch {
           if (!json) {
             p.log.warn(
-              `Could not update agent docs. Run \`${getCliInvocation()} init --features agents\` to update manually.`,
+              `Could not update agent docs. Run \`${getRunPrefix()} astryx init --features agents\` to update manually.`,
             );
           }
         }

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

@@ -12,14 +12,13 @@ import {fileURLToPath} from 'node:url';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {checkForUpdate} from './utils/update-check.mjs';
-import {getCliInvocation} from './utils/package-manager.mjs';
+import {getRunPrefix} from './utils/package-manager.mjs';
 import {API_VERSION, setJsonMode} from './lib/json.mjs';
 import {buildManifest} from './lib/manifest.mjs';
 import {cliError} from './lib/cli-error.mjs';
 import {ERROR_CODES} from './lib/error-codes.mjs';
 import {levenshteinDistance} from './lib/string-utils.mjs';
 import {installJsonShim} from './lib/json-shim.mjs';
-import {isAstryxInitialized} from './commands/agent-docs.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -175,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
@@ -238,40 +237,6 @@ program.hook('postAction', (thisCommand, actionCommand) => {
   }
 });
 
-/**
- * Enforcement layer 3 — setup nudge. If this project hasn't run `astryx init`
- * yet (no Astryx marker in any agent-doc file — see isAstryxInitialized), remind
- * the user/agent that setup is missing.
- *
- * Uses `preAction` (not postAction) so it fires for EVERY valid command — even
- * ones whose action errors or calls process.exit (postAction is skipped then).
- *
- * Suppressed in --json: that is machine output with a strict clean stdout+stderr
- * contract (json-shim.test: "error envelopes have empty stderr"), and --json
- * consumers parse stdout, not stderr — a stderr nudge would not reach them anyway.
- * The core/cli postinstall layers already nudge at install time regardless of
- * --json; a machine-readable nudge could later be an envelope field. Also skipped
- * for the installer commands themselves and outside a project (no package.json).
- */
-const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
-program.hook('preAction', (thisCommand, actionCommand) => {
-  try {
-    if (program.opts().json) return; // machine mode — keep --json output clean
-    if (SETUP_NUDGE_EXEMPT.has(actionCommand.name())) return;
-    const cwd = process.cwd();
-    if (!fs.existsSync(path.join(cwd, 'package.json'))) return; // not a project
-    if (isAstryxInitialized(cwd)) return; // already set up — stay quiet
-    // Same wording as the core/cli postinstall nudges. #4151's getCliInvocation()
-    // renders the correct form for THIS project — scoped `npx @astryxdesign/cli`
-    // one-off, or `<pm> astryx` when installed — never the bare `npx astryx` footgun.
-    console.error(
-      `\nNext step: run \`${getCliInvocation(cwd)} init\` to finish setup and install the Astryx agent prompt.`,
-    );
-  } catch {
-    // Never let the nudge break a command.
-  }
-});
-
 /**
  * Command registry — each command is lazy-loaded so a broken command
  * doesn't take down the entire CLI.
@@ -340,14 +305,15 @@ program
       console.log(`  ${c.name}${tag}`);
       if (c.description) console.log(`    ${c.description}`);
     }
-    console.log(`\nRun \`${getCliInvocation()} manifest --json\` for the full structured manifest.\n`);
+    console.log(`\nRun \`astryx manifest --json\` for the full structured manifest.\n`);
   });
 
 // Hidden command used by package.json postinstall scripts
 program
   .command('postinstall', {hidden: true})
   .action(() => {
-    const r = getCliInvocation();
+    const run = getRunPrefix();
+    const r = `${run} xds`;
     const pad = (s, len) => s + ' '.repeat(Math.max(0, len - s.length));
     const W = 49; // inner width of the box
     const line = (s) => `  │ ${pad(s, W)}│`;
@@ -357,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/lib/component-format.mjs

@@ -6,7 +6,6 @@
 
 import {discoverComponents, findComponentReadme, resolveImportPath} from './component-discovery.mjs';
 import {loadDocs} from './component-loader.mjs';
-import {getCliInvocation} from '../utils/package-manager.mjs';
 
 /**
  * Derive the `defineTheme` component-override key from a theming target.
@@ -82,7 +81,7 @@ function formatSubComponent(comp) {
   if (table) {
     out.push(table + '\n');
   } else {
-    out.push(`See \`${getCliInvocation()} component ${comp.name}\` for props and usage.\n`);
+    out.push(`See \`astryx component ${comp.name}\` for props and usage.\n`);
   }
   return out;
 }

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/package-manager.mjs

@@ -72,81 +72,3 @@ export function getRunPrefix(targetDir) {
     default: return 'npx';
   }
 }
-
-/** The published CLI package name — used for one-off (uninstalled) invocations. */
-export const CLI_PACKAGE = '@astryxdesign/cli';
-
-/** The CLI binary name — only resolves once the CLI is installed (or run via CLI_PACKAGE). */
-export const CLI_BIN = 'astryx';
-
-/**
- * Get the one-off ("dlx") runner for the detected package manager.
- *
- * Unlike {@link getRunPrefix} (which runs an *installed* binary), this fetches
- * and runs a package on demand — so it is always paired with the scoped
- * {@link CLI_PACKAGE}, never the bare `astryx` bin. Running bare `npx astryx`
- * without the CLI installed resolves to an unrelated package on the registry.
- *
- * @param {string} [targetDir]
- * @returns {string} e.g. 'npx', 'pnpm dlx', 'yarn dlx', 'bunx'
- */
-export function getDlxPrefix(targetDir) {
-  const pm = detectPackageManager(targetDir);
-  switch (pm) {
-    case 'yarn': return 'yarn dlx';
-    case 'pnpm': return 'pnpm dlx';
-    case 'bun': return 'bunx';
-    case 'npm':
-    default: return 'npx';
-  }
-}
-
-/**
- * Heuristic: was the running CLI launched one-off via a package runner
- * (npx / pnpm dlx / yarn dlx / bunx) rather than from an installed dependency?
- *
- * We sniff the entry path (`process.argv[1]`) for well-known runner-cache
- * markers. This errs safe in both directions: a false negative falls back to
- * the installed form (`<prefix> astryx`, the historical behavior), and a false
- * positive emits the always-valid scoped form (`<dlx> @astryxdesign/cli`).
- *
- * @returns {boolean}
- */
-export function isCliOneOff() {
-  const entry = String(process.argv[1] || '').replace(/\\/g, '/');
-  return /\/_npx\/|\/dlx[-/]|\/\.bun\/install\/cache\/|\/bunx-/.test(entry);
-}
-
-/**
- * The safe, install-aware CLI invocation stem to suggest to users.
- *
- * - Installed / global / dev: `<run-prefix> astryx` (e.g. `pnpm exec astryx`).
- *   Bare `astryx` resolves to the local (or global) binary.
- * - One-off (npx/dlx cache): `<dlx-prefix> @astryxdesign/cli` — the bare
- *   `astryx` name isn't on disk, so npm would fetch an unrelated registry
- *   package; the scoped package always resolves to us.
- *
- * @param {string} [targetDir]
- * @returns {string}
- */
-export function getCliInvocation(targetDir) {
-  if (isCliOneOff()) return `${getDlxPrefix(targetDir)} ${CLI_PACKAGE}`;
-  return `${getRunPrefix(targetDir)} ${CLI_BIN}`;
-}
-
-/**
- * Format a full, runnable CLI command from a subcommand string.
- *
- * Accepts either `astryx component Button` or `component Button` (a leading
- * `astryx` token is stripped) and prepends the install-aware invocation stem
- * from {@link getCliInvocation}.
- *
- * @param {string} command e.g. 'astryx component Button' | 'docs tokens'
- * @param {string} [targetDir]
- * @returns {string}
- */
-export function formatCliCommand(command, targetDir) {
-  const sub = String(command).replace(/^\s*astryx\b\s*/, '').trim();
-  const stem = getCliInvocation(targetDir);
-  return sub ? `${stem} ${sub}` : stem;
-}