@phren/cli 0.0.1

package/mcp/dist/cli-graph.js

@@ -0,0 +1,169 @@
+import { getPhrenPath } from "./shared.js";
+import { buildIndex, queryRows } from "./shared-index.js";
+import { resolveRuntimeProfile } from "./runtime-profile.js";
+/**
+ * CLI: phren graph [--project <name>] [--limit <n>]
+ * Displays the fragment knowledge graph as a table.
+ */
+export async function handleGraphRead(args) {
+    const phrenPath = getPhrenPath();
+    const profile = resolveRuntimeProfile(phrenPath);
+    let project;
+    let limit = 20;
+    for (let i = 0; i < args.length; i++) {
+        if ((args[i] === "--project" || args[i] === "-p") && args[i + 1]) {
+            project = args[++i];
+        }
+        else if ((args[i] === "--limit" || args[i] === "-n") && args[i + 1]) {
+            limit = Math.min(Math.max(parseInt(args[++i], 10) || 20, 1), 200);
+        }
+    }
+    const db = await buildIndex(phrenPath, profile);
+    let sql;
+    let params;
+    if (project) {
+        sql = `
+      SELECT 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 ?
+    `;
+        params = [`${project}/%`, limit];
+    }
+    else {
+        sql = `
+      SELECT 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 ?
+    `;
+        params = [limit];
+    }
+    const rows = queryRows(db, sql, params);
+    if (!rows || rows.length === 0) {
+        console.log("No fragments in the knowledge graph.");
+        return;
+    }
+    // Header
+    const nameW = 30;
+    const typeW = 12;
+    const refW = 6;
+    console.log(`${"Fragment".padEnd(nameW)} ${"Type".padEnd(typeW)} ${"Refs".padStart(refW)}`);
+    console.log(`${"─".repeat(nameW)} ${"─".repeat(typeW)} ${"─".repeat(refW)}`);
+    for (const row of rows) {
+        const name = String(row[0]).slice(0, nameW);
+        const type = String(row[1]).slice(0, typeW);
+        const refs = String(Number(row[2]));
+        console.log(`${name.padEnd(nameW)} ${type.padEnd(typeW)} ${refs.padStart(refW)}`);
+    }
+    console.log(`\n${rows.length} fragments shown.`);
+}
+/**
+ * CLI: phren graph link <project> <finding_text> <fragment_name>
+ * Links a finding to a fragment manually.
+ */
+export async function handleGraphLink(args) {
+    if (args.length < 3) {
+        console.error('Usage: phren graph link <project> "<finding text>" "<fragment name>"');
+        process.exit(1);
+    }
+    const [project, findingText, fragmentName] = args;
+    const phrenPath = getPhrenPath();
+    const profile = resolveRuntimeProfile(phrenPath);
+    const db = await buildIndex(phrenPath, profile);
+    // Check that the finding exists
+    const docCheck = queryRows(db, "SELECT content FROM docs WHERE project = ? AND filename = 'FINDINGS.md' LIMIT 1", [project]);
+    if (!docCheck || docCheck.length === 0) {
+        console.error(`No FINDINGS.md found for project "${project}".`);
+        process.exit(1);
+    }
+    const content = String(docCheck[0][0]);
+    if (!content.toLowerCase().includes(findingText.toLowerCase())) {
+        console.error(`Finding text not found in ${project}/FINDINGS.md.`);
+        process.exit(1);
+    }
+    // Use the MCP link_findings logic via direct DB operations
+    const sourceDoc = `${project}/FINDINGS.md`;
+    const normalizedFragment = fragmentName.toLowerCase();
+    try {
+        db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [normalizedFragment, "fragment", new Date().toISOString().slice(0, 10)]);
+    }
+    catch { /* best effort */ }
+    const fragmentResult = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [normalizedFragment, "fragment"]);
+    if (!fragmentResult?.length || !fragmentResult[0]?.values?.length) {
+        console.error("Failed to create fragment.");
+        process.exit(1);
+    }
+    const targetId = Number(fragmentResult[0].values[0][0]);
+    try {
+        db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [sourceDoc, "document", new Date().toISOString().slice(0, 10)]);
+    }
+    catch { /* best effort */ }
+    const docResult = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [sourceDoc, "document"]);
+    if (!docResult?.length || !docResult[0]?.values?.length) {
+        console.error("Failed to create document fragment.");
+        process.exit(1);
+    }
+    const sourceId = Number(docResult[0].values[0][0]);
+    try {
+        db.run("INSERT OR IGNORE INTO entity_links (source_id, target_id, rel_type, source_doc) VALUES (?, ?, ?, ?)", [sourceId, targetId, "mentions", sourceDoc]);
+    }
+    catch (err) {
+        console.error(`Failed to link: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    // Persist to manual-links.json
+    const { runtimeFile } = await import("./shared.js");
+    const fs = await import("fs");
+    const crypto = await import("crypto");
+    const { withFileLock } = await import("./shared-governance.js");
+    const manualLinksPath = runtimeFile(phrenPath, "manual-links.json");
+    try {
+        withFileLock(manualLinksPath, () => {
+            let existing = [];
+            if (fs.existsSync(manualLinksPath)) {
+                try {
+                    existing = JSON.parse(fs.readFileSync(manualLinksPath, "utf8"));
+                }
+                catch { /* fresh start */ }
+            }
+            const newEntry = { entity: normalizedFragment, entityType: "fragment", sourceDoc, relType: "mentions" };
+            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 (err) {
+        console.error(`Failed to persist manual link: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    console.log(`Linked "${fragmentName}" to ${sourceDoc}.`);
+}
+/**
+ * CLI: phren graph <subcommand>
+ * Routes graph subcommands.
+ */
+export async function handleGraphNamespace(args) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    switch (sub) {
+        case "link":
+            return handleGraphLink(rest);
+        case undefined:
+        case "read":
+            return handleGraphRead(rest);
+        default:
+            // Treat unknown subcommand as flags for read (e.g., --project)
+            return handleGraphRead(args);
+    }
+}

package/mcp/dist/cli-hooks-citations.js

@@ -0,0 +1,44 @@
+import { parseCitationComment, validateFindingCitation, } from "./content-citation.js";
+import { capCache } from "./shared.js";
+// ── Citation validation ──────────────────────────────────────────────────────
+const citationValidCache = new Map();
+export function clearCitationValidCache() {
+    citationValidCache.clear();
+}
+export function parseCitations(text) {
+    const results = [];
+    let m;
+    const citeRe = /<!--\s*phren:cite\s+(\{[\s\S]*?\})\s*-->/g;
+    while ((m = citeRe.exec(text)) !== null) {
+        const parsed = parseCitationComment(m[0]);
+        if (parsed)
+            results.push({ citation: parsed });
+    }
+    return results;
+}
+export function validateCitation(citation) {
+    const key = JSON.stringify(citation.citation);
+    if (citationValidCache.has(key))
+        return citationValidCache.get(key);
+    let valid = false;
+    if (citation.citation) {
+        valid = validateFindingCitation(citation.citation);
+    }
+    citationValidCache.set(key, valid);
+    capCache(citationValidCache);
+    return valid;
+}
+export function annotateStale(snippet) {
+    const citations = parseCitations(snippet);
+    if (citations.length === 0)
+        return snippet;
+    const annotations = [];
+    for (const c of citations) {
+        if (!validateCitation(c)) {
+            annotations.push("[citation stale]");
+        }
+    }
+    if (annotations.length === 0)
+        return snippet;
+    return snippet + " " + annotations.join(" ");
+}

package/mcp/dist/cli-hooks-context.js

@@ -0,0 +1,56 @@
+// cli-hooks-context.ts — HookContext: everything a hook handler needs as plain data + helpers.
+// Centralizes the "resolve state and check guards" pattern so hook handlers don't
+// reach into governance, init, project-config, hooks, init-setup, etc. directly.
+import { appendAuditLog, getPhrenPath, readRootManifest, } from "./shared.js";
+import { updateRuntimeHealth, } from "./shared-governance.js";
+import { detectProject } from "./shared-index.js";
+import { getHooksEnabledPreference } from "./init.js";
+import { isToolHookEnabled } from "./hooks.js";
+import { isProjectHookEnabled } from "./project-config.js";
+import { resolveRuntimeProfile } from "./runtime-profile.js";
+/** Build a HookContext from the current process environment. */
+export function buildHookContext() {
+    const phrenPath = getPhrenPath();
+    const profile = resolveRuntimeProfile(phrenPath);
+    const cwd = process.cwd();
+    const hookTool = process.env.PHREN_HOOK_TOOL || "claude";
+    const hooksEnabled = getHooksEnabledPreference(phrenPath);
+    const toolHookEnabled = hooksEnabled && isToolHookEnabled(phrenPath, hookTool);
+    const activeProject = detectProject(phrenPath, cwd, profile);
+    const manifest = readRootManifest(phrenPath);
+    return { phrenPath, profile, cwd, hookTool, activeProject, hooksEnabled, toolHookEnabled, manifest };
+}
+/** Check common hook guards. Returns a reason string if the hook should NOT run, null if OK. */
+export function checkHookGuard(ctx, event) {
+    if (!ctx.hooksEnabled)
+        return "disabled";
+    if (!ctx.toolHookEnabled)
+        return `tool_disabled tool=${ctx.hookTool}`;
+    if (!isProjectHookEnabled(ctx.phrenPath, ctx.activeProject, event)) {
+        return `project_disabled project=${ctx.activeProject}`;
+    }
+    return null;
+}
+/** Log a guard skip and optionally update runtime health. */
+export function handleGuardSkip(ctx, hookName, reason, healthUpdate) {
+    if (healthUpdate)
+        updateRuntimeHealth(ctx.phrenPath, healthUpdate);
+    appendAuditLog(ctx.phrenPath, hookName, `status=${reason}`);
+}
+// Re-export frequently used functions so hook handlers can import from one place
+export { debugLog, appendAuditLog, getPhrenPath, readRootManifest, sessionMarker, runtimeFile, EXEC_TIMEOUT_MS, getProjectDirs, findProjectNameCaseInsensitive, homePath, } from "./shared.js";
+export { updateRuntimeHealth, getWorkflowPolicy, withFileLock, appendReviewQueue, recordFeedback, getQualityMultiplier, } from "./shared-governance.js";
+export { detectProject } from "./shared-index.js";
+export { isProjectHookEnabled, readProjectConfig, getProjectSourcePath } from "./project-config.js";
+export { resolveRuntimeProfile } from "./runtime-profile.js";
+export { detectProjectDir, ensureLocalGitRepo, isProjectTracked, repairPreexistingInstall, } from "./init-setup.js";
+export { getProactivityLevelForTask, getProactivityLevelForFindings } from "./proactivity.js";
+export { hasExplicitFindingSignal, shouldAutoCaptureFindingsForLevel } from "./proactivity.js";
+export { FINDING_SENSITIVITY_CONFIG } from "./cli-config.js";
+export { isFeatureEnabled, errorMessage } from "./utils.js";
+export { bootstrapPhrenDotEnv } from "./phren-dotenv.js";
+export { finalizeTaskSession } from "./task-lifecycle.js";
+export { appendFindingJournal } from "./finding-journal.js";
+export { getHooksEnabledPreference } from "./init.js";
+export { isToolHookEnabled } from "./hooks.js";
+export { runDoctor } from "./link.js";

package/mcp/dist/cli-hooks-globs.js

@@ -0,0 +1,83 @@
+import * as fs from "fs";
+import * as path from "path";
+import { capCache } from "./shared.js";
+// ── Glob matching and project frontmatter ────────────────────────────────────
+const projectGlobCache = new Map();
+export function clearProjectGlobCache() {
+    projectGlobCache.clear();
+}
+function parseProjectGlobs(phrenPathLocal, project) {
+    if (projectGlobCache.has(project))
+        return projectGlobCache.get(project);
+    const claudeMdPath = path.join(phrenPathLocal, project, "CLAUDE.md");
+    let globs = null;
+    try {
+        if (fs.existsSync(claudeMdPath)) {
+            const raw = fs.readFileSync(claudeMdPath, "utf8");
+            const fmMatch = raw.match(/^---\n([\s\S]*?)\n---/);
+            if (fmMatch) {
+                const fmBlock = fmMatch[1];
+                const globLine = fmBlock.match(/^globs:\s*$/m);
+                if (globLine) {
+                    const lines = fmBlock.split("\n");
+                    const idx = lines.findIndex((l) => /^globs:\s*$/.test(l));
+                    if (idx >= 0) {
+                        const items = [];
+                        for (let i = idx + 1; i < lines.length; i++) {
+                            const m = lines[i].match(/^\s+-\s+(.+)/);
+                            if (m)
+                                items.push(m[1].trim().replace(/^["']|["']$/g, ""));
+                            else
+                                break;
+                        }
+                        if (items.length > 0)
+                            globs = items;
+                    }
+                }
+                else {
+                    const inlineMatch = fmBlock.match(/^globs:\s*\[([^\]]+)\]/m);
+                    if (inlineMatch) {
+                        globs = inlineMatch[1].split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        if (process.env.PHREN_DEBUG)
+            process.stderr.write(`[phren] getProjectGlobs: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    projectGlobCache.set(project, globs);
+    capCache(projectGlobCache);
+    return globs;
+}
+function simpleGlobMatch(pattern, filePath) {
+    const normalized = filePath.replace(/\\/g, "/");
+    const regex = pattern
+        .replace(/\\/g, "/")
+        .replace(/[.+^${}()|[\]]/g, "\\$&")
+        .replace(/\*\*/g, "\0")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]")
+        .replace(/\0/g, ".*");
+    return new RegExp(`^${regex}$`).test(normalized) || new RegExp(`(^|/)${regex}$`).test(normalized);
+}
+export function getProjectGlobBoost(phrenPathLocal, project, cwd, changedFiles) {
+    const globs = parseProjectGlobs(phrenPathLocal, project);
+    if (!globs)
+        return 1.0;
+    const paths = [];
+    if (cwd)
+        paths.push(cwd);
+    if (changedFiles) {
+        for (const f of changedFiles)
+            paths.push(f);
+    }
+    for (const p of paths) {
+        for (const glob of globs) {
+            if (simpleGlobMatch(glob, p))
+                return 1.3;
+        }
+    }
+    return 0.7;
+}

package/mcp/dist/cli-hooks-output.js

@@ -0,0 +1,130 @@
+import { recordInjection, recordRetrieval, } from "./shared-governance.js";
+import { getDocSourceKey, } from "./shared-index.js";
+import { logImpact, extractFindingIdsFromSnippet, } from "./finding-impact.js";
+import { isFeatureEnabled } from "./utils.js";
+import { annotateStale } from "./cli-hooks-citations.js";
+import { approximateTokens, fileRelevanceBoost, branchMatchBoost } from "./shared-retrieval.js";
+// ── Progressive disclosure helpers ────────────────────────────────────────────
+function buildOneLiner(snippet) {
+    const lines = snippet.split("\n").map(l => l.trim()).filter(l => l.length > 0);
+    if (!lines.length)
+        return "";
+    const first = lines[0].replace(/^[-*#>\s]+/, "").trim();
+    if (first.length <= 80)
+        return first;
+    return first.slice(0, 79) + "\u2026";
+}
+function buildCompactIndex(selected, phrenPathLocal) {
+    const lines = [];
+    for (const { doc, snippet } of selected) {
+        const id = `mem:${getDocSourceKey(doc, phrenPathLocal)}`;
+        const summary = buildOneLiner(snippet);
+        lines.push(`[${id}] ${doc.type}: ${summary}`);
+    }
+    return lines;
+}
+// ── Hook output formatting ───────────────────────────────────────────────────
+export function buildHookOutput(selected, usedTokens, intent, gitCtx, detectedProject, stage, tokenBudget, phrenPathLocal, sessionId) {
+    const projectLabel = detectedProject ? ` \u00b7 ${detectedProject}` : "";
+    const resultLabel = selected.length === 1 ? "1 result" : `${selected.length} results`;
+    const statusLine = `\u25c6 phren${projectLabel} \u00b7 ${resultLabel}`;
+    const parts = [statusLine, "<phren-context>"];
+    const impactEntries = [];
+    const impactSessionId = sessionId ?? "none";
+    const useCompactIndex = isFeatureEnabled("PHREN_FEATURE_PROGRESSIVE_DISCLOSURE", false) && selected.length >= 3;
+    if (useCompactIndex) {
+        const indexEntries = selected.slice(0, 8);
+        const indexLines = buildCompactIndex(indexEntries, phrenPathLocal);
+        parts.push("Context index (use get_memory_detail to expand any entry):");
+        for (const line of indexLines) {
+            parts.push(line);
+        }
+        parts.push("");
+        for (const injected of indexEntries) {
+            recordInjection(phrenPathLocal, injected.key, sessionId);
+            if (injected.doc.type === "findings") {
+                for (const findingId of extractFindingIdsFromSnippet(injected.snippet)) {
+                    impactEntries.push({
+                        findingId,
+                        project: injected.doc.project,
+                        sessionId: impactSessionId,
+                    });
+                }
+            }
+            try {
+                recordRetrieval(phrenPathLocal, `${injected.doc.project}/${injected.doc.filename}`, injected.doc.type);
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG)
+                    process.stderr.write(`[phren] injectContext recordRetrieval: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+    }
+    else {
+        // Position-aware injection: place most relevant at START and END so the
+        // highest-value snippets survive truncation pressure better.
+        // Input `selected` is already ranked by relevance (best first).
+        // Reorder so: [0] stays first, [1] goes last, middle positions get [2..N-1].
+        let ordered = selected;
+        if (selected.length >= 3) {
+            ordered = [
+                selected[0], // most relevant → start
+                ...selected.slice(2), // remaining → middle
+                selected[1], // second most → end
+            ];
+        }
+        // Re-verify token budget after reordering; trim middle items if over budget
+        if (ordered.length > 2) {
+            let totalTokens = 36; // base overhead
+            const keep = ordered.map(() => true);
+            for (let i = 0; i < ordered.length; i++) {
+                totalTokens += approximateTokens(ordered[i].snippet) + 14;
+            }
+            // Trim from the middle (indices 1..N-2) if over budget
+            if (totalTokens > tokenBudget) {
+                for (let i = ordered.length - 2; i >= 1; i--) {
+                    if (totalTokens <= tokenBudget)
+                        break;
+                    totalTokens -= approximateTokens(ordered[i].snippet) + 14;
+                    keep[i] = false;
+                }
+                ordered = ordered.filter((_, i) => keep[i]);
+            }
+        }
+        for (const injected of ordered) {
+            const { doc, snippet, key } = injected;
+            recordInjection(phrenPathLocal, key, sessionId);
+            if (doc.type === "findings") {
+                for (const findingId of extractFindingIdsFromSnippet(snippet)) {
+                    impactEntries.push({
+                        findingId,
+                        project: doc.project,
+                        sessionId: impactSessionId,
+                    });
+                }
+            }
+            try {
+                recordRetrieval(phrenPathLocal, doc.path ?? doc.filename, doc.type);
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG)
+                    process.stderr.write(`[phren] injectContext recordRetrievalOrdered: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            parts.push(`[${getDocSourceKey(doc, phrenPathLocal)}] (${doc.type})`);
+            parts.push(annotateStale(snippet));
+            parts.push("");
+        }
+    }
+    logImpact(phrenPathLocal, impactEntries);
+    parts.push("<phren-context>");
+    const changedCount = gitCtx?.changedFiles.size ?? 0;
+    if (gitCtx) {
+        const fileHits = selected.filter((r) => fileRelevanceBoost(r.doc.path, gitCtx.changedFiles) > 0).length;
+        const branchHits = selected.filter((r) => branchMatchBoost(r.doc.content, gitCtx.branch) > 0).length;
+        parts.push(`\u25c6 phren \u00b7 trace: intent=${intent}; reasons=file:${fileHits},branch:${branchHits}; branch=${gitCtx.branch}; changed_files=${changedCount}; tokens\u2248${usedTokens}/${tokenBudget}; stages=index:${stage.indexMs}ms,search:${stage.searchMs}ms,trust:${stage.trustMs}ms,rank:${stage.rankMs}ms,select:${stage.selectMs}ms`);
+    }
+    else {
+        parts.push(`\u25c6 phren \u00b7 trace: intent=${intent}; reasons=intent-only; tokens\u2248${usedTokens}/${tokenBudget}; stages=index:${stage.indexMs}ms,search:${stage.searchMs}ms,trust:${stage.trustMs}ms,rank:${stage.rankMs}ms,select:${stage.selectMs}ms`);
+    }
+    return parts;
+}

package/mcp/dist/cli-hooks-retrieval.js

@@ -0,0 +1,2 @@
+// cli-hooks-retrieval.ts — re-export surface for the shared retrieval core.
+export * from "./shared-retrieval.js";