@cat-factory/integrations 0.25.2 → 0.26.0

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

@@ -0,0 +1,317 @@
+import { assertHostPinned } from './http.js';
+// Claude-Design pure logic, kept out of the provider shell so it is unit-testable
+// without a live API: the connect-form descriptor, parsing a project/file ref out of
+// user input, the fixed-host SSRF guard, and — the part that earns the provider its
+// place over a plain HTML upload — a deterministic **design-system normalizer** that
+// turns a Claude Design project's manifest + component-preview HTML into the same
+// lightweight Markdown shape the Figma provider emits (`### Components`, `### Design
+// tokens`), so a frontend agent reads the design system the same way regardless of
+// which tool authored it. The `fetch` itself lives in `ClaudeDesignProvider`.
+//
+// Why a normalizer and not pass-through: a Claude Design export bundle is raw component
+// HTML + CSS. Handed to an agent verbatim it is noise (markup, scripts, inline styles).
+// The value is the *structure* — which components exist, grouped how, and what design
+// tokens (CSS custom properties) back them. That extraction is deterministic, so it is
+// backend TS here, not an LLM step, and it is what distinguishes this provider from
+// attaching the same HTML as a generic document.
+/**
+ * Claude Design's programmatic-read host. PROVISIONAL: today the design-system read is
+ * bound to a claude.ai login; this provider targets the per-user-PAT API shape the
+ * product is moving toward. The host is pinned (see {@link assertSafeClaudeDesignUrl})
+ * and the exact endpoints in `ClaudeDesignProvider` should be re-verified against the
+ * current API when the credentialed read ships — treat them as the intended shape, not a
+ * frozen contract.
+ */
+export const CLAUDE_DESIGN_API_HOST = 'api.claude.com';
+/** Where a human opens the project (the canonical URL stored on imported documents). */
+export const CLAUDE_DESIGN_APP_HOST = 'claude.ai';
+/** What the connect UI renders, and which credentials the provider needs. */
+export const CLAUDE_DESIGN_DESCRIPTOR = {
+    source: 'claude-design',
+    label: 'Claude Design',
+    icon: 'i-lucide-palette',
+    credentialFields: [
+        {
+            key: 'apiToken',
+            label: 'Personal access token',
+            secret: true,
+            placeholder: 'sk-ant-…',
+            help: 'A Claude Design personal access token authenticates as your own account, so it is stored per user and never shared with the rest of the workspace. Create one in claude.ai → Settings → Design.',
+        },
+    ],
+    refLabel: 'Claude Design project or component URL',
+    refPlaceholder: 'https://claude.ai/design/<projectId>',
+    // No catalogue search over a PAT — import a specific project/component by URL.
+    searchable: false,
+    // Personal token: each member connects their own; stored keyed by user id.
+    credentialScope: 'user',
+};
+/**
+ * The Claude Design read host is fixed, so any request/redirect must stay on it over
+ * https. A redirect off-host (e.g. to a link-local metadata address) is rejected as an
+ * SSRF attempt. Delegates to the shared host-pin guard; throws a plain `Error` the
+ * provider maps to a `DocumentHttpError`. Kept pure so it is unit-testable without a
+ * network.
+ */
+export function assertSafeClaudeDesignUrl(url) {
+    assertHostPinned(url, CLAUDE_DESIGN_API_HOST, 'Claude Design');
+}
+// ---- Ref parsing + canonical URL ------------------------------------------
+/** Composite external id delimiter: `<projectId>` or `<projectId>::<filePath>`. */
+const REF_DELIM = '::';
+const PROJECT_ID_RE = /^[A-Za-z0-9_-]+$/;
+/**
+ * Resolve a Claude Design reference from raw user input into the stable composite
+ * external id this provider stores: `"<projectId>"` for a whole project, or
+ * `"<projectId>::<filePath>"` for a single component/file. Accepts a
+ * `claude.ai/design/<projectId>` URL (optionally `…/files/<path>` or `?file=<path>`), a
+ * bare project id, or the composite form. Returns null when no project id is found.
+ *
+ * Deterministic (same input → same external id), which the
+ * `(workspace, source, externalId)` document key relies on for de-duplication.
+ */
+export function parseClaudeDesignRef(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    // Bare ref (anything that isn't an absolute URL): a project id, optionally
+    // `::`-suffixed with a file path (the path may itself contain `/`). Keyed off the
+    // `://` scheme separator so a bare `projectId::path` is never mis-parsed as a URL.
+    if (!trimmed.includes('://')) {
+        const [projectId, ...rest] = trimmed.split(REF_DELIM);
+        if (!projectId || !PROJECT_ID_RE.test(projectId))
+            return null;
+        const path = rest.join(REF_DELIM).trim();
+        return path ? `${projectId}${REF_DELIM}${normalizeFilePath(path)}` : projectId;
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (!/(^|\.)claude\.(ai|com)$/i.test(url.hostname))
+        return null;
+    const segments = url.pathname.split('/').filter(Boolean);
+    const designIdx = segments.indexOf('design');
+    if (designIdx === -1 || designIdx + 1 >= segments.length)
+        return null;
+    const projectId = segments[designIdx + 1];
+    if (!PROJECT_ID_RE.test(projectId))
+        return null;
+    // A file path may follow as `…/design/<id>/files/<path…>` or `?file=<path>`.
+    const after = segments.slice(designIdx + 2);
+    const fileSegments = after[0] === 'files' ? after.slice(1) : after;
+    const queryFile = url.searchParams.get('file') ?? url.searchParams.get('path');
+    const rawPath = queryFile ?? (fileSegments.length ? fileSegments.join('/') : '');
+    const path = rawPath ? normalizeFilePath(rawPath) : '';
+    return path ? `${projectId}${REF_DELIM}${path}` : projectId;
+}
+/** Strip leading slashes and collapse `.`/empty segments from a file path. */
+function normalizeFilePath(path) {
+    return path
+        .split('/')
+        .map((s) => s.trim())
+        .filter((s) => s && s !== '.')
+        .join('/');
+}
+/** Split a composite external id back into its project id and optional file path. */
+export function splitClaudeDesignExternalId(externalId) {
+    const idx = externalId.indexOf(REF_DELIM);
+    if (idx === -1)
+        return { projectId: externalId };
+    const filePath = externalId.slice(idx + REF_DELIM.length);
+    return { projectId: externalId.slice(0, idx), filePath: filePath || undefined };
+}
+/** Build the canonical web URL stored on the imported document (matched by `getByUrl`). */
+export function claudeDesignUrlFor(externalId) {
+    const { projectId, filePath } = splitClaudeDesignExternalId(externalId);
+    const base = `https://${CLAUDE_DESIGN_APP_HOST}/design/${projectId}`;
+    return filePath ? `${base}/files/${filePath}` : base;
+}
+/** The manifest file name Claude Design compiles its card index into. */
+export const DS_MANIFEST_PATH = '_ds_manifest.json';
+const MAX_CARDS = 200;
+const MAX_TOKENS = 200;
+const MAX_TEXT_CHARS = 2000;
+/**
+ * Parse a `_ds_manifest.json` payload (a bare array of cards, or `{ cards: [...] }`)
+ * into a lenient {@link DsCard} list. Unknown shapes yield `[]` so the caller falls
+ * back to per-file HTML extraction.
+ */
+export function parseDsManifest(json) {
+    const raw = Array.isArray(json)
+        ? json
+        : json && typeof json === 'object' && Array.isArray(json.cards)
+            ? json.cards
+            : [];
+    const cards = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const o = item;
+        const card = {};
+        if (typeof o.name === 'string')
+            card.name = o.name.trim();
+        if (typeof o.group === 'string')
+            card.group = o.group.trim();
+        if (typeof o.subtitle === 'string')
+            card.subtitle = o.subtitle.trim();
+        if (typeof o.path === 'string')
+            card.path = o.path.trim();
+        if (card.name || card.path)
+            cards.push(card);
+        if (cards.length >= MAX_CARDS)
+            break;
+    }
+    return cards;
+}
+const DS_CARD_RE = /<!--\s*@dsCard\s+([^>]*?)-->/i;
+const ATTR_RE = /(\w+)\s*=\s*"([^"]*)"/g;
+/**
+ * Read the first-line `<!-- @dsCard group="…" name="…" subtitle="…" -->` marker Claude
+ * Design writes at the top of each component-preview HTML. Returns null when absent.
+ */
+export function parseDsCardComment(html) {
+    const match = DS_CARD_RE.exec(html);
+    if (!match)
+        return null;
+    const attrs = {};
+    let m;
+    ATTR_RE.lastIndex = 0;
+    while ((m = ATTR_RE.exec(match[1])))
+        attrs[m[1].toLowerCase()] = m[2].trim();
+    const card = {};
+    if (attrs.name)
+        card.name = attrs.name;
+    if (attrs.group)
+        card.group = attrs.group;
+    if (attrs.subtitle)
+        card.subtitle = attrs.subtitle;
+    return card.name || card.group ? card : null;
+}
+const CSS_VAR_RE = /(--[A-Za-z0-9_-]+)\s*:\s*([^;{}]+)[;}]/g;
+/**
+ * Extract CSS custom properties (`--token: value`) from a stylesheet/HTML blob as design
+ * tokens, deduped (last value wins) and sorted. These are Claude Design's design tokens —
+ * the analogue of Figma variables.
+ */
+export function extractCssTokens(content) {
+    const tokens = new Map();
+    let m;
+    CSS_VAR_RE.lastIndex = 0;
+    while ((m = CSS_VAR_RE.exec(content))) {
+        const name = m[1];
+        const value = m[2].replace(/\s+/g, ' ').trim();
+        if (value && !value.startsWith('var('))
+            tokens.set(name, value);
+        if (tokens.size >= MAX_TOKENS)
+            break;
+    }
+    return [...tokens.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k} = ${v}`);
+}
+/** Strip `<script>`/`<style>` blocks and all tags, returning collapsed visible text. */
+export function htmlToText(html) {
+    const text = html
+        .replace(/<!--[\s\S]*?-->/g, ' ')
+        .replace(/<(script|style)\b[\s\S]*?<\/\1>/gi, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+    return text.length > MAX_TEXT_CHARS ? `${text.slice(0, MAX_TEXT_CHARS)}…` : text;
+}
+/** Render a grouped component inventory from a card list (`### <group>` → `- <name>`). */
+export function dsCardsToMarkdown(cards) {
+    const byGroup = new Map();
+    for (const card of cards) {
+        if (!card.name && !card.path)
+            continue;
+        const group = card.group?.trim() || 'Components';
+        const list = byGroup.get(group) ?? [];
+        list.push(card);
+        byGroup.set(group, list);
+    }
+    if (byGroup.size === 0)
+        return '';
+    const lines = ['### Components'];
+    for (const group of [...byGroup.keys()].sort()) {
+        lines.push(`#### ${group}`);
+        const seen = new Set();
+        for (const card of byGroup.get(group)) {
+            const name = card.name?.trim() || card.path?.trim() || '(unnamed)';
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            lines.push(card.subtitle ? `- ${name} — ${card.subtitle}` : `- ${name}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Normalize a whole Claude Design project's fetched files into the lightweight Markdown a
+ * frontend agent consumes. Strategy:
+ *   1. If a `_ds_manifest.json` is present, it is the authoritative component index →
+ *      `### Components` grouped inventory.
+ *   2. Otherwise, recover the inventory from each preview HTML's `@dsCard` marker.
+ *   3. Design tokens are unioned from the CSS custom properties across all files.
+ *   4. A bounded slice of visible text gives the agent a sense of the content.
+ *
+ * `projectName` titles the document. Pure: no network, fully unit-testable.
+ */
+export function renderClaudeDesignProject(projectName, files) {
+    const manifest = files.find((f) => f.path.endsWith(DS_MANIFEST_PATH));
+    let cards = [];
+    if (manifest) {
+        try {
+            cards = parseDsManifest(JSON.parse(manifest.content));
+        }
+        catch {
+            cards = [];
+        }
+    }
+    const htmlFiles = files.filter((f) => /\.html?$/i.test(f.path));
+    if (cards.length === 0) {
+        for (const file of htmlFiles) {
+            const card = parseDsCardComment(file.content);
+            if (card)
+                cards.push({ ...card, path: file.path });
+        }
+    }
+    const tokenSet = new Map();
+    for (const file of files) {
+        if (file.path.endsWith(DS_MANIFEST_PATH))
+            continue;
+        for (const entry of extractCssTokens(file.content)) {
+            const eq = entry.indexOf(' = ');
+            tokenSet.set(entry.slice(0, eq), entry.slice(eq + 3));
+            if (tokenSet.size >= MAX_TOKENS)
+                break;
+        }
+    }
+    const sections = [`## ${projectName.trim() || 'Claude Design project'}`];
+    const inventory = dsCardsToMarkdown(cards);
+    if (inventory)
+        sections.push(inventory);
+    if (tokenSet.size) {
+        const tokenLines = [...tokenSet.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => `- ${k} = ${v}`);
+        sections.push(['### Design tokens', ...tokenLines].join('\n'));
+    }
+    // A single-component import (one HTML, no manifest) carries little structure, so fold in
+    // a slice of its visible text — the same text-content affordance the Figma renderer gives.
+    if (!manifest && htmlFiles.length === 1) {
+        const text = htmlToText(htmlFiles[0].content);
+        if (text)
+            sections.push(['### Content', text].join('\n'));
+    }
+    return sections.join('\n\n').trim();
+}
+//# sourceMappingURL=claudeDesign.logic.js.map

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

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

package/dist/modules/documents/figma.logic.d.ts

@@ -0,0 +1,98 @@
+import type { DocumentSourceDescriptor } from '@cat-factory/kernel';
+/** Figma's REST API host. The PAT is sent to this host only — see {@link assertSafeFigmaUrl}. */
+export declare const FIGMA_API_HOST = "api.figma.com";
+/** What the connect UI renders, and which credentials the provider needs. */
+export declare const FIGMA_DESCRIPTOR: DocumentSourceDescriptor;
+/**
+ * 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 declare function assertSafeFigmaUrl(url: string): void;
+/**
+ * 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 declare function normalizeFigmaNodeId(raw: string): string | 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 declare function parseFigmaRef(input: string): string | null;
+/** Split a composite external id back into its file key and optional node id (colon form). */
+export declare function splitFigmaExternalId(externalId: string): {
+    fileKey: string;
+    nodeId?: string;
+};
+/**
+ * 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 declare function figmaUrlFor(externalId: string): string;
+/** The subset of a Figma node we read for the layout/text/component rendering. */
+export interface FigmaNode {
+    id?: string;
+    name?: string;
+    type?: string;
+    characters?: string;
+    componentId?: string;
+    absoluteBoundingBox?: {
+        width?: number;
+        height?: number;
+    } | null;
+    children?: FigmaNode[];
+}
+/** A `componentId → { name }` map (Figma returns it alongside the node tree). */
+export interface FigmaComponentMap {
+    [id: string]: {
+        name?: string;
+    } | undefined;
+}
+/**
+ * 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 declare function figmaNodesToMarkdown(roots: FigmaNode[], components?: FigmaComponentMap): string;
+interface FigmaVariable {
+    name?: string;
+    resolvedType?: string;
+    variableCollectionId?: string;
+    valuesByMode?: Record<string, unknown>;
+}
+interface FigmaVariableCollection {
+    name?: string;
+    modes?: {
+        modeId?: string;
+        name?: string;
+    }[];
+}
+/** The `/v1/files/:key/variables/local` `meta` payload we read. */
+export interface FigmaVariablesMeta {
+    variables?: Record<string, FigmaVariable | undefined>;
+    variableCollections?: Record<string, FigmaVariableCollection | undefined>;
+}
+/**
+ * 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 declare function figmaVariablesToMarkdown(meta: FigmaVariablesMeta | undefined): string;
+export {};
+//# sourceMappingURL=figma.logic.d.ts.map

package/dist/modules/documents/figma.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/figma.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AASnE,iGAAiG;AACjG,eAAO,MAAM,cAAc,kBAAkB,CAAA;AAE7C,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,EAAE,wBAiB9B,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEpD;AAID;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4B1D;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAI7F;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAKtD;AAID,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACxB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mBAAmB,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAChE,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAA;CACvB;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,CAAC,EAAE,EAAE,MAAM,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;CAC5C;AAqDD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,EAAE,EAClB,UAAU,GAAE,iBAAsB,GACjC,MAAM,CA8BR;AAID,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACvC;AAED,UAAU,uBAAuB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAC7C;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC,CAAA;IACrD,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,GAAG,SAAS,CAAC,CAAA;CAC1E;AAoBD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,CAoBrF"}