@astryxdesign/cli 0.1.6-canary.ff5dfca → 0.1.7-canary.04cd8f7

package/src/commands/swizzle.mjs

@@ -15,18 +15,16 @@
 
 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 {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
 import {Project} from '../lib/project.mjs';
 import {
   CORE_PACKAGE,
@@ -99,14 +97,6 @@ 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
@@ -190,6 +180,7 @@ 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(
@@ -207,10 +198,10 @@ export function registerSwizzle(program) {
         for (const name of components) {
           humanLog(`  ${name}`);
         }
-        humanLog(`\nUsage: astryx swizzle <component>\n`);
-        humanLog('Example: astryx swizzle Button');
+        humanLog(`\nUsage: ${run} swizzle <component>\n`);
+        humanLog(`Example: ${run} swizzle Button`);
         humanLog(
-          '         astryx swizzle XDSButton  (XDS prefix also works)\n',
+          `         ${run} swizzle XDSButton  (XDS prefix also works)\n`,
         );
         return;
       }
@@ -314,25 +305,11 @@ export function registerSwizzle(program) {
 
       if (existingFiles.length > 0 && !options.overwrite) {
         const relOutputForMsg = path.relative(process.cwd(), outputDir) || '.';
-        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;
-        }
+        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;
       }
 
       fs.mkdirSync(outputDir, {recursive: true});
@@ -411,7 +388,7 @@ export function registerSwizzle(program) {
         humanLog(
           '  Without one they render unstyled (no error). See setup per framework:',
         );
-        humanLog(`  ${getRunPrefix()} astryx docs styling`);
+        humanLog(`  ${run} docs styling`);
         humanLog(
           '  Next.js note: the StyleX Babel plugin disables SWC and breaks next/font —',
         );

package/src/commands/template.mjs

@@ -6,25 +6,16 @@
 
 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]')
@@ -36,6 +27,7 @@ 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
@@ -59,23 +51,11 @@ export function registerTemplate(program) {
         const collision = await detectTemplateCollision(name, targetPath);
         if (collision && !options.overwrite) {
           const rel = path.relative(process.cwd(), collision) || collision;
-          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;
-          }
+          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;
         }
       }
 
@@ -120,10 +100,10 @@ export function registerTemplate(program) {
             for (const t of blocks) renderEntry(t);
           }
           humanLog('\nUsage:');
-          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');
+          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`);
           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 '@clack/prompts';
+import * as p from '../lib/term-log.mjs';
 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 {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation, formatCliCommand} 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 `astryx upgrade --from <old-version>`.';
+          `Missing required --from. Install the target version first, then run \`${getCliInvocation()} 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 `astryx upgrade --from <old-version>`.';
+          `Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun \`${getCliInvocation()} upgrade --from <old-version>\`.`;
         if (json)
           return jsonError(msg, undefined, ERROR_CODES.ERR_VERSION_DETECT);
         p.log.error(msg);
@@ -390,6 +390,9 @@ 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 ' +
@@ -409,7 +412,7 @@ export function registerUpgrade(program) {
             });
           }
           p.log.warn(guidance);
-          p.log.info(`  ${suggestedCommand}`);
+          p.log.info(`  ${formatCliCommand(suggestedCommand)}`);
           p.log.info(
             'Integrations are skipped in this preview; they will be processed on the --apply run.',
           );
@@ -619,7 +622,7 @@ export function registerUpgrade(program) {
         } catch {
           if (!json) {
             p.log.warn(
-              `Could not update agent docs. Run \`${getRunPrefix()} astryx init --features agents\` to update manually.`,
+              `Could not update agent docs. Run \`${getCliInvocation()} 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(() => {});
-  // @clack/prompts writes directly to process.stdout — capture that too.
+  // Some human logs are written straight 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,7 +12,7 @@ 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 {getRunPrefix} from './utils/package-manager.mjs';
+import {getCliInvocation} 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';
@@ -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 clack prompts, no spawned processes).
+ * action (so no filesystem mutations, no interactive 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
@@ -305,15 +305,14 @@ program
       console.log(`  ${c.name}${tag}`);
       if (c.description) console.log(`    ${c.description}`);
     }
-    console.log(`\nRun \`astryx manifest --json\` for the full structured manifest.\n`);
+    console.log(`\nRun \`${getCliInvocation()} manifest --json\` for the full structured manifest.\n`);
   });
 
 // Hidden command used by package.json postinstall scripts
 program
   .command('postinstall', {hidden: true})
   .action(() => {
-    const run = getRunPrefix();
-    const r = `${run} xds`;
+    const r = getCliInvocation();
     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)}│`;
@@ -323,7 +322,7 @@ ${line('')}
 ${line('  Design system installed!')}
 ${line('')}
 ${line('  Get started:')}
-${line(`    ${r} init          Interactive setup`)}
+${line(`    ${r} init          Setup + AI agent docs`)}
 ${line(`    ${r} --help        See all commands`)}
 ${line('')}
 ${line('  Or run directly:')}

package/src/lib/component-format.mjs

@@ -6,6 +6,7 @@
 
 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.
@@ -81,7 +82,7 @@ function formatSubComponent(comp) {
   if (table) {
     out.push(table + '\n');
   } else {
-    out.push(`See \`astryx component ${comp.name}\` for props and usage.\n`);
+    out.push(`See \`${getCliInvocation()} component ${comp.name}\` for props and usage.\n`);
   }
   return out;
 }

package/src/lib/term-log.mjs

@@ -0,0 +1,48 @@
+// 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`);
+}

package/src/utils/package-manager.mjs

@@ -72,3 +72,81 @@ 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;
+}

package/src/utils/package-manager.test.mjs

@@ -4,9 +4,16 @@ import {describe, it, expect, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {detectPackageManager} from './package-manager.mjs';
+import {
+  detectPackageManager,
+  getDlxPrefix,
+  isCliOneOff,
+  getCliInvocation,
+  formatCliCommand,
+} from './package-manager.mjs';
 
 let tmpDir;
+const ORIGINAL_ARGV1 = process.argv[1];
 
 afterEach(() => {
   if (tmpDir) {
@@ -15,6 +22,7 @@ afterEach(() => {
   }
   vi.restoreAllMocks();
   delete process.env.npm_config_user_agent;
+  process.argv[1] = ORIGINAL_ARGV1;
 });
 
 function makeTmpDir() {
@@ -111,3 +119,102 @@ describe('detectPackageManager', () => {
     expect(detectPackageManager(dir)).toBe('bun');
   });
 });
+
+describe('getDlxPrefix', () => {
+  it('returns "pnpm dlx" for pnpm projects', () => {
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(getDlxPrefix(dir)).toBe('pnpm dlx');
+  });
+
+  it('returns "yarn dlx" for yarn projects', () => {
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'yarn.lock'), '');
+    expect(getDlxPrefix(dir)).toBe('yarn dlx');
+  });
+
+  it('returns "bunx" for bun projects', () => {
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'bun.lockb'), '');
+    expect(getDlxPrefix(dir)).toBe('bunx');
+  });
+
+  it('falls back to "npx" with no signals', () => {
+    const dir = makeTmpDir();
+    delete process.env.npm_config_user_agent;
+    expect(getDlxPrefix(dir)).toBe('npx');
+  });
+});
+
+describe('isCliOneOff', () => {
+  it('detects an npm npx cache entry', () => {
+    process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+    expect(isCliOneOff()).toBe(true);
+  });
+
+  it('detects a pnpm dlx cache entry', () => {
+    process.argv[1] = '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(true);
+  });
+
+  it('detects a bunx cache entry', () => {
+    process.argv[1] = '/home/u/.bun/install/cache/@astryxdesign/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(true);
+  });
+
+  it('is false for an installed node_modules entry', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(false);
+  });
+
+  it('is false for a source checkout (dev) entry', () => {
+    process.argv[1] = '/repo/packages/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(false);
+  });
+});
+
+describe('getCliInvocation', () => {
+  it('uses the run-prefix + bare bin when installed (not one-off)', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(getCliInvocation(dir)).toBe('pnpm exec astryx');
+  });
+
+  it('uses the dlx runner + scoped package when run one-off', () => {
+    process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+    const dir = makeTmpDir();
+    delete process.env.npm_config_user_agent;
+    expect(getCliInvocation(dir)).toBe('npx @astryxdesign/cli');
+  });
+
+  it('pairs the dlx runner with the scoped package for pnpm one-off', () => {
+    process.argv[1] = '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(getCliInvocation(dir)).toBe('pnpm dlx @astryxdesign/cli');
+  });
+});
+
+describe('formatCliCommand', () => {
+  it('strips a leading "astryx" token and prepends the invocation stem', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(formatCliCommand('astryx component Button', dir)).toBe('pnpm exec astryx component Button');
+  });
+
+  it('accepts a bare subcommand (no leading astryx)', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'package-lock.json'), '{}');
+    expect(formatCliCommand('docs tokens', dir)).toBe('npx astryx docs tokens');
+  });
+
+  it('rewrites to the scoped package for one-off invocations', () => {
+    process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'package-lock.json'), '{}');
+    expect(formatCliCommand('astryx component Button', dir)).toBe('npx @astryxdesign/cli component Button');
+  });
+});

package/src/utils/path-safety.mjs

@@ -165,21 +165,3 @@ 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/src/utils/update-check.mjs

@@ -14,6 +14,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {semverGt} from './semver.mjs';
+import {getCliInvocation} from './package-manager.mjs';
 
 /**
  * Read the latest available version from local signals.
@@ -75,7 +76,7 @@ export function checkForUpdate(cwd = process.cwd()) {
   // Use semver-aware comparison so '0.0.20' is correctly treated as greater
   // than '0.0.5' (lexicographic compare gets that backwards).
   if (semverGt(latest, installed)) {
-    return `FYI: A newer version of @astryxdesign/core (${latest}) is available. Install the new package version, then run: astryx upgrade --from <old-version> --apply`;
+    return `FYI: A newer version of @astryxdesign/core (${latest}) is available. Install the new package version, then run: ${getCliInvocation()} upgrade --from <old-version> --apply`;
   }
 
   return null;

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, pair with a smaller button size (sm) so actions don\'t overpower the tab row.',
+    '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.',
   isReady: true,
   aspectRatio: 4 / 3,
   componentsUsed: ['TabList', 'Tab', 'Button'],

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

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