@magic-markdown/cli 0.3.6 → 0.3.8

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.6";
+var CLI_VERSION = "0.3.8";
 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,6 +11257,21 @@ 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> [--folder-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).",
@@ -11300,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.
@@ -13367,6 +13386,33 @@ 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);
@@ -13425,7 +13471,9 @@ async function runBridge(options) {
     });
     socket.addEventListener("message", (event) => {
       if (typeof event.data !== "string") return;
-      void handleIncoming(JSON.parse(event.data)).catch((error) => {
+      const message = parseBridgeSyncMessage(event.data);
+      if (!message) return;
+      void handleIncoming(message).catch((error) => {
         process.stderr.write(`bridge incoming failed: ${error instanceof Error ? error.message : String(error)}
 `);
       });
@@ -13647,6 +13695,7 @@ async function requestBridgeToken(options, rootId) {
       rootId,
       actorId: options.actorId,
       actorName: options.actorName,
+      folderId: options.folderId,
       sourceName: options.sourceName,
       role: "edit"
     })
@@ -13689,6 +13738,16 @@ async function requestBridgeToken(options, rootId) {
   }
   throw new Error("Bridge approval timed out before a token was issued.");
 }
+function parseBridgeSyncMessage(data) {
+  if (!data.trim()) return void 0;
+  try {
+    return JSON.parse(data);
+  } catch (error) {
+    process.stderr.write(`bridge ignored malformed sync message: ${error instanceof Error ? error.message : String(error)}
+`);
+    return void 0;
+  }
+}
 function delay(ms) {
   return new Promise((resolve6) => setTimeout(resolve6, ms));
 }
@@ -13776,6 +13835,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];
 }
@@ -13974,24 +14042,31 @@ 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,
         sourceId: typeof parsed.flags.source === "string" ? parsed.flags.source : void 0,
         sourceName: typeof parsed.flags["source-name"] === "string" ? parsed.flags["source-name"] : void 0,
+        folderId: typeof parsed.flags["folder-id"] === "string" ? parsed.flags["folder-id"] : void 0,
         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,
         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": {
@@ -14147,6 +14222,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
@@ -14179,6 +14255,9 @@ 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> [--folder-id <id>] --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

package/package.json

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