@phren/cli 0.0.10 → 0.0.12

package/README.md

@@ -5,10 +5,12 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/@phren/cli"><img src="https://img.shields.io/npm/v/%40phren%2Fcli?style=flat&labelColor=0D0D0D&color=7C3AED" alt="npm version"></a>
   <a href="https://github.com/alaarab/phren/blob/main/LICENSE"><img src="https://img.shields.io/github/license/alaarab/phren?style=flat&labelColor=0D0D0D&color=7C3AED" alt="license"></a>
+  <a href="https://alaarab.github.io/phren/"><img src="https://img.shields.io/badge/docs-alaarab.github.io%2Fphren-7C3AED?style=flat&labelColor=0D0D0D" alt="docs"></a>
+  <a href="https://alaarab.github.io/phren/whitepaper.pdf"><img src="https://img.shields.io/badge/whitepaper-PDF-7C3AED?style=flat&labelColor=0D0D0D" alt="whitepaper"></a>
 </p>
 
 <p align="center">
-Every time you start a new session, your AI agent forgets everything it learned. Phren fixes that — findings, decisions, and patterns persist as markdown in a git repo you control. No database, no hosted service, no vendor lock-in. Works across sessions, projects, and machines.
+Every time you start a new session, your AI agent forgets everything it learned. Phren fixes that. Findings, decisions, and patterns persist as markdown in a git repo you control. No database, no hosted service, no vendor lock-in.
 </p>
 
 ---
@@ -23,18 +25,18 @@ That single command creates `~/.phren`, wires up MCP, installs hooks, and gives
 
 ## What phren tracks
 
-- **Findings** — bugs hit, patterns discovered, decisions and their reasoning. Tagged by type (`[pattern]`, `[decision]`, `[pitfall]`, `[observation]`) with per-type decay rates
-- **Fragments** — named concepts (auth, build, React) that connect findings across projects. When you search for a topic, phren pulls in everything linked to that fragment
-- **Tasks** — work items that persist across sessions with priority, pinning, and GitHub issue linking
-- **Sessions** — conversation boundaries with summaries and checkpoints, so the next session picks up where this one left off
-- **Skills** — reusable slash commands you teach phren. Drop them in `~/.phren/global/skills/` and they work everywhere
+- **Findings**: bugs hit, patterns discovered, decisions and their reasoning. Tagged by type (`[pattern]`, `[decision]`, `[pitfall]`, `[observation]`) with per-type decay rates
+- **Fragments**: named concepts (auth, build, React) that connect findings across projects. Search for a topic and phren pulls in everything linked to that fragment
+- **Tasks**: work items that persist across sessions with priority, pinning, and GitHub issue linking
+- **Sessions**: conversation boundaries with summaries and checkpoints, so the next session picks up where the last one left off
+- **Skills**: reusable slash commands you teach phren. Drop them in `~/.phren/global/skills/` and they work everywhere
 
 ## How it works
 
 - **Surfaces relevant context on every prompt** via hooks. Agents build on what they know instead of starting fresh
-- **Trust scores decay over time** — old findings lose confidence. Decisions never decay. Observations expire in 14 days
+- **Trust scores decay over time.** Old findings lose confidence. Decisions never decay. Observations expire in 14 days
 - **Syncs across machines** through git push/pull. No coordination service
-- **Works with Claude Code, Copilot, Cursor, and Codex** — one memory, every agent
+- **Works with Claude Code, Copilot, Cursor, and Codex.** One store, every agent
 - **Shell and web UI** for browsing, searching, and triaging (`phren` or `phren web-ui`)
 
 ## Quick start
@@ -43,18 +45,10 @@ That single command creates `~/.phren`, wires up MCP, installs hooks, and gives
 npx @phren/cli init          # set up phren (interactive walkthrough)
 ```
 
-Init detects your tools, registers MCP servers, and installs lifecycle hooks. After it finishes, open a prompt in any tracked project — phren is already injecting context.
+Init detects your tools, registers MCP servers, and installs lifecycle hooks. After it finishes, open a prompt in any tracked project. Phren is already injecting context.
 
 To add a project later, run `phren add` from that directory. To browse what phren knows, run `phren` to open the interactive shell.
 
-## Learn more
-
-- [Documentation site](https://alaarab.github.io/phren/)
-- [Whitepaper (PDF)](https://alaarab.github.io/phren/whitepaper.pdf)
-- [Architecture](docs/architecture.md) — how retrieval, governance, and persistence fit together
-- [Contributing](CONTRIBUTING.md) — how to add tools, skills, and tests
-- [Security](SECURITY.md)
-
 ---
 
 MIT License. Made by [Ala Arab](https://github.com/alaarab).

package/mcp/dist/capabilities/cli.js

@@ -1,6 +1,6 @@
 export const cliManifest = {
     surface: "cli",
-    version: "1.31.1",
+    version: "0.0.12",
     actions: {
         // Finding management
         "finding.add": { implemented: true, handler: "cli-actions.ts:handleAddFinding" },

package/mcp/dist/capabilities/mcp.js

@@ -1,6 +1,6 @@
 export const mcpManifest = {
     surface: "mcp",
-    version: "1.31.1",
+    version: "0.0.12",
     actions: {
         // Finding management
         "finding.add": { implemented: true, handler: "index.ts:add_finding" },

package/mcp/dist/capabilities/vscode.js

@@ -1,6 +1,6 @@
 export const vscodeManifest = {
     surface: "vscode",
-    version: "1.31.1",
+    version: "0.0.12",
     actions: {
         // Finding management
         "finding.add": { implemented: true, handler: "extension.ts:phren.addFinding" },

package/mcp/dist/capabilities/web-ui.js

@@ -1,6 +1,6 @@
 export const webUiManifest = {
     surface: "web-ui",
-    version: "1.31.1",
+    version: "0.0.12",
     actions: {
         // Finding management
         "finding.add": { implemented: false, reason: "Web UI is read-only for findings (review queue only)" },

package/mcp/dist/cli-actions.js

@@ -14,35 +14,27 @@ import { runSearch, runFragmentSearch, parseFragmentSearchArgs, runRelatedDocs,
 import { resolveRuntimeProfile } from "./runtime-profile.js";
 import { getProjectConsolidationStatus, CONSOLIDATION_ENTRY_THRESHOLD } from "./content-validate.js";
 import { listAllSessions } from "./mcp-session.js";
-export async function handleSearch(opts, profile) {
-    const result = await runSearch(opts, getPhrenPath(), profile);
-    if (result.lines.length > 0) {
+async function runAndPrint(fn) {
+    const result = await fn();
+    if (result.lines.length > 0)
         console.log(result.lines.join("\n"));
-    }
     if (result.exitCode !== 0)
         process.exit(result.exitCode);
 }
+export async function handleSearch(opts, profile) {
+    await runAndPrint(() => runSearch(opts, getPhrenPath(), profile));
+}
 export async function handleFragmentSearch(args, profile) {
     const opts = parseFragmentSearchArgs(args);
     if (!opts)
         return;
-    const result = await runFragmentSearch(opts.query, getPhrenPath(), profile, opts);
-    if (result.lines.length > 0) {
-        console.log(result.lines.join("\n"));
-    }
-    if (result.exitCode !== 0)
-        process.exit(result.exitCode);
+    await runAndPrint(() => runFragmentSearch(opts.query, getPhrenPath(), profile, opts));
 }
 export async function handleRelatedDocs(args, profile) {
     const opts = parseRelatedDocsArgs(args);
     if (!opts)
         return;
-    const result = await runRelatedDocs(opts.entity, getPhrenPath(), profile, opts);
-    if (result.lines.length > 0) {
-        console.log(result.lines.join("\n"));
-    }
-    if (result.exitCode !== 0)
-        process.exit(result.exitCode);
+    await runAndPrint(() => runRelatedDocs(opts.entity, getPhrenPath(), profile, opts));
 }
 export async function handleAddFinding(project, learning) {
     if (!project || !learning) {
@@ -58,7 +50,7 @@ export async function handleAddFinding(project, learning) {
         console.log(result.message);
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
+        console.error(errorMessage(err));
         process.exit(1);
     }
 }
@@ -164,7 +156,7 @@ export async function handleDoctor(args) {
                         }
                     }
                     catch (err) {
-                        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                        if ((process.env.PHREN_DEBUG))
                             process.stderr.write(`[phren] doctor searchMissParse: ${errorMessage(err)}\n`);
                     }
                 }
@@ -181,44 +173,49 @@ export async function handleDoctor(args) {
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+        if ((process.env.PHREN_DEBUG))
             process.stderr.write(`[phren] doctor searchMissAnalysis: ${errorMessage(err)}\n`);
     }
+    const semStatus = await getSemanticSearchStatus(getPhrenPath(), profile || undefined);
+    if (!semStatus.ollamaUrl) {
+        console.log("- ok  semantic-search: disabled (optional; enable for fuzzy/paraphrase-heavy retrieval)");
+    }
+    else if (!semStatus.available) {
+        console.log(`- warn semantic-search: Ollama not running at ${semStatus.ollamaUrl} (start Ollama or set PHREN_OLLAMA_URL=off to disable)`);
+    }
+    else if (!semStatus.modelReady) {
+        console.log(`- warn semantic-search: model ${semStatus.model} not pulled (run: ollama pull ${semStatus.model})`);
+    }
+    else {
+        console.log(`- ok  semantic-search: ${semStatus.model} ready, ${semStatus.coverage}`);
+    }
+    process.exit(result.ok ? 0 : 1);
+}
+async function getSemanticSearchStatus(phrenPath, profile) {
     try {
         const { checkOllamaAvailable, checkModelAvailable, getOllamaUrl, getEmbeddingModel } = await import("./shared-ollama.js");
         const { getEmbeddingCache, formatEmbeddingCoverage } = await import("./shared-embedding-cache.js");
         const { listIndexedDocumentPaths } = await import("./shared-index.js");
         const ollamaUrl = getOllamaUrl();
-        if (!ollamaUrl) {
-            console.log("- ok  semantic-search: disabled (optional; enable for fuzzy/paraphrase-heavy retrieval)");
-        }
-        else {
-            const available = await checkOllamaAvailable();
-            if (!available) {
-                console.log(`- warn semantic-search: Ollama not running at ${ollamaUrl} (start Ollama or set PHREN_OLLAMA_URL=off to disable)`);
-            }
-            else {
-                const model = getEmbeddingModel();
-                const modelReady = await checkModelAvailable();
-                if (!modelReady) {
-                    console.log(`- warn semantic-search: model ${model} not pulled (run: ollama pull ${model})`);
-                }
-                else {
-                    const phrenPath = getPhrenPath();
-                    const cache = getEmbeddingCache(phrenPath);
-                    await cache.load().catch(() => { });
-                    const allPaths = listIndexedDocumentPaths(phrenPath, profile || undefined);
-                    const coverage = cache.coverage(allPaths);
-                    console.log(`- ok  semantic-search: ${model} ready, ${formatEmbeddingCoverage(coverage)}`);
-                }
-            }
-        }
+        if (!ollamaUrl)
+            return { ollamaUrl: null };
+        const available = await checkOllamaAvailable();
+        if (!available)
+            return { ollamaUrl, available: false };
+        const model = getEmbeddingModel();
+        const modelReady = await checkModelAvailable();
+        if (!modelReady)
+            return { ollamaUrl, available: true, modelReady: false, model };
+        const cache = getEmbeddingCache(phrenPath);
+        await cache.load().catch(() => { });
+        const coverage = formatEmbeddingCoverage(cache.coverage(listIndexedDocumentPaths(phrenPath, profile)));
+        return { ollamaUrl, available: true, modelReady: true, model, coverage };
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] doctor ollamaStatus: ${errorMessage(err)}\n`);
+        if ((process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] getSemanticSearchStatus: ${errorMessage(err)}\n`);
+        return { ollamaUrl: null, status: "error", error: errorMessage(err) };
     }
-    process.exit(result.ok ? 0 : 1);
 }
 export async function handleStatus() {
     const phrenPath = getPhrenPath();
@@ -231,34 +228,24 @@ export async function handleStatus() {
     console.log(`unsynced commits: ${runtime.lastSync?.unsyncedCommits ?? 0}`);
     if (runtime.lastSync?.lastPushDetail)
         console.log(`push detail: ${runtime.lastSync.lastPushDetail}`);
-    try {
-        const { getOllamaUrl, checkOllamaAvailable, checkModelAvailable, getEmbeddingModel } = await import("./shared-ollama.js");
-        const { getEmbeddingCache, formatEmbeddingCoverage } = await import("./shared-embedding-cache.js");
-        const { listIndexedDocumentPaths } = await import("./shared-index.js");
-        const ollamaUrl = getOllamaUrl();
-        if (!ollamaUrl) {
-            console.log("semantic-search: disabled (optional)");
-            return;
-        }
-        const available = await checkOllamaAvailable();
-        if (!available) {
-            console.log(`semantic-search: offline (${ollamaUrl})`);
-            return;
+    const semStatus = await getSemanticSearchStatus(phrenPath, profile || undefined);
+    if (!semStatus.ollamaUrl) {
+        const errStatus = semStatus;
+        if (errStatus.status === "error") {
+            console.log(`semantic-search: error (${errStatus.error ?? "unknown"})`);
         }
-        const model = getEmbeddingModel();
-        const modelReady = await checkModelAvailable();
-        if (!modelReady) {
-            console.log(`semantic-search: model missing (${model})`);
-            return;
+        else {
+            console.log("semantic-search: disabled (optional)");
         }
-        const cache = getEmbeddingCache(phrenPath);
-        await cache.load().catch(() => { });
-        const coverage = cache.coverage(listIndexedDocumentPaths(phrenPath, profile || undefined));
-        console.log(`semantic-search: ${model} ready, ${formatEmbeddingCoverage(coverage)}`);
     }
-    catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] handleStatus semanticSearch: ${errorMessage(err)}\n`);
+    else if (!semStatus.available) {
+        console.log(`semantic-search: offline (${semStatus.ollamaUrl})`);
+    }
+    else if (!semStatus.modelReady) {
+        console.log(`semantic-search: model missing (${semStatus.model})`);
+    }
+    else {
+        console.log(`semantic-search: ${semStatus.model} ready, ${semStatus.coverage}`);
     }
 }
 export async function handleQualityFeedback(args) {