@cat-factory/integrations 0.6.0

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

@@ -0,0 +1,37 @@
+import type { DocumentSearchResult, DocumentSourceDescriptor } from '@cat-factory/kernel';
+/** What the connect UI renders, and which credentials the provider needs. */
+export declare const CONFLUENCE_DESCRIPTOR: DocumentSourceDescriptor;
+/**
+ * Build the CQL for a free-text page search: match the term anywhere in a page's
+ * text, newest first. Confluence's `text ~` is a fuzzy/word search, which is
+ * exactly what a "find a page" box wants.
+ */
+export declare function buildConfluenceSearchCql(query: string): string;
+/**
+ * Map a Confluence search response into lean hits. The endpoint nests the page
+ * under `content` (search API) or returns it flat (content/search API); we read
+ * either. URLs are resolved against the response's `base`, falling back to the
+ * site's `/wiki` base when absent.
+ */
+export declare function parseConfluenceSearchResults(json: unknown, fallbackBase: string): DocumentSearchResult[];
+/** Drop a trailing slash and a trailing `/wiki` so we can build paths uniformly. */
+export declare function normalizeBaseUrl(baseUrl: string): string;
+/**
+ * Resolve a Confluence page id from raw user input: a bare numeric id, a modern
+ * `/wiki/spaces/…/pages/<id>/…` URL, or a legacy `?pageId=<id>` URL.
+ */
+export declare function parseConfluenceRef(input: string): string | null;
+/**
+ * Validate a (normalized) Confluence base URL before it is stored and later
+ * fetched. Delegates to the shared Atlassian guard (`https`-only, no embedded
+ * credentials, no internal/private hosts), throwing {@link ValidationError} on
+ * anything unsafe.
+ */
+export declare function assertSafeConfluenceBaseUrl(baseUrl: string): void;
+/**
+ * Convert Confluence storage-format XHTML into the lightweight Markdown the
+ * generic planner/excerpt logic consumes: headings become `#`/`##`/`###`, list
+ * items become `- `, and block boundaries become newlines.
+ */
+export declare function confluenceStorageToMarkdown(html: string): string;
+//# sourceMappingURL=confluence.logic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"confluence.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/confluence.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AASzF,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,EAAE,wBAuBnC,CAAA;AAOD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAYD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,MAAM,GACnB,oBAAoB,EAAE,CAkBxB;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ/D;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEjE;AAaD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWhE"}

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

@@ -0,0 +1,133 @@
+import { assertSafeAtlassianBaseUrl, normalizeAtlassianBaseUrl } from '@cat-factory/kernel';
+// Confluence-specific pure logic, kept out of the worker so it is unit-testable
+// without a live site: parsing a page id out of user input, validating/securing
+// the site base URL, and converting storage-format XHTML into the lightweight
+// Markdown the generic planner consumes. The fetch itself lives in the worker's
+// ConfluenceProvider.
+/** What the connect UI renders, and which credentials the provider needs. */
+export const CONFLUENCE_DESCRIPTOR = {
+    source: 'confluence',
+    label: 'Confluence',
+    icon: 'i-lucide-book-open',
+    credentialFields: [
+        {
+            key: 'baseUrl',
+            label: 'Site URL',
+            placeholder: 'https://your-team.atlassian.net',
+            help: 'e.g. https://your-team.atlassian.net',
+        },
+        { key: 'accountEmail', label: 'Account email', placeholder: 'you@company.com' },
+        {
+            key: 'apiToken',
+            label: 'API token',
+            secret: true,
+            placeholder: 'Paste a Confluence API token',
+            help: 'Create one at id.atlassian.com → Security → API tokens',
+        },
+    ],
+    refLabel: 'Page URL or ID',
+    refPlaceholder: 'https://…/pages/12345/Title  or  12345',
+    searchable: true,
+};
+/** Escape a user string for embedding inside a CQL double-quoted literal. */
+function escapeCql(query) {
+    return query.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/**
+ * Build the CQL for a free-text page search: match the term anywhere in a page's
+ * text, newest first. Confluence's `text ~` is a fuzzy/word search, which is
+ * exactly what a "find a page" box wants.
+ */
+export function buildConfluenceSearchCql(query) {
+    return `type = page AND text ~ "${escapeCql(query.trim())}" ORDER BY lastmodified DESC`;
+}
+/**
+ * Map a Confluence search response into lean hits. The endpoint nests the page
+ * under `content` (search API) or returns it flat (content/search API); we read
+ * either. URLs are resolved against the response's `base`, falling back to the
+ * site's `/wiki` base when absent.
+ */
+export function parseConfluenceSearchResults(json, fallbackBase) {
+    const body = (json ?? {});
+    const base = body._links?.base ?? `${fallbackBase.replace(/\/+$/, '')}/wiki`;
+    const out = [];
+    for (const row of Array.isArray(body.results) ? body.results : []) {
+        const content = row.content ?? row;
+        const id = content.id;
+        if (!id)
+            continue;
+        const webui = row._links?.webui ?? '';
+        out.push({
+            source: 'confluence',
+            externalId: id,
+            title: content.title ?? '(untitled)',
+            url: webui ? `${base}${webui}` : `${base}/pages/${id}`,
+            excerpt: '',
+        });
+    }
+    return out;
+}
+/** Drop a trailing slash and a trailing `/wiki` so we can build paths uniformly. */
+export function normalizeBaseUrl(baseUrl) {
+    return normalizeAtlassianBaseUrl(baseUrl);
+}
+/**
+ * Resolve a Confluence page id from raw user input: a bare numeric id, a modern
+ * `/wiki/spaces/…/pages/<id>/…` URL, or a legacy `?pageId=<id>` URL.
+ */
+export function parseConfluenceRef(input) {
+    const trimmed = input.trim();
+    if (/^\d+$/.test(trimmed))
+        return trimmed;
+    const pageIdParam = trimmed.match(/[?&]pageId=(\d+)/);
+    if (pageIdParam)
+        return pageIdParam[1];
+    const pathMatch = trimmed.match(/\/pages\/(?:[a-z-]+\/)?(\d+)/i);
+    if (pathMatch)
+        return pathMatch[1];
+    return null;
+}
+/**
+ * Validate a (normalized) Confluence base URL before it is stored and later
+ * fetched. Delegates to the shared Atlassian guard (`https`-only, no embedded
+ * credentials, no internal/private hosts), throwing {@link ValidationError} on
+ * anything unsafe.
+ */
+export function assertSafeConfluenceBaseUrl(baseUrl) {
+    assertSafeAtlassianBaseUrl(baseUrl);
+}
+/** Decode the handful of XHTML entities Confluence storage format emits. */
+function decodeEntities(text) {
+    return text
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#3?9;|&apos;/gi, "'");
+}
+/**
+ * Convert Confluence storage-format XHTML into the lightweight Markdown the
+ * generic planner/excerpt logic consumes: headings become `#`/`##`/`###`, list
+ * items become `- `, and block boundaries become newlines.
+ */
+export function confluenceStorageToMarkdown(html) {
+    const withMarkers = html
+        .replace(/<h1\b[^>]*>([\s\S]*?)<\/h1>/gi, (_m, c) => `\n# ${stripTags(c)}\n`)
+        .replace(/<h2\b[^>]*>([\s\S]*?)<\/h2>/gi, (_m, c) => `\n## ${stripTags(c)}\n`)
+        .replace(/<h[3-6]\b[^>]*>([\s\S]*?)<\/h[3-6]>/gi, (_m, c) => `\n### ${stripTags(c)}\n`)
+        .replace(/<li\b[^>]*>([\s\S]*?)<\/li>/gi, (_m, c) => `\n- ${stripTags(c)}\n`)
+        .replace(/<\s*(br|\/p|\/div)\s*\/?>/gi, '\n');
+    return decodeEntities(stripTags(withMarkers))
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/** Strip any remaining tags and collapse intra-line whitespace. */
+function stripTags(html) {
+    return html
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/[ \t]+/g, ' ')
+        .trim();
+}
+//# sourceMappingURL=confluence.logic.js.map

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

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

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

@@ -0,0 +1,22 @@
+import type { DocumentSourceKind } from '@cat-factory/kernel';
+import type { DocumentBoardPlan } from '@cat-factory/kernel';
+import type { DocumentSourceProvider, DocumentSourceRegistry } from '@cat-factory/kernel';
+import { buildExcerpt, markdownToText, MapSourceRegistry } from '@cat-factory/kernel';
+export { buildExcerpt, markdownToText };
+/** A trivial in-memory provider registry built from the wired providers. */
+export declare class MapDocumentSourceRegistry extends MapSourceRegistry<DocumentSourceKind, DocumentSourceProvider> implements DocumentSourceRegistry {
+}
+/**
+ * Deterministic fallback planner: map the document's heading outline onto the
+ * board. h1 → a service frame, h2 → a module within it, h3 → a task within the
+ * current module (or directly in the frame). Used whenever no LLM is configured,
+ * and as the safety net when an LLM response can't be parsed.
+ */
+export declare function planFromHeadings(source: DocumentSourceKind, externalId: string, title: string, body: string): DocumentBoardPlan;
+/**
+ * Coerce an LLM's parsed JSON into a well-formed {@link DocumentBoardPlan},
+ * dropping anything malformed. Returns null when nothing usable remains, so the
+ * caller can fall back to the heading parser.
+ */
+export declare function coercePlan(source: DocumentSourceKind, externalId: string, parsed: unknown): DocumentBoardPlan | null;
+//# sourceMappingURL=documents.logic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documents.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/documents.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAmC,MAAM,qBAAqB,CAAA;AAC7F,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AACzF,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAKrF,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,CAAA;AAmBvC,4EAA4E;AAC5E,qBAAa,yBACX,SAAQ,iBAAiB,CAAC,kBAAkB,EAAE,sBAAsB,CACpE,YAAW,sBAAsB;CAAG;AAmBtC;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,kBAAkB,EAC1B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACX,iBAAiB,CAiCnB;AAiBD;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,kBAAkB,EAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,OAAO,GACd,iBAAiB,GAAG,IAAI,CAiC1B"}

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

@@ -0,0 +1,138 @@
+import { buildExcerpt, markdownToText, MapSourceRegistry } from '@cat-factory/kernel';
+// `markdownToText`/`buildExcerpt` now live in the shared markdown helpers (also
+// used by the task-source integration); re-exported here so existing
+// `documentsLogic.*` consumers are unchanged.
+export { buildExcerpt, markdownToText };
+// Source-agnostic helpers shared by every document source: deriving a plain-text
+// excerpt from a Markdown body, the deterministic heading-based planner, and
+// coercion of an LLM's JSON into a well-formed board plan. Providers normalize
+// their page bodies to lightweight Markdown so these stay independent of any one
+// source's format. Keeping them pure makes the planner deterministic and
+// trivially testable without a live source or an LLM.
+const BLOCK_TYPES = [
+    'frontend',
+    'service',
+    'api',
+    'database',
+    'queue',
+    'integration',
+    'external',
+];
+/** A trivial in-memory provider registry built from the wired providers. */
+export class MapDocumentSourceRegistry extends MapSourceRegistry {
+}
+/** Extract `#`/`##`/`###` headings (clamped to 1–3), in document order. */
+function extractHeadings(markdown) {
+    const headings = [];
+    const re = /^[ \t]*(#{1,6})[ \t]+(.+?)[ \t]*#*$/gm;
+    let m;
+    while ((m = re.exec(markdown)) !== null) {
+        const text = m[2].trim();
+        if (text)
+            headings.push({ level: Math.min(m[1].length, 3), text });
+    }
+    return headings;
+}
+/**
+ * Deterministic fallback planner: map the document's heading outline onto the
+ * board. h1 → a service frame, h2 → a module within it, h3 → a task within the
+ * current module (or directly in the frame). Used whenever no LLM is configured,
+ * and as the safety net when an LLM response can't be parsed.
+ */
+export function planFromHeadings(source, externalId, title, body) {
+    const headings = extractHeadings(body);
+    const frames = [];
+    let frame = null;
+    let module = null;
+    const ensureFrame = () => {
+        if (!frame) {
+            frame = { type: 'service', title, modules: [], tasks: [] };
+            frames.push(frame);
+        }
+        return frame;
+    };
+    for (const heading of headings) {
+        if (heading.level === 1) {
+            frame = { type: 'service', title: heading.text, modules: [], tasks: [] };
+            frames.push(frame);
+            module = null;
+        }
+        else if (heading.level === 2) {
+            module = { name: heading.text, tasks: [] };
+            ensureFrame().modules.push(module);
+        }
+        else {
+            const task = { title: heading.text };
+            if (module)
+                module.tasks.push(task);
+            else
+                ensureFrame().tasks.push(task);
+        }
+    }
+    if (frames.length === 0) {
+        frames.push({ type: 'service', title, modules: [], tasks: [] });
+    }
+    return { source, externalId, planner: 'headings', frames };
+}
+function asString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function coerceTask(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const obj = value;
+    const title = asString(obj.title);
+    if (!title)
+        return null;
+    const task = { title };
+    const description = asString(obj.description);
+    if (description)
+        task.description = description;
+    return task;
+}
+/**
+ * Coerce an LLM's parsed JSON into a well-formed {@link DocumentBoardPlan},
+ * dropping anything malformed. Returns null when nothing usable remains, so the
+ * caller can fall back to the heading parser.
+ */
+export function coercePlan(source, externalId, parsed) {
+    const root = parsed;
+    const rawFrames = Array.isArray(root?.frames) ? root.frames : [];
+    const frames = [];
+    for (const raw of rawFrames) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const obj = raw;
+        const title = asString(obj.title);
+        if (!title)
+            continue;
+        const type = BLOCK_TYPES.includes(obj.type)
+            ? obj.type
+            : 'service';
+        const modules = [];
+        for (const rawModule of Array.isArray(obj.modules) ? obj.modules : []) {
+            if (typeof rawModule !== 'object' || rawModule === null)
+                continue;
+            const mod = rawModule;
+            const name = asString(mod.name);
+            if (!name)
+                continue;
+            const tasks = (Array.isArray(mod.tasks) ? mod.tasks : [])
+                .map(coerceTask)
+                .filter((t) => t !== null);
+            modules.push({ name, tasks });
+        }
+        const tasks = (Array.isArray(obj.tasks) ? obj.tasks : [])
+            .map(coerceTask)
+            .filter((t) => t !== null);
+        const frame = { type, title, modules, tasks };
+        const description = asString(obj.description);
+        if (description)
+            frame.description = description;
+        frames.push(frame);
+    }
+    if (frames.length === 0)
+        return null;
+    return { source, externalId, planner: 'llm', frames };
+}
+//# sourceMappingURL=documents.logic.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documents.logic.js","sourceRoot":"","sources":["../../../src/modules/documents/documents.logic.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAErF,gFAAgF;AAChF,qEAAqE;AACrE,8CAA8C;AAC9C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,CAAA;AAEvC,iFAAiF;AACjF,6EAA6E;AAC7E,+EAA+E;AAC/E,iFAAiF;AACjF,yEAAyE;AACzE,sDAAsD;AAEtD,MAAM,WAAW,GAAyB;IACxC,UAAU;IACV,SAAS;IACT,KAAK;IACL,UAAU;IACV,OAAO;IACP,aAAa;IACb,UAAU;CACX,CAAA;AAED,4EAA4E;AAC5E,MAAM,OAAO,yBACX,SAAQ,iBAA6D;CACjC;AAOtC,2EAA2E;AAC3E,SAAS,eAAe,CAAC,QAAgB;IACvC,MAAM,QAAQ,GAAc,EAAE,CAAA;IAC9B,MAAM,EAAE,GAAG,uCAAuC,CAAA;IAClD,IAAI,CAAyB,CAAA;IAC7B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAA;QACzB,IAAI,IAAI;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;IACrE,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA0B,EAC1B,UAAkB,EAClB,KAAa,EACb,IAAY;IAEZ,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;IACtC,MAAM,MAAM,GAAgB,EAAE,CAAA;IAC9B,IAAI,KAAK,GAAqB,IAAI,CAAA;IAClC,IAAI,MAAM,GAAsB,IAAI,CAAA;IAEpC,MAAM,WAAW,GAAG,GAAc,EAAE;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAA;YAC1D,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACpB,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;YACxB,KAAK,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAA;YACxE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAClB,MAAM,GAAG,IAAI,CAAA;QACf,CAAC;aAAM,IAAI,OAAO,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAA;YAC1C,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACpC,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GAAa,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,CAAA;YAC9C,IAAI,MAAM;gBAAE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;;gBAC9B,WAAW,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACrC,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAA;IACjE,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAA;AAC5D,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;AACpF,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IAC5D,MAAM,GAAG,GAAG,KAAgC,CAAA;IAC5C,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IACjC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IACvB,MAAM,IAAI,GAAa,EAAE,KAAK,EAAE,CAAA;IAChC,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;IAC7C,IAAI,WAAW;QAAE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;IAC/C,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,MAA0B,EAC1B,UAAkB,EAClB,MAAe;IAEf,MAAM,IAAI,GAAG,MAAwC,CAAA;IACrD,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAA;IACjE,MAAM,MAAM,GAAgB,EAAE,CAAA;IAC9B,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;YAAE,SAAQ;QACrD,MAAM,GAAG,GAAG,GAA8B,CAAA;QAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACjC,IAAI,CAAC,KAAK;YAAE,SAAQ;QACpB,MAAM,IAAI,GAAI,WAAiC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAc,CAAC;YAC1E,CAAC,CAAE,GAAG,CAAC,IAAkB;YACzB,CAAC,CAAC,SAAS,CAAA;QACb,MAAM,OAAO,GAAiB,EAAE,CAAA;QAChC,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACtE,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI;gBAAE,SAAQ;YACjE,MAAM,GAAG,GAAG,SAAoC,CAAA;YAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;YAC/B,IAAI,CAAC,IAAI;gBAAE,SAAQ;YACnB,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;iBACtD,GAAG,CAAC,UAAU,CAAC;iBACf,MAAM,CAAC,CAAC,CAAC,EAAiB,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAA;YAC3C,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;QAC/B,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;aACtD,GAAG,CAAC,UAAU,CAAC;aACf,MAAM,CAAC,CAAC,CAAC,EAAiB,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAA;QAC3C,MAAM,KAAK,GAAc,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;QACxD,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QAC7C,IAAI,WAAW;YAAE,KAAK,CAAC,WAAW,GAAG,WAAW,CAAA;QAChD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACpB,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACpC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AACvD,CAAC"}

package/dist/modules/documents/github-docs.logic.d.ts

@@ -0,0 +1,52 @@
+import type { DocumentSourceDescriptor } from '@cat-factory/kernel';
+/**
+ * What the connect UI renders. GitHub docs piggyback on the workspace's existing
+ * GitHub App installation, so there are NO credential fields — the connect form
+ * is just a confirmation, and `normalizeConnection` accepts an empty bag.
+ */
+export declare const GITHUB_DOCS_DESCRIPTOR: DocumentSourceDescriptor;
+/** The parts of a GitHub doc external id (`owner/repo:path`). */
+export interface GitHubDocExternalId {
+    owner: string;
+    repo: string;
+    /** Path relative to the repo root, e.g. `docs/architecture.md`. */
+    path: string;
+}
+/** Build the canonical `owner/repo:path` external id from its parts. */
+export declare function githubDocExternalId(id: GitHubDocExternalId): string;
+/**
+ * Resolve a GitHub repo-doc reference from raw user input into the canonical
+ * `owner/repo:path` external id. Accepts:
+ *   - a blob URL: `https://github.com/octo/repo/blob/main/docs/x.md`
+ *   - a raw URL: `https://raw.githubusercontent.com/octo/repo/main/docs/x.md`
+ *   - the shorthand `octo/repo:docs/x.md`
+ * The branch/ref in a URL is dropped — the provider reads the default branch — so
+ * the external id (and thus a re-import's identity) is branch-stable. Returns
+ * null when nothing parses. Owner/repo/path are kept verbatim (case-preserving).
+ *
+ * KNOWN LIMITATION: a URL whose branch name itself contains a slash
+ * (`…/blob/feature/x/README.md`) is ambiguous — the branch/path boundary cannot
+ * be recovered from the URL alone, so the first segment after `blob/` (or the
+ * ref slot of a raw URL) is assumed to be the whole ref and the rest the path.
+ * For files on a slash-named branch, use the unambiguous `owner/repo:path`
+ * shorthand instead. (The default branch is what the provider actually reads.)
+ */
+export declare function parseGitHubDocRef(input: string): string | null;
+/**
+ * Split a stored `owner/repo:path` external id back into its parts. Returns null
+ * if the id is malformed (defensive — ids are produced by
+ * {@link parseGitHubDocRef}, but a stale/hand-edited row should not throw).
+ */
+export declare function parseGitHubDocExternalId(externalId: string): GitHubDocExternalId | null;
+/** The canonical web URL for a doc external id (default branch via `HEAD`). */
+export declare function githubDocUrl(id: GitHubDocExternalId): string;
+/** A human title for a doc: its file base name (e.g. `architecture.md`). */
+export declare function githubDocTitle(path: string): string;
+/**
+ * Build a GitHub code-search query scoped to one account. GitHub's code-search
+ * API rejects unscoped queries, so we append an `org:`/`user:` qualifier chosen
+ * from the installation's target type. The free text is trimmed and the account
+ * login is taken verbatim (GitHub logins have no special search chars).
+ */
+export declare function buildGitHubCodeSearchQuery(query: string, account: string, targetType: 'Organization' | 'User'): string;
+//# sourceMappingURL=github-docs.logic.d.ts.map

package/dist/modules/documents/github-docs.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-docs.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/github-docs.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAWnE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,wBASpC,CAAA;AAMD,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAA;CACb;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,mBAAmB,GAAG,MAAM,CAEnE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW9D;AAOD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAIvF;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,EAAE,EAAE,mBAAmB,GAAG,MAAM,CAE5D;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,cAAc,GAAG,MAAM,GAClC,MAAM,CAGR"}

package/dist/modules/documents/github-docs.logic.js

@@ -0,0 +1,94 @@
+// GitHub repo-doc document-source pure logic, kept out of the worker so it is
+// unit-testable without a live API: parsing a file reference out of user input
+// and round-tripping the `owner/repo:path` external id the provider stores. Like
+// the GitHub-issues task source, the provider reuses the workspace's installed
+// GitHub App, so this source needs no credentials of its own. A repo doc is a
+// single Markdown/text file (a README, an RFC under `docs/`, an architecture
+// note) linked to a task as context; the file body is already Markdown-ish, so
+// there is no body-conversion step here.
+/**
+ * What the connect UI renders. GitHub docs piggyback on the workspace's existing
+ * GitHub App installation, so there are NO credential fields — the connect form
+ * is just a confirmation, and `normalizeConnection` accepts an empty bag.
+ */
+export const GITHUB_DOCS_DESCRIPTOR = {
+    source: 'github',
+    label: 'GitHub Docs',
+    icon: 'i-lucide-file-code-2',
+    credentialFields: [],
+    refLabel: 'File URL or owner/repo:path',
+    refPlaceholder: 'octo/repo:docs/architecture.md  or  https://github.com/octo/repo/blob/main/README.md',
+    searchable: true,
+};
+// An owner/repo segment: letters, digits, '.', '_' and '-'. Mirrors the GitHub
+// issues source's segment grammar.
+const SEG = '[A-Za-z0-9._-]+';
+/** Build the canonical `owner/repo:path` external id from its parts. */
+export function githubDocExternalId(id) {
+    return `${id.owner}/${id.repo}:${id.path}`;
+}
+/**
+ * Resolve a GitHub repo-doc reference from raw user input into the canonical
+ * `owner/repo:path` external id. Accepts:
+ *   - a blob URL: `https://github.com/octo/repo/blob/main/docs/x.md`
+ *   - a raw URL: `https://raw.githubusercontent.com/octo/repo/main/docs/x.md`
+ *   - the shorthand `octo/repo:docs/x.md`
+ * The branch/ref in a URL is dropped — the provider reads the default branch — so
+ * the external id (and thus a re-import's identity) is branch-stable. Returns
+ * null when nothing parses. Owner/repo/path are kept verbatim (case-preserving).
+ *
+ * KNOWN LIMITATION: a URL whose branch name itself contains a slash
+ * (`…/blob/feature/x/README.md`) is ambiguous — the branch/path boundary cannot
+ * be recovered from the URL alone, so the first segment after `blob/` (or the
+ * ref slot of a raw URL) is assumed to be the whole ref and the rest the path.
+ * For files on a slash-named branch, use the unambiguous `owner/repo:path`
+ * shorthand instead. (The default branch is what the provider actually reads.)
+ */
+export function parseGitHubDocRef(input) {
+    const trimmed = input.trim();
+    const blob = trimmed.match(new RegExp(`github\\.com/(${SEG})/(${SEG})/blob/[^/]+/(.+)$`));
+    if (blob)
+        return `${blob[1]}/${blob[2]}:${stripQuery(blob[3])}`;
+    const raw = trimmed.match(new RegExp(`raw\\.githubusercontent\\.com/(${SEG})/(${SEG})/[^/]+/(.+)$`));
+    if (raw)
+        return `${raw[1]}/${raw[2]}:${stripQuery(raw[3])}`;
+    const short = trimmed.match(new RegExp(`^(${SEG})/(${SEG}):(.+)$`));
+    if (short)
+        return `${short[1]}/${short[2]}:${short[3].replace(/^\/+/, '')}`;
+    return null;
+}
+/** Drop any `?query`/`#hash` and leading slashes from a URL path tail. */
+function stripQuery(path) {
+    return path.split(/[?#]/)[0].replace(/^\/+/, '');
+}
+/**
+ * Split a stored `owner/repo:path` external id back into its parts. Returns null
+ * if the id is malformed (defensive — ids are produced by
+ * {@link parseGitHubDocRef}, but a stale/hand-edited row should not throw).
+ */
+export function parseGitHubDocExternalId(externalId) {
+    const m = externalId.match(new RegExp(`^(${SEG})/(${SEG}):(.+)$`));
+    if (!m)
+        return null;
+    return { owner: m[1], repo: m[2], path: m[3] };
+}
+/** The canonical web URL for a doc external id (default branch via `HEAD`). */
+export function githubDocUrl(id) {
+    return `https://github.com/${id.owner}/${id.repo}/blob/HEAD/${id.path}`;
+}
+/** A human title for a doc: its file base name (e.g. `architecture.md`). */
+export function githubDocTitle(path) {
+    const base = path.split('/').filter(Boolean).pop();
+    return base && base.length > 0 ? base : path;
+}
+/**
+ * Build a GitHub code-search query scoped to one account. GitHub's code-search
+ * API rejects unscoped queries, so we append an `org:`/`user:` qualifier chosen
+ * from the installation's target type. The free text is trimmed and the account
+ * login is taken verbatim (GitHub logins have no special search chars).
+ */
+export function buildGitHubCodeSearchQuery(query, account, targetType) {
+    const qualifier = targetType === 'Organization' ? 'org' : 'user';
+    return `${query.trim()} ${qualifier}:${account}`;
+}
+//# sourceMappingURL=github-docs.logic.js.map

package/dist/modules/documents/github-docs.logic.js.map

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

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

@@ -0,0 +1,31 @@
+import type { DocumentSearchResult, DocumentSourceDescriptor } from '@cat-factory/kernel';
+/** What the connect UI renders, and which credentials the provider needs. */
+export declare const NOTION_DESCRIPTOR: DocumentSourceDescriptor;
+/**
+ * Map a Notion `/v1/search` response into lean hits, keeping only pages (the API
+ * also returns databases). The page title is read from its `properties` exactly
+ * as the single-page fetch does, so list + import titles agree.
+ */
+export declare function parseNotionSearchResults(json: unknown): DocumentSearchResult[];
+/** Format 32 hex chars as a canonical dashed Notion/UUID id. */
+export declare function formatNotionId(hex32: string): string;
+/**
+ * Resolve a Notion page id from raw user input: a bare id (dashed UUID or 32 hex
+ * chars), or any Notion URL whose last path segment ends in the id. Returns the
+ * canonical dashed id, or null if none is found.
+ */
+export declare function parseNotionRef(input: string): string | null;
+/** The subset of a Notion block we read; the type key holds the rich text. */
+export interface NotionBlock {
+    type?: string;
+    [key: string]: unknown;
+}
+/**
+ * Convert a Notion page's top-level blocks into the lightweight Markdown the
+ * generic planner/excerpt logic consumes: headings become `#`/`##`/`###`, list
+ * items / to-dos become `- `, and other text blocks become plain lines.
+ */
+export declare function notionBlocksToMarkdown(blocks: NotionBlock[]): string;
+/** Extract a page title from a Notion page object's `properties`. */
+export declare function notionPageTitle(properties: Record<string, unknown> | undefined): string;
+//# sourceMappingURL=notion.logic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notion.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/documents/notion.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAQzF,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,wBAgB/B,CAAA;AAWD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,oBAAoB,EAAE,CAgB9E;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW3D;AAQD,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAcD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,CAkCpE;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAavF"}