@magic-markdown/cli 0.3.11 → 0.3.12

package/dist/index.js

@@ -10997,7 +10997,7 @@ var RemoteDocumentIO = class {
 };
 
 // src/agent.ts
-var CLI_VERSION = "0.3.11";
+var CLI_VERSION = "0.3.12";
 var CLI_PACKAGE_NAME = "@magic-markdown/cli";
 var AGENT_COMMANDS = [
   {
@@ -11279,6 +11279,23 @@ var AGENT_COMMANDS = [
       "--token (or MDOCS_BRIDGE_TOKEN) still works when a scoped bridge token is already available."
     ]
   },
+  {
+    name: "bridge resume",
+    summary: "Backfill missed Magic changes after an agent restart, then keep the bridge running.",
+    usage: "mdocs bridge resume --root <path> [--url <base-url>] [--workspace <id>] [--root-id <id>] [--request-token] [--once]",
+    output: "long-running",
+    mutates: true,
+    examples: [
+      "mdocs bridge resume --root . --request-token",
+      "mdocs bridge resume --root . --once --request-token"
+    ],
+    notes: [
+      "Reads non-secret connection defaults from .mdocs/bridge.json written by bridge setup.",
+      "Use this after a sandbox/container/agent session restarts. It backfills canonical Magic changes before publishing local edits.",
+      "--request-token opens a human approval URL when no MDOCS_BRIDGE_TOKEN is available; do not ask users to paste bridge tokens by default.",
+      "--once performs only the backfill/reconcile step and exits."
+    ]
+  },
   {
     name: "bridge",
     summary: "Sync a local Markdown root with a Magic workspace over WebSocket (long-running).",
@@ -11347,6 +11364,32 @@ Run \`mdocs help <command>\` (or \`mdocs <command> --help\`) for usage, examples
 5. For a document, run \`mdocs context <path|docId> --summary --json\` locally or \`mdocs remote context <path|docId> --summary --json\` for a joined share before reading full content. Then page Markdown with \`--start-line\` / \`--end-line\` and \`--no-review\` when you only need document text.
 6. Pull review state separately with \`mdocs review <path|docId> --json\` locally or \`mdocs remote review <path|docId> --json\` for a joined share. Use \`mdocs comment\` / \`mdocs remote comment\` for review notes and \`mdocs suggest\` / \`mdocs remote suggest\` for proposed replacements. Do not insert comments, CriticMarkup, directives, or Magic markers into Markdown files.
 
+## Filesystem Bridge / Resume
+
+When a human asks you to bind an editable local Markdown filesystem to Magic Markdown, use the latest official package and the human-approval token flow:
+
+\`\`\`bash
+npx --yes --package=@magic-markdown/cli@latest mdocs bridge setup \\
+  --root . \\
+  --workspace <workspace-id> \\
+  --root-id <root-id> \\
+  --url <magic-url> \\
+  --actor-name "<agent name>" \\
+  --request-token
+\`\`\`
+
+Return the Magic approval link and keep the bridge process running after approval. Success looks like \`mdocs bridge connected ...\`.
+
+If your sandbox, container, terminal, or agent session restarts after setup, do not ask for a raw bridge token. Start the latest CLI again and resume from the same root:
+
+\`\`\`bash
+npx --yes --package=@magic-markdown/cli@latest mdocs bridge resume --root . --request-token
+\`\`\`
+
+\`bridge resume\` reads non-secret defaults from \`.mdocs/bridge.json\`, backfills missed Magic changes before publishing local edits, and then keeps polling/watching. Use \`--once\` only when the user asked for a one-shot backfill rather than a live bridge.
+
+If Magic and the local root both changed the same document while you were offline, the bridge keeps the Magic canonical path, saves your local divergent version as a \`.conflict-...\` Markdown copy, and lets the conflict copy sync as a normal file. If Magic reports a server-side conflict, wait for the human to resolve it in Magic Markdown before retrying content pushes.
+
 ## Editing Rules
 
 - Comments and suggestions are sidecar operations. They should not modify clean Markdown until a suggestion is accepted.
@@ -13402,6 +13445,7 @@ function optionalFolderTarget(value) {
 // src/bridge.ts
 import { createHash as createHash2, randomUUID as randomUUID3 } from "node:crypto";
 import { basename as basename2, resolve as resolve4 } from "node:path";
+var BRIDGE_CONFIG_PATH = ".mdocs/bridge.json";
 function bridgeSetupIdentity(input) {
   const actorName = input.actorName?.trim() || "Agent";
   return {
@@ -13426,7 +13470,43 @@ async function runBridgeSetup(options) {
     actorId: identity.actorId,
     actorName: identity.actorName,
     sourceName: identity.sourceName,
-    requestToken: options.requestToken || !options.token
+    requestToken: options.requestToken || !options.token,
+    resume: true
+  });
+}
+async function runBridgeResume(options) {
+  const root = resolve4(options.root);
+  const config2 = await readBridgeConfig(root);
+  const identity = bridgeSetupIdentity({
+    actorId: options.actorId ?? config2?.actorId,
+    actorName: options.actorName ?? config2?.actorName,
+    sourceName: options.sourceName ?? config2?.sourceName
+  });
+  const workspaceId = options.workspaceId ?? config2?.workspaceId;
+  const rootId = options.rootId ?? options.sourceId ?? config2?.rootId;
+  const baseUrl = options.baseUrl ?? config2?.baseUrl;
+  if (!workspaceId || !rootId || !baseUrl) {
+    throw new Error("Missing bridge resume configuration. Run mdocs bridge setup --workspace <id> --root <path> --root-id <id> --url <base-url> first.");
+  }
+  await runBridge({
+    root,
+    workspaceId,
+    rootId,
+    sourceId: options.sourceId,
+    sourceName: identity.sourceName,
+    folderId: options.folderId ?? config2?.folderId,
+    canonicalPrefix: options.canonicalPrefix ?? config2?.canonicalPrefix,
+    replicaPrefix: options.replicaPrefix ?? config2?.replicaPrefix,
+    claimToken: options.claimToken,
+    actorId: identity.actorId,
+    actorName: identity.actorName,
+    baseUrl,
+    intervalMs: options.intervalMs ?? config2?.intervalMs ?? 1e3,
+    token: options.token,
+    requestToken: options.requestToken || !options.token,
+    pairingTimeoutMs: options.pairingTimeoutMs,
+    once: options.once,
+    resume: true
   });
 }
 async function runBridge(options) {
@@ -13459,8 +13539,24 @@ async function runBridge(options) {
   const registeredRoot = token ? await fetchScopedRoot({ ...options, token }, rootId) : await registerRoot(options, root, rootId, mapping);
   lastAppliedHead = lastAppliedHead ?? registeredRoot?.canonical.head;
   await writeSourceState(lastAppliedHead);
+  await writeBridgeConfig(root, {
+    schemaVersion: 1,
+    workspaceId: options.workspaceId,
+    rootId,
+    baseUrl: options.baseUrl,
+    actorId: options.actorId,
+    actorName: options.actorName,
+    sourceName: options.sourceName,
+    folderId: options.folderId,
+    canonicalPrefix: options.canonicalPrefix,
+    replicaPrefix: options.replicaPrefix,
+    intervalMs: options.intervalMs,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const backfilled = await resumeFromCanonical();
+  if (options.once) return;
   connect();
-  if (claimMode) await primeLocalSignatures();
+  if (claimMode && !backfilled) await primeLocalSignatures();
   else await publishSnapshot("initial");
   const timer = setInterval(() => {
     void publishSnapshot("poll").catch((error) => {
@@ -13536,6 +13632,87 @@ async function runBridge(options) {
       }
     }
   }
+  async function resumeFromCanonical() {
+    if (!options.resume && !token) return false;
+    const remote = await fetchCanonicalSnapshot({ ...options, token }, rootId).catch(() => void 0);
+    if (!remote) return false;
+    const baseDocs = lastAppliedHead ? await fetchCommitDocuments({ ...options, token }, rootId, lastAppliedHead).catch(() => /* @__PURE__ */ new Map()) : /* @__PURE__ */ new Map();
+    const remoteDocIds = new Set(remote.docs.map((doc) => doc.docId));
+    let applied = 0;
+    let keptLocal = 0;
+    let conflicted = 0;
+    for (const doc of remote.docs) {
+      const base = baseDocs.get(doc.docId);
+      const decision = await reconcileRemoteDocument(doc, base);
+      if (decision === "applied") applied += 1;
+      if (decision === "kept_local") keptLocal += 1;
+      if (decision === "conflict") conflicted += 1;
+    }
+    for (const [docId, base] of baseDocs) {
+      if (remoteDocIds.has(docId)) continue;
+      const decision = await reconcileRemoteDelete(docId, base);
+      if (decision === "applied") applied += 1;
+      if (decision === "conflict") conflicted += 1;
+    }
+    lastAppliedHead = remote.head ?? lastAppliedHead;
+    await writeSourceState(lastAppliedHead);
+    process.stdout.write(
+      `mdocs bridge resume ${root}: applied ${applied}, kept local ${keptLocal}, conflicts ${conflicted}, head ${lastAppliedHead ?? "unknown"}
+`
+    );
+    return true;
+  }
+  async function reconcileRemoteDocument(remote, base) {
+    const remoteSignature = documentSignature(remote.markdown, remote.sidecar);
+    const baseSignature = base ? documentSignature(base.markdown, base.sidecar) : void 0;
+    const localState = await localStateForCanonical(remote);
+    const localSignature = localState ? documentSignature(localState.markdown, localState.sidecar) : void 0;
+    if (!localState) {
+      await applyCanonicalDocument(remote);
+      return "applied";
+    }
+    if (localSignature === remoteSignature && localState.path === remote.path && localState.docId === remote.docId) {
+      signatures.set(remote.docId, remoteSignature);
+      seenDocs.add(remote.docId);
+      return "noop";
+    }
+    if (localSignature === remoteSignature && localState.path === remote.path) {
+      await applyCanonicalDocument(remote);
+      return "applied";
+    }
+    if (baseSignature && localSignature === baseSignature) {
+      await applyCanonicalDocument(remote);
+      return "applied";
+    }
+    if (baseSignature && remoteSignature === baseSignature) {
+      signatures.set(remote.docId, baseSignature);
+      seenDocs.add(remote.docId);
+      return "kept_local";
+    }
+    signatures.set(remote.docId, baseSignature ?? remoteSignature);
+    await applyCanonicalDocument(remote);
+    return "conflict";
+  }
+  async function reconcileRemoteDelete(docId, base) {
+    const localState = await getDocumentState(io, docId).catch(() => void 0);
+    if (!localState) return "noop";
+    const baseSignature = documentSignature(base.markdown, base.sidecar);
+    const localSignature = documentSignature(localState.markdown, localState.sidecar);
+    if (localSignature !== baseSignature) {
+      const copyPath = conflictCopyPath(localState.path);
+      await io.writeTextAtomic(copyPath, localState.markdown);
+      await seedConflictCopySidecar(copyPath, localState);
+      process.stderr.write(`local conflict ${localState.path}; local version saved as ${copyPath}, canonical delete applied
+`);
+    }
+    await io.deleteFile(localState.path).catch(() => void 0);
+    await io.deleteFile(sidecarPath(docId)).catch(() => void 0);
+    await removeManifestDocument(docId, localState.path);
+    signatures.delete(docId);
+    seenDocs.delete(docId);
+    pendingDeletes.delete(docId);
+    return localSignature === baseSignature ? "applied" : "conflict";
+  }
   async function handleIncoming(message) {
     if (message.type === "file-changed") {
       await applyCanonicalDocument(readDocumentPayload(message.payload));
@@ -13561,7 +13738,7 @@ async function runBridge(options) {
 `);
       if (!payload.docId) return;
       pendingDocs.delete(payload.docId);
-      const canonical = await fetchCanonicalDocument(payload.docId);
+      const canonical = await fetchCanonicalDocument2(payload.docId);
       if (canonical) await applyCanonicalDocument(canonical);
     }
     if (message.type === "sync-error") {
@@ -13576,7 +13753,7 @@ async function runBridge(options) {
   }
   async function applyCanonicalDocument(payload) {
     const remoteSignature = documentSignature(payload.markdown, payload.sidecar);
-    const localState = await getDocumentState(io, payload.docId).catch(() => void 0);
+    const localState = await localStateForCanonical(payload);
     const localSignature = localState ? documentSignature(localState.markdown, localState.sidecar) : void 0;
     if (localSignature && signatures.has(payload.docId) && localSignature !== signatures.get(payload.docId) && localSignature !== remoteSignature) {
       const copyPath = conflictCopyPath(payload.path);
@@ -13598,9 +13775,14 @@ async function runBridge(options) {
     if (localState && localState.path !== payload.path) {
       await io.deleteFile(localState.path).catch(() => void 0);
     }
+    if (localState && localState.docId !== payload.docId) {
+      await io.deleteFile(sidecarPath(localState.docId)).catch(() => void 0);
+      await removeManifestDocument(localState.docId, localState.path);
+    }
     await io.writeTextAtomic(payload.path, payload.markdown);
     await io.writeTextAtomic(sidecarPath(payload.docId), `${JSON.stringify(payload.sidecar, null, 2)}
 `);
+    await upsertManifestDocument(payload);
     signatures.set(payload.docId, remoteSignature);
     deniedSignatures.delete(payload.docId);
     seenDocs.add(payload.docId);
@@ -13636,7 +13818,14 @@ async function runBridge(options) {
       updatedAt: now
     });
   }
-  async function fetchCanonicalDocument(docId) {
+  async function localStateForCanonical(payload) {
+    const byDocId = await getDocumentState(io, payload.docId).catch(() => void 0);
+    if (byDocId) return byDocId;
+    const map = await getWorkspaceMap(io).catch(() => void 0);
+    const byPath = map?.docs.find((doc) => doc.path === payload.path);
+    return byPath ? getDocumentState(io, byPath.docId).catch(() => void 0) : void 0;
+  }
+  async function fetchCanonicalDocument2(docId) {
     try {
       const response = await fetch(
         new URL(
@@ -13701,6 +13890,34 @@ async function runBridge(options) {
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
   }
+  async function upsertManifestDocument(payload) {
+    const manifest = await readManifest(io).catch(() => void 0);
+    if (!manifest) return;
+    await writeManifest(io, {
+      ...manifest,
+      docs: [
+        ...manifest.docs.filter((doc) => doc.docId !== payload.docId && doc.path !== payload.path),
+        {
+          docId: payload.docId,
+          path: payload.path,
+          title: payload.sidecar.title || titleFromMarkdown(payload.path, payload.markdown),
+          contentHash: contentHashForText(payload.markdown),
+          currentSha: payload.canonicalHead ?? payload.currentSha,
+          updatedAt: payload.sidecar.updatedAt
+        }
+      ].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  async function removeManifestDocument(docId, path) {
+    const manifest = await readManifest(io).catch(() => void 0);
+    if (!manifest) return;
+    await writeManifest(io, {
+      ...manifest,
+      docs: manifest.docs.filter((doc) => doc.docId !== docId && doc.path !== path),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
 }
 async function requestBridgeToken(options, rootId) {
   const response = await fetch(new URL("/api/bridge-requests", options.baseUrl), {
@@ -13754,6 +13971,83 @@ async function requestBridgeToken(options, rootId) {
   }
   throw new Error("Bridge approval timed out before a token was issued.");
 }
+async function readBridgeConfig(root) {
+  const io = new NodeWorkspaceIO(root);
+  try {
+    const config2 = JSON.parse(await io.readText(BRIDGE_CONFIG_PATH));
+    if (config2.schemaVersion !== 1 || typeof config2.workspaceId !== "string" || typeof config2.rootId !== "string" || typeof config2.baseUrl !== "string" || typeof config2.actorId !== "string") {
+      return void 0;
+    }
+    return config2;
+  } catch {
+    return void 0;
+  }
+}
+async function writeBridgeConfig(root, config2) {
+  const io = new NodeWorkspaceIO(root);
+  await io.mkdir(".mdocs");
+  await io.writeTextAtomic(BRIDGE_CONFIG_PATH, `${JSON.stringify(config2, null, 2)}
+`);
+}
+async function fetchCanonicalSnapshot(options, rootId) {
+  const response = await fetch(new URL(`/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}/sync`, options.baseUrl), {
+    headers: authHeaders(options.token)
+  });
+  if (!response.ok) return void 0;
+  const snapshot = await response.json();
+  const docs = await Promise.all(
+    (snapshot.tree?.docs ?? []).map((doc) => typeof doc.docId === "string" ? doc.docId : void 0).filter((docId) => Boolean(docId)).map((docId) => fetchCanonicalDocument(options, rootId, docId))
+  );
+  return {
+    head: snapshot.tree?.root?.canonical.head,
+    docs: docs.filter((doc) => Boolean(doc))
+  };
+}
+async function fetchCommitDocuments(options, rootId, headId) {
+  const response = await fetch(
+    new URL(
+      `/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}/commits/${encodeURIComponent(headId)}?content=1`,
+      options.baseUrl
+    ),
+    { headers: authHeaders(options.token) }
+  );
+  if (!response.ok) return /* @__PURE__ */ new Map();
+  const payload = await response.json();
+  const docs = (payload.docs ?? []).map((doc) => readCommitDocumentPayload(doc, options.workspaceId, rootId, headId)).filter((doc) => Boolean(doc));
+  return new Map(docs.map((doc) => [doc.docId, doc]));
+}
+async function fetchCanonicalDocument(options, rootId, docId) {
+  try {
+    const response = await fetch(
+      new URL(
+        `/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}/documents/${encodeURIComponent(docId)}`,
+        options.baseUrl
+      ),
+      { headers: authHeaders(options.token) }
+    );
+    if (!response.ok) return void 0;
+    const document = await response.json();
+    return readDocumentPayload({ ...document, canonicalHead: document.currentSha });
+  } catch {
+    return void 0;
+  }
+}
+function readCommitDocumentPayload(payload, workspaceId, rootId, headId) {
+  if (!payload || typeof payload !== "object") return void 0;
+  const value = payload;
+  if (typeof value.markdown !== "string" || !value.sidecar || typeof value.sidecar !== "object") return void 0;
+  return readDocumentPayload({
+    workspaceId,
+    rootId,
+    docId: value.docId,
+    path: value.path,
+    title: value.title,
+    markdown: value.markdown,
+    sidecar: value.sidecar,
+    currentSha: headId,
+    canonicalHead: headId
+  });
+}
 function parseBridgeSyncMessage(data) {
   if (!data.trim()) return void 0;
   try {
@@ -14063,9 +14357,9 @@ async function main() {
       return;
     }
     case "bridge": {
-      const options = {
-        root: resolve5(String(parsed.flags.root ?? cwd)),
-        workspaceId: String(parsed.flags.workspace ?? "workspace_demo"),
+      const root = resolve5(String(parsed.flags.root ?? cwd));
+      const baseOptions = {
+        root,
         rootId: typeof parsed.flags["root-id"] === "string" ? parsed.flags["root-id"] : void 0,
         sourceId: typeof parsed.flags.source === "string" ? parsed.flags.source : void 0,
         sourceName: typeof parsed.flags["source-name"] === "string" ? parsed.flags["source-name"] : void 0,
@@ -14075,11 +14369,24 @@ async function main() {
         claimToken: typeof parsed.flags.claim === "string" ? parsed.flags.claim : void 0,
         actorId: typeof parsed.flags.actor === "string" ? parsed.flags.actor : void 0,
         actorName: typeof parsed.flags["actor-name"] === "string" ? parsed.flags["actor-name"] : void 0,
-        baseUrl: bridgeBaseUrl(parsed.flags),
         intervalMs: Number(parsed.flags.interval ?? 1e3),
         token: typeof parsed.flags.token === "string" ? parsed.flags.token : process.env.MDOCS_BRIDGE_TOKEN || void 0,
         requestToken: Boolean(parsed.flags["request-token"] || parsed.flags.pair),
-        pairingTimeoutMs: typeof parsed.flags["pairing-timeout-ms"] === "string" ? Number(parsed.flags["pairing-timeout-ms"]) : void 0
+        pairingTimeoutMs: typeof parsed.flags["pairing-timeout-ms"] === "string" ? Number(parsed.flags["pairing-timeout-ms"]) : void 0,
+        once: Boolean(parsed.flags.once)
+      };
+      if (subcommand === "resume") {
+        await runBridgeResume({
+          ...baseOptions,
+          workspaceId: typeof parsed.flags.workspace === "string" ? parsed.flags.workspace : void 0,
+          baseUrl: optionalBridgeBaseUrl(parsed.flags)
+        });
+        return;
+      }
+      const options = {
+        ...baseOptions,
+        workspaceId: typeof parsed.flags.workspace === "string" ? parsed.flags.workspace : "workspace_demo",
+        baseUrl: bridgeBaseUrl(parsed.flags)
       };
       if (subcommand === "setup") await runBridgeSetup(options);
       else await runBridge({ ...options, actorId: options.actorId ?? "actor_local" });
@@ -14183,13 +14490,17 @@ function requiredFlag2(flags, name) {
   return value;
 }
 function bridgeBaseUrl(flags) {
-  if (typeof flags.url === "string" && flags.url.trim()) return flags.url.trim();
-  const configured = process.env.MDOCS_BASE_URL?.trim();
+  const configured = optionalBridgeBaseUrl(flags);
   if (configured) return configured;
   throw new CliError("usage_error", "Missing --url <base-url> for mdocs bridge.", {
     hint: "Pass the Magic Markdown origin explicitly (for example --url https://magic.example.com) or set MDOCS_BASE_URL. The bridge does not assume a localhost server."
   });
 }
+function optionalBridgeBaseUrl(flags) {
+  if (typeof flags.url === "string" && flags.url.trim()) return flags.url.trim();
+  const configured = process.env.MDOCS_BASE_URL?.trim();
+  return configured || void 0;
+}
 async function readRequiredTextFlag2(flags, cwd, names) {
   const value = await readOptionalTextFlag2(flags, cwd, names);
   if (value === void 0) {
@@ -14274,6 +14585,9 @@ Commands:
   bridge setup --workspace <id> --root . --url <base-url> [--folder-id <id>] --request-token
                                       Initialize, validate, request approval,
                                       and start an agent filesystem bridge
+  bridge resume --root . --request-token [--once]
+                                      Backfill missed Magic changes, then keep
+                                      the bridge running unless --once is set
   bridge --workspace <id> --root . --url <base-url> --request-token
                                       Request human approval, then sync an
                                       approved local root with the workspace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magic-markdown/cli",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "Magic Markdown agent CLI (mdocs): read, review, comment on, suggest edits to, and sync clean Markdown workspaces.",
   "type": "module",
   "license": "MIT",