@phren/cli 0.0.1

package/mcp/dist/telemetry.js

@@ -0,0 +1,165 @@
+import * as fs from "fs";
+import * as path from "path";
+import { runtimeDir } from "./shared.js";
+// In-memory buffers keyed by phrenPath to batch disk writes
+// Keeping per-path buffers avoids silently losing events when the active path changes.
+const buffers = new Map();
+const pendingCounts = new Map();
+const FLUSH_THRESHOLD = 10;
+function telemetryPath(phrenPath) {
+    return path.join(runtimeDir(phrenPath), "telemetry.json");
+}
+function loadFromDisk(phrenPath) {
+    const file = telemetryPath(phrenPath);
+    const defaults = {
+        config: { enabled: false },
+        stats: { toolCalls: {}, cliCommands: {}, errors: 0, sessions: 0, lastActive: "" },
+    };
+    if (!fs.existsSync(file))
+        return defaults;
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        return {
+            config: { ...defaults.config, ...raw.config },
+            stats: { ...defaults.stats, ...raw.stats },
+        };
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] telemetry loadFromDisk: ${err instanceof Error ? err.message : String(err)}\n`);
+        return defaults;
+    }
+}
+function loadTelemetry(phrenPath) {
+    const cached = buffers.get(phrenPath);
+    if (cached)
+        return cached;
+    const data = loadFromDisk(phrenPath);
+    buffers.set(phrenPath, data);
+    return data;
+}
+function saveTelemetry(phrenPath, data) {
+    buffers.set(phrenPath, data);
+    const pending = (pendingCounts.get(phrenPath) ?? 0) + 1;
+    pendingCounts.set(phrenPath, pending);
+    if (pending >= FLUSH_THRESHOLD) {
+        flushTelemetryForPath(phrenPath);
+    }
+}
+function flushTelemetryForPath(phrenPath) {
+    const data = buffers.get(phrenPath);
+    const pending = pendingCounts.get(phrenPath) ?? 0;
+    if (!data || pending === 0)
+        return;
+    const file = telemetryPath(phrenPath);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] telemetry flush: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    pendingCounts.set(phrenPath, 0);
+}
+export function flushTelemetry() {
+    for (const phrenPath of buffers.keys()) {
+        flushTelemetryForPath(phrenPath);
+    }
+}
+// Register flush on process exit
+let exitHookRegistered = false;
+function ensureExitHook() {
+    if (exitHookRegistered)
+        return;
+    exitHookRegistered = true;
+    process.on("exit", () => flushTelemetry());
+}
+export function isTelemetryEnabled(phrenPath) {
+    return loadTelemetry(phrenPath).config.enabled;
+}
+export function setTelemetryEnabled(phrenPath, enabled) {
+    const data = loadTelemetry(phrenPath);
+    data.config.enabled = enabled;
+    if (enabled && !data.config.enabledAt) {
+        data.config.enabledAt = new Date().toISOString();
+    }
+    // Config changes flush immediately
+    buffers.set(phrenPath, data);
+    pendingCounts.set(phrenPath, 1);
+    flushTelemetryForPath(phrenPath);
+}
+export function trackToolCall(phrenPath, toolName) {
+    const data = loadTelemetry(phrenPath);
+    if (!data.config.enabled)
+        return;
+    ensureExitHook();
+    data.stats.toolCalls[toolName] = (data.stats.toolCalls[toolName] || 0) + 1;
+    data.stats.lastActive = new Date().toISOString();
+    saveTelemetry(phrenPath, data);
+}
+export function trackCliCommand(phrenPath, command) {
+    const data = loadTelemetry(phrenPath);
+    if (!data.config.enabled)
+        return;
+    ensureExitHook();
+    data.stats.cliCommands[command] = (data.stats.cliCommands[command] || 0) + 1;
+    data.stats.lastActive = new Date().toISOString();
+    saveTelemetry(phrenPath, data);
+}
+export function trackError(phrenPath) {
+    const data = loadTelemetry(phrenPath);
+    if (!data.config.enabled)
+        return;
+    ensureExitHook();
+    data.stats.errors += 1;
+    saveTelemetry(phrenPath, data);
+}
+export function trackSession(phrenPath) {
+    const data = loadTelemetry(phrenPath);
+    if (!data.config.enabled)
+        return;
+    ensureExitHook();
+    data.stats.sessions += 1;
+    data.stats.lastActive = new Date().toISOString();
+    saveTelemetry(phrenPath, data);
+}
+export function getTelemetrySummary(phrenPath) {
+    const data = loadTelemetry(phrenPath);
+    if (!data.config.enabled)
+        return "Telemetry: disabled (opt in with 'phren config telemetry on')";
+    const topTools = Object.entries(data.stats.toolCalls)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, 5)
+        .map(([name, count]) => `  ${name}: ${count}`)
+        .join("\n");
+    const topCli = Object.entries(data.stats.cliCommands)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, 5)
+        .map(([name, count]) => `  ${name}: ${count}`)
+        .join("\n");
+    const lines = [
+        `Telemetry: enabled (since ${data.config.enabledAt || "unknown"})`,
+        `Sessions: ${data.stats.sessions}`,
+        `Errors: ${data.stats.errors}`,
+        `Last active: ${data.stats.lastActive || "never"}`,
+    ];
+    if (topTools)
+        lines.push("Top tools:", topTools);
+    if (topCli)
+        lines.push("Top CLI commands:", topCli);
+    return lines.join("\n");
+}
+export function resetTelemetry(phrenPath) {
+    const data = loadTelemetry(phrenPath);
+    data.stats = { toolCalls: {}, cliCommands: {}, errors: 0, sessions: 0, lastActive: "" };
+    // Reset flushes immediately
+    buffers.set(phrenPath, data);
+    pendingCounts.set(phrenPath, 1);
+    flushTelemetryForPath(phrenPath);
+}
+// Reset internal buffer state (for testing)
+export function _resetBuffer() {
+    buffers.clear();
+    pendingCounts.clear();
+}

package/mcp/dist/test-global-setup.js

@@ -0,0 +1,37 @@
+/**
+ * Vitest globalSetup — runs once in the main process before any test workers spawn.
+ *
+ * Builds mcp/dist if it is missing or stale so every fork sees a complete,
+ * consistent dist artifact. Running the build here (rather than inside each
+ * fork via ensureCliBuilt) eliminates the race condition where one fork runs
+ * `rm -rf mcp/dist` while another fork is checking fs.existsSync(CLI_PATH).
+ *
+ * `pretest` in package.json already calls `npm run build`, so in normal `npm test`
+ * runs this is a fast no-op check. It is the safety net for:
+ *   - `vitest run` called directly (no pretest hook)
+ *   - Watch mode re-runs where pretest does not re-fire
+ *   - CI environments that skip npm lifecycle scripts
+ */
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const REPO_ROOT = path.resolve(__dirname, "../..");
+const CLI_PATH = path.join(REPO_ROOT, "mcp", "dist", "index.js");
+export async function setup() {
+    if (fs.existsSync(CLI_PATH)) {
+        // Dist already present — skip build. This is the common path when
+        // `npm test` is used (pretest already built it) or during watch mode
+        // re-runs where the artifact is still fresh.
+        return;
+    }
+    process.stdout.write("[test-global-setup] mcp/dist missing — building...\n");
+    execFileSync("npm", ["run", "build"], {
+        cwd: REPO_ROOT,
+        stdio: "inherit",
+        timeout: 60_000,
+    });
+    process.stdout.write("[test-global-setup] build complete.\n");
+}

package/mcp/dist/tool-registry.js

@@ -0,0 +1,104 @@
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+const CATEGORY_BY_MODULE = {
+    "mcp-search": "Search and browse",
+    "mcp-tasks": "Task management",
+    "mcp-finding": "Finding capture",
+    "mcp-memory": "Memory quality",
+    "mcp-data": "Data management",
+    "mcp-graph": "Entities and graph",
+    "mcp-session": "Session management",
+    "mcp-ops": "Operations and review",
+    "mcp-skills": "Skills management",
+    "mcp-hooks": "Hooks management",
+    "mcp-extract": "Extraction",
+};
+const MODULE_ORDER = Object.keys(CATEGORY_BY_MODULE);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function decodeStringLiteral(raw) {
+    return raw
+        .replace(/\\"/g, "\"")
+        .replace(/\\'/g, "'")
+        .replace(/\\n/g, "\n")
+        .replace(/\\\\/g, "\\");
+}
+function sourceDir() {
+    return __dirname;
+}
+function parseModuleTools(moduleName, source) {
+    const tools = [];
+    const pattern = /registerTool\(\s*"([^"]+)"\s*,\s*\{([\s\S]*?)\}\s*,/g;
+    for (const match of source.matchAll(pattern)) {
+        const [, name, configBlock] = match;
+        const descMatch = configBlock.match(/description:\s*"((?:[^"\\]|\\.)*)"/s);
+        if (!descMatch)
+            continue;
+        const titleMatch = configBlock.match(/title:\s*"((?:[^"\\]|\\.)*)"/s);
+        tools.push({
+            name,
+            title: titleMatch ? decodeStringLiteral(titleMatch[1]) : undefined,
+            description: decodeStringLiteral(descMatch[1]).replace(/\s+/g, " ").trim(),
+            module: moduleName,
+            category: CATEGORY_BY_MODULE[moduleName] || "Other",
+        });
+    }
+    // Handle loop-registered tools: { tool: "name", ... } patterns followed by registerTool(action.tool, ...)
+    const loopPattern = /for\s*\(const\s+(\w+)\s+of\s+\[([\s\S]*?)\]\s*(?:as\s+const\s*)?\)\s*\{\s*server\.registerTool\(\s*\1\.tool\s*,\s*\{([\s\S]*?)\}\s*,/g;
+    for (const loopMatch of source.matchAll(loopPattern)) {
+        const [, , itemsBlock, configBlock] = loopMatch;
+        const itemPattern = /\{\s*tool:\s*"([^"]+)"[^}]*verb:\s*"([^"]+)"/g;
+        for (const itemMatch of itemsBlock.matchAll(itemPattern)) {
+            const [, toolName, verb] = itemMatch;
+            const descMatch = configBlock.match(/description:\s*`\$\{[\w.]+\}\s*(.*?)`/s);
+            const desc = descMatch ? `${verb} ${descMatch[1]}`.trim() : `${verb} operation`;
+            tools.push({
+                name: toolName,
+                description: desc,
+                module: moduleName,
+                category: CATEGORY_BY_MODULE[moduleName] || "Other",
+            });
+        }
+    }
+    return tools;
+}
+export function getRegisteredTools() {
+    const dir = sourceDir();
+    const entries = [];
+    for (const moduleName of MODULE_ORDER) {
+        const tsPath = path.join(dir, `${moduleName}.ts`);
+        const jsPath = path.join(dir, `${moduleName}.js`);
+        const sourcePath = fs.existsSync(tsPath) ? tsPath : jsPath;
+        if (!fs.existsSync(sourcePath))
+            continue;
+        entries.push(...parseModuleTools(moduleName, fs.readFileSync(sourcePath, "utf8")));
+    }
+    return entries;
+}
+export function getToolCount() {
+    return getRegisteredTools().length;
+}
+export function getToolsByCategory() {
+    const grouped = new Map();
+    for (const tool of getRegisteredTools()) {
+        const items = grouped.get(tool.category) || [];
+        items.push(tool);
+        grouped.set(tool.category, items);
+    }
+    return MODULE_ORDER
+        .map((moduleName) => CATEGORY_BY_MODULE[moduleName])
+        .filter((category, index, all) => all.indexOf(category) === index)
+        .map((category) => ({
+        category,
+        tools: (grouped.get(category) || []).sort((a, b) => a.name.localeCompare(b.name)),
+    }))
+        .filter((entry) => entry.tools.length > 0);
+}
+export function renderToolCatalogMarkdown() {
+    return getToolsByCategory()
+        .map(({ category, tools }) => {
+        const lines = tools.map((tool) => `- \`${tool.name}\`: ${tool.description}`);
+        return `**${category}:**\n${lines.join("\n")}`;
+    })
+        .join("\n\n");
+}

package/mcp/dist/update.js

@@ -0,0 +1,97 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync } from "child_process";
+import { fileURLToPath } from "url";
+import { errorMessage } from "./utils.js";
+import { PACKAGE_NAME, PACKAGE_SPEC } from "./package-metadata.js";
+function shellCommand(bin) {
+    return process.platform === "win32" ? `${bin}.cmd` : bin;
+}
+function packageRootFromRuntime() {
+    const current = fileURLToPath(import.meta.url);
+    return path.resolve(path.dirname(current), "..", "..");
+}
+function run(cmd, args, cwd) {
+    return execFileSync(cmd, args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: process.platform === "win32" && cmd.endsWith(".cmd"),
+        timeout: 180_000,
+    }).trim();
+}
+function cleanupStarterRefreshArtifacts(phrenPath) {
+    const runtimeRoot = path.join(phrenPath, ".runtime", "starter-updates");
+    if (!fs.existsSync(runtimeRoot))
+        return 0;
+    let removed = 0;
+    for (const entry of fs.readdirSync(runtimeRoot, { recursive: true })) {
+        const fullPath = path.join(runtimeRoot, String(entry));
+        if (!fs.existsSync(fullPath))
+            continue;
+        const stat = fs.statSync(fullPath);
+        if (!stat.isFile())
+            continue;
+        if (fullPath.endsWith(".new") || fullPath.endsWith(".current")) {
+            fs.unlinkSync(fullPath);
+            removed++;
+        }
+    }
+    return removed;
+}
+function maybeRefreshStarter(root, builtEntry, refreshStarter) {
+    if (!refreshStarter) {
+        return " Run `phren update --refresh-starter` to refresh global starter assets.";
+    }
+    run(process.execPath, [builtEntry, "init", "--apply-starter-update", "-y"], root);
+    const cleaned = cleanupStarterRefreshArtifacts(root);
+    return cleaned > 0
+        ? ` Refreshed starter assets and cleaned ${cleaned} staged starter artifact(s).`
+        : " Refreshed starter assets.";
+}
+export async function runPhrenUpdate(opts = {}) {
+    const root = packageRootFromRuntime();
+    const hasGit = fs.existsSync(path.join(root, ".git"));
+    const builtEntry = path.join(root, "mcp", "dist", "index.js");
+    if (hasGit) {
+        try {
+            // Warn if working tree is dirty (autostash handles it, but good to know)
+            try {
+                const status = run("git", ["status", "--porcelain"], root);
+                if (status) {
+                    process.stderr.write(`Note: uncommitted changes detected, autostash will preserve them.\n`);
+                }
+            }
+            catch (err) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] runPhrenUpdate gitStatus: ${errorMessage(err)}\n`);
+            }
+            const pull = run("git", ["pull", "--rebase", "--autostash"], root);
+            run(shellCommand("npm"), ["install"], root);
+            try {
+                run(shellCommand("npm"), ["run", "build"], root);
+                run(process.execPath, [builtEntry, "--health"], root);
+                const starterMessage = maybeRefreshStarter(root, builtEntry, Boolean(opts.refreshStarter));
+                return { ok: true, message: `Updated local phren repo at ${root}${pull ? ` (${pull})` : ""}.${starterMessage} Rebuilt and verified CLI health.` };
+            }
+            catch (err) {
+                const detail = errorMessage(err);
+                return { ok: false, message: `Local repo updated but rebuild/health check failed: ${detail}` };
+            }
+        }
+        catch (err) {
+            const detail = errorMessage(err);
+            return { ok: false, message: `Local repo update failed: ${detail}` };
+        }
+    }
+    try {
+        run(shellCommand("npm"), ["install", "-g", `${PACKAGE_NAME}@latest`]);
+        run(shellCommand("npm"), ["list", "-g", PACKAGE_NAME, "--depth=0"]);
+        const starterMessage = maybeRefreshStarter(root, builtEntry, Boolean(opts.refreshStarter));
+        return { ok: true, message: `Updated phren via npm global install (@latest) and verified the package is installed.${starterMessage}` };
+    }
+    catch (err) {
+        const detail = errorMessage(err);
+        return { ok: false, message: `Global update failed: ${detail}. Try manually: npm install -g ${PACKAGE_SPEC}` };
+    }
+}