@astryxdesign/cli 0.7.2 → 0.7.3-canary.0bf23bd

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';