@creator-notes/cnotes 0.74.0 → 0.76.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "creator-notes-cli",
-  "version": "0.74.0",
+  "version": "0.76.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,CAo2F7D"}
+{"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);
@@ -1900,7 +2005,8 @@ Examples:
     });
     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")
@@ -1913,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,
@@ -1921,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);