@phren/cli 0.0.1

package/mcp/dist/cli-ops.js

@@ -0,0 +1,253 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync } from "child_process";
+import { EXEC_TIMEOUT_MS, findProjectNameCaseInsensitive, getPhrenPath, normalizeProjectNameForCreate, } from "./shared.js";
+import { isValidProjectName, errorMessage } from "./utils.js";
+import { readTasksAcrossProjects, TASKS_FILENAME } from "./data-access.js";
+import { applyGravity } from "./data-tasks.js";
+import { buildIndex, queryRows } from "./shared-index.js";
+import { resolveSubprocessArgs } from "./cli-hooks.js";
+import { listAllSessions, getSessionArtifacts } from "./mcp-session.js";
+export function handleTaskView(profile) {
+    const docs = readTasksAcrossProjects(getPhrenPath(), profile);
+    if (!docs.length) {
+        console.log("No tasks found.");
+        return;
+    }
+    let totalActive = 0;
+    let totalQueue = 0;
+    for (const doc of docs) {
+        const activeCount = doc.items.Active.length;
+        const queueCount = doc.items.Queue.length;
+        if (activeCount === 0 && queueCount === 0)
+            continue;
+        totalActive += activeCount;
+        totalQueue += queueCount;
+        console.log(`\n## ${doc.project}`);
+        if (activeCount > 0) {
+            console.log("  Active:");
+            const activeWithGravity = applyGravity(doc.items.Active).sort((a, b) => (a.rank ?? 0) - (b.rank ?? 0));
+            for (const item of activeWithGravity) {
+                const rankTag = item.rank !== undefined ? ` [#${item.rank}]` : "";
+                const github = item.githubIssue ? ` [gh:#${item.githubIssue}]` : item.githubUrl ? " [gh]" : "";
+                console.log(`    - ${item.line}${rankTag}${github}`);
+            }
+        }
+        if (queueCount > 0) {
+            console.log("  Queue:");
+            const queueWithGravity = applyGravity(doc.items.Queue).sort((a, b) => (a.rank ?? 0) - (b.rank ?? 0));
+            for (const item of queueWithGravity) {
+                const rankTag = item.rank !== undefined ? ` [#${item.rank}]` : "";
+                const github = item.githubIssue ? ` [gh:#${item.githubIssue}]` : item.githubUrl ? " [gh]" : "";
+                console.log(`    - ${item.line}${rankTag}${github}`);
+            }
+        }
+    }
+    if (totalActive === 0 && totalQueue === 0) {
+        console.log("All tasks are empty.");
+        return;
+    }
+    console.log(`\n${totalActive} active, ${totalQueue} queued across ${docs.length} project(s).`);
+}
+export function handleSessionsView(args) {
+    const phrenPath = getPhrenPath();
+    const sessionId = args[0];
+    if (sessionId) {
+        // Drill into a specific session
+        const sessions = listAllSessions(phrenPath, 200);
+        const session = sessions.find(s => s.sessionId === sessionId || s.sessionId.startsWith(sessionId));
+        if (!session) {
+            console.error(`Session "${sessionId}" not found.`);
+            process.exit(1);
+        }
+        const artifacts = getSessionArtifacts(phrenPath, session.sessionId);
+        console.log(`Session: ${session.sessionId.slice(0, 8)}`);
+        console.log(`Project: ${session.project ?? "—"}`);
+        console.log(`Started: ${session.startedAt.slice(0, 16).replace("T", " ")}`);
+        console.log(`Duration: ${session.durationMins ?? 0} min`);
+        console.log(`Status: ${session.status}`);
+        if (session.summary)
+            console.log(`Summary: ${session.summary}`);
+        if (artifacts.findings.length > 0) {
+            console.log(`\nFindings (${artifacts.findings.length}):`);
+            for (const f of artifacts.findings)
+                console.log(`  - [${f.project}] ${f.text}`);
+        }
+        if (artifacts.tasks.length > 0) {
+            console.log(`\nTasks (${artifacts.tasks.length}):`);
+            for (const t of artifacts.tasks)
+                console.log(`  - [${t.project}/${t.section}] ${t.text}`);
+        }
+        return;
+    }
+    // List all sessions
+    const sessions = listAllSessions(phrenPath, 50);
+    if (sessions.length === 0) {
+        console.log("No sessions found.");
+        return;
+    }
+    console.log("Sessions (newest first):\n");
+    for (const s of sessions) {
+        const id = s.sessionId.slice(0, 8);
+        const proj = s.project ?? "—";
+        const dur = s.durationMins != null ? `${s.durationMins}m` : "?";
+        const status = s.status === "active" ? " ●" : "";
+        const findings = s.findingsAdded > 0 ? ` ${s.findingsAdded}f` : "";
+        const date = s.startedAt.slice(0, 16).replace("T", " ");
+        const summary = s.summary ? `  ${s.summary.slice(0, 50)}` : "";
+        console.log(`  ${id}${status}  ${date}  ${dur}${findings}  ${proj}${summary}`);
+    }
+    console.log(`\n${sessions.length} session(s). Use \`phren sessions <id>\` to drill into one.`);
+}
+export async function handleQuickstart() {
+    const { runInit } = await import("./init.js");
+    const { runLink } = await import("./link.js");
+    const dirBasename = path.basename(process.cwd());
+    const readline = await import("readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const projectName = await new Promise((resolve) => {
+        rl.question(`Project name [${dirBasename}]: `, (answer) => {
+            rl.close();
+            resolve(answer.trim() || dirBasename);
+        });
+    });
+    const normalizedProjectName = normalizeProjectNameForCreate(projectName);
+    if (!isValidProjectName(normalizedProjectName)) {
+        console.error(`Error: invalid project name "${projectName}". Use lowercase letters, numbers, hyphens, or underscores.`);
+        return;
+    }
+    console.log(`\nInitializing phren for "${normalizedProjectName}"...\n`);
+    await runInit({ yes: true });
+    const phrenPath = getPhrenPath();
+    await runLink(phrenPath, {});
+    const existingProject = findProjectNameCaseInsensitive(phrenPath, normalizedProjectName);
+    if (existingProject && existingProject !== normalizedProjectName) {
+        console.error(`Error: project "${existingProject}" already exists with different casing. Refusing to create "${normalizedProjectName}" because it would split the same project on case-sensitive filesystems.`);
+        return;
+    }
+    const projectDir = path.join(phrenPath, normalizedProjectName);
+    if (!fs.existsSync(projectDir)) {
+        fs.mkdirSync(projectDir, { recursive: true });
+        fs.writeFileSync(path.join(projectDir, "FINDINGS.md"), `# ${normalizedProjectName} Findings\n`);
+        fs.writeFileSync(path.join(projectDir, TASKS_FILENAME), `# ${normalizedProjectName} Tasks\n\n## Active\n\n## Queue\n\n## Done\n`);
+    }
+    console.log(`\n\u2713 phren ready. Project: ${normalizedProjectName}. Try: phren search 'your query'`);
+}
+export async function handleDebugInjection(args, profile) {
+    let cwd = process.cwd();
+    let sessionId = `debug-${Date.now()}`;
+    const promptParts = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--cwd") {
+            cwd = args[++i] || cwd;
+            continue;
+        }
+        if (arg === "--session") {
+            sessionId = args[++i] || sessionId;
+            continue;
+        }
+        if (arg === "--prompt") {
+            promptParts.push(args[++i] || "");
+            continue;
+        }
+        promptParts.push(arg);
+    }
+    const prompt = promptParts.join(" ").trim();
+    if (!prompt) {
+        console.error('Usage: phren debug-injection --prompt "your prompt here" [--cwd <path>] [--session <id>]');
+        process.exit(1);
+    }
+    const subprocessArgs = resolveSubprocessArgs("hook-prompt");
+    if (!subprocessArgs) {
+        console.error("Could not resolve phren entrypoint for debug-injection.");
+        process.exit(1);
+    }
+    const payload = JSON.stringify({
+        prompt,
+        cwd,
+        session_id: sessionId,
+    });
+    try {
+        const out = execFileSync(process.execPath, subprocessArgs, {
+            cwd: process.cwd(),
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+            input: payload,
+            env: {
+                ...process.env,
+                PHREN_PATH: getPhrenPath(),
+                PHREN_PROFILE: profile,
+            },
+            timeout: EXEC_TIMEOUT_MS,
+        }).trim();
+        if (!out) {
+            console.log("(no context injected)");
+            return;
+        }
+        console.log(out);
+    }
+    catch (err) {
+        const stderr = err instanceof Error && "stderr" in err ? String(err.stderr || "").trim() : "";
+        if (stderr)
+            console.error(stderr);
+        console.error(`debug-injection failed: ${errorMessage(err)}`);
+        process.exit(1);
+    }
+}
+export async function handleInspectIndex(args, profile) {
+    let project;
+    let type;
+    let limit = 20;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--project") {
+            project = args[++i];
+            continue;
+        }
+        if (arg === "--type") {
+            type = args[++i];
+            continue;
+        }
+        if (arg === "--limit") {
+            const parsed = Number.parseInt(args[++i] || "", 10);
+            if (!Number.isNaN(parsed) && parsed > 0)
+                limit = Math.min(parsed, 200);
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            console.log("Usage: phren inspect-index [--project <name>] [--type <doc-type>] [--limit <n>]");
+            return;
+        }
+    }
+    const db = await buildIndex(getPhrenPath(), profile);
+    const where = [];
+    const params = [];
+    if (project) {
+        where.push("project = ?");
+        params.push(project);
+    }
+    if (type) {
+        where.push("type = ?");
+        params.push(type);
+    }
+    const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
+    const totalRows = queryRows(db, `SELECT count(*) FROM docs ${whereSql}`, params);
+    const total = Number(totalRows?.[0]?.[0] ?? 0);
+    console.log(`FTS index docs: ${total}`);
+    if (project)
+        console.log(`Project filter: ${project}`);
+    if (type)
+        console.log(`Type filter: ${type}`);
+    const sample = queryRows(db, `SELECT project, filename, type, path FROM docs ${whereSql} ORDER BY project, type, filename LIMIT ?`, [...params, limit]);
+    if (!sample || sample.length === 0) {
+        console.log("No rows for current filter.");
+        return;
+    }
+    console.log("");
+    for (const row of sample) {
+        const [proj, filename, docType, filePath] = row;
+        console.log(`- ${proj}/${filename} (${docType})`);
+        console.log(`  ${filePath}`);
+    }
+}

package/mcp/dist/cli-search.js

@@ -0,0 +1,407 @@
+import * as fs from "fs";
+import * as path from "path";
+import { runtimeFile } from "./shared.js";
+import { buildIndex, extractSnippet, queryDocRows, queryRows, queryEntityLinks, queryDocBySourceKey, logEntityMiss } from "./shared-index.js";
+import { buildFtsQueryVariants, errorMessage, isValidProjectName } from "./utils.js";
+import { keywordFallbackSearch } from "./core-search.js";
+const MAX_HISTORY = 20;
+const SEARCH_TYPE_ALIASES = {
+    skills: "skill",
+};
+const SEARCH_TYPES = new Set([
+    "claude",
+    "summary",
+    "findings",
+    "reference",
+    "task",
+    "changelog",
+    "canonical",
+    "memory-queue",
+    "skill",
+    "other",
+]);
+function historyFile(phrenPath) {
+    return runtimeFile(phrenPath, "search-history.jsonl");
+}
+export function readSearchHistory(phrenPath) {
+    const file = historyFile(phrenPath);
+    if (!fs.existsSync(file))
+        return [];
+    try {
+        return fs.readFileSync(file, "utf8")
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] readSearchHistory: ${errorMessage(err)}\n`);
+        return [];
+    }
+}
+function printSearchUsage() {
+    console.error("Usage:");
+    console.error("  phren search <query> [--project <name>] [--type <type>] [--limit <n>] [--all]");
+    console.error("  phren search --project <name> [--type <type>] [--limit <n>] [--all]");
+    console.error("  phren search --history                    Show recent searches");
+    console.error("  phren search --from-history <n>           Re-run search #n from history");
+    console.error("  type: claude|summary|findings|reference|task|changelog|canonical|memory-queue|skill|other");
+}
+function validateAndNormalizeSearchOptions(phrenPath, queryParts, project, type, limit, showHistory, fromHistory, searchAll) {
+    if (showHistory) {
+        return { query: "", limit, showHistory: true };
+    }
+    if (fromHistory !== undefined) {
+        const history = readSearchHistory(phrenPath);
+        if (fromHistory > history.length || fromHistory < 1) {
+            console.error(`No search at position ${fromHistory}. History has ${history.length} entries.`);
+            process.exit(1);
+        }
+        const entry = history[fromHistory - 1];
+        return {
+            query: entry.query,
+            limit,
+            project: entry.project,
+            type: entry.type,
+        };
+    }
+    if (project && !isValidProjectName(project)) {
+        console.error(`Invalid project name: "${project}"`);
+        process.exit(1);
+    }
+    let normalizedType;
+    if (type) {
+        normalizedType = SEARCH_TYPE_ALIASES[type.toLowerCase()] || type.toLowerCase();
+        if (!SEARCH_TYPES.has(normalizedType)) {
+            console.error(`Invalid --type value: "${type}"`);
+            printSearchUsage();
+            process.exit(1);
+        }
+    }
+    const query = queryParts.join(" ").trim();
+    if (!query && !project) {
+        console.error("Provide a query, or pass --project to browse a project's indexed docs.");
+        printSearchUsage();
+        process.exit(1);
+    }
+    return {
+        query,
+        limit,
+        project,
+        type: normalizedType,
+        searchAll,
+    };
+}
+export function parseSearchArgs(phrenPath, args) {
+    const queryParts = [];
+    let project;
+    let type;
+    let limit = 10;
+    let showHistory = false;
+    let fromHistory;
+    let searchAll = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            printSearchUsage();
+            return null;
+        }
+        if (arg === "--history") {
+            showHistory = true;
+            continue;
+        }
+        if (arg === "--all") {
+            limit = 100;
+            searchAll = true;
+            continue;
+        }
+        const [flag, inlineValue] = arg.startsWith("--") ? arg.split("=", 2) : [arg, undefined];
+        const readValue = () => {
+            if (inlineValue !== undefined)
+                return inlineValue;
+            const next = args[i + 1];
+            if (!next || next.startsWith("-")) {
+                console.error(`Missing value for ${flag}`);
+                printSearchUsage();
+                process.exit(1);
+            }
+            i++;
+            return next;
+        };
+        if (flag === "--project") {
+            project = readValue();
+            continue;
+        }
+        if (flag === "--type") {
+            type = readValue();
+            continue;
+        }
+        if (flag === "--limit") {
+            const parsed = Number.parseInt(readValue(), 10);
+            if (Number.isNaN(parsed) || parsed < 1 || parsed > 200) {
+                console.error("Invalid --limit value. Use an integer between 1 and 200.");
+                process.exit(1);
+            }
+            limit = parsed;
+            continue;
+        }
+        if (flag === "--from-history") {
+            const parsed = Number.parseInt(readValue(), 10);
+            if (Number.isNaN(parsed) || parsed < 1) {
+                console.error("Invalid --from-history value. Use a positive integer.");
+                process.exit(1);
+            }
+            fromHistory = parsed;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            console.error(`Unknown search flag: ${arg}`);
+            printSearchUsage();
+            process.exit(1);
+        }
+        queryParts.push(arg);
+    }
+    return validateAndNormalizeSearchOptions(phrenPath, queryParts, project, type, limit, showHistory, fromHistory, searchAll);
+}
+function recordSearchQuery(phrenPath, opts) {
+    if (!opts.query)
+        return;
+    const file = historyFile(phrenPath);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const entry = {
+        query: opts.query,
+        ...(opts.project && { project: opts.project }),
+        ...(opts.type && { type: opts.type }),
+        ts: new Date().toISOString(),
+    };
+    let entries = readSearchHistory(phrenPath);
+    entries.push(entry);
+    if (entries.length > MAX_HISTORY)
+        entries = entries.slice(-MAX_HISTORY);
+    fs.writeFileSync(file, entries.map((item) => JSON.stringify(item)).join("\n") + "\n");
+}
+function formatSearchHistoryLines(phrenPath) {
+    const entries = readSearchHistory(phrenPath);
+    if (!entries.length)
+        return ["No search history."];
+    const lines = ["Recent searches:", ""];
+    entries.forEach((entry, index) => {
+        const scope = [
+            entry.project ? `--project ${entry.project}` : "",
+            entry.type ? `--type ${entry.type}` : "",
+        ].filter(Boolean).join(" ");
+        const ts = entry.ts.slice(0, 16).replace("T", " ");
+        lines.push(`  ${index + 1}. "${entry.query}"${scope ? " " + scope : ""}  (${ts})`);
+    });
+    return lines;
+}
+export async function runSearch(opts, phrenPath, profile) {
+    if (opts.showHistory) {
+        return { lines: formatSearchHistoryLines(phrenPath), exitCode: 0 };
+    }
+    recordSearchQuery(phrenPath, opts);
+    const db = await buildIndex(phrenPath, profile);
+    try {
+        let sql = "SELECT project, filename, type, content, path FROM docs";
+        const where = [];
+        const params = [];
+        let queryVariants = [];
+        if (opts.query) {
+            queryVariants = buildFtsQueryVariants(opts.query, opts.project, phrenPath);
+            const safeQuery = queryVariants[0] ?? "";
+            if (!safeQuery) {
+                return { lines: ["Query empty after sanitization."], exitCode: 1 };
+            }
+            where.push("docs MATCH ?");
+            params.push(safeQuery);
+        }
+        if (opts.project) {
+            where.push("project = ?");
+            params.push(opts.project);
+        }
+        if (opts.type) {
+            where.push("type = ?");
+            params.push(opts.type);
+        }
+        if (where.length > 0) {
+            sql += ` WHERE ${where.join(" AND ")}`;
+        }
+        sql += opts.query ? " ORDER BY rank LIMIT ?" : " ORDER BY project, type, filename LIMIT ?";
+        params.push(opts.limit);
+        let rows = queryDocRows(db, sql, params);
+        if ((!rows || rows.length === 0) && queryVariants.length > 1) {
+            for (const variant of queryVariants.slice(1)) {
+                const relaxedParams = [...params];
+                relaxedParams[0] = variant;
+                rows = queryDocRows(db, sql, relaxedParams);
+                if (rows?.length)
+                    break;
+            }
+        }
+        const lines = [];
+        if (!rows && opts.query) {
+            const fallbackRows = keywordFallbackSearch(db, opts.query, { project: opts.project, type: opts.type, limit: opts.limit });
+            if (fallbackRows) {
+                rows = fallbackRows;
+                lines.push("(keyword fallback)");
+            }
+        }
+        if (!rows) {
+            if (opts.query) {
+                try {
+                    const { logSearchMiss } = await import("./mcp-search.js");
+                    logSearchMiss(phrenPath, opts.query, opts.project);
+                }
+                catch (err) {
+                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                        process.stderr.write(`[phren] search logSearchMiss: ${errorMessage(err)}\n`);
+                }
+            }
+            const scope = [
+                opts.query ? `query "${opts.query}"` : undefined,
+                opts.project ? `project "${opts.project}"` : undefined,
+                opts.type ? `type "${opts.type}"` : undefined,
+            ].filter(Boolean).join(", ");
+            return { lines: [scope ? `No results found for ${scope}.` : "No results found."], exitCode: 0 };
+        }
+        if (opts.project && !opts.query) {
+            lines.push(`Browsing ${rows.length} document(s) in project "${opts.project}"`);
+            if (opts.type)
+                lines.push(`Type filter: ${opts.type}`);
+            lines.push("");
+        }
+        for (const row of rows) {
+            const snippet = extractSnippet(row.content, opts.query, 7);
+            lines.push(`[${row.project}/${row.filename}] (${row.type})`);
+            lines.push(snippet);
+            lines.push("");
+        }
+        return { lines, exitCode: 0 };
+    }
+    catch (err) {
+        return { lines: [`Search error: ${errorMessage(err)}`], exitCode: 1 };
+    }
+}
+// ── Fragment search (parity with MCP search_fragments) ────────────────────
+export async function runFragmentSearch(query, phrenPath, profile, opts) {
+    if (!query.trim()) {
+        return { lines: ["Usage: phren search-fragments <query> [--project <name>] [--limit <n>]"], exitCode: 1 };
+    }
+    const db = await buildIndex(phrenPath, profile);
+    const max = opts.limit ?? 10;
+    const pattern = `%${query.toLowerCase()}%`;
+    let sql;
+    let params;
+    if (opts.project) {
+        sql = `
+      SELECT e.name, e.type, COUNT(el.source_id) as ref_count
+      FROM entities e
+      LEFT JOIN entity_links el ON el.target_id = e.id
+      WHERE e.name LIKE ? AND el.source_doc LIKE ?
+      GROUP BY e.id, e.name, e.type
+      ORDER BY ref_count DESC
+      LIMIT ?
+    `;
+        params = [pattern, `${opts.project}/%`, max];
+    }
+    else {
+        sql = `
+      SELECT e.name, e.type, COUNT(el.source_id) as ref_count
+      FROM entities e
+      LEFT JOIN entity_links el ON el.target_id = e.id
+      WHERE e.name LIKE ?
+      GROUP BY e.id, e.name, e.type
+      ORDER BY ref_count DESC
+      LIMIT ?
+    `;
+        params = [pattern, max];
+    }
+    const rows = queryRows(db, sql, params);
+    if (!rows || rows.length === 0) {
+        logEntityMiss(phrenPath, query, "cli_search_fragments", opts.project);
+        return { lines: [`No fragments matching "${query}".`], exitCode: 0 };
+    }
+    const lines = [`Fragments matching "${query}" (${rows.length} result(s)):\n`];
+    for (const r of rows) {
+        const name = String(r[0]);
+        const type = String(r[1]);
+        const refCount = Number(r[2]);
+        lines.push(`  ${name} (${type}) — ${refCount} reference(s)`);
+    }
+    return { lines, exitCode: 0 };
+}
+export function parseFragmentSearchArgs(args) {
+    const queryParts = [];
+    let project;
+    let limit;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            console.error("Usage: phren search-fragments <query> [--project <name>] [--limit <n>]");
+            return null;
+        }
+        if (arg === "--project" && args[i + 1]) {
+            project = args[++i];
+            continue;
+        }
+        if (arg === "--limit" && args[i + 1]) {
+            limit = Number.parseInt(args[++i], 10);
+            continue;
+        }
+        if (!arg.startsWith("-")) {
+            queryParts.push(arg);
+        }
+    }
+    return { query: queryParts.join(" "), project, limit };
+}
+// ── Related docs (parity with MCP get_related_docs) ───────────────────────
+export async function runRelatedDocs(entity, phrenPath, profile, opts) {
+    if (!entity.trim()) {
+        return { lines: ["Usage: phren related-docs <fragment-name> [--project <name>] [--limit <n>]"], exitCode: 1 };
+    }
+    const db = await buildIndex(phrenPath, profile);
+    const max = opts.limit ?? 10;
+    const links = queryEntityLinks(db, entity.toLowerCase());
+    let relatedDocs = links.related.filter(r => r.includes("/"));
+    if (opts.project) {
+        relatedDocs = relatedDocs.filter(d => d.startsWith(`${opts.project}/`));
+    }
+    relatedDocs = relatedDocs.slice(0, max);
+    if (relatedDocs.length === 0) {
+        logEntityMiss(phrenPath, entity, "cli_related_docs", opts.project);
+        return { lines: [`No docs found referencing fragment "${entity}".`], exitCode: 0 };
+    }
+    const lines = [`Docs referencing "${entity}" (${relatedDocs.length} result(s)):\n`];
+    for (const doc of relatedDocs) {
+        const docRow = queryDocBySourceKey(db, phrenPath, doc);
+        const snippet = docRow?.content ? docRow.content.slice(0, 120).replace(/\n/g, " ").trim() : "";
+        lines.push(`  [${doc}]`);
+        if (snippet)
+            lines.push(`    ${snippet}...`);
+    }
+    return { lines, exitCode: 0 };
+}
+export function parseRelatedDocsArgs(args) {
+    const entityParts = [];
+    let project;
+    let limit;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            console.error("Usage: phren related-docs <fragment-name> [--project <name>] [--limit <n>]");
+            return null;
+        }
+        if (arg === "--project" && args[i + 1]) {
+            project = args[++i];
+            continue;
+        }
+        if (arg === "--limit" && args[i + 1]) {
+            limit = Number.parseInt(args[++i], 10);
+            continue;
+        }
+        if (!arg.startsWith("-")) {
+            entityParts.push(arg);
+        }
+    }
+    return { entity: entityParts.join(" "), project, limit };
+}