@cat-factory/integrations 0.25.2 → 0.26.0

package/dist/modules/documents/DocumentImportService.js

@@ -24,15 +24,21 @@ export class DocumentImportService {
             throw new ValidationError(`Unknown or unconfigured document source '${source}'`);
         return provider;
     }
-    /** Fetch a page (by id or URL) and upsert its projection; returns the document. */
-    async import(workspaceId, source, ref) {
+    /**
+     * Fetch a page (by id or URL) and upsert its projection; returns the document.
+     * `ownerUserId` resolves the credential for a personal (`credentialScope: 'user'`)
+     * source — the acting user — and is ignored for workspace sources. The cached
+     * projection is always workspace-scoped, so a personal source's imported page is
+     * shared with the workspace once fetched (only the *credential* is personal).
+     */
+    async import(workspaceId, source, ref, ownerUserId = '') {
         await requireWorkspace(this.deps.workspaceRepository, workspaceId);
         const provider = this.requireProvider(source);
         const externalId = provider.parseRef(ref);
         if (!externalId) {
             throw new ValidationError(`Could not resolve a ${source} page id from '${ref}'`);
         }
-        const connection = await this.deps.connectionService.requireConnection(workspaceId, source);
+        const connection = await this.deps.connectionService.requireConnection(workspaceId, source, ownerUserId);
         const content = await provider.fetchDocument(connection.credentials, externalId);
         // Preserve any existing block link across a re-import.
         const existing = await this.deps.documentRepository.get(workspaceId, source, content.externalId);
@@ -70,13 +76,13 @@ export class DocumentImportService {
      * and builds/parses the source-specific query. Throws if the source can't
      * search (no provider `search`), so the controller can answer cleanly.
      */
-    async search(workspaceId, source, query) {
+    async search(workspaceId, source, query, ownerUserId = '') {
         await requireWorkspace(this.deps.workspaceRepository, workspaceId);
         const provider = this.requireProvider(source);
         if (!provider.search) {
             throw new ValidationError(`The ${source} source does not support search`);
         }
-        const connection = await this.deps.connectionService.requireConnection(workspaceId, source);
+        const connection = await this.deps.connectionService.requireConnection(workspaceId, source, ownerUserId);
         return provider.search(connection.credentials, query, workspaceId);
     }
     /** Every document imported into the workspace, across sources, as wire shapes. */

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

@@ -1 +1 @@
-{"version":3,"file":"DocumentImportService.js","sourceRoot":"","sources":["../../../src/modules/documents/DocumentImportService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DocumentImportService.js","sourceRoot":"","sources":["../../../src/modules/documents/DocumentImportService.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAGtD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAgBnD,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAAC,MAAsB;IACrD,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAA;AACH,CAAC;AAED,MAAM,OAAO,qBAAqB;IACH,IAAI;IAAjC,YAA6B,IAAuC;oBAAvC,IAAI;IAAsC,CAAC;IAEhE,eAAe,CAAC,MAA0B;QAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAC/C,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,eAAe,CAAC,4CAA4C,MAAM,GAAG,CAAC,CAAA;QAC/F,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CACV,WAAmB,EACnB,MAA0B,EAC1B,GAAW,EACX,WAAW,GAAG,EAAE;QAEhB,MAAM,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,CAAA;QAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAA;QAC7C,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;QACzC,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,eAAe,CAAC,uBAAuB,MAAM,kBAAkB,GAAG,GAAG,CAAC,CAAA;QAClF,CAAC;QACD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,iBAAiB,CACpE,WAAW,EACX,MAAM,EACN,WAAW,CACZ,CAAA;QACD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC,WAAW,EAAE,UAAU,CAAC,CAAA;QAEhF,uDAAuD;QACvD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,CAAA;QAChG,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QACtC,mFAAmF;QACnF,mFAAmF;QACnF,oFAAoF;QACpF,iFAAiF;QACjF,IACE,QAAQ;YACR,QAAQ,CAAC,SAAS,KAAK,IAAI;YAC3B,QAAQ,CAAC,WAAW,KAAK,IAAI;YAC7B,QAAQ,CAAC,KAAK,KAAK,OAAO,CAAC,KAAK;YAChC,QAAQ,CAAC,GAAG,KAAK,OAAO,CAAC,GAAG,EAC5B,CAAC;YACD,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAA;QACnC,CAAC;QACD,MAAM,MAAM,GAAmB;YAC7B,WAAW;YACX,MAAM;YACN,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC;YACnC,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,IAAI;YACjB,aAAa,EAAE,QAAQ,EAAE,aAAa,IAAI,IAAI;YAC9C,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YAC/B,SAAS,EAAE,IAAI;SAChB,CAAA;QACD,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACjD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAA;IACjC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CACV,WAAmB,EACnB,MAA0B,EAC1B,KAAa,EACb,WAAW,GAAG,EAAE;QAEhB,MAAM,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,CAAA;QAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAA;QAC7C,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACrB,MAAM,IAAI,eAAe,CAAC,OAAO,MAAM,iCAAiC,CAAC,CAAA;QAC3E,CAAC;QACD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,iBAAiB,CACpE,WAAW,EACX,MAAM,EACN,WAAW,CACZ,CAAA;QACD,OAAO,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,KAAK,EAAE,WAAW,CAAC,CAAA;IACpE,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,aAAa,CAAC,WAAmB;QACrC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,eAAe,CAAC,WAAW,CAAC,CAAA;QAC/E,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAA;IACtC,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,eAAe,CACnB,WAAmB,EACnB,MAA0B,EAC1B,UAAkB;QAElB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,CAAA;QACtF,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,eAAe,CAAC,GAAG,MAAM,UAAU,UAAU,yBAAyB,CAAC,CAAA;QACnF,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;CACF"}

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

@@ -0,0 +1,42 @@
+import { type DocumentContent, type DocumentCredentials, type DocumentSourceProvider, type NormalizedConnection } from '@cat-factory/kernel';
+/** Carries the HTTP status so callers can surface a meaningful error. */
+export declare class FigmaApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare class FigmaProvider implements DocumentSourceProvider {
+    readonly kind: 'figma';
+    readonly descriptor: {
+        source: "claude-design" | "confluence" | "figma" | "github" | "linear" | "notion";
+        label: string;
+        icon: string;
+        credentialFields: {
+            key: string;
+            label: string;
+            help?: string | undefined;
+            placeholder?: string | undefined;
+            secret?: boolean | undefined;
+        }[];
+        refLabel: string;
+        refPlaceholder: string;
+        searchable?: boolean | undefined;
+        credentialScope?: "user" | "workspace" | undefined;
+    };
+    normalizeConnection(input: DocumentCredentials): NormalizedConnection;
+    parseRef(input: string): string | null;
+    fetchDocument(credentials: DocumentCredentials, externalId: string): Promise<DocumentContent>;
+    /** Fetch a specific node's subtree, or the whole file's document, plus its components. */
+    private fetchNodes;
+    /**
+     * Fetch local variables (design tokens); null on the Enterprise-gating 403/404. Fully
+     * best-effort: any transport failure (incl. a blocked-redirect `DocumentHttpError`)
+     * drops the section rather than failing the whole import.
+     */
+    private fetchVariables;
+    /** Best-effort short-lived PNG render URL for the node (or whole file); null on any failure. */
+    private fetchPreviewUrl;
+    private headers;
+    private parse;
+    private get;
+}
+//# sourceMappingURL=FigmaProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FigmaProvider.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/FigmaProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAA;AAsB5B,yEAAyE;AACzE,qBAAa,aAAc,SAAQ,KAAK;IAEpC,QAAQ,CAAC,MAAM,EAAE,MAAM;IADzB,YACW,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EAIhB;CACF;AAgCD,qBAAa,aAAc,YAAW,sBAAsB;IAC1D,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAS;IAChC,QAAQ,CAAC,UAAU;;;;;;;;;;;;;;;MAAmB;IAEtC,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAMpE;IAED,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAErC;IAEK,aAAa,CACjB,WAAW,EAAE,mBAAmB,EAChC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CA0B1B;IAED,0FAA0F;YAC5E,UAAU;IAyCxB;;;;OAIG;YACW,cAAc;IAmB5B,gGAAgG;YAClF,eAAe;IAqB7B,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,KAAK;YAQC,GAAG;CAqBlB"}

package/dist/modules/documents/FigmaProvider.js

@@ -0,0 +1,176 @@
+import { ValidationError, } from '@cat-factory/kernel';
+import { FIGMA_API_HOST, FIGMA_DESCRIPTOR } from './figma.logic.js';
+import * as figmaLogic from './figma.logic.js';
+import { DocumentHttpError, createHostPinnedFetch, readCappedText } from './http.js';
+// FigmaProvider: the document-source provider for Figma. It authenticates with a
+// per-workspace personal access token (the `X-Figma-Token` header), fetches a
+// file or a specific frame/node via the REST API, and renders the layout tree,
+// text, components-used and (Enterprise-gated) design tokens to the Markdown the
+// planner + `.cat-context/` materialisation consume. All Figma-specific *pure*
+// logic (ref parsing, the fixed-host SSRF guard, JSON → Markdown) lives in
+// `figma.logic.ts` so it is unit-testable; this class is the thin `fetch` shell.
+// Because the API host is fixed (`api.figma.com`) and there is no per-site base
+// URL, the only SSRF surface is a redirect off-host — guarded per hop below.
+const API_BASE = 'https://api.figma.com/v1';
+const USER_AGENT = 'cat-factory';
+/** Depth fetched for a whole-file link (a node link fetches its own subtree). */
+const FILE_DEPTH = 2;
+/** Hard cap on the bytes read off any response body, to protect the isolate. */
+const MAX_RESPONSE_BYTES = 5_000_000;
+/** Carries the HTTP status so callers can surface a meaningful error. */
+export class FigmaApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'FigmaApiError';
+    }
+}
+/**
+ * `fetch` pinned to `api.figma.com`, following redirects by hand so the SSRF host
+ * guard runs against every hop (a 302 can't chase the PAT off-host). The transport +
+ * capped-read are the shared documents `http` helpers; only the host/label differ.
+ */
+const safeFetch = createHostPinnedFetch({ host: FIGMA_API_HOST, label: 'Figma' });
+export class FigmaProvider {
+    kind = 'figma';
+    descriptor = FIGMA_DESCRIPTOR;
+    normalizeConnection(input) {
+        const apiToken = input.apiToken?.trim();
+        if (!apiToken) {
+            throw new ValidationError('Figma requires a personal access token');
+        }
+        return { credentials: { apiToken }, label: 'Figma' };
+    }
+    parseRef(input) {
+        return figmaLogic.parseFigmaRef(input);
+    }
+    async fetchDocument(credentials, externalId) {
+        const { fileKey, nodeId } = figmaLogic.splitFigmaExternalId(externalId);
+        if (!fileKey) {
+            throw new FigmaApiError(400, `Figma ref is missing a file key: ${externalId}`);
+        }
+        const { roots, components, fileName } = await this.fetchNodes(credentials, fileKey, nodeId);
+        const sections = [figmaLogic.figmaNodesToMarkdown(roots, components)];
+        // Design tokens are Enterprise-gated; on 403/404 drop the section, don't fail.
+        const tokens = await this.fetchVariables(credentials, fileKey);
+        if (tokens)
+            sections.push(tokens);
+        // A rendered preview rides along as a reference line (no download). Best-effort:
+        // a non-multimodal agent ignores it and the short-lived URL may expire.
+        const preview = await this.fetchPreviewUrl(credentials, fileKey, nodeId);
+        if (preview)
+            sections.push(`### Rendered preview\nRendered preview: ${preview}`);
+        const title = nodeId ? `${fileName} — ${roots[0]?.name?.trim() || nodeId}` : fileName || fileKey;
+        return {
+            externalId,
+            title,
+            url: figmaLogic.figmaUrlFor(externalId),
+            body: sections.filter(Boolean).join('\n\n').trim(),
+        };
+    }
+    /** Fetch a specific node's subtree, or the whole file's document, plus its components. */
+    async fetchNodes(credentials, fileKey, nodeId) {
+        if (nodeId) {
+            const res = await this.get(credentials, `/files/${encodeURIComponent(fileKey)}/nodes?ids=${encodeURIComponent(nodeId)}`);
+            const entry = res.nodes?.[nodeId];
+            if (!entry?.document) {
+                throw new FigmaApiError(404, `Figma node ${nodeId} not found in file ${fileKey}`);
+            }
+            return {
+                roots: [entry.document],
+                components: entry.components ?? {},
+                fileName: res.name ?? fileKey,
+            };
+        }
+        const res = await this.get(credentials, `/files/${encodeURIComponent(fileKey)}?depth=${FILE_DEPTH}`);
+        if (!res.document) {
+            throw new FigmaApiError(502, `Figma returned no document for file ${fileKey}`);
+        }
+        // For a whole-file link the document's children are the pages/canvases; render
+        // each top-level frame under them as a section root.
+        const roots = (res.document.children ?? []).flatMap((page) => page.children ?? []);
+        return {
+            roots: roots.length ? roots : [res.document],
+            components: res.components ?? {},
+            fileName: res.name ?? fileKey,
+        };
+    }
+    /**
+     * Fetch local variables (design tokens); null on the Enterprise-gating 403/404. Fully
+     * best-effort: any transport failure (incl. a blocked-redirect `DocumentHttpError`)
+     * drops the section rather than failing the whole import.
+     */
+    async fetchVariables(credentials, fileKey) {
+        try {
+            const res = await safeFetch(`${API_BASE}/files/${encodeURIComponent(fileKey)}/variables/local`, { method: 'GET', headers: this.headers(credentials) });
+            if (res.status === 403 || res.status === 404)
+                return null;
+            if (!res.ok)
+                return null;
+            const json = this.parse(await readCappedText(res, MAX_RESPONSE_BYTES));
+            const markdown = figmaLogic.figmaVariablesToMarkdown(json?.meta);
+            return markdown || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Best-effort short-lived PNG render URL for the node (or whole file); null on any failure. */
+    async fetchPreviewUrl(credentials, fileKey, nodeId) {
+        if (!nodeId)
+            return null;
+        try {
+            const res = await safeFetch(`${API_BASE}/images/${encodeURIComponent(fileKey)}?ids=${encodeURIComponent(nodeId)}&format=png`, { method: 'GET', headers: this.headers(credentials) });
+            if (!res.ok)
+                return null;
+            const json = this.parse(await readCappedText(res, MAX_RESPONSE_BYTES));
+            if (!json || json.err)
+                return null;
+            const url = json.images?.[nodeId];
+            return typeof url === 'string' ? url : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    headers(credentials) {
+        return {
+            'x-figma-token': credentials.apiToken ?? '',
+            accept: 'application/json',
+            'user-agent': USER_AGENT,
+        };
+    }
+    parse(text) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    async get(credentials, path) {
+        const url = `${API_BASE}${path}`;
+        let res;
+        try {
+            res = await safeFetch(url, { method: 'GET', headers: this.headers(credentials) });
+        }
+        catch (err) {
+            // The shared transport raises DocumentHttpError on a blocked/off-host redirect;
+            // surface it as the provider's own error type so callers see one shape.
+            if (err instanceof DocumentHttpError)
+                throw new FigmaApiError(err.status, err.message);
+            throw err;
+        }
+        if (!res.ok) {
+            const text = await readCappedText(res, MAX_RESPONSE_BYTES).catch(() => '');
+            throw new FigmaApiError(res.status, `Figma GET ${url} → ${res.status}: ${text.slice(0, 300)}`);
+        }
+        const json = this.parse(await readCappedText(res, MAX_RESPONSE_BYTES));
+        if (json === null) {
+            throw new FigmaApiError(502, `Figma returned an unparseable body for ${path}`);
+        }
+        return json;
+    }
+}
+//# sourceMappingURL=FigmaProvider.js.map

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

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

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

@@ -8,7 +8,7 @@ export declare class GitHubDocsProvider implements DocumentSourceProvider {
     private readonly deps;
     readonly kind: 'github';
     readonly descriptor: {
-        source: "confluence" | "github" | "linear" | "notion";
+        source: "claude-design" | "confluence" | "figma" | "github" | "linear" | "notion";
         label: string;
         icon: string;
         credentialFields: {
@@ -21,6 +21,7 @@ export declare class GitHubDocsProvider implements DocumentSourceProvider {
         refLabel: string;
         refPlaceholder: string;
         searchable?: boolean | undefined;
+        credentialScope?: "user" | "workspace" | undefined;
     };
     constructor(deps: GitHubDocsProviderDependencies);
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"GitHubDocsProvider.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/GitHubDocsProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,4BAA4B,EACjC,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAA;AAe5B,MAAM,WAAW,8BAA8B;IAC7C,YAAY,EAAE,YAAY,CAAA;IAC1B,8EAA8E;IAC9E,aAAa,EAAE,4BAA4B,CAAA;CAC5C;AAED,qBAAa,kBAAmB,YAAW,sBAAsB;IAInD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAS;IACjC,QAAQ,CAAC,UAAU;;;;;;;;;;;;;;MAAyB;IAE5C,YAA6B,IAAI,EAAE,8BAA8B,EAAI;IAErE;;;;OAIG;IACH,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,oBAAoB,CAErE;IAED,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAErC;IAEK,aAAa,CACjB,YAAY,EAAE,mBAAmB,EACjC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CAoB1B;IAEK,MAAM,CACV,YAAY,EAAE,mBAAmB,EACjC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAkCjC;IAED;;;;OAIG;YACW,qBAAqB;CAUpC"}
+{"version":3,"file":"GitHubDocsProvider.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/GitHubDocsProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,4BAA4B,EACjC,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAA;AAe5B,MAAM,WAAW,8BAA8B;IAC7C,YAAY,EAAE,YAAY,CAAA;IAC1B,8EAA8E;IAC9E,aAAa,EAAE,4BAA4B,CAAA;CAC5C;AAED,qBAAa,kBAAmB,YAAW,sBAAsB;IAInD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAS;IACjC,QAAQ,CAAC,UAAU;;;;;;;;;;;;;;;MAAyB;IAE5C,YAA6B,IAAI,EAAE,8BAA8B,EAAI;IAErE;;;;OAIG;IACH,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,oBAAoB,CAErE;IAED,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAErC;IAEK,aAAa,CACjB,YAAY,EAAE,mBAAmB,EACjC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CAoB1B;IAEK,MAAM,CACV,YAAY,EAAE,mBAAmB,EACjC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAkCjC;IAED;;;;OAIG;YACW,qBAAqB;CAUpC"}

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

@@ -2,7 +2,7 @@ import { type DocumentContent, type DocumentCredentials, type DocumentSearchResu
 export declare class LinearDocumentProvider implements DocumentSourceProvider {
     readonly kind: 'linear';
     readonly descriptor: {
-        source: "confluence" | "github" | "linear" | "notion";
+        source: "claude-design" | "confluence" | "figma" | "github" | "linear" | "notion";
         label: string;
         icon: string;
         credentialFields: {
@@ -15,6 +15,7 @@ export declare class LinearDocumentProvider implements DocumentSourceProvider {
         refLabel: string;
         refPlaceholder: string;
         searchable?: boolean | undefined;
+        credentialScope?: "user" | "workspace" | undefined;
     };
     normalizeConnection(input: DocumentCredentials): NormalizedConnection;
     parseRef(input: string): string | null;

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

@@ -1 +1 @@
-{"version":3,"file":"LinearDocumentProvider.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/LinearDocumentProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAA;AAsB5B,qBAAa,sBAAuB,YAAW,sBAAsB;IACnE,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAS;IACjC,QAAQ,CAAC,UAAU;;;;;;;;;;;;;;MAAyB;IAE5C,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAMpE;IAED,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAErC;IAEK,aAAa,CACjB,WAAW,EAAE,mBAAmB,EAChC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CAM1B;IAEK,MAAM,CAAC,WAAW,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAO7F;CACF"}
+{"version":3,"file":"LinearDocumentProvider.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/LinearDocumentProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAA;AAsB5B,qBAAa,sBAAuB,YAAW,sBAAsB;IACnE,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAS;IACjC,QAAQ,CAAC,UAAU;;;;;;;;;;;;;;;MAAyB;IAE5C,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAMpE;IAED,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAErC;IAEK,aAAa,CACjB,WAAW,EAAE,mBAAmB,EAChC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CAM1B;IAEK,MAAM,CAAC,WAAW,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAO7F;CACF"}

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

@@ -7,7 +7,7 @@ export declare class NotionApiError extends Error {
 export declare class NotionProvider implements DocumentSourceProvider {
     readonly kind: 'notion';
     readonly descriptor: {
-        source: "confluence" | "github" | "linear" | "notion";
+        source: "claude-design" | "confluence" | "figma" | "github" | "linear" | "notion";
         label: string;
         icon: string;
         credentialFields: {
@@ -20,6 +20,7 @@ export declare class NotionProvider implements DocumentSourceProvider {
         refLabel: string;
         refPlaceholder: string;
         searchable?: boolean | undefined;
+        credentialScope?: "user" | "workspace" | undefined;
     };
     normalizeConnection(input: DocumentCredentials): NormalizedConnection;
     parseRef(input: string): string | null;

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

@@ -1 +1 @@
-{"version":3,"file":"NotionProvider.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/NotionProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAA;AAuB5B,yEAAyE;AACzE,qBAAa,cAAe,SAAQ,KAAK;IAErC,QAAQ,CAAC,MAAM,EAAE,MAAM;IADzB,YACW,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EAIhB;CACF;AAkGD,qBAAa,cAAe,YAAW,sBAAsB;IAC3D,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAS;IACjC,QAAQ,CAAC,UAAU;;;;;;;;;;;;;;MAAoB;IAEvC,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAMpE;IAED,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAErC;IAEK,aAAa,CACjB,WAAW,EAAE,mBAAmB,EAChC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CAe1B;IAEK,MAAM,CAAC,WAAW,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CA6B7F;IAED,iFAAiF;YACnE,WAAW;YAqBX,GAAG;CA+BlB"}
+{"version":3,"file":"NotionProvider.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/NotionProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAA;AAuB5B,yEAAyE;AACzE,qBAAa,cAAe,SAAQ,KAAK;IAErC,QAAQ,CAAC,MAAM,EAAE,MAAM;IADzB,YACW,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EAIhB;CACF;AAkGD,qBAAa,cAAe,YAAW,sBAAsB;IAC3D,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAS;IACjC,QAAQ,CAAC,UAAU;;;;;;;;;;;;;;;MAAoB;IAEvC,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAMpE;IAED,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAErC;IAEK,aAAa,CACjB,WAAW,EAAE,mBAAmB,EAChC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CAe1B;IAEK,MAAM,CAAC,WAAW,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CA6B7F;IAED,iFAAiF;YACnE,WAAW;YAqBX,GAAG;CA+BlB"}

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

@@ -0,0 +1,88 @@
+import type { DocumentSourceDescriptor } from '@cat-factory/kernel';
+/**
+ * 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 declare const CLAUDE_DESIGN_API_HOST = "api.claude.com";
+/** Where a human opens the project (the canonical URL stored on imported documents). */
+export declare const CLAUDE_DESIGN_APP_HOST = "claude.ai";
+/** What the connect UI renders, and which credentials the provider needs. */
+export declare const CLAUDE_DESIGN_DESCRIPTOR: DocumentSourceDescriptor;
+/**
+ * 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 declare function assertSafeClaudeDesignUrl(url: string): void;
+/**
+ * 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 declare function parseClaudeDesignRef(input: string): string | null;
+/** Split a composite external id back into its project id and optional file path. */
+export declare function splitClaudeDesignExternalId(externalId: string): {
+    projectId: string;
+    filePath?: string;
+};
+/** Build the canonical web URL stored on the imported document (matched by `getByUrl`). */
+export declare function claudeDesignUrlFor(externalId: string): string;
+/** A single component card, as recorded by Claude Design's `@dsCard` markers/manifest. */
+export interface DsCard {
+    name?: string;
+    group?: string;
+    subtitle?: string;
+    path?: string;
+}
+/** One fetched project file (path + raw textual content). */
+export interface ClaudeDesignFile {
+    path: string;
+    content: string;
+}
+/** The manifest file name Claude Design compiles its card index into. */
+export declare const DS_MANIFEST_PATH = "_ds_manifest.json";
+/**
+ * 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 declare function parseDsManifest(json: unknown): DsCard[];
+/**
+ * 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 declare function parseDsCardComment(html: string): DsCard | null;
+/**
+ * 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 declare function extractCssTokens(content: string): string[];
+/** Strip `<script>`/`<style>` blocks and all tags, returning collapsed visible text. */
+export declare function htmlToText(html: string): string;
+/** Render a grouped component inventory from a card list (`### <group>` → `- <name>`). */
+export declare function dsCardsToMarkdown(cards: DsCard[]): string;
+/**
+ * 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 declare function renderClaudeDesignProject(projectName: string, files: ClaudeDesignFile[]): string;
+//# sourceMappingURL=claudeDesign.logic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"claudeDesign.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/claudeDesign.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAmBnE;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,mBAAmB,CAAA;AAEtD,wFAAwF;AACxF,eAAO,MAAM,sBAAsB,cAAc,CAAA;AAEjD,6EAA6E;AAC7E,eAAO,MAAM,wBAAwB,EAAE,wBAmBtC,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3D;AASD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkCjE;AAWD,qFAAqF;AACrF,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG;IAC/D,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAKA;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAI7D;AAID,0FAA0F;AAC1F,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,sBAAsB,CAAA;AAMnD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAmBvD;AAKD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY9D;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAW1D;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAc/C;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAsBzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,MAAM,CA+ChG"}