@magic-markdown/cli 0.3.5 → 0.3.7

package/README.md

@@ -22,19 +22,21 @@ The package is a single self-contained bundle with no runtime dependencies. It r
 ## Quick start for agents
 
 ```bash
+npx --yes --package=@magic-markdown/cli@latest mdocs version --json
+
 # Join a shared document and announce presence
-mdocs join <share-url> --doc <docId> --name "Claude Code" --json
+npx --yes --package=@magic-markdown/cli@latest mdocs join <share-url> --doc <docId> --name "Claude Code" --json
 
 # Orient without dumping the whole document
-mdocs remote context --summary --json
+npx --yes --package=@magic-markdown/cli@latest mdocs remote context --summary --json
 
 # Page document text separately from review state
-mdocs remote context --start-line 1 --end-line 120 --no-review --json
-mdocs remote review --json
+npx --yes --package=@magic-markdown/cli@latest mdocs remote context --start-line 1 --end-line 120 --no-review --json
+npx --yes --package=@magic-markdown/cli@latest mdocs remote review --json
 
 # Leave a comment or propose an edit (ranges are 1-based, inclusive)
-mdocs remote comment --range 12:14 --body "Tighten this paragraph." --json
-mdocs remote suggest --range 12:14 --with-file replacement.md --message "Clearer phrasing" --json
+npx --yes --package=@magic-markdown/cli@latest mdocs remote comment --range 12:14 --body "Tighten this paragraph." --json
+npx --yes --package=@magic-markdown/cli@latest mdocs remote suggest --range 12:14 --with-file replacement.md --message "Clearer phrasing" --json
 ```
 
 Run `mdocs agent guide` for the full agent workflow, `mdocs help <command>` for any command, or `mdocs agent commands --json` for the machine-readable command contract.

package/dist/index.js

@@ -10990,7 +10990,7 @@ var RemoteDocumentIO = class {
 };
 
 // src/agent.ts
-var CLI_VERSION = "0.3.5";
+var CLI_VERSION = "0.3.7";
 var CLI_PACKAGE_NAME = "@magic-markdown/cli";
 var AGENT_COMMANDS = [
   {
@@ -11009,6 +11009,14 @@ var AGENT_COMMANDS = [
     mutates: false,
     examples: ["mdocs agent commands --json"]
   },
+  {
+    name: "agent-guide",
+    summary: "Alias for mdocs agent guide.",
+    usage: "mdocs agent-guide [--json]",
+    output: "text",
+    mutates: false,
+    examples: ["mdocs agent-guide", "mdocs agent-guide --json"]
+  },
   {
     name: "init",
     summary: "Create .mdocs metadata and index Markdown documents.",
@@ -11249,14 +11257,33 @@ var AGENT_COMMANDS = [
       "mdocs checkpoint restore checkpoint_abc123 --json"
     ]
   },
+  {
+    name: "bridge setup",
+    summary: "Initialize, validate, request approval for, and start an agent filesystem bridge.",
+    usage: "mdocs bridge setup --workspace <id> --root <path> --root-id <id> --url <base-url> --actor-name <agent-name> --request-token",
+    output: "long-running",
+    mutates: true,
+    examples: [
+      "mdocs bridge setup --workspace workspace_abc --root . --root-id agentfs-hermes --url https://magic.example.com --actor-name Hermes --request-token"
+    ],
+    notes: [
+      "Runs init and doctor before starting the bridge.",
+      "--request-token opens a human approval URL and avoids pasting bridge secrets into an agent session.",
+      "--token (or MDOCS_BRIDGE_TOKEN) still works when a scoped bridge token is already available."
+    ]
+  },
   {
     name: "bridge",
     summary: "Sync a local Markdown root with a Magic workspace over WebSocket (long-running).",
-    usage: "mdocs bridge --workspace <id> --root <path> --url <base-url>",
+    usage: "mdocs bridge --workspace <id> --root <path> --url <base-url> --request-token",
     output: "long-running",
     mutates: true,
-    examples: ["mdocs bridge --workspace workspace_abc --root . --root-id root_abc --url https://magic.example.com"],
-    notes: ["--url (or MDOCS_BASE_URL) is required; the bridge never assumes a localhost server."]
+    examples: ["mdocs bridge --workspace workspace_abc --root . --root-id root_abc --url https://magic.example.com --request-token"],
+    notes: [
+      "--request-token opens a human approval URL and avoids pasting bridge secrets into an agent session.",
+      "--token (or MDOCS_BRIDGE_TOKEN) still works when a scoped bridge token is already available.",
+      "--url (or MDOCS_BASE_URL) is required; the bridge never assumes a localhost server."
+    ]
   },
   {
     name: "serve-mcp",
@@ -11296,14 +11323,10 @@ Magic Markdown keeps Markdown files clean and stores collaboration metadata in .
 
 ## Install / Bootstrap
 
-The only official package is \`@magic-markdown/cli\` (bins \`mdocs\` and \`magic-markdown\`). A different, unrelated package is published as \`@mdocs/cli\` \u2014 do not install it. This snippet uses \`mdocs\` only after verifying its identity, otherwise it runs the official package through npx without a global install:
+The only official package is \`@magic-markdown/cli\` (bins \`mdocs\` and \`magic-markdown\`). A different, unrelated package is published as \`@mdocs/cli\` \u2014 do not install it. Agent sessions should bootstrap through the latest official package so they do not reuse a stale global \`mdocs\`:
 
 \`\`\`bash
-MDOCS="mdocs"
-if ! command -v mdocs >/dev/null 2>&1 || ! mdocs version --json 2>/dev/null | grep -qF '"name": "@magic-markdown/cli"'; then
-  MDOCS="npx --yes --package=@magic-markdown/cli@latest mdocs"
-fi
-$MDOCS version --json
+npx --yes --package=@magic-markdown/cli@latest mdocs version --json
 \`\`\`
 
 Run \`mdocs help <command>\` (or \`mdocs <command> --help\`) for usage, examples, and notes on any command, or \`mdocs agent commands --json\` for the full machine-readable contract.
@@ -13363,10 +13386,38 @@ function optionalFolderTarget(value) {
 // src/bridge.ts
 import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
 import { basename as basename2, resolve as resolve4 } from "node:path";
+function bridgeSetupIdentity(input) {
+  const actorName = input.actorName?.trim() || "Agent";
+  return {
+    actorId: input.actorId?.trim() || `agent:${agentSlug(actorName)}`,
+    actorName,
+    sourceName: input.sourceName?.trim() || agentFilesystemDisplayName(actorName)
+  };
+}
+async function runBridgeSetup(options) {
+  const root = resolve4(options.root);
+  const identity = bridgeSetupIdentity(options);
+  const io = new NodeWorkspaceIO(root);
+  const manifest = await indexWorkspace(io);
+  process.stdout.write(`mdocs bridge setup indexed ${manifest.docs.length} Markdown document${manifest.docs.length === 1 ? "" : "s"} in ${root}
+`);
+  const doctor = await runDoctor(io, root);
+  process.stdout.write(`mdocs doctor ${doctor.ok ? "ok" : "has warnings"}: ${doctor.checks.map((check) => check.details).join(" ")}
+`);
+  await runBridge({
+    ...options,
+    root,
+    actorId: identity.actorId,
+    actorName: identity.actorName,
+    sourceName: identity.sourceName,
+    requestToken: options.requestToken || !options.token
+  });
+}
 async function runBridge(options) {
   const root = resolve4(options.root);
   const localManifestSource = await readLocalSource(root);
   const rootId = options.rootId ?? options.sourceId ?? localManifestSource?.sourceId ?? rootIdForPath(root);
+  const token = options.token ?? (options.requestToken ? await requestBridgeToken(options, rootId) : void 0);
   const replicaId = `replica_${createHash2("sha256").update(`${root}:${options.actorId}`).digest("hex").slice(0, 12)}`;
   const replicaKind = actorKindForBridge(options.actorId) === "agent" ? "agent_runtime" : "local";
   const mapping = createSourceMapping({
@@ -13389,7 +13440,7 @@ async function runBridge(options) {
   const claimMode = Boolean(options.claimToken || localManifestSource?.canonicalHead);
   let lastAppliedHead = localManifestSource?.canonicalHead;
   let socket;
-  const registeredRoot = options.token ? await fetchScopedRoot(options, rootId) : await registerRoot(options, root, rootId, mapping);
+  const registeredRoot = token ? await fetchScopedRoot({ ...options, token }, rootId) : await registerRoot(options, root, rootId, mapping);
   lastAppliedHead = lastAppliedHead ?? registeredRoot?.canonical.head;
   await writeSourceState(lastAppliedHead);
   connect();
@@ -13412,7 +13463,7 @@ async function runBridge(options) {
     url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
     url.searchParams.set("actorId", options.actorId);
     url.searchParams.set("sourceId", sourceId);
-    if (options.token) url.searchParams.set("token", options.token);
+    if (token) url.searchParams.set("token", token);
     socket = new WebSocket(url);
     socket.addEventListener("open", () => {
       process.stdout.write(`mdocs bridge connected ${root} -> ${options.workspaceId}/${rootId}
@@ -13574,7 +13625,7 @@ async function runBridge(options) {
           `/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}/documents/${encodeURIComponent(docId)}`,
           options.baseUrl
         ),
-        { headers: authHeaders(options.token) }
+        { headers: authHeaders(token) }
       );
       if (!response.ok) return void 0;
       const document = await response.json();
@@ -13633,6 +13684,60 @@ async function runBridge(options) {
     });
   }
 }
+async function requestBridgeToken(options, rootId) {
+  const response = await fetch(new URL("/api/bridge-requests", options.baseUrl), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      workspaceId: options.workspaceId,
+      rootId,
+      actorId: options.actorId,
+      actorName: options.actorName,
+      sourceName: options.sourceName,
+      role: "edit"
+    })
+  }).catch((error) => {
+    throw new Error(`Failed to create bridge approval request: ${error instanceof Error ? error.message : String(error)}`);
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to create bridge approval request: ${response.status} ${await response.text()}`);
+  }
+  const created = await response.json();
+  if (!created.requestId || !created.pollToken || !created.approveUrl) {
+    throw new Error("Bridge approval request response was missing requestId, pollToken, or approveUrl.");
+  }
+  process.stdout.write(`mdocs bridge approval needed: ${created.approveUrl}
+`);
+  if (created.expiresAt) process.stdout.write(`Waiting for approval until ${created.expiresAt}.
+`);
+  const deadline = Date.now() + (options.pairingTimeoutMs ?? 1e3 * 60 * 15);
+  while (Date.now() < deadline) {
+    await delay(2e3);
+    const pollResponse = await fetch(new URL(`/api/bridge-requests/${encodeURIComponent(created.requestId)}/token`, options.baseUrl), {
+      headers: { Authorization: `Bearer ${created.pollToken}` }
+    }).catch((error) => {
+      throw new Error(`Bridge approval polling failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    const payload = await pollResponse.json().catch(() => ({}));
+    if (pollResponse.status === 202) continue;
+    if (pollResponse.ok && payload.token) {
+      process.stdout.write(`mdocs bridge approved${payload.expiresAt ? `; token expires ${payload.expiresAt}` : ""}.
+`);
+      return payload.token;
+    }
+    if (pollResponse.status === 409 && payload.status === "rejected") {
+      throw new Error("Bridge approval request was rejected.");
+    }
+    if (pollResponse.status === 410 || payload.status === "expired") {
+      throw new Error("Bridge approval request expired before it was approved.");
+    }
+    throw new Error(`Bridge approval polling failed with status ${pollResponse.status}.`);
+  }
+  throw new Error("Bridge approval timed out before a token was issued.");
+}
+function delay(ms) {
+  return new Promise((resolve6) => setTimeout(resolve6, ms));
+}
 function authHeaders(token) {
   return token ? { Authorization: `Bearer ${token}` } : {};
 }
@@ -13717,6 +13822,15 @@ function agentNameFromActorId(actorId, rootName) {
   if (nameFromId) return nameFromId;
   return "Agent";
 }
+function agentFilesystemDisplayName(agentName) {
+  const trimmed = agentName.trim();
+  if (!trimmed) return "Agent Filesystem";
+  return /\bagent$/i.test(trimmed) ? `${trimmed} Filesystem` : `${trimmed} Agent Filesystem`;
+}
+function agentSlug(agentName) {
+  const slug = agentName.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+  return slug || "agent";
+}
 function mergePermissions(permissions, permission) {
   return [...permissions.filter((candidate) => candidate.actorId !== permission.actorId), permission];
 }
@@ -13915,8 +14029,12 @@ async function main() {
       await runAgentCommand(io, cwd, subcommand, parsed);
       return;
     }
+    case "agent-guide": {
+      print(parsed.flags.json ? getAgentGuidePayload() : getAgentSkillMarkdown(), parsed.flags);
+      return;
+    }
     case "bridge": {
-      await runBridge({
+      const options = {
         root: resolve5(String(parsed.flags.root ?? cwd)),
         workspaceId: String(parsed.flags.workspace ?? "workspace_demo"),
         rootId: typeof parsed.flags["root-id"] === "string" ? parsed.flags["root-id"] : void 0,
@@ -13925,12 +14043,16 @@ async function main() {
         canonicalPrefix: typeof parsed.flags["canonical-prefix"] === "string" ? parsed.flags["canonical-prefix"] : void 0,
         replicaPrefix: typeof parsed.flags["replica-prefix"] === "string" ? parsed.flags["replica-prefix"] : void 0,
         claimToken: typeof parsed.flags.claim === "string" ? parsed.flags.claim : void 0,
-        actorId: String(parsed.flags.actor ?? "actor_local"),
+        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
-      });
+        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
+      };
+      if (subcommand === "setup") await runBridgeSetup(options);
+      else await runBridge({ ...options, actorId: options.actorId ?? "actor_local" });
       return;
     }
     case "doctor": {
@@ -14086,6 +14208,7 @@ function help() {
 
 Commands:
   agent guide                        Print agent SKILL.md workflow guidance
+  agent-guide                        Alias for agent guide
   agent commands --json              Print machine-readable command metadata
   init [path]                         Initialize .mdocs and index Markdown files
   map --json                          Print workspace map
@@ -14118,10 +14241,15 @@ Commands:
   remote events|history|restore       Poll events, list commits, restore snapshots
   remote library|create-folder|update-folder|move-root|invite-folder
                                       Organize the joined project library
+  bridge setup --workspace <id> --root . --url <base-url> --request-token
+                                      Initialize, validate, request approval,
+                                      and start an agent filesystem bridge
+  bridge --workspace <id> --root . --url <base-url> --request-token
+                                      Request human approval, then sync an
+                                      approved local root with the workspace
   bridge --workspace <id> --root . --url <base-url> --token <bridge-token>
                                       Sync an approved local root with the workspace
-                                      (--token from the web "Bind agent filesystem"
-                                      dialog, or MDOCS_BRIDGE_TOKEN)
+                                      (or set MDOCS_BRIDGE_TOKEN)
   bridge --claim <token> --root . --canonical-prefix prompts --replica-prefix packages/agent/prompts
                                       Claim an existing repo path as a Magic-canonical source mapping
   doctor --json                       Validate sidecar mappings

package/package.json

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