@oortmem/claude-code 0.0.0-stage → 0.1.1

package/dist/install.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Installs Oort's hooks into a Claude Code settings file (usually
+ * `~/.claude/settings.json`). Schema, per https://code.claude.com/docs/en/hooks:
+ *
+ *     { "hooks": { "<Event>": [ { "matcher"?: string, "hooks": [ { "type": "command", "command": string, "timeout"?: seconds } ] } ] } }
+ *
+ * UserPromptSubmit and Stop take no matcher (one would be ignored); SessionStart's
+ * matcher filters the session source, and is omitted so it fires on every source.
+ */
+export declare const HOOK_EVENTS: readonly ['UserPromptSubmit', 'Stop', 'SessionStart'];
+export type InstalledEvent = (typeof HOOK_EVENTS)[number];
+/** Seconds. Claude Code's defaults are 30 (UserPromptSubmit) and 600 (others). */
+export declare const HOOK_TIMEOUTS: Record<InstalledEvent, number>;
+/** `cmd` as one shell word: as is when it is plainly safe, otherwise single-quoted. */
+export declare function shellQuote(cmd: string): string;
+/**
+ * Merges Oort's three hook entries (`<cmd> hook <Event>`) into the settings
+ * file, creating it if missing. Idempotent; replaces a stale Oort entry in
+ * place; never removes or reorders anyone else's hooks. Writes atomically and
+ * keeps a one-time backup of the original at `<settingsPath>.oort-backup`.
+ * Refuses (file untouched) settings that are not JSON, or whose `hooks` or
+ * hook event values have the wrong shape.
+ */
+export declare function installHooks(settingsPath: string, cmd: string): {
+    changed: boolean;
+};
+/**
+ * Removes only Oort's entries. A group left empty by the removal goes too; an
+ * event array or `hooks` object left empty goes only if Oort created it (it is
+ * absent from the pre-install backup). A missing file is left missing.
+ */
+export declare function uninstallHooks(settingsPath: string, cmd: string): {
+    changed: boolean;
+};
+export interface HookEventStatus {
+    event: InstalledEvent;
+    /**
+     * `current`: `<cmd> hook <event>` for this bin. `stale`: Oort's entry from
+     * another install path. `found`: Oort's entry, with no bin to compare
+     * against. `missing`: no Oort entry (a wrapper such as `cd x && oort hook
+     * Stop` is the user's own and does not count).
+     */
+    state: 'current' | 'stale' | 'found' | 'missing';
+    /** The bin the entry runs, unquoted, for `stale` and `found`. */
+    command?: string;
+}
+/**
+ * Read-only: which of Oort's hooks the settings file holds, for `oort
+ * doctor`. Throws, like `installHooks`, on settings that are not JSON or have
+ * the wrong shape.
+ */
+export declare function hookStatus(settingsPath: string, cmd?: string): {
+    exists: boolean;
+    events: HookEventStatus[];
+};

package/dist/install.js

@@ -0,0 +1,257 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { writeFileAtomic } from './fsutil.js';
+/**
+ * Installs Oort's hooks into a Claude Code settings file (usually
+ * `~/.claude/settings.json`). Schema, per https://code.claude.com/docs/en/hooks:
+ *
+ *     { "hooks": { "<Event>": [ { "matcher"?: string, "hooks": [ { "type": "command", "command": string, "timeout"?: seconds } ] } ] } }
+ *
+ * UserPromptSubmit and Stop take no matcher (one would be ignored); SessionStart's
+ * matcher filters the session source, and is omitted so it fires on every source.
+ */
+export const HOOK_EVENTS = ['UserPromptSubmit', 'Stop', 'SessionStart'];
+/** Seconds. Claude Code's defaults are 30 (UserPromptSubmit) and 600 (others). */
+export const HOOK_TIMEOUTS = {
+    UserPromptSubmit: 10,
+    Stop: 5,
+    SessionStart: 10,
+};
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** `cmd` as one shell word: as is when it is plainly safe, otherwise single-quoted. */
+export function shellQuote(cmd) {
+    return /^[A-Za-z0-9_@%+=:,./~-]+$/.test(cmd) ? cmd : `'${cmd.replaceAll("'", `'\\''`)}'`;
+}
+const commandFor = (cmd, event) => `${shellQuote(cmd)} hook ${event}`;
+/**
+ * Ours, under `event`: exactly `<cmd> hook <event>`, or exactly `oort hook
+ * <event>` from any install path (a stale entry from a moved binary). Anything
+ * with more around it (`cd x && oort hook Stop`, `oort hook Stop --flag`) is
+ * the user's own wrapper and is never touched.
+ */
+function isOurs(h, cmd, event) {
+    if (!isObject(h) || h['type'] !== 'command' || typeof h['command'] !== 'string')
+        return false;
+    const c = h['command'];
+    return (c === commandFor(cmd, event) ||
+        new RegExp(`^(?:\\S*/)?oort hook ${event}$`).test(c) ||
+        // A package's bin, as `oort install` writes it: `<prefix>/oort(mem)/dist/main.js`.
+        new RegExp(`^(?:'[^']*/oort(?:mem)?/dist/main\\.js'|[^'\\s]*/oort(?:mem)?/dist/main\\.js) hook ${event}$`).test(c));
+}
+function desired(cmd, event) {
+    return { type: 'command', command: commandFor(cmd, event), timeout: HOOK_TIMEOUTS[event] };
+}
+function parseSettings(text, file) {
+    let parsed;
+    try {
+        parsed = text.trim().length === 0 ? {} : JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`Claude Code settings ${file} is not valid JSON: ${e.message}`);
+    }
+    if (!isObject(parsed))
+        throw new Error(`Claude Code settings ${file} is not a JSON object`);
+    const hooks = parsed['hooks'];
+    if (hooks === undefined)
+        return parsed;
+    if (!isObject(hooks))
+        throw new Error(`Claude Code settings ${file}: "hooks" is not an object`);
+    for (const event of HOOK_EVENTS) {
+        if (hooks[event] !== undefined && !Array.isArray(hooks[event])) {
+            throw new Error(`Claude Code settings ${file}: "hooks.${event}" is not an array`);
+        }
+    }
+    return parsed;
+}
+function readSettings(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            return { settings: {}, existed: false, mode: 0o600 };
+        }
+        throw e;
+    }
+    return {
+        settings: parseSettings(text, file),
+        existed: true,
+        mode: fs.statSync(file).mode & 0o777,
+    };
+}
+const backupPath = (file) => `${file}.oort-backup`;
+function writeSettings(file, settings, existed, mode) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const backup = backupPath(file);
+    if (existed && !fs.existsSync(backup)) {
+        fs.copyFileSync(file, backup, fs.constants.COPYFILE_EXCL);
+        if (process.platform !== 'win32')
+            fs.chmodSync(backup, 0o600);
+    }
+    // A settings file symlinked from a dotfiles repo stays a symlink: write its target.
+    const target = existed ? fs.realpathSync(file) : file;
+    writeFileAtomic(target, `${JSON.stringify(settings, null, 2)}\n`, mode);
+}
+/**
+ * Containers (`hooks`, `hooks.<Event>`) that existed before Oort first
+ * installed, read from the one-time backup. No backup means the file did not
+ * exist then, so every container is ours. An unreadable backup keeps them all.
+ */
+function preexisting(file) {
+    let text;
+    try {
+        text = fs.readFileSync(backupPath(file), 'utf8');
+    }
+    catch {
+        return { hooks: false, events: new Set() };
+    }
+    try {
+        const before = parseSettings(text, backupPath(file));
+        const hooks = before['hooks'];
+        return {
+            hooks: isObject(hooks),
+            events: new Set(isObject(hooks) ? Object.keys(hooks) : []),
+        };
+    }
+    catch {
+        return { hooks: true, events: new Set(HOOK_EVENTS) };
+    }
+}
+/**
+ * Merges Oort's three hook entries (`<cmd> hook <Event>`) into the settings
+ * file, creating it if missing. Idempotent; replaces a stale Oort entry in
+ * place; never removes or reorders anyone else's hooks. Writes atomically and
+ * keeps a one-time backup of the original at `<settingsPath>.oort-backup`.
+ * Refuses (file untouched) settings that are not JSON, or whose `hooks` or
+ * hook event values have the wrong shape.
+ */
+export function installHooks(settingsPath, cmd) {
+    const { settings, existed, mode } = readSettings(settingsPath);
+    const before = JSON.stringify(settings);
+    const hooks = isObject(settings['hooks']) ? { ...settings['hooks'] } : {};
+    for (const event of HOOK_EVENTS) {
+        const want = desired(cmd, event);
+        const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+        // Replace the first of ours in place, drop any other copies.
+        let placed = false;
+        const next = [];
+        for (const g of groups) {
+            if (!isObject(g) || !Array.isArray(g['hooks'])) {
+                next.push(g);
+                continue;
+            }
+            const hs = [];
+            let touched = false;
+            for (const h of g['hooks']) {
+                if (!isOurs(h, cmd, event)) {
+                    hs.push(h);
+                }
+                else if (!placed) {
+                    hs.push(want);
+                    placed = true;
+                    touched = true;
+                }
+                else {
+                    touched = true;
+                }
+            }
+            if (!touched)
+                next.push(g);
+            else if (hs.length > 0)
+                next.push({ ...g, hooks: hs });
+        }
+        if (!placed)
+            next.push({ hooks: [want] });
+        hooks[event] = next;
+    }
+    const updated = { ...settings, hooks };
+    if (JSON.stringify(updated) === before)
+        return { changed: false };
+    writeSettings(settingsPath, updated, existed, mode);
+    return { changed: true };
+}
+/**
+ * Removes only Oort's entries. A group left empty by the removal goes too; an
+ * event array or `hooks` object left empty goes only if Oort created it (it is
+ * absent from the pre-install backup). A missing file is left missing.
+ */
+export function uninstallHooks(settingsPath, cmd) {
+    if (!fs.existsSync(settingsPath))
+        return { changed: false };
+    const { settings, existed, mode } = readSettings(settingsPath);
+    if (!isObject(settings['hooks']))
+        return { changed: false };
+    const hooks = { ...settings['hooks'] };
+    const kept = preexisting(settingsPath);
+    let removed = false;
+    for (const event of HOOK_EVENTS) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups))
+            continue;
+        const next = [];
+        for (const g of groups) {
+            if (!isObject(g) || !Array.isArray(g['hooks'])) {
+                next.push(g);
+                continue;
+            }
+            const hs = g['hooks'];
+            const left = hs.filter((h) => !isOurs(h, cmd, event));
+            if (left.length === hs.length)
+                next.push(g);
+            else if (left.length > 0)
+                next.push({ ...g, hooks: left });
+        }
+        if (next.length === groups.length && next.every((g, i) => g === groups[i]))
+            continue;
+        removed = true;
+        if (next.length === 0 && !kept.events.has(event))
+            delete hooks[event];
+        else
+            hooks[event] = next;
+    }
+    if (!removed)
+        return { changed: false };
+    const updated = { ...settings, hooks };
+    if (Object.keys(hooks).length === 0 && !kept.hooks)
+        delete updated['hooks'];
+    writeSettings(settingsPath, updated, existed, mode);
+    return { changed: true };
+}
+/** The bin part of `<bin> hook <event>`, with shellQuote's quoting undone. */
+function binOf(command, event) {
+    const bin = command.slice(0, -` hook ${event}`.length);
+    return bin.startsWith("'") && bin.endsWith("'") ? bin.slice(1, -1).replaceAll(`'\\''`, "'") : bin;
+}
+/**
+ * Read-only: which of Oort's hooks the settings file holds, for `oort
+ * doctor`. Throws, like `installHooks`, on settings that are not JSON or have
+ * the wrong shape.
+ */
+export function hookStatus(settingsPath, cmd) {
+    const { settings, existed } = readSettings(settingsPath);
+    const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
+    const events = HOOK_EVENTS.map((event) => {
+        const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+        for (const g of groups) {
+            if (!isObject(g) || !Array.isArray(g['hooks']))
+                continue;
+            for (const h of g['hooks']) {
+                if (!isOurs(h, cmd ?? 'oort', event))
+                    continue;
+                const command = h.command;
+                if (cmd !== undefined && command === commandFor(cmd, event)) {
+                    return { event, state: 'current' };
+                }
+                return {
+                    event,
+                    state: cmd === undefined ? 'found' : 'stale',
+                    command: binOf(command, event),
+                };
+            }
+        }
+        return { event, state: 'missing' };
+    });
+    return { exists: existed, events };
+}
+//# sourceMappingURL=install.js.map

package/dist/log.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One JSON line per hook run in `$OORT_HOME/logs/hooks.log`. Entries hold ids,
+ * outcomes, counts and timings only, never prompt, memory or transcript text:
+ * the logger takes no free-form string beyond the fields below, and callers
+ * pass outcome names they choose, never input.
+ */
+export interface HookLogEntry {
+    ts: string;
+    event: string;
+    /** Claude Code's session id (sanitised). */
+    session: string | null;
+    project: string | null;
+    outcome: string;
+    counts: Record<string, number>;
+    timings: Record<string, number>;
+    degraded?: string[];
+    /** Queue line ids (random uuids), e.g. for dead-lettered lines. */
+    ids?: string[];
+}
+export interface HookLogger {
+    /** Appends one line. Never throws: a broken log must not break a session. */
+    write(entry: Omit<HookLogEntry, 'ts'> & {
+        ts?: string;
+    }): void;
+}
+/** The log rotates to `hooks.log.1` (one rotation kept) once it exceeds this. */
+export declare const HOOK_LOG_MAX_BYTES: number;
+export declare function createHookLogger(home: string, opts?: {
+    maxBytes?: number;
+}): HookLogger;

package/dist/log.js

@@ -0,0 +1,65 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { appendPrivateFile } from '@oortmem/core';
+/** The log rotates to `hooks.log.1` (one rotation kept) once it exceeds this. */
+export const HOOK_LOG_MAX_BYTES = 5 * 1024 * 1024;
+const ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const TOKEN_MAX = 64;
+/**
+ * Event, outcome and degradation names: short tokens of `[A-Za-z0-9:_-]`,
+ * whatever a caller passes, so free text cannot reach the log by construction.
+ */
+function token(v) {
+    const t = v.replace(/[^A-Za-z0-9:_-]+/g, '_').slice(0, TOKEN_MAX);
+    return t.length > 0 ? t : '_';
+}
+/** Ids and outcome names are ours, but are clamped to a safe charset anyway. */
+function safeId(v) {
+    if (v === null)
+        return null;
+    return ID.test(v) ? v : '[invalid]';
+}
+function numbers(r) {
+    const out = {};
+    for (const [k, v] of Object.entries(r))
+        if (typeof v === 'number')
+            out[k] = Math.round(v * 10) / 10;
+    return out;
+}
+export function createHookLogger(home, opts = {}) {
+    const file = path.join(home, 'logs', 'hooks.log');
+    const maxBytes = opts.maxBytes ?? HOOK_LOG_MAX_BYTES;
+    return {
+        write(entry) {
+            try {
+                const line = {
+                    ts: entry.ts ?? new Date().toISOString(),
+                    event: token(entry.event),
+                    session: safeId(entry.session),
+                    project: safeId(entry.project),
+                    outcome: token(entry.outcome),
+                    counts: numbers(entry.counts),
+                    timings: numbers(entry.timings),
+                    ...(entry.degraded !== undefined && entry.degraded.length > 0
+                        ? { degraded: entry.degraded.map(token) }
+                        : {}),
+                    ...(entry.ids !== undefined && entry.ids.length > 0
+                        ? { ids: entry.ids.map((id) => safeId(id) ?? '[invalid]') }
+                        : {}),
+                };
+                try {
+                    if (fs.statSync(file).size > maxBytes)
+                        fs.renameSync(file, `${file}.1`);
+                }
+                catch {
+                    // No log yet, or a concurrent hook rotated it first.
+                }
+                appendPrivateFile(file, `${JSON.stringify(line)}\n`);
+            }
+            catch {
+                // Logging is best effort.
+            }
+        },
+    };
+}
+//# sourceMappingURL=log.js.map

package/dist/queue.d.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { type Observation, type Scope } from '@oortmem/core';
+import type { HookDeps } from './deps.js';
+/**
+ * The write-path queue between the Stop hook and the drain.
+ *
+ * - `$OORT_HOME/queue/<session>.jsonl`: one JSON line per scrubbed observation,
+ *   appended by the Stop hook (0600, directory 0700).
+ * - `$OORT_HOME/queue/.lock`: the drain lock (`wx`); one drain at a time. A lock
+ *   older than ten minutes is from a crashed drain and is broken.
+ * - `<file>.lock`: a short per-file lock held by an append, and by the drain
+ *   while it rewrites the file, so no concurrent append is lost.
+ * - `$OORT_HOME/queue/dead/<session>.jsonl`: lines that failed three times, or
+ *   could not be parsed.
+ */
+export declare const DRAIN_LOCK_STALE_MS: number;
+export declare const DRAIN_MAX_PER_RUN = 50;
+export declare const MAX_ATTEMPTS = 3;
+declare const QueueLineSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        orgId: z.ZodString;
+        customerId: z.ZodString;
+        agentId: z.ZodString;
+        projectId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    obs: z.ZodObject<{
+        userText: z.ZodString;
+        assistantText: z.ZodString;
+        toolSummaries: z.ZodArray<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        turnRef: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+        at: z.ZodString;
+    }, z.core.$strip>;
+    attempts: z.ZodNumber;
+    queuedAt: z.ZodString;
+}, z.core.$strip>;
+export type QueueLine = z.infer<typeof QueueLineSchema>;
+export declare const queueDir: (home: string) => string;
+/** A file-name-safe form of a session id; anything unusual is hashed. */
+export declare function queueName(session: string): string;
+/**
+ * Scrubs and appends observations to the session's queue file; observations
+ * that are mostly secret are dropped. Never holds a lock across anything but
+ * the append; if the file lock is busy, the batch goes to a unique segment
+ * file instead (the drain reads every `*.jsonl`), so nothing is lost.
+ */
+export declare function enqueueObservations(home: string, session: string, scope: Scope, observations: Observation[], now?: Date): {
+    queued: number;
+    dropped: number;
+};
+/** True when some queue file is waiting to be drained. */
+export declare function hasPendingQueue(home: string): boolean;
+export interface DrainResult {
+    processed: number;
+    failed: number;
+    remaining: number;
+}
+/**
+ * A stable id for a queued turn: `<sessionId>:<transcript turn>` when both are known, else the
+ * queue line's own id (kept across retries, since a failed line stays in its file).
+ */
+export declare function turnRefOf(line: {
+    id: string;
+    obs: {
+        sessionId?: string;
+        turnRef?: string;
+    };
+}): string;
+/**
+ * Observes queued lines, oldest file first, at most 50 per run, under the
+ * drain lock. A line that observed is removed; one whose observe threw keeps
+ * its place with `attempts + 1`, and moves to `dead/` at the third failure.
+ * Without embed, decide and write adapters the queue is left untouched.
+ */
+export declare function drainQueue(deps: HookDeps): Promise<DrainResult>;
+export {};