@cat-factory/integrations 0.6.0

package/dist/modules/datadog/datadog.logic.js

@@ -0,0 +1,90 @@
+// Pure helpers for the Datadog post-release-health integration: site validation
+// (anti-SSRF — only real Datadog hosts), base-URL construction, and mapping Datadog's
+// monitor/SLO shapes onto the runtime-neutral `ReleaseSignalState`.
+/** The domain tag used to seal Datadog credentials at rest (HKDF info). */
+export const DATADOG_CIPHER_INFO = 'cat-factory:datadog';
+/** Datadog site host suffixes we allow a connection to point at (anti-SSRF). */
+const ALLOWED_SITE_SUFFIXES = [
+    'datadoghq.com',
+    'datadoghq.eu',
+    'us3.datadoghq.com',
+    'us5.datadoghq.com',
+    'ap1.datadoghq.com',
+    'ddog-gov.com',
+];
+/**
+ * Validate a configured Datadog `site` host and return the normalized host (no
+ * scheme/path). Throws when it isn't a recognised Datadog host so a misconfiguration
+ * can't turn the server into an SSRF vector. Accepts a bare host or a full URL.
+ */
+export function normalizeDatadogSite(site) {
+    const trimmed = site
+        .trim()
+        .replace(/^https?:\/\//i, '')
+        .replace(/\/.*$/, '')
+        .toLowerCase();
+    if (!trimmed)
+        throw new DatadogApiError('config', 'Datadog site is empty');
+    const ok = ALLOWED_SITE_SUFFIXES.some((s) => trimmed === s || trimmed.endsWith(`.${s}`));
+    if (!ok) {
+        throw new DatadogApiError('config', `Unrecognised Datadog site host: ${trimmed}`);
+    }
+    return trimmed;
+}
+/** The API base URL for a (validated) site host. */
+export function datadogApiBase(site) {
+    return `https://api.${normalizeDatadogSite(site)}`;
+}
+/**
+ * Map Datadog's monitor `overall_state` string onto a release signal state.
+ *
+ * `attribution` lets the post-release-health gate ignore an alert that PREDATES the
+ * release it is watching: a monitor already alerting before `since` (an unrelated /
+ * flaky / never-recovered incident) is not attributable to this release, so it is
+ * downgraded to `warn` (which does NOT regress the gate) rather than escalating an
+ * on-call investigation that blames an innocent PR. When the transition timestamp is
+ * unknown (Datadog didn't report `overall_state_modified`) we keep the alert — better
+ * to investigate than to silently miss a real regression.
+ */
+export function mapMonitorState(overallState, attribution) {
+    switch ((overallState ?? '').toLowerCase()) {
+        case 'alert':
+        case 'alert_recovery':
+            // A pre-existing alert (state last changed before the release marker) is not this
+            // release's regression — don't escalate on it.
+            if (attribution &&
+                attribution.stateModifiedMs !== undefined &&
+                attribution.stateModifiedMs < attribution.since) {
+                return 'warn';
+            }
+            return 'alert';
+        case 'warn':
+        case 'warn_recovery':
+            return 'warn';
+        case 'ok':
+            return 'ok';
+        default:
+            // 'No Data' | 'Unknown' | 'Ignored' | 'Skipped' | undefined
+            return 'no_data';
+    }
+}
+/**
+ * Map an SLO's current SLI value vs its target onto a release signal state:
+ * below target → `alert` (error budget breached), at/above → `ok`, missing → `no_data`.
+ */
+export function mapSloState(sliValue, target) {
+    if (sliValue === null || target === null)
+        return 'no_data';
+    return sliValue < target ? 'alert' : 'ok';
+}
+export class DatadogApiError extends Error {
+    endpoint;
+    detail;
+    constructor(endpoint, detail) {
+        super(`Datadog ${endpoint} failed: ${detail}`);
+        this.endpoint = endpoint;
+        this.detail = detail;
+        this.name = 'DatadogApiError';
+    }
+}
+//# sourceMappingURL=datadog.logic.js.map

package/dist/modules/datadog/datadog.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datadog.logic.js","sourceRoot":"","sources":["../../../src/modules/datadog/datadog.logic.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,sFAAsF;AACtF,oEAAoE;AAEpE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAA;AAExD,gFAAgF;AAChF,MAAM,qBAAqB,GAAG;IAC5B,eAAe;IACf,cAAc;IACd,mBAAmB;IACnB,mBAAmB;IACnB,mBAAmB;IACnB,cAAc;CACf,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,MAAM,OAAO,GAAG,IAAI;SACjB,IAAI,EAAE;SACN,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC;SAC5B,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpB,WAAW,EAAE,CAAA;IAChB,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,eAAe,CAAC,QAAQ,EAAE,uBAAuB,CAAC,CAAA;IAC1E,MAAM,EAAE,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;IACxF,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,MAAM,IAAI,eAAe,CAAC,QAAQ,EAAE,mCAAmC,OAAO,EAAE,CAAC,CAAA;IACnF,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,eAAe,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAA;AACpD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,YAAgC,EAChC,WAAyD;IAEzD,QAAQ,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QAC3C,KAAK,OAAO,CAAC;QACb,KAAK,gBAAgB;YACnB,kFAAkF;YAClF,+CAA+C;YAC/C,IACE,WAAW;gBACX,WAAW,CAAC,eAAe,KAAK,SAAS;gBACzC,WAAW,CAAC,eAAe,GAAG,WAAW,CAAC,KAAK,EAC/C,CAAC;gBACD,OAAO,MAAM,CAAA;YACf,CAAC;YACD,OAAO,OAAO,CAAA;QAChB,KAAK,MAAM,CAAC;QACZ,KAAK,eAAe;YAClB,OAAO,MAAM,CAAA;QACf,KAAK,IAAI;YACP,OAAO,IAAI,CAAA;QACb;YACE,4DAA4D;YAC5D,OAAO,SAAS,CAAA;IACpB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,QAAuB,EAAE,MAAqB;IACxE,IAAI,QAAQ,KAAK,IAAI,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,SAAS,CAAA;IAC1D,OAAO,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAA;AAC3C,CAAC;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAE7B,QAAQ;IACR,MAAM;IAFjB,YACW,QAAgB,EAChB,MAAc;QAEvB,KAAK,CAAC,WAAW,QAAQ,YAAY,MAAM,EAAE,CAAC,CAAA;wBAHrC,QAAQ;sBACR,MAAM;QAGf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;IAC/B,CAAC;CACF"}

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

@@ -0,0 +1,29 @@
+import { type DocumentContent, type DocumentCredentials, type DocumentSearchResult, type DocumentSourceProvider, type NormalizedConnection } from '@cat-factory/kernel';
+/** Carries the HTTP status so callers can surface a meaningful error. */
+export declare class ConfluenceApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare class ConfluenceProvider implements DocumentSourceProvider {
+    readonly kind: 'confluence';
+    readonly descriptor: {
+        source: "confluence" | "github" | "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;
+    };
+    normalizeConnection(input: DocumentCredentials): NormalizedConnection;
+    parseRef(input: string): string | null;
+    fetchDocument(credentials: DocumentCredentials, externalId: string): Promise<DocumentContent>;
+    search(credentials: DocumentCredentials, query: string): Promise<DocumentSearchResult[]>;
+}
+//# sourceMappingURL=ConfluenceProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ConfluenceProvider.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/ConfluenceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAA;AAiB5B,yEAAyE;AACzE,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,MAAM,EAAE,MAAM;IADzB,YACW,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EAIhB;CACF;AA+ED,qBAAa,kBAAmB,YAAW,sBAAsB;IAC/D,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAS;IACrC,QAAQ,CAAC,UAAU;;;;;;;;;;;;;;MAAwB;IAE3C,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAepE;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,CAiD1B;IAEK,MAAM,CAAC,WAAW,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAkC7F;CACF"}

package/dist/modules/documents/ConfluenceProvider.js

@@ -0,0 +1,180 @@
+import { ValidationError, } from '@cat-factory/kernel';
+import { CONFLUENCE_DESCRIPTOR } from './confluence.logic.js';
+import * as confluenceLogic from './confluence.logic.js';
+// ConfluenceProvider: the document-source provider for Confluence Cloud. It
+// authenticates with HTTP Basic (account email + API token), fetches a page in
+// storage format, and converts the body to the Markdown the planner consumes.
+// All Confluence-specific *pure* logic (ref parsing, base-URL SSRF guard,
+// XHTML → Markdown) lives in `@cat-factory/integrations` so it is unit-testable; this
+// class is the thin `fetch` shell around it. No SDK — fetch + `btoa` suffice.
+const USER_AGENT = 'cat-factory';
+/** Bound the redirect chain so a permitted first hop can't walk us anywhere. */
+const MAX_REDIRECTS = 5;
+/** 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 ConfluenceApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'ConfluenceApiError';
+    }
+}
+/**
+ * `fetch` with redirects followed by hand so the SSRF guard runs against EVERY
+ * hop. With the default `redirect: 'follow'` the permitted site could 302 to an
+ * internal target (or downgrade https→http) and the runtime would follow it
+ * unchecked, leaking the Basic-auth token. We force `redirect: 'manual'`,
+ * re-resolve the `Location` against the current URL, and re-run the same
+ * `assertSafe` guard (https-only + host blocklist) before following.
+ */
+async function safeFetch(url, init, assertSafe) {
+    let current = url;
+    for (let hop = 0;; hop++) {
+        assertSafe(current);
+        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 >= MAX_REDIRECTS) {
+                throw new ConfluenceApiError(502, 'Confluence 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.
+ */
+async function readCappedText(res, maxBytes) {
+    const declared = res.headers.get('content-length');
+    if (declared && Number(declared) > maxBytes) {
+        throw new ConfluenceApiError(502, 'Confluence 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 ConfluenceApiError(502, 'Confluence 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);
+}
+export class ConfluenceProvider {
+    kind = 'confluence';
+    descriptor = CONFLUENCE_DESCRIPTOR;
+    normalizeConnection(input) {
+        const baseUrlRaw = input.baseUrl?.trim();
+        const accountEmail = input.accountEmail?.trim();
+        const apiToken = input.apiToken?.trim();
+        if (!baseUrlRaw || !accountEmail || !apiToken) {
+            throw new ValidationError('Confluence requires a site URL, account email and API token');
+        }
+        const baseUrl = confluenceLogic.normalizeBaseUrl(baseUrlRaw);
+        // Guard against SSRF: the stored base URL is later fetched with the
+        // workspace's credentials, so it must be a public https host.
+        confluenceLogic.assertSafeConfluenceBaseUrl(baseUrl);
+        return {
+            credentials: { baseUrl, accountEmail, apiToken },
+            label: baseUrl,
+        };
+    }
+    parseRef(input) {
+        return confluenceLogic.parseConfluenceRef(input);
+    }
+    async fetchDocument(credentials, externalId) {
+        const base = credentials.baseUrl.replace(/\/+$/, '');
+        const url = `${base}/wiki/rest/api/content/${encodeURIComponent(externalId)}?expand=body.storage,version`;
+        const auth = btoa(`${credentials.accountEmail}:${credentials.apiToken}`);
+        const res = await safeFetch(url, {
+            method: 'GET',
+            headers: {
+                authorization: `Basic ${auth}`,
+                accept: 'application/json',
+                'user-agent': USER_AGENT,
+            },
+        }, (u) => confluenceLogic.assertSafeConfluenceBaseUrl(u));
+        if (!res.ok) {
+            const text = await readCappedText(res, MAX_RESPONSE_BYTES).catch(() => '');
+            throw new ConfluenceApiError(res.status, `Confluence GET ${url} → ${res.status}: ${text.slice(0, 300)}`);
+        }
+        const text = await readCappedText(res, MAX_RESPONSE_BYTES);
+        const json = (() => {
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return null;
+            }
+        })();
+        if (!json || !json.id) {
+            throw new ConfluenceApiError(502, `Confluence returned an unexpected body for page ${externalId}`);
+        }
+        const linkBase = json._links?.base ?? `${base}/wiki`;
+        const webui = json._links?.webui ?? '';
+        return {
+            externalId: json.id,
+            title: json.title ?? '(untitled)',
+            url: `${linkBase}${webui}`,
+            body: confluenceLogic.confluenceStorageToMarkdown(json.body?.storage?.value ?? ''),
+        };
+    }
+    async search(credentials, query) {
+        const base = credentials.baseUrl.replace(/\/+$/, '');
+        const cql = encodeURIComponent(confluenceLogic.buildConfluenceSearchCql(query));
+        const url = `${base}/wiki/rest/api/content/search?cql=${cql}&limit=20`;
+        const auth = btoa(`${credentials.accountEmail}:${credentials.apiToken}`);
+        const res = await safeFetch(url, {
+            method: 'GET',
+            headers: {
+                authorization: `Basic ${auth}`,
+                accept: 'application/json',
+                'user-agent': USER_AGENT,
+            },
+        }, (u) => confluenceLogic.assertSafeConfluenceBaseUrl(u));
+        if (!res.ok) {
+            const text = await readCappedText(res, MAX_RESPONSE_BYTES).catch(() => '');
+            throw new ConfluenceApiError(res.status, `Confluence search ${url} → ${res.status}: ${text.slice(0, 300)}`);
+        }
+        const text = await readCappedText(res, MAX_RESPONSE_BYTES);
+        const json = (() => {
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return null;
+            }
+        })();
+        return confluenceLogic.parseConfluenceSearchResults(json, base);
+    }
+}
+//# sourceMappingURL=ConfluenceProvider.js.map

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

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

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

@@ -0,0 +1,30 @@
+import type { Clock } from '@cat-factory/kernel';
+import type { DocumentConnectionRecord, DocumentConnectionRepository } from '@cat-factory/kernel';
+import type { DocumentSourceRegistry } from '@cat-factory/kernel';
+import type { DocumentConnection, DocumentSourceDescriptor, DocumentSourceKind } from '@cat-factory/kernel';
+import type { WorkspaceRepository } from '@cat-factory/kernel';
+export interface DocumentConnectionServiceDependencies {
+    documentConnectionRepository: DocumentConnectionRepository;
+    registry: DocumentSourceRegistry;
+    workspaceRepository: WorkspaceRepository;
+    clock: Clock;
+}
+export declare class DocumentConnectionService {
+    private readonly deps;
+    constructor(deps: DocumentConnectionServiceDependencies);
+    /** The descriptors of every configured source (drives the connect UI). */
+    listSources(): DocumentSourceDescriptor[];
+    /** Resolve a provider for a source or throw if that source isn't configured. */
+    private requireProvider;
+    /** Connect (or re-connect) a workspace to a document source. */
+    connect(workspaceId: string, source: DocumentSourceKind, credentials: Record<string, string>): Promise<DocumentConnection>;
+    /** The workspace's current connection for a source, or null if not connected. */
+    getConnection(workspaceId: string, source: DocumentSourceKind): Promise<DocumentConnection | null>;
+    /** Every live connection the workspace holds, across sources. */
+    listConnections(workspaceId: string): Promise<DocumentConnection[]>;
+    /** Resolve the live connection (with credentials) or throw if not connected. */
+    requireConnection(workspaceId: string, source: DocumentSourceKind): Promise<DocumentConnectionRecord>;
+    /** Disconnect a workspace from a source (tombstones the binding). */
+    disconnect(workspaceId: string, source: DocumentSourceKind): Promise<void>;
+}
+//# sourceMappingURL=DocumentConnectionService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentConnectionService.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/DocumentConnectionService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAChD,OAAO,KAAK,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAA;AACjG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AACjE,OAAO,KAAK,EACV,kBAAkB,EAClB,wBAAwB,EACxB,kBAAkB,EACnB,MAAM,qBAAqB,CAAA;AAG5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAQ9D,MAAM,WAAW,qCAAqC;IACpD,4BAA4B,EAAE,4BAA4B,CAAA;IAC1D,QAAQ,EAAE,sBAAsB,CAAA;IAChC,mBAAmB,EAAE,mBAAmB,CAAA;IACxC,KAAK,EAAE,KAAK,CAAA;CACb;AAUD,qBAAa,yBAAyB;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,qCAAqC,EAAI;IAE5E,0EAA0E;IAC1E,WAAW,IAAI,wBAAwB,EAAE,CAExC;IAED,gFAAgF;IAChF,OAAO,CAAC,eAAe;IAMvB,gEAAgE;IAC1D,OAAO,CACX,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,EAC1B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,OAAO,CAAC,kBAAkB,CAAC,CAkB7B;IAED,iFAAiF;IAC3E,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAGpC;IAED,iEAAiE;IAC3D,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAGxE;IAED,gFAAgF;IAC1E,iBAAiB,CACrB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,wBAAwB,CAAC,CAMnC;IAED,qEAAqE;IAC/D,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/E;CACF"}

package/dist/modules/documents/DocumentConnectionService.js

@@ -0,0 +1,69 @@
+import { ConflictError, ValidationError } from '@cat-factory/kernel';
+import { requireWorkspace } from '@cat-factory/kernel';
+function toConnection(record) {
+    return {
+        source: record.source,
+        label: record.label,
+        connectedAt: record.createdAt,
+    };
+}
+export class DocumentConnectionService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** The descriptors of every configured source (drives the connect UI). */
+    listSources() {
+        return this.deps.registry.list().map((p) => p.descriptor);
+    }
+    /** Resolve a provider for a source or throw if that source isn't configured. */
+    requireProvider(source) {
+        const provider = this.deps.registry.get(source);
+        if (!provider)
+            throw new ValidationError(`Unknown or unconfigured document source '${source}'`);
+        return provider;
+    }
+    /** Connect (or re-connect) a workspace to a document source. */
+    async connect(workspaceId, source, credentials) {
+        await requireWorkspace(this.deps.workspaceRepository, workspaceId);
+        const provider = this.requireProvider(source);
+        const normalized = provider.normalizeConnection(credentials);
+        const existing = await this.deps.documentConnectionRepository.getByWorkspace(workspaceId, source);
+        const record = {
+            workspaceId,
+            source,
+            credentials: normalized.credentials,
+            label: normalized.label,
+            createdAt: existing?.createdAt ?? this.deps.clock.now(),
+            deletedAt: null,
+        };
+        await this.deps.documentConnectionRepository.upsert(record);
+        return toConnection(record);
+    }
+    /** The workspace's current connection for a source, or null if not connected. */
+    async getConnection(workspaceId, source) {
+        const record = await this.deps.documentConnectionRepository.getByWorkspace(workspaceId, source);
+        return record ? toConnection(record) : null;
+    }
+    /** Every live connection the workspace holds, across sources. */
+    async listConnections(workspaceId) {
+        const records = await this.deps.documentConnectionRepository.listByWorkspace(workspaceId);
+        return records.map(toConnection);
+    }
+    /** Resolve the live connection (with credentials) or throw if not connected. */
+    async requireConnection(workspaceId, source) {
+        const record = await this.deps.documentConnectionRepository.getByWorkspace(workspaceId, source);
+        if (!record) {
+            throw new ConflictError(`Workspace '${workspaceId}' is not connected to ${source}`);
+        }
+        return record;
+    }
+    /** Disconnect a workspace from a source (tombstones the binding). */
+    async disconnect(workspaceId, source) {
+        const record = await this.deps.documentConnectionRepository.getByWorkspace(workspaceId, source);
+        if (!record)
+            return;
+        await this.deps.documentConnectionRepository.softDelete(workspaceId, source, this.deps.clock.now());
+    }
+}
+//# sourceMappingURL=DocumentConnectionService.js.map

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

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

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

@@ -0,0 +1,34 @@
+import type { Clock } from '@cat-factory/kernel';
+import type { DocumentSourceRegistry } from '@cat-factory/kernel';
+import type { DocumentRecord, DocumentRepository } from '@cat-factory/kernel';
+import type { SourceDocument, DocumentSearchResult, DocumentSourceKind } from '@cat-factory/kernel';
+import type { WorkspaceRepository } from '@cat-factory/kernel';
+import type { DocumentConnectionService } from './DocumentConnectionService.js';
+export interface DocumentImportServiceDependencies {
+    registry: DocumentSourceRegistry;
+    documentRepository: DocumentRepository;
+    connectionService: DocumentConnectionService;
+    workspaceRepository: WorkspaceRepository;
+    clock: Clock;
+}
+/** Project a stored document record onto the wire shape (drops body + tombstone). */
+export declare function toSourceDocument(record: DocumentRecord): SourceDocument;
+export declare class DocumentImportService {
+    private readonly deps;
+    constructor(deps: DocumentImportServiceDependencies);
+    private requireProvider;
+    /** Fetch a page (by id or URL) and upsert its projection; returns the document. */
+    import(workspaceId: string, source: DocumentSourceKind, ref: string): Promise<SourceDocument>;
+    /**
+     * Search a source's catalogue by free text, returning lean hits (not yet
+     * imported). The provider authenticates with the workspace's stored credentials
+     * and builds/parses the source-specific query. Throws if the source can't
+     * search (no provider `search`), so the controller can answer cleanly.
+     */
+    search(workspaceId: string, source: DocumentSourceKind, query: string): Promise<DocumentSearchResult[]>;
+    /** Every document imported into the workspace, across sources, as wire shapes. */
+    listDocuments(workspaceId: string): Promise<SourceDocument[]>;
+    /** Resolve a stored document record (with body) or throw if not imported. */
+    requireDocument(workspaceId: string, source: DocumentSourceKind, externalId: string): Promise<DocumentRecord>;
+}
+//# sourceMappingURL=DocumentImportService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentImportService.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/DocumentImportService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAChD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAGnG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAA;AAS/E,MAAM,WAAW,iCAAiC;IAChD,QAAQ,EAAE,sBAAsB,CAAA;IAChC,kBAAkB,EAAE,kBAAkB,CAAA;IACtC,iBAAiB,EAAE,yBAAyB,CAAA;IAC5C,mBAAmB,EAAE,mBAAmB,CAAA;IACxC,KAAK,EAAE,KAAK,CAAA;CACb;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAUvE;AAED,qBAAa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,iCAAiC,EAAI;IAExE,OAAO,CAAC,eAAe;IAMvB,mFAAmF;IAC7E,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,EAC1B,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,cAAc,CAAC,CA0BzB;IAED;;;;;OAKG;IACG,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAQjC;IAED,kFAAkF;IAC5E,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAGlE;IAED,6EAA6E;IACvE,eAAe,CACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,EAC1B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,CAMzB;CACF"}

package/dist/modules/documents/DocumentImportService.js

@@ -0,0 +1,83 @@
+import { ValidationError } from '@cat-factory/kernel';
+import { requireWorkspace } from '@cat-factory/kernel';
+import { buildExcerpt } from './documents.logic.js';
+/** Project a stored document record onto the wire shape (drops body + tombstone). */
+export function toSourceDocument(record) {
+    return {
+        source: record.source,
+        externalId: record.externalId,
+        title: record.title,
+        url: record.url,
+        excerpt: record.excerpt,
+        linkedBlockId: record.linkedBlockId,
+        syncedAt: record.syncedAt,
+    };
+}
+export class DocumentImportService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    requireProvider(source) {
+        const provider = this.deps.registry.get(source);
+        if (!provider)
+            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) {
+        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 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);
+        const record = {
+            workspaceId,
+            source,
+            externalId: content.externalId,
+            title: content.title,
+            url: content.url,
+            excerpt: buildExcerpt(content.body),
+            body: content.body,
+            linkedBlockId: existing?.linkedBlockId ?? null,
+            syncedAt: this.deps.clock.now(),
+            deletedAt: null,
+        };
+        await this.deps.documentRepository.upsert(record);
+        return toSourceDocument(record);
+    }
+    /**
+     * Search a source's catalogue by free text, returning lean hits (not yet
+     * imported). The provider authenticates with the workspace's stored credentials
+     * 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) {
+        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);
+        return provider.search(connection.credentials, query, workspaceId);
+    }
+    /** Every document imported into the workspace, across sources, as wire shapes. */
+    async listDocuments(workspaceId) {
+        const records = await this.deps.documentRepository.listByWorkspace(workspaceId);
+        return records.map(toSourceDocument);
+    }
+    /** Resolve a stored document record (with body) or throw if not imported. */
+    async requireDocument(workspaceId, source, externalId) {
+        const record = await this.deps.documentRepository.get(workspaceId, source, externalId);
+        if (!record) {
+            throw new ValidationError(`${source} page '${externalId}' has not been imported`);
+        }
+        return record;
+    }
+}
+//# sourceMappingURL=DocumentImportService.js.map

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

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

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

@@ -0,0 +1,31 @@
+import type { DocumentBoardPlan, SourceDocument, DocumentSourceKind } from '@cat-factory/kernel';
+import type { BlockRepository } from '@cat-factory/kernel';
+import type { DocumentRepository } from '@cat-factory/kernel';
+import type { BoardWritePort } from '@cat-factory/kernel';
+export interface DocumentLinkServiceDependencies {
+    boardService: BoardWritePort;
+    blockRepository: BlockRepository;
+    documentRepository: DocumentRepository;
+}
+/** Counts of blocks created by a spawn, for the API response. */
+export interface SpawnResult {
+    frames: number;
+    modules: number;
+    tasks: number;
+}
+export declare class DocumentLinkService {
+    private readonly deps;
+    constructor(deps: DocumentLinkServiceDependencies);
+    /**
+     * Apply a board plan to a workspace. Without `frameId` each planned frame
+     * becomes a new top-level frame; with it, the plan's modules and tasks are
+     * added inside that existing frame (the planned frames are flattened into it).
+     */
+    spawn(workspaceId: string, plan: DocumentBoardPlan, frameId?: string): Promise<SpawnResult>;
+    /** Add a planned frame's modules and tasks inside an existing frame. */
+    private spawnInto;
+    private addTask;
+    /** Attach an imported document to a board block as extra agent context. */
+    linkToBlock(workspaceId: string, blockId: string, source: DocumentSourceKind, externalId: string): Promise<SourceDocument>;
+}
+//# sourceMappingURL=DocumentLinkService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentLinkService.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/DocumentLinkService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAEnB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AASzD,MAAM,WAAW,+BAA+B;IAC9C,YAAY,EAAE,cAAc,CAAA;IAC5B,eAAe,EAAE,eAAe,CAAA;IAChC,kBAAkB,EAAE,kBAAkB,CAAA;CACvC;AAED,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd;AAED,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,+BAA+B,EAAI;IAEtE;;;;OAIG;IACG,KAAK,CACT,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,CAAC,CAiCtB;IAED,wEAAwE;YAC1D,SAAS;YAoBT,OAAO;IAiBrB,2EAA2E;IACrE,WAAW,CACf,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,kBAAkB,EAC1B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,CAazB;CACF"}