protocontent 0.1.0 → 0.3.0

package/README.md

@@ -72,7 +72,15 @@ Each running bridge process owns one **space** — a DNS-safe id like
 lifetime. When `CLAUDE_SESSION_ID` is present the id is derived deterministically
 from it; otherwise it's random. A `spaceLabel` is derived from the current working
 directory's basename. Everything you publish in a session lands in the same space,
-served at `https://<spaceId>.protocontent.com`, which updates live.
+served at `https://<spaceId>.protocontent.app`, which updates live.
+
+### Keeping artifacts out of git
+
+protocontent artifacts are **ephemeral** — you publish them to a URL, you don't
+commit them. On startup the bridge makes a best-effort, idempotent check: if it's
+running inside a git repo, it ensures `.protocontent/` is in your `.gitignore`.
+Stage anything you publish under `.protocontent/` and it stays out of version
+control automatically. Opt out with `PROTOCONTENT_NO_GITIGNORE=1`.
 
 ## Tools
 

package/dist/config.js

@@ -1,7 +1,7 @@
 import { promises as fs } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { generateSpaceId, slugify } from "./util.js";
+import { generateSpaceId, slugify, ensureGitignore } from "./util.js";
 export const DEFAULT_API_BASE = "https://api.protocontent.com";
 /** Resolve the configured API base, trimming any trailing slash. */
 export function getApiBase() {
@@ -84,18 +84,134 @@ export async function resolveToken(apiBase) {
     const minted = await mintAnonymousToken(apiBase);
     return minted.token;
 }
+function spacesPath() {
+    return path.join(configDir(), "spaces.json");
+}
+async function readSpaces() {
+    try {
+        const raw = await fs.readFile(spacesPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+async function writeSpaces(map) {
+    await fs.mkdir(configDir(), { recursive: true, mode: 0o700 });
+    await fs.writeFile(spacesPath(), JSON.stringify(map, null, 2) + "\n", { mode: 0o600 });
+    try {
+        await fs.chmod(spacesPath(), 0o600);
+    }
+    catch {
+        // best effort
+    }
+}
+// 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,}$/;
 /**
- * Compute the per-process space id and label.
- * Seeded deterministically from CLAUDE_SESSION_ID when present so the
- * space lines up with the agent's thread; otherwise random.
+ * 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.
  */
-export function computeSpace() {
-    const seed = process.env.CLAUDE_SESSION_ID?.trim();
-    const spaceId = generateSpaceId(seed && seed.length > 0 ? seed : undefined);
+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 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() {
+    // 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 (pinned && pinned.length > 0) {
+        spaceId = slugify(pinned, "");
+        if (!spaceId)
+            spaceId = generateSpaceId();
+    }
+    else {
+        const map = await readSpaces();
+        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[projectKey] = spaceId;
+            await writeSpaces(map);
+        }
+    }
     let spaceLabel;
     try {
-        const base = path.basename(process.cwd());
-        const label = slugify(base, "");
+        const label = slugify(path.basename(projectKey), "");
         spaceLabel = label.length > 0 ? label : undefined;
     }
     catch {
@@ -107,6 +223,8 @@ export function computeSpace() {
 export async function loadConfig() {
     const apiBase = getApiBase();
     const token = await resolveToken(apiBase);
-    const { spaceId, spaceLabel } = computeSpace();
+    const { spaceId, spaceLabel } = await computeSpace();
+    // Keep ephemeral published artifacts out of git (best-effort, idempotent).
+    await ensureGitignore(process.env.CLAUDE_PROJECT_DIR || process.cwd());
     return { apiBase, token, spaceId, spaceLabel };
 }

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 = `https://${config.spaceId}.protocontent.com`;
+            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/dist/util.js

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { randomBytes, randomInt } from "node:crypto";
 import { promises as fs } from "node:fs";
 import * as path from "node:path";
 /**
@@ -90,32 +90,28 @@ const NOUNS = [
     "comet", "ember", "falcon", "heron", "lynx", "otter", "raven", "sparrow",
     "beacon", "compass", "lantern", "anchor", "pebble", "ripple", "breeze", "echo",
 ];
-function pick(arr, index) {
-    return arr[index % arr.length];
+const B32 = "abcdefghijklmnopqrstuvwxyz234567";
+/** A cryptographically-random DNS-safe token of `len` base32 chars (~5 bits each). */
+function randomToken(len) {
+    const bytes = randomBytes(len);
+    let out = "";
+    for (let i = 0; i < len; i++)
+        out += B32[bytes[i] & 31];
+    return out;
 }
 /**
- * Generate a DNS-safe space id of the form `word-word-xxx`
- * (e.g. `amber-canyon-7f3`). When `seed` is provided the result is
- * deterministic (so it lines up with an agent thread/session id);
- * otherwise it is random.
+ * Generate a DNS-safe space id like `quiet-harbor-3kf9q…` — two random words
+ * for a little readability, plus a 22-char crypto-random suffix (~110 bits).
+ *
+ * The id is the capability that grants access to a space, so it must be
+ * UNGUESSABLE and is never derived from anything public (e.g. the agent session
+ * id). Per-thread stability is handled by caching this random id in
+ * ~/.protocontent/spaces.json (see config.ts), NOT by seeding it.
  */
-export function generateSpaceId(seed) {
-    if (seed && seed.length > 0) {
-        const hash = createHash("sha256").update(seed).digest();
-        const adjIndex = hash.readUInt16BE(0);
-        const nounIndex = hash.readUInt16BE(2);
-        // 3-char base36 suffix derived from the next bytes.
-        const suffixNum = hash.readUInt32BE(4) % (36 * 36 * 36);
-        const suffix = suffixNum.toString(36).padStart(3, "0").slice(-3);
-        return `${pick(ADJECTIVES, adjIndex)}-${pick(NOUNS, nounIndex)}-${suffix}`;
-    }
-    const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
-    const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
-    const suffix = Math.floor(Math.random() * (36 * 36 * 36))
-        .toString(36)
-        .padStart(3, "0")
-        .slice(-3);
-    return `${adj}-${noun}-${suffix}`;
+export function generateSpaceId() {
+    const adj = ADJECTIVES[randomInt(ADJECTIVES.length)];
+    const noun = NOUNS[randomInt(NOUNS.length)];
+    return `${adj}-${noun}-${randomToken(22)}`;
 }
 const DEFAULT_SKIP_DIRS = new Set([
     "node_modules",
@@ -179,3 +175,56 @@ export function formatBytes(bytes) {
         return `${(bytes / 1024).toFixed(0)} KB`;
     return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
+// --- gitignore convention ---------------------------------------------------
+/**
+ * Best-effort: if `startDir` is inside a git repo, ensure `.protocontent/` is
+ * listed in the repo's .gitignore. protocontent artifacts are ephemeral — you
+ * publish them to a URL, you don't commit them — so staging them under
+ * `.protocontent/` keeps them out of version control automatically.
+ *
+ * Idempotent; silent on any failure; opt out with PROTOCONTENT_NO_GITIGNORE=1.
+ */
+export async function ensureGitignore(startDir = process.cwd()) {
+    if (process.env.PROTOCONTENT_NO_GITIGNORE)
+        return;
+    try {
+        // Walk up to the repo root (a directory containing .git).
+        let dir = path.resolve(startDir);
+        let root = null;
+        for (let i = 0; i < 40; i++) {
+            try {
+                await fs.stat(path.join(dir, ".git"));
+                root = dir;
+                break;
+            }
+            catch {
+                const parent = path.dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+        if (!root)
+            return; // not inside a git repo — nothing to do
+        const giPath = path.join(root, ".gitignore");
+        let content = "";
+        try {
+            content = await fs.readFile(giPath, "utf8");
+        }
+        catch {
+            // no .gitignore yet — appendFile will create it
+        }
+        const alreadyIgnored = content
+            .split(/\r?\n/)
+            .map((l) => l.trim())
+            .some((l) => l === ".protocontent/" || l === ".protocontent");
+        if (alreadyIgnored)
+            return;
+        const sep = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+        const block = `${sep}\n# protocontent — ephemeral published artifacts (not source)\n.protocontent/\n`;
+        await fs.appendFile(giPath, block);
+    }
+    catch {
+        // best effort — never fail a publish over this
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "protocontent",
-  "version": "0.1.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": {