@phren/cli 0.0.1

package/mcp/dist/shared-vector-index.js

@@ -0,0 +1,199 @@
+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";
+const VECTOR_INDEX_VERSION = 1;
+const VECTOR_INDEX_TABLE_COUNT = 4;
+const VECTOR_INDEX_BITS_PER_TABLE = 12;
+const VECTOR_INDEX_TARGET_MULTIPLIER = 8;
+const VECTOR_INDEX_MIN_CANDIDATES = 24;
+const VECTOR_INDEX_FALLBACK_CAP = 64;
+function embeddingsFilePath(phrenPath) {
+    return runtimeFile(phrenPath, "embeddings.json");
+}
+function vectorIndexPath(phrenPath) {
+    return runtimeFile(phrenPath, "embedding-index.json");
+}
+function readSourceMarker(phrenPath) {
+    try {
+        const stat = fs.statSync(embeddingsFilePath(phrenPath));
+        return { mtimeMs: stat.mtimeMs, size: stat.size };
+    }
+    catch {
+        return null;
+    }
+}
+function markersMatch(a, b) {
+    if (!a && !b)
+        return true;
+    if (!a || !b)
+        return false;
+    return a.mtimeMs === b.mtimeMs && a.size === b.size;
+}
+function stepSeed(seed) {
+    return (Math.imul(seed, 1664525) + 1013904223) >>> 0;
+}
+function pairSeed(model, table, bit) {
+    const raw = crypto.createHash("sha256").update(`${model}:${table}:${bit}`).digest();
+    return raw.readUInt32LE(0);
+}
+function dimensionPair(dims, model, table, bit) {
+    if (dims <= 1)
+        return [0, 0];
+    let seed = pairSeed(model, table, bit);
+    const a = seed % dims;
+    seed = stepSeed(seed);
+    let b = seed % dims;
+    if (b === a)
+        b = (b + 1) % dims;
+    return [a, b];
+}
+function bucketKey(vec, model, table) {
+    const dims = vec.length;
+    if (dims === 0)
+        return "";
+    let bits = "";
+    for (let bit = 0; bit < VECTOR_INDEX_BITS_PER_TABLE; bit++) {
+        const [a, b] = dimensionPair(dims, model, table, bit);
+        bits += (vec[a] ?? 0) >= (vec[b] ?? 0) ? "1" : "0";
+    }
+    return bits;
+}
+function oneBitNeighbors(key) {
+    const neighbors = [];
+    for (let i = 0; i < key.length; i++) {
+        neighbors.push(`${key.slice(0, i)}${key[i] === "1" ? "0" : "1"}${key.slice(i + 1)}`);
+    }
+    return neighbors;
+}
+function buildVectorIndexData(entries) {
+    const byModel = new Map();
+    for (const entry of entries) {
+        if (!entry.model || entry.vec.length === 0)
+            continue;
+        const arr = byModel.get(entry.model) ?? [];
+        arr.push(entry);
+        byModel.set(entry.model, arr);
+    }
+    const models = {};
+    for (const [model, modelEntries] of byModel.entries()) {
+        const dims = modelEntries[0]?.vec.length ?? 0;
+        const tables = Array.from({ length: VECTOR_INDEX_TABLE_COUNT }, () => ({}));
+        const allPaths = [];
+        for (const entry of modelEntries) {
+            allPaths.push(entry.path);
+            for (let table = 0; table < VECTOR_INDEX_TABLE_COUNT; table++) {
+                const key = bucketKey(entry.vec, model, table);
+                const bucket = tables[table][key] ?? [];
+                bucket.push(entry.path);
+                tables[table][key] = bucket;
+            }
+        }
+        models[model] = { dims, allPaths, tables };
+    }
+    return models;
+}
+class PersistentVectorIndex {
+    phrenPath;
+    loaded = false;
+    source = null;
+    models = {};
+    constructor(phrenPath) {
+        this.phrenPath = phrenPath;
+    }
+    loadFromDisk() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        const filePath = vectorIndexPath(this.phrenPath);
+        try {
+            const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+            if (parsed?.version !== VECTOR_INDEX_VERSION || !parsed.models || typeof parsed.models !== "object")
+                return;
+            this.source = parsed.source ?? null;
+            this.models = parsed.models;
+        }
+        catch (err) {
+            const code = err instanceof Error && "code" in err ? String(err.code ?? "") : "";
+            if (code !== "ENOENT")
+                debugLog(`PersistentVectorIndex load failed: ${errorMessage(err)}`);
+        }
+    }
+    saveToDisk() {
+        const filePath = vectorIndexPath(this.phrenPath);
+        try {
+            withFileLock(filePath, () => {
+                const tmp = `${filePath}.tmp-${crypto.randomUUID()}`;
+                const payload = {
+                    version: VECTOR_INDEX_VERSION,
+                    source: this.source,
+                    models: this.models,
+                };
+                fs.writeFileSync(tmp, JSON.stringify(payload));
+                fs.renameSync(tmp, filePath);
+            });
+        }
+        catch (err) {
+            debugLog(`PersistentVectorIndex save failed: ${errorMessage(err)}`);
+        }
+    }
+    ensure(entries) {
+        this.loadFromDisk();
+        const currentSource = readSourceMarker(this.phrenPath);
+        if (markersMatch(this.source, currentSource) && Object.keys(this.models).length > 0)
+            return;
+        this.models = buildVectorIndexData(entries);
+        this.source = currentSource;
+        this.saveToDisk();
+    }
+    query(model, queryVec, limit, eligiblePaths) {
+        if (queryVec.length === 0)
+            return [];
+        const modelIndex = this.models[model];
+        if (!modelIndex || modelIndex.dims === 0)
+            return [];
+        const target = Math.max(VECTOR_INDEX_MIN_CANDIDATES, limit * VECTOR_INDEX_TARGET_MULTIPLIER);
+        const seen = new Set();
+        const keys = Array.from({ length: VECTOR_INDEX_TABLE_COUNT }, (_, table) => bucketKey(queryVec, model, table));
+        const addBucket = (table, key) => {
+            const bucket = modelIndex.tables[table]?.[key] ?? [];
+            for (const entryPath of bucket) {
+                if (eligiblePaths && !eligiblePaths.has(entryPath))
+                    continue;
+                seen.add(entryPath);
+                if (seen.size >= target)
+                    return;
+            }
+        };
+        for (let table = 0; table < keys.length && seen.size < target; table++) {
+            addBucket(table, keys[table]);
+        }
+        for (let table = 0; table < keys.length && seen.size < target; table++) {
+            for (const neighbor of oneBitNeighbors(keys[table])) {
+                addBucket(table, neighbor);
+                if (seen.size >= target)
+                    break;
+            }
+        }
+        if (seen.size === 0) {
+            for (const entryPath of modelIndex.allPaths) {
+                if (eligiblePaths && !eligiblePaths.has(entryPath))
+                    continue;
+                seen.add(entryPath);
+                if (seen.size >= VECTOR_INDEX_FALLBACK_CAP)
+                    break;
+            }
+        }
+        return [...seen];
+    }
+}
+const vectorIndexInstances = new Map();
+export function getPersistentVectorIndex(phrenPath) {
+    const existing = vectorIndexInstances.get(phrenPath);
+    if (existing)
+        return existing;
+    const created = new PersistentVectorIndex(phrenPath);
+    vectorIndexInstances.set(phrenPath, created);
+    return created;
+}

package/mcp/dist/shared.js

@@ -0,0 +1,114 @@
+import * as fs from "fs";
+import * as path from "path";
+import { debugLog, runtimeFile } from "./phren-paths.js";
+import { errorMessage, isValidProjectName } from "./utils.js";
+export { HOOK_TOOL_NAMES, hookConfigPath } from "./provider-adapters.js";
+export { EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, PhrenError, phrenOk, phrenErr, forwardErr, parsePhrenErrorCode, isRecord, withDefaults, FINDING_TYPES, FINDING_TAGS, KNOWN_OBSERVATION_TAGS, DOC_TYPES, capCache, } from "./phren-core.js";
+export { ROOT_MANIFEST_FILENAME, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, findProjectNameCaseInsensitive, getProjectDirs, collectNativeMemoryFiles, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, } from "./phren-paths.js";
+export { PROACTIVITY_LEVELS, getProactivityLevel, getProactivityLevelForFindings, getProactivityLevelForTask, hasExplicitFindingSignal, hasExplicitTaskSignal, hasExecutionIntent, hasDiscoveryIntent, shouldAutoCaptureFindingsForLevel, shouldAutoCaptureTaskForLevel, } from "./proactivity.js";
+const RESERVED_PROJECT_DIR_NAMES = new Set(["profiles", "templates", "global"]);
+const MEMORY_SCOPE_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+export function normalizeMemoryScope(scope) {
+    if (typeof scope !== "string")
+        return undefined;
+    const normalized = scope.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    if (!MEMORY_SCOPE_PATTERN.test(normalized))
+        return undefined;
+    return normalized;
+}
+export function isMemoryScopeVisible(itemScope, activeScope) {
+    if (!activeScope)
+        return true;
+    if (!itemScope)
+        return true; // Untagged legacy entries are visible to all scoped agents.
+    return itemScope === "shared" || itemScope === activeScope;
+}
+export function impactLogFile(phrenPath) {
+    return runtimeFile(phrenPath, "impact.jsonl");
+}
+function isProjectDirEntry(entry) {
+    return entry.isDirectory()
+        && !entry.name.startsWith(".")
+        && !entry.name.endsWith(".archived")
+        && !RESERVED_PROJECT_DIR_NAMES.has(entry.name);
+}
+function isCanonicalProjectDirName(name) {
+    return name === name.toLowerCase() && isValidProjectName(name);
+}
+export function appendAuditLog(phrenPath, event, details) {
+    const logPath = runtimeFile(phrenPath, "audit.log");
+    const line = `[${new Date().toISOString()}] ${event} ${details}\n`;
+    const lockPath = logPath + ".lock";
+    const maxWait = 5000;
+    const pollMs = 50;
+    const staleMs = 30_000;
+    const waiter = new Int32Array(new SharedArrayBuffer(4));
+    // Q82: use an inline lock (same protocol as withFileLock) to guard the
+    // append + conditional rotation so concurrent processes don't read the same
+    // old content and race to write a truncated version each.
+    let waited = 0;
+    let hasLock = false;
+    try {
+        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+        while (waited < maxWait) {
+            try {
+                fs.writeFileSync(lockPath, `${process.pid}\n${Date.now()}`, { flag: "wx" });
+                hasLock = true;
+                break;
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] appendAuditLog lockWrite: ${errorMessage(err)}\n`);
+                try {
+                    const stat = fs.statSync(lockPath);
+                    if (Date.now() - stat.mtimeMs > staleMs) {
+                        try {
+                            fs.unlinkSync(lockPath);
+                        }
+                        catch {
+                            // Another process may have claimed or removed the stale lock between
+                            // statSync and unlinkSync. Sleep before retrying to avoid a spin loop.
+                            Atomics.wait(waiter, 0, 0, pollMs);
+                            waited += pollMs;
+                        }
+                        continue;
+                    }
+                }
+                catch (statErr) {
+                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                        process.stderr.write(`[phren] appendAuditLog staleStat: ${errorMessage(statErr)}\n`);
+                }
+                Atomics.wait(waiter, 0, 0, pollMs);
+                waited += pollMs;
+            }
+        }
+        if (hasLock) {
+            fs.appendFileSync(logPath, line);
+            const stat = fs.statSync(logPath);
+            if (stat.size > 1_000_000) {
+                const content = fs.readFileSync(logPath, "utf8");
+                const lines = content.split("\n");
+                fs.writeFileSync(logPath, lines.slice(-500).join("\n"));
+            }
+        }
+        else {
+            debugLog(`Audit log skipped (lock timeout): ${event} ${details}`);
+        }
+    }
+    catch (err) {
+        debugLog(`Audit log write failed: ${errorMessage(err)}`);
+    }
+    finally {
+        if (hasLock) {
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] appendAuditLog unlock: ${errorMessage(err)}\n`);
+            }
+        }
+    }
+}

package/mcp/dist/shell-entry.js

@@ -0,0 +1,209 @@
+/**
+ * Shell entry point: wires PhrenShell to stdin/stdout.
+ * Extracted from shell.ts to keep the orchestrator under 300 lines.
+ */
+import { PhrenShell } from "./shell.js";
+import { style, clearScreen, clearToEnd, shellStartupFrames } from "./shell-render.js";
+import { errorMessage } from "./utils.js";
+import { computePhrenLiveStateToken } from "./shared.js";
+import { VERSION } from "./init-shared.js";
+import { loadShellState, saveShellState } from "./shell-state-store.js";
+const LIVE_STATE_POLL_MS = 2000;
+function renderIntroFrame(frame, footer) {
+    clearScreen();
+    process.stdout.write(footer ? `${frame}\n${footer}\n` : `${frame}\n`);
+    clearToEnd();
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForAnyKeypress() {
+    await new Promise((resolve) => {
+        const onData = () => {
+            process.stdin.removeListener("data", onData);
+            resolve();
+        };
+        process.stdin.on("data", onData);
+    });
+}
+export function resolveStartupIntroPlan(phrenPath, version = VERSION) {
+    const state = loadShellState(phrenPath);
+    const mode = state.introMode === "always" || state.introMode === "off" ? state.introMode : "once-per-version";
+    if (mode === "off") {
+        return { mode, variant: "skip", holdForKeypress: false, dwellMs: 0, markSeen: false };
+    }
+    if (mode === "always") {
+        return { mode, variant: "full", holdForKeypress: false, dwellMs: 700, markSeen: true };
+    }
+    if (state.introSeenVersion !== version) {
+        return { mode, variant: "full", holdForKeypress: true, dwellMs: 0, markSeen: true };
+    }
+    return { mode, variant: "final-frame", holdForKeypress: false, dwellMs: 550, markSeen: false };
+}
+function markStartupIntroSeen(phrenPath, version = VERSION) {
+    const state = loadShellState(phrenPath);
+    if (state.introSeenVersion === version)
+        return;
+    saveShellState(phrenPath, { ...state, introSeenVersion: version });
+}
+async function playStartupIntro(phrenPath, plan = resolveStartupIntroPlan(phrenPath)) {
+    if (!process.stdout.isTTY || plan.variant === "skip")
+        return;
+    const frames = shellStartupFrames(VERSION);
+    const renderHint = plan.holdForKeypress
+        ? `${style.dim("Press any key to enter")}`
+        : `${style.dim("Loading shell…")}`;
+    if (plan.variant === "full") {
+        for (const frame of frames.slice(0, -1)) {
+            renderIntroFrame(frame);
+            await sleep(160);
+        }
+    }
+    renderIntroFrame(frames[frames.length - 1], renderHint);
+    if (plan.holdForKeypress) {
+        await waitForAnyKeypress();
+    }
+    else if (plan.dwellMs > 0) {
+        await sleep(plan.dwellMs);
+    }
+    if (plan.markSeen) {
+        markStartupIntroSeen(phrenPath);
+    }
+}
+export function startLiveStatePoller({ phrenPath, shell, repaint, isExiting = () => false, intervalMs = LIVE_STATE_POLL_MS, computeToken = computePhrenLiveStateToken, }) {
+    let liveStateToken = computeToken(phrenPath);
+    let stopped = false;
+    let inFlight = false;
+    const pollOnce = async () => {
+        if (stopped || inFlight || isExiting())
+            return;
+        inFlight = true;
+        try {
+            const nextToken = computeToken(phrenPath);
+            if (nextToken === liveStateToken)
+                return;
+            liveStateToken = nextToken;
+            shell.invalidateSubsectionsCache();
+            shell.setMessage(`  ${style.boldCyan("Live")} ${style.dim("store updated")}`);
+            await repaint();
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+    const poll = setInterval(() => {
+        void pollOnce();
+    }, intervalMs);
+    poll.unref?.();
+    return () => {
+        stopped = true;
+        clearInterval(poll);
+    };
+}
+export async function startShell(phrenPath, profile) {
+    const shell = new PhrenShell(phrenPath, profile);
+    if (!process.stdin.isTTY) {
+        const { createInterface } = await import("readline");
+        const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+        const repaint = async () => { clearScreen(); process.stdout.write(await shell.render()); rl.setPrompt(`\n${style.boldCyan(":phren>")} `); rl.prompt(); };
+        const stopPoll = startLiveStatePoller({ phrenPath, shell, repaint });
+        await repaint();
+        rl.on("line", async (line) => {
+            try {
+                const keep = await shell.handleInput(line);
+                if (!keep) {
+                    shell.close();
+                    rl.close();
+                    return;
+                }
+            }
+            catch (err) {
+                process.stdout.write(`\n${style.red("Error:")} ${String(errorMessage(err))}\n`);
+            }
+            await repaint();
+        });
+        rl.on("SIGINT", () => { stopPoll(); shell.close(); rl.close(); });
+        rl.on("close", () => { stopPoll(); });
+        await new Promise((resolve) => { rl.on("close", () => { shell.close(); resolve(); }); });
+        return;
+    }
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    process.stdout.write("\x1b[?1049h");
+    let exiting = false;
+    let cleanedUp = false;
+    const repaint = async () => { clearScreen(); process.stdout.write(await shell.render()); clearToEnd(); };
+    let done;
+    const exitPromise = new Promise((resolve) => { done = resolve; });
+    const restoreTerminal = () => {
+        // Shutdown cleanup is intentionally silent: terminal restoration is best-effort
+        // cleanup, not a user-requested write path.
+        try {
+            process.stdin.setRawMode(false);
+        }
+        catch { }
+        try {
+            process.stdin.pause();
+        }
+        catch { }
+        try {
+            process.stdout.write("\x1b[?1049l");
+        }
+        catch { }
+    };
+    const onData = async (key) => {
+        if (exiting)
+            return;
+        try {
+            const keep = await shell.handleRawKey(key);
+            if (!keep) {
+                exiting = true;
+                finish();
+                return;
+            }
+            await repaint();
+        }
+        catch (err) {
+            shell.setMessage(`Error: ${errorMessage(err)}`);
+            await repaint();
+        }
+    };
+    const onResize = async () => { if (!exiting)
+        await repaint(); };
+    const onSignal = () => {
+        if (exiting)
+            return;
+        exiting = true;
+        finish();
+    };
+    const onProcessExit = () => { restoreTerminal(); };
+    const stopPoll = startLiveStatePoller({ phrenPath, shell, repaint, isExiting: () => exiting });
+    const finish = () => {
+        if (cleanedUp)
+            return;
+        cleanedUp = true;
+        stopPoll();
+        process.stdin.removeListener("data", onData);
+        process.stdout.removeListener("resize", onResize);
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+        process.removeListener("exit", onProcessExit);
+        restoreTerminal();
+        shell.close();
+        done();
+    };
+    process.stdin.on("data", onData);
+    process.stdout.on("resize", onResize);
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+    process.once("exit", onProcessExit);
+    try {
+        await playStartupIntro(phrenPath);
+        await repaint();
+        await exitPromise;
+    }
+    finally {
+        finish();
+    }
+}