carrick 0.3.82 → 0.3.83

package/dist/hook/reuse.d.ts

@@ -0,0 +1,97 @@
+/** One function the working tree declares and the index does not. */
+export type NewFunction = {
+    /** As the source spells it. */
+    name: string;
+    /** Repo-relative path of the file that declares it. */
+    file: string;
+    /** The commit the index this was compared against was taken at. */
+    indexCommit: string;
+};
+/** A session's accumulated record. */
+export type SessionRecord = {
+    /** Every new function this session has seen, in the order it saw them. */
+    found: NewFunction[];
+    /** `file::name` for the ones a nudge has already listed. */
+    nudged: string[];
+    /** RFC 3339, when this file was last written. Drives the prune below. */
+    updated: string;
+};
+/**
+ * How many entries one nudge names.
+ *
+ * `find_similar` takes twenty, so a longer list would be cut by the agent
+ * making the call. Cutting it here keeps the cut in one place and keeps the
+ * line readable.
+ */
+export declare const MAX_ENTRIES = 20;
+/** Where one session's record lives. */
+export declare function sessionFile(sessionId: string, home?: string): string | null;
+/** The directory `carrick remove` deletes. */
+export declare function sessionsDir(home?: string): string;
+/** A session's record, or an empty one. Never throws. */
+export declare function readSession(sessionId: string, home?: string): SessionRecord;
+/**
+ * Drop session files nothing will read again.
+ *
+ * A session id is never reused, so every file here is dead the moment its
+ * conversation ends and only the clock can say when that was. Without this the
+ * directory grows one file per session forever.
+ */
+export declare function prune(home?: string, now?: number): void;
+/**
+ * Delete every session record on this machine, for `carrick remove`.
+ *
+ * Returns how many files went, so the command can stay silent about a machine
+ * that never recorded one. The remover lives beside the writer, which is the
+ * rule every other half of `carrick remove` follows (carrick#1034).
+ */
+export declare function removeSessions(home?: string): number;
+/**
+ * Add what one edit found, keeping the first sighting of each function.
+ *
+ * Deduplicated on file and name: an agent edits one file several times in a
+ * task, and every one of those edits re-reports the same new function.
+ */
+export declare function record(sessionId: string, found: NewFunction[], home?: string): SessionRecord;
+/** What a nudge has not yet named, oldest first. */
+export declare function pending(record: SessionRecord): NewFunction[];
+/** Mark entries as named, so the next stop of the same task says nothing. */
+export declare function markNudged(sessionId: string, entries: NewFunction[], home?: string): void;
+/** What one delivery of the nudge said, for the hook that delivered it. */
+export type Drained = {
+    /** The line to hand the model. */
+    line: string;
+    /** How many functions it names. */
+    named: number;
+    /** How many the session has recorded in all, named or not. */
+    found: number;
+};
+/**
+ * The nudge for one session, marked as spoken, or nothing to say (carrick#1335).
+ *
+ * The one place the sequence lives, because two hooks deliver it: Claude Code's
+ * `Stop`, and Codex's `UserPromptSubmit`, which is the only non-blocking
+ * model-visible event Codex gives us. Both read the same store, speak the same
+ * line and mark the same set; only the event name on the wire differs.
+ *
+ * The marking happens here, before the caller writes anything, and that order
+ * is the point: a nudge that is written and not recorded fires again on the
+ * next stop, and a task is several stops.
+ */
+export declare function drain(sessionId: string, home?: string): Drained | null;
+/**
+ * The one line the Stop hook hands the model.
+ *
+ * Three things it has to carry, and each is load-bearing:
+ *
+ * * the names, so the call can be made without another read;
+ * * `description` entries rather than `name`, because `find_similar` resolves
+ *   a `name` against the index and these are exactly the functions it does not
+ *   hold — a `name` entry for one of them comes back as an error;
+ * * the two limits, because they decide what an empty answer means. The
+ *   comparison is against the index's commit, which is this repo's default
+ *   branch as the last scan saw it, so a function written earlier on this
+ *   branch is listed here too. And the index holds no body hash: the match is
+ *   on what a function is described as doing, not on its source.
+ */
+export declare function nudge(entries: NewFunction[]): string;

package/dist/hook/reuse.js

@@ -0,0 +1,245 @@
+// What one session has added that the index does not hold, and the one line
+// the agent is told about it at the end of the task (carrick#1330).
+//
+// The measured problem: a reuse check that waits to be remembered does not
+// run. Prose alone reached the index in none of five runs; a hook reached it
+// in all five. So the check has to be delivered, not documented — but delivery
+// costs a model turn, and most edits add no function, so it cannot ride the
+// edit. The split is: the post-edit hook RECORDS silently (it already re-checks
+// the edited file, and the list of new functions comes back in that answer),
+// and the Stop hook SPEAKS once, with everything the task accumulated.
+//
+// The store is a file per session under `~/.carrick/sessions`, outside every
+// repository: a scratch file about one conversation is not a thing to put in a
+// user's tree, and a workspace can hold several repos while a session is one.
+// Nothing here ever throws at its caller — an edit and a stop must not fail
+// because a state file could not be written.
+//
+// Reference: `docs/reference/task-skills.md`, "The reuse nudge".
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * How many entries one nudge names.
+ *
+ * `find_similar` takes twenty, so a longer list would be cut by the agent
+ * making the call. Cutting it here keeps the cut in one place and keeps the
+ * line readable.
+ */
+export const MAX_ENTRIES = 20;
+/** Session files older than this are removed on the next write. */
+const KEEP_DAYS = 7;
+/** A file name a session id can never escape from. */
+function safeId(sessionId) {
+    return /^[A-Za-z0-9._-]{1,128}$/.test(sessionId) ? sessionId : null;
+}
+/** Where one session's record lives. */
+export function sessionFile(sessionId, home = os.homedir()) {
+    const id = safeId(sessionId);
+    return id === null ? null : path.join(home, ".carrick", "sessions", `${id}.json`);
+}
+/** The directory `carrick remove` deletes. */
+export function sessionsDir(home = os.homedir()) {
+    return path.join(home, ".carrick", "sessions");
+}
+/** The key a `nudged` list holds an entry under. */
+function key(entry) {
+    return `${entry.file}::${entry.name}`;
+}
+/** A session's record, or an empty one. Never throws. */
+export function readSession(sessionId, home) {
+    const empty = { found: [], nudged: [], updated: "" };
+    const file = sessionFile(sessionId, home);
+    if (file === null)
+        return empty;
+    let body;
+    try {
+        body = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return empty;
+    }
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed !== "object" || parsed === null)
+            return empty;
+        const record = parsed;
+        return {
+            found: Array.isArray(record.found)
+                ? record.found.filter((entry) => typeof entry?.name === "string" && typeof entry?.file === "string")
+                : [],
+            nudged: Array.isArray(record.nudged)
+                ? record.nudged.filter((entry) => typeof entry === "string")
+                : [],
+            updated: typeof record.updated === "string" ? record.updated : "",
+        };
+    }
+    catch {
+        // A half-written file is a file to replace, not a reason to stop: nobody
+        // edits this by hand and nothing downstream depends on its history.
+        return empty;
+    }
+}
+function write(sessionId, record, home) {
+    const file = sessionFile(sessionId, home);
+    if (file === null)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    }
+    catch {
+        // Nothing to do and nothing to say: the nudge is a nicety and the edit it
+        // rides behind is not.
+    }
+    prune(home);
+}
+/**
+ * Drop session files nothing will read again.
+ *
+ * A session id is never reused, so every file here is dead the moment its
+ * conversation ends and only the clock can say when that was. Without this the
+ * directory grows one file per session forever.
+ */
+export function prune(home, now = Date.now()) {
+    const dir = sessionsDir(home);
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const cutoff = now - KEEP_DAYS * 24 * 60 * 60 * 1000;
+    for (const name of names) {
+        const file = path.join(dir, name);
+        try {
+            if (fs.statSync(file).mtimeMs < cutoff)
+                fs.unlinkSync(file);
+        }
+        catch {
+            // A file another process is removing at the same moment is already gone.
+        }
+    }
+}
+/**
+ * Delete every session record on this machine, for `carrick remove`.
+ *
+ * Returns how many files went, so the command can stay silent about a machine
+ * that never recorded one. The remover lives beside the writer, which is the
+ * rule every other half of `carrick remove` follows (carrick#1034).
+ */
+export function removeSessions(home) {
+    const dir = sessionsDir(home);
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const name of names) {
+        try {
+            fs.unlinkSync(path.join(dir, name));
+            removed += 1;
+        }
+        catch {
+            // Already gone, or not ours to remove.
+        }
+    }
+    try {
+        fs.rmdirSync(dir);
+    }
+    catch {
+        // Something else is in it; the records are gone either way.
+    }
+    return removed;
+}
+/**
+ * Add what one edit found, keeping the first sighting of each function.
+ *
+ * Deduplicated on file and name: an agent edits one file several times in a
+ * task, and every one of those edits re-reports the same new function.
+ */
+export function record(sessionId, found, home) {
+    const current = readSession(sessionId, home);
+    const seen = new Set(current.found.map(key));
+    for (const entry of found) {
+        if (seen.has(key(entry)))
+            continue;
+        seen.add(key(entry));
+        current.found.push(entry);
+    }
+    current.updated = new Date().toISOString();
+    write(sessionId, current, home);
+    return current;
+}
+/** What a nudge has not yet named, oldest first. */
+export function pending(record) {
+    const nudged = new Set(record.nudged);
+    return record.found.filter((entry) => !nudged.has(key(entry)));
+}
+/** Mark entries as named, so the next stop of the same task says nothing. */
+export function markNudged(sessionId, entries, home) {
+    const current = readSession(sessionId, home);
+    const nudged = new Set(current.nudged);
+    for (const entry of entries)
+        nudged.add(key(entry));
+    current.nudged = [...nudged];
+    current.updated = new Date().toISOString();
+    write(sessionId, current, home);
+}
+/**
+ * The nudge for one session, marked as spoken, or nothing to say (carrick#1335).
+ *
+ * The one place the sequence lives, because two hooks deliver it: Claude Code's
+ * `Stop`, and Codex's `UserPromptSubmit`, which is the only non-blocking
+ * model-visible event Codex gives us. Both read the same store, speak the same
+ * line and mark the same set; only the event name on the wire differs.
+ *
+ * The marking happens here, before the caller writes anything, and that order
+ * is the point: a nudge that is written and not recorded fires again on the
+ * next stop, and a task is several stops.
+ */
+export function drain(sessionId, home) {
+    const current = readSession(sessionId, home);
+    const waiting = pending(current);
+    if (waiting.length === 0)
+        return null;
+    const line = nudge(waiting);
+    markNudged(sessionId, waiting, home);
+    return { line, named: waiting.length, found: current.found.length };
+}
+/**
+ * The one line the Stop hook hands the model.
+ *
+ * Three things it has to carry, and each is load-bearing:
+ *
+ * * the names, so the call can be made without another read;
+ * * `description` entries rather than `name`, because `find_similar` resolves
+ *   a `name` against the index and these are exactly the functions it does not
+ *   hold — a `name` entry for one of them comes back as an error;
+ * * the two limits, because they decide what an empty answer means. The
+ *   comparison is against the index's commit, which is this repo's default
+ *   branch as the last scan saw it, so a function written earlier on this
+ *   branch is listed here too. And the index holds no body hash: the match is
+ *   on what a function is described as doing, not on its source.
+ */
+export function nudge(entries) {
+    const named = entries.slice(0, MAX_ENTRIES);
+    const commits = [...new Set(named.map((entry) => entry.indexCommit).filter(Boolean))];
+    const at = commits.length === 1
+        ? `the index at ${commits[0].slice(0, 7)}`
+        : "the index this workspace holds";
+    const list = named
+        .map((entry) => `${entry.name} (${entry.file})`)
+        .join(", ");
+    const more = entries.length > named.length ? ` ${entries.length - named.length} more are not listed.` : "";
+    return [
+        `This task added ${named.length} function${named.length === 1 ? "" : "s"} that ${at} does not hold: ${list}.${more}`,
+        `Run the carrick-reuse skill now: one find_similar call, one \`description\` entry per function (a \`name\` entry resolves against the index, and these are not in it).`,
+        `Two limits on the answer: the index was taken at ${commits.length === 1 ? commits[0].slice(0, 7) : "this workspace's last scan"} on the default branch, so anything added on this branch is compared against that; and the comparison is on what each function is described as doing, not on its source.`,
+    ].join(" ");
+}
+//# sourceMappingURL=reuse.js.map

package/dist/hook/reuse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reuse.js","sourceRoot":"","sources":["../../src/hook/reuse.ts"],"names":[],"mappings":"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"}

package/dist/hook/stop.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** The one channel a Stop hook has that the model reads. */
+export declare function emission(context: string): string;

package/dist/hook/stop.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Stop hook: one reuse nudge per task, or nothing at all (carrick#1330).
+//
+// What it prints, and why that shape: Claude Code delivers a Stop hook's
+// `hookSpecificOutput.additionalContext` to the MODEL and lets the turn
+// continue — non-error feedback the model can act on. The alternatives were
+// both wrong for this: `systemMessage` is shown to the user and never reaches
+// the model (measured, carrick session 2026-09-03 — a Stop hook fired in 21
+// sessions and changed nothing), and `decision: "block"` reaches the model by
+// refusing to let the turn end, which is a block. This nudge is advice.
+//
+// It is silent whenever it has nothing new to say: no session id, no recorded
+// functions, or every recorded function already named by an earlier stop of
+// the same session. A stop after a stop is the common case — a task is
+// several turns — so "already nudged" is the state this has to get right or
+// the line repeats on every turn until the session ends.
+//
+// It exits 0 on every path, like the other two.
+//
+// Reference: `docs/reference/task-skills.md`, "The reuse nudge" — the three
+// parts, the channel measurement behind this shape, and what Codex lacks.
+import { createLogger } from "../log.js";
+import { resolveChannel } from "../channel.js";
+import { drain } from "./reuse.js";
+const log = createLogger("carrick-stop");
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+/** The one channel a Stop hook has that the model reads. */
+export function emission(context) {
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "Stop",
+            additionalContext: context,
+        },
+    });
+}
+async function main() {
+    // `off` silences every surface this package has, and this is one of them.
+    // The `lsp` channel is NOT excluded: it decides who delivers a verdict about
+    // an edited file, and this says nothing about a verdict.
+    if (resolveChannel({ hooksInstalled: true }).channel === "off") {
+        log("CARRICK_CHANNEL=off; printing nothing");
+        return;
+    }
+    let payload;
+    try {
+        payload = JSON.parse((await readStdin()) || "{}");
+    }
+    catch (error) {
+        log("unparseable payload", String(error));
+        return;
+    }
+    const session = payload.session_id;
+    if (!session) {
+        log("no session id in the payload; nothing to look up");
+        return;
+    }
+    // `drain` reads the store, builds the line and marks the set as spoken, in
+    // that order. Codex's `UserPromptSubmit` hook calls the same function
+    // (carrick#1335); the difference between the two hosts is the event name on
+    // the wire and nothing else.
+    const spoken = drain(session);
+    if (spoken === null) {
+        log(`nothing new in ${session}: everything recorded has been named`);
+        return;
+    }
+    process.stdout.write(emission(spoken.line));
+    log(`named ${spoken.named} new function(s) to the model, of ${spoken.found} recorded`);
+}
+await main();
+process.exit(0);
+//# sourceMappingURL=stop.js.map

package/dist/hook/stop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop.js","sourceRoot":"","sources":["../../src/hook/stop.ts"],"names":[],"mappings":";AACA,yEAAyE;AACzE,EAAE;AACF,yEAAyE;AACzE,wEAAwE;AACxE,4EAA4E;AAC5E,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,wEAAwE;AACxE,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,uEAAuE;AACvE,4EAA4E;AAC5E,yDAAyD;AACzD,EAAE;AACF,gDAAgD;AAChD,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAE1E,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,MAAM,GAAG,GAAG,YAAY,CAAC,cAAc,CAAC,CAAC;AAQzC,KAAK,UAAU,SAAS;IACtB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;QAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,kBAAkB,EAAE;YAClB,aAAa,EAAE,MAAM;YACrB,iBAAiB,EAAE,OAAO;SAC3B;KACF,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,0EAA0E;IAC1E,6EAA6E;IAC7E,yDAAyD;IACzD,IAAI,cAAc,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QAC/D,GAAG,CAAC,uCAAuC,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IAED,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,SAAS,EAAE,CAAC,IAAI,IAAI,CAAY,CAAC;IAC/D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,GAAG,CAAC,qBAAqB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IACnC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,GAAG,CAAC,kDAAkD,CAAC,CAAC;QACxD,OAAO;IACT,CAAC;IAED,2EAA2E;IAC3E,sEAAsE;IACtE,4EAA4E;IAC5E,6BAA6B;IAC7B,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,GAAG,CAAC,kBAAkB,OAAO,sCAAsC,CAAC,CAAC;QACrE,OAAO;IACT,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5C,GAAG,CAAC,SAAS,MAAM,CAAC,KAAK,qCAAqC,MAAM,CAAC,KAAK,WAAW,CAAC,CAAC;AACzF,CAAC;AAED,MAAM,IAAI,EAAE,CAAC;AACb,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC"}

package/dist/hook/user-prompt.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * The one channel a `UserPromptSubmit` hook has that the model reads.
+ *
+ * Codex parses this with `deny_unknown_fields`
+ * (`codex-rs/hooks/src/schema.rs`), so the object is exactly these two keys and
+ * a wrong event name is a parse failure rather than a silent drop.
+ */
+export declare function emission(context: string): string;

package/dist/hook/user-prompt.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook: the reuse nudge, on Codex (carrick#1335).
+//
+// Same nudge, same store, same once-per-set marking as the Stop hook this
+// package installs for Claude Code — `drain` is the shared half and the only
+// difference is which event carries the line.
+//
+// Why this event and not `Stop`. Codex accepts `additionalContext` on
+// `PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit` and
+// `SubagentStart`, and warns "this event cannot emit additionalContext" for
+// every other one (`codex-rs/hooks/src/engine/discovery.rs`). A Codex `Stop`
+// hook can reach the model only by refusing to let the turn end, and this nudge
+// is advice, never a block. `UserPromptSubmit` is the one event that is both
+// model-visible and non-blocking there.
+//
+// What that costs: the line arrives with the NEXT prompt rather than at the end
+// of the task that earned it, and a run that ends on that task never sees it.
+// The named-once marking is what makes the late delivery safe — the set is
+// spoken once, whenever the next prompt comes, and never again.
+//
+// It exits 0 on every path, like the other three. A prompt never fails because
+// Carrick had nothing to say.
+//
+// Reference: `docs/reference/task-skills.md`, "The reuse nudge".
+import { createLogger } from "../log.js";
+import { resolveChannel } from "../channel.js";
+import { drain } from "./reuse.js";
+const log = createLogger("carrick-user-prompt");
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * The one channel a `UserPromptSubmit` hook has that the model reads.
+ *
+ * Codex parses this with `deny_unknown_fields`
+ * (`codex-rs/hooks/src/schema.rs`), so the object is exactly these two keys and
+ * a wrong event name is a parse failure rather than a silent drop.
+ */
+export function emission(context) {
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: context,
+        },
+    });
+}
+async function main() {
+    // `off` silences every surface this package has, and this is one of them.
+    if (resolveChannel({ hooksInstalled: true }).channel === "off") {
+        log("CARRICK_CHANNEL=off; printing nothing");
+        return;
+    }
+    let payload;
+    try {
+        payload = JSON.parse((await readStdin()) || "{}");
+    }
+    catch (error) {
+        log("unparseable payload", String(error));
+        return;
+    }
+    const session = payload.session_id;
+    if (!session) {
+        log("no session id in the payload; nothing to look up");
+        return;
+    }
+    const spoken = drain(session);
+    if (spoken === null) {
+        log(`nothing new in ${session}: everything recorded has been named`);
+        return;
+    }
+    process.stdout.write(emission(spoken.line));
+    log(`named ${spoken.named} new function(s) to the model, of ${spoken.found} recorded`);
+}
+await main();
+process.exit(0);
+//# sourceMappingURL=user-prompt.js.map

package/dist/hook/user-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-prompt.js","sourceRoot":"","sources":["../../src/hook/user-prompt.ts"],"names":[],"mappings":";AACA,mEAAmE;AACnE,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,8CAA8C;AAC9C,EAAE;AACF,sEAAsE;AACtE,sEAAsE;AACtE,4EAA4E;AAC5E,6EAA6E;AAC7E,gFAAgF;AAChF,6EAA6E;AAC7E,wCAAwC;AACxC,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,2EAA2E;AAC3E,gEAAgE;AAChE,EAAE;AACF,+EAA+E;AAC/E,8BAA8B;AAC9B,EAAE;AACF,iEAAiE;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,MAAM,GAAG,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAC;AAMhD,KAAK,UAAU,SAAS;IACtB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;QAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,kBAAkB,EAAE;YAClB,aAAa,EAAE,kBAAkB;YACjC,iBAAiB,EAAE,OAAO;SAC3B;KACF,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,0EAA0E;IAC1E,IAAI,cAAc,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QAC/D,GAAG,CAAC,uCAAuC,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IAED,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,SAAS,EAAE,CAAC,IAAI,IAAI,CAAY,CAAC;IAC/D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,GAAG,CAAC,qBAAqB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IACnC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,GAAG,CAAC,kDAAkD,CAAC,CAAC;QACxD,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,GAAG,CAAC,kBAAkB,OAAO,sCAAsC,CAAC,CAAC;QACrE,OAAO;IACT,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5C,GAAG,CAAC,SAAS,MAAM,CAAC,KAAK,qCAAqC,MAAM,CAAC,KAAK,WAAW,CAAC,CAAC;AACzF,CAAC;AAED,MAAM,IAAI,EAAE,CAAC;AACb,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC"}

package/dist/init/codex.d.ts

@@ -0,0 +1,51 @@
+import { type HookGroup, type InstalledHook } from "./settings.ts";
+/** Codex's project config folder, relative to the workspace. */
+export declare const CODEX_DIR = ".codex";
+/** The file init writes, relative to the workspace. */
+export declare const CODEX_HOOKS_FILE: string;
+/** What this package registers with Codex, and the only entries it removes. */
+export declare function codexHooks(command?: string): Record<string, HookGroup[]>;
+/** What `codexHooks` writes, flattened the way `installedCarrickHooks` reads. */
+export declare function expectedCodexHooks(command?: string): InstalledHook[];
+/**
+ * Whether Codex is set up for this workspace.
+ *
+ * The test is its project config folder, which is the layer Codex reads project
+ * hooks and project config from and the folder this file lives in. A workspace
+ * with no `.codex/` has nothing of Codex's in it, and `carrick doctor` says
+ * nothing about Codex there rather than warning every Claude Code user about a
+ * host they do not run.
+ */
+export declare function codexInUse(workspace: string): boolean;
+/** Our entries in a `.codex/hooks.json`, or an empty list where there is none. */
+export declare function installedCodexHooks(workspace: string): InstalledHook[];
+/** The file as it is, or null when it is not there. Throws nothing but I/O. */
+export declare function readHooksFile(workspace: string): string | null;
+export type CodexWrite = "written" | "unchanged";
+/**
+ * Write our entries into the project's Codex hooks file, merging.
+ *
+ * Throws on a file that is not JSON, exactly as the `.claude` writer does: a
+ * file somebody hand-edited into something unparseable is reported, never
+ * overwritten.
+ */
+export declare function writeCodexHooks(workspace: string, command: string): CodexWrite;
+/**
+ * Whether what is left of a hooks file is nothing but the shape of one.
+ *
+ * `.codex/hooks.json` differs from a settings file in who it belongs to: init
+ * is the reason it exists, so a file holding no hooks and nothing else after
+ * our entries come out is ours to delete rather than an empty husk to leave in
+ * somebody's repository. A `description`, a key we never write, or anyone
+ * else's entry all make it theirs.
+ */
+export declare function isEmptyHooksDocument(body: string): boolean;
+export type CodexRemoval = "removed" | "file removed" | null;
+/**
+ * Take our entries out again, and the file with them where it held only ours.
+ *
+ * Null when there was nothing of ours there, so `carrick remove` stays silent
+ * about a machine that never installed it. A `.codex` directory emptied by the
+ * deletion goes too; one holding anything else of Codex's stays.
+ */
+export declare function uninstallCodexHooks(workspace: string): CodexRemoval;