protocontent 0.2.0 → 0.3.0

package/dist/config.js

@@ -109,37 +109,109 @@ async function writeSpaces(map) {
 }
 // A valid high-entropy space id: two words + a >=20-char base32 suffix.
 const NEW_SPACE_ID = /^[a-z]+-[a-z]+-[a-z2-7]{20,}$/;
+/**
+ * Resolve the stable PROJECT ROOT for a directory: the top of its git repo,
+ * shared across all worktrees of that repo, so the space stays the same whether
+ * you run in the main checkout or any worktree.
+ *
+ * Walks up looking for `.git`. A `.git` directory means we found the repo root.
+ * A `.git` *file* means this is a linked worktree — it points at
+ * `<mainRoot>/.git/worktrees/<name>`, so we recover `<mainRoot>` from it.
+ * Returns null if `startDir` is not inside a git repo.
+ */
+async function resolveProjectRoot(startDir) {
+    let dir = path.resolve(startDir);
+    for (let i = 0; i < 40; i++) {
+        const gitPath = path.join(dir, ".git");
+        try {
+            const stat = await fs.stat(gitPath);
+            if (stat.isDirectory())
+                return dir;
+            if (stat.isFile()) {
+                // Linked worktree: ".git" is a file like "gitdir: /abs/.git/worktrees/x".
+                try {
+                    const content = await fs.readFile(gitPath, "utf8");
+                    const m = content.match(/gitdir:\s*(.+)\s*$/m);
+                    if (m) {
+                        let gd = m[1].trim();
+                        if (!path.isAbsolute(gd))
+                            gd = path.resolve(dir, gd);
+                        const marker = `${path.sep}.git${path.sep}worktrees${path.sep}`;
+                        const idx = gd.indexOf(marker);
+                        if (idx >= 0)
+                            return gd.slice(0, idx); // the main repo root
+                    }
+                }
+                catch {
+                    // fall through to using this dir
+                }
+                return dir;
+            }
+        }
+        catch {
+            // no .git here — keep walking up
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
 /**
  * Compute the space id + label for this run.
  *
  * The space id is HIGH-ENTROPY RANDOM (~110 bits) — it's the capability that
- * grants access to a space, so it must be unguessable and is NOT derived from
- * anything public like the agent session id. For stability across bridge
- * restarts within the SAME agent thread, the random id is cached keyed by
- * CLAUDE_SESSION_ID in ~/.protocontent/spaces.json. Without a session id, each
- * process gets a fresh random space.
+ * grants access to a space, so it must be unguessable and is NEVER derived from
+ * anything public.
+ *
+ * It is cached so the SAME space is reused across bridge restarts, subagents,
+ * compaction, and resumed/renamed sessions — anything that would otherwise mint
+ * a fresh slug and orphan the links already shared. The cache key, in priority
+ * order:
+ *   1. PROTOCONTENT_SPACE_ID — explicit pin (advanced; used verbatim).
+ *   2. The git PROJECT ROOT (stable across worktrees of one repo).
+ *   3. CLAUDE_PROJECT_DIR, else the current working directory.
+ * The chosen id is persisted under that key in ~/.protocontent/spaces.json and a
+ * valid cached id is never silently regenerated. (Legacy entries keyed by
+ * CLAUDE_SESSION_ID are still honored and migrated to the project key.)
  */
 export async function computeSpace() {
-    const sessionKey = process.env.CLAUDE_SESSION_ID?.trim();
+    // 1. Explicit pin wins outright.
+    const pinned = process.env.PROTOCONTENT_SPACE_ID?.trim();
+    // 2/3. Resolve a stable project key.
+    const startDir = process.env.CLAUDE_PROJECT_DIR?.trim() || process.cwd();
+    const projectRoot = await resolveProjectRoot(startDir);
+    const projectKey = projectRoot || startDir;
     let spaceId;
-    if (sessionKey && sessionKey.length > 0) {
+    if (pinned && pinned.length > 0) {
+        spaceId = slugify(pinned, "");
+        if (!spaceId)
+            spaceId = generateSpaceId();
+    }
+    else {
         const map = await readSpaces();
-        const cached = map[sessionKey];
-        if (cached && NEW_SPACE_ID.test(cached)) {
-            spaceId = cached;
+        const sessionKey = process.env.CLAUDE_SESSION_ID?.trim();
+        const fromProject = map[projectKey];
+        const fromSession = sessionKey ? map[sessionKey] : undefined;
+        if (fromProject && NEW_SPACE_ID.test(fromProject)) {
+            spaceId = fromProject;
+        }
+        else if (fromSession && NEW_SPACE_ID.test(fromSession)) {
+            // Migrate a legacy session-keyed space onto the durable project key.
+            spaceId = fromSession;
+            map[projectKey] = spaceId;
+            await writeSpaces(map);
         }
         else {
             spaceId = generateSpaceId();
-            map[sessionKey] = spaceId;
+            map[projectKey] = spaceId;
             await writeSpaces(map);
         }
     }
-    else {
-        spaceId = generateSpaceId();
-    }
     let spaceLabel;
     try {
-        const label = slugify(path.basename(process.cwd()), "");
+        const label = slugify(path.basename(projectKey), "");
         spaceLabel = label.length > 0 ? label : undefined;
     }
     catch {

package/dist/index.js

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { artifactHistory, keepArtifact, listSpace, publish, unpublishArtifact, } from "./api.js";
+import { ApiError, artifactHistory, keepArtifact, listSpace, publish, unpublishArtifact, } from "./api.js";
 import { loadConfig } from "./config.js";
 import { contentTypeFromName, formatBytes, slugify, slugifyBasename, walkDir, } from "./util.js";
 // Safety rails for a single publish_folder call (not the abuse-limits feature).
@@ -23,31 +23,16 @@ function fmtTime(ms) {
         return "";
     return new Date(ms).toISOString().slice(0, 16).replace("T", " ") + " UTC";
 }
-/** Format an epoch-ms expiry as an absolute time plus a relative hint. */
-function fmtExpiry(ms) {
-    if (ms == null)
-        return "";
-    const days = Math.round((ms - Date.now()) / 86400000);
-    const rel = days <= 0 ? "soon" : days === 1 ? "in ~1 day" : `in ~${days} days`;
-    return `${fmtTime(ms)} (${rel})`;
-}
-/** Compose the standard human-readable success message every tool returns. */
+/**
+ * Compose the success message a publish tool returns. Deliberately terse: hand
+ * the agent the tappable link plus a one-line directive to share it plainly.
+ * No space/version/expiry chatter — that ceremony is what makes replies noisy.
+ */
 function publishMessage(what, res) {
-    const lines = [];
-    lines.push(`Published ${what} (v${res.version}).`);
-    // Always surface a tappable markdown link.
-    lines.push("");
-    lines.push(res.markdown);
-    lines.push("");
-    lines.push(`Live space (updates in real time): ${res.spaceUrl}`);
-    lines.push(`Direct URL: ${res.url}`);
-    if (res.expiresAt) {
-        lines.push(`Expires ${fmtExpiry(res.expiresAt)} — use \`keep\` to make it permanent.`);
-    }
-    else {
-        lines.push("This artifact has no expiry.");
-    }
-    return lines.join("\n");
+    return (`Published ${what}.\n\n` +
+        `${res.markdown}\n\n` +
+        `Share that link with the user in one short line. No emoji, no private/public ` +
+        `labels, no expiry notes — just the link.`);
 }
 async function main() {
     let config;
@@ -63,18 +48,25 @@ async function main() {
     process.stderr.write(`[protocontent] space ${config.spaceId}` +
         (config.spaceLabel ? ` (${config.spaceLabel})` : "") +
         ` -> ${config.apiBase}\n`);
-    const server = new McpServer({ name: "protocontent", version: "0.1.0" }, {
-        instructions: "Publish local files/folders to protocontent and get a shareable, live-updating URL. " +
-            "Each agent thread maps to one persistent 'space'. Use publish_html for a single file " +
-            "or inline content, publish_folder for a directory (e.g. a built site), and list/history/" +
-            "unpublish/keep to manage artifacts. Always show the returned markdown link to the user.",
+    const server = new McpServer({ name: "protocontent", version: "0.3.0" }, {
+        instructions: "Publish a local file or folder to protocontent and share its live link. Everything you " +
+            "publish lands in this thread's persistent 'space' and updates in place when you republish " +
+            "under the same name.\n\n" +
+            "WHEN TO PUBLISH: any self-contained, browser-openable artifact — HTML reports, plans, " +
+            "dashboards, prototypes, diagrams, screenshots, or a built static site. Never publish source " +
+            "code, secrets, or files meant to be committed.\n\n" +
+            "AFTER PUBLISHING: share the returned markdown link in ONE short line — no preamble, no " +
+            "emoji, no 'private vs public' explanation, no expiry notes. To update an artifact, publish " +
+            "again with the SAME `name` (same URL). The `list` tool returns the space index link that " +
+            "shows everything; surface it only when the user asks to see the whole collection.",
     });
     // --- publish_html ----------------------------------------------------------
     server.registerTool("publish_html", {
         title: "Publish a single file",
-        description: "Publish a single HTML (or other) file or inline content to this space and get a " +
-            "tappable, live URL. Provide exactly one of `path` (a file on disk) or `content` " +
-            "(inline text). The space page updates live as you republish.",
+        description: "Publish a single HTML (or other) file or inline content to this space and share its live " +
+            "link. Provide exactly one of `path` (a file on disk) or `content` (inline text; `html`/" +
+            "`body` accepted as aliases). To update an artifact, call again with the SAME `name` — it " +
+            "republishes in place at the same URL (don't invent a new name like plan-v2).",
         inputSchema: {
             path: z
                 .string()
@@ -84,6 +76,18 @@ async function main() {
                 .string()
                 .optional()
                 .describe("Inline file content to publish (alternative to `path`)."),
+            // `html`/`body` are accepted as aliases for `content`. The tool name is
+            // `publish_html`, so agents — especially when calling before the schema
+            // loads — reach for `html`. Accepting it makes the obvious guess work
+            // instead of failing with a confusing XOR error.
+            html: z
+                .string()
+                .optional()
+                .describe("Alias for `content` (inline file content)."),
+            body: z
+                .string()
+                .optional()
+                .describe("Alias for `content` (inline file content)."),
             name: z
                 .string()
                 .optional()
@@ -94,9 +98,15 @@ async function main() {
                 .describe("Optional time-to-live, e.g. '7d', '24h'. Omit for the default."),
         },
     }, async (args) => {
-        const { path: filePath, content, name, ttl } = args;
-        if ((filePath && content) || (!filePath && content === undefined)) {
-            return errorResult("Provide exactly one of `path` or `content`.");
+        const { path: filePath, name, ttl } = args;
+        // Coalesce the inline-content aliases into a single value.
+        const content = args.content ?? args.html ?? args.body;
+        if (filePath && content !== undefined) {
+            return errorResult("Provide exactly one of `path` or `content`, not both.");
+        }
+        if (!filePath && content === undefined) {
+            return errorResult("Provide either `content` (inline text, also accepted as `html`/`body`) " +
+                "or `path` (a file on disk).");
         }
         let bytes;
         let sourceName;
@@ -151,9 +161,9 @@ async function main() {
     // --- publish_folder --------------------------------------------------------
     server.registerTool("publish_folder", {
         title: "Publish a folder",
-        description: "Recursively publish a local directory (e.g. a built static site) to this space and " +
-            "get a tappable, live URL. Skips node_modules, .git, and dotfiles. The space page " +
-            "updates live as you republish.",
+        description: "Recursively publish a local directory (e.g. a built static site) to this space and share " +
+            "its live link. To update it, call again with the SAME `name` — it republishes in place at " +
+            "the same URL. Skips node_modules, .git, dist, and dotfiles.",
         inputSchema: {
             dir: z.string().describe("Path to the directory to publish."),
             entry: z
@@ -234,32 +244,33 @@ async function main() {
     // --- list ------------------------------------------------------------------
     server.registerTool("list", {
         title: "List artifacts in this space",
-        description: "List all artifacts published in this space, with their live URLs and versions.",
+        description: "List the artifacts in this space with their live links, plus the space index link that " +
+            "shows everything. Use it to recover an artifact's link, or to give the user the index page " +
+            "when they ask to see the whole collection.",
         inputSchema: {},
     }, async () => {
         try {
             const res = await listSpace(config);
             const spaceUrl = res.spaceUrl || `https://${config.spaceId}.protocontent.app`;
             if (!res.artifacts || res.artifacts.length === 0) {
-                return textResult(`No artifacts published yet in space ${config.spaceId}.\n` +
-                    `Space: ${spaceUrl}`);
+                return textResult("Nothing published in this space yet.");
             }
-            const lines = res.artifacts.map((a) => {
-                const exp = a.expiresAt ? ` — expires ${fmtExpiry(a.expiresAt)}` : " — no expiry";
-                return `- [${a.name} ↗](${a.url}) (v${a.version})${exp}`;
-            });
-            return textResult(`Artifacts in space ${config.spaceId}:\n` +
-                lines.join("\n") +
-                `\n\nLive space (updates in real time): ${spaceUrl}`);
+            const lines = res.artifacts.map((a) => `- [${a.name} ↗](${a.url})`);
+            return textResult(lines.join("\n") + `\n\nSpace index (shows everything): ${spaceUrl}`);
         }
         catch (err) {
+            // A space that has never been published to 404s — that's "empty", not an error.
+            if (err instanceof ApiError && err.status === 404) {
+                return textResult("Nothing published in this space yet.");
+            }
             return errorResult(`List failed: ${err.message}`);
         }
     });
     // --- history ---------------------------------------------------------------
     server.registerTool("history", {
         title: "Show an artifact's version history",
-        description: "Show the published version history of a named artifact in this space.",
+        description: "Show the published version history of a named artifact in this space (each republish under " +
+            "the same name is a new version).",
         inputSchema: {
             name: z.string().describe("Artifact name (slug) to show history for."),
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "protocontent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Co-located stdio MCP bridge for protocontent — read local files and publish them to the protocontent HTTP API.",
   "type": "module",
   "bin": {