docz-cli 0.8.2 → 0.10.0

package/README.md

@@ -79,6 +79,7 @@ export DOCSYNC_API_TOKEN=<your-token>
 | `ls <space>[:<path>]` | List files and folders |
 | `cat <space>:<path>` | Read file content |
 | `upload <file> <space>[:<dir>]` | Upload local file |
+| `image upload <file>` | Upload image to OSS, get permanent public URL for Markdown |
 | `write <space>:<path> <content>` | Write content to file (`-` for stdin) |
 | `mkdir <space>:<path>` | Create folder |
 | `rm <space>:<path>` | Delete file/folder (30-day trash) |
@@ -141,6 +142,16 @@ docz-cli upload ./report.pdf G160-研发:reports                         # Uploa
 docz-cli mkdir G160-研发:new-project                                   # Create folder
 ```
 
+### Images
+
+Upload images to OSS for embedding in Markdown documents. Returns a permanent public URL — visible in share links and blogs without login, and doesn't consume Space quota. Supports png/jpg/webp, max 5MB.
+
+```bash
+docz-cli image upload ./screenshot.png
+# URL: https://<bucket>.oss-cn-beijing.aliyuncs.com/docz-markdown/2026/06/.../image.png
+# Markdown: ![screenshot](https://...)
+```
+
 ### Manage
 
 ```bash
@@ -254,6 +265,7 @@ Add to your MCP settings:
 | `docz_list_files` | List files in a directory |
 | `docz_read_file` | Read file content |
 | `docz_upload_file` | Upload/create a file |
+| `docz_upload_image` | Upload image to OSS, returns public URL for Markdown |
 | `docz_mkdir` | Create a folder |
 | `docz_delete` | Delete file/folder |
 | `docz_file_history` | View change history |
@@ -285,6 +297,7 @@ docz-cli wraps the DocSync REST API:
 | `ls` | `GET /api/spaces/{id}/tree?path=` |
 | `cat` | `GET /api/spaces/{id}/blob/{path}` |
 | `upload` / `write` | `POST /api/spaces/{id}/files/upload` or `POST /api/spaces/{id}/files/save` |
+| `image upload` | `POST /api/assets/images` |
 | `mkdir` | `POST /api/spaces/{id}/files/mkdir` |
 | `rm` | `POST /api/spaces/{id}/files/delete` |
 | `mv` | `POST /api/spaces/{id}/files/rename` |

package/dist/{chunk-DTGG5V2F.js → chunk-26LVQHYL.js}

@@ -115,6 +115,20 @@ var DocSyncClient = class {
       body: form
     });
   }
+  /**
+   * Upload an image to the server's OSS asset storage.
+   * Returns a permanent public URL that can be embedded in Markdown.
+   * Server limits: png/jpg/webp only, max 5MB.
+   */
+  async uploadImage(content, filename) {
+    const blob = new Blob([content], { type: "application/octet-stream" });
+    const form = new FormData();
+    form.append("file", blob, filename);
+    return this.request("/api/assets/images", {
+      method: "POST",
+      body: form
+    });
+  }
   async save(spaceId, path, content, opts) {
     const body = { path, content };
     if (opts?.baseRef) body.base_ref = opts.baseRef;
@@ -298,6 +312,301 @@ var DocSyncClient = class {
   }
 };
 
+// src/collab/text.ts
+import { createHash } from "crypto";
+function collabHash(content) {
+  return `sha256:${createHash("sha256").update(content, "utf8").digest("hex")}`;
+}
+var CollabConflictError = class extends Error {
+  constructor(currentHash, baseHash) {
+    super(
+      `collaborative document changed since base_collab_hash (current: ${currentHash}, base: ${baseHash})`
+    );
+    this.currentHash = currentHash;
+    this.baseHash = baseHash;
+    this.name = "CollabConflictError";
+  }
+};
+var CollabBaseHashRequiredError = class extends Error {
+  constructor(currentHash) {
+    super(
+      `base_collab_hash is required unless force is explicitly enabled (current: ${currentHash})`
+    );
+    this.currentHash = currentHash;
+    this.name = "CollabBaseHashRequiredError";
+  }
+};
+function getYText(doc) {
+  return doc.getText("content");
+}
+function readText(doc) {
+  return getYText(doc).toString();
+}
+function replaceText(doc, nextContent, opts = {}) {
+  const ytext = getYText(doc);
+  const previous = ytext.toString();
+  const previousHash = collabHash(previous);
+  const baseHash = opts.baseHash;
+  if (!opts.force) {
+    if (!baseHash) {
+      throw new CollabBaseHashRequiredError(previousHash);
+    }
+    if (previousHash !== baseHash) {
+      throw new CollabConflictError(previousHash, baseHash);
+    }
+  }
+  doc.transact(() => {
+    ytext.delete(0, ytext.length);
+    if (nextContent) ytext.insert(0, nextContent);
+  }, opts.origin ?? "docz-cli");
+  return { previousHash, hash: collabHash(nextContent) };
+}
+
+// src/collab/types.ts
+var CollabUnknownError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CollabUnknownError";
+  }
+};
+var CollabPublishError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "CollabPublishError";
+  }
+};
+
+// src/collab/room.ts
+import { randomUUID } from "crypto";
+import {
+  HocuspocusProvider,
+  HocuspocusProviderWebsocket
+} from "@hocuspocus/provider";
+import WebSocket from "ws";
+import * as Y from "yjs";
+
+// src/collab/roomName.ts
+function decodePath(path) {
+  try {
+    return decodeURIComponent(path);
+  } catch {
+    return path;
+  }
+}
+function normalizeCollabFilePath(path) {
+  const decoded = decodePath(path.trim()).replace(/\\/g, "/");
+  const parts = [];
+  for (const part of decoded.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") throw new Error("invalid collab file path");
+    parts.push(part);
+  }
+  return parts.join("/");
+}
+function buildCollabDocumentName(spaceId, filePath) {
+  const sid = spaceId.trim();
+  const normalizedPath = normalizeCollabFilePath(filePath);
+  if (!sid || !normalizedPath)
+    throw new Error("space id and file path are required");
+  return `${sid}:${normalizedPath}`;
+}
+
+// src/collab/room.ts
+function wsUrl(baseUrl) {
+  const u = new URL(baseUrl);
+  u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+  u.pathname = "/collab";
+  u.search = "";
+  u.hash = "";
+  return u.toString();
+}
+function withTimeout(promise, ms, label) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(new CollabUnknownError(`${label} timed out after ${ms}ms`)),
+      ms
+    );
+  });
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+var CollabRoomClient = class {
+  doc = new Y.Doc();
+  provider = null;
+  websocketProvider = null;
+  openOptions = null;
+  pending = /* @__PURE__ */ new Map();
+  connected = false;
+  synced = false;
+  readOnly = false;
+  async open(options) {
+    const openOptions = {
+      ...options,
+      path: normalizeCollabFilePath(options.path),
+      timeoutMs: options.timeoutMs ?? 3e4
+    };
+    this.openOptions = openOptions;
+    const opened = new Promise((resolve, reject) => {
+      const websocketProvider = new HocuspocusProviderWebsocket({
+        url: wsUrl(openOptions.baseUrl),
+        WebSocketPolyfill: WebSocket,
+        parameters: {
+          space_id: openOptions.spaceId,
+          file_path: openOptions.path,
+          client: openOptions.client,
+          client_version: openOptions.clientVersion
+        }
+      });
+      this.websocketProvider = websocketProvider;
+      const provider = new HocuspocusProvider({
+        websocketProvider,
+        name: buildCollabDocumentName(openOptions.spaceId, openOptions.path),
+        document: this.doc,
+        token: () => openOptions.token,
+        onAuthenticated: () => {
+        },
+        onAuthenticationFailed: (data) => {
+          reject(
+            new CollabPublishError(
+              `collab authentication failed: ${data.reason}`,
+              "auth_failed"
+            )
+          );
+        },
+        onStatus: ({ status }) => {
+          this.connected = status === "connected";
+        },
+        onSynced: ({ state }) => {
+          this.synced = state;
+          if (state) resolve();
+        },
+        onStateless: ({ payload }) => {
+          this.handleStateless(payload);
+        },
+        onDisconnect: () => {
+          this.connected = false;
+        }
+      });
+      this.provider = provider;
+    });
+    await withTimeout(opened, openOptions.timeoutMs, "collab open");
+    return this.read();
+  }
+  read() {
+    if (!this.openOptions) throw new Error("collab room is not open");
+    const content = readText(this.doc);
+    return {
+      spaceId: this.openOptions.spaceId,
+      path: this.openOptions.path,
+      content,
+      collabHash: collabHash(content),
+      connected: this.connected && this.synced,
+      readOnly: this.readOnly
+    };
+  }
+  write(content, opts = {}) {
+    if (!this.openOptions) throw new Error("collab room is not open");
+    if (this.readOnly)
+      throw new CollabPublishError("collab room is read-only", "read_only");
+    const result = replaceText(this.doc, content, {
+      baseHash: opts.baseHash,
+      force: opts.force,
+      origin: this.openOptions.client
+    });
+    return {
+      spaceId: this.openOptions.spaceId,
+      path: this.openOptions.path,
+      previousHash: result.previousHash,
+      collabHash: result.hash
+    };
+  }
+  async publish(timeoutMs) {
+    if (!this.provider || !this.openOptions)
+      throw new Error("collab room is not open");
+    const reqId = randomUUID();
+    const ms = timeoutMs ?? this.openOptions.timeoutMs ?? 3e4;
+    const result = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(reqId);
+        reject(
+          new CollabUnknownError(`collab publish ack timed out after ${ms}ms`)
+        );
+      }, ms);
+      this.pending.set(reqId, { resolve, reject, timer });
+    });
+    this.provider.sendStateless(
+      JSON.stringify({
+        type: "publish",
+        reqId,
+        client: this.openOptions.client,
+        client_version: this.openOptions.clientVersion
+      })
+    );
+    return result;
+  }
+  close() {
+    for (const [reqId, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      pending.reject(
+        new CollabUnknownError("collab room closed before publish ack")
+      );
+      this.pending.delete(reqId);
+    }
+    this.provider?.destroy();
+    this.websocketProvider?.destroy();
+    this.provider = null;
+    this.websocketProvider = null;
+    this.doc.destroy();
+  }
+  handleStateless(payload) {
+    let msg;
+    try {
+      msg = JSON.parse(payload);
+    } catch {
+      return;
+    }
+    if (!msg.reqId) return;
+    const pending = this.pending.get(msg.reqId);
+    if (!pending) return;
+    this.pending.delete(msg.reqId);
+    clearTimeout(pending.timer);
+    if (msg.type === "publish_ack" || msg.type === "recreate_after_delete_ack") {
+      if (!this.openOptions) {
+        pending.reject(
+          new CollabUnknownError("collab room closed before publish ack")
+        );
+        return;
+      }
+      pending.resolve({
+        spaceId: this.openOptions.spaceId,
+        path: this.openOptions.path,
+        ref: msg.ref || "",
+        contentRef: msg.content_ref || "",
+        externalBackup: msg.external_backup || ""
+      });
+      return;
+    }
+    pending.reject(
+      new CollabPublishError(
+        `collab publish failed${msg.code ? `: ${msg.code}` : ""}`,
+        msg.code
+      )
+    );
+  }
+};
+async function withCollabRoom(options, fn) {
+  const room = new CollabRoomClient();
+  try {
+    await room.open(options);
+    return await fn(room);
+  } finally {
+    room.close();
+  }
+}
+
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
@@ -331,8 +640,98 @@ function getConfigPath() {
 }
 
 // src/commands.ts
-import { readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "fs";
 import { basename } from "path";
+
+// src/collab/bridge.ts
+import readline from "readline";
+function send(value) {
+  process.stdout.write(`${JSON.stringify(value)}
+`);
+}
+async function startCollabBridge(openRoom) {
+  let room = null;
+  let cleanupObserver = null;
+  const rl = readline.createInterface({
+    input: process.stdin,
+    crlfDelay: Number.POSITIVE_INFINITY
+  });
+  function attachObserver(nextRoom) {
+    cleanupObserver?.();
+    const ytext = nextRoom.doc.getText("content");
+    const observer = () => {
+      const content = ytext.toString();
+      send({ event: "document_change", content, hash: collabHash(content) });
+    };
+    ytext.observe(observer);
+    cleanupObserver = () => ytext.unobserve(observer);
+  }
+  function closeRoom() {
+    cleanupObserver?.();
+    cleanupObserver = null;
+    room?.close();
+    room = null;
+  }
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    let req;
+    try {
+      req = JSON.parse(line);
+    } catch (err) {
+      send({ event: "error", code: "bad_json", message: String(err) });
+      continue;
+    }
+    try {
+      if (req.method === "open") {
+        const target = String(req.params?.target ?? "");
+        closeRoom();
+        room = await openRoom(target);
+        attachObserver(room);
+        const current = room.read();
+        send({
+          id: req.id,
+          result: {
+            content: current.content,
+            hash: current.collabHash,
+            read_only: current.readOnly
+          }
+        });
+        send({
+          event: "opened",
+          content: current.content,
+          hash: current.collabHash
+        });
+      } else if (req.method === "local_change") {
+        if (!room) throw new Error("room is not open");
+        const content = String(req.params?.content ?? "");
+        const baseHash = req.params?.base_hash ? String(req.params.base_hash) : void 0;
+        const result = room.write(content, {
+          baseHash,
+          force: req.params?.force === true
+        });
+        send({ id: req.id, result: { hash: result.collabHash } });
+      } else if (req.method === "publish") {
+        if (!room) throw new Error("room is not open");
+        send({ id: req.id, result: await room.publish() });
+      } else if (req.method === "status") {
+        send({ id: req.id, result: room ? room.read() : { connected: false } });
+      } else if (req.method === "close") {
+        closeRoom();
+        send({ id: req.id, result: { ok: true } });
+      } else {
+        throw new Error(`unknown method: ${req.method}`);
+      }
+    } catch (err) {
+      send({
+        id: req.id,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  closeRoom();
+}
+
+// src/commands.ts
 function getClient() {
   const token = getToken();
   if (!token) {
@@ -343,6 +742,32 @@ function getClient() {
   }
   return new DocSyncClient(getBaseUrl(), token);
 }
+function getRequiredToken() {
+  const token = getToken();
+  if (!token) {
+    console.error(
+      "Error: No token configured.\nRun `docz login` or set DOCSYNC_API_TOKEN environment variable."
+    );
+    process.exit(1);
+  }
+  return token;
+}
+async function buildCollabOpenOptions(target, opts = {}) {
+  const api = getClient();
+  const { spaceId, path } = await resolveTarget(api, [target]);
+  if (!path) {
+    throw new Error("file path is required for collaborative editing");
+  }
+  return {
+    baseUrl: getBaseUrl(),
+    token: getRequiredToken(),
+    spaceId,
+    path,
+    client: opts.client ?? "docz-cli",
+    clientVersion: opts.clientVersion ?? "0.10.0",
+    timeoutMs: opts.timeout
+  };
+}
 function parseTarget(args) {
   if (args.length === 0) {
     console.error(
@@ -449,6 +874,31 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf-8");
 }
 var MAX_SAVE_SIZE = 2 * 1024 * 1024;
+var IMAGE_EXTS = ["png", "jpg", "jpeg", "webp"];
+var IMAGE_MAX_SIZE = 5 * 1024 * 1024;
+function readImageFile(filePath) {
+  if (!existsSync2(filePath)) {
+    return { error: `File not found: ${filePath}` };
+  }
+  const filename = basename(filePath);
+  const ext = filename.split(".").pop()?.toLowerCase() ?? "";
+  if (!IMAGE_EXTS.includes(ext)) {
+    return {
+      error: `Unsupported image type ".${ext}". Supported: ${IMAGE_EXTS.join(", ")}`
+    };
+  }
+  const size = statSync(filePath).size;
+  if (size > IMAGE_MAX_SIZE) {
+    return {
+      error: `Image too large (${formatSize(size)}). Max size: 5 MB`
+    };
+  }
+  return { content: readFileSync2(filePath), filename };
+}
+function markdownImageRef(filename, url) {
+  const alt = filename.replace(/\.[^.]+$/, "");
+  return `![${alt}](${url})`;
+}
 function registerCommands(program) {
   program.command("login").description("Configure DocSync credentials").option("-u, --url <url>", "DocSync server URL").option("-t, --token <token>", "API token").action(async (opts) => {
     const url = opts.url ?? getBaseUrl();
@@ -532,6 +982,20 @@ function registerCommands(program) {
     const result = await client.upload(spaceId, targetDir, filename, content);
     console.log(`Uploaded: ${result.path}`);
   });
+  const image = program.command("image").description("Image asset operations");
+  image.command("upload").description(
+    "Upload image to OSS, returns a permanent public URL for Markdown embedding"
+  ).argument("<file>", "Local image file (png/jpg/webp, max 5MB)").action(async (file) => {
+    const read = readImageFile(file);
+    if ("error" in read) {
+      console.error(`Error: ${read.error}`);
+      process.exit(1);
+    }
+    const client = getClient();
+    const result = await client.uploadImage(read.content, read.filename);
+    console.log(`URL: ${result.url}`);
+    console.log(`Markdown: ${markdownImageRef(read.filename, result.url)}`);
+  });
   program.command("write").description(
     "Write content to file \u2014 docz write <space>:<path> <content> or <url> <content>"
   ).argument("<target>", "space:dir/filename.md or short URL").argument("<content>", "File content (or - for stdin)").option("--force", "Skip conflict detection").option("-m, --message <msg>", "Custom commit message").action(
@@ -834,6 +1298,124 @@ function registerCommands(program) {
     const ref = await client.getFileRef(spaceId, path);
     console.log(ref.url);
   });
+  const collab = program.command("collab").description("Collaborative editing via Docz realtime rooms");
+  collab.command("cat").description(
+    "Read collaborative document \u2014 docz collab cat <space>:<path> or <url>"
+  ).argument("<target>", "space:path or short URL").option("--raw", "Output raw content only").option("--timeout <ms>", "Open timeout in milliseconds", Number).action(
+    async (target, opts) => {
+      const open = await buildCollabOpenOptions(target, {
+        timeout: opts.timeout
+      });
+      await withCollabRoom(open, async (room) => {
+        const result = room.read();
+        if (!opts.raw) {
+          console.error(`collab_hash: ${result.collabHash}`);
+          console.error(`read_only: ${result.readOnly ? "true" : "false"}`);
+          console.error("---");
+        }
+        process.stdout.write(result.content);
+      });
+    }
+  );
+  collab.command("write").description(
+    "Write collaborative document \u2014 docz collab write <space>:<path> <content>"
+  ).argument("<target>", "space:path or short URL").argument("<content>", "File content (or - for stdin)").option("--base-collab-hash <hash>", "Hash returned by docz collab cat").option("--force", "Skip collaborative hash conflict detection").option("--no-publish", "Only update realtime room, do not flush to repo").option("--timeout <ms>", "Open/publish timeout in milliseconds", Number).action(
+    async (target, content, opts) => {
+      const open = await buildCollabOpenOptions(target, {
+        timeout: opts.timeout
+      });
+      const body = content === "-" ? await readStdin() : content;
+      if (Buffer.byteLength(body, "utf-8") > MAX_SAVE_SIZE) {
+        console.error(
+          "Error: content exceeds 2MB limit. Use `docz upload` for large files."
+        );
+        process.exit(1);
+      }
+      try {
+        await withCollabRoom(open, async (room) => {
+          const write = room.write(body, {
+            baseHash: opts.baseCollabHash,
+            force: opts.force
+          });
+          if (opts.publish === false) {
+            console.log(
+              `Updated collaborative room (collab_hash: ${write.collabHash})`
+            );
+            return;
+          }
+          const published = await room.publish(opts.timeout);
+          console.log(
+            `Published: ${published.path} (ref: ${published.ref}, collab_hash: ${write.collabHash})`
+          );
+          if (published.externalBackup) {
+            console.log(`External backup: ${published.externalBackup}`);
+          }
+        });
+      } catch (err) {
+        if (err instanceof CollabConflictError) {
+          console.error(
+            `Error: collaborative document changed. Re-read and retry. current=${err.currentHash} base=${err.baseHash}`
+          );
+          process.exit(1);
+        }
+        if (err instanceof CollabBaseHashRequiredError) {
+          console.error(
+            `Error: --base-collab-hash is required unless --force is set. Re-read first to get the latest hash. current=${err.currentHash}`
+          );
+          process.exit(1);
+        }
+        if (err instanceof CollabUnknownError) {
+          console.error(
+            `Unknown state: ${err.message}. The server may have processed the publish; please re-read before retrying.`
+          );
+          process.exit(75);
+        }
+        throw err;
+      }
+    }
+  );
+  collab.command("publish").description(
+    "Flush collaborative document to repo \u2014 docz collab publish <space>:<path>"
+  ).argument("<target>", "space:path or short URL").option("--timeout <ms>", "Open/publish timeout in milliseconds", Number).action(async (target, opts) => {
+    const open = await buildCollabOpenOptions(target, {
+      timeout: opts.timeout
+    });
+    try {
+      await withCollabRoom(open, async (room) => {
+        const result = await room.publish(opts.timeout);
+        console.log(`Published: ${result.path} (ref: ${result.ref})`);
+        if (result.externalBackup) {
+          console.log(`External backup: ${result.externalBackup}`);
+        }
+      });
+    } catch (err) {
+      if (err instanceof CollabUnknownError) {
+        console.error(
+          `Unknown state: ${err.message}. The server may have processed the publish; please re-read before retrying.`
+        );
+        process.exit(75);
+      }
+      throw err;
+    }
+  });
+  collab.command("bridge").description("Start local JSONL bridge for terminal editors").option("--client <name>", "Client name sent to Docz", "docz.nvim").option(
+    "--client-version <version>",
+    "Client version sent to Docz",
+    "0.10.0"
+  ).option("--timeout <ms>", "Open/publish timeout in milliseconds", Number).action(
+    async (opts) => {
+      await startCollabBridge(async (target) => {
+        const open = await buildCollabOpenOptions(target, {
+          client: opts.client,
+          clientVersion: opts.clientVersion,
+          timeout: opts.timeout
+        });
+        const room = new CollabRoomClient();
+        await room.open(open);
+        return room;
+      });
+    }
+  );
   program.command("diff").description(
     "Show changes \u2014 docz diff <space>[:<path>] <commit> [<from>] or <url> <commit> [<from>]"
   ).argument("<target>", "space or space:path or short URL").argument("<to>", "Commit hash").argument("[from]", "From commit hash (default: to^)").action(async (target, to, from) => {
@@ -862,9 +1444,15 @@ function registerCommands(program) {
 export {
   ConflictError,
   DocSyncClient,
+  CollabConflictError,
+  CollabBaseHashRequiredError,
+  CollabUnknownError,
+  withCollabRoom,
   getBaseUrl,
   getToken,
   parseExpires,
+  readImageFile,
+  markdownImageRef,
   registerCommands
 };
-//# sourceMappingURL=chunk-DTGG5V2F.js.map
+//# sourceMappingURL=chunk-26LVQHYL.js.map