@prom.codes/saver 0.1.3 → 0.1.5

package/README.md

@@ -9,30 +9,32 @@ caveats and destructive sequences **verbatim**.
 It is the third prom.codes tool, alongside **prom.codes Context** (code retrieval)
 and **prom.codes Memory** (agent memory).
 
-## Quick start
-
-```jsonc
-// Claude Desktop / Cursor MCP config
-{
-  "mcpServers": {
-    "saver": {
-      "command": "npx",
-      "args": ["-y", "@prom.codes/saver@latest"],
-      "env": { "PROMETHEUS_WORKSPACE_ROOT": "/absolute/path/to/your/repo" }
-    }
-  }
-}
+## Quick start (Claude Code)
+
+```bash
+claude mcp add saver -- npx -y @prom.codes/saver@latest
 ```
 
+No key needed. `claude mcp add` defaults to local scope; add `--scope project`
+for a committable `.mcp.json`. Other hosts (Cursor, VS Code) use the same
+command/args in their own config.
+
 Then ask your agent to run `setup` once per workspace. Levels: `lite` (filler
 only), `balanced` (default — lean, not terse), `aggressive` (telegraphic, opt-in,
 never for code/destructive work). The rules keep code, caveats, destructive steps
 and anything the agent needs later **verbatim** — it shapes phrasing, never what the
 agent does or remembers.
 
+A second tool, `status`, reports where it would write, the key state, and which
+runtimes already have the block installed. If a fresh window opens with no
+project (workspace falls back to home), `setup` **refuses to write rule files
+into your home dir** — open your project folder first.
+
 No database and no native modules — `npx` works turnkey everywhere (Node ≥ 20.10).
-An API key is **optional**: Saver works fully without one, and accepts the same
-`PROMETHEUS_API_KEY` (`prom_live_…`) as prom.codes Context and Memory to tie the
-install to your account.
+The workspace is auto-detected (Claude Code `CLAUDE_PROJECT_DIR`); set
+`PROMETHEUS_WORKSPACE_ROOT` only to target a different folder. An API key is
+**optional**: the Saver works fully without one, and accepts the same
+`PROMETHEUS_API_KEY` (`prom_live_<tag>_<secret>`) as prom.codes Context and
+Memory to tie the install to your account.
 
-Docs: https://prom.codes/docs
+Docs: https://prom.codes/docs/mcp/saver

package/dist/bin.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 // dist/bin.js
-import { resolve } from "node:path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // dist/key.js
@@ -14,13 +13,36 @@ function classifyKey(raw) {
   return KEY_PATTERN.test(key) ? "valid" : "malformed";
 }
 
+// dist/workspace.js
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+function isHomeOrFilesystemRoot(root) {
+  const abs = resolve(root);
+  if (abs === "")
+    return true;
+  if (abs === resolve(homedir()))
+    return true;
+  if (dirname(abs) === abs)
+    return true;
+  return false;
+}
+function resolveWorkspaceRoot(env = process.env) {
+  const explicit = (env.PROMETHEUS_WORKSPACE_ROOT ?? "").trim();
+  if (explicit !== "")
+    return resolve(explicit);
+  const claude = (env.CLAUDE_PROJECT_DIR ?? "").trim();
+  if (claude !== "")
+    return resolve(claude);
+  return resolve(process.cwd());
+}
+
 // dist/tools.js
 import { z } from "zod";
 
 // dist/setup.js
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname as dirname2, join } from "node:path";
 var SAVER_LEVELS = ["lite", "balanced", "aggressive"];
 var DEFAULT_LEVEL = "balanced";
 var SAVER_RUNTIMES = [
@@ -83,6 +105,18 @@ function detectRuntimes(workspaceRoot) {
   const found = SAVER_RUNTIMES.filter((rt) => existsSync(join(workspaceRoot, TARGETS[rt].detect)));
   return found.length > 0 ? found : ["agents"];
 }
+function installedRuntimes(workspaceRoot) {
+  return SAVER_RUNTIMES.filter((rt) => {
+    const p = join(workspaceRoot, TARGETS[rt].relPath);
+    if (!existsSync(p))
+      return false;
+    try {
+      return readFileSync(p, "utf-8").includes(BLOCK_START);
+    } catch {
+      return false;
+    }
+  });
+}
 function upsertBlock(existing, block) {
   const marked = withMarkers(block);
   const start = existing.indexOf(BLOCK_START);
@@ -103,7 +137,7 @@ async function installRuntime(workspaceRoot, runtime, level) {
   if (exists && before === after) {
     return { runtime, path: absPath, action: "unchanged" };
   }
-  await mkdir(dirname(absPath), { recursive: true });
+  await mkdir(dirname2(absPath), { recursive: true });
   await writeFile(absPath, after, "utf-8");
   return { runtime, path: absPath, action: exists ? "updated" : "created" };
 }
@@ -119,14 +153,24 @@ var setupInput = {
   level: levelEnum.optional(),
   runtimes: z.array(runtimeEnum).min(1).optional()
 };
+var emptyInput = {};
 function registerTools(server, deps) {
   const { workspaceRoot, apiKey, requireKey } = deps;
   const keyState = deps.keyState ?? (apiKey !== void 0 ? "valid" : "absent");
+  const rootIsHomeOrFsRoot = isHomeOrFilesystemRoot(workspaceRoot);
   server.registerTool("setup", {
     title: "Install the prom.codes Saver efficient-output rules",
     description: "Idempotently install the prom.codes Saver efficient-output rule block into this workspace's agent runtime configs (CLAUDE.md / .cursor/rules / .augment/rules / AGENTS.md). The rules cut token cost by trimming the agent's own prose (preamble, narration, pasted tool output) while keeping code, caveats and destructive sequences verbatim. `level`: `lite` (filler only) | `balanced` (default \u2014 lean, not terse) | `aggressive` (telegraphic, opt-in, never for code/destructive). Without `runtimes` it auto-detects which are present (fallback: agents). Re-running updates the block in place. Run this once per workspace.",
     inputSchema: setupInput
   }, async (args) => {
+    if (rootIsHomeOrFsRoot) {
+      return textResult({
+        ok: false,
+        installed: false,
+        workspaceRoot,
+        reason: "Workspace resolved to your home directory or a filesystem root \u2014 refusing to write rule files there. Open your project folder (Claude Code passes it via CLAUDE_PROJECT_DIR) or set PROMETHEUS_WORKSPACE_ROOT, then retry."
+      });
+    }
     if (requireKey === true && keyState !== "valid") {
       return {
         isError: true,
@@ -157,6 +201,24 @@ function registerTools(server, deps) {
       results
     });
   });
+  server.registerTool("status", {
+    title: "Saver status / health check",
+    description: "Health check for the prom.codes Saver in this workspace: the resolved workspace root, whether the API key is present/valid (optional \u2014 the Saver works keyless), which agent runtimes are detected here, and which of them already have the Saver rule block installed. Call this to confirm where it would write and whether `setup` has already run.",
+    inputSchema: emptyInput
+  }, async () => {
+    const detected = detectRuntimes(workspaceRoot);
+    const installed = rootIsHomeOrFsRoot ? [] : installedRuntimes(workspaceRoot);
+    const summary = rootIsHomeOrFsRoot ? `Workspace resolved to ${workspaceRoot} (home/root) \u2014 setup is refused here. Open your project folder.` : installed.length > 0 ? `Saver installed in ${workspaceRoot} for: ${installed.join(", ")}.` : `Saver not yet installed in ${workspaceRoot}. Run setup. Detected runtimes: ${detected.join(", ")}.`;
+    return textResult({
+      installed: installed.length > 0,
+      workspaceRoot,
+      rootIsHomeOrFsRoot,
+      key: { keyed: apiKey !== void 0, keyState, requireKey: requireKey === true },
+      detectedRuntimes: detected,
+      installedRuntimes: installed,
+      summary
+    });
+  });
 }
 
 // dist/server.js
@@ -180,7 +242,7 @@ function createServer(deps, options = {}) {
 
 // dist/bin.js
 async function main() {
-  const workspaceRoot = resolve(process.env.PROMETHEUS_WORKSPACE_ROOT ?? process.cwd());
+  const workspaceRoot = resolveWorkspaceRoot(process.env);
   const rawKey = process.env[API_KEY_ENV];
   const keyState = classifyKey(rawKey);
   const requireKey = /^(1|true|yes|on)$/i.test(process.env[REQUIRE_KEY_ENV] ?? "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prom.codes/saver",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "prom.codes Saver — cut token cost without cutting quality, as an MCP installer.",
   "type": "module",
   "bin": {