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

package/src/commands/upgrade.test.mjs

@@ -6,6 +6,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import {Command} from 'commander';
 import {registerUpgrade} from './upgrade.mjs';
+import {generateCompressedIndex} from './agent-docs.mjs';
 
 let tmpDir;
 let originalCwd;
@@ -24,7 +25,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;
@@ -158,3 +159,156 @@ describe('upgrade --list dedup', () => {
     expect(names.length).toBe(unique.size);
   });
 });
+
+// Issue #4168 — `upgrade` must refresh the managed agent-docs block after a
+// version bump, on EVERY path (the block documents the installed library, not
+// the codemod outcome), and must NOT write during a dry run.
+describe('upgrade agent-docs refresh (#4168)', () => {
+  /** Write an agent-doc file with a managed block generated for `version`. */
+  function writeAgentBlock(rel, version) {
+    const filePath = path.join(tmpDir, rel);
+    fs.mkdirSync(path.dirname(filePath), {recursive: true});
+    fs.writeFileSync(filePath, `# Doc\n\n${generateCompressedIndex(version)}\n`);
+  }
+
+  it('refreshes a stale block with --apply, even when there are no codemods (up-to-date path)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+
+    // --from == installed → up-to-date short-circuit: no codemods run, yet the
+    // stale block must still be brought current. This is the exact gap in #4168.
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.type).toBe('upgrade.status');
+    expect(result.data.status).toBe('up_to_date');
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('refreshed');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    expect(result.data.agentDocs.fromVersions).toEqual(['0.0.1']);
+    expect(result.data.agentDocs.files).toContain('AGENTS.md');
+
+    const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toMatch(/Astryx v0\.0\.15 ·/);
+    expect(content).not.toMatch(/Astryx v0\.0\.1 ·/);
+  });
+
+  it('reports a stale block on a dry run WITHOUT writing', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+    const before = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15']); // no --apply
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('would-refresh');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // The file must be untouched by a dry run.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(before);
+  });
+
+  it('refreshes a stale block on the no-codemods path (--apply)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.11'); // (0.0.10, 0.0.11] has no registered codemods
+    writeSourceFile();
+    writeAgentBlock('CLAUDE.md', '0.0.1');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.10', '--apply', '--path', 'src']);
+
+    expect(result.type).toBe('upgrade.status');
+    expect(result.data.status).toBe('no_codemods');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    expect(fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8')).toMatch(/Astryx v0\.0\.11 ·/);
+  });
+
+  it('nudges to run init when core is installed but no managed block exists', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    // No agent-doc files at all.
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('missing');
+    expect(result.data.agentDocs.action).toBe('nudge-init');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // Must NOT silently create docs during an upgrade.
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+  });
+
+  it('treats an agent file without our markers as "never initialized" (missing)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nHand-written, no astryx block.\n');
+    const before = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('missing');
+    expect(result.data.agentDocs.action).toBe('nudge-init');
+    // An unmarked file is left exactly as-is.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(before);
+  });
+
+  it('does not silently no-op a stale block with malformed markers (START without END)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    // A corrupted block: START + version header but no matching END marker, so
+    // the writer can't safely splice it. This must not crash, corrupt the file,
+    // or falsely claim success — it should surface an error and nudge re-init.
+    const corrupted =
+      '# A\n\n<!-- ASTRYX:START -->\nAstryx v0.0.1 · 9 components\nguidance, but no end marker\n';
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), corrupted);
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('error');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // File left byte-for-byte intact — never corrupted.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(corrupted);
+  });
+
+  it('stays silent when the block already matches the installed version', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.15');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('current');
+    expect(result.data.agentDocs.action).toBe('none');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+  });
+
+  it('migrates a legacy XDS block to the current Astryx block (--apply)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    fs.writeFileSync(
+      path.join(tmpDir, 'CLAUDE.md'),
+      '# Claude\n\n<!-- XDS:START -->\nlegacy index\n<!-- XDS:END -->\n\nMore rules.\n',
+    );
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+    expect(content).toMatch(/Astryx v0\.0\.15 ·/);
+    expect(content).not.toContain('legacy index');
+    expect(content).toContain('More rules.');
+  });
+
+  it('surfaces agentDocs in the human output on the up-to-date path', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'upgrade', '--from', '0.0.15', '--apply']);
+    const output = stdoutCalls.join('') + logCalls.join('\n');
+    expect(output).toMatch(/Agent docs refreshed/i);
+  });
+});

package/src/index.mjs

@@ -12,13 +12,14 @@ 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';
 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));
 
@@ -174,7 +175,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
@@ -237,6 +238,40 @@ 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.
@@ -305,15 +340,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 +357,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/types/upgrade.d.ts

@@ -23,6 +23,31 @@ export interface UpgradeListEntry {
   version: string;
 }
 
+/**
+ * State of the managed agent-docs block (`<!-- ASTRYX:START --> … END -->`)
+ * relative to the installed core version, plus what `upgrade` did about it.
+ * Present on every upgrade response (run, status, and the codemod/config error
+ * envelopes) because the block is refreshed independently of codemods.
+ *
+ * - `refreshed`     — a stale block was rewritten (`--apply` only).
+ * - `would-refresh` — a stale block was detected in dry-run; nothing written.
+ * - `nudge-init`    — no managed block exists; user should run `init`.
+ * - `error`         — refresh was attempted but writing failed.
+ * - `none`          — nothing to do (block already current).
+ */
+export interface AgentDocsSummary {
+  status: 'missing' | 'stale' | 'current';
+  /** Installed core version the block should reflect. */
+  installedVersion: string;
+  /** Distinct stale block versions found (the "from" side of the refresh). */
+  fromVersions: string[];
+  /** Files rewritten (apply) or that would be rewritten (dry-run). */
+  files: string[];
+  /** True only when a block was actually rewritten (apply mode). */
+  refreshed: boolean;
+  action: 'refreshed' | 'would-refresh' | 'nudge-init' | 'error' | 'none';
+}
+
 /** xds --json upgrade [--apply] */
 export interface UpgradeRunResponse {
   type: 'upgrade.run';
@@ -32,6 +57,7 @@ export interface UpgradeRunResponse {
     codemods: number;
     depsUpdated: string[];
     agentDocsRefreshed: boolean;
+    agentDocs: AgentDocsSummary;
   };
 }
 
@@ -49,8 +75,18 @@ export interface UpgradeRunResponse {
 export interface UpgradeStatusResponse {
   type: 'upgrade.status';
   data:
-    | {status: 'up_to_date'; from: string; to: string}
-    | {status: 'no_codemods'; from: string; to: string}
+    | {
+        status: 'up_to_date';
+        from: string;
+        to: string;
+        agentDocs: AgentDocsSummary;
+      }
+    | {
+        status: 'no_codemods';
+        from: string;
+        to: string;
+        agentDocs: AgentDocsSummary;
+      }
     | {
         status: 'config_fixable';
         from: string;
@@ -60,5 +96,6 @@ export interface UpgradeStatusResponse {
         suggestedCommand: string;
         message: string;
         note: string;
+        agentDocs: AgentDocsSummary;
       };
 }

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;