@creator-notes/cnotes 0.73.0 → 0.75.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "creator-notes-cli",
-  "version": "0.73.0",
+  "version": "0.75.0",
   "description": "CreatorNotes CLI: create notes, build canvases, search knowledge from the terminal",
   "author": {
     "name": "CreatorNotes",

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;AAiK5C,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmxF7D"}
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../../src/commands/canvas.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAwL5C,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAq9F7D"}

package/dist/commands/canvas.js

@@ -10,6 +10,7 @@ import { outputJson, outputTable, outputQuiet, truncate, timeAgo, formatAgo } fr
 import { readCanvasMarkdown, renderCanvasMarkdown, parseSharedCanvasLink, sameServerOrigin, readCanvasSection, renderCanvasSectionMarkdown, } from "../lib/canvas-read.js";
 import { resolveAgentSession } from "../lib/claude-session.js";
 import { WARN, dim } from "../lib/style.js";
+import { findOverlaps, layoutItemsFrom, parseSize, resolveAnchor, suggestFreeSpot, } from "../lib/canvas-layout.js";
 import { canvasUrl, canvasLinkForRef } from "../lib/urls.js";
 import { canvasActionPath, commentsListPath, parseCommentStatus, } from "../lib/canvas-paths.js";
 import { registerCanvasMilestoneCommands } from "./canvas-milestone.js";
@@ -66,6 +67,18 @@ function warnLayoutListMisuse(node) {
  * below a growing frame that shifted down with it (or didn't, and why).
  * Straddlers the grown frame ran over go to stderr like every layout warning.
  */
+/**
+ * add-node / move-node take raw x/y with no packing. Say so on every use, and
+ * pass on the server's overlap lint when the box lands on something (a card
+ * dropped on a portal or a text block can't be clicked). stderr, so --json
+ * stdout stays parseable.
+ */
+function warnRawPlacement(data, verb) {
+    const warning = data?.layoutWarning;
+    if (warning?.message)
+        console.error(`${WARN} ${warning.message}`);
+    console.error(dim(`${verb} is low-level: raw x/y, no collision check. Prefer \`canvas place\` (new items, packed) or \`canvas arrange\` (reflow existing), and \`canvas status\` to see the layout first.`));
+}
 function printRippleSummary(ripple, dryRun = false) {
     if (!ripple || typeof ripple !== "object")
         return;
@@ -273,6 +286,11 @@ Examples:
         .description("Get canvas details with nodes and edges")
         .argument("<canvasId>", "Canvas ID")
         .addHelpText("after", `
+Positions: --json splits items by kind (nodes, richtextNodes, listNodes,
+canvasLinkNodes for portals, sectionNodes). To check where things sit, read
+allNodes instead: every kind in ONE list with x, y, width and height. Or run
+\`cnotes canvas status <canvasId>\` for that list plus any overlaps.
+
 Examples:
   $ cnotes canvas get <canvasId> --json
 `)
@@ -328,6 +346,87 @@ Examples:
                     console.log(`  ${ln.id}: -> ${name} (${ln.positionX}, ${ln.positionY})`);
                 }
             }
+            console.log(dim("\nEvery item with its box, and any overlaps: cnotes canvas status " + canvasId));
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
+    canvas
+        .command("status")
+        .description("See a canvas's whole layout before you move anything: every item (cards, text, lists, portals, " +
+        "sections) as one list of rectangles, the items that overlap, and with --near a free spot next to an anchor.")
+        .argument("<canvasId>", "Canvas ID")
+        .option("--near <ref>", "Suggest a free spot next to this item (display id or node id) or point (x,y)")
+        .option("--size <WxH>", "Box to find room for with --near (default: a note card, 280x130)", "280x130")
+        .addHelpText("after", `
+Sections are containers: they are listed, but a card inside one is not an
+overlap. Read-only.
+
+Examples:
+  $ cnotes canvas status CANVAS-361
+  $ cnotes canvas status CANVAS-361 --near DECISION-6KJ          # where can this card go?
+  $ cnotes canvas status CANVAS-361 --near 900,100 --size 560x240 --json
+`)
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            const size = parseSize(opts.size);
+            if (!size)
+                throw new ValidationError(`--size must look like 280x130 (got "${opts.size}")`);
+            const data = await api.get(`/api/canvas/${encodeURIComponent(canvasId)}`, {
+                workspaceId: cfg.workspaceId,
+            });
+            const items = layoutItemsFrom(data);
+            const overlaps = findOverlaps(items);
+            let freeSpot = null;
+            if (opts.near) {
+                const anchor = resolveAnchor(items, opts.near);
+                if (!anchor) {
+                    throw new ValidationError(`No item "${opts.near}" on this canvas.`, "Pass a display id or node id from the list above, or a point as x,y.");
+                }
+                const spot = suggestFreeSpot(items, anchor, size);
+                if (spot)
+                    freeSpot = { ...spot, ...size, near: opts.near };
+            }
+            if (cfg.json) {
+                outputJson({
+                    items,
+                    overlaps: overlaps.map((o) => ({ a: o.a.ref, b: o.b.ref, area: o.area })),
+                    ...(opts.near ? { freeSpot } : {}),
+                });
+                return;
+            }
+            const canvas = data.canvas;
+            console.log(`Canvas: ${canvas?.title ?? canvasId} · ${items.length} items`);
+            outputTable(["KIND", "REF", "LABEL", "X", "Y", "W", "H"], items.map((i) => [
+                i.kind,
+                truncate(i.ref, 28),
+                truncate(i.label, 36),
+                String(Math.round(i.x)),
+                String(Math.round(i.y)),
+                String(Math.round(i.width)),
+                String(Math.round(i.height)),
+            ]));
+            if (overlaps.length === 0) {
+                console.log("\nNo overlaps.");
+            }
+            else {
+                console.log(`\n${WARN} ${overlaps.length} overlap${overlaps.length === 1 ? "" : "s"} (one item covers the other):`);
+                for (const o of overlaps) {
+                    console.log(`  ${o.a.ref} (${o.a.kind}) × ${o.b.ref} (${o.b.kind})  ${o.area}px²`);
+                }
+                console.log("  Fix with `canvas arrange`, or move one to a free spot from `--near`.");
+            }
+            if (opts.near) {
+                if (freeSpot) {
+                    console.log(`\nFree ${size.width}x${size.height} spot near ${opts.near}: x=${freeSpot.x} y=${freeSpot.y}`);
+                }
+                else {
+                    console.log(`\nNo free ${size.width}x${size.height} spot near ${opts.near}; try \`canvas place --placement auto\`.`);
+                }
+            }
         }
         catch (error) {
             handleError(error, cfg.json);
@@ -699,12 +798,17 @@ Examples:
     });
     canvas
         .command("add-node")
-        .description("Add a note to a canvas")
+        .description("Low-level: add one note card at raw x/y, with no collision check. To put cards on a canvas, " +
+        "use `canvas place` (packs them overlap-free, --placement auto finds the space). Warns when the card lands on something.")
         .argument("<canvasId>", "Canvas ID")
         .requiredOption("--note <noteId>", "Note display ID or Convex ID")
         .option("--x <n>", "X position", "100")
         .option("--y <n>", "Y position", "100")
         .addHelpText("after", `
+Prefer \`canvas place\` for new cards. If you do pick x/y yourself, check the
+spot first: \`cnotes canvas status <canvasId> --near <ref>\` lists every item's
+box and suggests a free one.
+
 Examples:
   $ cnotes canvas add-node <canvasId> --note MEETING-12 --x 200 --y 300
 `)
@@ -733,6 +837,7 @@ Examples:
                 if (link)
                     console.log(`Link: ${link}`);
             }
+            warnRawPlacement(data, "add-node");
         }
         catch (error) {
             handleError(error, cfg.json);
@@ -1816,9 +1921,92 @@ Examples:
             handleError(error, cfg.json);
         }
     });
+    canvas
+        .command("update-text")
+        .description("Edit a Text card IN PLACE: same node id, position, edges and mentions pointing at it. " +
+        "Replace the whole copy, swap one exact snippet (--find/--replace), or --append a paragraph. " +
+        "Never delete + re-add a card to change its words: that mints a new id and breaks what points at it.")
+        .argument("<canvasId>", "Canvas ID")
+        .requiredOption("--node <id>", "The Text card's node id (the id on kind:richtext elements in `canvas read --json`)")
+        .option("--content <markdown>", "New copy for the whole card (markdown)")
+        .option("--content-file <path>", "Read the new copy from a markdown file")
+        .option("--find <text>", "Exact snippet to change; must occur exactly once in the card")
+        .option("--replace <text>", "What --find becomes (pass \"\" to delete it)")
+        .option("--append <markdown>", "Add a paragraph at the end of the card")
+        .addOption(new Option("--size <size>", "New card size").choices(["small", "medium", "large"]))
+        .option("--color <hex>", "New tint hex")
+        .option("--clear-color", "Remove the tint")
+        .option("--no-ripple", "If the card grows, leave the content below where it is (warn only)")
+        .addHelpText("after", `
+The edit attaches to the active operation (cnotes operations begin) and shows
+in \`cnotes canvas activity\`. A card that grows pushes the band below it down,
+the same as a new card does; the response names anything it still runs into.
+
+Examples:
+  # Add today's date to a banner without touching its mentions
+  $ cnotes canvas update-text CANVAS-359 --node <nodeId> --find "picks none" --replace "picks none (10 Oct 2026)"
+
+  # Append a line
+  $ cnotes canvas update-text CANVAS-359 --node <nodeId> --append "Answered on 10 Oct 2026."
+
+  # Rewrite the whole card from a file
+  $ cnotes canvas update-text CANVAS-359 --node <nodeId> --content-file ./banner.md
+`)
+        .action(async (canvasId, opts) => {
+        const cfg = resolveConfig(program.opts());
+        const api = new ApiClient(cfg.serverUrl, cfg.token);
+        try {
+            if (opts.content !== undefined && opts.contentFile !== undefined) {
+                throw new ValidationError("Pass --content or --content-file, not both.");
+            }
+            const content = opts.contentFile !== undefined ? readFileSafe(opts.contentFile) : opts.content;
+            if ((opts.find === undefined) !== (opts.replace === undefined)) {
+                throw new ValidationError("--find and --replace go together.");
+            }
+            const modes = [content !== undefined, opts.find !== undefined, opts.append !== undefined].filter(Boolean).length;
+            if (modes > 1) {
+                throw new ValidationError("Change the copy one way per call: --content, --find/--replace, or --append.");
+            }
+            const body = { action: "updateRichtextNode", nodeId: opts.node };
+            if (content !== undefined)
+                body.content = content;
+            if (opts.find !== undefined) {
+                body.find = opts.find;
+                body.replace = opts.replace;
+            }
+            if (opts.append !== undefined)
+                body.append = opts.append;
+            if (opts.size !== undefined)
+                body.size = opts.size;
+            // '' is the server's "clear the tint" sentinel.
+            if (opts.clearColor)
+                body.colorHex = "";
+            else if (typeof opts.color === "string")
+                body.colorHex = opts.color;
+            if (opts.ripple === false)
+                body.ripple = false;
+            if (Object.keys(body).length === 2) {
+                throw new ValidationError("Nothing to change: pass --content, --find/--replace, --append, --size or --color.");
+            }
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), body);
+            if (cfg.json) {
+                outputJson(data);
+                return;
+            }
+            console.log(`Updated Text card ${opts.node}`);
+            printRippleSummary(data.ripple);
+            const warning = data.layoutWarning;
+            if (warning?.message)
+                console.error(`${WARN} ${warning.message}`);
+        }
+        catch (error) {
+            handleError(error, cfg.json);
+        }
+    });
     canvas
         .command("move-node")
-        .description("Move a node to a new position on a canvas")
+        .description("Low-level: move one node to raw x/y, with no collision check. To tidy or reflow a canvas, use " +
+        "`canvas arrange`; to see what's where first, `canvas status`. Warns when the node lands on something.")
         .argument("<canvasId>", "Canvas ID")
         .requiredOption("--node <nodeId>", "Canvas node ID")
         .requiredOption("--x <n>", "X position")
@@ -1831,7 +2019,7 @@ Examples:
         try {
             const positionX = Number(opts.x);
             const positionY = Number(opts.y);
-            await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
+            const data = await api.post(canvasActionPath(canvasId, cfg.workspaceId), {
                 action: "moveNode",
                 nodeId: opts.node,
                 nodeType: opts.type,
@@ -1839,11 +2027,18 @@ Examples:
                 positionY,
             });
             if (cfg.json) {
-                outputJson({ success: true, nodeId: opts.node, positionX, positionY });
+                outputJson({
+                    success: true,
+                    nodeId: opts.node,
+                    positionX,
+                    positionY,
+                    ...(data?.layoutWarning ? { layoutWarning: data.layoutWarning } : {}),
+                });
             }
             else {
                 console.log(`Moved node ${opts.node} to (${positionX}, ${positionY})`);
             }
+            warnRawPlacement(data, "move-node");
         }
         catch (error) {
             handleError(error, cfg.json);