@gixcopilot/knowledge 0.1.0

package/dist/loaders/web.js

@@ -0,0 +1,102 @@
+import { CopilotError } from '@gixcopilot/protocol';
+import { createKnowledgeDocument } from '../document.js';
+import { throwIfAborted } from '../loader.js';
+import { normalizeText } from '../normalize.js';
+import { assertSafeWebUrl, SsrfGuardError } from '../net/ssrf-guard.js';
+import { extractHtmlStructure } from './html-structure.js';
+const DEFAULT_MAX_BYTES = 5_000_000;
+/**
+ * Remote web loader (Section 20). Deliberately narrow: no arbitrary model-controlled fetch
+ * capability (Section 20's explicit prohibition) - the URL comes from a developer-configured
+ * `webSource`, never from model output, and is checked with `assertSafeWebUrl` before fetching.
+ */
+export const webLoader = {
+    async *load(source, context) {
+        throwIfAborted(context?.signal);
+        const maxBytes = source.config.maxBytes ?? DEFAULT_MAX_BYTES;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+            throw CopilotError.validation('maxBytes must be a positive integer.');
+        let url;
+        try {
+            url = new URL(source.config.url);
+        }
+        catch {
+            throw CopilotError.sourceLoadFailed(`Invalid URL: "${source.config.url}"`, {
+                sourceId: source.id,
+            });
+        }
+        try {
+            await assertSafeWebUrl(url);
+        }
+        catch (error) {
+            if (error instanceof SsrfGuardError) {
+                throw CopilotError.sourceLoadFailed(error.message, { sourceId: source.id, url: url.href });
+            }
+            throw error;
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                headers: source.config.headers,
+                redirect: 'error',
+                signal: context?.signal,
+            });
+        }
+        catch (error) {
+            throw CopilotError.sourceLoadFailed(`Failed to fetch "${url.href}": ${String(error)}`, {
+                sourceId: source.id,
+            });
+        }
+        if (!response.ok) {
+            throw CopilotError.sourceLoadFailed(`Fetching "${url.href}" returned HTTP ${response.status}.`, { sourceId: source.id, status: response.status });
+        }
+        const contentLength = response.headers.get('content-length');
+        if (contentLength && Number(contentLength) > maxBytes) {
+            throw CopilotError.sourceLoadFailed(`Response for "${url.href}" exceeds the ${maxBytes}-byte limit.`, { sourceId: source.id });
+        }
+        const parts = [];
+        let bytes = 0;
+        const reader = response.body?.getReader();
+        try {
+            if (reader) {
+                while (true) {
+                    throwIfAborted(context?.signal);
+                    const { done, value } = (await reader.read());
+                    if (done)
+                        break;
+                    bytes += value.byteLength;
+                    if (bytes > maxBytes)
+                        throw CopilotError.sourceLoadFailed(`Response exceeds the ${maxBytes}-byte limit.`, { sourceId: source.id });
+                    parts.push(value);
+                }
+            }
+        }
+        finally {
+            await reader?.cancel();
+            reader?.releaseLock();
+        }
+        const body = Buffer.concat(parts).toString('utf8');
+        throwIfAborted(context?.signal);
+        const contentType = response.headers.get('content-type') ?? '';
+        const structure = contentType.includes('html')
+            ? extractHtmlStructure(body)
+            : { text: body };
+        const content = normalizeText(structure.text);
+        if (content.length === 0)
+            return;
+        yield createKnowledgeDocument({
+            sourceId: source.id,
+            content,
+            metadata: {
+                uri: url.href,
+                ...(source.name !== undefined || structure.title !== undefined
+                    ? { title: source.name ?? structure.title }
+                    : {}),
+                mimeType: contentType || undefined,
+                tenantId: source.tenantId,
+                acl: source.acl,
+            },
+        });
+    },
+};
+//# sourceMappingURL=web.js.map

package/dist/loaders/web.js.map

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

package/dist/net/ssrf-guard.d.ts

@@ -0,0 +1,13 @@
+export declare class SsrfGuardError extends Error {
+    readonly name = "SsrfGuardError";
+}
+/**
+ * Best-effort SSRF guard for the web loader (Section 20/6). Resolves the hostname and rejects
+ * loopback/RFC1918/link-local/metadata-service/CGNAT addresses before a fetch is attempted, and
+ * restricts to http/https. This is a real, meaningful check, not a complete one: it does not
+ * defend against DNS-rebinding between this check and the actual `fetch()` call (a TOCTOU gap
+ * that would require pinning the resolved IP into the connection itself, which the platform
+ * `fetch()` API does not expose) - documented explicitly rather than claimed as airtight.
+ */
+export declare function assertSafeWebUrl(url: URL): Promise<void>;
+//# sourceMappingURL=ssrf-guard.d.ts.map

package/dist/net/ssrf-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.d.ts","sourceRoot":"","sources":["../../src/net/ssrf-guard.ts"],"names":[],"mappings":"AAGA,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAkB,IAAI,oBAAoB;CAC3C;AAqDD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB9D"}

package/dist/net/ssrf-guard.js

@@ -0,0 +1,88 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+export class SsrfGuardError extends Error {
+    name = 'SsrfGuardError';
+}
+function ipv4ToInt(ip) {
+    return ip
+        .split('.')
+        .reduce((acc, octet) => (acc << 8) + Number(octet), 0);
+}
+function inV4Range(ip, base, prefixLength) {
+    const mask = prefixLength === 0 ? 0 : (~0 << (32 - prefixLength)) >>> 0;
+    return (ipv4ToInt(ip) & mask) === (ipv4ToInt(base) & mask);
+}
+/** RFC 1918 + loopback + link-local (includes the 169.254.169.254 cloud metadata address) + CGNAT + "this network". */
+const BLOCKED_V4_RANGES = [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.168.0.0', 16],
+    ['198.18.0.0', 15],
+    ['224.0.0.0', 4],
+    ['240.0.0.0', 4],
+];
+function isPrivateIpv4(ip) {
+    return BLOCKED_V4_RANGES.some(([base, prefixLength]) => inV4Range(ip, base, prefixLength));
+}
+function isPrivateIpv6(ip) {
+    const normalized = ip.toLowerCase();
+    if (normalized === '::1' || normalized === '::')
+        return true;
+    if (normalized.startsWith('fe8') || normalized.startsWith('fe9') || normalized.startsWith('fea') || normalized.startsWith('feb')) {
+        return true; // fe80::/10 link-local
+    }
+    if (normalized.startsWith('fc') || normalized.startsWith('fd'))
+        return true; // fc00::/7 unique local
+    if (normalized.startsWith('ff'))
+        return true; // multicast
+    if (normalized.startsWith('::ffff:'))
+        return true; // includes canonical hex IPv4-mapped literals
+    const v4Mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(normalized);
+    if (v4Mapped?.[1])
+        return isPrivateIpv4(v4Mapped[1]);
+    return false;
+}
+function isPrivateIp(ip) {
+    const version = isIP(ip);
+    if (version === 4)
+        return isPrivateIpv4(ip);
+    if (version === 6)
+        return isPrivateIpv6(ip);
+    return true; // not a recognizable literal IP - fail closed
+}
+/**
+ * Best-effort SSRF guard for the web loader (Section 20/6). Resolves the hostname and rejects
+ * loopback/RFC1918/link-local/metadata-service/CGNAT addresses before a fetch is attempted, and
+ * restricts to http/https. This is a real, meaningful check, not a complete one: it does not
+ * defend against DNS-rebinding between this check and the actual `fetch()` call (a TOCTOU gap
+ * that would require pinning the resolved IP into the connection itself, which the platform
+ * `fetch()` API does not expose) - documented explicitly rather than claimed as airtight.
+ */
+export async function assertSafeWebUrl(url) {
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new SsrfGuardError(`Unsupported protocol "${url.protocol}" - only http/https are allowed.`);
+    }
+    if (url.username || url.password)
+        throw new SsrfGuardError('Embedded URL credentials are not allowed.');
+    const hostname = url.hostname.replace(/^\[|\]$/g, '');
+    if (isIP(hostname) && isPrivateIp(hostname)) {
+        throw new SsrfGuardError(`"${hostname}" resolves to a disallowed address range.`);
+    }
+    if (!isIP(hostname)) {
+        const records = await lookup(hostname, { all: true }).catch((error) => {
+            throw new SsrfGuardError(`Could not resolve host "${hostname}": ${String(error)}`);
+        });
+        const blocked = records.find((record) => isPrivateIp(record.address));
+        if (!records.length)
+            throw new SsrfGuardError('Host did not resolve to any address.');
+        if (blocked) {
+            throw new SsrfGuardError(`"${hostname}" resolves to a disallowed address (${blocked.address}).`);
+        }
+    }
+}
+//# sourceMappingURL=ssrf-guard.js.map

package/dist/net/ssrf-guard.js.map

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

package/dist/normalize.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared text normalization (Section 26) applied by every loader before a KnowledgeDocument is
+ * produced: consistent line endings and collapsed excessive blank space, without destroying
+ * meaningful structure (paragraph breaks are preserved, not collapsed to nothing).
+ */
+export declare function normalizeText(raw: string): string;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjD"}

package/dist/normalize.js

@@ -0,0 +1,14 @@
+/**
+ * Shared text normalization (Section 26) applied by every loader before a KnowledgeDocument is
+ * produced: consistent line endings and collapsed excessive blank space, without destroying
+ * meaningful structure (paragraph breaks are preserved, not collapsed to nothing).
+ */
+export function normalizeText(raw) {
+    return raw
+        .replace(/\r\n?/g, '\n')
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, '')
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+//# sourceMappingURL=normalize.js.map

package/dist/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,GAAG;SACP,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC;SACvB,OAAO,CAAC,2CAA2C,EAAE,EAAE,CAAC;SACxD,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC;SAC1B,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC;SAC1B,IAAI,EAAE,CAAC;AACZ,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,10 @@
+import type { KnowledgeSource } from './source.js';
+/** Tracks configured knowledge sources (Section 11). Not a mandatory global singleton - callers create one per application/tenant as needed. */
+export interface KnowledgeSourceRegistry {
+    register(source: KnowledgeSource): void;
+    get(id: string): KnowledgeSource | undefined;
+    list(): readonly KnowledgeSource[];
+    remove(id: string): void;
+}
+export declare function createKnowledgeSourceRegistry(initial?: readonly KnowledgeSource[]): KnowledgeSourceRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,gJAAgJ;AAChJ,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IACxC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IAC7C,IAAI,IAAI,SAAS,eAAe,EAAE,CAAC;IACnC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,SAAS,eAAe,EAAO,GACvC,uBAAuB,CAyBzB"}

package/dist/registry.js

@@ -0,0 +1,27 @@
+import { CopilotError } from '@gixcopilot/protocol';
+export function createKnowledgeSourceRegistry(initial = []) {
+    const sources = new Map();
+    for (const source of initial) {
+        sources.set(source.id, source);
+    }
+    return {
+        register(source) {
+            if (sources.has(source.id)) {
+                throw CopilotError.validation(`A knowledge source with id "${source.id}" is already registered.`, {
+                    sourceId: source.id,
+                });
+            }
+            sources.set(source.id, source);
+        },
+        get(id) {
+            return sources.get(id);
+        },
+        list() {
+            return [...sources.values()];
+        },
+        remove(id) {
+            sources.delete(id);
+        },
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAWpD,MAAM,UAAU,6BAA6B,CAC3C,UAAsC,EAAE;IAExC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IACnD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC;IAED,OAAO;QACL,QAAQ,CAAC,MAAM;YACb,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC3B,MAAM,YAAY,CAAC,UAAU,CAAC,+BAA+B,MAAM,CAAC,EAAE,0BAA0B,EAAE;oBAChG,QAAQ,EAAE,MAAM,CAAC,EAAE;iBACpB,CAAC,CAAC;YACL,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,GAAG,CAAC,EAAE;YACJ,OAAO,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC;QACD,IAAI;YACF,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAC/B,CAAC;QACD,MAAM,CAAC,EAAE;YACP,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/source.d.ts

@@ -0,0 +1,136 @@
+import type { KnowledgeACL } from './acl.js';
+import type { DocumentMetadata } from './document.js';
+/** The knowledge source types the architecture supports (Section 10). */
+export type KnowledgeSourceType = 'file' | 'text' | 'markdown' | 'pdf' | 'docx' | 'html' | 'web' | 'api' | 'database' | 'object-storage' | 'mcp-resource' | 'custom';
+/** Framework-independent knowledge source contract (Section 9). Never coupled to a specific storage system. */
+export interface KnowledgeSource<TConfig = unknown> {
+    readonly id: string;
+    readonly type: KnowledgeSourceType;
+    readonly name?: string;
+    readonly tenantId?: string;
+    readonly acl?: KnowledgeACL;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly config: TConfig;
+}
+export interface KnowledgeSourceCommonInput {
+    readonly id?: string;
+    readonly name?: string;
+    readonly tenantId?: string;
+    /** Shorthand for `acl.permissions` - merged with an explicit `acl` if both are given. */
+    readonly permissions?: readonly string[];
+    readonly acl?: KnowledgeACL;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface TextSourceConfig {
+    readonly content: string;
+}
+export type TextSourceInput = KnowledgeSourceCommonInput & TextSourceConfig;
+export declare function textSource(input: TextSourceInput): KnowledgeSource<TextSourceConfig>;
+export type MarkdownSourceInput = KnowledgeSourceCommonInput & TextSourceConfig;
+export declare function markdownSource(input: MarkdownSourceInput): KnowledgeSource<TextSourceConfig>;
+/** Exactly one of `path`/`buffer` must be provided - validated by the corresponding loader. */
+export interface BinarySourceConfig {
+    readonly path?: string;
+    readonly buffer?: Buffer;
+}
+export type PdfSourceInput = KnowledgeSourceCommonInput & BinarySourceConfig;
+export declare function pdfSource(input: PdfSourceInput): KnowledgeSource<BinarySourceConfig>;
+export type DocxSourceInput = KnowledgeSourceCommonInput & BinarySourceConfig;
+export declare function docxSource(input: DocxSourceInput): KnowledgeSource<BinarySourceConfig>;
+/** Exactly one of `html`/`path` must be provided - validated by the loader. */
+export interface HtmlSourceConfig {
+    readonly html?: string;
+    readonly path?: string;
+}
+export type HtmlSourceInput = KnowledgeSourceCommonInput & HtmlSourceConfig;
+export declare function htmlSource(input: HtmlSourceInput): KnowledgeSource<HtmlSourceConfig>;
+export interface WebSourceConfig {
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly maxBytes?: number;
+}
+export type WebSourceInput = KnowledgeSourceCommonInput & WebSourceConfig;
+export declare function webSource(input: WebSourceInput): KnowledgeSource<WebSourceConfig>;
+/** One document produced from a non-file source (API/database rows) - Section 21/22. */
+export interface DerivedDocumentInput {
+    readonly content: string;
+    readonly discriminator?: string | number;
+    readonly metadata?: Partial<Omit<DocumentMetadata, 'contentHash'>>;
+}
+/**
+ * API knowledge source (Section 21) - deliberately distinct from a Phase 8 API *tool*: this
+ * never executes an action, it only turns a response into documents. `request` is the caller's
+ * own fetch/HTTP call (so this package never owns HTTP credentials/base-URL policy);
+ * `toDocuments` maps the raw response into zero or more documents.
+ */
+export interface ApiSourceConfig {
+    readonly request: () => Promise<unknown>;
+    readonly toDocuments: (response: unknown) => readonly DerivedDocumentInput[];
+}
+export type ApiSourceInput = KnowledgeSourceCommonInput & ApiSourceConfig;
+export declare function apiSource(input: ApiSourceInput): KnowledgeSource<ApiSourceConfig>;
+/**
+ * Database knowledge source (Section 22). `query` is a caller-supplied, already-parameterized
+ * async function returning rows - this package never builds or executes SQL/query strings
+ * itself, so "unrestricted natural-language-to-SQL access" is impossible by construction.
+ */
+export interface DatabaseSourceConfig<TRow = unknown> {
+    readonly query: () => Promise<readonly TRow[]>;
+    readonly toDocument: (row: TRow, index: number) => DerivedDocumentInput;
+}
+export type DatabaseSourceInput<TRow = unknown> = KnowledgeSourceCommonInput & DatabaseSourceConfig<TRow>;
+export declare function createDatabaseKnowledgeSource<TRow = unknown>(input: DatabaseSourceInput<TRow>): KnowledgeSource<DatabaseSourceConfig<TRow>>;
+/** Minimal object-storage boundary (Section 23) - no concrete cloud SDK dependency. */
+export interface ObjectStorageObject {
+    readonly key: string;
+    readonly content: string;
+    readonly metadata?: Partial<Omit<DocumentMetadata, 'contentHash'>>;
+}
+export interface ObjectStorageClient {
+    list(prefix?: string): Promise<readonly string[]>;
+    get(key: string): Promise<ObjectStorageObject>;
+}
+export interface ObjectStorageSourceConfig {
+    readonly client: ObjectStorageClient;
+    /** Explicit key list, or omit to list everything under `prefix` at load time. */
+    readonly keys?: readonly string[];
+    readonly prefix?: string;
+}
+export type ObjectStorageSourceInput = KnowledgeSourceCommonInput & ObjectStorageSourceConfig;
+export declare function objectStorageSource(input: ObjectStorageSourceInput): KnowledgeSource<ObjectStorageSourceConfig>;
+/** A structural subset of @gixcopilot/mcp's client/integration resource API (Section 24). */
+export interface McpResourceReader {
+    listResources(): Promise<readonly {
+        readonly uri: string;
+        readonly name: string;
+        readonly description?: string;
+        readonly mimeType?: string;
+    }[]>;
+    readResource(uri: string): Promise<{
+        readonly uri: string;
+        readonly mimeType?: string;
+        readonly text?: string;
+    }>;
+}
+export interface McpResourceSourceConfig {
+    readonly client: McpResourceReader;
+    /** Explicit resource URIs, or omit to ingest every resource the server advertises. */
+    readonly uris?: readonly string[];
+}
+export type McpResourceSourceInput = KnowledgeSourceCommonInput & McpResourceSourceConfig;
+export declare function mcpResourceSource(input: McpResourceSourceInput): KnowledgeSource<McpResourceSourceConfig>;
+/** Generic local/remote file source that dispatches by extension (Section 10's 'file' type). */
+export interface FileSourceConfig {
+    readonly path: string;
+}
+export type FileSourceInput = KnowledgeSourceCommonInput & FileSourceConfig;
+export declare function fileSource(input: FileSourceInput): KnowledgeSource<FileSourceConfig>;
+/**
+ * Escape hatch for a source type this package doesn't model - the caller supplies their own
+ * `DocumentLoader` for it directly (Section 10). No default loader is registered for `custom`.
+ */
+export type CustomSourceInput = KnowledgeSourceCommonInput & {
+    readonly config?: unknown;
+};
+export declare function customSource(input: CustomSourceInput): KnowledgeSource<unknown>;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

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

package/dist/source.js

@@ -0,0 +1,55 @@
+import { randomUUID } from 'node:crypto';
+function resolveAcl(input) {
+    if (!input.permissions || input.permissions.length === 0)
+        return input.acl;
+    const merged = new Set([...(input.acl?.permissions ?? []), ...input.permissions]);
+    return { ...input.acl, permissions: [...merged] };
+}
+function buildSource(type, config, input) {
+    return {
+        id: input.id ?? randomUUID(),
+        type,
+        ...(input.name !== undefined ? { name: input.name } : {}),
+        ...(input.tenantId !== undefined ? { tenantId: input.tenantId } : {}),
+        ...(resolveAcl(input) !== undefined ? { acl: resolveAcl(input) } : {}),
+        ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+        config,
+    };
+}
+export function textSource(input) {
+    return buildSource('text', { content: input.content }, input);
+}
+export function markdownSource(input) {
+    return buildSource('markdown', { content: input.content }, input);
+}
+export function pdfSource(input) {
+    return buildSource('pdf', { path: input.path, buffer: input.buffer }, input);
+}
+export function docxSource(input) {
+    return buildSource('docx', { path: input.path, buffer: input.buffer }, input);
+}
+export function htmlSource(input) {
+    return buildSource('html', { html: input.html, path: input.path }, input);
+}
+export function webSource(input) {
+    return buildSource('web', { url: input.url, headers: input.headers, maxBytes: input.maxBytes }, input);
+}
+export function apiSource(input) {
+    return buildSource('api', { request: input.request, toDocuments: input.toDocuments }, input);
+}
+export function createDatabaseKnowledgeSource(input) {
+    return buildSource('database', { query: input.query, toDocument: input.toDocument }, input);
+}
+export function objectStorageSource(input) {
+    return buildSource('object-storage', { client: input.client, keys: input.keys, prefix: input.prefix }, input);
+}
+export function mcpResourceSource(input) {
+    return buildSource('mcp-resource', { client: input.client, uris: input.uris }, input);
+}
+export function fileSource(input) {
+    return buildSource('file', { path: input.path }, input);
+}
+export function customSource(input) {
+    return buildSource('custom', input.config, input);
+}
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@gixcopilot/knowledge",
+  "version": "0.1.0",
+  "description": "Framework-independent knowledge source, document, and loader contracts for the AI Copilot SDK - the ingestion boundary RAG builds on.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AfoudaSWE/gix_ai_copilot_nx.git",
+    "directory": "packages/knowledge"
+  },
+  "homepage": "https://github.com/AfoudaSWE/gix_ai_copilot_nx/tree/main/packages/knowledge#readme",
+  "bugs": {
+    "url": "https://github.com/AfoudaSWE/gix_ai_copilot_nx/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.spec.*",
+    "!dist/**/*.spec-helper.*",
+    "!dist/**/*.integration.spec.*",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "mammoth": "^1.11.0",
+    "node-html-parser": "^7.0.1",
+    "pdfjs-dist": "^4.10.38",
+    "@gixcopilot/protocol": "0.1.0",
+    "@gixcopilot/mcp": "0.1.0"
+  },
+  "devDependencies": {
+    "jszip": "^3.10.1",
+    "pdf-lib": "^1.17.1",
+    "vitest": "5.0.1"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}