@cat-factory/integrations 0.25.2 → 0.26.0

package/dist/modules/documents/figma.logic.js

@@ -0,0 +1,249 @@
+import { assertHostPinned } from './http.js';
+// Figma-specific pure logic, kept out of the provider shell so it is unit-testable
+// without a live workspace: parsing/canonicalising a file+node ref out of user input,
+// the fixed-host SSRF guard, and converting the Figma node/variables JSON into the
+// lightweight Markdown the generic planner + `.cat-context/` materialisation consume.
+// The `fetch` itself (the `X-Figma-Token` REST client) lives in `FigmaProvider`.
+/** Figma's REST API host. The PAT is sent to this host only — see {@link assertSafeFigmaUrl}. */
+export const FIGMA_API_HOST = 'api.figma.com';
+/** What the connect UI renders, and which credentials the provider needs. */
+export const FIGMA_DESCRIPTOR = {
+    source: 'figma',
+    label: 'Figma',
+    icon: 'i-lucide-figma',
+    credentialFields: [
+        {
+            key: 'apiToken',
+            label: 'Personal access token',
+            secret: true,
+            placeholder: 'figd_…',
+            help: 'Create a personal access token at figma.com → Settings → Security → Personal access tokens (file_content + file_variables read scopes). Design tokens require an Enterprise plan; without it the tokens section is simply omitted.',
+        },
+    ],
+    refLabel: 'Figma file or frame URL',
+    refPlaceholder: 'https://www.figma.com/design/<key>/Title?node-id=1-2',
+    // No catalogue search API for a PAT — import a specific file/frame by URL.
+    searchable: false,
+};
+/**
+ * The Figma REST host is fixed, so any request/redirect must stay on
+ * `api.figma.com` over https. A redirect off-host (e.g. to an internal address)
+ * is treated as an SSRF attempt and rejected. Mirrors the per-hop guard the other
+ * document providers run. Throws a plain `Error` (the provider maps it to a
+ * `FigmaApiError`); kept pure so it is unit-testable without a network.
+ */
+export function assertSafeFigmaUrl(url) {
+    assertHostPinned(url, FIGMA_API_HOST, 'Figma');
+}
+// ---- Ref parsing + canonical URL ------------------------------------------
+/**
+ * Normalise a Figma node id to the API/colon form. Figma share URLs encode a
+ * node id as `1234-5678` (dash) where the REST API expects `1234:5678` (colon);
+ * a `?node-id=1234%3A5678` decodes straight to the colon form. We accept either
+ * and return the colon form, or null for anything that isn't a simple
+ * `n` / `n:n` node id (complex instance ids like `I12:3;45:6` are dropped → the
+ * import falls back to the whole file rather than guessing).
+ */
+export function normalizeFigmaNodeId(raw) {
+    const value = raw.trim();
+    if (!value)
+        return null;
+    const colon = value.includes(':') ? value : value.replace(/-/g, ':');
+    if (/^\d+:\d+$/.test(colon) || /^\d+$/.test(colon))
+        return colon;
+    return null;
+}
+/**
+ * Resolve a Figma reference from raw user input into the stable composite
+ * external id this provider stores: `"<fileKey>"` for a whole-file link, or
+ * `"<fileKey>:<nodeId>"` for a specific frame/node (nodeId in colon form).
+ * Accepts a `figma.com` file/design/proto/board URL, a bare file key, or a
+ * `fileKey:node:id` string. Returns null when no file key is found.
+ *
+ * `parseRef` is deterministic (same input → same external id), which is what the
+ * `(workspace, source, externalId)` document key relies on for de-duplication —
+ * URL auto-match via `getByUrl` is a separate, best-effort path keyed on the
+ * canonical {@link figmaUrlFor} output.
+ */
+export function parseFigmaRef(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    // Bare ref: a file key, optionally `:`-suffixed with a node id. Only when it is
+    // clearly not a URL (no scheme, no slash, not a figma.com host).
+    if (!trimmed.includes('/') && !/figma\.com/i.test(trimmed)) {
+        const [key, ...rest] = trimmed.split(':');
+        if (!key || !/^[A-Za-z0-9]+$/.test(key))
+            return null;
+        if (rest.length === 0)
+            return key;
+        const node = normalizeFigmaNodeId(rest.join(':'));
+        return node ? `${key}:${node}` : key;
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (!/(^|\.)figma\.com$/i.test(url.hostname))
+        return null;
+    const match = url.pathname.match(/\/(?:file|design|proto|board)\/([A-Za-z0-9]+)/);
+    if (!match)
+        return null;
+    const fileKey = match[1];
+    const nodeRaw = url.searchParams.get('node-id');
+    if (!nodeRaw)
+        return fileKey;
+    const node = normalizeFigmaNodeId(nodeRaw);
+    return node ? `${fileKey}:${node}` : fileKey;
+}
+/** Split a composite external id back into its file key and optional node id (colon form). */
+export function splitFigmaExternalId(externalId) {
+    const idx = externalId.indexOf(':');
+    if (idx === -1)
+        return { fileKey: externalId };
+    return { fileKey: externalId.slice(0, idx), nodeId: externalId.slice(idx + 1) };
+}
+/**
+ * Build the canonical web URL stored on the imported document (and matched by
+ * `getByUrl`). The node id is rendered back in the share-URL dash form so the
+ * stored URL matches the kind of link a teammate pastes into a task description.
+ */
+export function figmaUrlFor(externalId) {
+    const { fileKey, nodeId } = splitFigmaExternalId(externalId);
+    const base = `https://www.figma.com/design/${fileKey}`;
+    if (!nodeId)
+        return base;
+    return `${base}?node-id=${nodeId.replace(/:/g, '-')}`;
+}
+const MAX_TREE_DEPTH = 6;
+const MAX_TREE_NODES = 400;
+function dimensionLabel(node) {
+    const box = node.absoluteBoundingBox;
+    if (!box || box.width == null || box.height == null)
+        return '';
+    return ` (${Math.round(box.width)}×${Math.round(box.height)})`;
+}
+/**
+ * Render a node and its descendants as an indented bullet tree (name + type +
+ * size), bounded in depth and total nodes so a huge frame can't blow up the
+ * context file. Mutates `counter` to enforce the global node cap.
+ */
+function renderLayout(node, depth, counter, lines) {
+    if (depth > MAX_TREE_DEPTH || counter.n >= MAX_TREE_NODES)
+        return;
+    counter.n++;
+    const indent = '  '.repeat(depth);
+    const name = node.name?.trim() || '(unnamed)';
+    const type = node.type ? ` _${node.type}_` : '';
+    lines.push(`${indent}- ${name}${type}${dimensionLabel(node)}`);
+    for (const child of node.children ?? []) {
+        if (counter.n >= MAX_TREE_NODES) {
+            lines.push(`${indent}  - … (truncated)`);
+            break;
+        }
+        renderLayout(child, depth + 1, counter, lines);
+    }
+}
+/** Collect every TEXT node's `characters`, in document order, bounded. */
+function collectText(node, out) {
+    if (out.length >= MAX_TREE_NODES)
+        return;
+    if (node.type === 'TEXT' && node.characters?.trim())
+        out.push(node.characters.trim());
+    for (const child of node.children ?? [])
+        collectText(child, out);
+}
+/** Collect the distinct design-system components a node tree instantiates. */
+function collectComponents(node, components, out) {
+    if (node.type === 'INSTANCE') {
+        const name = (node.componentId && components[node.componentId]?.name) || node.name?.trim();
+        if (name)
+            out.add(name);
+    }
+    for (const child of node.children ?? [])
+        collectComponents(child, components, out);
+}
+/**
+ * Convert a fetched Figma node (a frame or a whole file's document) into the
+ * lightweight Markdown the planner/agent consume: a `## <name>` heading, a
+ * `### Layout` bullet tree, the `### Text content`, and the distinct
+ * `### Components used` (matched against the repo's components by the agent).
+ */
+export function figmaNodesToMarkdown(roots, components = {}) {
+    const sections = [];
+    for (const root of roots) {
+        const lines = [];
+        lines.push(`## ${root.name?.trim() || '(unnamed frame)'}${dimensionLabel(root)}`);
+        const layout = [];
+        // One counter shared across every top-level child so MAX_TREE_NODES bounds the whole
+        // frame, not each subtree — a wide frame can't blow past the cap one branch at a time.
+        const counter = { n: 0 };
+        for (const child of root.children ?? [])
+            renderLayout(child, 0, counter, layout);
+        if (layout.length) {
+            lines.push('', '### Layout', ...layout);
+        }
+        const text = [];
+        collectText(root, text);
+        if (text.length) {
+            lines.push('', '### Text content', ...text.map((t) => `- ${t.replace(/\s+/g, ' ')}`));
+        }
+        const comps = new Set();
+        collectComponents(root, components, comps);
+        if (comps.size) {
+            lines.push('', '### Components used', ...[...comps].sort().map((c) => `- ${c}`));
+        }
+        sections.push(lines.join('\n').trim());
+    }
+    return sections.join('\n\n').trim();
+}
+/** Render a single variable value (colour object → hex/rgba, else compact JSON). */
+function renderVariableValue(value) {
+    if (value && typeof value === 'object' && 'r' in value) {
+        const c = value;
+        const to255 = (n) => Math.round((n ?? 0) * 255);
+        const hex = [c.r, c.g, c.b].map((n) => to255(n).toString(16).padStart(2, '0')).join('');
+        return c.a != null && c.a < 1 ? `#${hex} (a=${c.a.toFixed(2)})` : `#${hex}`;
+    }
+    if (value && typeof value === 'object' && 'type' in value) {
+        // An alias to another variable — surface its target id.
+        const alias = value;
+        if (alias.type === 'VARIABLE_ALIAS' && alias.id)
+            return `→ ${alias.id}`;
+    }
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? String(value) : value.toFixed(2);
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return String(value);
+    return JSON.stringify(value);
+}
+/**
+ * Convert the Figma local-variables payload into a `### Design tokens` section,
+ * one line per `collection › mode › name = value`. Returns '' when there are no
+ * variables (so the caller drops the section entirely).
+ */
+export function figmaVariablesToMarkdown(meta) {
+    const variables = meta?.variables ?? {};
+    const collections = meta?.variableCollections ?? {};
+    const lines = [];
+    for (const variable of Object.values(variables)) {
+        if (!variable?.name)
+            continue;
+        const collection = variable.variableCollectionId
+            ? collections[variable.variableCollectionId]
+            : undefined;
+        const collectionName = collection?.name ?? 'Tokens';
+        const modes = collection?.modes ?? [];
+        for (const [modeId, value] of Object.entries(variable.valuesByMode ?? {})) {
+            const modeName = modes.find((m) => m.modeId === modeId)?.name ?? 'default';
+            lines.push(`- ${collectionName} › ${modeName} › ${variable.name} = ${renderVariableValue(value)}`);
+        }
+    }
+    if (!lines.length)
+        return '';
+    return ['### Design tokens', ...lines.sort()].join('\n');
+}
+//# sourceMappingURL=figma.logic.js.map

package/dist/modules/documents/figma.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma.logic.js","sourceRoot":"","sources":["../../../src/modules/documents/figma.logic.ts"],"names":[],"mappings":"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"}

package/dist/modules/documents/http.d.ts

@@ -0,0 +1,35 @@
+/** Carries the HTTP status so a provider can surface a meaningful error to the caller. */
+export declare class DocumentHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Assert a request/redirect URL stays on the provider's fixed `host` over https. A
+ * redirect off-host (e.g. to a link-local metadata address) or an http downgrade is
+ * treated as an SSRF attempt and rejected. Throws a plain `Error` so it stays trivially
+ * unit-testable without a network; the caller maps it to a {@link DocumentHttpError}.
+ * `label` names the provider in the message (e.g. `Figma`, `Claude Design`).
+ */
+export declare function assertHostPinned(url: string, host: string, label: string): void;
+export interface HostPinnedFetchOptions {
+    /** The single host this provider's API lives on (e.g. `api.figma.com`). */
+    host: string;
+    /** Provider name used in error messages. */
+    label: string;
+    /** Max redirect hops before giving up (default 5). */
+    maxRedirects?: number;
+}
+/**
+ * Build a `fetch` that follows redirects **by hand** so {@link assertHostPinned} runs
+ * against EVERY hop. With the default `redirect: 'follow'` a 302 from the API could be
+ * chased to an internal target (or downgraded to http), leaking the credential. We force
+ * `redirect: 'manual'`, re-resolve the `Location`, and re-validate before each hop.
+ */
+export declare function createHostPinnedFetch(opts: HostPinnedFetchOptions): (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * Read a response body with a running byte cap so a hostile/huge response can't OOM the
+ * isolate. Checks the declared Content-Length first, then enforces the cap while
+ * streaming. `label` names the provider in the error message.
+ */
+export declare function readCappedText(res: Response, maxBytes: number, label?: string): Promise<string>;
+//# sourceMappingURL=http.d.ts.map

package/dist/modules/documents/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/http.ts"],"names":[],"mappings":"AAaA,0FAA0F;AAC1F,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,MAAM,EAAE,MAAM;IADzB,YACW,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EAIhB;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAa/E;AAKD,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,sBAAsB,GAC3B,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CA0BvD;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,QAAQ,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,SAAa,GACjB,OAAO,CAAC,MAAM,CAAC,CAgCjB"}

package/dist/modules/documents/http.js

@@ -0,0 +1,120 @@
+// Shared HTTP helpers for the host-pinned document-source providers (Figma, Claude
+// Design, …). Every provider that talks to a *fixed* third-party API host shares the
+// same two concerns: (1) keep the credential on the intended host — follow redirects
+// by hand and re-validate every hop so a 302 can't chase the token to an internal
+// address (SSRF) or downgrade it to http; (2) bound the bytes read off any response so
+// a hostile/huge body can't OOM the isolate. Notion/Confluence each grew their own copy
+// of this; it is hoisted here so a new fixed-host provider reuses it instead of
+// re-deriving the per-hop guard (and the latent bug of forgetting it).
+//
+// The helper is host-*pinned*, not host-*allow-listed*: it serves providers whose API
+// lives at a single known host. A site-configurable provider (Confluence) keeps its own
+// guard because its allowed host is per-connection, not a constant.
+/** Carries the HTTP status so a provider can surface a meaningful error to the caller. */
+export class DocumentHttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'DocumentHttpError';
+    }
+}
+/**
+ * Assert a request/redirect URL stays on the provider's fixed `host` over https. A
+ * redirect off-host (e.g. to a link-local metadata address) or an http downgrade is
+ * treated as an SSRF attempt and rejected. Throws a plain `Error` so it stays trivially
+ * unit-testable without a network; the caller maps it to a {@link DocumentHttpError}.
+ * `label` names the provider in the message (e.g. `Figma`, `Claude Design`).
+ */
+export function assertHostPinned(url, host, label) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`${label} request URL is invalid: ${url}`);
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new Error(`${label} request must use https`);
+    }
+    if (parsed.hostname.toLowerCase() !== host.toLowerCase()) {
+        throw new Error(`${label} redirect to a disallowed host: ${parsed.hostname}`);
+    }
+}
+/** Bound the redirect chain so the fixed API host can't 302 us elsewhere indefinitely. */
+const DEFAULT_MAX_REDIRECTS = 5;
+/**
+ * Build a `fetch` that follows redirects **by hand** so {@link assertHostPinned} runs
+ * against EVERY hop. With the default `redirect: 'follow'` a 302 from the API could be
+ * chased to an internal target (or downgraded to http), leaking the credential. We force
+ * `redirect: 'manual'`, re-resolve the `Location`, and re-validate before each hop.
+ */
+export function createHostPinnedFetch(opts) {
+    const maxRedirects = opts.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    return async function safeFetch(url, init) {
+        let current = url;
+        for (let hop = 0;; hop++) {
+            try {
+                assertHostPinned(current, opts.host, opts.label);
+            }
+            catch (err) {
+                throw new DocumentHttpError(502, err instanceof Error ? err.message : `${opts.label} request blocked`);
+            }
+            const res = await fetch(current, { ...init, redirect: 'manual' });
+            if (res.status >= 300 && res.status < 400) {
+                const location = res.headers.get('location');
+                if (!location)
+                    return res;
+                if (hop >= maxRedirects) {
+                    throw new DocumentHttpError(502, `${opts.label} returned too many redirects`);
+                }
+                current = new URL(location, current).toString();
+                continue;
+            }
+            return res;
+        }
+    };
+}
+/**
+ * Read a response body with a running byte cap so a hostile/huge response can't OOM the
+ * isolate. Checks the declared Content-Length first, then enforces the cap while
+ * streaming. `label` names the provider in the error message.
+ */
+export async function readCappedText(res, maxBytes, label = 'Response') {
+    const declared = res.headers.get('content-length');
+    if (declared && Number(declared) > maxBytes) {
+        throw new DocumentHttpError(502, `${label} response too large`);
+    }
+    const body = res.body;
+    if (!body)
+        return '';
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel();
+                throw new DocumentHttpError(502, `${label} response too large`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        merged.set(c, offset);
+        offset += c.byteLength;
+    }
+    return new TextDecoder().decode(merged);
+}
+//# sourceMappingURL=http.js.map

package/dist/modules/documents/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/modules/documents/http.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/integrations",
-  "version": "0.25.2",
+  "version": "0.26.0",
   "description": "External-system integration domain logic for the Agent Architecture Board (GitHub, documents, tasks, environments, runners).",
   "repository": {
     "type": "git",
@@ -25,8 +25,8 @@
   },
   "dependencies": {
     "ai": "^6.0.209",
-    "@cat-factory/contracts": "0.42.0",
-    "@cat-factory/kernel": "0.44.0"
+    "@cat-factory/contracts": "0.43.0",
+    "@cat-factory/kernel": "0.45.0"
   },
   "devDependencies": {
     "typescript": "7.0.1-rc",