orbitmap 0.4.6 → 0.6.0

package/dist/commands/setup-agent.d.ts

@@ -6,7 +6,7 @@ export type AgentType = 'claude' | 'gemini' | 'codex' | 'cursor' | 'windsurf' |
  *               `~/.codex`). This is the DEFAULT, because agent skills do **not** traverse
  *               directories: a project-level `.claude/skills/` is invisible to a session
  *               started in a sibling or child repository, while `CLAUDE.md` *is* inherited
- *               downwards — so a project-scope install hands sub-directories a hook that
+ *               downwards — so a project-scope install hands sub-directories a block that
  *               tells them to load skills they cannot see. A workspace now legitimately
  *               spans several area directories (IN-rwb5qu), so one project-scope install
  *               would only ever cover one of them.
@@ -45,12 +45,59 @@ export interface InstallTarget {
  * Resolve where an install lands.
  *
  * User scope writes **only** under the agent's personal config directory — nothing is
- * written into the project. That is the point: at user scope the skills and the hook
+ * written into the project. That is the point: at user scope the skills and the block
  * that references them are both visible from every directory, so there is no reason to
  * leave a second, narrower copy behind in one repository.
  */
 export declare function resolveInstallTarget(agentType: AgentType, scope: SkillScope, cwd: string, homeDir?: string): InstallTarget;
 export declare function detectAgent(cwdOverride?: string): AgentType | null;
+/**
+ * The command our PostToolUse hook entry runs (`src/commands/emit-instructions.ts`): it
+ * re-emits any `Instructions (…)` block from an orbitmap command's stdout as
+ * `additionalContext`, so the block lands at instruction tier instead of data tier.
+ *
+ * This string is also the entry's IDENTITY. JSON has no comments, so the
+ * `ORBITMAP_START`/`ORBITMAP_END` marker convention the markdown blocks rely on cannot be
+ * reproduced here — our entry is recognised by `command === EMIT_INSTRUCTIONS_COMMAND`,
+ * never by array position. Changing this string orphans every installed entry.
+ */
+export declare const EMIT_INSTRUCTIONS_COMMAND = "orbitmap emit-instructions";
+/**
+ * Where the hook entry lives for a resolved install target, or `null` when this agent
+ * has no hook mechanism this CLI knows how to write.
+ *
+ * - Claude Code: `settings.json` in the same `.claude/` directory as the skills — the
+ *   hook always lands in the scope the rest of the install used (project install →
+ *   `<project>/.claude/settings.json`, user install → `~/.claude/settings.json`).
+ * - Codex: `hooks.json` next to the `AGENTS.md` the instructions block went into —
+ *   but only at user scope: Codex reads hooks from its `~/.codex` directory only, so a
+ *   project-scope install writes none (and says so).
+ *
+ * Paths are derived from the {@link InstallTarget}, never from `os.homedir()` directly,
+ * so hermetic tests that pass an explicit home stay inside their sandbox.
+ */
+export declare function resolveHookSettingsPath(agentType: AgentType, target: InstallTarget): string | null;
+export type HookWriteResult = 'created' | 'updated' | 'unchanged' | 'skipped';
+/**
+ * Install our PostToolUse hook entry into `settingsPath`, idempotently and in the spirit
+ * of {@link writeBlock}: every key we do not own is preserved verbatim, our entry is
+ * APPENDED beside any hooks the user already has, and a second run changes nothing
+ * (`unchanged` leaves the file byte-identical).
+ *
+ * A file that is not valid JSON (or not a JSON object) is never rewritten — that returns
+ * `skipped`, and the caller must say so out loud: a hook silently not installed is a
+ * dead channel with no signal.
+ */
+export declare function writeEmitInstructionsHook(settingsPath: string): HookWriteResult;
+/**
+ * Remove our hook entry from `settingsPath` — and nothing else.
+ *
+ * Mirrors the guarantee of {@link removeProjectInstall}: a user's own hooks and every
+ * unrelated key survive verbatim, an unreadable file is left alone, and the file itself
+ * is deleted only when our entry was its entire content (i.e. this CLI created it).
+ * Returns whether anything was removed.
+ */
+export declare function removeEmitInstructionsHook(settingsPath: string): boolean;
 /**
  * What a previous project-scope install left behind in `cwd`.
  *
@@ -65,24 +112,28 @@ export interface StaleProjectInstall {
     skillDirs: string[];
     /** Absolute path of the agent config file that still carries our marker block, if any. */
     configPath: string | null;
+    /** Absolute path of a `.claude/settings.json` that still carries our hook entry, if any. */
+    settingsPath: string | null;
 }
 /**
  * Find a previous project-scope install in `cwd`.
  *
- * Deliberately narrow: only the five skill directories this CLI creates by name, and only
- * a config file that actually contains OUR marker block. A user's own skill in
- * `.claude/skills/`, an unrelated `CLAUDE.md`, or a `.claude/` holding only settings are
- * invisible here — which is what makes the cleanup below safe.
+ * Deliberately narrow: only the five skill directories this CLI creates by name, only
+ * a config file that actually contains OUR marker block, and only a `settings.json`
+ * that actually contains OUR hook entry. A user's own skill in `.claude/skills/`, an
+ * unrelated `CLAUDE.md`, or a `.claude/settings.json` without our entry are invisible
+ * here — which is what makes the cleanup below safe.
  */
 export declare function detectProjectInstall(cwd: string, agentType: AgentType): StaleProjectInstall | null;
 /**
  * Remove a stale project-scope install — and nothing else.
  *
- * Only ever touches: the five skill directories named in {@link StaleProjectInstall}, and
- * the marker-delimited block inside the config file. Text outside the markers is kept
- * verbatim; the config file itself is deleted only when the block was its entire content
- * (i.e. this CLI created it). Parent directories are removed only when they are already
- * empty — a `.claude/` holding a user's own skills or `settings.json` survives intact.
+ * Only ever touches: the five skill directories named in {@link StaleProjectInstall},
+ * the marker-delimited block inside the config file, and OUR hook entry inside
+ * `settings.json`. Text outside the markers — and every settings key that is not our
+ * entry — is kept verbatim; each file is deleted only when our content was its entire
+ * content (i.e. this CLI created it). Parent directories are removed only when they are
+ * already empty — a `.claude/` holding a user's own skills or settings survives intact.
  * There is no recursive delete of `.claude` anywhere in this function.
  */
 export declare function removeProjectInstall(stale: StaleProjectInstall): string[];
@@ -102,8 +153,10 @@ export declare function parseAgentType(value: string): AgentType | null;
  * Install the OrbitMap skills for one agent, non-interactively and idempotently.
  *
  * At the default `user` scope: Claude Code → `~/.claude/skills/<name>/SKILL.md` × 4 +
- * the hook block in `~/.claude/CLAUDE.md`; Gemini/Codex → the inlined block in
- * `~/.gemini/GEMINI.md` / `~/.codex/AGENTS.md`. **Nothing is written into `cwd`.**
+ * the instructions block in `~/.claude/CLAUDE.md` + the PostToolUse hook entry in
+ * `~/.claude/settings.json`; Gemini/Codex → the inlined block in `~/.gemini/GEMINI.md` /
+ * `~/.codex/AGENTS.md` (Codex also gets the hook entry in `~/.codex/hooks.json`, with
+ * its two remaining manual steps printed). **Nothing is written into `cwd`.**
  * At `project` scope everything lands in `cwd`, exactly as it used to.
  *
  * Safe to call repeatedly: identical input leaves the tree byte-identical, and the
@@ -115,7 +168,42 @@ export declare function parseAgentType(value: string): AgentType | null;
  */
 export declare function installAgentSkills(cwd: string, agentType: AgentType, scope?: SkillScope, options?: {
     cleanProject?: boolean;
+    homeDir?: string;
 }): Promise<InstallTarget>;
+/**
+ * What the drift check found in the installed config files, for tests and callers.
+ *
+ * `null` means: nothing to say — no agent detected, no config file, no OrbitMap block,
+ * or the installed block is already at (or beyond) this binary's version.
+ */
+export interface InstructionsDrift {
+    /** Config file whose block is stale. */
+    configPath: string;
+    /** Version stamped in the installed START marker, or `null` for a pre-versioning block. */
+    installedVersion: string | null;
+}
+/**
+ * Detect whether the installed OrbitMap instruction block predates this binary.
+ *
+ * Locates the config file the way `setup-agent` does: `detectAgent(cwd)` names the agent,
+ * then the project-scope file is checked before the user-scope one (a project-level block
+ * shadows the user-level one in that directory, so it is the one actually being read).
+ * The first file that carries an OrbitMap block decides. Never writes anything.
+ *
+ * Returns `null` (silence) when: no agent is detectable, no config file carries a block,
+ * or the installed block's version is equal to or newer than `cliVersion`.
+ */
+export declare function detectInstructionsDrift(cwd: string, cliVersion?: string, homeDir?: string): InstructionsDrift | null;
+/** Test hook: forget that a drift warning was already printed in this process. */
+export declare function resetInstructionsDriftWarning(): void;
+/**
+ * One stderr line when the installed instructions predate this binary — nothing else.
+ *
+ * Called from exactly two commands (`orbitmap init`, `orbitmap context`) so there is no
+ * per-command tax. Never rewrites anything, never blocks, prints at most once per
+ * invocation, and goes to stderr so `--json` stdout stays parseable.
+ */
+export declare function warnIfInstructionsDrift(cwd?: string, cliVersion?: string, homeDir?: string): void;
 export declare function setupAgentCommand(options: {
     agent?: string;
     scope?: string;