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

package/src/commands/setup-nudge.test.mjs

@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guardrail tests — the centralized setup check + enforcement layer 3.
+ *
+ * Unit: isAstryxInitialized() detects the Astryx marker across EVERY agent-doc
+ * location (including the previously-missed Hermes files) and legacy XDS blocks.
+ *
+ * Integration: the CLI nudges (stderr) before a command when the project hasn't
+ * run init — INCLUDING in --json mode (agents pass --json, and stderr never
+ * corrupts the stdout JSON envelope). Quiet once set up, outside a project, and
+ * for the installer command itself.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {isAstryxInitialized} from './agent-docs.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.resolve(__dirname, '..', '..', 'bin', 'astryx.mjs');
+const MARKER = '<!-- ASTRYX:START -->';
+const NUDGE = /finish setup and install the Astryx agent prompt/;
+
+let tmp;
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-setup-nudge-'));
+});
+afterEach(() => {
+  fs.rmSync(tmp, {recursive: true, force: true});
+});
+
+function write(rel, body) {
+  const p = path.join(tmp, rel);
+  fs.mkdirSync(path.dirname(p), {recursive: true});
+  fs.writeFileSync(p, body);
+}
+
+function run(args, cwd = tmp) {
+  return spawnSync(process.execPath, [CLI, ...args], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 30_000,
+    env: {...process.env, FORCE_COLOR: '0'},
+  });
+}
+
+describe('isAstryxInitialized — centralized setup check (one place)', () => {
+  it('is false in an empty project', () => {
+    expect(isAstryxInitialized(tmp)).toBe(false);
+  });
+
+  // Covers EVERY location a preset can write — .hermes.md/HERMES.md were the gap.
+  it.each(['AGENTS.md', 'CLAUDE.md', '.claude/CLAUDE.md', '.cursorrules', '.hermes.md', 'HERMES.md'])(
+    'detects the marker in %s',
+    file => {
+      write(file, `# doc\n${MARKER}\nbody`);
+      expect(isAstryxInitialized(tmp)).toBe(true);
+    },
+  );
+
+  it('detects the legacy XDS marker for back-compat', () => {
+    write('AGENTS.md', '<!-- XDS:START -->');
+    expect(isAstryxInitialized(tmp)).toBe(true);
+  });
+
+  it('is false when a doc file exists WITHOUT the marker', () => {
+    write('AGENTS.md', 'project notes, no astryx block');
+    expect(isAstryxInitialized(tmp)).toBe(false);
+  });
+});
+
+describe('enforcement layer 3 — per-command setup nudge', () => {
+  const asProject = () => write('package.json', '{"name":"t"}');
+
+  it('nudges on stderr after a command when not set up', () => {
+    asProject();
+    const r = run(['docs', 'tokens']);
+    expect(r.stderr).toMatch(NUDGE);
+  });
+
+  it('is suppressed in --json (machine mode stays clean), stdout valid JSON', () => {
+    asProject();
+    const r = run(['--json', 'docs', 'tokens']);
+    // --json is machine output with a clean stdout+stderr contract; the human
+    // nudge must NOT leak into it (json-shim: error envelopes have empty stderr).
+    expect(r.stderr).not.toMatch(NUDGE);
+    expect(() => JSON.parse(r.stdout)).not.toThrow();
+  });
+
+  it('is quiet once set up (marker present)', () => {
+    asProject();
+    write('AGENTS.md', MARKER);
+    expect(run(['docs', 'tokens']).stderr).not.toMatch(NUDGE);
+  });
+
+  it('is quiet outside a project (no package.json)', () => {
+    expect(run(['docs', 'tokens']).stderr).not.toMatch(NUDGE);
+  });
+
+  it('does not nudge for the installer command itself', () => {
+    asProject();
+    expect(run(['init']).stderr).not.toMatch(NUDGE);
+  });
+});

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

@@ -11,8 +11,11 @@
  *
  * Pipeline (--apply):
  *   1. Read installed @astryxdesign/core (or legacy @xds/core) version
- *   2. Run codemods for --from → installed version
- *   3. Refresh agent docs (AGENTS.md / CLAUDE.md) if present
+ *   2. Refresh the managed agent-docs block (AGENTS.md / CLAUDE.md) to the
+ *      installed version — runs on EVERY path (including the up-to-date /
+ *      no-codemods short-circuits), because the block documents the installed
+ *      library, not the codemod outcome. Dry-run reports without writing.
+ *   3. Run codemods for --from → installed version
  *
  * Options:
  *   --from <version>       Previous version before the dependency upgrade
@@ -37,7 +40,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';
@@ -46,8 +49,8 @@ import {
   selectIntegrationCodemods,
 } 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 {installAgentDocs, inspectAgentDocs} from './agent-docs.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';
@@ -135,6 +138,103 @@ async function runPostCodemodHooks(hooks, context, silent) {
   }
 }
 
+/**
+ * Refresh (or, in dry-run, report) the managed agent-docs block after a version
+ * bump. The block (`<!-- ASTRYX:START --> … <!-- ASTRYX:END -->`) documents the
+ * INSTALLED library — its version, component index, and agent rules — so it must
+ * be re-synced on EVERY upgrade path, including the up-to-date / no-codemods
+ * short-circuits where no source file changes. That was the gap in #4168: an
+ * agent reading a stale index queries missing components and follows superseded
+ * rules. Three cases, one detection pass:
+ *
+ * - `stale`   — a managed block records an older version (or a legacy XDS
+ *               marker). `--apply` rewrites it; dry-run reports the pending
+ *               refresh as a loud next step and writes nothing.
+ * - `missing` — core is installed but no managed block exists anywhere (the repo
+ *               never ran `init`, or its agent docs were never marked). We never
+ *               silently create docs mid-upgrade; we nudge to run `init`.
+ * - `current` — every block already matches the installed version: stay silent.
+ *
+ * @param {{cwd: string, installedVersion: string, apply: boolean, json: boolean}} ctx
+ * @returns {import('../types/upgrade').AgentDocsSummary}
+ */
+export function refreshAgentDocs({cwd, installedVersion, apply, json}) {
+  const inspection = inspectAgentDocs(cwd, installedVersion);
+  /** @type {import('../types/upgrade').AgentDocsSummary} */
+  const summary = {
+    status: inspection.status,
+    installedVersion,
+    fromVersions: inspection.blockVersions,
+    files: [],
+    refreshed: false,
+    action: 'none',
+  };
+
+  // Never initialized — don't silently create docs during an upgrade; nudge.
+  if (inspection.status === 'missing') {
+    summary.action = 'nudge-init';
+    if (!json) {
+      p.log.warn(
+        `No Astryx agent-docs block found — AI agents have no component index. Run \`${formatCliCommand('astryx init --features agents')}\` to install it.`,
+      );
+    }
+    return summary;
+  }
+
+  if (inspection.status === 'current') return summary;
+
+  // Stale.
+  summary.files = inspection.staleFiles;
+  const fromLabel = summary.fromVersions.length
+    ? `v${summary.fromVersions.join(', v')}`
+    : 'an unknown version';
+
+  if (!apply) {
+    // Dry-run: report the pending change, never write.
+    summary.action = 'would-refresh';
+    if (!json) {
+      p.log.warn(
+        `Agent docs are stale: block is at ${fromLabel}, installed is v${installedVersion}. Re-run with --apply to refresh (${summary.files.join(', ')}).`,
+      );
+    }
+    return summary;
+  }
+
+  // Apply: rewrite only files that already carry a marker (onlyReplace).
+  try {
+    const written = installAgentDocs(cwd, {onlyReplace: true});
+    summary.refreshed = written.length > 0;
+    summary.files = written;
+    if (summary.refreshed) {
+      summary.action = 'refreshed';
+      if (!json) {
+        p.log.success(
+          `Agent docs refreshed → v${installedVersion} (from ${fromLabel}): ${written.join(', ')}`,
+        );
+      }
+    } else {
+      // We detected a stale marked block but rewrote nothing, and
+      // installAgentDocs did not throw — the block markers are malformed (e.g. a
+      // START with no matching END, so the writer can't safely splice it). Don't
+      // fail silently: the block is exactly the artifact agents rely on.
+      summary.action = 'error';
+      if (!json) {
+        p.log.warn(
+          `Agent docs look stale but couldn't be refreshed — the <!-- ASTRYX:START -->/<!-- ASTRYX:END --> markers may be malformed. Run \`${formatCliCommand('astryx init --features agents')}\` to reinstall the block.`,
+        );
+      }
+    }
+  } catch {
+    summary.action = 'error';
+    if (!json) {
+      p.log.warn(
+        `Could not refresh agent docs. Run \`${formatCliCommand('astryx init --features agents')}\` to update them manually.`,
+      );
+    }
+  }
+  return summary;
+}
+
 /**
  * Register the `upgrade` command (codemod-driven version migration).
  */
@@ -176,7 +276,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 +337,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);
@@ -254,6 +354,19 @@ export function registerUpgrade(program) {
         );
       }
 
+      // Sync the managed agent-docs block to the installed version FIRST. It
+      // documents the installed library (version + component index + rules),
+      // independent of any source codemods, so it must be refreshed on every
+      // path below — including the up-to-date / no-codemods short-circuits that
+      // return before codemods ever run (issue #4168). Dry-run reports without
+      // writing. Folded into every terminal payload as `agentDocs`.
+      const agentDocs = refreshAgentDocs({
+        cwd: process.cwd(),
+        installedVersion: targetVersion,
+        apply: options.apply,
+        json,
+      });
+
       // ───────────────────────────────────────────────────────────────────
       // PIPELINE ORDERING
       //
@@ -275,6 +388,7 @@ export function registerUpgrade(program) {
             status: 'up_to_date',
             from: currentVersion,
             to: targetVersion,
+            agentDocs,
           });
         }
         p.log.success('Already up to date — no codemods to run.');
@@ -390,6 +504,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 ' +
@@ -406,10 +523,11 @@ export function registerUpgrade(program) {
               suggestedCommand,
               message: guidance,
               note: 'Integrations are skipped in this preview; they will be processed on the --apply run.',
+              agentDocs,
             });
           }
           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.',
           );
@@ -417,11 +535,12 @@ export function registerUpgrade(program) {
           return;
         }
         // Genuine config error (apply mode, OR dry-run with no pending core
-        // config codemod that would fix it): abort as before.
+        // config codemod that would fix it): abort as before. The agent-docs
+        // refresh already ran (it's independent of config), so surface it.
         if (json)
           return jsonError(
             err.message,
-            undefined,
+            {agentDocs},
             ERROR_CODES.ERR_INVALID_ARGUMENT,
           );
         p.log.error(err.message);
@@ -499,6 +618,7 @@ export function registerUpgrade(program) {
             status: 'no_codemods',
             from: currentVersion,
             to: targetVersion,
+            agentDocs,
           });
         }
         p.log.success('No codemods available for this version range.');
@@ -510,7 +630,7 @@ export function registerUpgrade(program) {
       if (totalTransforms === 0 && totalOptional === 0) {
         const msg = `Codemod "${options.codemod}" not found. Use --list to see available codemods.`;
         if (json)
-          return jsonError(msg, undefined, ERROR_CODES.ERR_UNKNOWN_CODEMOD);
+          return jsonError(msg, {agentDocs}, ERROR_CODES.ERR_UNKNOWN_CODEMOD);
         p.log.error(msg);
         p.outro('Aborted');
         process.exitCode = 1;
@@ -532,7 +652,10 @@ export function registerUpgrade(program) {
         to: targetVersion,
         codemods: totalTransforms,
         integrations: integrations.map(i => i.name ?? i.__spec),
-        agentDocsRefreshed: false,
+        // Refreshed up front (before the gates above), so the receipt just
+        // reports what happened. `agentDocsRefreshed` kept for back-compat.
+        agentDocsRefreshed: agentDocs.refreshed,
+        agentDocs,
       };
 
       // Run file-based integration codemods alongside the core registry
@@ -604,26 +727,9 @@ export function registerUpgrade(program) {
         }
       }
 
-      // Refresh agent docs if any exist (AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, etc.)
-      // Always update after --apply; also update during dry-run if files exist,
-      // since the index reflects the installed CLI version, not the codemods.
-      const existingDocs = discoverAgentDocs(process.cwd());
-      if (existingDocs.length > 0) {
-        try {
-          // onlyReplace: only update files that already have Astryx markers.
-          // Don't inject into files that never had Astryx content.
-          const written = installAgentDocs(process.cwd(), {onlyReplace: true});
-          receipt.agentDocsRefreshed = written.length > 0;
-          if (!json && written.length > 0)
-            p.log.success(`Agent docs updated: ${written.join(', ')}`);
-        } catch {
-          if (!json) {
-            p.log.warn(
-              `Could not update agent docs. Run \`${getRunPrefix()} astryx init --features agents\` to update manually.`,
-            );
-          }
-        }
-      }
+      // NOTE: the managed agent-docs block was already refreshed up front (see
+      // refreshAgentDocs after installed-version detection), so it stays in sync
+      // even on the short-circuit paths that return before this point.
 
       receipt.filesChanged = mergedFilesChanged;
       receipt.transformsApplied = mergedTransformsApplied;