@amoree-code/ocean 0.0.0-stage → 1.2.0

package/dist/application/clients/hooks.js

@@ -0,0 +1,335 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { defaultClientEnv, edit, newBatch, planClients, readJournal, temporaryEntryProblem, } from "./clients.js";
+import { canonicalJson, ManualEdit } from "./editors.js";
+// The `ocean hook` action each event runs, and what an Ocean hook for it already looks like.
+const EVENTS = {
+    SessionStart: {
+        action: "session-start",
+        flags: " --repair",
+        pattern: /ocean-session-bootstrap|\bhook session-start\b/,
+    },
+    SessionEnd: {
+        action: "session-end",
+        flags: "",
+        pattern: /ocean-session-close|\bhook session-end\b/,
+    },
+};
+export const HOOK_ADAPTERS = [
+    {
+        client: "claude-code",
+        hookClient: "claude",
+        file: ".claude/settings.json",
+        windowsShell: "powershell",
+        events: ["SessionStart", "SessionEnd"],
+        group: (command, windows) => ({
+            hooks: [
+                {
+                    type: "command",
+                    command,
+                    ...(windows ? { shell: "powershell" } : {}),
+                    timeout: 10,
+                },
+            ],
+        }),
+    },
+    {
+        client: "codex",
+        hookClient: "codex",
+        file: ".codex/hooks.json",
+        windowsShell: "cmd",
+        events: ["SessionStart", "SessionEnd"],
+        group: (command, _windows, event) => event === "SessionEnd"
+            ? { hooks: [{ type: "command", command, timeout: 10 }] }
+            : {
+                matcher: "startup|resume",
+                hooks: [
+                    {
+                        type: "command",
+                        command,
+                        timeout: 10,
+                        statusMessage: "Loading Ocean context",
+                    },
+                ],
+            },
+    },
+    {
+        client: "gemini",
+        hookClient: "gemini",
+        file: ".gemini/settings.json",
+        windowsShell: "powershell",
+        // Gemini CLI 0.58 also fires SessionEnd (fireSessionEndEvent), T-307.
+        events: ["SessionStart", "SessionEnd"],
+        // Gemini's hook timeout is in milliseconds.
+        group: (command) => ({
+            matcher: "*",
+            hooks: [{ name: "ocean", type: "command", command, timeout: 10_000 }],
+        }),
+    },
+    {
+        // Qwen Code 0.23: Claude's hook shape, `hookSpecificOutput.additionalContext` on
+        // SessionStart, timeouts in milliseconds (its bundled docs/features/hooks.md), T-307.
+        client: "qwen",
+        hookClient: "qwen",
+        file: ".qwen/settings.json",
+        windowsShell: "powershell",
+        events: ["SessionStart", "SessionEnd"],
+        group: (command, windows, event) => ({
+            ...(event === "SessionStart" ? { matcher: "startup|resume" } : {}),
+            hooks: [
+                {
+                    type: "command",
+                    name: "ocean",
+                    command,
+                    ...(windows ? { shell: "powershell" } : {}),
+                    timeout: 10_000,
+                },
+            ],
+        }),
+    },
+    {
+        // Cursor agent (hooks.json version 1): flat `{command}` entries under `sessionStart` /
+        // `sessionEnd`; sessionStart reads `additional_context` from the hook's output, T-307.
+        client: "cursor",
+        hookClient: "cursor",
+        file: ".cursor/hooks.json",
+        windowsShell: "powershell",
+        events: ["SessionStart", "SessionEnd"],
+        key: (event) => (event === "SessionStart" ? "sessionStart" : "sessionEnd"),
+        seed: { version: 1 },
+        group: (command) => ({ command }),
+    },
+];
+const shellWord = (word) => /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
+// A Windows path cannot hold `"`. PowerShell also closes a string on the typographic quotes.
+const cmdWord = (word) => `"${word}"`;
+const powershellWord = (word) => `'${word.replace(/['\u2018\u2019\u201a\u201b]/g, "$&$&")}'`;
+const isWindows = (env) => (env.platform ?? process.platform) === "win32";
+// `--repair` also starts `client sync` in the background, which re-applies approved clients.
+export function hookCommand(env, hookClient, event = "SessionStart") {
+    const program = Array.isArray(env.entry.args)
+        ? String(env.entry.args[0])
+        : "";
+    // A shim entry (`ocean mcp serve`) names no engine file; the shim is the whole program.
+    const words = program === "mcp"
+        ? [String(env.entry.command)]
+        : [String(env.entry.command), program];
+    const shell = isWindows(env)
+        ? HOOK_ADAPTERS.find((item) => item.hookClient === hookClient)?.windowsShell
+        : undefined;
+    const invocation = shell === "cmd"
+        ? words.map(cmdWord).join(" ")
+        : shell === "powershell"
+            ? `& ${words.map(powershellWord).join(" ")}`
+            : words.map(shellWord).join(" ");
+    const { action, flags } = EVENTS[event];
+    return `${invocation} hook ${action} --client ${hookClient}${flags}`;
+}
+const hookGroup = (adapter, env, event) => adapter.group(hookCommand(env, adapter.hookClient, event), isWindows(env), event);
+// The event's group list, `[]` when absent; null when the file holds another shape there.
+function sessionGroups(root, event) {
+    const hooks = root.hooks;
+    if (hooks === undefined)
+        return [];
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+        return null;
+    const groups = hooks[event];
+    if (groups === undefined)
+        return [];
+    return Array.isArray(groups) ? groups : null;
+}
+const isOceanCommand = (hook, event) => {
+    const command = hook?.command;
+    return typeof command === "string" && EVENTS[event].pattern.test(command);
+};
+// A group of hooks (`{hooks: [...]}`), or one flat entry (Cursor's `{command}`).
+const hasOceanHook = (groups, event) => groups.some((group) => {
+    const hooks = group?.hooks;
+    return Array.isArray(hooks)
+        ? hooks.some((hook) => isOceanCommand(hook, event))
+        : isOceanCommand(group, event);
+});
+const eventKey = (adapter, event) => adapter.key?.(event) ?? event;
+async function readText(file) {
+    try {
+        return await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "";
+        throw error;
+    }
+}
+function planOne(text, adapter, env, event) {
+    const plan = {
+        client: adapter.client,
+        event,
+        file: `~/${adapter.file}`,
+        status: "change",
+    };
+    let root;
+    try {
+        root = JSON.parse(text.trim() ? text : "{}");
+    }
+    catch {
+        return { ...plan, status: "manual", reason: "the file is not valid JSON" };
+    }
+    const key = eventKey(adapter, event);
+    const groups = sessionGroups(root, key);
+    if (!groups)
+        return {
+            ...plan,
+            status: "manual",
+            reason: `hooks.${key} is not a list`,
+        };
+    if (hasOceanHook(groups, event))
+        return { ...plan, status: "current" };
+    const group = hookGroup(adapter, env, event);
+    try {
+        canonicalJson(text);
+    }
+    catch (error) {
+        if (!(error instanceof ManualEdit))
+            throw error;
+        return {
+            ...plan,
+            status: "manual",
+            reason: error.message,
+            snippet: `hooks.${key} += ${JSON.stringify(group)}`,
+        };
+    }
+    return plan;
+}
+export async function planHooks(env = defaultClientEnv()) {
+    const installed = new Set((await planClients(env))
+        .filter((plan) => plan.installed)
+        .map((plan) => plan.client));
+    const plans = [];
+    for (const adapter of HOOK_ADAPTERS) {
+        if (!installed.has(adapter.client))
+            continue;
+        const text = await readText(path.join(env.home, adapter.file));
+        for (const event of adapter.events)
+            plans.push(planOne(text, adapter, env, event));
+    }
+    return plans;
+}
+// Appends the Ocean group where it is missing; journaled under `batch` so `ocean clients
+// restore` undoes it together with the MCP entries of the same apply.
+export async function applyHooks(options = {}) {
+    const env = options.env ?? defaultClientEnv();
+    if (options.durable ?? !options.env) {
+        const problem = temporaryEntryProblem(env.entry);
+        if (problem)
+            throw new Error(`Refusing to add session hooks: ${problem}`);
+    }
+    const batch = options.batch ?? newBatch();
+    const results = [];
+    for (const plan of await planHooks(env)) {
+        if (options.clients && !options.clients.includes(plan.client))
+            continue;
+        if (plan.status !== "change")
+            continue;
+        const adapter = HOOK_ADAPTERS.find((item) => item.client === plan.client);
+        if (!adapter)
+            continue;
+        const result = await edit(path.join(env.home, adapter.file), (text) => {
+            const { event } = plan;
+            if (planOne(text, adapter, env, event).status !== "change")
+                return null;
+            const { parsed, render } = canonicalJson(text);
+            const created = [];
+            // A seeded top-level field is journaled as `root:<name>`, removed again with `hooks`.
+            for (const [field, value] of Object.entries(adapter.seed ?? {}))
+                if (parsed[field] === undefined) {
+                    parsed[field] = value;
+                    created.push(`root:${field}`);
+                }
+            if (parsed.hooks === undefined) {
+                parsed.hooks = {};
+                created.push("hooks");
+            }
+            const hooks = parsed.hooks;
+            const key = eventKey(adapter, event);
+            if (hooks[key] === undefined) {
+                hooks[key] = [];
+                created.push(key);
+            }
+            const group = hookGroup(adapter, env, event);
+            hooks[key].push(group);
+            return {
+                next: render(parsed),
+                entries: [
+                    {
+                        client: adapter.client,
+                        file: adapter.file,
+                        op: "hook-add",
+                        key: event,
+                        before: null,
+                        after: group,
+                        created,
+                    },
+                ],
+            };
+        }, batch);
+        results.push({ client: plan.client, event: plan.event, result });
+    }
+    return { batch, results };
+}
+// Removes the groups one apply batch added. A group the user changed or removed since is a
+// conflict and left alone; keys the add created are removed again once empty.
+export async function restoreHooks(options) {
+    const env = options.env ?? defaultClientEnv();
+    const entries = (await readJournal())
+        .filter((entry) => entry.batch === options.batch &&
+        entry.op === "hook-add" &&
+        !entry.restoreOf)
+        .reverse();
+    const restored = [];
+    const conflicts = [];
+    const undo = newBatch();
+    for (const entry of entries) {
+        const label = `${entry.client}:${entry.key === "SessionEnd" ? "end-hook" : "hook"}`;
+        // Set per attempt: edit() may run the change again when the file moved under it.
+        const outcome = { restored: false };
+        await edit(path.join(env.home, entry.file), (text) => {
+            outcome.restored = false;
+            let document;
+            try {
+                document = canonicalJson(text);
+            }
+            catch {
+                return null;
+            }
+            const { parsed, render } = document;
+            // Batches journaled before SessionEnd existed carry SessionStart as their key.
+            const event = (entry.key ?? "SessionStart");
+            const adapter = HOOK_ADAPTERS.find((item) => item.client === entry.client);
+            const key = adapter ? eventKey(adapter, event) : event;
+            const groups = sessionGroups(parsed, key);
+            const index = groups?.findIndex((group) => isDeepStrictEqual(group, entry.after)) ??
+                -1;
+            if (!groups || index < 0)
+                return null;
+            groups.splice(index, 1);
+            const hooks = parsed.hooks;
+            if (entry.created?.includes(key) && groups.length === 0)
+                delete hooks[key];
+            if (entry.created?.includes("hooks") && !Object.keys(hooks).length) {
+                delete parsed.hooks;
+                for (const created of entry.created)
+                    if (created.startsWith("root:"))
+                        delete parsed[created.slice(5)];
+            }
+            outcome.restored = true;
+            return {
+                next: render(parsed),
+                entries: [{ ...entry, restoreOf: options.batch }],
+            };
+        }, undo);
+        (outcome.restored ? restored : conflicts).push(label);
+    }
+    return { restored, conflicts };
+}
+//# sourceMappingURL=hooks.js.map