@phren/cli 0.0.1

package/mcp/dist/phren-core.js

@@ -0,0 +1,108 @@
+// Shared Phren result types, validation tags, and low-level helpers.
+/**
+ * Minimal cross-domain starter set for entity/conflict detection.
+ *
+ * Kept intentionally small: only terms that are genuinely universal across
+ * disciplines (languages, infra primitives, version control). Framework-specific
+ * tools (React, Django, Unity, JUCE, Ansible, ...) are learned dynamically from
+ * each project's FINDINGS.md via extractDynamicEntities().
+ */
+export const UNIVERSAL_TECH_TERMS_RE = /\b(Python|Rust|Go|Java|TypeScript|JavaScript|Docker|Kubernetes|AWS|GCP|Azure|SQL|Git)\b/gi;
+/**
+ * Additional entity patterns beyond CamelCase and acronyms.
+ * Each pattern has a named group so callers can identify the entity type.
+ */
+export const EXTRA_ENTITY_PATTERNS = [
+    // Semantic version numbers: v1.2.3, 2.0.0-beta.1
+    { re: /\bv?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?\b/g, label: "version" },
+    // Environment variable keys: PHREN_*, NODE_ENV, etc. (2+ uppercase segments separated by _)
+    { re: /\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b/g, label: "env_key" },
+    // File paths: at least one slash with an extension or known dir prefix
+    { re: /(?:~\/|\.\/|\/)[a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+/g, label: "file_path" },
+    // Error codes: E0001, ERR_MODULE_NOT_FOUND, TS2345, etc.
+    { re: /\b(?:ERR_[A-Z0-9_]{3,}|(?:TS|RS|PY|E)\d{3,})\b/g, label: "error_code" },
+    // ISO date references: 2025-03-11, 2025/03/11
+    { re: /\b\d{4}[-/]\d{2}[-/]\d{2}\b/g, label: "date" },
+];
+// Default timeout for execFileSync calls (30s for most operations, 10s for quick probes like `which`)
+export const EXEC_TIMEOUT_MS = 30_000;
+export const EXEC_TIMEOUT_QUICK_MS = 10_000;
+// Structured error codes for consistent error handling across data-access and MCP tools
+export const PhrenError = {
+    PROJECT_NOT_FOUND: "PROJECT_NOT_FOUND",
+    INVALID_PROJECT_NAME: "INVALID_PROJECT_NAME",
+    FILE_NOT_FOUND: "FILE_NOT_FOUND",
+    PERMISSION_DENIED: "PERMISSION_DENIED",
+    MALFORMED_JSON: "MALFORMED_JSON",
+    MALFORMED_YAML: "MALFORMED_YAML",
+    NOT_FOUND: "NOT_FOUND",
+    AMBIGUOUS_MATCH: "AMBIGUOUS_MATCH",
+    LOCK_TIMEOUT: "LOCK_TIMEOUT",
+    EMPTY_INPUT: "EMPTY_INPUT",
+    VALIDATION_ERROR: "VALIDATION_ERROR",
+    INDEX_ERROR: "INDEX_ERROR",
+    NETWORK_ERROR: "NETWORK_ERROR",
+};
+export function phrenOk(data) {
+    return { ok: true, data };
+}
+export function phrenErr(error, code) {
+    return { ok: false, error, code };
+}
+// Forward a failed PhrenResult to a different result type (re-types the error branch).
+// Safe to call after an `if (!result.ok)` guard; extracts error and code from the union.
+export function forwardErr(result) {
+    if (!result.ok)
+        return { ok: false, error: result.error, code: result.code };
+    return { ok: false, error: "unexpected forward of ok result" };
+}
+const ERROR_CODES = new Set(Object.values(PhrenError));
+// Extract the error code from an error string (e.g. "PROJECT_NOT_FOUND: ...").
+// Returns the code if the string starts with a known PhrenError, or undefined.
+export function parsePhrenErrorCode(msg) {
+    const prefix = msg.split(":")[0]?.trim();
+    if (prefix && ERROR_CODES.has(prefix))
+        return prefix;
+    return undefined;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Shallow-merge data onto defaults so missing keys get filled in. */
+export function withDefaults(data, defaults) {
+    const merged = { ...defaults };
+    for (const key of Object.keys(data)) {
+        const val = data[key];
+        if (val !== undefined && val !== null) {
+            if (typeof val === "object" && !Array.isArray(val) && typeof merged[key] === "object" && !Array.isArray(merged[key])) {
+                merged[key] = { ...merged[key], ...val };
+            }
+            else {
+                merged[key] = val;
+            }
+        }
+    }
+    return merged;
+}
+/** All valid finding type tags — used for writes, search filters, and hook extraction */
+export const FINDING_TYPES = ["decision", "pitfall", "pattern", "tradeoff", "architecture", "bug"];
+/** Searchable finding tags (same set as FINDING_TYPES) */
+export const FINDING_TAGS = FINDING_TYPES;
+/** Canonical set of known observation tags — derived from FINDING_TYPES */
+export const KNOWN_OBSERVATION_TAGS = new Set(FINDING_TYPES);
+/** Document types in the FTS index */
+export const DOC_TYPES = ["claude", "findings", "reference", "skills", "summary", "task", "changelog", "canonical", "memory-queue", "skill", "other"];
+// ── Cache eviction helper ────────────────────────────────────────────────────
+const CACHE_MAX = 1000;
+const CACHE_EVICT = 100;
+export function capCache(cache) {
+    if (cache.size > CACHE_MAX) {
+        const it = cache.keys();
+        for (let i = 0; i < CACHE_EVICT; i++) {
+            const k = it.next();
+            if (k.done)
+                break;
+            cache.delete(k.value);
+        }
+    }
+}

package/mcp/dist/phren-dotenv.js

@@ -0,0 +1,67 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+let _loadedEnvKey;
+let _loadedEnvPath = null;
+let _loadedEnvMtimeMs = -1;
+function homeDir() {
+    return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+function parseAndApplyDotEnv(filePath) {
+    const content = fs.readFileSync(filePath, "utf8");
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIdx = trimmed.indexOf("=");
+        if (eqIdx < 1)
+            continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        const raw = trimmed.slice(eqIdx + 1).trim();
+        const value = /^(["'])(.*)\1$/.test(raw) ? raw.slice(1, -1) : raw;
+        if (key && !(key in process.env))
+            process.env[key] = value;
+    }
+}
+function resolveDotEnvPath(phrenPath) {
+    const envPath = process.env.PHREN_PATH;
+    const candidates = [
+        phrenPath ? path.join(phrenPath, ".env") : null,
+        envPath ? path.join(envPath, ".env") : null,
+        path.join(homeDir(), ".phren", ".env"),
+    ].filter((candidate) => Boolean(candidate));
+    const seen = new Set();
+    for (const candidate of candidates) {
+        const resolved = path.resolve(candidate);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        if (fs.existsSync(resolved))
+            return resolved;
+    }
+    return null;
+}
+export function bootstrapPhrenDotEnv(phrenPath) {
+    const cacheKey = `${phrenPath ?? ""}|${process.env.PHREN_PATH ?? ""}|${process.env.HOME ?? ""}|${process.env.USERPROFILE ?? ""}`;
+    const envPath = resolveDotEnvPath(phrenPath);
+    if (!envPath) {
+        _loadedEnvKey = cacheKey;
+        _loadedEnvPath = null;
+        _loadedEnvMtimeMs = -1;
+        return null;
+    }
+    const mtimeMs = fs.statSync(envPath).mtimeMs;
+    if (_loadedEnvKey === cacheKey && _loadedEnvPath === envPath && _loadedEnvMtimeMs === mtimeMs) {
+        return envPath;
+    }
+    parseAndApplyDotEnv(envPath);
+    _loadedEnvKey = cacheKey;
+    _loadedEnvPath = envPath;
+    _loadedEnvMtimeMs = mtimeMs;
+    return envPath;
+}
+export function resetPhrenDotEnvBootstrapForTests() {
+    _loadedEnvKey = undefined;
+    _loadedEnvPath = null;
+    _loadedEnvMtimeMs = -1;
+}

package/mcp/dist/phren-paths.js

@@ -0,0 +1,476 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import * as crypto from "crypto";
+import * as yaml from "js-yaml";
+import { bootstrapPhrenDotEnv } from "./phren-dotenv.js";
+import { PhrenError, isRecord } from "./phren-core.js";
+import { errorMessage, isValidProjectName, safeProjectPath } from "./utils.js";
+bootstrapPhrenDotEnv();
+export const ROOT_MANIFEST_FILENAME = "phren.root.yaml";
+export function homeDir() {
+    return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+export function homePath(...parts) {
+    return path.join(homeDir(), ...parts);
+}
+export function expandHomePath(input) {
+    if (input === "~")
+        return homeDir();
+    if (input.startsWith("~/") || input.startsWith("~\\"))
+        return path.join(homeDir(), input.slice(2));
+    return input;
+}
+export function defaultPhrenPath() {
+    return expandHomePath(process.env.PHREN_PATH || homePath(".phren"));
+}
+export function rootManifestPath(phrenPath) {
+    return path.join(phrenPath, ROOT_MANIFEST_FILENAME);
+}
+export function atomicWriteText(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.tmp-${crypto.randomUUID()}`;
+    fs.writeFileSync(tmpPath, content);
+    fs.renameSync(tmpPath, filePath);
+}
+function isInstallMode(value) {
+    return value === "shared" || value === "project-local";
+}
+function isSyncMode(value) {
+    return value === "managed-git" || value === "workspace-git";
+}
+function normalizeManifest(raw) {
+    if (!isRecord(raw))
+        return null;
+    const version = Number(raw.version);
+    const installMode = raw.installMode;
+    const syncMode = raw.syncMode;
+    if (version !== 1 || !isInstallMode(installMode) || !isSyncMode(syncMode))
+        return null;
+    const workspaceRoot = typeof raw.workspaceRoot === "string" && raw.workspaceRoot.trim()
+        ? path.resolve(expandHomePath(raw.workspaceRoot))
+        : undefined;
+    const primaryProject = typeof raw.primaryProject === "string" && raw.primaryProject.trim()
+        ? raw.primaryProject.trim()
+        : undefined;
+    if (installMode === "project-local") {
+        if (!workspaceRoot || !primaryProject || !isValidProjectName(primaryProject))
+            return null;
+    }
+    return {
+        version: 1,
+        installMode,
+        syncMode,
+        workspaceRoot,
+        primaryProject,
+    };
+}
+export function readRootManifest(phrenPath) {
+    const manifestFile = rootManifestPath(phrenPath);
+    if (!fs.existsSync(manifestFile))
+        return null;
+    try {
+        const parsed = yaml.load(fs.readFileSync(manifestFile, "utf8"), { schema: yaml.CORE_SCHEMA });
+        return normalizeManifest(parsed);
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] readRootManifest: ${errorMessage(err)}\n`);
+        return null;
+    }
+}
+export function writeRootManifest(phrenPath, manifest) {
+    const normalized = normalizeManifest(manifest);
+    if (!normalized) {
+        throw new Error(`${PhrenError.VALIDATION_ERROR}: invalid phren root manifest for ${phrenPath}`);
+    }
+    atomicWriteText(rootManifestPath(phrenPath), yaml.dump(normalized, { lineWidth: 1000 }));
+}
+export function resolveInstallContext(phrenPath) {
+    const resolvedPath = path.resolve(phrenPath);
+    const manifest = readRootManifest(resolvedPath);
+    if (!manifest) {
+        throw new Error(`${PhrenError.NOT_FOUND}: phren root manifest not found: ${rootManifestPath(resolvedPath)}`);
+    }
+    return { phrenPath: resolvedPath, ...manifest };
+}
+function requireDirectory(resolved, label) {
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`${PhrenError.NOT_FOUND}: ${label} not found: ${resolved}`);
+    }
+    if (!fs.statSync(resolved).isDirectory()) {
+        throw new Error(`${PhrenError.VALIDATION_ERROR}: ${label} is not a directory: ${resolved}`);
+    }
+    return resolved;
+}
+function hasRootManifest(candidate) {
+    return fs.existsSync(rootManifestPath(candidate));
+}
+function hasInstallMarkers(candidate) {
+    return fs.existsSync(path.join(candidate, "machines.yaml"))
+        || fs.existsSync(path.join(candidate, ".governance"))
+        || fs.existsSync(path.join(candidate, "global"));
+}
+function isPhrenRootCandidate(candidate) {
+    return hasRootManifest(candidate) || hasInstallMarkers(candidate);
+}
+export function findNearestPhrenPath(startDir = process.cwd()) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const localCandidate = path.join(current, ".phren");
+        if (isPhrenRootCandidate(localCandidate))
+            return localCandidate;
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+function sharedRootCandidate() {
+    return homePath(".phren");
+}
+let cachedPhrenPath;
+let cachedPhrenPathKey;
+export function findPhrenPath() {
+    const cacheKey = [
+        ((process.env.PHREN_PATH || process.env.PHREN_PATH) ?? ""),
+        process.env.HOME ?? "",
+        process.env.USERPROFILE ?? "",
+        process.cwd(),
+    ].join("|");
+    if (cachedPhrenPath !== undefined && cachedPhrenPathKey === cacheKey)
+        return cachedPhrenPath;
+    cachedPhrenPathKey = cacheKey;
+    const envVal = (process.env.PHREN_PATH || process.env.PHREN_PATH)?.trim();
+    if (envVal) {
+        const resolved = path.resolve(expandHomePath(envVal));
+        cachedPhrenPath = isPhrenRootCandidate(resolved) ? resolved : null;
+        return cachedPhrenPath;
+    }
+    const nearest = findNearestPhrenPath();
+    if (nearest) {
+        cachedPhrenPath = nearest;
+        return nearest;
+    }
+    const shared = sharedRootCandidate();
+    cachedPhrenPath = isPhrenRootCandidate(shared) ? shared : null;
+    return cachedPhrenPath;
+}
+export function ensurePhrenPath() {
+    const existing = findPhrenPath();
+    if (existing)
+        return existing;
+    const defaultPath = sharedRootCandidate();
+    fs.mkdirSync(defaultPath, { recursive: true });
+    writeRootManifest(defaultPath, {
+        version: 1,
+        installMode: "shared",
+        syncMode: "managed-git",
+    });
+    cachedPhrenPath = defaultPath;
+    cachedPhrenPathKey = [
+        ((process.env.PHREN_PATH || process.env.PHREN_PATH) ?? ""),
+        process.env.HOME ?? "",
+        process.env.USERPROFILE ?? "",
+        process.cwd(),
+    ].join("|");
+    return defaultPath;
+}
+export function findPhrenPathWithArg(arg) {
+    if (arg) {
+        const resolved = requireDirectory(path.resolve(expandHomePath(arg)), "phren path");
+        if (!hasRootManifest(resolved)) {
+            throw new Error(`${PhrenError.NOT_FOUND}: phren root manifest not found: ${rootManifestPath(resolved)}`);
+        }
+        return resolved;
+    }
+    const existing = findPhrenPath();
+    if (existing)
+        return existing;
+    throw new Error(`${PhrenError.NOT_FOUND}: phren root not found. Run 'npx phren init'.`);
+}
+export function isProjectLocalMode(phrenPath) {
+    try {
+        return resolveInstallContext(phrenPath).installMode === "project-local";
+    }
+    catch {
+        return false;
+    }
+}
+// Centralized runtime path helpers. All ephemeral/runtime files go in
+// subdirectories to keep the phren root clean.
+export function runtimeDir(phrenPath) {
+    return path.join(phrenPath, ".runtime");
+}
+/** Unlink a file, ignoring ENOENT. Rethrows any other error. */
+export function tryUnlink(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+}
+export function sessionsDir(phrenPath) {
+    return path.join(phrenPath, ".sessions");
+}
+const runtimeDirsMade = new Set();
+export function runtimeFile(phrenPath, name) {
+    const dir = runtimeDir(phrenPath);
+    if (!runtimeDirsMade.has(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+        runtimeDirsMade.add(dir);
+    }
+    return path.join(dir, name);
+}
+export function installPreferencesFile(phrenPath) {
+    return path.join(runtimeDir(phrenPath), "install-preferences.json");
+}
+export function runtimeHealthFile(phrenPath) {
+    return path.join(runtimeDir(phrenPath), "runtime-health.json");
+}
+export function shellStateFile(phrenPath) {
+    return path.join(runtimeDir(phrenPath), "shell-state.json");
+}
+export function sessionMetricsFile(phrenPath) {
+    return path.join(runtimeDir(phrenPath), "session-metrics.json");
+}
+export function memoryScoresFile(phrenPath) {
+    return path.join(runtimeDir(phrenPath), "memory-scores.json");
+}
+export function memoryUsageLogFile(phrenPath) {
+    return path.join(runtimeDir(phrenPath), "memory-usage.log");
+}
+export function sessionMarker(phrenPath, name) {
+    const dir = sessionsDir(phrenPath);
+    fs.mkdirSync(dir, { recursive: true });
+    return path.join(dir, name);
+}
+// Debug logging is best-effort and only writes when a phren root already exists.
+export function debugLog(msg) {
+    if (!(process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+        return;
+    const phrenPath = findPhrenPath();
+    if (!phrenPath)
+        return;
+    const logFile = runtimeFile(phrenPath, "debug.log");
+    try {
+        fs.appendFileSync(logFile, `[${new Date().toISOString()}] ${msg}\n`);
+    }
+    catch {
+        // debug log is best-effort; logging errors about logging would recurse
+    }
+}
+export function appendIndexEvent(phrenPath, event) {
+    try {
+        const file = runtimeFile(phrenPath, "index-events.jsonl");
+        fs.appendFileSync(file, JSON.stringify({ at: new Date().toISOString(), ...event }) + "\n");
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] appendIndexEvent: ${errorMessage(err)}\n`);
+    }
+}
+/** Resolve the canonical findings file for a project directory. */
+export function resolveFindingsPath(projectDir) {
+    const findingsPath = path.join(projectDir, "FINDINGS.md");
+    if (fs.existsSync(findingsPath))
+        return findingsPath;
+    return undefined;
+}
+const RESERVED_PROJECT_DIR_NAMES = new Set(["profiles", "templates", "global"]);
+function isProjectDirEntry(entry) {
+    return entry.isDirectory()
+        && !entry.name.startsWith(".")
+        && !entry.name.endsWith(".archived")
+        && !RESERVED_PROJECT_DIR_NAMES.has(entry.name);
+}
+export function normalizeProjectNameForCreate(name) {
+    return name.trim().toLowerCase();
+}
+export function findProjectNameCaseInsensitive(phrenPath, name) {
+    const needle = name.toLowerCase();
+    try {
+        for (const entry of fs.readdirSync(phrenPath, { withFileTypes: true })) {
+            if (!isProjectDirEntry(entry))
+                continue;
+            if (entry.name.toLowerCase() === needle)
+                return entry.name;
+        }
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] findProjectNameCaseInsensitive: ${errorMessage(err)}\n`);
+    }
+    return null;
+}
+function getLocalProjectDirs(phrenPath, manifest) {
+    const primaryProject = manifest.primaryProject;
+    if (!primaryProject || !isValidProjectName(primaryProject))
+        return [];
+    const projectPath = safeProjectPath(phrenPath, primaryProject);
+    if (!projectPath || !fs.existsSync(projectPath) || !fs.statSync(projectPath).isDirectory())
+        return [];
+    const visible = fs.readdirSync(phrenPath, { withFileTypes: true }).filter(isProjectDirEntry).map((entry) => entry.name);
+    if (visible.length !== 1 || visible[0] !== primaryProject)
+        return [];
+    return [projectPath];
+}
+// Figure out which project directories to index.
+export function getProjectDirs(phrenPath, profile) {
+    const manifest = readRootManifest(phrenPath);
+    if (manifest?.installMode === "project-local") {
+        return getLocalProjectDirs(phrenPath, manifest);
+    }
+    if (profile) {
+        if (!isValidProjectName(profile)) {
+            console.error(`${PhrenError.VALIDATION_ERROR}: Invalid PHREN_PROFILE value: ${profile}`);
+            return [];
+        }
+        const profilePath = path.join(phrenPath, "profiles", `${profile}.yaml`);
+        if (!fs.existsSync(profilePath)) {
+            console.error(`${PhrenError.FILE_NOT_FOUND}: Profile file not found: ${profilePath}`);
+            return [];
+        }
+        try {
+            const data = yaml.load(fs.readFileSync(profilePath, "utf-8"), { schema: yaml.CORE_SCHEMA });
+            const projects = isRecord(data) ? data.projects : undefined;
+            if (!Array.isArray(projects)) {
+                console.error(`${PhrenError.MALFORMED_YAML}: Profile YAML missing valid "projects" array: ${profilePath}`);
+                return [];
+            }
+            const listed = projects
+                .map((p) => {
+                const name = String(p);
+                if (!isValidProjectName(name)) {
+                    console.error(`${PhrenError.VALIDATION_ERROR}: Skipping invalid project name in profile: ${name}`);
+                    return null;
+                }
+                return safeProjectPath(phrenPath, name);
+            })
+                .filter((p) => p !== null && fs.existsSync(p));
+            const sharedDirs = ["shared", "org"]
+                .map((name) => safeProjectPath(phrenPath, name))
+                .filter((p) => Boolean(p && fs.existsSync(p) && fs.statSync(p).isDirectory()));
+            return [...new Set([...listed, ...sharedDirs])];
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] getProjectDirs yamlParse: ${errorMessage(err)}\n`);
+            console.error(`${PhrenError.MALFORMED_YAML}: Malformed profile YAML: ${profilePath}`);
+            return [];
+        }
+    }
+    try {
+        return fs.readdirSync(phrenPath, { withFileTypes: true })
+            .filter(isProjectDirEntry)
+            .map((entry) => path.join(phrenPath, entry.name));
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] getProjectDirs: ${errorMessage(err)}\n`);
+        return [];
+    }
+}
+// Collect MEMORY*.md files from native agent memory locations (~/.claude/projects/*/memory/)
+export function collectNativeMemoryFiles() {
+    const claudeProjectsDir = homePath(".claude", "projects");
+    if (!fs.existsSync(claudeProjectsDir))
+        return [];
+    const results = [];
+    try {
+        for (const entry of fs.readdirSync(claudeProjectsDir)) {
+            const memDir = path.join(claudeProjectsDir, entry, "memory");
+            if (!fs.existsSync(memDir))
+                continue;
+            for (const file of fs.readdirSync(memDir)) {
+                if (!file.endsWith(".md") || file === "MEMORY.md")
+                    continue;
+                const fullPath = path.join(memDir, file);
+                const match = file.match(/^MEMORY-(.+)\.md$/);
+                const project = match ? match[1] : `native:${entry}`;
+                results.push({ project, file, fullPath });
+            }
+        }
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] collectNativeMemoryFiles: ${errorMessage(err)}\n`);
+    }
+    return results;
+}
+function pushFileToken(parts, filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        if (stat.isFile())
+            parts.push(`${filePath}:${stat.mtimeMs}:${stat.size}`);
+    }
+    catch {
+        parts.push(`${filePath}:missing`);
+    }
+}
+function pushDirTokens(parts, dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        parts.push(`${dirPath}:missing`);
+        return;
+    }
+    for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+        const fullPath = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            pushDirTokens(parts, fullPath);
+            continue;
+        }
+        const stat = fs.statSync(fullPath);
+        parts.push(`${fullPath}:${stat.mtimeMs}:${stat.size}`);
+    }
+}
+export function computePhrenLiveStateToken(phrenPath) {
+    const parts = [];
+    const projectDirs = getProjectDirs(phrenPath).sort();
+    const manifest = readRootManifest(phrenPath);
+    for (const projectDir of projectDirs) {
+        const project = path.basename(projectDir);
+        parts.push(`project:${project}`);
+        for (const file of ["CLAUDE.md", "summary.md", "FINDINGS.md", "tasks.md", "MEMORY_QUEUE.md", "CANONICAL_MEMORIES.md", "topic-config.json", "phren.project.yaml"]) {
+            pushFileToken(parts, path.join(projectDir, file));
+        }
+        pushDirTokens(parts, path.join(projectDir, "reference"));
+        pushDirTokens(parts, path.join(projectDir, "skills"));
+        pushDirTokens(parts, path.join(projectDir, ".claude", "skills"));
+    }
+    if (manifest?.installMode === "shared") {
+        pushDirTokens(parts, path.join(phrenPath, "profiles"));
+    }
+    pushDirTokens(parts, path.join(phrenPath, "global", "skills"));
+    pushFileToken(parts, path.join(phrenPath, ".governance", "access-control.json"));
+    pushFileToken(parts, rootManifestPath(phrenPath));
+    pushFileToken(parts, runtimeHealthFile(phrenPath));
+    pushFileToken(parts, runtimeFile(phrenPath, "audit.log"));
+    pushFileToken(parts, memoryUsageLogFile(phrenPath));
+    pushFileToken(parts, installPreferencesFile(phrenPath));
+    if (manifest?.installMode === "shared") {
+        pushDirTokens(parts, homePath(".github", "hooks"));
+        pushFileToken(parts, homePath(".cursor", "hooks.json"));
+    }
+    return parts.sort().join("|");
+}
+// Lazy singleton for getPhrenPath — shared across all CLI modules.
+let lazyPhrenPath;
+export function getPhrenPath() {
+    if (!lazyPhrenPath) {
+        const existing = findPhrenPath();
+        if (!existing)
+            throw new Error(`${PhrenError.NOT_FOUND}: phren root not found. Run 'npx phren init'.`);
+        lazyPhrenPath = existing;
+    }
+    return lazyPhrenPath;
+}
+export function qualityMarkers(phrenPathLocal) {
+    const today = new Date().toISOString().slice(0, 10);
+    return {
+        done: runtimeFile(phrenPathLocal, `quality-${today}`),
+        lock: runtimeFile(phrenPathLocal, `quality-${today}.lock`),
+    };
+}