@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/clients/cli/run.mjs

@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file One run of the CLI, after the Node version gate: choose who answers
+ * the folder, hand the run off when that is another release (spec AST-081
+ * FR2, FR9), then dispatch the command.
+ *
+ * @input The arguments after `astryx`, read from `process.argv`; the CLI
+ *   package root; and, for a run a programmatic host started, the reason the
+ *   host declined the project's own CLI.
+ * @output The command's effects. The run owns the process: its exit status is
+ *   `process.exitCode`, unless a hand-off or a failure exits the process.
+ * @position clients/cli — called by `bin/astryx.mjs` and by the host entry
+ *   (`host/index.mjs`).
+ */
+
+/**
+ * Run the CLI once in this process.
+ *
+ * Every import here is dynamic: modules that load `styleText` must load only
+ * after the bin's Node version gate, and the release choice must run before
+ * the command modules load, so a run handed to another release loads none of
+ * them.
+ *
+ * @param {{cliRoot: string, argv: string[], declinedProjectCli?: string}} input
+ * @returns {Promise<import('../../host/index.js').HostedCliResult | undefined>}
+ *   resolves when the command has finished; with another release's result
+ *   when, in a hosted run, that release's host entry answered
+ */
+export async function runCli({cliRoot, argv, declinedProjectCli}) {
+  const {startRun} = await import('../../foundation/release/handoff.mjs');
+  const answered = await startRun({cliRoot, argv, declinedProjectCli});
+  if (answered) return answered;
+
+  const {
+    program,
+    loadProjectDebugHandler,
+    loadProjectForHelp,
+    handleVersionJsonPreflight,
+  } = await import('./index.mjs');
+  const {isJsonMode, toErrorEnvelope} =
+    await import('../../foundation/response/json.mjs');
+  const {handleCommanderError} = await import('./lib/json-shim.mjs');
+  const {setOutcome} = await import('../../foundation/debug/index.mjs');
+
+  /**
+   * Top-level error boundary (contract guarantee #4): an uncaught throw must
+   * never reach a --json consumer as a raw stack trace. If we're in JSON mode,
+   * convert it to the contract's error envelope on stdout and exit 1;
+   * otherwise preserve the normal human-facing behavior.
+   *
+   * We detect JSON mode two ways: the global flag (set once root options are
+   * parsed) and a raw argv check, since a throw can occur during
+   * parsing/command load — before the preAction hook engages the flag.
+   */
+  function inJsonMode() {
+    return isJsonMode() || process.argv.slice(2).includes('--json');
+  }
+
+  /** @param {unknown} err */
+  function handleFatal(err) {
+    // CommanderError (parse errors, --help, unknown command) routes
+    // through the JSON shim so that a --json consumer always gets a
+    // valid envelope and the right exit code. handleCommanderError
+    // calls process.exit when it owns the error.
+    if (handleCommanderError(err)) return;
+
+    // Anything still here is an uncaught throw or an unhandled rejection —
+    // a bug rather than a user error, and the class of failure most worth
+    // having a record of.
+    setOutcome('fatal', {exitCode: 1, error: err});
+
+    if (inJsonMode()) {
+      // Only emit if a command didn't already produce an envelope.
+      if (!process.__xdsJsonHandled) {
+        process.__xdsJsonHandled = true;
+        console.log(JSON.stringify(toErrorEnvelope(err), null, 2));
+      }
+      process.exit(1);
+    }
+    // Human mode: preserve Commander/Node default-ish behavior.
+    console.error(
+      err instanceof Error ? err.stack || err.message : String(err),
+    );
+    process.exit(1);
+  }
+
+  process.on('unhandledRejection', handleFatal);
+  process.on('uncaughtException', handleFatal);
+
+  // Pick up the project's `debug` function before parsing, so parse errors
+  // and `--help` — which short-circuit before any hook runs — are reported
+  // too.
+  await loadProjectDebugHandler();
+  // Help prints its commands while Commander parses, so a help run reads the
+  // project's declared `cliCommand` here.
+  await loadProjectForHelp();
+
+  // `--version --json` answers and exits without Commander, so it runs here —
+  // after the handler exists, or the run would go unrecorded.
+  handleVersionJsonPreflight();
+
+  try {
+    await program.parseAsync(process.argv);
+  } catch (err) {
+    handleFatal(err);
+  }
+}

package/foundation/agent-docs/agent-doc-state.d.mts

@@ -4,15 +4,25 @@
 /**
  * Find all existing agent doc files in a directory, across EVERY location any
  * preset can write (see {@link AGENT_DOC_PATHS}: AGENTS.md, CLAUDE.md,
- * .claude/CLAUDE.md, .cursorrules, .hermes.md, HERMES.md).
+ * .claude/CLAUDE.md, GEMINI.md, .cursorrules, .hermes.md, HERMES.md).
  * @param {string} targetDir
  * @returns {string[]} Relative paths of existing agent doc files
  */
 export function discoverAgentDocs(targetDir: string): string[];
+/**
+ * Whether `content` holds an Astryx block. A managed block that only imports
+ * another file (the one-line `@./AGENTS.md` that init writes to GEMINI.md) does
+ * not count: it holds nothing once that file has lost its block. A malformed
+ * block still counts, so a half-written file reads as set up.
+ *
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function holdsAstryxBlock(content: string): boolean;
 /**
  * Single source of truth for "is Astryx set up in this project?" — true when any
- * agent-doc file already carries the Astryx marker, i.e. `init` / `agent-docs`
- * has run. Reused by the init & upgrade commands, the per-command setup nudge
+ * agent-doc file already holds an Astryx block, i.e. `init` / `agent-docs` has
+ * run. Reused by the init & upgrade commands, the per-command setup nudge
  * (enforcement layer 3), and the cli postinstall nudge (layer 2). Core's
  * postinstall (separate package, layer 1) mirrors the same marker contract.
  *
@@ -68,6 +78,7 @@ export function shouldNudge({ scriptPath, npmCommand, isSetUp }?: {
 export const AGENTS_MD: "AGENTS.md";
 export const CLAUDE_MD: "CLAUDE.md";
 export const CLAUDE_DIR_MD: ".claude/CLAUDE.md";
+export const GEMINI_MD: "GEMINI.md";
 export const CURSOR_RULES: ".cursorrules";
 export const HERMES_DOT_MD: ".hermes.md";
 export const HERMES_MD: "HERMES.md";
@@ -77,10 +88,12 @@ export const LEGACY_MARKER_START: "<!-- XDS:START -->";
 export const LEGACY_MARKER_END: "<!-- XDS:END -->";
 /**
  * The canonical set of EVERY location an --agent preset (or the default) can
- * write the Astryx block. SINGLE SOURCE OF TRUTH: discovery, removal, and the
- * `isAstryxInitialized` predicate all derive from this list, so "where init
- * writes" and "where we look" can never drift. (Explicit --agent-docs-path
- * targets are user-chosen and not enumerable here.)
+ * write a managed Astryx block — the full block, or the one-line import of
+ * AGENTS.md that the default writes to GEMINI.md. SINGLE
+ * SOURCE OF TRUTH: discovery, removal, and the `isAstryxInitialized` predicate
+ * all derive from this list, so "where init writes" and "where we look" can
+ * never drift. (Explicit --agent-docs-path targets are user-chosen and not
+ * enumerable here.)
  */
 export const AGENT_DOC_PATHS: string[];
 /**

package/foundation/agent-docs/agent-doc-state.mjs

@@ -29,6 +29,7 @@ import * as path from 'node:path';
 export const AGENTS_MD = 'AGENTS.md';
 export const CLAUDE_MD = 'CLAUDE.md';
 export const CLAUDE_DIR_MD = '.claude/CLAUDE.md'; // cross-platform literal
+export const GEMINI_MD = 'GEMINI.md';
 export const CURSOR_RULES = '.cursorrules';
 export const HERMES_DOT_MD = '.hermes.md';
 export const HERMES_MD = 'HERMES.md';
@@ -41,15 +42,18 @@ export const LEGACY_MARKER_END = '<!-- XDS:END -->';
 
 /**
  * The canonical set of EVERY location an --agent preset (or the default) can
- * write the Astryx block. SINGLE SOURCE OF TRUTH: discovery, removal, and the
- * `isAstryxInitialized` predicate all derive from this list, so "where init
- * writes" and "where we look" can never drift. (Explicit --agent-docs-path
- * targets are user-chosen and not enumerable here.)
+ * write a managed Astryx block — the full block, or the one-line import of
+ * AGENTS.md that the default writes to GEMINI.md. SINGLE
+ * SOURCE OF TRUTH: discovery, removal, and the `isAstryxInitialized` predicate
+ * all derive from this list, so "where init writes" and "where we look" can
+ * never drift. (Explicit --agent-docs-path targets are user-chosen and not
+ * enumerable here.)
  */
 export const AGENT_DOC_PATHS = [
   AGENTS_MD, // Codex / ChatGPT / Muse / generic
   CLAUDE_MD, // Claude Code (root)
   CLAUDE_DIR_MD, // Claude Code (.claude/CLAUDE.md)
+  GEMINI_MD, // Gemini CLI
   CURSOR_RULES, // Cursor
   HERMES_DOT_MD, // Hermes
   HERMES_MD, // Hermes
@@ -64,7 +68,7 @@ export const INIT_MARKERS = [MARKER_START, LEGACY_MARKER_START];
 /**
  * Find all existing agent doc files in a directory, across EVERY location any
  * preset can write (see {@link AGENT_DOC_PATHS}: AGENTS.md, CLAUDE.md,
- * .claude/CLAUDE.md, .cursorrules, .hermes.md, HERMES.md).
+ * .claude/CLAUDE.md, GEMINI.md, .cursorrules, .hermes.md, HERMES.md).
  * @param {string} targetDir
  * @returns {string[]} Relative paths of existing agent doc files
  */
@@ -72,10 +76,33 @@ export function discoverAgentDocs(targetDir) {
   return AGENT_DOC_PATHS.filter(p => fs.existsSync(path.join(targetDir, p)));
 }
 
+/**
+ * Whether `content` holds an Astryx block. A managed block that only imports
+ * another file (the one-line `@./AGENTS.md` that init writes to GEMINI.md) does
+ * not count: it holds nothing once that file has lost its block. A malformed
+ * block still counts, so a half-written file reads as set up.
+ *
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function holdsAstryxBlock(content) {
+  for (const marker of INIT_MARKERS) {
+    let at = content.indexOf(marker);
+    while (at !== -1) {
+      const from = at + marker.length;
+      const end = content.indexOf('<!--', from);
+      const inner = (end === -1 ? content.slice(from) : content.slice(from, end)).trim();
+      if (!/^@\S+$/.test(inner)) return true;
+      at = content.indexOf(marker, from);
+    }
+  }
+  return false;
+}
+
 /**
  * Single source of truth for "is Astryx set up in this project?" — true when any
- * agent-doc file already carries the Astryx marker, i.e. `init` / `agent-docs`
- * has run. Reused by the init & upgrade commands, the per-command setup nudge
+ * agent-doc file already holds an Astryx block, i.e. `init` / `agent-docs` has
+ * run. Reused by the init & upgrade commands, the per-command setup nudge
  * (enforcement layer 3), and the cli postinstall nudge (layer 2). Core's
  * postinstall (separate package, layer 1) mirrors the same marker contract.
  *
@@ -86,7 +113,7 @@ export function isAstryxInitialized(targetDir = process.cwd()) {
   for (const rel of discoverAgentDocs(targetDir)) {
     try {
       const content = fs.readFileSync(path.join(targetDir, rel), 'utf-8');
-      if (INIT_MARKERS.some(m => content.includes(m))) {
+      if (holdsAstryxBlock(content)) {
         return true;
       }
     } catch {

package/foundation/agent-docs/agent-docs.d.mts

@@ -1,6 +1,31 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * Throw {@link AgentDocsHomeError} when `targetDir` is the home folder, or a
+ * settings folder in it outside a project.
+ * @param {string} targetDir
+ */
+export function assertAgentDocsTarget(targetDir: string): void;
+/**
+ * The folder a run started in `cwd` writes agent docs to: the nearest folder at
+ * or above it whose package.json declares an `@astryxdesign` package, else the
+ * nearest folder with any package.json. The search stops at a repository root
+ * and never reaches the home folder, so a stray `~/package.json` cannot pull
+ * the docs there.
+ * @param {string} cwd
+ * @returns {string | null} null when no folder it searches has a package.json;
+ *   init then writes where it runs, as before.
+ */
+export function resolveAgentDocsRoot(cwd: string): string | null;
+/**
+ * The folder `init` run in `cwd` writes the agent docs to: the project root
+ * {@link resolveAgentDocsRoot} finds, else `cwd` itself. The one definition
+ * that init, its removal, and the per-command setup nudge all use.
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function agentDocsTargetDir(cwd: string): string;
 /**
  * Parse the Astryx version a managed block was generated for, from its header
  * line ("Astryx v1.2.3 · N components"). Returns null when the block predates
@@ -23,6 +48,8 @@ export function parseBlockVersion(content: string): string | null;
  * - `current` — every managed block already matches the installed version.
  * And the project is `missing` when no managed block exists anywhere (the repo
  * has agent-doc files without our markers, or none at all — i.e. never `init`ed).
+ * A managed import of AGENTS.md is not a block here: it names no version and
+ * stays current while AGENTS.md holds the block.
  *
  * @param {string} targetDir
  * @param {string} [installedVersion] Defaults to the installed core version.
@@ -170,34 +197,70 @@ export function injectAgentsMd(targetDir: string, version: string): void;
  */
 export function injectClaudeMd(targetDir: string, version: string): boolean;
 /**
- * Remove Astryx section from a file.
- * If the file becomes empty (only boilerplate header remains), deletes it.
+ * Remove the Astryx-managed block, between its markers, from a file, leaving
+ * every other line as it is. With `deleteIfEmpty`, the file is deleted when
+ * nothing is left but whitespace or the exact heading init writes into a file
+ * it creates; with `deleteIfBlank`, only when nothing but whitespace is left.
  *
  * @param {string} filePath
- * @param {{deleteIfEmpty?: boolean}} [options]
+ * @param {{deleteIfEmpty?: boolean, deleteIfBlank?: boolean}} [options]
  * @returns {boolean} Whether the Astryx section was found and removed
  */
-export function removeXdsBlock(filePath: string, { deleteIfEmpty }?: {
+export function removeXdsBlock(filePath: string, { deleteIfEmpty, deleteIfBlank }?: {
     deleteIfEmpty?: boolean;
+    deleteIfBlank?: boolean;
 }): boolean;
 /**
  * Remove Astryx section from all known agent doc files.
  * @param {string} targetDir
+ * @param {object} [options]
+ * @param {string} [options.shownFrom] - Folder the logged paths are shown
+ *   relative to; defaults to `targetDir`.
+ * @param {Set<string>} [options.skip] - Files left as they are.
  * @returns {string[]} the project-relative files a block was removed from.
  * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
  *   resolves outside `targetDir`; nothing is changed.
  */
-export function removeAgentDocs(targetDir: string): string[];
+export function removeAgentDocs(targetDir: string, { shownFrom, skip }?: {
+    shownFrom?: string | undefined;
+    skip?: Set<string> | undefined;
+}): string[];
+/**
+ * Remove the managed block where init writes it, the project root (see
+ * {@link resolveAgentDocsRoot}), and in `cwd`, so a block an earlier version
+ * wrote in that folder goes too. Each folder is checked before anything is
+ * changed. Run below the project root, a project-root agent file holding a
+ * block that resolves outside the project is left as it is and reported to
+ * `onSkipped`, as install does there; 0.7.x touched only `cwd`. A file in
+ * `cwd`, or at the root when run there, that resolves outside refuses the run.
+ *
+ * @param {string} cwd
+ * @param {{onSkipped?: (rel: string, reason: string) => void}} [options]
+ * @returns {string[]} the files a block was removed from, relative to `cwd`
+ * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL`; nothing is changed
+ */
+export function removeProjectAgentDocs(cwd: string, { onSkipped }?: {
+    onSkipped?: (rel: string, reason: string) => void;
+}): string[];
 /**
  * Programmatic entry point for installing agent docs.
  * Used by the init command, upgrade command, and agent-docs command.
  *
- * Strategy (when no agent/paths specified):
- * - Discover all existing agent doc files.
- * - Leave `@path` import wrappers untouched; if an older run expanded a block
- *   into one, remove that duplicate block.
- * - Initialize or refresh every standalone file.
- * - If nothing exists, create AGENTS.md as the tool-agnostic default.
+ * Default strategy (no agent/paths specified), so every agent reads the block:
+ * - Write the block to AGENTS.md (created when missing).
+ * - Write the block to the project's Claude Code file: root CLAUDE.md when it
+ *   exists, else an existing .claude/CLAUDE.md, even when it imports AGENTS.md.
+ *   Remove a block from the other one. Create no Claude file.
+ * - Write a managed import of AGENTS.md to GEMINI.md (created when missing),
+ *   unless GEMINI.md already imports AGENTS.md.
+ * - Keep a full block in every other existing standalone file.
+ * - Leave every other `@path` import wrapper untouched; if an older run
+ *   expanded a block into one, remove that duplicate block. When a wrapper
+ *   imports a file other than AGENTS.md, the project keeps its own layout:
+ *   every standalone file gets the block.
+ * A refresh (`onlyReplace`) rewrites existing blocks in place, the Claude
+ * file's copy included, leaves imports of AGENTS.md as they are, and creates
+ * nothing.
  *
  * @param {string} targetDir
  * @param {object} [options]
@@ -211,11 +274,21 @@ export function removeAgentDocs(targetDir: string): string[];
  *   so an integration's topics reach the agent.
  * @param {string} [options.renderedBlock] - Fully rendered expected block. Init
  *   and upgrade pass one shared block to every target.
+ * @param {(rel: string, reason: string) => void} [options.onSkipped] - Called
+ *   for each file skipped because it resolves outside `targetDir` and 0.7.1
+ *   never wrote it: GEMINI.md, or any file when `refuseEscapes` is false.
+ * @param {boolean} [options.refuseEscapes] - Whether a file 0.7.1 wrote that
+ *   resolves outside `targetDir` refuses the run (default). Init passes false
+ *   when it runs below the project root, where 0.7.1 wrote in the folder it
+ *   ran in instead.
  * @returns {string[]} List of files written
  * @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
  *   write resolves outside `targetDir`; nothing is written.
+ * @throws {AgentDocsHomeError} when `targetDir` is the home folder, or a settings
+ *   folder in it outside a project, or, with `paths`, when a file's own folder
+ *   is; nothing is written.
  */
-export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, onlyReplace, topics, renderedBlock, }?: {
+export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, onlyReplace, topics, renderedBlock, onSkipped, refuseEscapes, }?: {
     zh?: boolean | undefined;
     lang?: string | undefined;
     agent?: string | undefined;
@@ -223,7 +296,22 @@ export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, on
     onlyReplace?: boolean | undefined;
     topics?: string[] | undefined;
     renderedBlock?: string | undefined;
+    onSkipped?: ((rel: string, reason: string) => void) | undefined;
+    refuseEscapes?: boolean | undefined;
 }): string[];
+/**
+ * Thrown when agent docs would be written into the home folder, or into a
+ * settings folder in it such as `~/.gemini` outside a project. Agents read the
+ * files there (for example `~/.claude/CLAUDE.md` or `~/.gemini/GEMINI.md`) in
+ * every project, so a project's version-pinned block never goes there. Removal
+ * stays allowed.
+ */
+export class AgentDocsHomeError extends Error {
+    /** @param {string} dir */
+    constructor(dir: string);
+    /** The refused folder. */
+    dir: string;
+}
 import { discoverAgentDocs } from './agent-doc-state.mjs';
 import { isAstryxInitialized } from './agent-doc-state.mjs';
 import { isAstryxPromptInReach } from './agent-doc-state.mjs';