protocontent 0.1.0 → 0.2.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,62 @@ 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.
+ * 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.
  */
-export function computeSpace() {
-    const seed = process.env.CLAUDE_SESSION_ID?.trim();
-    const spaceId = generateSpaceId(seed && seed.length > 0 ? seed : undefined);
+export async function computeSpace() {
+    const sessionKey = process.env.CLAUDE_SESSION_ID?.trim();
+    let spaceId;
+    if (sessionKey && sessionKey.length > 0) {
+        const map = await readSpaces();
+        const cached = map[sessionKey];
+        if (cached && NEW_SPACE_ID.test(cached)) {
+            spaceId = cached;
+        }
+        else {
+            spaceId = generateSpaceId();
+            map[sessionKey] = spaceId;
+            await writeSpaces(map);
+        }
+    }
+    else {
+        spaceId = generateSpaceId();
+    }
     let spaceLabel;
     try {
-        const base = path.basename(process.cwd());
-        const label = slugify(base, "");
+        const label = slugify(path.basename(process.cwd()), "");
         spaceLabel = label.length > 0 ? label : undefined;
     }
     catch {
@@ -107,6 +151,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

@@ -239,7 +239,7 @@ async function main() {
     }, 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}`);

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.2.0",
   "description": "Co-located stdio MCP bridge for protocontent — read local files and publish them to the protocontent HTTP API.",
   "type": "module",
   "bin": {