pmx-canvas 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -3,6 +3,62 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.5] - 2026-04-26
+
+Image-validation hardening + CLI ergonomics. The boundary where untrusted
+file paths become canvas state now validates magic bytes, and common CLI
+typos produce one-line suggestions instead of help-block dumps.
+
+### Added
+
+- **Magic-byte validation for local image nodes.** PNG / JPEG / GIF / SVG /
+  WebP / BMP / ICO / AVIF headers are sniffed before a file becomes an
+  `image` node. A file renamed `screenshot.png` containing PowerPoint XML
+  is now rejected with a clear error before it reaches the renderer.
+- **macOS cloud-on-demand placeholder detection.** Files in iCloud Drive,
+  OneDrive, etc. that are not yet downloaded locally are detected via
+  `stat -f %Xf` flags and rejected with a hint to download them first —
+  no more silent freezes when an iCloud-only file is dropped on the canvas.
+- **`/bin/dd` escape hatch with a 5s timeout** for macOS-only paths where
+  the direct fs read could hang on an unresponsive volume (e.g. an
+  unmounted SMB share that still satisfies `existsSync`). Distinguishes
+  timeout (`SIGTERM` / `ETIMEDOUT`) from generic spawn failures so the
+  cloud-storage hint isn't shown for unrelated errors.
+- **CLI typo hints for resource subcommands.**
+  - `pmx-canvas node delete <id>` and `pmx-canvas node rm <id>` exit 1 with
+    `Did you mean: pmx-canvas node remove?`.
+  - `pmx-canvas edge delete <id>` and `pmx-canvas edge rm <id>` get the
+    same treatment.
+  - `pmx-canvas node pin <id>` redirects to the top-level
+    `pmx-canvas pin <id>` command.
+
+### Changed
+
+- **`GET /api/canvas/image/:id` is now async** (`fs/promises.readFile`) and
+  validates content before serving — returns **400** on invalid image bytes
+  instead of 200 with `application/octet-stream`.
+- **Bare `pmx-canvas node` (no subcommand)** now exits 1 with structured
+  JSON instead of printing the resource help block. Use
+  `pmx-canvas node --help` for the listing.
+
+### Internal
+
+- New module `src/server/image-source.ts` extracts and extends image
+  validation from `canvas-operations.ts`. Same error contract; richer
+  checks. The MCP and HTTP layers both flow through `addCanvasNode`, so
+  CLAUDE.md rule #5 (four-layer parity) is preserved without touching
+  the SDK or MCP server.
+- Direct fs read is the fast path on every platform (no fork, no shell);
+  `dd` is only consulted on macOS as a fallback when direct read fails on
+  a path that wasn't flagged as a placeholder.
+- Real magic-byte fixtures in `tests/unit/canvas-operations.test.ts` (was:
+  `*.png` extension smoke tests). New HTTP coverage in
+  `tests/unit/server-api.test.ts` for valid / invalid / missing image
+  paths. New CLI coverage for `node delete`, `node pin`, `edge delete`,
+  `edge rm` typo hints.
+
+[0.1.5]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.5
+
 ## [0.1.4] - 2026-04-26
 
 Graph/CLI ergonomics + canvas-node taxonomy hardening. Three threads:

package/dist/types/server/image-source.d.ts

@@ -0,0 +1,3 @@
+export declare function validateLocalImageFile(path: string): {
+    mimeType: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/src/cli/agent.ts

@@ -873,6 +873,21 @@ function filterJsonRenderSchemaView(
 // ── Commands ─────────────────────────────────────────────────
 
 const COMMANDS: Record<string, { run: (args: string[]) => Promise<void>; help: string; examples: string[] }> = {};
+const RESOURCE_COMMAND_ALIASES: Record<string, Record<string, string>> = {
+  node: {
+    delete: 'remove',
+    rm: 'remove',
+  },
+  edge: {
+    delete: 'remove',
+    rm: 'remove',
+  },
+};
+const RESOURCE_SUBCOMMAND_HINTS: Record<string, Record<string, string>> = {
+  node: {
+    pin: 'Use the top-level pin command instead: pmx-canvas pin <node-id>',
+  },
+};
 
 function cmd(
   name: string,
@@ -2225,12 +2240,32 @@ export async function runAgentCli(args: string[]): Promise<void> {
   // Unknown command — show help for the resource if it exists
   const resourceCommands = Object.keys(COMMANDS).filter((k) => k.startsWith(oneWord + ' '));
   if (resourceCommands.length > 0) {
-    console.log(`\nAvailable "${oneWord}" commands:\n`);
-    for (const k of resourceCommands) {
-      console.log(`  pmx-canvas ${k.padEnd(20)} ${COMMANDS[k].help}`);
+    if (args[1] === '--help' || args[1] === '-h') {
+      console.log(`\nAvailable "${oneWord}" commands:\n`);
+      for (const k of resourceCommands) {
+        console.log(`  pmx-canvas ${k.padEnd(20)} ${COMMANDS[k].help}`);
+      }
+      console.log('\nRun any command with --help for details.\n');
+      return;
     }
-    console.log('\nRun any command with --help for details.\n');
-    return;
+    const subcommand = args[1];
+    const suggestion = subcommand ? RESOURCE_COMMAND_ALIASES[oneWord]?.[subcommand] : undefined;
+    const extraHint = subcommand ? RESOURCE_SUBCOMMAND_HINTS[oneWord]?.[subcommand] : undefined;
+    const available = resourceCommands
+      .map((k) => k.slice(oneWord.length + 1))
+      .sort()
+      .join(', ');
+    const hints = [
+      suggestion ? `Did you mean: pmx-canvas ${oneWord} ${suggestion}?` : undefined,
+      extraHint,
+      `Available subcommands: ${available}`,
+    ].filter((hint): hint is string => typeof hint === 'string');
+    die(
+      subcommand
+        ? `Unknown ${oneWord} subcommand: "${subcommand}".`
+        : `Missing ${oneWord} subcommand.`,
+      hints.join(' '),
+    );
   }
 
   die(`Unknown command: ${oneWord}`, 'Run: pmx-canvas --help');

package/src/server/canvas-operations.ts

@@ -4,7 +4,6 @@ import { recomputeCodeGraph } from './code-graph.js';
 import {
   canvasState,
   type CanvasEdge,
-  IMAGE_MIME_MAP,
   type CanvasNodeState,
   type CanvasNodeUpdate,
   type CanvasSnapshot,
@@ -36,6 +35,7 @@ import {
   getWebpageFetchErrorDetails,
   normalizeWebpageUrl,
 } from './webpage-node.js';
+import { validateLocalImageFile } from './image-source.js';
 import { buildExcalidrawRestoreCheckpointToolInput, ensureExcalidrawCheckpointId, isExcalidrawCreateView } from './diagram-presets.js';
 
 export type CanvasArrangeMode = 'grid' | 'column' | 'flow';
@@ -435,22 +435,14 @@ function buildImageNodeData(input: CanvasAddNodeInput): Record<string, unknown>
 
   if (!isDataUri && !isUrl && src) {
     const resolved = resolve(src);
-    const ext = resolved.split('.').pop()?.toLowerCase() ?? '';
     const fileName = resolved.split('/').pop() ?? src;
-    const mime = IMAGE_MIME_MAP[ext];
-    if (!mime) {
-      throw new Error(
-        `Invalid image node: "${fileName}" has unsupported extension ".${ext}". ` +
-          `Accepted: ${Object.keys(IMAGE_MIME_MAP).join(', ')}. ` +
-          `For non-image files use type="file" (live viewer) or type="webpage" (URL) instead.`,
-      );
-    }
+    const { mimeType } = validateLocalImageFile(resolved);
     return {
       ...(input.data ?? {}),
       src: resolved,
       title: input.title ?? fileName,
       path: resolved,
-      mimeType: mime,
+      mimeType,
     };
   }
 

package/src/server/image-source.ts

@@ -0,0 +1,206 @@
+import { execFileSync } from 'node:child_process';
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
+import { IMAGE_MIME_MAP } from './canvas-state.js';
+
+const IMAGE_HEADER_BYTES = 512;
+const IMAGE_HEADER_READ_TIMEOUT_MS = 5000;
+// Set by `chflags hidden`, iCloud Drive, OneDrive, etc. on macOS — the
+// metadata exists but the file content has not been downloaded locally.
+const MACOS_DATALESS_FLAG = 0x40000000;
+// Per macOS `man stat -f %Xf`, this bit is also set on iCloud Documents
+// & Files for content-not-yet-downloaded entries on newer OS releases.
+const MACOS_BSD_NODUMP_FLAG = 0x00000001;
+
+function fileName(path: string): string {
+  return basename(path) || path;
+}
+
+function readMacosFileFlags(path: string): number | null {
+  if (process.platform !== 'darwin') return null;
+
+  try {
+    const raw = execFileSync('/usr/bin/stat', ['-f', '%Xf', path], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1000,
+    }).trim();
+    return raw.length > 0 ? Number.parseInt(raw, 16) : null;
+  } catch {
+    return null;
+  }
+}
+
+function isMacosCloudPlaceholder(path: string): boolean {
+  const flags = readMacosFileFlags(path);
+  if (flags === null) return false;
+  // Both flags can indicate iCloud-on-demand status depending on macOS
+  // release; treat either as a placeholder.
+  return (flags & MACOS_DATALESS_FLAG) !== 0 || (flags & MACOS_BSD_NODUMP_FLAG) !== 0;
+}
+
+function assertNotCloudPlaceholder(path: string): void {
+  if (isMacosCloudPlaceholder(path)) {
+    throw new Error(
+      `Invalid image node: "${fileName(path)}" appears to be a cloud-on-demand placeholder. ` +
+        'Ensure the file is downloaded locally before adding it as an image.',
+    );
+  }
+}
+
+function readHeaderWithDirectFs(path: string, size: number): Buffer {
+  const length = Math.min(IMAGE_HEADER_BYTES, size);
+  const buffer = Buffer.alloc(length);
+  const fd = openSync(path, 'r');
+  try {
+    const bytesRead = readSync(fd, buffer, 0, length, 0);
+    return buffer.subarray(0, bytesRead);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+interface ProcessSpawnError {
+  code?: string;
+  signal?: NodeJS.Signals;
+  status?: number;
+}
+
+function isProcessSpawnError(value: unknown): value is ProcessSpawnError {
+  return value !== null && typeof value === 'object';
+}
+
+function readHeaderWithDd(path: string): Buffer {
+  return execFileSync('/bin/dd', [`if=${path}`, `bs=${IMAGE_HEADER_BYTES}`, 'count=1'], {
+    encoding: 'buffer',
+    maxBuffer: IMAGE_HEADER_BYTES,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: IMAGE_HEADER_READ_TIMEOUT_MS,
+  });
+}
+
+function readHeaderWithTimeout(path: string, size: number): Buffer {
+  // Direct fs read is the fast path on every platform — no fork, no shell,
+  // no timeout required because the kernel either returns bytes immediately
+  // or fails synchronously. The `dd` escape hatch only matters for macOS
+  // cloud-on-demand placeholders, which `assertNotCloudPlaceholder` rejected
+  // at the call site, so this path is safe.
+  try {
+    return readHeaderWithDirectFs(path, size);
+  } catch (directError) {
+    // On macOS, fall through to `/bin/dd` so a kernel-level stall on a path
+    // we did not flag as a placeholder (e.g. an unmounted SMB share that
+    // still satisfies `existsSync`) cannot wedge a Bun fiber.
+    if (process.platform !== 'darwin' || !existsSync('/bin/dd')) {
+      throw directError;
+    }
+    try {
+      return readHeaderWithDd(path);
+    } catch (ddError) {
+      const reason = isProcessSpawnError(ddError) ? ddError : null;
+      const timedOut = reason?.signal === 'SIGTERM' || reason?.code === 'ETIMEDOUT';
+      if (timedOut) {
+        throw new Error(
+          `Invalid image node: could not read image header for "${fileName(path)}" within ${IMAGE_HEADER_READ_TIMEOUT_MS}ms. ` +
+            'If this file is stored in OneDrive, iCloud Drive, or another cloud-on-demand provider, download it locally first.',
+        );
+      }
+      const detail = ddError instanceof Error ? ddError.message : String(ddError);
+      throw new Error(
+        `Invalid image node: could not read "${fileName(path)}" — ${detail}.`,
+      );
+    }
+  }
+}
+
+function hasAscii(buffer: Buffer, offset: number, value: string): boolean {
+  return buffer.subarray(offset, offset + value.length).toString('ascii') === value;
+}
+
+function detectImageMimeType(header: Buffer): string | null {
+  if (
+    header.length >= 8 &&
+    header[0] === 0x89 &&
+    hasAscii(header, 1, 'PNG') &&
+    header[4] === 0x0d &&
+    header[5] === 0x0a &&
+    header[6] === 0x1a &&
+    header[7] === 0x0a
+  ) {
+    return 'image/png';
+  }
+
+  if (header.length >= 3 && header[0] === 0xff && header[1] === 0xd8 && header[2] === 0xff) {
+    return 'image/jpeg';
+  }
+
+  if (header.length >= 6 && (hasAscii(header, 0, 'GIF87a') || hasAscii(header, 0, 'GIF89a'))) {
+    return 'image/gif';
+  }
+
+  if (header.length >= 12 && hasAscii(header, 0, 'RIFF') && hasAscii(header, 8, 'WEBP')) {
+    return 'image/webp';
+  }
+
+  if (header.length >= 2 && hasAscii(header, 0, 'BM')) {
+    return 'image/bmp';
+  }
+
+  if (
+    header.length >= 4 &&
+    header[0] === 0x00 &&
+    header[1] === 0x00 &&
+    (header[2] === 0x01 || header[2] === 0x02) &&
+    header[3] === 0x00
+  ) {
+    return 'image/x-icon';
+  }
+
+  if (header.length >= 12 && hasAscii(header, 4, 'ftyp')) {
+    const brandArea = header.subarray(8, Math.min(header.length, 32)).toString('ascii');
+    if (brandArea.includes('avif') || brandArea.includes('avis')) return 'image/avif';
+  }
+
+  const text = header.toString('utf8').replace(/^\uFEFF/, '').trimStart().toLowerCase();
+  if (text.startsWith('<svg') || (text.startsWith('<?xml') && text.includes('<svg'))) {
+    return 'image/svg+xml';
+  }
+
+  return null;
+}
+
+export function validateLocalImageFile(path: string): { mimeType: string } {
+  const name = fileName(path);
+  if (!existsSync(path)) {
+    throw new Error(`Invalid image node: "${name}" does not exist.`);
+  }
+
+  const stat = statSync(path);
+  if (!stat.isFile()) {
+    throw new Error(`Invalid image node: "${name}" is not a regular file.`);
+  }
+  if (stat.size <= 0) {
+    throw new Error(`Invalid image node: "${name}" is empty.`);
+  }
+
+  const ext = name.split('.').pop()?.toLowerCase() ?? '';
+  if (!IMAGE_MIME_MAP[ext]) {
+    throw new Error(
+      `Invalid image node: "${name}" has unsupported extension ".${ext}". ` +
+        `Accepted: ${Object.keys(IMAGE_MIME_MAP).join(', ')}. ` +
+        'For non-image files use type="file" (live viewer) or type="webpage" (URL) instead.',
+    );
+  }
+
+  assertNotCloudPlaceholder(path);
+  const header = readHeaderWithTimeout(path, stat.size);
+  const mimeType = detectImageMimeType(header);
+  if (!mimeType) {
+    throw new Error(
+      `Invalid image node: "${name}" is not a recognized image file. ` +
+        'Expected PNG, JPEG, GIF, SVG, WebP, BMP, ICO, or AVIF image bytes.',
+    );
+  }
+
+  return { mimeType };
+}

package/src/server/server.ts

@@ -36,6 +36,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { basename, extname, join, relative, resolve } from 'node:path';
 import * as marked from 'marked';
 import type {
@@ -67,6 +68,7 @@ import { diffLayouts, formatDiff, mutationHistory } from './mutation-history.js'
 import { buildCanvasSummary, serializeCanvasLayout, serializeCanvasNode } from './canvas-serialization.js';
 import { buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
+import { validateLocalImageFile } from './image-source.js';
 import {
   addCanvasNode,
   addCanvasEdge,
@@ -1091,7 +1093,7 @@ async function handleCanvasViewport(req: Request): Promise<Response> {
 }
 
 // ── Serve image file for image nodes ─────────────────────────
-function handleCanvasImage(pathname: string): Response {
+async function handleCanvasImage(pathname: string): Promise<Response> {
   const nodeId = pathname.replace('/api/canvas/image/', '');
   const node = canvasState.getNode(nodeId);
   if (!node || node.type !== 'image') {
@@ -1105,9 +1107,13 @@ function handleCanvasImage(pathname: string): Response {
   if (!existsSync(safePath)) {
     return responseText('Image file not found', 404);
   }
-  const ext = safePath.split('.').pop()?.toLowerCase() ?? '';
-  const contentType = IMAGE_MIME_MAP[ext] || 'application/octet-stream';
-  const data = readFileSync(safePath);
+  let contentType: string;
+  try {
+    contentType = validateLocalImageFile(safePath).mimeType;
+  } catch (error) {
+    return responseText(error instanceof Error ? error.message : 'Invalid image file', 400);
+  }
+  const data = await readFile(safePath);
   return new Response(data, {
     headers: {
       'Content-Type': contentType,
@@ -3773,7 +3779,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
           }
 
           if (url.pathname.startsWith('/api/canvas/image/') && req.method === 'GET') {
-            return handleCanvasImage(url.pathname);
+            return await handleCanvasImage(url.pathname);
           }
 
           if (url.pathname === '/api/canvas/edge' && req.method === 'POST') {