@phren/cli 0.1.13 → 0.1.14

package/dist/cli/session-background.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveSubprocessArgs(command: string): string[] | null;
+export declare function scheduleBackgroundSync(phrenPathLocal: string): boolean;
+export declare function scheduleBackgroundMaintenance(phrenPathLocal: string, project?: string): boolean;

package/dist/cli/session-background.js

@@ -0,0 +1,176 @@
+/**
+ * Background sync and maintenance scheduling.
+ * Extracted from hooks-session.ts for modularity.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { debugLog, errorMessage, runtimeFile, isFeatureEnabled, } from "./hooks-context.js";
+import { qualityMarkers } from "../shared.js";
+import { spawnDetachedChild } from "../shared/process.js";
+import { logger } from "../logger.js";
+const SYNC_LOCK_STALE_MS = 10 * 60 * 1000; // 10 minutes
+const MAINTENANCE_LOCK_STALE_MS = 2 * 60 * 60 * 1000; // 2 hours
+export function resolveSubprocessArgs(command) {
+    // Prefer the entry script that started this process
+    const entry = process.argv[1];
+    if (entry && fs.existsSync(entry) && /index\.(ts|js)$/.test(entry))
+        return [entry, command];
+    // Fallback: look for index.js next to this file or one level up (for subdirectory builds)
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    for (const dir of [thisDir, path.dirname(thisDir)]) {
+        const candidate = path.join(dir, "index.js");
+        if (fs.existsSync(candidate))
+            return [candidate, command];
+    }
+    return null;
+}
+export function scheduleBackgroundSync(phrenPathLocal) {
+    const lockPath = runtimeFile(phrenPathLocal, "background-sync.lock");
+    const logPath = runtimeFile(phrenPathLocal, "background-sync.log");
+    const spawnArgs = resolveSubprocessArgs("background-sync");
+    if (!spawnArgs)
+        return false;
+    try {
+        if (fs.existsSync(lockPath)) {
+            const ageMs = Date.now() - fs.statSync(lockPath).mtimeMs;
+            if (ageMs <= SYNC_LOCK_STALE_MS)
+                return false;
+            fs.unlinkSync(lockPath);
+        }
+    }
+    catch (err) {
+        debugLog(`scheduleBackgroundSync: lock check failed: ${errorMessage(err)}`);
+        return false;
+    }
+    try {
+        fs.writeFileSync(lockPath, JSON.stringify({ startedAt: new Date().toISOString(), pid: process.pid }) + "\n", { flag: "wx" });
+        const logFd = fs.openSync(logPath, "a");
+        fs.writeSync(logFd, `[${new Date().toISOString()}] spawn ${process.execPath} ${spawnArgs.join(" ")}\n`);
+        const child = spawnDetachedChild(spawnArgs, { phrenPath: phrenPathLocal, logFd });
+        child.unref();
+        fs.closeSync(logFd);
+        return true;
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch { }
+        debugLog(`scheduleBackgroundSync: spawn failed: ${errorMessage(err)}`);
+        return false;
+    }
+}
+export function scheduleBackgroundMaintenance(phrenPathLocal, project) {
+    if (!isFeatureEnabled("PHREN_FEATURE_DAILY_MAINTENANCE", true))
+        return false;
+    const markers = qualityMarkers(phrenPathLocal);
+    if (fs.existsSync(markers.done))
+        return false;
+    if (fs.existsSync(markers.lock)) {
+        try {
+            const ageMs = Date.now() - fs.statSync(markers.lock).mtimeMs;
+            if (ageMs <= MAINTENANCE_LOCK_STALE_MS)
+                return false;
+            fs.unlinkSync(markers.lock);
+        }
+        catch (err) {
+            debugLog(`maybeRunBackgroundMaintenance: lock check failed: ${errorMessage(err)}`);
+            return false;
+        }
+    }
+    const spawnArgs = resolveSubprocessArgs("background-maintenance");
+    if (!spawnArgs)
+        return false;
+    try {
+        // Use exclusive open (O_EXCL) to atomically claim the lock; if another process
+        // already holds it this throws and we return false without spawning a duplicate.
+        const lockContent = JSON.stringify({
+            startedAt: new Date().toISOString(),
+            project: project || "all",
+            pid: process.pid,
+        }) + "\n";
+        let fd;
+        try {
+            fd = fs.openSync(markers.lock, "wx");
+        }
+        catch (err) {
+            // Another process already claimed the lock
+            logger.debug("hooks-session", `backgroundMaintenance lockClaim: ${errorMessage(err)}`);
+            return false;
+        }
+        try {
+            fs.writeSync(fd, lockContent);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        if (project)
+            spawnArgs.push(project);
+        const logDir = path.join(phrenPathLocal, ".config");
+        fs.mkdirSync(logDir, { recursive: true });
+        const logPath = path.join(logDir, "background-maintenance.log");
+        const logFd = fs.openSync(logPath, "a");
+        fs.writeSync(logFd, `[${new Date().toISOString()}] spawn ${process.execPath} ${spawnArgs.join(" ")}\n`);
+        const child = spawnDetachedChild(spawnArgs, { phrenPath: phrenPathLocal, logFd });
+        child.on("exit", (code, signal) => {
+            const msg = `[${new Date().toISOString()}] exit code=${code ?? "null"} signal=${signal ?? "none"}\n`;
+            try {
+                fs.appendFileSync(logPath, msg);
+            }
+            catch (err) {
+                logger.debug("hooks-session", `backgroundMaintenance exitLog: ${errorMessage(err)}`);
+            }
+            if (code === 0) {
+                try {
+                    fs.writeFileSync(markers.done, new Date().toISOString() + "\n");
+                }
+                catch (err) {
+                    logger.debug("hooks-session", `backgroundMaintenance doneMarker: ${errorMessage(err)}`);
+                }
+            }
+            try {
+                fs.unlinkSync(markers.lock);
+            }
+            catch (err) {
+                logger.debug("hooks-session", `backgroundMaintenance unlockOnExit: ${errorMessage(err)}`);
+            }
+        });
+        child.on("error", (spawnErr) => {
+            const msg = `[${new Date().toISOString()}] spawn error: ${spawnErr.message}\n`;
+            try {
+                fs.appendFileSync(logPath, msg);
+            }
+            catch (err) {
+                logger.debug("hooks-session", `backgroundMaintenance errorLog: ${errorMessage(err)}`);
+            }
+            try {
+                fs.unlinkSync(markers.lock);
+            }
+            catch (err) {
+                logger.debug("hooks-session", `backgroundMaintenance unlockOnError: ${errorMessage(err)}`);
+            }
+        });
+        fs.closeSync(logFd);
+        child.unref();
+        return true;
+    }
+    catch (err) {
+        const errMsg = errorMessage(err);
+        try {
+            const logDir = path.join(phrenPathLocal, ".config");
+            fs.mkdirSync(logDir, { recursive: true });
+            fs.appendFileSync(path.join(logDir, "background-maintenance.log"), `[${new Date().toISOString()}] spawn failed: ${errMsg}\n`);
+        }
+        catch (err) {
+            logger.debug("hooks-session", `backgroundMaintenance logSpawnFailure: ${errorMessage(err)}`);
+        }
+        try {
+            fs.unlinkSync(markers.lock);
+        }
+        catch (err) {
+            logger.debug("hooks-session", `backgroundMaintenance unlockOnFailure: ${errorMessage(err)}`);
+        }
+        return false;
+    }
+}

package/dist/cli/session-git.d.ts

@@ -0,0 +1,17 @@
+export interface GitContext {
+    branch: string;
+    changedFiles: Set<string>;
+}
+export declare function getGitContext(cwd?: string): GitContext | null;
+export declare function runBestEffortGit(args: string[], cwd: string): Promise<{
+    ok: boolean;
+    output?: string;
+    error?: string;
+}>;
+export declare function countUnsyncedCommits(cwd: string): Promise<number>;
+export declare function recoverPushConflict(cwd: string): Promise<{
+    ok: boolean;
+    detail: string;
+    pullStatus: "ok" | "error";
+    pullDetail: string;
+}>;

package/dist/cli/session-git.js

@@ -0,0 +1,181 @@
+/**
+ * Git helpers for session hooks.
+ * Extracted from hooks-session.ts for modularity.
+ */
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { EXEC_TIMEOUT_MS, debugLog, errorMessage, } from "./hooks-context.js";
+import { runGit } from "../utils.js";
+import { isTaskFileName } from "../data/tasks.js";
+import { autoMergeConflicts, mergeTask, mergeFindings, } from "../shared/content.js";
+export function getGitContext(cwd) {
+    if (!cwd)
+        return null;
+    const git = (args) => runGit(cwd, args, EXEC_TIMEOUT_MS, debugLog);
+    const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (!branch)
+        return null;
+    const changedFiles = new Set();
+    for (const changed of [
+        git(["diff", "--name-only"]),
+        git(["diff", "--name-only", "--cached"]),
+    ]) {
+        if (!changed)
+            continue;
+        for (const line of changed.split("\n").map((s) => s.trim()).filter(Boolean)) {
+            changedFiles.add(line);
+            const basename = path.basename(line);
+            if (basename)
+                changedFiles.add(basename);
+        }
+    }
+    return { branch, changedFiles };
+}
+// ── Git command helpers ─────────────────────────────────────────────────────
+function isTransientGitError(message) {
+    return /(timed out|connection|network|could not resolve host|rpc failed|429|502|503|504|service unavailable)/i.test(message);
+}
+function shouldRetryGitCommand(args) {
+    const cmd = args[0] || "";
+    return cmd === "push" || cmd === "pull" || cmd === "fetch";
+}
+export async function runBestEffortGit(args, cwd) {
+    const retries = shouldRetryGitCommand(args) ? 2 : 0;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            const output = execFileSync("git", args, {
+                cwd,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+                timeout: EXEC_TIMEOUT_MS,
+            }).trim();
+            return { ok: true, output };
+        }
+        catch (err) {
+            const message = errorMessage(err);
+            if (attempt < retries && isTransientGitError(message)) {
+                const delayMs = 500 * (attempt + 1);
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+                continue;
+            }
+            return { ok: false, error: message };
+        }
+    }
+    return { ok: false, error: "git command failed" };
+}
+export async function countUnsyncedCommits(cwd) {
+    const upstream = await runBestEffortGit(["rev-parse", "--abbrev-ref", "@{upstream}"], cwd);
+    if (!upstream.ok || !upstream.output) {
+        const allCommits = await runBestEffortGit(["rev-list", "--count", "HEAD"], cwd);
+        if (!allCommits.ok || !allCommits.output)
+            return 0;
+        const parsed = Number.parseInt(allCommits.output.trim(), 10);
+        return Number.isNaN(parsed) ? 0 : parsed;
+    }
+    const ahead = await runBestEffortGit(["rev-list", "--count", `${upstream.output.trim()}..HEAD`], cwd);
+    if (!ahead.ok || !ahead.output)
+        return 0;
+    const parsed = Number.parseInt(ahead.output.trim(), 10);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+// ── Merge helpers ───────────────────────────────────────────────────────────
+function isMergeableMarkdown(relPath) {
+    const filename = path.basename(relPath).toLowerCase();
+    return filename === "findings.md" || isTaskFileName(filename);
+}
+async function snapshotLocalMergeableFiles(cwd) {
+    const upstream = await runBestEffortGit(["rev-parse", "--abbrev-ref", "@{upstream}"], cwd);
+    if (!upstream.ok || !upstream.output)
+        return new Map();
+    const changed = await runBestEffortGit(["diff", "--name-only", `${upstream.output.trim()}..HEAD`], cwd);
+    if (!changed.ok || !changed.output)
+        return new Map();
+    const snapshots = new Map();
+    for (const relPath of changed.output.split("\n").map((line) => line.trim()).filter(Boolean)) {
+        if (!isMergeableMarkdown(relPath))
+            continue;
+        const fullPath = path.join(cwd, relPath);
+        if (!fs.existsSync(fullPath))
+            continue;
+        snapshots.set(relPath, fs.readFileSync(fullPath, "utf8"));
+    }
+    return snapshots;
+}
+async function reconcileMergeableFiles(cwd, snapshots) {
+    let changedAny = false;
+    for (const [relPath, localBeforePull] of snapshots.entries()) {
+        const fullPath = path.join(cwd, relPath);
+        if (!fs.existsSync(fullPath))
+            continue;
+        const current = fs.readFileSync(fullPath, "utf8");
+        const filename = path.basename(relPath).toLowerCase();
+        const merged = filename === "findings.md"
+            ? mergeFindings(current, localBeforePull)
+            : mergeTask(current, localBeforePull);
+        if (merged === current)
+            continue;
+        fs.writeFileSync(fullPath, merged);
+        changedAny = true;
+    }
+    if (!changedAny)
+        return false;
+    const add = await runBestEffortGit(["add", "--", ...snapshots.keys()], cwd);
+    if (!add.ok)
+        return false;
+    const commit = await runBestEffortGit(["commit", "-m", "auto-merge markdown recovery"], cwd);
+    return commit.ok;
+}
+export async function recoverPushConflict(cwd) {
+    const localSnapshots = await snapshotLocalMergeableFiles(cwd);
+    const pull = await runBestEffortGit(["pull", "--rebase", "--quiet"], cwd);
+    if (pull.ok) {
+        const reconciled = await reconcileMergeableFiles(cwd, localSnapshots);
+        const retryPush = await runBestEffortGit(["push"], cwd);
+        return {
+            ok: retryPush.ok,
+            detail: retryPush.ok
+                ? (reconciled ? "commit pushed after pull --rebase and markdown reconciliation" : "commit pushed after pull --rebase")
+                : (retryPush.error || "push failed after pull --rebase"),
+            pullStatus: "ok",
+            pullDetail: pull.output || "pull --rebase ok",
+        };
+    }
+    const conflicted = await runBestEffortGit(["diff", "--name-only", "--diff-filter=U"], cwd);
+    const conflictedOutput = conflicted.output?.trim() || "";
+    if (!conflicted.ok || !conflictedOutput) {
+        await runBestEffortGit(["rebase", "--abort"], cwd);
+        return {
+            ok: false,
+            detail: pull.error || "pull --rebase failed",
+            pullStatus: "error",
+            pullDetail: pull.error || "pull --rebase failed",
+        };
+    }
+    if (!autoMergeConflicts(cwd)) {
+        await runBestEffortGit(["rebase", "--abort"], cwd);
+        return {
+            ok: false,
+            detail: `rebase conflicts require manual resolution: ${conflictedOutput}`,
+            pullStatus: "error",
+            pullDetail: `rebase conflicts require manual resolution: ${conflictedOutput}`,
+        };
+    }
+    const continued = await runBestEffortGit(["-c", "core.editor=true", "rebase", "--continue"], cwd);
+    if (!continued.ok) {
+        await runBestEffortGit(["rebase", "--abort"], cwd);
+        return {
+            ok: false,
+            detail: continued.error || "rebase --continue failed",
+            pullStatus: "error",
+            pullDetail: continued.error || "rebase --continue failed",
+        };
+    }
+    const retryPush = await runBestEffortGit(["push"], cwd);
+    return {
+        ok: retryPush.ok,
+        detail: retryPush.ok ? "commit pushed after auto-merge recovery" : (retryPush.error || "push failed after auto-merge recovery"),
+        pullStatus: "ok",
+        pullDetail: "pull --rebase recovered via auto-merge",
+    };
+}

package/dist/cli/session-metrics.d.ts

@@ -0,0 +1,2 @@
+import type { SelectedSnippet } from "../shared/retrieval.js";
+export declare function trackSessionMetrics(phrenPathLocal: string, sessionId: string, selected: SelectedSnippet[]): void;

package/dist/cli/session-metrics.js

@@ -0,0 +1,67 @@
+/**
+ * Session metrics tracking.
+ * Extracted from hooks-session.ts for modularity.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { debugLog, errorMessage, withFileLock, getQualityMultiplier, recordFeedback, } from "./hooks-context.js";
+import { sessionMetricsFile } from "../shared.js";
+function parseSessionMetrics(phrenPathLocal) {
+    const file = sessionMetricsFile(phrenPathLocal);
+    if (!fs.existsSync(file))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        debugLog(`parseSessionMetrics: failed to read ${file}: ${errorMessage(err)}`);
+        return {};
+    }
+}
+function writeSessionMetrics(phrenPathLocal, data) {
+    const file = sessionMetricsFile(phrenPathLocal);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+}
+function updateSessionMetrics(phrenPathLocal, updater) {
+    const file = sessionMetricsFile(phrenPathLocal);
+    withFileLock(file, () => {
+        const metrics = parseSessionMetrics(phrenPathLocal);
+        updater(metrics);
+        writeSessionMetrics(phrenPathLocal, metrics);
+    });
+}
+export function trackSessionMetrics(phrenPathLocal, sessionId, selected) {
+    updateSessionMetrics(phrenPathLocal, (metrics) => {
+        if (!metrics[sessionId])
+            metrics[sessionId] = { prompts: 0, keys: {}, lastChangedCount: 0, lastKeys: [] };
+        metrics[sessionId].prompts += 1;
+        const injectedKeys = [];
+        for (const injected of selected) {
+            injectedKeys.push(injected.key);
+            const key = injected.key;
+            const seen = metrics[sessionId].keys[key] || 0;
+            metrics[sessionId].keys[key] = seen + 1;
+            if (seen >= 1)
+                recordFeedback(phrenPathLocal, key, "reprompt");
+        }
+        const relevantCount = selected.filter((s) => getQualityMultiplier(phrenPathLocal, s.key) > 0.5).length;
+        const prevRelevant = metrics[sessionId].lastChangedCount || 0;
+        const prevKeys = metrics[sessionId].lastKeys || [];
+        if (relevantCount > prevRelevant) {
+            for (const prevKey of prevKeys) {
+                recordFeedback(phrenPathLocal, prevKey, "helpful");
+            }
+        }
+        metrics[sessionId].lastChangedCount = relevantCount;
+        metrics[sessionId].lastKeys = injectedKeys;
+        metrics[sessionId].lastSeen = new Date().toISOString();
+        const thirtyDaysAgo = Date.now() - 30 * 86400000;
+        for (const sid of Object.keys(metrics)) {
+            const seen = metrics[sid].lastSeen;
+            if (seen && new Date(seen).getTime() < thirtyDaysAgo) {
+                delete metrics[sid];
+            }
+        }
+    });
+}

package/dist/cli/session-start.d.ts

@@ -0,0 +1,3 @@
+export declare function getUntrackedProjectNotice(phrenPath: string, cwd: string): string | null;
+export declare function getSessionStartOnboardingNotice(phrenPath: string, cwd: string, activeProject: string | null): string | null;
+export declare function handleHookSessionStart(): Promise<void>;