@corvio/cli 0.1.0-beta.26 → 0.1.0-beta.27

package/README.md

@@ -15,8 +15,8 @@ corvio files get <asset_id> --content --json
 corvio files organize <asset_id> --instruction 'Create a reusable decision brief' --yes --json
 corvio files operation <operation_id> --json
 corvio files resume <operation_id> --yes --json
-corvio docs table-read <document_id> --limit 25 --json
-corvio docs table-mutate <document_id> --input ./table-change.json --change-summary 'Updated owner and due date' --yes --json
+corvio docs table-read <workspace_id/document_id> --limit 25 --json
+corvio docs table-mutate <workspace_id/document_id> --input ./table-change.json --change-summary 'Updated owner and due date' --yes --json
 corvio sync init --dir ./knowledge --root-node-id <node_id> --json
 corvio update check --json
 ```
@@ -32,7 +32,7 @@ fresh host session. Until a reviewed WorkBuddy marketplace listing is live, a Wo
 auto-update from Corvio. Remote MCP changes are server-delivered and normally need only a refreshed host session unless new OAuth scopes
 require reauthorization.
 
-The CLI rejects unknown/duplicate options and malformed integer bounds before network access. Normal API calls have a bounded timeout (`CORVIO_REQUEST_TIMEOUT_MS`, maximum ten minutes); only reads, explicit idempotency contracts, revision guards, and other owner-declared safe operations retry automatically. Document updates preflight the current revision when `--expected-revision` is omitted. `docs table-read` returns a bounded stable-ID projection; `docs table-mutate` accepts a JSON payload for at most 50 cell updates or row appends and requires the fetched revision, while formulas, styles, structure, sorting, and semantic transformations remain `corvio ask --allow-actions` work. When the executing principal is a connected Agent, document and table mutations also require `--change-summary`, create a visible document-level comment after the guarded update, and return its receipt; a comment failure is reported as a partial effect rather than silent success. When a Corvio document or comment supplied the task, use `corvio agent closeout` to return the verified outcome, optionally resolve the thread, and read both document and thread back. Downloads, uploads, and Markdown pulls verify SHA-256 receipts before replacing local files; local writes are atomic, remote default filenames cannot escape the current directory, and Sync refuses symbolic-link traversal while checkpointing each successful push.
+The CLI rejects unknown/duplicate options and malformed integer bounds before network access. Normal API calls have a bounded timeout (`CORVIO_REQUEST_TIMEOUT_MS`, maximum ten minutes); only reads, explicit idempotency contracts, revision guards, and other owner-declared safe operations retry automatically. Document commands accept both bare document IDs and canonical `workspace_id/document_id` handles; a canonical handle that disagrees with the selected Workspace fails before remote access, and successful reads return `canonical_id` for direct reuse. Document updates preflight the current revision when `--expected-revision` is omitted. `docs table-read` returns a bounded stable-ID projection; `docs table-mutate` accepts a JSON payload for at most 50 cell updates or row appends and requires the fetched revision, while formulas, styles, structure, sorting, and semantic transformations remain `corvio ask --allow-actions` work. When the executing principal is a connected Agent, document and table mutations also require `--change-summary`, create a visible document-level comment after the guarded update, and return its receipt; a comment failure is reported as a partial effect rather than silent success. When a Corvio document or comment supplied the task, use `corvio agent closeout` to return the verified outcome, optionally resolve the thread, and read both document and thread back. Downloads, uploads, and Markdown pulls verify SHA-256 receipts before replacing local files; local writes are atomic, remote default filenames cannot escape the current directory, and Sync refuses symbolic-link traversal while checkpointing each successful push.
 
 For `corvio ask`, pass the user's natural goal, complete decision-relevant context, and explicit constraints. Unless the user chose them,
 do not invent taxonomy, titles, artifact counts, or Corvio's internal plan. Read the terminal Question receipt and use `artifact.url` or

package/dist/cli.js

@@ -39,7 +39,7 @@ import {
   agentCredentialPath,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.26";
+const VERSION = "0.1.0-beta.27";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
@@ -189,8 +189,11 @@ const COMMAND_HELP = Object.freeze({
 
 function contextualHelp(command, action) {
   const normalizedCommand = command === "workspace" ? "workspaces" : command === "folders" ? "projects" : command;
-  const commandHelp = COMMAND_HELP[normalizedCommand];
-  if (!commandHelp) return HELP.trimEnd();
+  const baseCommandHelp = COMMAND_HELP[normalizedCommand];
+  if (!baseCommandHelp) return HELP.trimEnd();
+  const commandHelp = normalizedCommand === "docs"
+    ? `${baseCommandHelp}\n\nDocument commands accept either a bare document ID or the canonical workspace_id/document_id handle returned by Corvio. A canonical handle that disagrees with the selected Workspace fails before any remote request. Document reads return canonical_id for direct reuse.`
+    : baseCommandHelp;
   if (!action) return commandHelp;
   const matchingLine = commandHelp
     .split("\n")
@@ -277,6 +280,53 @@ function resourcePath(value) {
   return encodeURIComponent(String(value));
 }
 
+function resolveDocumentId(value, selection) {
+  const raw = String(value || "").trim();
+  if (!raw) {
+    throw new CliError("Provide a document ID or canonical workspace/document handle.", {
+      code: "document_id_required",
+    });
+  }
+  const handle = raw.startsWith("document:") ? raw.slice("document:".length) : raw;
+  if (!handle.includes("/")) return handle;
+  const parts = handle.split("/");
+  if (parts.length !== 2 || parts.some((part) => !part.trim())) {
+    throw new CliError(
+      "Document handles must be a document ID or canonical workspace_id/document_id pair.",
+      { code: "document_handle_invalid" },
+    );
+  }
+  const [workspaceId, documentId] = parts.map((part) => part.trim());
+  if (!selection?.workspaceId) {
+    throw new CliError(
+      "A canonical document handle requires an explicit or resolved Workspace route.",
+      { code: "document_workspace_route_unavailable", exitCode: EXIT.AUTH },
+    );
+  }
+  if (selection?.workspaceId && workspaceId !== selection.workspaceId) {
+    throw new CliError(
+      `The document handle belongs to Workspace ${workspaceId}, but the current route is ${selection.workspaceId}.`,
+      {
+        code: "document_workspace_mismatch",
+        exitCode: EXIT.AUTH,
+        details: {
+          handle_workspace_id: workspaceId,
+          selected_workspace_id: selection.workspaceId,
+        },
+      },
+    );
+  }
+  return documentId;
+}
+
+function withCanonicalDocumentId(value, selection, fallbackDocumentId = null) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const workspaceId = String(selection?.workspaceId || "").trim();
+  const documentId = String(fallbackDocumentId || value.id || "").trim();
+  if (!workspaceId || !documentId) return value;
+  return { ...value, canonical_id: `${workspaceId}/${documentId}` };
+}
+
 function safeRemoteFileName(value, fallback) {
   const normalized = String(value || "").replaceAll("\\", "/");
   const name = basename(normalized).trim();
@@ -2821,7 +2871,7 @@ async function search(options, positionals) {
 }
 
 async function docs(options, action, id) {
-  const { api, executionIdentity } = await executionClient(options);
+  const { api, executionIdentity, selection } = await executionClient(options);
   const documentId = id || options.id;
   let result;
   if (action === "list") {
@@ -2830,8 +2880,19 @@ async function docs(options, action, id) {
       throw new CliError("--lifecycle must be active or archived.", { code: "document_lifecycle_invalid" });
     }
     result = await api.request("/documents", { query: { ...pageQuery(options), lifecycle } });
+    if (Array.isArray(result?.data)) {
+      result = {
+        ...result,
+        data: result.data.map((item) => withCanonicalDocumentId(item, selection)),
+      };
+    }
   } else if (action === "get") {
-    result = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}`);
+    const targetId = resolveDocumentId(documentId, selection);
+    result = withCanonicalDocumentId(
+      await api.request(`/documents/${resourcePath(targetId)}`),
+      selection,
+      targetId,
+    );
     if (executionIdentity === "agent") {
       result = {
         ...result,
@@ -2843,7 +2904,7 @@ async function docs(options, action, id) {
       result = { ...result, output: options.output };
     }
   } else if (action === "table-read") {
-    const targetId = documentId || option(options, "id", { required: true });
+    const targetId = resolveDocumentId(documentId, selection);
     result = await api.request(`/documents/${resourcePath(targetId)}/table`, {
       query: {
         table_id: options["table-id"] || undefined,
@@ -2853,7 +2914,7 @@ async function docs(options, action, id) {
     });
   } else if (action === "table-mutate") {
     requireConfirmation(options, "Mutating a document table");
-    const targetId = documentId || option(options, "id", { required: true });
+    const targetId = resolveDocumentId(documentId, selection);
     const payload = await readJsonObject(option(options, "input", { required: true }), "--input");
     const changeSummary = String(options["change-summary"] || "").trim();
     if (executionIdentity === "agent" && !changeSummary) {
@@ -2931,7 +2992,7 @@ async function docs(options, action, id) {
         code: "document_update_empty",
       });
     }
-    const targetId = documentId || option(options, "id", { required: true });
+    const targetId = resolveDocumentId(documentId, selection);
     const changeSummary = String(options["change-summary"] || "").trim();
     if (executionIdentity === "agent" && !changeSummary) {
       throw new CliError(
@@ -3005,7 +3066,8 @@ async function docs(options, action, id) {
     }
   } else if (action === "move") {
     rejectTogether(options, "before-node-id", "after-node-id");
-    const current = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}`);
+    const targetId = resolveDocumentId(documentId, selection);
+    const current = await api.request(`/documents/${resourcePath(targetId)}`);
     result = await api.request(`/nodes/${resourcePath(current.node_id)}:move`, {
       method: "POST",
       headers: { "idempotency-key": idempotencyKey(options) },
@@ -3017,25 +3079,31 @@ async function docs(options, action, id) {
     });
   } else if (action === "archive") {
     requireConfirmation(options, "Archiving a document");
-    result = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}`, { method: "DELETE" });
+    const targetId = resolveDocumentId(documentId, selection);
+    result = await api.request(`/documents/${resourcePath(targetId)}`, { method: "DELETE" });
   } else if (action === "restore") {
     requireConfirmation(options, "Restoring an archived document");
-    result = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}/restore`, { method: "POST", retrySafe: true });
+    const targetId = resolveDocumentId(documentId, selection);
+    result = await api.request(`/documents/${resourcePath(targetId)}/restore`, { method: "POST", retrySafe: true });
   } else if (action === "share") {
     requireConfirmation(options, "Creating a document share link");
-    result = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}/shares`, {
+    const targetId = resolveDocumentId(documentId, selection);
+    result = await api.request(`/documents/${resourcePath(targetId)}/shares`, {
       method: "POST",
       retrySafe: true,
       body: { public_display_name: options["display-name"] || null },
     });
   } else if (action === "open") {
-    const targetId = documentId || option(options, "id", { required: true });
+    const targetId = resolveDocumentId(documentId, selection);
     const target = `${String(process.env.CORVIO_APP_BASE || DEFAULT_APP_BASE).replace(/\/+$/, "")}/app/d/${resourcePath(targetId)}`;
     const opened = options["no-input"] ? false : await openBrowser(target);
     result = { document_id: targetId, url: target, opened };
   } else {
     throw new CliError("docs action must be list, get, table-read, table-mutate, create, update, move, archive, restore, share, or open.");
   }
+  if (!new Set(["list", "create"]).has(action)) {
+    result = withCanonicalDocumentId(result, selection, resolveDocumentId(documentId, selection));
+  }
   writeResult(result, { json: options.json });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corvio/cli",
-  "version": "0.1.0-beta.26",
+  "version": "0.1.0-beta.27",
   "description": "Official Corvio Workspace CLI for questions, knowledge search, documents, and Agent workflows.",
   "type": "module",
   "bin": {