@phren/cli 0.3.5 → 0.3.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -28307,7 +28307,7 @@ var init_package_metadata = __esm({
28307
28307
  __dirname = path24.dirname(fileURLToPath2(import.meta.url));
28308
28308
  ROOT = path24.join(__dirname, "..");
28309
28309
  PACKAGE_JSON_PATH = path24.join(ROOT, "package.json");
28310
- BUNDLED_VERSION = true ? "0.3.5" : "0.0.0";
28310
+ BUNDLED_VERSION = true ? "0.3.6" : "0.0.0";
28311
28311
  PACKAGE_JSON = readPackageJson();
28312
28312
  PACKAGE_NAME = PACKAGE_JSON.name || "phren";
28313
28313
  VERSION = PACKAGE_JSON.version || BUNDLED_VERSION;
@@ -50515,7 +50515,7 @@ async function readSecret(prompt) {
50515
50515
  // src/bridge/hook-main.ts
50516
50516
  init_utils_helpers();
50517
50517
  Object.assign(process.env, nonInteractiveGitEnv());
50518
- runBridge(process.argv.slice(2), "0.3.5").then((code) => {
50518
+ runBridge(process.argv.slice(2), "0.3.6").then((code) => {
50519
50519
  process.exitCode = code;
50520
50520
  }).catch((error62) => {
50521
50521
  console.error(error62 instanceof Error ? error62.message : "Phren Hook failed.");
@@ -4,6 +4,8 @@ export type TopLevelInvocation = {
4
4
  } | {
5
5
  kind: "mcp";
6
6
  phrenArg: string;
7
+ } | {
8
+ kind: "mcp-serve";
7
9
  } | {
8
10
  kind: "help";
9
11
  } | {
@@ -30,6 +30,9 @@ export function resolveTopLevelInvocation(argv) {
30
30
  if (looksLikePhrenRootArg(positional)) {
31
31
  return { kind: "mcp", phrenArg: positional };
32
32
  }
33
+ if (argvCommand === "mcp" && argv.length === 1) {
34
+ return { kind: "mcp-serve" };
35
+ }
33
36
  if (argvCommand === "--help" || argvCommand === "-h") {
34
37
  // `phren --help all` reads like `phren help all`, so it does the same.
35
38
  return argv.length > 1 ? { kind: "manage", argv } : { kind: "help" };
package/dist/index.js CHANGED
@@ -6,6 +6,7 @@ import { log as structuredLog, logger } from "./logger.js";
6
6
  import { errorMessage } from "./utils.js";
7
7
  import { nonInteractiveGitEnv } from "./utils-helpers.js";
8
8
  import { printIntegratedHelp, printIntegratedVersion, resolveTopLevelInvocation, runTopLevelCommand, } from "./entrypoint.js";
9
+ import { pluginSetupReason, runPluginSetupServer } from "./mcp/plugin-mode.js";
9
10
  // NOTE: the MCP-server-only module graph (MCP SDK, FTS indexer, tool registries,
10
11
  // startup-embedding, custom-hook engine) is intentionally NOT imported here. It is
11
12
  // dynamically imported inside main() so that top-level commands — hook-prompt,
@@ -30,7 +31,12 @@ if (invocation.kind === "manage") {
30
31
  }
31
32
  process.exit(process.exitCode ?? 0);
32
33
  }
33
- const phrenPath = findPhrenPathWithArg(invocation.phrenArg);
34
+ // `phren mcp` (the Claude Code plugin) with no store yet, or with `phren init`'s
35
+ // own server already registered, serves a small setup / empty server instead.
36
+ const pluginSetup = invocation.kind === "mcp-serve" ? pluginSetupReason() : null;
37
+ const phrenPath = pluginSetup
38
+ ? ""
39
+ : findPhrenPathWithArg(invocation.kind === "mcp" ? invocation.phrenArg : undefined);
34
40
  const STALE_LOCK_MS = 120_000; // 2 min — slightly above EXEC_TIMEOUT_MS (30s) to avoid blocking healthy writers
35
41
  function cleanStaleLocks(phrenPath) {
36
42
  const dir = runtimeDir(phrenPath);
@@ -342,7 +348,7 @@ async function main() {
342
348
  process.on("SIGTERM", () => void shutdown("SIGTERM"));
343
349
  process.on("SIGINT", () => void shutdown("SIGINT"));
344
350
  }
345
- main().catch((err) => {
351
+ (pluginSetup ? runPluginSetupServer(pluginSetup) : main()).catch((err) => {
346
352
  console.error("Failed to start phren-mcp:", err);
347
353
  process.exit(1);
348
354
  });
@@ -0,0 +1,16 @@
1
+ export type PluginSetupReason = "no-store" | "stand-down";
2
+ /**
3
+ * True when Claude Code will also load a user-level `phren` server that
4
+ * `phren init` registered. Claude Code reads user MCP servers from
5
+ * `.claude.json` (inside CLAUDE_CONFIG_DIR when set), not from settings.json,
6
+ * so an entry only in settings.json does not count.
7
+ */
8
+ export declare function userLevelPhrenMcpConfigured(env?: NodeJS.ProcessEnv): boolean;
9
+ /** Why `phren mcp` should not start the full server, or null when it should. */
10
+ export declare function pluginSetupReason(env?: NodeJS.ProcessEnv): PluginSetupReason | null;
11
+ export declare function setupMessage(): string;
12
+ export declare function runInitForPlugin(): {
13
+ ok: boolean;
14
+ output: string;
15
+ };
16
+ export declare function runPluginSetupServer(reason: PluginSetupReason): Promise<void>;
@@ -0,0 +1,106 @@
1
+ /**
2
+ * `phren mcp`: the MCP server as the Claude Code plugin starts it.
3
+ *
4
+ * The plugin cannot pass a store path (it does not know one), so `phren mcp`
5
+ * finds the store itself. Two cases then need something other than the full
6
+ * server:
7
+ *
8
+ * - no store yet (a plugin-only user on first run): a small server whose one
9
+ * tool explains setup and, once the user agrees, runs `phren init --yes`;
10
+ * - `phren init` already registered its own `phren` server for Claude Code and
11
+ * the plugin launched this one (PHREN_MCP_OWNER=plugin): an empty server, so
12
+ * the user does not see every phren tool twice.
13
+ */
14
+ import * as fs from "fs";
15
+ import * as path from "path";
16
+ import { spawnSync } from "child_process";
17
+ import { findPhrenPath, homePath } from "../phren-paths.js";
18
+ function hasPhrenServer(filePath) {
19
+ try {
20
+ const data = JSON.parse(fs.readFileSync(filePath, "utf8"));
21
+ return Boolean(data?.mcpServers && typeof data.mcpServers === "object" && data.mcpServers.phren);
22
+ }
23
+ catch {
24
+ return false;
25
+ }
26
+ }
27
+ /**
28
+ * True when Claude Code will also load a user-level `phren` server that
29
+ * `phren init` registered. Claude Code reads user MCP servers from
30
+ * `.claude.json` (inside CLAUDE_CONFIG_DIR when set), not from settings.json,
31
+ * so an entry only in settings.json does not count.
32
+ */
33
+ export function userLevelPhrenMcpConfigured(env = process.env) {
34
+ const configDir = env.CLAUDE_CONFIG_DIR?.trim();
35
+ return hasPhrenServer(configDir ? path.join(configDir, ".claude.json") : homePath(".claude.json"));
36
+ }
37
+ /** Why `phren mcp` should not start the full server, or null when it should. */
38
+ export function pluginSetupReason(env = process.env) {
39
+ if (env.PHREN_MCP_OWNER === "plugin" && userLevelPhrenMcpConfigured(env))
40
+ return "stand-down";
41
+ return findPhrenPath() ? null : "no-store";
42
+ }
43
+ const NO_STORE_INSTRUCTIONS = "phren gives this agent memory across sessions (findings, tasks, project context), but it has no store on this machine yet. " +
44
+ "When the user asks about phren or memory, call phren_setup to explain setup, and only call it with confirm=true after they agree.";
45
+ const STAND_DOWN_INSTRUCTIONS = "phren is already registered as its own MCP server by `phren init`; use that server's tools. This plugin copy stays empty so nothing appears twice.";
46
+ export function setupMessage() {
47
+ return [
48
+ "phren has no memory store on this machine yet.",
49
+ "",
50
+ "Setup runs `phren init --yes`, which:",
51
+ "- creates the store at ~/.phren (a local git repo; nothing leaves the machine unless you add a remote)",
52
+ "- registers phren's MCP server and memory hooks in ~/.claude/settings.json (the plugin's own copies then stand down)",
53
+ "- wires any other agents it detects (Codex, Copilot CLI, Cursor, VS Code)",
54
+ "",
55
+ "Ask the user before running it. Afterwards, Claude Code needs a restart to load the memory tools.",
56
+ ].join("\n");
57
+ }
58
+ export function runInitForPlugin() {
59
+ const entry = process.argv[1];
60
+ const result = spawnSync(process.execPath, [entry, "init", "--yes"], {
61
+ encoding: "utf8",
62
+ stdio: ["ignore", "pipe", "pipe"],
63
+ timeout: 180_000,
64
+ env: { ...process.env, PHREN_MCP_OWNER: "" },
65
+ });
66
+ const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
67
+ const tail = output.split("\n").slice(-25).join("\n");
68
+ return { ok: result.status === 0, output: tail || (result.error ? String(result.error) : "") };
69
+ }
70
+ export async function runPluginSetupServer(reason) {
71
+ const [{ McpServer }, { StdioServerTransport }, { z }, { VERSION }] = await Promise.all([
72
+ import("@modelcontextprotocol/sdk/server/mcp.js"),
73
+ import("@modelcontextprotocol/sdk/server/stdio.js"),
74
+ import("zod"),
75
+ import("../package-metadata.js"),
76
+ ]);
77
+ const server = new McpServer({ name: "phren-mcp", version: VERSION }, { instructions: reason === "no-store" ? NO_STORE_INSTRUCTIONS : STAND_DOWN_INSTRUCTIONS });
78
+ if (reason === "no-store") {
79
+ server.registerTool("phren_setup", {
80
+ title: "◆ phren · set up memory",
81
+ description: "phren has no memory store on this machine yet. Call without arguments to get what setup does; " +
82
+ "call with confirm=true, only after the user agrees, to run `phren init --yes` (creates ~/.phren and wires Claude Code). Restart Claude Code afterwards.",
83
+ inputSchema: z.object({
84
+ confirm: z.boolean().optional().describe("true runs setup now. Only after the user agreed."),
85
+ }),
86
+ }, async ({ confirm }) => {
87
+ if (!confirm)
88
+ return { content: [{ type: "text", text: setupMessage() }] };
89
+ const result = runInitForPlugin();
90
+ const next = result.ok
91
+ ? "\n\nphren is set up. Restart Claude Code so its memory tools and hooks load."
92
+ : "\n\nSetup failed. The user can run `npx -y @phren/cli init` in a terminal instead.";
93
+ return { content: [{ type: "text", text: `${result.output}${next}` }], isError: !result.ok };
94
+ });
95
+ }
96
+ else {
97
+ // An empty but well-formed tool list, so clients that list tools
98
+ // regardless of capabilities get [] rather than "method not found".
99
+ const { ListToolsRequestSchema } = await import("@modelcontextprotocol/sdk/types.js");
100
+ server.server.registerCapabilities({ tools: {} });
101
+ server.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [] }));
102
+ }
103
+ const transport = new StdioServerTransport();
104
+ await server.connect(transport);
105
+ console.error(`phren-mcp running in plugin ${reason} mode`);
106
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.3.5",
3
+ "version": "0.3.6",
4
4
  "description": "Knowledge layer for AI agents - CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-consolidate
3
- description: Find patterns across project findings and surface insights that apply everywhere.
3
+ description: Find patterns that repeat across several projects' phren findings and promote the ones that apply everywhere into shared global memory.
4
4
  dependencies:
5
5
  - git
6
6
  ---
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-discover
3
- description: Audit your phren repo and tell you exactly what needs attention.
3
+ description: Audit the phren memory store and report what needs attention, such as stale content, projects missing a summary, skill gaps and unhealthy task queues, with the top three things to fix.
4
4
  dependencies:
5
5
  - git
6
6
  - gh
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-init
3
- description: Set up a new project in phren with summary, AGENTS.md, task, and skill templates.
3
+ description: Set up phren memory. Creates the store with `phren init` on first use, or adds the current project to an existing store with its summary, AGENTS.md and task list. Use when phren reports no store or the user wants a project remembered.
4
4
  dependencies:
5
5
  - git
6
6
  ---
@@ -24,17 +24,15 @@ PHREN_DIR="${PHREN_DIR:-$HOME/.phren}"
24
24
  ls "$PHREN_DIR" 2>/dev/null
25
25
  ```
26
26
 
27
- If the phren directory doesn't exist, offer to create it:
28
- > "No phren repo found. Want me to create one at ~/.phren? This will set up the base directory structure (global/, profiles/, machines.yaml)."
27
+ If the phren directory doesn't exist, this is a first run. Offer to set phren up:
28
+ > "phren has no memory store on this machine yet. Want me to run `phren init`? It creates a local git-backed store at ~/.phren and registers phren's memory hooks and MCP server with Claude Code (and any other agents it finds). Nothing leaves this machine unless you add a git remote."
29
29
 
30
- If the user says yes, create the base structure:
30
+ If the user says yes, let the CLI build the store; never create it by hand:
31
31
  ```bash
32
- mkdir -p "$PHREN_DIR"/{global/skills,profiles}
33
- # Create a starter machines.yaml
34
- # Create a starter profile
32
+ if command -v phren >/dev/null 2>&1; then phren init --yes; else npx -y @phren/cli init --yes; fi
35
33
  ```
36
34
 
37
- Then continue with the project scaffolding below.
35
+ If phren's MCP server is running in setup mode it offers the same thing as the `phren_setup` tool (`confirm: true` runs it). Either way, tell the user to restart Claude Code afterwards so the memory tools and hooks load, then continue with the project scaffolding below if they named a project.
38
36
 
39
37
  ## With a project name
40
38
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-profiles
3
- description: Manage machine-to-profile and profile-to-project mappings in phren. Multi-machine users only.
3
+ description: Inspect or change which projects each machine loads from the phren store (machine-to-profile and profile-to-project mappings). Only for users who sync phren across several machines.
4
4
  dependencies:
5
5
  - git
6
6
  ---
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-summarize
3
- description: Write the "what we know" paragraph for each topic archive yourself, from the bullets phren hands you, using the model you are already running as. No API key, no local model.
3
+ description: Write the grounded "what we know" paragraph for each phren topic archive from the bullets phren provides, using the model already running. No API key or local model needed.
4
4
  ---
5
5
  # /phren-summarize
6
6
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: phren-sync
3
- description: Pull your phren store onto this machine or push local changes back. Thin wrapper around the CLI, which does the linking.
3
+ description: Pull the phren memory store onto this machine (and wire it with `phren init`) or push local memory changes to its git remote. Use on a new machine or when memory on another machine should catch up.
4
4
  dependencies:
5
5
  - git
6
6
  ---