knodin 0.8.2 → 0.8.4

package/dist/src/agent-hooks.js

@@ -0,0 +1,156 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const OWNED_COMMAND = "knodin agent-event";
+function settingsPath(homeDir = os.homedir()) {
+    return path.join(homeDir, ".claude", "settings.json");
+}
+function assertNotSymlink(filePath) {
+    for (const candidate of [path.dirname(filePath), filePath]) {
+        try {
+            if (fs.lstatSync(candidate).isSymbolicLink())
+                throw new Error(`knodin agent-hooks: refusing symlinked path ${candidate}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+function readSettings(filePath) {
+    if (!fs.existsSync(filePath))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`knodin agent-hooks: invalid Claude settings JSON: ${error.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("knodin agent-hooks: Claude settings must contain a JSON object");
+    return parsed;
+}
+function atomicWrite(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, filePath);
+}
+function ownedEntry(value) {
+    return JSON.stringify(value).includes(OWNED_COMMAND);
+}
+function removeOwned(document) {
+    const hooks = document.hooks;
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+        return;
+    const hookObject = hooks;
+    for (const [event, value] of Object.entries(hookObject)) {
+        if (!Array.isArray(value))
+            continue;
+        const retained = value.filter((entry) => !ownedEntry(entry));
+        if (retained.length === 0)
+            delete hookObject[event];
+        else
+            hookObject[event] = retained;
+    }
+    if (Object.keys(hookObject).length === 0)
+        delete document.hooks;
+}
+function hook(command, event, matcher) {
+    return {
+        ...(matcher ? { matcher } : {}),
+        hooks: [
+            {
+                type: "command",
+                command: `${command} agent-event ${event}`,
+                timeout: 5,
+            },
+        ],
+    };
+}
+function managedHooks(command) {
+    const observed = "mcp__knodin__knodin|Bash|Read|Glob|Grep|Edit|Write|NotebookEdit";
+    return {
+        SessionStart: [hook(command, "session-start", "startup|resume|clear|compact")],
+        UserPromptSubmit: [hook(command, "turn-start")],
+        PreToolUse: [hook(command, "pre-tool", observed)],
+        PostToolUse: [hook(command, "post-tool", observed)],
+        PostToolUseFailure: [hook(command, "tool-failure", observed)],
+        Stop: [hook(command, "turn-end")],
+        SessionEnd: [hook(command, "session-end")],
+    };
+}
+function mergedSettings(existing, command) {
+    const document = structuredClone(existing);
+    removeOwned(document);
+    const hooks = document.hooks && typeof document.hooks === "object" && !Array.isArray(document.hooks)
+        ? document.hooks
+        : {};
+    for (const [event, entries] of Object.entries(managedHooks(command))) {
+        const current = Array.isArray(hooks[event]) ? hooks[event] : [];
+        hooks[event] = [...current, ...entries];
+    }
+    document.hooks = hooks;
+    return document;
+}
+export function inspectClaudeAgentHooks(options = {}) {
+    const filePath = settingsPath(options.homeDir);
+    assertNotSymlink(filePath);
+    const document = readSettings(filePath);
+    const serialized = JSON.stringify(document);
+    const count = serialized.split(OWNED_COMMAND).length - 1;
+    return {
+        schemaVersion: 1,
+        client: "claude",
+        settingsPath: filePath,
+        installed: count > 0,
+        managedEntries: count,
+    };
+}
+export function installClaudeAgentHooks(options = {}) {
+    const filePath = settingsPath(options.homeDir);
+    assertNotSymlink(filePath);
+    const before = readSettings(filePath);
+    const after = mergedSettings(before, options.command ?? "knodin");
+    const beforeText = `${JSON.stringify(before, null, 2)}\n`;
+    const afterText = `${JSON.stringify(after, null, 2)}\n`;
+    const changed = beforeText !== afterText;
+    if (changed && !options.dryRun) {
+        if (fs.existsSync(filePath)) {
+            const backup = `${filePath}.knodin-backup`;
+            if (!fs.existsSync(backup))
+                fs.copyFileSync(filePath, backup, fs.constants.COPYFILE_EXCL);
+        }
+        atomicWrite(filePath, afterText);
+    }
+    return {
+        schemaVersion: 1,
+        client: "claude",
+        settingsPath: filePath,
+        changed,
+        dryRun: options.dryRun === true,
+        managedEntries: Object.keys(managedHooks(options.command ?? "knodin")).length,
+    };
+}
+export function uninstallClaudeAgentHooks(options = {}) {
+    const filePath = settingsPath(options.homeDir);
+    assertNotSymlink(filePath);
+    if (!fs.existsSync(filePath))
+        return { removed: false, settingsPath: filePath };
+    const document = readSettings(filePath);
+    const hadOwned = ownedEntry(document);
+    removeOwned(document);
+    if (hadOwned) {
+        if (Object.keys(document).length === 0)
+            fs.unlinkSync(filePath);
+        else
+            atomicWrite(filePath, `${JSON.stringify(document, null, 2)}\n`);
+    }
+    return {
+        schemaVersion: 1,
+        client: "claude",
+        removed: hadOwned,
+        settingsPath: filePath,
+    };
+}

package/dist/src/cli-model.js

@@ -251,6 +251,14 @@ function createCliProgram(capture = () => { }) {
     leaf(program, "serve", "run the one-tool MCP gateway on stdio", capture);
     leaf(program, "version", "print the installed knodin version", capture);
     leaf(program, "hook-refresh <kind> [values...]", "internal Git lifecycle refresh", capture);
+    const agentHooks = program
+        .command("agent-hooks")
+        .description("manage optional user-global coding-agent lifecycle hooks");
+    for (const action of ["install", "status", "uninstall"])
+        leaf(agentHooks, action, `${action} optional coding-agent hooks`, capture)
+            .option("--client <client>", "coding-agent client; currently claude")
+            .option("--dry-run", "preview settings changes without writing");
+    leaf(program, "agent-event <event>", "internal coding-agent lifecycle event", capture);
     leaf(program, "refresh-artifacts [event]", "refresh external graph artifacts", capture);
     addRepositoryCommands(program, capture);
     addRemoteCommands(program, capture);
@@ -283,7 +291,14 @@ function createCliProgram(capture = () => { }) {
         .command("telemetry")
         .description("manage local opt-in ROI telemetry")
         .allowExcessArguments(false)
-        .addArgument(new Argument("<action>").choices(["status", "report", "export", "clear"]));
+        .addArgument(new Argument("<action>").choices([
+        "enable",
+        "disable",
+        "status",
+        "report",
+        "export",
+        "clear",
+    ]));
     telemetry
         .option("--input <path>", "telemetry input path")
         .option("--output <path>", "dashboard or evidence-bundle output path")

package/dist/src/docs-sections.js

@@ -27,6 +27,7 @@ The \`query\` operation lets you ask precise, structured questions about your co
 - **tests_for <target>**: Find test files that cover this symbol.
 - **file_summary <target>**: Lists all symbols defined in a file.
 - **shortest_path <from> <to>**: Find the call-graph chain connecting two symbols.
+- **cross_substrate_path <from> <to>**: Prove one bounded static Salesforce Flow action to a uniquely resolved Apex \`@InvocableMethod\`. Returns exact XML and Apex evidence, stable endpoint identities, freshness, explicit omissions, and budget metadata; it does not resolve Terraform, dbt, or arbitrary substrate crossings.
 - **impact <symbol>**: Directional, depth-bounded symbol reach with stable selectors, relation/confidence/test filters, edge evidence, and heuristic summaries. Use \`impactMode: "file"\` explicitly for a distinctly labeled changed-file blast radius.
 - **dead_code**: Surface exported or unexported symbols with zero references.
 - **large_functions / large_files**: Spot complex "god" functions and files exceeding size thresholds.