@phren/cli 0.0.1

package/mcp/dist/shell-palette.js

@@ -0,0 +1,119 @@
+import { execFileSync } from "child_process";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { runLink } from "./link.js";
+import { runPhrenUpdate } from "./update.js";
+import { EXEC_TIMEOUT_MS, } from "./shared.js";
+export function resultMsg(r) {
+    if (!r.ok)
+        return r.error;
+    return typeof r.data === "string" ? r.data : JSON.stringify(r.data);
+}
+export function editDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1]
+                ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+export function tokenize(input) {
+    const out = [];
+    let current = "";
+    let quote = null;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if ((ch === '"' || ch === "'") && (!quote || quote === ch)) {
+            quote = quote ? null : ch;
+            continue;
+        }
+        if (!quote && /\s/.test(ch)) {
+            if (current) {
+                out.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += ch;
+    }
+    if (current)
+        out.push(current);
+    return out;
+}
+export function tasksByFilter(items, filter) {
+    const needle = filter.toLowerCase().trim();
+    if (!needle)
+        return items;
+    return items.filter((item) => `${item.id} ${item.line} ${item.context || ""} ${item.githubIssue ? `#${item.githubIssue}` : ""} ${item.githubUrl || ""}`.toLowerCase().includes(needle));
+}
+export function queueByFilter(items, filter) {
+    const needle = filter.toLowerCase().trim();
+    if (!needle)
+        return items;
+    return items.filter((item) => `${item.id} ${item.section} ${item.text}`.toLowerCase().includes(needle));
+}
+export function expandIds(input) {
+    const parts = input.split(",").map((s) => s.trim()).filter(Boolean);
+    const result = [];
+    for (const part of parts) {
+        const rangeMatch = part.match(/^([AQD])(\d+)-\1?(\d+)$/i);
+        if (rangeMatch) {
+            const prefix = rangeMatch[1].toUpperCase();
+            const start = Number.parseInt(rangeMatch[2], 10);
+            const end = Number.parseInt(rangeMatch[3], 10);
+            for (let i = Math.min(start, end); i <= Math.max(start, end); i++) {
+                result.push(`${prefix}${i}`);
+            }
+        }
+        else {
+            result.push(part);
+        }
+    }
+    return result;
+}
+export function normalizeSection(sectionRaw) {
+    const normalized = sectionRaw.toLowerCase();
+    if (["active", "a"].includes(normalized))
+        return "Active";
+    if (["queue", "queued", "q"].includes(normalized))
+        return "Queue";
+    if (["done", "d"].includes(normalized))
+        return "Done";
+    return null;
+}
+// ── Infrastructure ───────────────────────────────────────────────────────────
+export function resolveEntryScript() {
+    const current = fileURLToPath(import.meta.url);
+    return path.resolve(path.dirname(current), "index.js");
+}
+export async function defaultRunHooks(phrenPath) {
+    const entry = resolveEntryScript();
+    execFileSync(process.execPath, [entry, "hook-session-start"], {
+        cwd: phrenPath,
+        stdio: "ignore",
+        timeout: EXEC_TIMEOUT_MS,
+    });
+    execFileSync(process.execPath, [entry, "hook-stop"], {
+        cwd: phrenPath,
+        stdio: "ignore",
+        timeout: EXEC_TIMEOUT_MS,
+    });
+    return "Lifecycle hooks rerun (session-start + stop).";
+}
+export async function defaultRunUpdate() {
+    const result = await runPhrenUpdate();
+    return result.message;
+}
+export async function defaultRunRelink(phrenPath) {
+    await runLink(phrenPath, { register: false, allTools: true });
+    return "Relink completed for detected tools.";
+}

package/mcp/dist/shell-render.js

@@ -0,0 +1,252 @@
+// ── ANSI utilities ──────────────────────────────────────────────────────────
+const ESC = "\x1b[";
+export const RESET = `${ESC}0m`;
+export const style = {
+    bold: (s) => `${ESC}1m${s}${RESET}`,
+    dim: (s) => `${ESC}2m${s}${RESET}`,
+    italic: (s) => `${ESC}3m${s}${RESET}`,
+    cyan: (s) => `${ESC}36m${s}${RESET}`,
+    green: (s) => `${ESC}32m${s}${RESET}`,
+    yellow: (s) => `${ESC}33m${s}${RESET}`,
+    red: (s) => `${ESC}31m${s}${RESET}`,
+    magenta: (s) => `${ESC}35m${s}${RESET}`,
+    blue: (s) => `${ESC}34m${s}${RESET}`,
+    white: (s) => `${ESC}37m${s}${RESET}`,
+    gray: (s) => `${ESC}90m${s}${RESET}`,
+    boldCyan: (s) => `${ESC}1;36m${s}${RESET}`,
+    boldGreen: (s) => `${ESC}1;32m${s}${RESET}`,
+    boldYellow: (s) => `${ESC}1;33m${s}${RESET}`,
+    boldRed: (s) => `${ESC}1;31m${s}${RESET}`,
+    boldMagenta: (s) => `${ESC}1;35m${s}${RESET}`,
+    boldBlue: (s) => `${ESC}1;34m${s}${RESET}`,
+    dimItalic: (s) => `${ESC}2;3m${s}${RESET}`,
+    invert: (s) => `${ESC}7m${s}${RESET}`,
+};
+export function badge(label, colorFn) {
+    return colorFn(`[${label}]`);
+}
+export function separator(width = 50) {
+    return style.dim("━".repeat(Math.max(1, width)));
+}
+export function stripAnsi(s) {
+    return s.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "");
+}
+export function visibleWidth(s) {
+    return stripAnsi(s).length;
+}
+export function padToWidth(s, width) {
+    if (width <= 0)
+        return "";
+    if (width === 1)
+        return truncateLine(s, width);
+    const visible = stripAnsi(s);
+    if (visible.length > width)
+        return visible.slice(0, width - 1) + "…";
+    return s + " ".repeat(width - visible.length);
+}
+// ANSI handling: `s` may contain ANSI escape codes (styled text from the style.*
+// helpers). We measure visible width via stripAnsi, then if truncation is needed we
+// slice the *plain* text (discarding ANSI codes) to avoid cutting mid-escape. A
+// trailing reset is appended to guard against any residual SGR state from earlier
+// output on the same terminal line.
+export function truncateLine(s, cols) {
+    if (cols <= 0)
+        return "";
+    if (cols === 1)
+        return "…" + "\x1b[0m";
+    const visible = stripAnsi(s);
+    if (visible.length <= cols)
+        return s;
+    return visible.slice(0, cols - 1) + "…" + "\x1b[0m";
+}
+// Reserve one column to avoid terminal autowrap when a line exactly fills the width.
+// Many terminals wrap on the last visible column, which corrupts full-screen redraws.
+export function renderWidth(columns = process.stdout.columns || 80) {
+    return Math.max(1, columns - 1);
+}
+export function wrapSegments(segments, cols, opts = {}) {
+    const indent = opts.indent ?? "  ";
+    const maxLines = Math.max(1, opts.maxLines ?? Number.POSITIVE_INFINITY);
+    const separator = opts.separator ?? " ";
+    const indentWidth = visibleWidth(indent);
+    const available = Math.max(1, cols - indentWidth);
+    const lines = [];
+    let current = indent;
+    let currentWidth = indentWidth;
+    const pushEllipsis = () => {
+        const extraSep = currentWidth > indentWidth ? separator : "";
+        lines.push(truncateLine(current + extraSep + "…", cols));
+    };
+    for (const raw of segments) {
+        if (!raw)
+            continue;
+        const segment = truncateLine(raw, available);
+        const segmentWidth = visibleWidth(segment);
+        const separatorWidth = currentWidth > indentWidth ? visibleWidth(separator) : 0;
+        if (currentWidth > indentWidth && currentWidth + separatorWidth + segmentWidth > cols) {
+            if (lines.length + 1 >= maxLines) {
+                pushEllipsis();
+                return lines.join("\n");
+            }
+            lines.push(current);
+            current = indent + segment;
+            currentWidth = indentWidth + segmentWidth;
+            continue;
+        }
+        if (currentWidth > indentWidth) {
+            current += separator;
+            currentWidth += separatorWidth;
+        }
+        current += segment;
+        currentWidth += segmentWidth;
+    }
+    lines.push(current);
+    return lines.slice(0, maxLines).join("\n");
+}
+// ── Phren theme ────────────────────────────────────────────────────────────
+// Neural gradient palette: purple → blue → cyan (256-color ANSI)
+const PHREN_GRADIENT = [
+    "\x1b[38;5;93m", // vivid purple
+    "\x1b[38;5;99m", // purple-blue
+    "\x1b[38;5;105m", // blue-purple
+    "\x1b[38;5;111m", // sky blue
+    "\x1b[38;5;75m", // dodger blue
+    "\x1b[38;5;81m", // cyan-blue
+    "\x1b[38;5;87m", // bright cyan
+];
+// Apply gradient coloring across non-whitespace characters
+export function gradient(text, colors = PHREN_GRADIENT) {
+    const plain = stripAnsi(text);
+    const chars = [...plain];
+    const nonSpaceCount = chars.filter(ch => !/\s/.test(ch)).length;
+    if (!nonSpaceCount || !colors.length)
+        return text;
+    let result = "";
+    let vi = 0;
+    for (const ch of chars) {
+        if (/\s/.test(ch)) {
+            result += ch;
+        }
+        else {
+            const ci = Math.min(Math.floor(vi * colors.length / nonSpaceCount), colors.length - 1);
+            result += colors[ci] + ch;
+            vi++;
+        }
+    }
+    return result + RESET;
+}
+// Block-letter logo for startup animation
+const PHREN_LOGO = [
+    " ██████╗ ██████╗ ██████╗ ████████╗███████╗██╗  ██╗",
+    "██╔════╝██╔═══██╗██╔══██╗╚══██╔══╝██╔════╝╚██╗██╔╝",
+    "██║     ██║   ██║██████╔╝   ██║   █████╗   ╚███╔╝ ",
+    "██║     ██║   ██║██╔══██╗   ██║   ██╔══╝   ██╔██╗ ",
+    "╚██████╗╚██████╔╝██║  ██║   ██║   ███████╗██╔╝ ╚██╗",
+    " ╚═════╝ ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝",
+];
+// Compact phren character for startup (imported inline to avoid circular deps)
+const PHREN_STARTUP = [
+    "\x1b[96m        ✦\x1b[0m",
+    "\x1b[38;5;57m   ▄\x1b[35m██████\x1b[38;5;57m▄\x1b[0m",
+    "\x1b[35m  ██\x1b[95m▓▓\x1b[35m██\x1b[95m▓▓\x1b[35m██\x1b[0m",
+    "\x1b[35m  █\x1b[38;5;57m◆\x1b[35m██\x1b[38;5;57m◆\x1b[35m███\x1b[0m",
+    "\x1b[35m  ██\x1b[2m\x1b[35m▽\x1b[0m\x1b[35m████\x1b[95m█\x1b[0m",
+    "\x1b[38;5;57m   ▀\x1b[35m██████\x1b[38;5;57m▀\x1b[0m",
+    "\x1b[38;5;57m    ██  ██\x1b[0m",
+];
+// ── Line-based viewport: edge-triggered scroll (stable, no jumpiness) ─────────
+export function lineViewport(allLines, cursorFirstLine, cursorLastLine, height, prevStart) {
+    if (allLines.length === 0 || height <= 0)
+        return { lines: [], scrollStart: 0 };
+    if (allLines.length <= height)
+        return { lines: allLines.slice(), scrollStart: 0 };
+    const first = Math.max(0, Math.min(cursorFirstLine, allLines.length - 1));
+    const last = Math.max(first, Math.min(cursorLastLine, allLines.length - 1));
+    let start = Math.max(0, prevStart);
+    // Scroll up if cursor is above viewport
+    if (first < start)
+        start = first;
+    // Scroll down if cursor is below viewport
+    if (last >= start + height)
+        start = last - height + 1;
+    // Clamp
+    start = Math.min(start, Math.max(0, allLines.length - height));
+    return { lines: allLines.slice(start, start + height), scrollStart: start };
+}
+// ── Help text ────────────────────────────────────────────────────────────────
+export function shellHelpText() {
+    const hdr = (s) => style.bold(s);
+    const k = (s) => style.boldCyan(s);
+    const d = (s) => style.dim(s);
+    const cmd = (s) => style.cyan(s);
+    return [
+        "",
+        hdr("Navigation"),
+        `  ${k("← →")} ${d("switch tabs")}    ${k("↑ ↓")} ${d("move cursor")}    ${k("↵")} ${d("activate")}    ${k("q")} ${d("quit")}`,
+        `  ${k("/")} ${d("filter")}    ${k(":")} ${d("command palette")}    ${k("Esc")} ${d("cancel / clear filter")}    ${k("?")} ${d("toggle this help")}`,
+        "",
+        hdr("View-specific keys"),
+        `  ${style.bold("Projects")}     ${k("↵")} ${d("open project tasks")}  ${k("i")} ${d("cycle intro mode")}`,
+        `  ${style.bold("Tasks")}        ${k("a")} ${d("add task")}  ${k("d")} ${d("toggle active/queue")}  ${k("↵")} ${d("mark complete")}`,
+        `  ${style.bold("Fragments")}   ${k("a")} ${d("tell phren")}  ${k("d")} ${d("delete selected")}`,
+        `  ${style.bold("Review Queue")} ${k("a")} ${d("approve")}  ${k("r")} ${d("reject")}  ${k("e")} ${d("edit")}`,
+        `  ${style.bold("Skills")}       ${k("t")} ${d("toggle enabled")}  ${k("d")} ${d("remove")}`,
+        "",
+        hdr("Palette commands  (:cmd)"),
+        `  ${cmd(":open <project>")}                             ${d("set active project context")}`,
+        `  ${cmd(":add <task>")}                                 ${d("add task")}`,
+        `  ${cmd(":complete <id|match>")}                        ${d("mark done")}`,
+        `  ${cmd(":move <id|match> <active|queue|done>")}        ${d("move item")}`,
+        `  ${cmd(":reprioritize <id|match> <high|medium|low>")}`,
+        `  ${cmd(":context <id|match> <text>")}`,
+        `  ${cmd(":pin <id>")}  ${cmd(":unpin <id>")}  ${cmd(":work next")}  ${cmd(":tidy [keep]")}`,
+        `  ${cmd(":find add <text>")}  ${cmd(":find remove <id|match>")}`,
+        `  ${cmd(":intro always|once-per-version|off")}`,
+        `  ${cmd(":mq approve|reject|edit <id>")}`,
+        `  ${cmd(":govern")}  ${cmd(":consolidate")}  ${cmd(":search <query>")}`,
+        `  ${cmd(":undo")}  ${cmd(":diff")}  ${cmd(":conflicts")}  ${cmd(":reset")}`,
+        `  ${cmd(":run fix")}  ${cmd(":relink")}  ${cmd(":rerun hooks")}  ${cmd(":update")}`,
+        `  ${cmd(":machines")}`,
+    ].join("\n");
+}
+// ── Terminal control ──────────────────────────────────────────────────────────
+export function clearScreen() {
+    if (process.stdout.isTTY) {
+        // Move cursor to home and overwrite in place (no full clear = no flicker)
+        process.stdout.write("\x1b[H");
+    }
+}
+// Clear any leftover lines below the rendered content
+export function clearToEnd() {
+    if (process.stdout.isTTY) {
+        process.stdout.write("\x1b[J");
+    }
+}
+export function shellStartupFrames(version) {
+    const cols = process.stdout.columns || 80;
+    const tagline = style.dim("local memory for working agents");
+    const versionBadge = badge(`v${version}`, style.boldBlue);
+    if (cols >= 56) {
+        const logo = PHREN_LOGO.map(line => "  " + gradient(line));
+        const phren = PHREN_STARTUP.map(line => "  " + line);
+        const sep = gradient("━".repeat(Math.min(52, cols)));
+        return [
+            // Frame 1: Phren appears
+            ["", ...phren, "", `  ${versionBadge}  ${tagline}`, ""].join("\n"),
+            // Frame 2: Full logo materializes with phren
+            ["", ...phren, "", ...logo, "", `  ${versionBadge}  ${tagline}`, ""].join("\n"),
+            // Frame 3: Complete with brand separator
+            ["", ...phren, "", ...logo, `  ${sep}`, `  ${gradient("◆")} ${style.bold("phren")}  ${versionBadge}  ${tagline}`, ""].join("\n"),
+        ];
+    }
+    // Narrow terminal: progressive text reveal with gradient
+    const stages = ["c", "cor", "phren"];
+    const spinners = ["◜", "◠", "◝"];
+    return stages.map((stage, i) => [
+        "",
+        `  ${gradient(stage)} ${style.dim(spinners[i])}`,
+        "",
+        `  ${versionBadge}  ${tagline}`,
+        "",
+    ].join("\n"));
+}

package/mcp/dist/shell-state-store.js

@@ -0,0 +1,81 @@
+import * as fs from "fs";
+import * as path from "path";
+import { phrenErr, PhrenError, phrenOk, shellStateFile } from "./shared.js";
+import { getRuntimeHealth, withFileLock as withFileLockRaw } from "./shared-governance.js";
+import { errorMessage } from "./utils.js";
+function withSafeLock(filePath, fn) {
+    try {
+        return withFileLockRaw(filePath, fn);
+    }
+    catch (err) {
+        const msg = errorMessage(err);
+        if (msg.includes("could not acquire lock")) {
+            return phrenErr(`Could not acquire write lock for "${path.basename(filePath)}". Another write may be in progress; please retry.`, PhrenError.LOCK_TIMEOUT);
+        }
+        throw err;
+    }
+}
+const SHELL_STATE_VERSION = 3;
+const VALID_VIEWS = new Set(["Projects", "Tasks", "Findings", "Review Queue", "Skills", "Hooks", "Machines/Profiles", "Health"]);
+export function loadShellState(phrenPath) {
+    const file = shellStateFile(phrenPath);
+    const fallback = {
+        version: SHELL_STATE_VERSION,
+        view: "Projects",
+        page: 1,
+        perPage: 40,
+        introMode: "once-per-version",
+    };
+    if (!fs.existsSync(file))
+        return fallback;
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        const persistedView = VALID_VIEWS.has(raw.view)
+            ? raw.view
+            : fallback.view;
+        return {
+            version: SHELL_STATE_VERSION,
+            view: persistedView,
+            project: raw.project,
+            filter: raw.filter,
+            page: Number.isFinite(raw.page) ? Number(raw.page) : fallback.page,
+            perPage: Number.isFinite(raw.perPage) ? Number(raw.perPage) : fallback.perPage,
+            introMode: raw.introMode === "always" || raw.introMode === "off" ? raw.introMode : "once-per-version",
+            introSeenVersion: typeof raw.introSeenVersion === "string" ? raw.introSeenVersion : undefined,
+        };
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] loadShellState parse: ${errorMessage(err)}\n`);
+        return fallback;
+    }
+}
+export function saveShellState(phrenPath, state) {
+    const file = shellStateFile(phrenPath);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    withSafeLock(file, () => {
+        const out = {
+            version: SHELL_STATE_VERSION,
+            view: state.view,
+            project: state.project,
+            filter: state.filter,
+            page: state.page,
+            perPage: state.perPage,
+            introMode: state.introMode,
+            introSeenVersion: state.introSeenVersion,
+        };
+        fs.writeFileSync(file, JSON.stringify(out, null, 2) + "\n");
+        return phrenOk(undefined);
+    });
+}
+export function resetShellState(phrenPath) {
+    const file = shellStateFile(phrenPath);
+    return withSafeLock(file, () => {
+        if (fs.existsSync(file))
+            fs.unlinkSync(file);
+        return phrenOk("Shell state reset.");
+    });
+}
+export function readRuntimeHealth(phrenPath) {
+    return getRuntimeHealth(phrenPath);
+}

package/mcp/dist/shell-types.js

@@ -0,0 +1,13 @@
+// Projects is level 0 (the home screen); these sub-views are level 1 (drill-down into a project)
+// Health is NOT a sub-view — it's a global overlay accessible from anywhere via [h]
+export const SUB_VIEWS = ["Tasks", "Findings", "Review Queue", "Skills", "Hooks"];
+export const TAB_ICONS = {
+    Projects: "◉",
+    Tasks: "▤",
+    Findings: "✦",
+    "Review Queue": "◈",
+    Skills: "◆",
+    Hooks: "⚡",
+    Health: "♡",
+};
+export const MAX_UNDO_STACK = 10;

package/mcp/dist/shell-view-list.js

@@ -0,0 +1,14 @@
+import { RESET, padToWidth, truncateLine, lineViewport, style } from "./shell-render.js";
+export function formatSelectableLine(line, cols, selected) {
+    return selected
+        ? `\x1b[7m${padToWidth(line, cols)}${RESET}`
+        : truncateLine(line, cols);
+}
+export function viewportWithStatus(allLines, cursorFirstLine, cursorLastLine, usableHeight, previousScroll, currentIndex, totalItems) {
+    const vp = lineViewport(allLines, cursorFirstLine, cursorLastLine, Math.max(1, usableHeight), previousScroll);
+    if (allLines.length > usableHeight) {
+        const pct = totalItems <= 1 ? 100 : Math.round((currentIndex / Math.max(totalItems - 1, 1)) * 100);
+        vp.lines.push(style.dim(`  ━━━${currentIndex + 1}/${totalItems}  ${pct}%`));
+    }
+    return vp;
+}