@creator-notes/cnotes 0.33.0 → 0.35.0

package/README.md

@@ -61,7 +61,7 @@ cnotes search semantic "onboarding flow"
 One contract across every command:
 
 - **Success is the exit code, not a body field.** Exit `0` is success; never look for an `ok` key. Failures use a typed table: `2` auth, `3` validation, `4` not found, `5` conflict, `6` rate limit, `7` permission, `8` subscription required, `9` network (the request never reached the server — DNS/TCP/TLS failed; the JSON carries the low-level `cause`, e.g. `ENOTFOUND`). Re-running a write because a key looked empty will duplicate it.
-- **Reads return a bare array; writes return an envelope.** `notes list/get/search --json` pipe to `jq '.[0]'`. `notes create --json` returns `{ results, relationshipsCreated, relationshipTypesCreated }`; read created notes from `.results` (not `notes`/`ok`).
+- **Reads return a bare array; writes return an envelope.** `notes list/get/search --json` pipe to `jq '.[0]'`. `notes create --json` returns `{ results, relationshipsCreated, relationshipTypesCreated, rubrics? }`; read created notes from `.results` (not `notes`/`ok`). Each result carries `displayId`, `title`, `type`, and `rubric`.
 - **Errors teach.** A `--json` failure prints `{ error, code, exitCode, hint }` to stderr, where `hint` names the command that fixes it (a bad workspace id returns a 404 with `resource: "workspace"` and a `cnotes workspace list` hint, not a bare 500).
 
 ## Authentication

package/dist/commands/canvas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../../src/commands/canvas.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAkG5C,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAm3E7D"}
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../../src/commands/canvas.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AA8G5C,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4hF7D"}

package/dist/commands/canvas.js

@@ -11,6 +11,17 @@ import { readCanvasMarkdown, renderCanvasMarkdown } from "../lib/canvas-read.js"
 import { resolveAgentSession } from "../lib/claude-session.js";
 import { WARN, dim } from "../lib/style.js";
 import { canvasUrl, canvasLinkForRef } from "../lib/urls.js";
+/**
+ * Path for a `/api/canvas/<id>` action call. ALWAYS carries `?workspaceId=`:
+ * CLI Bearer auth needs it to resolve a CANVAS-<n> display id, and the
+ * placeLayout/arrangeLayout actions reject the request outright without it
+ * (server's resolveCanvasForAuth). Build every canvas action URL through this
+ * helper — a call site that hand-rolls the path silently loses display-id
+ * support at best and 400s at worst (the add-section bug).
+ */
+function canvasActionPath(canvasId, workspaceId) {
+    return `/api/canvas/${encodeURIComponent(canvasId)}?workspaceId=${encodeURIComponent(workspaceId)}`;
+}
 /**
  * A list item is a *collection of member notes* with a short markdown description
  * that frames them — not a place to dump prose. When a description carries several
@@ -250,7 +261,7 @@ Examples:
         const cfg = resolveConfig(program.opts());
         const api = new ApiClient(cfg.serverUrl, cfg.token);
         try {
-            const data = await api.get(`/api/canvas/${encodeURIComponent(canvasId)}?workspaceId=${encodeURIComponent(cfg.workspaceId)}`);
+            const data = await api.get(canvasActionPath(canvasId, cfg.workspaceId));
             if (cfg.json) {
                 outputJson(data);
                 return;
@@ -540,7 +551,7 @@ Examples:
         const cfg = resolveConfig(program.opts());
         const api = new ApiClient(cfg.serverUrl, cfg.token);
         try {
-            const data = await api.delete(`/api/canvas/${canvasId}`);
+            const data = await api.delete(canvasActionPath(canvasId, cfg.workspaceId));
             if (cfg.json) {
                 outputJson(data);
             }
@@ -560,7 +571,7 @@ Examples:
         const cfg = resolveConfig(program.opts());
         const api = new ApiClient(cfg.serverUrl, cfg.token);
         try {
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "setAsHome",
             });
             if (cfg.json) {
@@ -582,7 +593,7 @@ Examples:
         const cfg = resolveConfig(program.opts());
         const api = new ApiClient(cfg.serverUrl, cfg.token);
         try {
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "archive",
             });
             if (cfg.json) {
@@ -604,7 +615,7 @@ Examples:
         const cfg = resolveConfig(program.opts());
         const api = new ApiClient(cfg.serverUrl, cfg.token);
         try {
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "unarchive",
             });
             if (cfg.json) {
@@ -633,7 +644,7 @@ Examples:
         const cfg = resolveConfig(program.opts());
         const api = new ApiClient(cfg.serverUrl, cfg.token);
         try {
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "addNode",
                 noteId: opts.note,
                 positionX: parseInt(opts.x, 10),
@@ -704,7 +715,7 @@ Examples:
             colorHex = opts.color.startsWith("#") ? opts.color : `#${opts.color}`;
         }
         try {
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "addRichtextNode",
                 content,
                 size: opts.size,
@@ -768,7 +779,7 @@ Examples:
                 // and lands the whole block collision-aware. Explicit --x/--y seed
                 // the origin; omitting them places below existing content.
                 const explicitOrigin = cmd.getOptionValueSource("x") === "cli" || cmd.getOptionValueSource("y") === "cli";
-                const data = await api.post(`/api/canvas/${canvasId}`, {
+                const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                     action: "placeLayout",
                     doc: {
                         ...(explicitOrigin
@@ -803,7 +814,7 @@ Examples:
                 }
                 return;
             }
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "addSectionNode",
                 name: opts.name,
                 positionX: parseInt(opts.x, 10),
@@ -927,7 +938,7 @@ Examples:
             }
             const noteIds = opts.notes ? opts.notes.split(",").map((id) => id.trim()) : [];
             warnListItemMisuse(opts.description, noteIds.length);
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "addListNode",
                 description: opts.description,
                 noteIds: noteIds.length > 0 ? noteIds : undefined,
@@ -958,7 +969,7 @@ Examples:
         const cfg = resolveConfig(program.opts());
         const api = new ApiClient(cfg.serverUrl, cfg.token);
         try {
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "addCanvasLink",
                 linkedCanvasId: opts.target,
                 positionX: parseInt(opts.x, 10),
@@ -1011,7 +1022,7 @@ Examples:
                     positionY,
                 };
             });
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "bulkAddNodes",
                 notes,
             });
@@ -1124,7 +1135,7 @@ Placement (relative to nodes already on the canvas):
                 doc.placement = opts.placement;
             }
             warnLayoutListMisuse(doc);
-            const data = await api.post(`/api/canvas/${encodeURIComponent(canvasId)}?workspaceId=${encodeURIComponent(cfg.workspaceId)}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "placeLayout",
                 doc,
                 ...(opts.dryRun ? { dryRun: true } : {}),
@@ -1332,7 +1343,7 @@ Examples:
                     // Name is required by the section container schema; the server
                     // updates the existing frame in place and keeps SECTION-<n>.
                     // Fetch the current name so we don't invent a placeholder title.
-                    const canvas = await api.get(`/api/canvas/${encodeURIComponent(canvasId)}?workspaceId=${encodeURIComponent(cfg.workspaceId)}`);
+                    const canvas = await api.get(canvasActionPath(canvasId, cfg.workspaceId));
                     const want = String(opts.section);
                     const wantUpper = want.toUpperCase();
                     const section = (canvas.sectionNodes ?? []).find((s) => s.id === want ||
@@ -1354,7 +1365,7 @@ Examples:
                 }
             }
             const autoResize = opts.autoResize !== false;
-            const data = await api.post(`/api/canvas/${encodeURIComponent(canvasId)}?workspaceId=${encodeURIComponent(cfg.workspaceId)}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "arrangeLayout",
                 doc,
                 ...(opts.section ? { targetSectionId: opts.section } : {}),
@@ -1439,7 +1450,7 @@ Examples:
                     positionY,
                 };
             });
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "bulkMoveNodes",
                 moves,
             });
@@ -1469,7 +1480,7 @@ Examples:
                 throw new ValidationError("--nodes must be a non-empty JSON array of strings");
             }
             nodeIds = nodeIds.map(String);
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "bulkRemoveNodes",
                 nodeIds,
             });
@@ -1509,7 +1520,7 @@ Examples:
     });
     canvas
         .command("add-edge")
-        .description("Connect two nodes on a canvas (any node type: note, text, list, richtext, canvas-link)")
+        .description("Connect two nodes on a canvas (any node type: note, text, list, richtext, canvas-link, section)")
         .argument("<canvasId>", "Canvas ID")
         .requiredOption("--source <nodeId>", "Source node ID (any node type on the canvas)")
         .requiredOption("--target <nodeId>", "Target node ID (any node type on the canvas)")
@@ -1522,7 +1533,7 @@ Examples:
         try {
             const { arrowStart, arrowEnd } = parseArrowMode(opts.arrow);
             const lineStyle = parseLineStyle(opts.lineStyle);
-            const data = await api.post(`/api/canvas/${canvasId}`, {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "addEdge",
                 sourceNodeId: opts.source,
                 targetNodeId: opts.target,
@@ -1594,7 +1605,7 @@ Examples:
             }
             if (opts.reverse)
                 body.reverse = true;
-            const data = await api.post(`/api/canvas/${canvasId}`, body);
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), body);
             if (cfg.json) {
                 outputJson(data);
             }
@@ -1661,7 +1672,7 @@ Examples:
                 body.colorHex = opts.color;
             // workspaceId is what lets the server resolve a CANVAS-<n> handle (the
             // form every example here uses) rather than demanding a raw Convex id.
-            const data = await api.post(`/api/canvas/${encodeURIComponent(canvasId)}?workspaceId=${encodeURIComponent(cfg.workspaceId)}`, body);
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), body);
             if (cfg.json) {
                 outputJson(data);
             }
@@ -1688,7 +1699,7 @@ Examples:
         try {
             const positionX = Number(opts.x);
             const positionY = Number(opts.y);
-            await api.post(`/api/canvas/${canvasId}`, {
+            await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "moveNode",
                 nodeId: opts.node,
                 nodeType: opts.type,
@@ -1715,7 +1726,7 @@ Examples:
         const cfg = resolveConfig(program.opts());
         const api = new ApiClient(cfg.serverUrl, cfg.token);
         try {
-            await api.post(`/api/canvas/${canvasId}`, {
+            await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "removeNode",
                 nodeId: opts.node,
             });
@@ -1739,7 +1750,7 @@ Examples:
         const cfg = resolveConfig(program.opts());
         const api = new ApiClient(cfg.serverUrl, cfg.token);
         try {
-            await api.post(`/api/canvas/${canvasId}`, {
+            await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "removeEdge",
                 edgeId: opts.edge,
             });
@@ -2165,5 +2176,164 @@ Examples:
             handleError(error, wantsJson);
         }
     });
+    // ---- comments: private anchored comments (the review queue) ----
+    // Visible only to the caller and agents acting as them — a shared canvas
+    // never shows one member's comments to another. The human drops comments in
+    // a review sweep (web UI or `comments add`); the agent runs `comments list`
+    // to pull the queue, addresses each item, and `comments resolve`s it. The
+    // active operation (from `operations begin` / `agent-run begin`) attaches to
+    // add/resolve automatically via the X-Agent-Run-Id header, so every resolved
+    // comment records which run addressed it.
+    const comments = canvas
+        .command("comments")
+        .description("Private comments anchored to canvas nodes — the review queue (visible only to you and your agents)");
+    comments
+        .command("list")
+        .description("List your comments on a canvas (open ones by default)")
+        .argument("<canvasId>", "Canvas ID")
+        .option("--status <status>", "Filter: open (default) | resolved | all", "open")
+        .addHelpText("after", `
+Examples:
+  $ cnotes canvas comments list <canvasId>            # open review queue
+  $ cnotes canvas comments list <canvasId> --status all --json
+`)
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const status = String(opts.status);
+            if (!["open", "resolved", "all"].includes(status)) {
+                throw new ValidationError("--status must be one of: open, resolved, all");
+            }
+            const data = await api.get(`${canvasActionPath(canvasId, cfg.workspaceId)}&view=comments&status=${status}`);
+            const rows = data.comments ?? [];
+            if (cfg.quiet) {
+                outputQuiet(rows.map((r) => String(r._id)).join("\n"));
+                return;
+            }
+            if (cfg.json) {
+                outputJson(data);
+                return;
+            }
+            if (rows.length === 0) {
+                console.log(status === "open" ? "No open comments on this canvas." : "No comments found.");
+                return;
+            }
+            for (const row of rows) {
+                const target = row.targetLabel ?? `${row.targetNodeType} node ${row.targetNodeId}`;
+                const stale = row.isStale ? " — target has changed since this was written" : "";
+                const missing = row.targetMissing ? " — node no longer on the canvas" : "";
+                const kind = row.authorKind === "agent" ? "agent note" : "comment";
+                console.log(`[${row.status}] ${row._id}`);
+                console.log(`  on ${target} (${kind})${stale}${missing}`);
+                console.log(`  ${truncate(String(row.content), 200)}`);
+            }
+            if (data.truncated) {
+                console.log(`(showing the first ${rows.length} — resolve some or narrow --status to see the rest)`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    comments
+        .command("add")
+        .description("Leave a comment anchored to a canvas node")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--node <nodeRef>", "Target node: raw node id, NOTE display id, or SECTION display id")
+        .requiredOption("--text <content>", "Comment text (max 4000 chars)")
+        .option("--author <kind>", "Author kind: agent (CLI default) | human")
+        .addHelpText("after", `
+Examples:
+  $ cnotes canvas comments add <canvasId> --node NOTE-12 --text "Tighten this to one claim"
+  $ cnotes canvas comments add <canvasId> --node SECTION-7 --text "Do not reflow — filmstrip depends on this order"
+`)
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            if (opts.author && !["human", "agent"].includes(opts.author)) {
+                throw new ValidationError("--author must be human or agent");
+            }
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
+                action: "addComment",
+                targetNodeId: opts.node,
+                content: opts.text,
+                authorKind: opts.author,
+            });
+            if (cfg.quiet) {
+                outputQuiet(String(data.annotationId));
+                return;
+            }
+            if (cfg.json) {
+                outputJson(data);
+                return;
+            }
+            console.log(`Comment ${data.annotationId} added on ${data.targetNodeType} node (${opts.node}).`);
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    comments
+        .command("resolve")
+        .description("Resolve a comment — the active operation (if any) is recorded as what addressed it")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--id <annotationId>", "Comment ID (from comments list)")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
+                action: "resolveComment",
+                annotationId: opts.id,
+            });
+            if (cfg.quiet) {
+                outputQuiet(String(data.annotationId));
+                return;
+            }
+            if (cfg.json) {
+                outputJson(data);
+                return;
+            }
+            if (data.alreadyResolved) {
+                console.log(`Comment ${opts.id} was already resolved.`);
+            }
+            else {
+                const provenance = data.resolvedByOperationId ? " (resolving operation recorded)" : "";
+                console.log(`Resolved comment ${opts.id}.${provenance}`);
+            }
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    comments
+        .command("rm")
+        .description("Delete a comment")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--id <annotationId>", "Comment ID (from comments list)")
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
+                action: "removeComment",
+                annotationId: opts.id,
+            });
+            if (cfg.quiet) {
+                outputQuiet(String(data.annotationId));
+                return;
+            }
+            if (cfg.json) {
+                outputJson(data);
+                return;
+            }
+            console.log(`Deleted comment ${opts.id}.`);
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
 }
 //# sourceMappingURL=canvas.js.map