@1agh/maude 0.58.2 → 0.59.0

package/apps/studio/figma/comments-to-strokes.test.ts

@@ -0,0 +1,194 @@
+// figma/comments-to-strokes.ts — the review record.
+//
+// Comments live on their own endpoint, nowhere in the document tree, so every
+// tree-walking version of this importer brought across exactly zero of them.
+
+import { describe, expect, test } from 'bun:test';
+
+import { STICKY_PALETTE } from '../annotations-model.ts';
+import type { FigmaComment } from './client.ts';
+import { commentsToStrokes, indexNodes, MAX_COMMENT_STROKES } from './comments-to-strokes.ts';
+import { ImportReport } from './sanitize.ts';
+import { normalizeDocument } from './types.ts';
+
+const KEY = 'dGNzRC2kmrmGnOxaBa0RI7';
+
+function page() {
+  const doc = normalizeDocument(
+    {
+      id: '0:0',
+      name: 'Page',
+      type: 'CANVAS',
+      children: [
+        {
+          id: '1:2',
+          name: 'Screen',
+          type: 'FRAME',
+          visible: true,
+          absoluteBoundingBox: { x: 1000, y: 500, width: 375, height: 812 },
+        },
+      ],
+    },
+    { fileKey: KEY, surface: 'design' }
+  );
+  return doc.root;
+}
+
+const comment = (over: Partial<FigmaComment> = {}): FigmaComment => ({
+  id: 'c1',
+  message: 'Chybí',
+  nodeId: '1:2',
+  x: 20,
+  y: 30,
+  resolved: false,
+  ...over,
+});
+
+const ORIGIN = { x: 1000, y: 500 };
+
+describe('positioning', () => {
+  test('a pin lands at its node position plus its offset, page-normalized', () => {
+    const { strokes } = commentsToStrokes(
+      [comment()],
+      indexNodes(page()),
+      ORIGIN,
+      new ImportReport()
+    );
+    expect(strokes).toHaveLength(1);
+    expect(strokes[0]).toMatchObject({ tool: 'sticky', x: 20, y: 30 });
+  });
+
+  test('a comment pinned to a node on another page is counted, not silently lost', () => {
+    const report = new ImportReport();
+    const { strokes, unplacedIds } = commentsToStrokes(
+      [comment({ nodeId: '9:9' })],
+      indexNodes(page()),
+      ORIGIN,
+      report
+    );
+    expect(strokes).toHaveLength(0);
+    expect(unplacedIds).toHaveLength(1);
+  });
+
+  test('a canvas-level pin uses its page coordinates directly', () => {
+    const { strokes } = commentsToStrokes(
+      [comment({ nodeId: '0:0', x: 1100, y: 600 })],
+      indexNodes(page()),
+      ORIGIN,
+      new ImportReport(),
+      '0:0'
+    );
+    expect(strokes[0]).toMatchObject({ x: 100, y: 100 });
+  });
+});
+
+describe('threads', () => {
+  test('replies fold into their root card in time order', () => {
+    const { strokes } = commentsToStrokes(
+      [
+        comment({ id: 'root', message: 'A/b test', author: 'maj' }),
+        comment({ id: 'r2', parentId: 'root', message: 'second', createdAt: '2026-02-01' }),
+        comment({ id: 'r1', parentId: 'root', message: 'first', createdAt: '2026-01-01' }),
+      ],
+      indexNodes(page()),
+      ORIGIN,
+      new ImportReport()
+    );
+    expect(strokes).toHaveLength(1);
+    expect((strokes[0] as { text: string }).text).toBe('maj: A/b test\n↳ first\n↳ second');
+  });
+});
+
+describe('resolved threads', () => {
+  test('are carried on grey paper rather than dropped', () => {
+    // A resolved comment is the record of a decision already made; dropping it
+    // is the same silent content loss the rest of this importer keeps relearning.
+    const { strokes } = commentsToStrokes(
+      [comment({ resolved: true })],
+      indexNodes(page()),
+      ORIGIN,
+      new ImportReport()
+    );
+    expect(strokes).toHaveLength(1);
+    expect((strokes[0] as { color: string }).color).toBe(STICKY_PALETTE[2]);
+    expect((strokes[0] as { text: string }).text).toStartWith('✓ ');
+  });
+
+  test('an open thread stays on the default yellow', () => {
+    const { strokes } = commentsToStrokes(
+      [comment()],
+      indexNodes(page()),
+      ORIGIN,
+      new ImportReport()
+    );
+    expect((strokes[0] as { color: string }).color).toBe(STICKY_PALETTE[0]);
+  });
+});
+
+describe('bounds', () => {
+  test('message text goes through the zero-glyph strip like every other import', () => {
+    const report = new ImportReport();
+    // U+E0041 — Unicode Tags block, zero glyphs, a payload channel.
+    const { strokes } = commentsToStrokes(
+      [comment({ message: `ok\u{E0041}` })],
+      indexNodes(page()),
+      ORIGIN,
+      report
+    );
+    expect((strokes[0] as { text: string }).text).toBe('ok');
+    expect(report.entries.some((e) => e.disposition === 'hidden-chars-dropped')).toBe(true);
+  });
+
+  test('an empty message produces no card', () => {
+    const { strokes } = commentsToStrokes(
+      [comment({ message: '   ' })],
+      indexNodes(page()),
+      ORIGIN,
+      new ImportReport()
+    );
+    expect(strokes).toHaveLength(0);
+  });
+
+  test('a pathological comment count is capped and reported', () => {
+    const many = Array.from({ length: MAX_COMMENT_STROKES + 25 }, (_, i) =>
+      comment({ id: `c${i}` })
+    );
+    const report = new ImportReport();
+    const { strokes } = commentsToStrokes(many, indexNodes(page()), ORIGIN, report);
+    expect(strokes).toHaveLength(MAX_COMMENT_STROKES);
+    expect(report.entries.some((e) => e.disposition === 'asset-cap-reached')).toBe(true);
+  });
+});
+
+describe('orphaned threads (the caller decides, not this module)', () => {
+  test('an unplaceable thread is returned by id, NOT reported here', () => {
+    // Per page, "not on this page" is the normal case — a comment lives on
+    // exactly one page. Reporting it here would fire once per page and read as
+    // content loss that never happened. Only the caller, which sees every page,
+    // can tell an unplaced thread from a deleted-target orphan.
+    const report = new ImportReport();
+    const { strokes, placedIds, unplacedIds } = commentsToStrokes(
+      [comment({ id: 'here' }), comment({ id: 'elsewhere', nodeId: '9:9' })],
+      indexNodes(page()),
+      ORIGIN,
+      report
+    );
+    expect(strokes).toHaveLength(1);
+    expect(placedIds).toEqual(['here']);
+    expect(unplacedIds).toEqual(['elsewhere']);
+    expect(report.entries.some((e) => e.disposition === 'comment-target-deleted')).toBe(false);
+  });
+
+  test('placedIds are raw Figma ids so the caller can intersect them', () => {
+    // The stroke id is sanitized (`figc_…`); the caller reconciles across pages
+    // on the RAW id, and a mismatch there would silently orphan every thread.
+    const { strokes, placedIds } = commentsToStrokes(
+      [comment({ id: '166-92:86' })],
+      indexNodes(page()),
+      ORIGIN,
+      new ImportReport()
+    );
+    expect(placedIds).toEqual(['166-92:86']);
+    expect((strokes[0] as { id: string }).id).not.toBe('166-92:86');
+  });
+});

package/apps/studio/figma/comments-to-strokes.ts

@@ -0,0 +1,173 @@
+/**
+ * @file       figma/comments-to-strokes.ts — Figma review comments → annotations.
+ * @scope      apps/studio/figma/comments-to-strokes.ts
+ * @purpose    Bring across the notes a designer actually left on a file.
+ *
+ * @rationale  Figma comments live on `/v1/files/:key/comments`, NOWHERE in the
+ *             document tree. An importer that walks the tree — which is every
+ *             version of this one until now — therefore misses every single
+ *             one. The live StudyFi file carries 133 of them ("Chybí", "A/b
+ *             test", "redirect do nastaveni…"): the actual review record, the
+ *             part a handoff is FOR, imported as zero.
+ *
+ * @invariant  A COMMENT IS DATA. The message is third-party free text: it goes
+ *             through `cleanText`'s zero-glyph strip and length bound like every
+ *             other imported string, is never parsed, and never reaches anything
+ *             that could act on it (DDR-216 D1/D6a).
+ *
+ * @invariant  RESOLVED THREADS ARE CARRIED, NOT DROPPED. A resolved comment is
+ *             the record of a decision already made; discarding it silently is
+ *             the same content loss this importer keeps relearning. They arrive
+ *             on grey paper instead of yellow.
+ */
+
+import {
+  DEFAULT_STICKY_COLOR,
+  STICKY_PALETTE,
+  type StickyStroke,
+  type Stroke,
+} from '../annotations-model.ts';
+import type { FigmaComment } from './client.ts';
+import { cleanText, type ImportReport } from './sanitize.ts';
+import type { FigmaNode } from './types.ts';
+
+/** Matches the sticky cap in `to-strokes.ts` — a thread is not an essay. */
+const COMMENT_TEXT_CAP = 1200;
+/** Paper size. Wide enough for a sentence, short enough not to bury the design. */
+const CARD_W = 240;
+const CARD_MIN_H = 120;
+const CARD_MAX_H = 520;
+const CARD_FONT = 13;
+/** Rough wrap width in characters at `CARD_FONT` — height is estimated, not laid out. */
+const CHARS_PER_LINE = 30;
+const LINE_H = 18;
+/** Grey paper for a settled thread; slot 0 (yellow) stays "still open". */
+const RESOLVED_COLOR = STICKY_PALETTE[2];
+/** A pathological file should not paper the canvas over. */
+export const MAX_COMMENT_STROKES = 300;
+
+export interface CommentStrokesResult {
+  strokes: Stroke[];
+  /** Thread ids this page placed. Raw Figma ids, matching `unplacedIds`. */
+  placedIds: string[];
+  /**
+   * Thread ids this page could not place, because the node they name is not in
+   * it. Per page that is NORMAL — a comment lives on exactly one page — so this
+   * is deliberately not reported here. The caller intersects it across every
+   * page; a thread unplaced EVERYWHERE is an orphan whose target was deleted
+   * from the file, and only the caller can know that.
+   */
+  unplacedIds: string[];
+}
+
+/** Index every node on a page by id, so a pin can find what it hangs off. */
+export function indexNodes(root: FigmaNode): Map<string, FigmaNode> {
+  const out = new Map<string, FigmaNode>();
+  const walk = (n: FigmaNode): void => {
+    out.set(n.id, n);
+    for (const c of n.children ?? []) walk(c);
+  };
+  walk(root);
+  return out;
+}
+
+/**
+ * Turn a file's comments into sticky annotations positioned over the page.
+ *
+ * World coordinates match the artboards: the pin sits at its target node's
+ * absolute position plus the comment's offset within that node, normalized to
+ * the same page origin the canvas used.
+ */
+export function commentsToStrokes(
+  comments: readonly FigmaComment[],
+  nodes: ReadonlyMap<string, FigmaNode>,
+  origin: { x: number; y: number },
+  report: ImportReport,
+  pageId?: string
+): CommentStrokesResult {
+  // Replies hang off their root pin; only roots get a card.
+  const repliesByParent = new Map<string, FigmaComment[]>();
+  const roots: FigmaComment[] = [];
+  for (const c of comments) {
+    if (c.parentId) {
+      const list = repliesByParent.get(c.parentId);
+      if (list) list.push(c);
+      else repliesByParent.set(c.parentId, [c]);
+    } else {
+      roots.push(c);
+    }
+  }
+
+  const strokes: Stroke[] = [];
+  const placedIds: string[] = [];
+  const unplacedIds: string[] = [];
+
+  for (const root of roots) {
+    if (strokes.length >= MAX_COMMENT_STROKES) {
+      report.add(root.id, 'COMMENT', 'asset-cap-reached', `>${MAX_COMMENT_STROKES} comments`);
+      break;
+    }
+
+    // Where does this pin live? Either inside a node on this page, or — for a
+    // canvas-level pin — at page coordinates directly.
+    let wx: number;
+    let wy: number;
+    if (root.nodeId && root.nodeId !== pageId) {
+      const target = nodes.get(root.nodeId);
+      const bb = target?.absoluteBoundingBox;
+      if (!bb) {
+        unplacedIds.push(root.id);
+        continue;
+      }
+      wx = bb.x + (root.x ?? 0);
+      wy = bb.y + (root.y ?? 0);
+    } else if (root.x !== undefined && root.y !== undefined) {
+      wx = root.x;
+      wy = root.y;
+    } else {
+      unplacedIds.push(root.id);
+      continue;
+    }
+
+    const body = composeThread(root, repliesByParent.get(root.id) ?? []);
+    const clean = cleanText(body, COMMENT_TEXT_CAP);
+    if (clean.strippedHidden) report.add(root.id, 'COMMENT', 'hidden-chars-dropped');
+    if (clean.truncated) report.add(root.id, 'COMMENT', 'truncated-text');
+    if (!clean.text.trim()) continue;
+
+    const lines = clean.text
+      .split('\n')
+      .reduce((n, l) => n + Math.max(1, Math.ceil(l.length / CHARS_PER_LINE)), 0);
+    const h = Math.min(CARD_MAX_H, Math.max(CARD_MIN_H, lines * LINE_H + 24));
+
+    const card: StickyStroke = {
+      id: `figc_${root.id.replace(/[^0-9A-Za-z]+/g, '_')}`,
+      tool: 'sticky',
+      color: root.resolved ? RESOLVED_COLOR : DEFAULT_STICKY_COLOR,
+      x: Math.round(wx - origin.x),
+      y: Math.round(wy - origin.y),
+      w: CARD_W,
+      h: Math.round(h),
+      text: clean.text,
+      fontSize: CARD_FONT,
+    };
+    strokes.push(card);
+    placedIds.push(root.id);
+    report.add(root.id, 'COMMENT', 'imported', root.resolved ? 'resolved' : 'open');
+  }
+
+  return { strokes, placedIds, unplacedIds };
+}
+
+/**
+ * One thread as one card's body. The author handle is provenance shown as text
+ * — a display string, never an identifier anything acts on (D7).
+ */
+function composeThread(root: FigmaComment, replies: readonly FigmaComment[]): string {
+  const head = root.resolved ? '✓ ' : '';
+  const who = (c: FigmaComment) => (c.author ? `${c.author}: ` : '');
+  const parts = [`${head}${who(root)}${root.message}`];
+  const ordered = [...replies].sort((a, b) => (a.createdAt ?? '').localeCompare(b.createdAt ?? ''));
+  for (const r of ordered) parts.push(`↳ ${who(r)}${r.message}`);
+  return parts.join('\n');
+}

package/apps/studio/figma/endpoints.ts

@@ -0,0 +1,273 @@
+// figma/endpoints.ts — `/_api/figma/*` orchestration (DDR-216 D2 + D3).
+//
+// Pure handlers behind the three Figma routes: validate inputs, call the key
+// store or the REST client, and shape a `{ status, json }` result. NO HTTP /
+// Request dependency — http.ts owns the gating (method · loopback Host ·
+// same-origin CSRF · body byte cap) and this module owns orchestration,
+// mirroring github/endpoints.ts and git/endpoints.ts.
+//
+// SECURITY — the three properties this file exists to hold (DDR-216):
+//
+//   1. MAIN-ORIGIN ONLY, by omission from BOTH CANVAS_SAFE_API (http.ts) and
+//      startCanvasServer's `routes` map (server.ts). A canvas-reachable Figma
+//      route is simultaneously a token-exfiltration primitive and an SSRF
+//      primitive, and canvases run as real unsandboxed JS on a separate origin
+//      (DDR-054) — so the gate is that the route does not exist from there.
+//      `test/canvas-origin-gate.test.ts` asserts all three 403 at the gate on
+//      the canvas origin (403, not 405 — the request never reaches a handler).
+//      That is only HALF the property: the MAIN origin is reachable from any
+//      page the user visits, so http.ts also applies `isTrustedRequestHost` +
+//      `sameOriginWrite` (writes) / `sameOriginRead` (the status GET, where a
+//      browser may omit `Origin`). `test/figma-routes.test.ts` owns that half.
+//
+//   2. THE KEY IS NEVER ECHOED. `connect` returns `{ configured: true }`;
+//      `status` returns presence only. Neither reads the stored value back —
+//      the same discipline `/_api/generate/keys` states in its own comment, so
+//      a proxy or a log between here and the client cannot capture it.
+//
+//   3. `figma` IS NOT A MEDIA-GENERATION PROVIDER. It produces no Modality and
+//      needs no AdapterFactory, so it is deliberately absent from
+//      generation/registry.ts; these routes call the key STORE directly. That
+//      also keeps ONE write path for the secret — two would be how one of them
+//      ends up ungated (DDR-216 D2, a Round-1 security finding).
+
+import { deleteProviderKey, isConfigured, setProviderKey } from '../generation/keys.ts';
+import { FigmaApiError, fetchIdentity } from './client.ts';
+
+/** The provider id under which the PAT lives in `~/.config/maude/keys.json`. */
+export const FIGMA_PROVIDER_ID = 'figma';
+
+/** Where a user mints one, and the granular scope to ask for. The blanket
+ *  `files:read` scope is deprecated — never name it in UI or docs. */
+export const FIGMA_TOKEN_URL = 'https://www.figma.com/developers/api#access-tokens';
+export const FIGMA_REQUIRED_SCOPE = 'file_content:read';
+
+export interface FigmaEndpointResult {
+  status: number;
+  json: unknown;
+}
+
+/**
+ * Figma PATs are opaque, but they are not arbitrary text: bounding the shape
+ * here means a paste accident (a whole URL, a JSON blob, a stray newline) fails
+ * at the boundary rather than becoming a stored "key" that produces a confusing
+ * 401 later. Deliberately permissive on the alphabet and strict on everything
+ * structural — printable ASCII only, no whitespace, bounded length.
+ */
+const TOKEN_SHAPE_RE = /^[!-~]{20,255}$/;
+
+/**
+ * `/v1/me` returns a handle we display as "Connected as …". It is
+ * upstream-controlled, so it is length- and charset-bounded before it ever
+ * reaches client state, and it is NEVER persisted into config.json or any
+ * versioned file (DDR-216 D6 sink table).
+ */
+export function boundDisplayHandle(raw: string): string {
+  return raw
+    .normalize('NFC')
+    .replace(/[^\p{L}\p{N} ._@-]/gu, '')
+    .trim()
+    .slice(0, 64);
+}
+
+export interface FigmaImportRequest {
+  url: string;
+  mode: 'board' | 'frames' | 'tokens';
+  dryRun?: boolean;
+}
+
+export interface FigmaExplodeRequest {
+  /** Canvas path RELATIVE to the design root. Never absolute, never `..`. */
+  canvas: string;
+  /** The `DCArtboard` id. Code-computed at import time, so a strict charset. */
+  artboard: string;
+  dryRun?: boolean;
+  confirmDocument?: boolean;
+}
+
+/**
+ * Validate an explode request.
+ *
+ * Narrower than `parseImportRequest`, because this one MUTATES an existing
+ * reviewed, versioned, peer-synced artifact. The caller supplies a target and
+ * nothing else: no output path, no node id, no URL, no size. Everything else is
+ * read from what the deterministic import already recorded (DDR-219 D8, which
+ * inherits DDR-216 D3's "the producer never picks its own target").
+ */
+export function parseExplodeRequest(body: unknown): FigmaExplodeRequest | null {
+  if (!body || typeof body !== 'object') return null;
+  const b = body as Record<string, unknown>;
+  if (typeof b.canvas !== 'string' || b.canvas.length === 0 || b.canvas.length > 512) return null;
+  // Traversal is refused HERE as well as by the verb's realpath containment.
+  // Two independent checks, because this one is cheap and the failure is total.
+  if (b.canvas.includes('..') || b.canvas.startsWith('/') || /^[A-Za-z]:/.test(b.canvas)) {
+    return null;
+  }
+  if (!b.canvas.endsWith('.tsx')) return null;
+  if (typeof b.artboard !== 'string' || !/^[a-z0-9-]{1,64}$/.test(b.artboard)) return null;
+  return {
+    canvas: b.canvas,
+    artboard: b.artboard,
+    dryRun: b.dryRun === true,
+    confirmDocument: b.confirmDocument === true,
+  };
+}
+
+export interface FigmaEndpoints {
+  /** POST — store a PAT. Returns presence only, never the value. */
+  connect(body: unknown): FigmaEndpointResult;
+  /** DELETE — forget the PAT. */
+  disconnect(): FigmaEndpointResult;
+  /** GET — presence only. Reveals whether a key exists, never what it is. */
+  status(): FigmaEndpointResult;
+  /** POST — validate the stored token against `GET /v1/me`. */
+  probe(): Promise<FigmaEndpointResult>;
+  /** POST — run an import. Same work the CLI verb does, same guarantees. */
+  runImport(body: unknown): Promise<FigmaEndpointResult>;
+  /** POST — make ONE already-imported artboard editable via Dev Mode codegen. */
+  explode(body: unknown): Promise<FigmaEndpointResult>;
+}
+
+/**
+ * Validate an import request into a typed shape.
+ *
+ * Deliberately narrow: a mode from a fixed enum, a URL that `figma/url.ts` will
+ * reject if it is not a real Figma URL, and a boolean. No slug, no path, no
+ * output location — the caller does not get to choose where anything lands
+ * (the same reason DDR-174 has its orchestrator compute the target path rather
+ * than letting the producer pick one).
+ */
+export function parseImportRequest(body: unknown): FigmaImportRequest | null {
+  if (!body || typeof body !== 'object') return null;
+  const b = body as Record<string, unknown>;
+  const mode = b.mode;
+  if (mode !== 'board' && mode !== 'frames' && mode !== 'tokens') return null;
+  if (typeof b.url !== 'string' || b.url.length === 0 || b.url.length > 2048) return null;
+  return { url: b.url, mode, dryRun: b.dryRun === true };
+}
+
+export interface FigmaEndpointDeps {
+  /**
+   * Runs the import. Injected so this module stays HTTP- and fs-free (the same
+   * split github/endpoints.ts uses) and so the route can be tested without a
+   * network. The real implementation is `bin/_import-figma.mjs`.
+   */
+  runImport?(req: FigmaImportRequest): Promise<{
+    summary: Record<string, unknown>;
+  }>;
+  /** Same injection, same reason. The real implementation is the verb's
+   *  `explodeArtboard`, so the panel and the CLI cannot drift apart in what
+   *  they validate, cap or report. */
+  explode?(req: FigmaExplodeRequest): Promise<{ summary: Record<string, unknown> }>;
+}
+
+export function createFigmaEndpoints(deps: FigmaEndpointDeps = {}): FigmaEndpoints {
+  return {
+    connect(body: unknown): FigmaEndpointResult {
+      if (!body || typeof body !== 'object') {
+        return { status: 400, json: { error: 'token required' } };
+      }
+      const token = (body as Record<string, unknown>).token;
+      if (typeof token !== 'string' || !TOKEN_SHAPE_RE.test(token.trim())) {
+        // Fixed message — never echoes what was sent (DDR-216 D10).
+        return { status: 400, json: { error: 'that does not look like a Figma access token' } };
+      }
+      try {
+        setProviderKey(FIGMA_PROVIDER_ID, token.trim());
+      } catch {
+        return { status: 400, json: { error: 'could not store the token' } };
+      }
+      // Presence flag only. Deliberately does NOT read the value back.
+      return { status: 200, json: { configured: isConfigured(FIGMA_PROVIDER_ID) } };
+    },
+
+    disconnect(): FigmaEndpointResult {
+      deleteProviderKey(FIGMA_PROVIDER_ID);
+      return { status: 200, json: { configured: false } };
+    },
+
+    status(): FigmaEndpointResult {
+      return {
+        status: 200,
+        json: {
+          configured: isConfigured(FIGMA_PROVIDER_ID),
+          tokenUrl: FIGMA_TOKEN_URL,
+          requiredScope: FIGMA_REQUIRED_SCOPE,
+        },
+      };
+    },
+
+    async probe(): Promise<FigmaEndpointResult> {
+      try {
+        const identity = await fetchIdentity();
+        return { status: 200, json: { ok: true, handle: boundDisplayHandle(identity.handle) } };
+      } catch (err) {
+        if (err instanceof FigmaApiError) {
+          // `err.message` is a fixed, code-owned string from MESSAGE_BY_KIND —
+          // it carries no upstream text, no header and no token (D2/D10).
+          const status = err.kind === 'not_configured' ? 400 : 502;
+          return { status, json: { ok: false, reason: err.kind, error: err.message } };
+        }
+        return {
+          status: 502,
+          json: { ok: false, reason: 'network', error: 'Figma probe failed.' },
+        };
+      }
+    },
+
+    async runImport(body: unknown): Promise<FigmaEndpointResult> {
+      const req = parseImportRequest(body);
+      if (!req) return { status: 400, json: { error: 'mode and url are required' } };
+      if (!deps.runImport) {
+        return { status: 501, json: { error: 'import is not available in this shell' } };
+      }
+      try {
+        const { summary } = await deps.runImport(req);
+        // The summary is the SAME code-generated, enum-coded accounting the CLI
+        // prints (DDR-216 D7/D10) — node ids and reason codes, never node text.
+        // It is safe to hand to a client precisely BECAUSE of that.
+        return { status: 200, json: { ok: true, ...summary } };
+      } catch (err) {
+        if (err instanceof FigmaApiError) {
+          return {
+            status: err.kind === 'not_configured' ? 400 : 502,
+            json: { ok: false, reason: err.kind, error: err.message },
+          };
+        }
+        // Anything else is reported generically — an import failure message must
+        // never become a channel for an upstream string (D10).
+        return { status: 500, json: { ok: false, reason: 'failed', error: 'Import failed.' } };
+      }
+    },
+
+    async explode(body: unknown): Promise<FigmaEndpointResult> {
+      const req = parseExplodeRequest(body);
+      if (!req) return { status: 400, json: { error: 'canvas and artboard are required' } };
+      if (!deps.explode) {
+        return { status: 501, json: { error: 'codegen is not available in this shell' } };
+      }
+      try {
+        const { summary } = await deps.explode(req);
+        return { status: 200, json: { ok: true, ...summary } };
+      } catch (err) {
+        // Codegen being unavailable is the COMMON case (no Dev/Full seat, Figma
+        // desktop not running, Dev Mode off, wrong tab). It is a 409, not a 500:
+        // nothing is wrong with the request or with us. The reason code is the
+        // client's OWN enum — `CodegenError.kind` / `CodegenConvertError.reason`
+        // are code-owned strings from fixed tables, never upstream text.
+        const kind = (err as { kind?: string; reason?: string } | null)?.kind;
+        const reason = (err as { reason?: string } | null)?.reason;
+        if (typeof kind === 'string') {
+          return {
+            status: 409,
+            json: { ok: false, reason: kind, error: (err as Error).message },
+          };
+        }
+        if (typeof reason === 'string') {
+          return { status: 422, json: { ok: false, reason, error: (err as Error).message } };
+        }
+        return { status: 500, json: { ok: false, reason: 'failed', error: 'Explode failed.' } };
+      }
+    },
+  };
+}