@phren/cli 0.0.1

package/mcp/dist/mcp-graph.js

@@ -0,0 +1,339 @@
+import { mcpResponse } from "./mcp-types.js";
+import { z } from "zod";
+import * as fs from "fs";
+import * as crypto from "crypto";
+import { isValidProjectName } from "./utils.js";
+import { queryDocBySourceKey, queryRows, queryFragmentLinks, queryCrossProjectFragments, ensureGlobalEntitiesTable, logFragmentMiss } from "./shared-index.js";
+import { runtimeFile } from "./shared.js";
+import { withFileLock } from "./shared-governance.js";
+export function register(server, ctx) {
+    // ── search_fragments ──────────────────────────────────────────────────
+    server.registerTool("search_fragments", {
+        title: "phren : search fragments",
+        description: "Search named fragments in the knowledge graph (libraries, tools, concepts mentioned in findings). " +
+            "Returns matching fragment names and how many findings reference each.",
+        inputSchema: z.object({
+            query: z.string().describe("Fragment name to search for (partial match)."),
+            project: z.string().optional().describe("Filter to a specific project."),
+            limit: z.number().int().min(1).max(50).optional().describe("Max results (default 10)."),
+        }),
+    }, async ({ query, project, limit }) => {
+        const db = ctx.db();
+        const max = limit ?? 10;
+        const pattern = `%${query.toLowerCase()}%`;
+        let sql;
+        let params;
+        if (project) {
+            sql = `
+          SELECT e.name, e.type, COUNT(el.source_id) as ref_count
+          FROM entities e
+          LEFT JOIN entity_links el ON el.target_id = e.id
+          WHERE e.name LIKE ? AND el.source_doc LIKE ?
+          GROUP BY e.id, e.name, e.type
+          ORDER BY ref_count DESC
+          LIMIT ?
+        `;
+            params = [pattern, `${project}/%`, max];
+        }
+        else {
+            sql = `
+          SELECT e.name, e.type, COUNT(el.source_id) as ref_count
+          FROM entities e
+          LEFT JOIN entity_links el ON el.target_id = e.id
+          WHERE e.name LIKE ?
+          GROUP BY e.id, e.name, e.type
+          ORDER BY ref_count DESC
+          LIMIT ?
+        `;
+            params = [pattern, max];
+        }
+        const rows = queryRows(db, sql, params);
+        if (!rows || rows.length === 0) {
+            logFragmentMiss(ctx.phrenPath, query, "search_fragments", project);
+            return mcpResponse({ ok: true, data: [], message: `No fragments matching "${query}".` });
+        }
+        const fragments = rows.map(r => ({
+            name: String(r[0]),
+            type: String(r[1]),
+            refCount: Number(r[2]),
+        }));
+        return mcpResponse({ ok: true, data: fragments });
+    });
+    // ── get_related_docs ──────────────────────────────────────────────────
+    server.registerTool("get_related_docs", {
+        title: "phren : related docs",
+        description: "Find all findings and docs that mention a specific fragment (library, tool, concept). " +
+            "Use this to see how a technology is used across projects.",
+        inputSchema: z.object({
+            entity: z.string().describe("Fragment name to look up."),
+            project: z.string().optional().describe("Filter to a specific project."),
+            limit: z.number().int().min(1).max(50).optional().describe("Max docs to return (default 10)."),
+        }),
+    }, async ({ entity, project, limit }) => {
+        const db = ctx.db();
+        const max = limit ?? 10;
+        const links = queryFragmentLinks(db, entity.toLowerCase());
+        let relatedDocs = links.related.filter(r => r.includes("/"));
+        if (project) {
+            relatedDocs = relatedDocs.filter(d => d.startsWith(`${project}/`));
+        }
+        relatedDocs = relatedDocs.slice(0, max);
+        if (relatedDocs.length === 0) {
+            logFragmentMiss(ctx.phrenPath, entity, "get_related_docs", project);
+            return mcpResponse({ ok: true, data: [], message: `No docs found referencing fragment "${entity}".` });
+        }
+        const results = [];
+        for (const doc of relatedDocs) {
+            const docRow = queryDocBySourceKey(db, ctx.phrenPath, doc);
+            const snippet = docRow?.content ? docRow.content.slice(0, 200) : "";
+            results.push({ sourceDoc: doc, snippet });
+        }
+        return mcpResponse({ ok: true, data: results });
+    });
+    // ── read_graph ────────────────────────────────────────────────────────
+    server.registerTool("read_graph", {
+        title: "phren : knowledge graph",
+        description: "Read the fragment relationship graph. Returns top fragments by reference count " +
+            "and their connected documents.",
+        inputSchema: z.object({
+            project: z.string().optional().describe("Filter to a specific project."),
+            limit: z.number().int().min(1).max(2000).optional().describe("Max fragments to return (default 500, max 2000)."),
+            offset: z.number().int().min(0).optional().describe("Number of fragments to skip for pagination (default 0)."),
+        }),
+    }, async ({ project, limit, offset }) => {
+        const db = ctx.db();
+        const max = limit ?? 500;
+        const skip = offset ?? 0;
+        // First get total count
+        let countSql;
+        let countParams;
+        if (project) {
+            countSql = `
+          SELECT COUNT(*) FROM (
+            SELECT e.id FROM entities e
+            JOIN entity_links el ON el.target_id = e.id
+            WHERE e.type != 'document' AND el.source_doc LIKE ?
+            GROUP BY e.id
+          )
+        `;
+            countParams = [`${project}/%`];
+        }
+        else {
+            countSql = `
+          SELECT COUNT(*) FROM (
+            SELECT e.id FROM entities e
+            JOIN entity_links el ON el.target_id = e.id
+            WHERE e.type != 'document'
+            GROUP BY e.id
+          )
+        `;
+            countParams = [];
+        }
+        const countRows = queryRows(db, countSql, countParams);
+        const total = countRows && countRows.length > 0 ? Number(countRows[0][0]) : 0;
+        let sql;
+        let params;
+        // Step 1: Get fragment list with counts (no GROUP_CONCAT to avoid comma-in-value bugs)
+        if (project) {
+            sql = `
+          SELECT e.id, e.name, e.type, COUNT(el.source_id) as ref_count
+          FROM entities e
+          JOIN entity_links el ON el.target_id = e.id
+          WHERE e.type != 'document' AND el.source_doc LIKE ?
+          GROUP BY e.id, e.name, e.type
+          ORDER BY ref_count DESC
+          LIMIT ? OFFSET ?
+        `;
+            params = [`${project}/%`, max, skip];
+        }
+        else {
+            sql = `
+          SELECT e.id, e.name, e.type, COUNT(el.source_id) as ref_count
+          FROM entities e
+          JOIN entity_links el ON el.target_id = e.id
+          WHERE e.type != 'document'
+          GROUP BY e.id, e.name, e.type
+          ORDER BY ref_count DESC
+          LIMIT ? OFFSET ?
+        `;
+            params = [max, skip];
+        }
+        const rows = queryRows(db, sql, params);
+        if (!rows || rows.length === 0) {
+            return mcpResponse({ ok: true, data: { fragments: [], total, hasMore: false }, message: "No fragments in the graph." });
+        }
+        // Step 2: For each fragment, fetch its docs as separate rows
+        const fragments = rows.map(r => {
+            const fragmentId = Number(r[0]);
+            const docSql = project
+                ? "SELECT DISTINCT el.source_doc FROM entity_links el WHERE el.target_id = ? AND el.source_doc LIKE ?"
+                : "SELECT DISTINCT el.source_doc FROM entity_links el WHERE el.target_id = ?";
+            const docParams = project ? [fragmentId, `${project}/%`] : [fragmentId];
+            const docRows = queryRows(db, docSql, docParams);
+            const docs = (docRows || []).map(dr => String(dr[0]));
+            const fragmentName = String(r[1]);
+            return {
+                id: `fragment:${fragmentName}`,
+                name: fragmentName,
+                type: String(r[2]),
+                refCount: Number(r[3]),
+                docs,
+            };
+        });
+        const hasMore = skip + fragments.length < total;
+        return mcpResponse({ ok: true, data: { fragments, total, hasMore, offset: skip, limit: max } });
+    });
+    // ── link_findings ─────────────────────────────────────────────────────
+    server.registerTool("link_findings", {
+        title: "phren : link findings",
+        description: "Manually link a finding to a fragment (technology/concept) that wasn't auto-detected. " +
+            "Use this to explicitly connect a finding to a library or tool.",
+        inputSchema: z.object({
+            project: z.string().describe("Project name."),
+            finding_text: z.string().describe("Partial text of the finding to link (used to locate the source doc)."),
+            entity: z.string().describe("Fragment name to link to (e.g. 'Redis', 'Docker')."),
+            relation: z.string().optional().describe("Relationship type (default: 'mentions')."),
+            entity_type: z.string().optional().describe("Fragment type (e.g. 'library', 'service', 'concept', 'architecture'). Defaults to 'fragment'."),
+        }),
+    }, async ({ project, finding_text, entity, relation, entity_type }) => {
+        if (!isValidProjectName(project)) {
+            return mcpResponse({ ok: false, error: `Invalid project: "${project}"` });
+        }
+        return ctx.withWriteQueue(async () => {
+            const db = ctx.db();
+            const relType = relation ?? "mentions";
+            const fragmentName = entity.toLowerCase();
+            const resolvedFragmentType = entity_type ?? "fragment";
+            // 1. Find or create fragment
+            try {
+                db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [fragmentName, resolvedFragmentType, new Date().toISOString().slice(0, 10)]);
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG || (process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] link_findings fragmentInsert: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            const fragmentResult = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [fragmentName, resolvedFragmentType]);
+            if (!fragmentResult?.length || !fragmentResult[0]?.values?.length) {
+                return mcpResponse({ ok: false, error: "Failed to create fragment." });
+            }
+            const targetId = Number(fragmentResult[0].values[0][0]);
+            // 2. Find source doc in the canonical findings document
+            const docCheck = queryRows(db, "SELECT content FROM docs WHERE project = ? AND filename = 'FINDINGS.md' LIMIT 1", [project]);
+            let sourceDoc = `${project}/FINDINGS.md`;
+            if (!docCheck || docCheck.length === 0) {
+                return mcpResponse({ ok: false, error: `No FINDINGS.md found for project "${project}".` });
+            }
+            const content = String(docCheck[0][0]);
+            if (!content.toLowerCase().includes(finding_text.toLowerCase())) {
+                return mcpResponse({ ok: false, error: `Finding text not found in ${sourceDoc}.` });
+            }
+            // 3. Find or create document fragment
+            try {
+                db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [sourceDoc, "document", new Date().toISOString().slice(0, 10)]);
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG || (process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] link_findings docFragmentInsert: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            const docFragmentResult = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [sourceDoc, "document"]);
+            if (!docFragmentResult?.length || !docFragmentResult[0]?.values?.length) {
+                return mcpResponse({ ok: false, error: "Failed to create document fragment." });
+            }
+            const sourceId = Number(docFragmentResult[0].values[0][0]);
+            // 4. Insert fragment link
+            try {
+                db.run("INSERT OR IGNORE INTO entity_links (source_id, target_id, rel_type, source_doc) VALUES (?, ?, ?, ?)", [sourceId, targetId, relType, sourceDoc]);
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG || (process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] link_findings linkInsert: ${err instanceof Error ? err.message : String(err)}\n`);
+                return mcpResponse({ ok: false, error: "Failed to insert fragment link." });
+            }
+            // 4a. Also populate global_entities so manual links appear in cross_project_fragments
+            try {
+                ensureGlobalEntitiesTable(db);
+                db.run("INSERT OR IGNORE INTO global_entities (entity, project, doc_key) VALUES (?, ?, ?)", [fragmentName, project, sourceDoc]);
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG || (process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] link_findings globalFragments: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            // 4b. Persist manual link so it survives index rebuilds (mandatory — failure aborts the operation)
+            const manualLinksPath = runtimeFile(ctx.phrenPath, "manual-links.json");
+            try {
+                withFileLock(manualLinksPath, () => {
+                    let existing = [];
+                    if (fs.existsSync(manualLinksPath)) {
+                        try {
+                            existing = JSON.parse(fs.readFileSync(manualLinksPath, "utf8"));
+                        }
+                        catch (err) {
+                            if (process.env.PHREN_DEBUG || (process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                                process.stderr.write(`[phren] link_findings manualLinksRead: ${err instanceof Error ? err.message : String(err)}\n`);
+                        }
+                    }
+                    const newEntry = { entity: fragmentName, entityType: resolvedFragmentType, sourceDoc, relType };
+                    const alreadyStored = existing.some((e) => e.entity === newEntry.entity && e.entityType === newEntry.entityType && e.sourceDoc === newEntry.sourceDoc && e.relType === newEntry.relType);
+                    if (!alreadyStored) {
+                        existing.push(newEntry);
+                        const tmpPath = manualLinksPath + `.tmp-${crypto.randomUUID()}`;
+                        fs.writeFileSync(tmpPath, JSON.stringify(existing, null, 2));
+                        fs.renameSync(tmpPath, manualLinksPath);
+                    }
+                });
+            }
+            catch (persistErr) {
+                return mcpResponse({
+                    ok: false,
+                    error: `Failed to persist manual link: ${persistErr instanceof Error ? persistErr.message : String(persistErr)}`,
+                    errorCode: "INTERNAL_ERROR",
+                });
+            }
+            // 5. Rebuild index to refresh (only after successful persistence)
+            await ctx.rebuildIndex();
+            return mcpResponse({
+                ok: true,
+                message: `Linked "${entity}" to ${sourceDoc} with relation "${relType}".`,
+            });
+        });
+    });
+    // ── cross_project_fragments ───────────────────────────────────────────
+    server.registerTool("cross_project_fragments", {
+        title: "phren : cross-project fragments",
+        description: "Find fragments (libraries, tools, concepts) shared across multiple projects. " +
+            "Use this to discover how a technology or concept is used in other projects.",
+        inputSchema: z.object({
+            entity: z.string().describe("Fragment name to search for (partial match)."),
+            exclude_project: z.string().optional().describe("Exclude a specific project from results."),
+            limit: z.number().int().min(1).max(50).optional().describe("Max results (default 20)."),
+        }),
+    }, async ({ entity, exclude_project, limit }) => {
+        const db = ctx.db();
+        const max = limit ?? 20;
+        const results = queryCrossProjectFragments(db, entity, exclude_project);
+        const capped = results.slice(0, max);
+        if (capped.length === 0) {
+            logFragmentMiss(ctx.phrenPath, entity, "cross_project_fragments", exclude_project);
+            return mcpResponse({ ok: true, data: [], message: `No cross-project references found for "${entity}".` });
+        }
+        // Group by project for cleaner output
+        const byProject = new Map();
+        for (const r of capped) {
+            const arr = byProject.get(r.project) ?? [];
+            arr.push({ fragment: r.fragment, docKey: r.docKey });
+            byProject.set(r.project, arr);
+        }
+        const lines = [];
+        for (const [proj, refs] of byProject) {
+            lines.push(`### ${proj}`);
+            for (const ref of refs) {
+                lines.push(`- ${ref.fragment} (${ref.docKey})`);
+            }
+        }
+        return mcpResponse({
+            ok: true,
+            message: `Cross-project references for "${entity}" (${capped.length} results):\n\n${lines.join("\n")}`,
+            data: capped,
+        });
+    });
+}

package/mcp/dist/mcp-hooks.js

@@ -0,0 +1,256 @@
+import { mcpResponse } from "./mcp-types.js";
+import { z } from "zod";
+import * as fs from "fs";
+import * as path from "path";
+import { readInstallPreferences, writeInstallPreferences } from "./init-preferences.js";
+import { readCustomHooks, getHookTarget, HOOK_EVENT_VALUES } from "./hooks.js";
+import { hookConfigPath } from "./shared.js";
+import { PROJECT_HOOK_EVENTS, isProjectHookEnabled, readProjectConfig, writeProjectHookConfig } from "./project-config.js";
+import { isValidProjectName } from "./utils.js";
+const HOOK_TOOLS = ["claude", "copilot", "cursor", "codex"];
+const VALID_CUSTOM_EVENTS = HOOK_EVENT_VALUES;
+/**
+ * Validate a custom hook command at registration time.
+ * Rejects obviously dangerous patterns to reduce confused-deputy risk
+ * if install-preferences.json is ever compromised.
+ * Returns an error string, or null if valid.
+ */
+function validateHookCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed)
+        return "Command cannot be empty.";
+    if (trimmed.length > 1000)
+        return "Command too long (max 1000 characters).";
+    // Reject shell metacharacters that allow injection or arbitrary execution
+    // when the command is later run via `sh -c`.
+    if (/[`$(){}&|;<>]/.test(trimmed)) {
+        return "Command contains disallowed shell characters: ` $ ( ) { } & | ; < >";
+    }
+    // eval and source can execute arbitrary code
+    if (/\b(eval|source)\b/.test(trimmed))
+        return "eval and source are not permitted in hook commands.";
+    // Command must start with a word character, path, or quoted string
+    if (!/^[\w./~"'"]/.test(trimmed))
+        return "Command must begin with an executable name or path.";
+    return null;
+}
+function normalizeHookTool(input) {
+    if (!input)
+        return null;
+    const lower = input.toLowerCase();
+    return HOOK_TOOLS.includes(lower) ? lower : null;
+}
+function normalizeProjectHookEvent(input) {
+    if (!input)
+        return null;
+    const normalized = input.trim().toLowerCase();
+    const aliasMap = {
+        userpromptsubmit: "UserPromptSubmit",
+        prompt: "UserPromptSubmit",
+        stop: "Stop",
+        sessionstart: "SessionStart",
+        start: "SessionStart",
+        posttooluse: "PostToolUse",
+        tool: "PostToolUse",
+    };
+    return aliasMap[normalized] ?? null;
+}
+export function register(server, ctx) {
+    const { phrenPath } = ctx;
+    // ── list_hooks ───────────────────────────────────────────────────────────
+    server.registerTool("list_hooks", {
+        title: "◆ phren · hooks",
+        description: "List hook status for all tools (claude, copilot, cursor, codex) with enable/disable state, " +
+            "config file paths, and custom integration hooks.",
+        inputSchema: z.object({
+            project: z.string().optional().describe("Optional project name to include project-level lifecycle hook overrides."),
+        }),
+    }, async ({ project }) => {
+        const prefs = readInstallPreferences(phrenPath);
+        const globalEnabled = prefs.hooksEnabled !== false;
+        const toolPrefs = prefs.hookTools && typeof prefs.hookTools === "object" ? prefs.hookTools : {};
+        const paths = {
+            claude: hookConfigPath("claude", phrenPath),
+            copilot: hookConfigPath("copilot", phrenPath),
+            cursor: hookConfigPath("cursor", phrenPath),
+            codex: hookConfigPath("codex", phrenPath),
+        };
+        const customHooks = readCustomHooks(phrenPath);
+        let projectHooks = null;
+        if (project !== undefined) {
+            if (!isValidProjectName(project) || !fs.existsSync(path.join(phrenPath, project))) {
+                return mcpResponse({ ok: false, error: `Project "${project}" not found.` });
+            }
+            const config = readProjectConfig(phrenPath, project);
+            projectHooks = {
+                project,
+                baseEnabled: typeof config.hooks?.enabled === "boolean" ? config.hooks.enabled : null,
+                configPath: path.join(phrenPath, project, "phren.project.yaml"),
+                events: PROJECT_HOOK_EVENTS.map((event) => ({
+                    event,
+                    configured: typeof config.hooks?.[event] === "boolean" ? config.hooks[event] : null,
+                    enabled: isProjectHookEnabled(phrenPath, project, event, config),
+                })),
+            };
+        }
+        const tools = HOOK_TOOLS.map(tool => ({
+            tool,
+            enabled: globalEnabled && toolPrefs[tool] !== false,
+            configPath: paths[tool],
+            configExists: fs.existsSync(paths[tool]),
+        }));
+        const lines = [
+            `Hooks globally ${globalEnabled ? "enabled" : "disabled"}`,
+            "",
+            ...tools.map(t => `${t.tool}: ${t.enabled ? "enabled" : "disabled"} | config: ${t.configExists ? t.configPath : "(not found)"}`),
+        ];
+        if (projectHooks) {
+            lines.push("", `Project ${projectHooks.project}: base ${projectHooks.baseEnabled === null ? "inherit" : projectHooks.baseEnabled ? "enabled" : "disabled"} | config: ${projectHooks.configPath}`, ...projectHooks.events.map((event) => `${event.event}: ${event.enabled ? "enabled" : "disabled"}${event.configured === null ? " (inherit)" : ` (explicit ${event.configured ? "on" : "off"})`}`));
+        }
+        if (customHooks.length > 0) {
+            lines.push("", `${customHooks.length} custom hook(s):`);
+            for (const h of customHooks) {
+                const hookKind = "webhook" in h ? "[webhook] " : "";
+                lines.push(`  ${h.event}: ${hookKind}${getHookTarget(h)}${h.timeout ? ` (${h.timeout}ms)` : ""}`);
+            }
+        }
+        return mcpResponse({ ok: true, message: lines.join("\n"), data: { globalEnabled, tools, customHooks, projectHooks } });
+    });
+    // ── toggle_hooks ─────────────────────────────────────────────────────────
+    server.registerTool("toggle_hooks", {
+        title: "◆ phren · toggle hooks",
+        description: "Enable or disable hooks globally, for a specific tool, or for a tracked project.",
+        inputSchema: z.object({
+            enabled: z.boolean().describe("true to enable, false to disable."),
+            tool: z.string().optional().describe("Specific tool. Omit to toggle globally."),
+            project: z.string().optional().describe("Tracked project name for project-level lifecycle hook overrides."),
+            event: z.string().optional().describe("Optional lifecycle event for project-level overrides: UserPromptSubmit, Stop, SessionStart, PostToolUse."),
+        }),
+    }, async ({ enabled, tool, project, event }) => {
+        if (tool && project) {
+            return mcpResponse({ ok: false, error: "Pass either tool or project, not both." });
+        }
+        if (event && !project) {
+            return mcpResponse({ ok: false, error: "event requires project." });
+        }
+        if (project) {
+            if (!isValidProjectName(project) || !fs.existsSync(path.join(phrenPath, project))) {
+                return mcpResponse({ ok: false, error: `Project "${project}" not found.` });
+            }
+            const normalizedEvent = normalizeProjectHookEvent(event);
+            if (event && !normalizedEvent) {
+                return mcpResponse({ ok: false, error: `Invalid event "${event}". Use: ${PROJECT_HOOK_EVENTS.join(", ")}` });
+            }
+            if (normalizedEvent) {
+                writeProjectHookConfig(phrenPath, project, { [normalizedEvent]: enabled });
+                return mcpResponse({
+                    ok: true,
+                    message: `${enabled ? "Enabled" : "Disabled"} ${normalizedEvent} hook for ${project}.`,
+                    data: { project, event: normalizedEvent, enabled },
+                });
+            }
+            writeProjectHookConfig(phrenPath, project, { enabled });
+            return mcpResponse({
+                ok: true,
+                message: `${enabled ? "Enabled" : "Disabled"} hooks for project ${project}.`,
+                data: { project, enabled },
+            });
+        }
+        if (tool) {
+            const normalized = normalizeHookTool(tool);
+            if (!normalized) {
+                return mcpResponse({ ok: false, error: `Invalid tool "${tool}". Use: ${HOOK_TOOLS.join(", ")}` });
+            }
+            const prefs = readInstallPreferences(phrenPath);
+            writeInstallPreferences(phrenPath, {
+                hookTools: {
+                    ...(prefs.hookTools && typeof prefs.hookTools === "object" ? prefs.hookTools : {}),
+                    [normalized]: enabled,
+                },
+            });
+            return mcpResponse({ ok: true, message: `${enabled ? "Enabled" : "Disabled"} hooks for ${normalized}.`, data: { tool: normalized, enabled } });
+        }
+        writeInstallPreferences(phrenPath, { hooksEnabled: enabled });
+        return mcpResponse({ ok: true, message: `${enabled ? "Enabled" : "Disabled"} hooks globally.`, data: { global: true, enabled } });
+    });
+    // ── add_custom_hook ──────────────────────────────────────────────────────
+    server.registerTool("add_custom_hook", {
+        title: "◆ phren · add custom hook",
+        description: "Add a custom integration hook. Valid events: " +
+            VALID_CUSTOM_EVENTS.join(", ") + ". " +
+            "Provide either command (shell) or webhook (HTTP POST URL), not both.",
+        inputSchema: z.object({
+            event: z.enum(VALID_CUSTOM_EVENTS).describe("Hook event name."),
+            command: z.string().optional().describe("Shell command to execute."),
+            webhook: z.string().optional().describe("HTTP POST URL to call asynchronously (webhook hook)."),
+            secret: z.string().optional().describe("HMAC-SHA256 signing secret for webhook hooks. Sent as X-Phren-Signature header."),
+            timeout: z.number().int().min(1).optional().describe("Timeout in ms (default 5000)."),
+        }),
+    }, async ({ event, command, webhook, secret, timeout }) => {
+        if (!command && !webhook)
+            return mcpResponse({ ok: false, error: "Provide either command or webhook." });
+        if (command && webhook)
+            return mcpResponse({ ok: false, error: "Provide command or webhook, not both." });
+        let newHook;
+        if (webhook) {
+            const trimmed = webhook.trim();
+            if (!trimmed.startsWith("http://") && !trimmed.startsWith("https://")) {
+                return mcpResponse({ ok: false, error: "webhook must be an http:// or https:// URL." });
+            }
+            // Reject private/loopback hostnames to prevent SSRF
+            try {
+                const { hostname } = new URL(trimmed);
+                const h = hostname.toLowerCase().replace(/^\[|\]$/g, ""); // strip IPv6 brackets
+                const ssrfBlocked = h === "localhost" ||
+                    h === "::1" ||
+                    /^127\./.test(h) ||
+                    /^10\./.test(h) ||
+                    /^172\.(1[6-9]|2\d|3[01])\./.test(h) ||
+                    /^192\.168\./.test(h) ||
+                    /^169\.254\./.test(h) ||
+                    h.endsWith(".local") ||
+                    h.endsWith(".internal");
+                if (ssrfBlocked) {
+                    return mcpResponse({ ok: false, error: `webhook hostname "${hostname}" is a private or loopback address.` });
+                }
+            }
+            catch {
+                return mcpResponse({ ok: false, error: "webhook is not a valid URL." });
+            }
+            newHook = { event, webhook: trimmed, ...(secret ? { secret } : {}), ...(timeout !== undefined ? { timeout } : {}) };
+        }
+        else {
+            const cmdErr = validateHookCommand(command);
+            if (cmdErr)
+                return mcpResponse({ ok: false, error: cmdErr });
+            newHook = { event, command: command, ...(timeout !== undefined ? { timeout } : {}) };
+        }
+        return ctx.withWriteQueue(async () => {
+            const prefs = readInstallPreferences(phrenPath);
+            const existing = Array.isArray(prefs.customHooks) ? prefs.customHooks : [];
+            writeInstallPreferences(phrenPath, { ...prefs, customHooks: [...existing, newHook] });
+            return mcpResponse({ ok: true, message: `Added custom hook for "${event}": ${"webhook" in newHook ? "[webhook] " : ""}${getHookTarget(newHook)}`, data: { hook: newHook, total: existing.length + 1 } });
+        });
+    });
+    // ── remove_custom_hook ───────────────────────────────────────────────────
+    server.registerTool("remove_custom_hook", {
+        title: "◆ phren · remove custom hook",
+        description: "Remove custom hook(s) by event and optional command text (partial match).",
+        inputSchema: z.object({
+            event: z.enum(VALID_CUSTOM_EVENTS).describe("Hook event name to match."),
+            command: z.string().optional().describe("Partial command text. Omit to remove all hooks for the event."),
+        }),
+    }, async ({ event, command }) => {
+        return ctx.withWriteQueue(async () => {
+            const prefs = readInstallPreferences(phrenPath);
+            const existing = Array.isArray(prefs.customHooks) ? prefs.customHooks : [];
+            const remaining = existing.filter(h => h.event !== event || (command && !getHookTarget(h).includes(command)));
+            const removed = existing.length - remaining.length;
+            if (removed === 0) {
+                return mcpResponse({ ok: false, error: `No custom hooks matched event="${event}"${command ? ` command containing "${command}"` : ""}.` });
+            }
+            writeInstallPreferences(phrenPath, { ...prefs, customHooks: remaining });
+            return mcpResponse({ ok: true, message: `Removed ${removed} custom hook(s) for "${event}".`, data: { removed, remaining: remaining.length } });
+        });
+    });
+}

package/mcp/dist/mcp-memory.js

@@ -0,0 +1,58 @@
+import { mcpResponse } from "./mcp-types.js";
+import { z } from "zod";
+import * as fs from "fs";
+import * as path from "path";
+import { runtimeDir } from "./shared.js";
+import { recordFeedback, flushEntryScores, } from "./shared-governance.js";
+import { upsertCanonical } from "./shared-content.js";
+import { isValidProjectName } from "./utils.js";
+export function register(server, ctx) {
+    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+    server.registerTool("pin_memory", {
+        title: "◆ phren · pin memory",
+        description: "Promote an important memory into CANONICAL_MEMORIES.md so retrieval prioritizes it.",
+        inputSchema: z.object({
+            project: z.string().describe("Project name."),
+            memory: z.string().describe("Canonical memory text to pin."),
+        }),
+    }, async ({ project, memory }) => {
+        if (!isValidProjectName(project))
+            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
+        return withWriteQueue(async () => {
+            const result = upsertCanonical(phrenPath, project, memory);
+            if (!result.ok)
+                return mcpResponse({ ok: false, error: result.error });
+            // Update FTS index so newly pinned memory is immediately searchable
+            const canonicalPath = path.join(phrenPath, project, "CANONICAL_MEMORIES.md");
+            updateFileInIndex(canonicalPath);
+            return mcpResponse({ ok: true, message: result.data, data: { project, memory } });
+        });
+    });
+    server.registerTool("memory_feedback", {
+        title: "◆ phren · feedback",
+        description: "Record feedback on whether an injected memory was helpful or noisy/regressive.",
+        inputSchema: z.object({
+            key: z.string().describe("Memory key to score."),
+            feedback: z.enum(["helpful", "reprompt", "regression"]).describe("Feedback type."),
+        }),
+    }, async ({ key, feedback }) => {
+        return withWriteQueue(async () => {
+            recordFeedback(phrenPath, key, feedback);
+            flushEntryScores(phrenPath);
+            const feedbackWeights = {
+                helpful: 1.0,
+                not_helpful: -0.3,
+                reprompt: -0.5,
+                regression: -1.0,
+            };
+            const weight = feedbackWeights[feedback] ?? 0;
+            // Write feedback audit to a dedicated file — NOT to scores.jsonl, which uses a
+            // different schema ({key, delta, at}) and would crash readScoreJournal if polluted.
+            const auditFile = path.join(runtimeDir(phrenPath), "feedback-audit.jsonl");
+            fs.mkdirSync(path.dirname(auditFile), { recursive: true });
+            const entry = { key, feedback, weight, timestamp: new Date().toISOString() };
+            fs.appendFileSync(auditFile, JSON.stringify(entry) + "\n");
+            return mcpResponse({ ok: true, message: `Recorded feedback ${feedback} for ${key} (weight: ${weight})`, data: { key, feedback, weight } });
+        });
+    });
+}