pmx-canvas 0.3.3 → 0.3.4

package/src/cli/commands/edges.ts

@@ -0,0 +1,73 @@
+// Edge commands: edge add|list|remove.
+
+import { cmd, die, invokeOperation, output, parseFlags, showCommandHelp } from '../shared.js';
+
+// ── edge add ─────────────────────────────────────────────────
+cmd(
+  'edge add',
+  'Add an edge between two nodes',
+  [
+    'pmx-canvas edge add --from <node-id> --to <node-id> --type flow',
+    'pmx-canvas edge add --from-search "DVT O3 — GitOps" --to-search "deep work trend" --type relation',
+    'pmx-canvas edge add --from n1 --to n2 --type depends-on --label "imports"',
+    'pmx-canvas edge add --from n1 --to n2 --type references --style dashed --animated',
+  ],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('edge add');
+
+    const type = (flags.type as string) || 'flow';
+    const from = typeof flags.from === 'string' ? flags.from : undefined;
+    const to = typeof flags.to === 'string' ? flags.to : undefined;
+    const fromSearch = typeof flags['from-search'] === 'string' ? flags['from-search'] : undefined;
+    const toSearch = typeof flags['to-search'] === 'string' ? flags['to-search'] : undefined;
+
+    if (!from && !fromSearch) {
+      die(
+        'Missing source selector',
+        'Use --from <id> or --from-search "query". Search queries must resolve to exactly one node. Example: pmx-canvas edge add --from-search "DVT O3 — GitOps" --to-search "deep work trend" --type relation',
+      );
+    }
+    if (!to && !toSearch) {
+      die(
+        'Missing target selector',
+        'Use --to <id> or --to-search "query". Search queries must resolve to exactly one node. Example: pmx-canvas edge add --from-search "DVT O3 — GitOps" --to-search "deep work trend" --type relation',
+      );
+    }
+
+    const body: Record<string, unknown> = {
+      type,
+      ...(from ? { from } : {}),
+      ...(to ? { to } : {}),
+      ...(fromSearch ? { fromSearch } : {}),
+      ...(toSearch ? { toSearch } : {}),
+    };
+    if (flags.label && flags.label !== true) body.label = flags.label;
+    if (typeof flags.style === 'string') body.style = flags.style;
+    if (flags.animated) body.animated = true;
+
+    const result = await invokeOperation('edge.add', body);
+    output(result);
+  },
+);
+
+// ── edge list ────────────────────────────────────────────────
+cmd('edge list', 'List all edges on the canvas', ['pmx-canvas edge list'], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('edge list');
+
+  const layout = (await invokeOperation('layout.get', {})) as { edges: unknown[] };
+  output(layout.edges);
+});
+
+// ── edge remove ──────────────────────────────────────────────
+cmd('edge remove', 'Remove an edge by ID', ['pmx-canvas edge remove <edge-id>'], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('edge remove');
+
+  const id = positional[0];
+  if (!id) die('Missing edge ID', 'pmx-canvas edge remove <edge-id>');
+
+  const result = await invokeOperation('edge.remove', { edge_id: id });
+  output(result);
+});

package/src/cli/commands/groups.ts

@@ -0,0 +1,81 @@
+// Group commands: group create|add|remove.
+
+import {
+  cmd,
+  die,
+  invokeOperation,
+  optionalFiniteFlag,
+  optionalPositiveFiniteFlag,
+  output,
+  parseFlags,
+  requireFlag,
+  showCommandHelp,
+} from '../shared.js';
+
+// ── group create ─────────────────────────────────────────────
+cmd(
+  'group create',
+  'Create a group node',
+  [
+    'pmx-canvas group create --title "API Layer" node1 node2',
+    'pmx-canvas group create --title "Quarterly board" --x 40 --y 60 --width 1600 --height 900 --child-layout column node1 node2',
+    'pmx-canvas group create --title "Frontend" --color "#ff6b6b"',
+  ],
+  async (args) => {
+    const { positional, flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('group create');
+
+    const body: Record<string, unknown> = {};
+    if (flags.title && flags.title !== true) body.title = flags.title;
+    if (flags.color && flags.color !== true) body.color = flags.color;
+    const x = optionalFiniteFlag(flags, 'x', 'Use a finite number, e.g. --x 40');
+    const y = optionalFiniteFlag(flags, 'y', 'Use a finite number, e.g. --y 60');
+    const width = optionalPositiveFiniteFlag(flags, 'width', 'Use a positive number, e.g. --width 1600');
+    const height = optionalPositiveFiniteFlag(flags, 'height', 'Use a positive number, e.g. --height 900');
+    if (x !== undefined) body.x = x;
+    if (y !== undefined) body.y = y;
+    if (width !== undefined) body.width = width;
+    if (height !== undefined) body.height = height;
+    if (typeof flags['child-layout'] === 'string') body.childLayout = flags['child-layout'];
+    if (positional.length > 0) body.childIds = positional;
+
+    const result = await invokeOperation('group.create', body);
+    output(result);
+  },
+);
+
+// ── group add ────────────────────────────────────────────────
+cmd(
+  'group add',
+  'Add nodes to an existing group',
+  [
+    'pmx-canvas group add --group <group-id> node1 node2',
+    'pmx-canvas group add --group <group-id> --child-layout flow node1 node2',
+  ],
+  async (args) => {
+    const { positional, flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('group add');
+
+    const groupId = requireFlag(flags, 'group', 'pmx-canvas group add --group <group-id> node1 node2');
+    if (positional.length === 0) die('No node IDs provided', 'pmx-canvas group add --group <group-id> node1 node2');
+
+    const result = await invokeOperation('group.add', {
+      groupId,
+      childIds: positional,
+      ...(typeof flags['child-layout'] === 'string' ? { childLayout: flags['child-layout'] } : {}),
+    });
+    output(result);
+  },
+);
+
+// ── group remove ─────────────────────────────────────────────
+cmd('group remove', 'Ungroup all children from a group', ['pmx-canvas group remove <group-id>'], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('group remove');
+
+  const id = positional[0];
+  if (!id) die('Missing group ID', 'pmx-canvas group remove <group-id>');
+
+  const result = await invokeOperation('group.remove', { groupId: id });
+  output(result);
+});

package/src/cli/commands/history.ts

@@ -0,0 +1,220 @@
+// History commands: undo, redo, history, snapshot save|list|gc|restore|delete,
+// snapshot diff, and diff.
+
+import {
+  cmd,
+  die,
+  getStringFlag,
+  invokeOperation,
+  isRecord,
+  optionalNumberFlag,
+  output,
+  parseFlags,
+  requireFlag,
+  showCommandHelp,
+} from '../shared.js';
+
+function summarizeHistoryResult(result: Record<string, unknown>): Record<string, unknown> {
+  const entries = Array.isArray(result.entries) ? result.entries.filter(isRecord) : [];
+  const countsByOperation: Record<string, number> = {};
+  let currentIndex = 0;
+
+  entries.forEach((entry, index) => {
+    const op = typeof entry.operationType === 'string' ? entry.operationType : 'unknown';
+    countsByOperation[op] = (countsByOperation[op] ?? 0) + 1;
+    if (entry.isCurrent === true) currentIndex = index + 1;
+  });
+
+  const recent = entries.slice(-10).map((entry, index) => ({
+    index: entries.length - Math.min(entries.length, 10) + index + 1,
+    operationType: entry.operationType,
+    description: entry.description,
+    status: entry.isCurrent === true ? 'current' : entry.isUndone === true ? 'undone' : 'applied',
+  }));
+
+  return {
+    totalMutations: entries.length,
+    currentIndex,
+    canUndo: result.canUndo === true,
+    canRedo: result.canRedo === true,
+    countsByOperation,
+    recent,
+  };
+}
+
+function compactHistoryResult(result: Record<string, unknown>): Record<string, unknown> {
+  const entries = Array.isArray(result.entries) ? result.entries.filter(isRecord) : [];
+  return {
+    totalMutations: entries.length,
+    canUndo: result.canUndo === true,
+    canRedo: result.canRedo === true,
+    entries: entries.slice(-20).map((entry, index) => ({
+      index: entries.length - Math.min(entries.length, 20) + index + 1,
+      operationType: entry.operationType,
+      description: entry.description,
+      status: entry.isCurrent === true ? 'current' : entry.isUndone === true ? 'undone' : 'applied',
+    })),
+  };
+}
+
+// ── undo ─────────────────────────────────────────────────────
+cmd('undo', 'Undo the last canvas mutation', ['pmx-canvas undo'], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('undo');
+
+  const result = await invokeOperation('canvas.undo', {});
+  output(result);
+});
+
+// ── redo ─────────────────────────────────────────────────────
+cmd('redo', 'Redo the last undone mutation', ['pmx-canvas redo'], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('redo');
+
+  const result = await invokeOperation('canvas.redo', {});
+  output(result);
+});
+
+// ── history ──────────────────────────────────────────────────
+cmd(
+  'history',
+  'Show canvas mutation history',
+  ['pmx-canvas history', 'pmx-canvas history --summary', 'pmx-canvas history --compact'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('history');
+
+    const result = (await invokeOperation('history.get', {})) as Record<string, unknown>;
+    if (flags.summary) {
+      output(summarizeHistoryResult(result));
+      return;
+    }
+    if (flags.compact) {
+      output(compactHistoryResult(result));
+      return;
+    }
+    output(result);
+  },
+);
+
+// ── snapshot save ────────────────────────────────────────────
+cmd(
+  'snapshot save',
+  'Save a named snapshot of the current canvas',
+  ['pmx-canvas snapshot save --name "before-refactor"', 'pmx-canvas snapshot save --name checkpoint-1'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('snapshot save');
+
+    const name = requireFlag(flags, 'name', 'pmx-canvas snapshot save --name "my-snapshot"');
+    const result = await invokeOperation('snapshot.save', { name });
+    output(result);
+  },
+);
+
+// ── snapshot list ────────────────────────────────────────────
+cmd(
+  'snapshot list',
+  'List saved snapshots',
+  [
+    'pmx-canvas snapshot list',
+    'pmx-canvas snapshot list --limit 50 --query baseline',
+    'pmx-canvas snapshot list --after 2026-05-01T00:00:00Z --before 2026-05-05T00:00:00Z',
+    'pmx-canvas snapshot list --all',
+  ],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('snapshot list');
+
+    const limit = optionalNumberFlag(flags, 'limit', 'Use a positive integer, e.g. --limit 50');
+    const query = getStringFlag(flags, 'query', 'q');
+    const before = getStringFlag(flags, 'before');
+    const after = getStringFlag(flags, 'after');
+    const result = await invokeOperation('snapshot.list', {
+      ...(limit !== undefined ? { limit } : {}),
+      ...(query ? { q: query } : {}),
+      ...(before ? { before } : {}),
+      ...(after ? { after } : {}),
+      ...(flags.all ? { all: true } : {}),
+    });
+    output(result);
+  },
+);
+
+// ── snapshot gc ──────────────────────────────────────────────
+cmd(
+  'snapshot gc',
+  'Delete old snapshots, keeping the newest N',
+  ['pmx-canvas snapshot gc --keep 20 --dry-run', 'pmx-canvas snapshot gc --keep 50 --yes'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('snapshot gc');
+
+    const keep = optionalNumberFlag(flags, 'keep', 'Use a positive integer, e.g. --keep 20');
+    const dryRun = flags['dry-run'] === true;
+    if (!dryRun && !flags.yes) {
+      die('Destructive operation requires --yes flag', 'Preview with: pmx-canvas snapshot gc --keep 20 --dry-run');
+    }
+    const result = await invokeOperation('snapshot.gc', {
+      ...(keep !== undefined ? { keep } : {}),
+      dryRun,
+    });
+    output(result);
+  },
+);
+
+// ── snapshot restore ─────────────────────────────────────────
+cmd(
+  'snapshot restore',
+  'Restore canvas from a snapshot',
+  ['pmx-canvas snapshot restore <snapshot-id-or-name>'],
+  async (args) => {
+    const { positional, flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('snapshot restore');
+
+    const id = positional[0];
+    if (!id) die('Missing snapshot ID or name', 'pmx-canvas snapshot restore <snapshot-id-or-name>');
+
+    const result = await invokeOperation('snapshot.restore', { id });
+    output(result);
+  },
+);
+
+// ── snapshot delete ──────────────────────────────────────────
+cmd('snapshot delete', 'Delete a saved snapshot', ['pmx-canvas snapshot delete <snapshot-id>'], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('snapshot delete');
+
+  const id = positional[0];
+  if (!id) die('Missing snapshot ID', 'pmx-canvas snapshot delete <snapshot-id>');
+
+  const result = await invokeOperation('snapshot.delete', { id });
+  output(result);
+});
+
+async function runSnapshotDiff(args: string[]): Promise<void> {
+  const { positional, flags } = parseFlags(args);
+  const snapshot = positional[0];
+  if (!snapshot) die('Missing snapshot ID or name', 'pmx-canvas snapshot diff <snapshot-id-or-name>');
+  const result = await invokeOperation('snapshot.diff', { id: snapshot });
+  output(result);
+}
+
+// ── snapshot diff ────────────────────────────────────────────
+cmd(
+  'snapshot diff',
+  'Compare current canvas against a saved snapshot',
+  ['pmx-canvas snapshot diff <snapshot-id>', 'pmx-canvas snapshot diff "before-refactor"'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help || flags.h) return showCommandHelp('snapshot diff');
+    await runSnapshotDiff(args);
+  },
+);
+
+// ── diff ─────────────────────────────────────────────────────
+cmd('diff', 'Compare current canvas against a snapshot', ['pmx-canvas diff <snapshot-id>'], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('diff');
+  await runSnapshotDiff(args);
+});