@phren/cli 0.0.1

package/mcp/dist/provider-adapters.js

@@ -0,0 +1,176 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+export const HOOK_TOOL_NAMES = ["claude", "copilot", "cursor", "codex"];
+function homeDir(env = process.env) {
+    return env.HOME || env.USERPROFILE || os.homedir();
+}
+function joinPortable(base, ...parts) {
+    const usePosix = base.startsWith("/") && !base.includes("\\");
+    if (usePosix) {
+        const normalizedBase = base.replace(/\/+$/g, "");
+        const normalizedParts = parts.map((part) => part.replace(/^\/+|\/+$/g, ""));
+        return [normalizedBase, ...normalizedParts].join("/").replace(/\/{2,}/g, "/");
+    }
+    return path.join(base, ...parts);
+}
+function homePathForEnv(env, ...parts) {
+    return joinPortable(homeDir(env), ...parts);
+}
+function defaultPhrenPath(env = process.env) {
+    return env.PHREN_PATH || env.PHREN_PATH || homePathForEnv(env, ".phren");
+}
+function normalizeWindowsPathToWsl(input) {
+    if (!input)
+        return undefined;
+    if (input.startsWith("/"))
+        return input;
+    const match = input.match(/^([A-Za-z]):\\(.*)$/);
+    if (!match)
+        return input;
+    const drive = match[1].toLowerCase();
+    const rest = match[2].replace(/\\/g, "/");
+    return `/mnt/${drive}/${rest}`;
+}
+function uniqStrings(values) {
+    return Array.from(new Set(values.filter((value) => Boolean(value && value.trim()))));
+}
+export function pickExistingFile(candidates) {
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+export function hookConfigPath(tool, phrenPath = defaultPhrenPath()) {
+    switch (tool) {
+        case "claude":
+            return homePathForEnv(process.env, ".claude", "settings.json");
+        case "copilot":
+            return homePathForEnv(process.env, ".github", "hooks", "phren.json");
+        case "cursor":
+            return homePathForEnv(process.env, ".cursor", "hooks.json");
+        case "codex":
+            return path.join(phrenPath || defaultPhrenPath(), "codex.json");
+    }
+}
+export function hookConfigPaths(phrenPath) {
+    return {
+        claude: hookConfigPath("claude", phrenPath),
+        copilot: hookConfigPath("copilot", phrenPath),
+        cursor: hookConfigPath("cursor", phrenPath),
+        codex: hookConfigPath("codex", phrenPath),
+    };
+}
+export function hookConfigRoots(phrenPath) {
+    const roots = new Set([path.resolve(phrenPath)]);
+    for (const target of Object.values(hookConfigPaths(phrenPath))) {
+        roots.add(path.resolve(path.dirname(target)));
+    }
+    return Array.from(roots);
+}
+export function vscodeMcpCandidates(env = process.env) {
+    const home = homeDir(env);
+    const userProfile = normalizeWindowsPathToWsl(env.USERPROFILE);
+    const username = env.USERNAME;
+    const userProfileRoaming = userProfile ? joinPortable(userProfile, "AppData", "Roaming", "Code", "User") : undefined;
+    const guessedWindowsRoaming = !userProfile && username
+        ? path.posix.join("/mnt/c", "Users", username, "AppData", "Roaming", "Code", "User")
+        : undefined;
+    return uniqStrings([
+        userProfileRoaming,
+        guessedWindowsRoaming,
+        joinPortable(home, ".config", "Code", "User"),
+        joinPortable(home, ".vscode-server", "data", "User"),
+        joinPortable(home, "Library", "Application Support", "Code", "User"),
+        joinPortable(home, "AppData", "Roaming", "Code", "User"),
+    ]);
+}
+export function probeVsCodeConfig(commandExists, env = process.env) {
+    const home = homeDir(env);
+    const userProfile = normalizeWindowsPathToWsl(env.USERPROFILE);
+    const userProfileRoaming = userProfile
+        ? joinPortable(userProfile, "AppData", "Roaming", "Code", "User")
+        : undefined;
+    const candidates = vscodeMcpCandidates(env);
+    const existing = candidates.find((candidate) => fs.existsSync(candidate));
+    const installed = Boolean(existing) ||
+        commandExists("code") ||
+        Boolean(userProfile &&
+            (fs.existsSync(joinPortable(userProfile, "AppData", "Local", "Programs", "Microsoft VS Code")) ||
+                fs.existsSync(joinPortable(userProfile, "AppData", "Roaming", "Code"))));
+    return {
+        targetDir: installed ? (existing || userProfileRoaming || joinPortable(home, ".config", "Code", "User")) : null,
+        installed,
+    };
+}
+export function cursorMcpCandidates(env = process.env) {
+    const home = homeDir(env);
+    return [
+        joinPortable(home, ".cursor", "mcp.json"),
+        joinPortable(home, ".config", "Cursor", "User", "mcp.json"),
+        joinPortable(home, "Library", "Application Support", "Cursor", "User", "mcp.json"),
+        joinPortable(home, "AppData", "Roaming", "Cursor", "User", "mcp.json"),
+    ];
+}
+export function resolveCursorMcpConfig(commandExists, env = process.env) {
+    const home = homeDir(env);
+    const candidates = cursorMcpCandidates(env);
+    const existing = pickExistingFile(candidates);
+    const installed = Boolean(existing) ||
+        fs.existsSync(path.join(home, ".cursor")) ||
+        fs.existsSync(path.join(home, ".config", "Cursor")) ||
+        fs.existsSync(path.join(home, "Library", "Application Support", "Cursor")) ||
+        fs.existsSync(path.join(home, "AppData", "Roaming", "Cursor")) ||
+        commandExists("cursor");
+    return { installed, existing, target: existing || candidates[0] };
+}
+export function copilotMcpCandidates(env = process.env) {
+    const home = homeDir(env);
+    return [
+        joinPortable(home, ".copilot", "mcp-config.json"),
+        joinPortable(home, ".github", "mcp.json"),
+        joinPortable(home, ".config", "github-copilot", "mcp.json"),
+        joinPortable(home, "Library", "Application Support", "github-copilot", "mcp.json"),
+        joinPortable(home, "AppData", "Roaming", "github-copilot", "mcp.json"),
+    ];
+}
+export function resolveCopilotMcpConfig(commandExists, env = process.env) {
+    const home = homeDir(env);
+    const candidates = copilotMcpCandidates(env);
+    const existing = pickExistingFile(candidates);
+    const hasCliDir = fs.existsSync(path.join(home, ".copilot"));
+    const installed = Boolean(existing) ||
+        hasCliDir ||
+        fs.existsSync(path.join(home, ".github")) ||
+        fs.existsSync(path.join(home, ".config", "github-copilot")) ||
+        fs.existsSync(path.join(home, "Library", "Application Support", "github-copilot")) ||
+        fs.existsSync(path.join(home, "AppData", "Roaming", "github-copilot")) ||
+        commandExists("gh");
+    return { installed, existing, cliConfig: candidates[0], hasCliDir };
+}
+export function codexJsonCandidates(phrenPath, env = process.env) {
+    const home = homeDir(env);
+    return [
+        joinPortable(home, ".codex", "config.json"),
+        joinPortable(home, ".codex", "mcp.json"),
+        path.join(phrenPath, "codex.json"),
+    ];
+}
+export function resolveCodexMcpConfig(phrenPath, commandExists, env = process.env) {
+    const home = homeDir(env);
+    const tomlPath = joinPortable(home, ".codex", "config.toml");
+    const jsonCandidates = codexJsonCandidates(phrenPath, env);
+    const existingJson = pickExistingFile(jsonCandidates);
+    const installed = fs.existsSync(tomlPath) ||
+        Boolean(existingJson) ||
+        fs.existsSync(path.join(home, ".codex")) ||
+        commandExists("codex");
+    return {
+        installed,
+        tomlPath,
+        existingJson,
+        preferToml: fs.existsSync(tomlPath) || !existingJson,
+        jsonCandidates,
+    };
+}

package/mcp/dist/runtime-profile.js

@@ -0,0 +1,18 @@
+import { resolveActiveProfile } from "./profile-store.js";
+export function requestedProfileFromEnv() {
+    const profile = (process.env.PHREN_PROFILE)?.trim();
+    return profile ? profile : undefined;
+}
+/**
+ * Resolve the effective runtime profile for user-facing entrypoints.
+ * Explicit env selection is strict. Implicit selection is best-effort via
+ * machines.yaml / profiles and falls back to an unscoped view during early setup.
+ */
+export function resolveRuntimeProfile(phrenPath, requestedProfile = requestedProfileFromEnv()) {
+    const result = resolveActiveProfile(phrenPath, requestedProfile);
+    if (result.ok)
+        return result.data || "";
+    if (requestedProfile)
+        throw new Error(result.error);
+    return "";
+}

package/mcp/dist/session-checkpoints.js

@@ -0,0 +1,131 @@
+import * as fs from "fs";
+import * as path from "path";
+import { errorMessage } from "./utils.js";
+import { debugLog, sessionMarker } from "./shared.js";
+import { atomicWriteJson } from "./session-utils.js";
+function sanitizeFileSegment(value) {
+    const trimmed = value.trim();
+    const safe = trimmed.replace(/[^a-zA-Z0-9._-]+/g, "_");
+    return safe || "unknown";
+}
+function checkpointDir(phrenPath) {
+    const probe = sessionMarker(phrenPath, "checkpoint-probe.json");
+    return path.dirname(probe);
+}
+function checkpointFileName(project, taskId) {
+    return `checkpoint-${sanitizeFileSegment(project)}-${sanitizeFileSegment(taskId)}.json`;
+}
+export function checkpointPath(phrenPath, project, taskId) {
+    return sessionMarker(phrenPath, checkpointFileName(project, taskId));
+}
+function readCheckpointFile(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        if (typeof parsed.project !== "string" || typeof parsed.taskId !== "string" || typeof parsed.taskLine !== "string")
+            return null;
+        return {
+            project: parsed.project,
+            taskId: parsed.taskId,
+            taskText: typeof parsed.taskText === "string" ? parsed.taskText : parsed.taskLine,
+            taskLine: parsed.taskLine,
+            sessionId: typeof parsed.sessionId === "string" ? parsed.sessionId : undefined,
+            createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : new Date().toISOString(),
+            resumptionHint: {
+                lastAttempt: parsed.resumptionHint?.lastAttempt && typeof parsed.resumptionHint.lastAttempt === "string"
+                    ? parsed.resumptionHint.lastAttempt
+                    : "No prior attempt captured",
+                nextStep: parsed.resumptionHint?.nextStep && typeof parsed.resumptionHint.nextStep === "string"
+                    ? parsed.resumptionHint.nextStep
+                    : parsed.taskLine,
+            },
+            gitStatus: typeof parsed.gitStatus === "string" ? parsed.gitStatus : "",
+            editedFiles: Array.isArray(parsed.editedFiles) ? parsed.editedFiles.filter((v) => typeof v === "string") : [],
+            failingTests: Array.isArray(parsed.failingTests) ? parsed.failingTests.filter((v) => typeof v === "string") : [],
+        };
+    }
+    catch (err) {
+        debugLog(`checkpoint read ${filePath}: ${errorMessage(err)}`);
+        return null;
+    }
+}
+export function writeTaskCheckpoint(phrenPath, checkpoint) {
+    const filePath = checkpointPath(phrenPath, checkpoint.project, checkpoint.taskId);
+    const normalizedCheckpoint = {
+        ...checkpoint,
+        taskText: checkpoint.taskText ?? checkpoint.taskLine,
+    };
+    atomicWriteJson(filePath, normalizedCheckpoint);
+}
+export function listTaskCheckpoints(phrenPath, project) {
+    const dir = checkpointDir(phrenPath);
+    let files;
+    try {
+        files = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    for (const name of files) {
+        if (!name.startsWith("checkpoint-") || !name.endsWith(".json"))
+            continue;
+        const filePath = path.join(dir, name);
+        const parsed = readCheckpointFile(filePath);
+        if (!parsed)
+            continue;
+        if (project && parsed.project !== project)
+            continue;
+        let mtimeMs = 0;
+        try {
+            mtimeMs = fs.statSync(filePath).mtimeMs;
+        }
+        catch {
+            // keep 0
+        }
+        rows.push({ checkpoint: parsed, mtimeMs });
+    }
+    rows.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return rows.map((row) => row.checkpoint);
+}
+export function clearTaskCheckpoint(phrenPath, args) {
+    const ids = new Set();
+    if (args.taskId)
+        ids.add(args.taskId);
+    if (args.stableId)
+        ids.add(args.stableId);
+    if (args.positionalId)
+        ids.add(args.positionalId);
+    let removed = 0;
+    for (const id of ids) {
+        const filePath = checkpointPath(phrenPath, args.project, id);
+        try {
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+                removed++;
+            }
+        }
+        catch (err) {
+            debugLog(`checkpoint clear ${filePath}: ${errorMessage(err)}`);
+        }
+    }
+    const allProjectCheckpoints = listTaskCheckpoints(phrenPath, args.project);
+    for (const checkpoint of allProjectCheckpoints) {
+        const idMatch = ids.size > 0 && ids.has(checkpoint.taskId);
+        const lineMatch = args.taskLine && checkpoint.taskLine === args.taskLine;
+        if (!idMatch && !lineMatch)
+            continue;
+        const filePath = checkpointPath(phrenPath, checkpoint.project, checkpoint.taskId);
+        try {
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+                removed++;
+            }
+        }
+        catch (err) {
+            debugLog(`checkpoint clear scan ${filePath}: ${errorMessage(err)}`);
+        }
+    }
+    return removed;
+}

package/mcp/dist/session-utils.js

@@ -0,0 +1,68 @@
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * Write JSON to a file atomically using temp-file + rename.
+ * Ensures the parent directory exists before writing.
+ */
+export function atomicWriteJson(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");
+    fs.renameSync(tmpPath, filePath);
+}
+/**
+ * Log an error to stderr when PHREN_DEBUG is enabled.
+ * Centralises the repeated `if (PHREN_DEBUG) stderr.write(...)` pattern.
+ */
+export function debugError(scope, err) {
+    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG)) {
+        process.stderr.write(`[phren] ${scope}: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+/**
+ * Enumerate all `session-*.json` files under `dir`, parse each one via `parse`,
+ * and keep entries where `filter` returns true.
+ *
+ * Returns an array of `{ fullPath, data, mtimeMs }` sorted newest-mtime-first.
+ * `includeMtime` controls whether `fs.statSync` is called (some callers don't need it).
+ */
+export function scanSessionFiles(dir, parse, filter, opts) {
+    const includeMtime = opts?.includeMtime ?? true;
+    const errorScope = opts?.errorScope ?? "scanSessionFiles";
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        debugError(`${errorScope} readdir`, err);
+        return [];
+    }
+    const results = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.startsWith("session-") || !entry.name.endsWith(".json"))
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        try {
+            const data = parse(fullPath);
+            if (data === null)
+                continue;
+            if (!filter(data, fullPath))
+                continue;
+            let mtimeMs = 0;
+            if (includeMtime) {
+                try {
+                    mtimeMs = fs.statSync(fullPath).mtimeMs;
+                }
+                catch { /* keep 0 */ }
+            }
+            results.push({ fullPath, data, mtimeMs });
+        }
+        catch (err) {
+            debugError(`${errorScope} entry`, err);
+        }
+    }
+    if (includeMtime) {
+        results.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    }
+    return results;
+}

package/mcp/dist/shared-content.js

@@ -0,0 +1,8 @@
+// Barrel re-export. Internal code imports from the specific modules directly.
+export { checkConsolidationNeeded, validateFindingsFormat, stripTaskDoneSection, validateTaskFormat, extractConflictVersions, mergeFindings, mergeTask, autoMergeConflicts, } from "./content-validate.js";
+export { filterTrustedFindings, filterTrustedFindingsDetailed, } from "./content-citation.js";
+export { scanForSecrets, resolveCoref, isDuplicateFinding, detectConflicts, extractDynamicEntities, checkSemanticDedup, checkSemanticConflicts, } from "./content-dedup.js";
+export { countActiveFindings, autoArchiveToReference, } from "./content-archive.js";
+export { upsertCanonical, addFindingToFile, addFindingsToFile, } from "./content-learning.js";
+export { FINDING_LIFECYCLE_STATUSES, parseFindingLifecycle, buildLifecycleComments, isInactiveFindingLine, } from "./finding-lifecycle.js";
+export { METADATA_REGEX, parseStatus, parseStatusField, parseSupersession, parseSupersedesRef, parseContradiction, parseAllContradictions, parseFindingId, parseCreatedDate, isCitationLine, isArchiveStart, isArchiveEnd, stripLifecycleMetadata, stripRelationMetadata, stripAllMetadata, stripComments, addMetadata, } from "./content-metadata.js";

package/mcp/dist/shared-embedding-cache.js

@@ -0,0 +1,143 @@
+import * as fs from "fs";
+import * as crypto from "crypto";
+import { runtimeFile, debugLog } from "./shared.js";
+import { withFileLock } from "./shared-governance.js";
+import { errorMessage } from "./utils.js";
+function isEmbeddingEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return typeof candidate.model === "string"
+        && Array.isArray(candidate.vec)
+        && candidate.vec.every((n) => typeof n === "number" && Number.isFinite(n))
+        && typeof candidate.at === "string";
+}
+function readEmbeddingMapFromDisk(filePath) {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Embedding cache must be a JSON object");
+    }
+    const data = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        if (isEmbeddingEntry(v))
+            data[k] = v;
+    }
+    return data;
+}
+export class EmbeddingCache {
+    phrenPath;
+    cache = new Map();
+    dirty = false;
+    dirtyUpserts = new Set();
+    dirtyDeletes = new Set();
+    constructor(phrenPath) {
+        this.phrenPath = phrenPath;
+    }
+    async load() {
+        if (this.dirty)
+            return;
+        const filePath = runtimeFile(this.phrenPath, "embeddings.json");
+        try {
+            const data = readEmbeddingMapFromDisk(filePath);
+            this.cache = new Map(Object.entries(data));
+            debugLog(`EmbeddingCache loaded: ${this.cache.size} entries`);
+        }
+        catch (err) {
+            const code = err instanceof Error && "code" in err ? String(err.code ?? "") : "";
+            if (code === "ENOENT") {
+                this.cache.clear();
+                return;
+            }
+            debugLog(`EmbeddingCache load failed for ${filePath}: ${errorMessage(err)}`);
+        }
+    }
+    get(docPath, model) {
+        const entry = this.cache.get(docPath);
+        if (!entry || entry.model !== model)
+            return null;
+        return entry.vec;
+    }
+    set(docPath, model, vec) {
+        this.cache.set(docPath, { model, vec, at: new Date().toISOString().slice(0, 10) });
+        this.dirty = true;
+        this.dirtyUpserts.add(docPath);
+        this.dirtyDeletes.delete(docPath);
+    }
+    delete(docPath) {
+        this.cache.delete(docPath);
+        this.dirty = true;
+        this.dirtyDeletes.add(docPath);
+        this.dirtyUpserts.delete(docPath);
+    }
+    async flush() {
+        if (!this.dirty)
+            return;
+        const filePath = runtimeFile(this.phrenPath, "embeddings.json");
+        try {
+            withFileLock(filePath, () => {
+                let data = {};
+                try {
+                    if (fs.existsSync(filePath))
+                        data = readEmbeddingMapFromDisk(filePath);
+                }
+                catch (err) {
+                    debugLog(`EmbeddingCache flush merge read failed for ${filePath}: ${errorMessage(err)}`);
+                }
+                for (const key of this.dirtyDeletes)
+                    delete data[key];
+                for (const key of this.dirtyUpserts) {
+                    const entry = this.cache.get(key);
+                    if (entry)
+                        data[key] = entry;
+                }
+                const tmp = filePath + `.tmp-${crypto.randomUUID()}`;
+                fs.writeFileSync(tmp, JSON.stringify(data));
+                fs.renameSync(tmp, filePath);
+                this.cache = new Map(Object.entries(data));
+            });
+            this.dirty = false;
+            this.dirtyUpserts.clear();
+            this.dirtyDeletes.clear();
+        }
+        catch (err) {
+            debugLog(`EmbeddingCache flush error: ${errorMessage(err)}`);
+        }
+    }
+    getAllEntries() {
+        return [...this.cache.entries()].map(([p, e]) => ({ path: p, vec: e.vec, model: e.model }));
+    }
+    size() {
+        return this.cache.size;
+    }
+    coverage(allPaths) {
+        const total = allPaths.length;
+        const embedded = allPaths.filter(p => this.cache.has(p)).length;
+        const missing = Math.max(0, total - embedded);
+        const pct = total === 0 ? 0 : Math.round((embedded / total) * 100);
+        const missingPct = total === 0 ? 0 : Math.max(0, 100 - pct);
+        const state = total === 0
+            ? "empty"
+            : embedded === 0
+                ? "cold"
+                : embedded === total
+                    ? "warm"
+                    : "warming";
+        return { total, embedded, missing, pct, missingPct, state };
+    }
+}
+export function formatEmbeddingCoverage(coverage) {
+    if (coverage.total === 0)
+        return "0 indexed docs";
+    return `${coverage.embedded}/${coverage.total} docs embedded (${coverage.pct}% warm, ${coverage.missingPct}% cold)`;
+}
+// Module-level singleton per phrenPath
+const cacheInstances = new Map();
+export function getEmbeddingCache(phrenPath) {
+    const existing = cacheInstances.get(phrenPath);
+    if (existing)
+        return existing;
+    const instance = new EmbeddingCache(phrenPath);
+    cacheInstances.set(phrenPath, instance);
+    return instance;
+}