@kaelio/ktx 0.13.1 → 0.15.0

package/dist/context/cache/sqlite-content-result-cache.js

@@ -0,0 +1,223 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import Database from 'better-sqlite3';
+const RESULTS_TABLE = 'local_content_results';
+const RESULTS_PRIMARY_KEY = ['namespace', 'scope_key', 'input_hash'];
+function isSafeRunId(runId) {
+    return /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(runId);
+}
+function parseResultRow(row) {
+    const base = {
+        runId: row.run_id,
+        namespace: row.namespace,
+        scopeKey: row.scope_key,
+        inputHash: row.input_hash,
+        metadata: JSON.parse(row.metadata_json || '{}'),
+        updatedAt: row.updated_at,
+    };
+    if (row.status === 'completed') {
+        return {
+            ...base,
+            status: 'completed',
+            output: JSON.parse(row.output_json ?? 'null'),
+            errorMessage: null,
+        };
+    }
+    return {
+        ...base,
+        status: 'failed',
+        output: null,
+        errorMessage: row.error_message ?? 'Unknown content result failure',
+    };
+}
+export class SqliteContentResultCache {
+    db;
+    constructor(options) {
+        mkdirSync(dirname(options.dbPath), { recursive: true });
+        this.db = new Database(options.dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.db.exec('DROP TABLE IF EXISTS local_scan_enrichment_stages');
+        this.dropResultsTableIfPrimaryKeyDiffers();
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS local_content_results (
+        run_id TEXT NOT NULL,
+        namespace TEXT NOT NULL,
+        scope_key TEXT NOT NULL,
+        input_hash TEXT NOT NULL,
+        status TEXT NOT NULL,
+        output_json TEXT,
+        error_message TEXT,
+        metadata_json TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (namespace, scope_key, input_hash)
+      );
+
+      CREATE INDEX IF NOT EXISTS local_content_results_lookup_idx
+        ON local_content_results (namespace, scope_key, input_hash, updated_at);
+      CREATE INDEX IF NOT EXISTS local_content_results_run_idx
+        ON local_content_results (run_id, updated_at, namespace);
+    `);
+    }
+    dropResultsTableIfPrimaryKeyDiffers() {
+        const columns = this.db.prepare(`PRAGMA table_info(${RESULTS_TABLE})`).all();
+        if (columns.length === 0) {
+            return;
+        }
+        const primaryKey = columns
+            .filter((column) => column.pk > 0)
+            .sort((left, right) => left.pk - right.pk)
+            .map((column) => column.name);
+        const matches = primaryKey.length === RESULTS_PRIMARY_KEY.length &&
+            primaryKey.every((name, index) => name === RESULTS_PRIMARY_KEY[index]);
+        if (!matches) {
+            this.db.exec(`DROP TABLE ${RESULTS_TABLE}`);
+        }
+    }
+    async findCompletedResult(input) {
+        const row = this.db
+            .prepare(`
+        SELECT *
+        FROM local_content_results
+        WHERE namespace = ?
+          AND scope_key = ?
+          AND input_hash = ?
+          AND status = 'completed'
+        ORDER BY updated_at DESC
+        LIMIT 1
+      `)
+            .get(input.namespace, input.scopeKey, input.inputHash);
+        if (!row) {
+            return null;
+        }
+        const parsed = parseResultRow(row);
+        return parsed.status === 'completed' ? parsed : null;
+    }
+    async findLatestCompletedResult(input) {
+        const row = this.db
+            .prepare(`
+        SELECT *
+        FROM local_content_results
+        WHERE namespace = ?
+          AND scope_key = ?
+          AND status = 'completed'
+        ORDER BY updated_at DESC
+        LIMIT 1
+      `)
+            .get(input.namespace, input.scopeKey);
+        if (!row) {
+            return null;
+        }
+        const parsed = parseResultRow(row);
+        return parsed.status === 'completed' ? parsed : null;
+    }
+    async saveCompletedResult(input) {
+        this.db
+            .prepare(`
+        INSERT INTO local_content_results (
+          run_id,
+          namespace,
+          scope_key,
+          input_hash,
+          status,
+          output_json,
+          error_message,
+          metadata_json,
+          updated_at
+        )
+        VALUES (
+          @runId,
+          @namespace,
+          @scopeKey,
+          @inputHash,
+          'completed',
+          @outputJson,
+          NULL,
+          @metadataJson,
+          @updatedAt
+        )
+        ON CONFLICT(namespace, scope_key, input_hash) DO UPDATE SET
+          run_id = excluded.run_id,
+          status = excluded.status,
+          output_json = excluded.output_json,
+          error_message = excluded.error_message,
+          metadata_json = excluded.metadata_json,
+          updated_at = excluded.updated_at
+      `)
+            .run({
+            runId: input.runId,
+            namespace: input.namespace,
+            scopeKey: input.scopeKey,
+            inputHash: input.inputHash,
+            outputJson: JSON.stringify(input.output),
+            metadataJson: JSON.stringify(input.metadata),
+            updatedAt: input.updatedAt,
+        });
+    }
+    async saveFailedResult(input) {
+        this.db
+            .prepare(`
+        INSERT INTO local_content_results (
+          run_id,
+          namespace,
+          scope_key,
+          input_hash,
+          status,
+          output_json,
+          error_message,
+          metadata_json,
+          updated_at
+        )
+        VALUES (
+          @runId,
+          @namespace,
+          @scopeKey,
+          @inputHash,
+          'failed',
+          NULL,
+          @errorMessage,
+          @metadataJson,
+          @updatedAt
+        )
+        ON CONFLICT(namespace, scope_key, input_hash) DO UPDATE SET
+          run_id = excluded.run_id,
+          status = excluded.status,
+          output_json = excluded.output_json,
+          error_message = excluded.error_message,
+          metadata_json = excluded.metadata_json,
+          updated_at = excluded.updated_at
+      `)
+            .run({
+            runId: input.runId,
+            namespace: input.namespace,
+            scopeKey: input.scopeKey,
+            inputHash: input.inputHash,
+            errorMessage: input.errorMessage,
+            metadataJson: JSON.stringify(input.metadata),
+            updatedAt: input.updatedAt,
+        });
+    }
+    async deleteResult(input) {
+        this.db
+            .prepare(`
+        DELETE FROM local_content_results
+        WHERE namespace = ?
+          AND scope_key = ?
+          AND input_hash = ?
+      `)
+            .run(input.namespace, input.scopeKey, input.inputHash);
+    }
+    async listRunResults(runId) {
+        if (!isSafeRunId(runId)) {
+            return [];
+        }
+        const rows = this.db
+            .prepare(`
+        SELECT *
+        FROM local_content_results
+        WHERE run_id = ?
+        ORDER BY updated_at ASC, namespace ASC
+      `)
+            .all(runId);
+        return rows.map((row) => parseResultRow(row));
+    }
+}

package/dist/context/connections/bigquery-identifiers.d.ts

@@ -1,2 +1,3 @@
 export declare function normalizeBigQueryProjectId(value: string, context?: string): string;
+export declare function normalizeBigQueryDatasetId(value: string, context?: string): string;
 export declare function normalizeBigQueryRegion(value: string, context?: string): string;

package/dist/context/connections/bigquery-identifiers.js

@@ -1,4 +1,5 @@
 const BIGQUERY_PROJECT_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+const BIGQUERY_DATASET_ID_PATTERN = /^[A-Za-z0-9_]+$/;
 const BIGQUERY_REGION_PATTERN = /^[a-z0-9-]+$/;
 export function normalizeBigQueryProjectId(value, context = 'historic-SQL ingest') {
     if (!BIGQUERY_PROJECT_ID_PATTERN.test(value)) {
@@ -6,6 +7,12 @@ export function normalizeBigQueryProjectId(value, context = 'historic-SQL ingest
     }
     return value;
 }
+export function normalizeBigQueryDatasetId(value, context = 'historic-SQL ingest') {
+    if (!BIGQUERY_DATASET_ID_PATTERN.test(value)) {
+        throw new Error(`Invalid BigQuery dataset id for ${context}: ${value}`);
+    }
+    return value;
+}
 export function normalizeBigQueryRegion(value, context = 'historic-SQL ingest') {
     const normalized = value.trim().toLowerCase().replace(/^region-/, '');
     if (!BIGQUERY_REGION_PATTERN.test(normalized)) {

package/dist/context/connections/configured-connections.d.ts

@@ -0,0 +1,9 @@
+import type { KtxProjectConnectionConfig } from '../project/config.js';
+/**
+ * Validate a connection id supplied as an explicit command/tool argument against
+ * the canonical `ktx.yaml` connections map. Returns the id when configured;
+ * otherwise throws an error that lists the configured ids so the caller can fix
+ * the typo. Use for explicit arguments only — persisted page frontmatter that
+ * references a since-removed connection must warn, not fail.
+ */
+export declare function assertConfiguredConnectionId(connections: Record<string, KtxProjectConnectionConfig>, connectionId: string): string;

package/dist/context/connections/configured-connections.js

@@ -0,0 +1,18 @@
+function listConfiguredConnectionIds(connections) {
+    return Object.keys(connections).sort();
+}
+/**
+ * Validate a connection id supplied as an explicit command/tool argument against
+ * the canonical `ktx.yaml` connections map. Returns the id when configured;
+ * otherwise throws an error that lists the configured ids so the caller can fix
+ * the typo. Use for explicit arguments only — persisted page frontmatter that
+ * references a since-removed connection must warn, not fail.
+ */
+export function assertConfiguredConnectionId(connections, connectionId) {
+    if (Object.hasOwn(connections, connectionId)) {
+        return connectionId;
+    }
+    const ids = listConfiguredConnectionIds(connections);
+    const configured = ids.length > 0 ? ids.join(', ') : '(none configured)';
+    throw new Error(`Unknown connection "${connectionId}". Configured connections: ${configured}.`);
+}

package/dist/context/connections/dialects.d.ts

@@ -1,12 +1,27 @@
 import type { KtxConnectionDriver, KtxSchemaDimensionType, KtxTableRef } from '../scan/types.js';
 import type { KtxDialectTableRef } from './dialect-helpers.js';
+/**
+ * Driver-agnostic dialect surface every connection implements, including
+ * non-SQL sources like MongoDB: display/ref formatting and type mapping. The
+ * catalog and entity-details paths resolve this for any snapshot driver, so it
+ * must stay free of SQL generation.
+ */
 export interface KtxDialect {
     readonly type: KtxConnectionDriver;
-    quoteIdentifier(identifier: string): string;
-    formatTableName(table: KtxDialectTableRef): string;
     formatDisplayRef(table: KtxDialectTableRef): string;
     parseDisplayRef(display: string): KtxTableRef | null;
     columnDisplayTablePartCount(): 1 | 2 | 3;
+    mapToDimensionType(nativeType: string): KtxSchemaDimensionType;
+    mapDataType(nativeType: string): string;
+}
+/**
+ * SQL query generation, implemented only by SQL warehouse drivers. The relationship
+ * profiling/validation pipeline is the sole caller and is gated on the
+ * `readOnlySql` capability, so these methods are unreachable for a non-SQL source.
+ */
+export interface KtxSqlDialect extends KtxDialect {
+    quoteIdentifier(identifier: string): string;
+    formatTableName(table: KtxDialectTableRef): string;
     getLimitOffsetClause(limit: number, offset?: number): string;
     getTopClause(limit: number): string;
     getRandomSampleFilter(samplePct: number): string;
@@ -22,7 +37,18 @@ export interface KtxDialect {
     getDistinctCountExpression(column: string): string;
     textLengthExpression(columnSql: string): string;
     castToText(columnSql: string): string;
-    mapToDimensionType(nativeType: string): KtxSchemaDimensionType;
-    mapDataType(nativeType: string): string;
 }
 export declare function getDialectForDriver(driver: string): KtxDialect;
+export declare function getSqlDialectForDriver(driver: string): KtxSqlDialect;
+/**
+ * Whether a driver can generate and execute SQL. Single source of truth for the
+ * SQL/non-SQL boundary: a driver is SQL-queryable iff it has a SQL dialect, so
+ * non-SQL sources (e.g. mongodb) are excluded without a hand-maintained list.
+ */
+export declare function isSqlQueryableDriver(driver: string | undefined): boolean;
+/**
+ * Refuse a non-SQL connection (e.g. mongodb) at a read-only-SQL entry point before
+ * any dialect selection or parser/daemon work, so it is never validated as Postgres.
+ * The federated `duckdb` connection has no driver — callers skip this guard for it.
+ */
+export declare function assertSqlQueryableConnection(connectionId: string, driver: string | undefined): void;

package/dist/context/connections/dialects.js

@@ -1,20 +1,13 @@
 import { KtxBigQueryDialect } from '../../connectors/bigquery/dialect.js';
 import { KtxClickHouseDialect } from '../../connectors/clickhouse/dialect.js';
+import { KtxMongoDbDialect } from '../../connectors/mongodb/dialect.js';
 import { KtxMysqlDialect } from '../../connectors/mysql/dialect.js';
 import { KtxPostgresDialect } from '../../connectors/postgres/dialect.js';
 import { KtxSqliteDialect } from '../../connectors/sqlite/dialect.js';
 import { KtxSnowflakeDialect } from '../../connectors/snowflake/dialect.js';
 import { KtxSqlServerDialect } from '../../connectors/sqlserver/dialect.js';
-const supportedDrivers = [
-    'bigquery',
-    'clickhouse',
-    'mysql',
-    'postgres',
-    'sqlite',
-    'snowflake',
-    'sqlserver',
-];
-const dialectFactories = {
+import { KtxExpectedError } from '../../errors.js';
+const sqlDialectFactories = {
     bigquery: () => new KtxBigQueryDialect(),
     clickhouse: () => new KtxClickHouseDialect(),
     mysql: () => new KtxMysqlDialect(),
@@ -23,11 +16,45 @@ const dialectFactories = {
     snowflake: () => new KtxSnowflakeDialect(),
     sqlserver: () => new KtxSqlServerDialect(),
 };
+const dialectFactories = {
+    ...sqlDialectFactories,
+    mongodb: () => new KtxMongoDbDialect(),
+};
+const supportedSqlDrivers = Object.keys(sqlDialectFactories).sort();
 export function getDialectForDriver(driver) {
     const normalized = driver.toLowerCase().trim();
     const factory = dialectFactories[normalized];
     if (factory) {
         return factory();
     }
-    throw new Error(`Unsupported warehouse driver "${driver}". Supported drivers: ${supportedDrivers.join(', ')}`);
+    throw new Error(`Unsupported driver "${driver}". Supported drivers: ${Object.keys(dialectFactories).sort().join(', ')}`);
+}
+export function getSqlDialectForDriver(driver) {
+    const normalized = driver.toLowerCase().trim();
+    const factory = sqlDialectFactories[normalized];
+    if (factory) {
+        return factory();
+    }
+    throw new Error(`Driver "${driver}" has no SQL dialect. SQL drivers: ${supportedSqlDrivers.join(', ')}`);
+}
+/**
+ * Whether a driver can generate and execute SQL. Single source of truth for the
+ * SQL/non-SQL boundary: a driver is SQL-queryable iff it has a SQL dialect, so
+ * non-SQL sources (e.g. mongodb) are excluded without a hand-maintained list.
+ */
+export function isSqlQueryableDriver(driver) {
+    const normalized = (driver ?? '').toLowerCase().trim();
+    return Object.prototype.hasOwnProperty.call(sqlDialectFactories, normalized);
+}
+/**
+ * Refuse a non-SQL connection (e.g. mongodb) at a read-only-SQL entry point before
+ * any dialect selection or parser/daemon work, so it is never validated as Postgres.
+ * The federated `duckdb` connection has no driver — callers skip this guard for it.
+ */
+export function assertSqlQueryableConnection(connectionId, driver) {
+    if (!isSqlQueryableDriver(driver)) {
+        throw new KtxExpectedError(`Connection '${connectionId}' uses the non-SQL driver '${driver ?? 'unknown'}'. ` +
+            'Read-only SQL (ktx sql, the sql_execution tool) requires a SQL warehouse connection; ' +
+            'MongoDB and other context-only sources are searchable and ingestable, not SQL-queryable.');
+    }
 }

package/dist/context/connections/drivers.js

@@ -45,6 +45,27 @@ export const driverRegistrations = {
             };
         },
     },
+    mongodb: {
+        driver: 'mongodb',
+        scopeConfigKey: 'databases',
+        hasHistoricSqlReader: false,
+        load: async () => {
+            const m = await import('../../connectors/mongodb/connector.js');
+            return {
+                isConnectionConfig: (connection) => {
+                    const typedConnection = connection;
+                    return m.isKtxMongoDbConnectionConfig(typedConnection);
+                },
+                createScanConnector: ({ connectionId, connection }) => {
+                    const typedConnection = connection;
+                    if (!m.isKtxMongoDbConnectionConfig(typedConnection)) {
+                        throw invalidConnectionConfig('mongodb');
+                    }
+                    return new m.KtxMongoDbScanConnector({ connectionId, connection: typedConnection });
+                },
+            };
+        },
+    },
     mysql: {
         driver: 'mysql',
         scopeConfigKey: 'schemas',

package/dist/context/connections/gdrive-config.d.ts

@@ -0,0 +1,19 @@
+import type { KtxProjectConnectionConfig } from '../project/config.js';
+import type { GdrivePullConfig } from '../ingest/adapters/gdrive/types.js';
+type RawKtxGdriveConnectionConfig = Extract<KtxProjectConnectionConfig, {
+    driver: 'gdrive';
+}>;
+export type KtxGdriveConnectionConfig = Omit<RawKtxGdriveConnectionConfig, 'service_account_key_ref' | 'folder_id' | 'recursive'> & {
+    driver: 'gdrive';
+    service_account_key_ref: string;
+    folder_id: string;
+    recursive: boolean;
+};
+interface ResolveKeyOptions {
+    readTextFile?: (path: string) => Promise<string>;
+}
+export declare function parseGdriveConnectionConfig(raw: unknown): KtxGdriveConnectionConfig;
+/** @internal */
+export declare function resolveGdriveServiceAccountKey(serviceAccountKeyRef: string, options?: ResolveKeyOptions): Promise<string>;
+export declare function gdriveConnectionToPullConfig(config: KtxGdriveConnectionConfig, options?: ResolveKeyOptions): Promise<GdrivePullConfig>;
+export {};

package/dist/context/connections/gdrive-config.js

@@ -0,0 +1,57 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { gdrivePullConfigSchema } from '../ingest/adapters/gdrive/types.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function expandHome(path) {
+    return path === '~' || path.startsWith('~/') ? resolve(homedir(), path.slice(2)) : path;
+}
+export function parseGdriveConnectionConfig(raw) {
+    if (!isRecord(raw)) {
+        throw new Error('gdrive connection config must be an object');
+    }
+    if (raw.driver !== 'gdrive') {
+        throw new Error('gdrive connection config requires driver: gdrive');
+    }
+    const keyRef = typeof raw.service_account_key_ref === 'string' && raw.service_account_key_ref.trim().length > 0 // pragma: allowlist secret
+        ? raw.service_account_key_ref.trim()
+        : null;
+    if (!keyRef) {
+        throw new Error('gdrive connection config requires service_account_key_ref');
+    }
+    if (!keyRef.startsWith('file:')) {
+        throw new Error('gdrive service_account_key_ref must use file:/path/to/key.json');
+    }
+    const folderId = typeof raw.folder_id === 'string' && raw.folder_id.trim().length > 0 ? raw.folder_id.trim() : null;
+    if (!folderId) {
+        throw new Error('gdrive connection config requires folder_id');
+    }
+    return {
+        driver: 'gdrive',
+        service_account_key_ref: keyRef,
+        folder_id: folderId,
+        recursive: raw.recursive === true,
+    };
+}
+/** @internal */
+export async function resolveGdriveServiceAccountKey(serviceAccountKeyRef, options = {}) {
+    if (!serviceAccountKeyRef.startsWith('file:')) {
+        throw new Error('gdrive service_account_key_ref must use file:/path/to/key.json');
+    }
+    const path = expandHome(serviceAccountKeyRef.slice('file:'.length));
+    const readTextFile = options.readTextFile ?? ((filePath) => readFile(filePath, 'utf-8'));
+    const value = (await readTextFile(path)).trim();
+    if (!value) {
+        throw new Error(`gdrive service account key file is empty: ${path}`);
+    }
+    return value;
+}
+export async function gdriveConnectionToPullConfig(config, options = {}) {
+    return gdrivePullConfigSchema.parse({
+        serviceAccountKey: await resolveGdriveServiceAccountKey(config.service_account_key_ref, options),
+        folderId: config.folder_id,
+        recursive: config.recursive,
+    });
+}

package/dist/context/connections/query-deadline.d.ts

@@ -0,0 +1,31 @@
+import { KtxQueryError } from '../../errors.js';
+/**
+ * Canonical default bound on read-query execution time. Generous headroom over
+ * any indexed aggregate or normal profiling probe; a pathological nested-loop
+ * scan blows past it immediately. Overridable per-connection via
+ * `query_timeout_ms`. Production reads it through {@link resolveQueryDeadlineMs};
+ * exported for the resolver's own unit tests.
+ * @internal
+ */
+export declare const DEFAULT_QUERY_TIMEOUT_MS = 30000;
+interface QueryTimeoutConnectionConfig {
+    query_timeout_ms?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Single source of truth for the read-query deadline: the per-connection
+ * `query_timeout_ms` override (milliseconds) when present, else the default.
+ * Every connector resolves through here so the default and override precedence
+ * live in exactly one place. A malformed override (zero, negative, non-integer,
+ * non-number) is a config error — surfaced here even though `ktx.yaml`
+ * validation also rejects it, so programmatically-built connectors cannot
+ * silently run unbounded.
+ */
+export declare function resolveQueryDeadlineMs(connection: QueryTimeoutConnectionConfig | undefined): number;
+/**
+ * The canonical, driver-independent timeout error an agent sees regardless of
+ * which connector enforced the deadline. Reads in whole seconds. Remote
+ * connectors pass the driver's own timeout error as `cause`.
+ */
+export declare function queryDeadlineExceededError(deadlineMs: number, options?: ErrorOptions): KtxQueryError;
+export {};

package/dist/context/connections/query-deadline.js

@@ -0,0 +1,37 @@
+import { KtxQueryError } from '../../errors.js';
+/**
+ * Canonical default bound on read-query execution time. Generous headroom over
+ * any indexed aggregate or normal profiling probe; a pathological nested-loop
+ * scan blows past it immediately. Overridable per-connection via
+ * `query_timeout_ms`. Production reads it through {@link resolveQueryDeadlineMs};
+ * exported for the resolver's own unit tests.
+ * @internal
+ */
+export const DEFAULT_QUERY_TIMEOUT_MS = 30_000;
+/**
+ * Single source of truth for the read-query deadline: the per-connection
+ * `query_timeout_ms` override (milliseconds) when present, else the default.
+ * Every connector resolves through here so the default and override precedence
+ * live in exactly one place. A malformed override (zero, negative, non-integer,
+ * non-number) is a config error — surfaced here even though `ktx.yaml`
+ * validation also rejects it, so programmatically-built connectors cannot
+ * silently run unbounded.
+ */
+export function resolveQueryDeadlineMs(connection) {
+    const raw = connection?.query_timeout_ms;
+    if (raw === undefined || raw === null) {
+        return DEFAULT_QUERY_TIMEOUT_MS;
+    }
+    if (typeof raw !== 'number' || !Number.isInteger(raw) || raw <= 0) {
+        throw new Error(`query_timeout_ms must be a positive integer in milliseconds, received ${JSON.stringify(raw)}.`);
+    }
+    return raw;
+}
+/**
+ * The canonical, driver-independent timeout error an agent sees regardless of
+ * which connector enforced the deadline. Reads in whole seconds. Remote
+ * connectors pass the driver's own timeout error as `cause`.
+ */
+export function queryDeadlineExceededError(deadlineMs, options) {
+    return new KtxQueryError(`query exceeded ${Math.round(deadlineMs / 1000)}s`, options);
+}

package/dist/context/ingest/adapters/gdrive/chunk.d.ts

@@ -0,0 +1,3 @@
+import type { ChunkResult, DiffSet, ScopeDescriptor } from '../../types.js';
+export declare function chunkGdriveStagedDir(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
+export declare function describeGdriveScope(stagedDir: string): Promise<ScopeDescriptor>;

package/dist/context/ingest/adapters/gdrive/chunk.js

@@ -0,0 +1,74 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { gdriveManifestSchema, gdriveMetadataSchema } from './types.js';
+const GDRIVE_RECONCILE_GUIDANCE = 'Synthesize durable wiki knowledge from this Google Doc. Preserve product definitions, process documentation, and operating rules as wiki pages. Do not create semantic-layer sources from gdrive content in v1.';
+function normalizeRawPath(path) {
+    return path.replace(/\\/g, '/');
+}
+async function walk(root) {
+    const entries = await readdir(root, { withFileTypes: true, recursive: true });
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => normalizeRawPath(relative(root, join(entry.parentPath, entry.name))))
+        .sort();
+}
+function safeUnitKey(path) {
+    return `gdrive-${path.replace(/^docs\//, '').replace(/\/page\.md$/, '').replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '')}`;
+}
+async function readManifest(stagedDir) {
+    try {
+        return gdriveManifestSchema.parse(JSON.parse(await readFile(join(stagedDir, 'manifest.json'), 'utf-8')));
+    }
+    catch (error) {
+        throw new Error(`Invalid gdrive manifest: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function chunkGdriveStagedDir(stagedDir, diffSet) {
+    const files = await walk(stagedDir);
+    const manifest = await readManifest(stagedDir);
+    const touched = diffSet
+        ? new Set([...diffSet.added, ...diffSet.modified].map((path) => normalizeRawPath(path)))
+        : null;
+    const workUnits = [];
+    for (const pagePath of files.filter((path) => path.endsWith('/page.md'))) {
+        const metadataPath = pagePath.replace(/\/page\.md$/, '/metadata.json');
+        const primary = [metadataPath, pagePath].filter((path) => files.includes(path));
+        if (touched && !primary.some((path) => touched.has(path))) {
+            continue;
+        }
+        const metadata = gdriveMetadataSchema.parse(JSON.parse(await readFile(join(stagedDir, metadataPath), 'utf-8')));
+        const rawFiles = touched ? primary.filter((path) => touched.has(path)).sort() : primary.sort();
+        const dependencyPaths = ['manifest.json'].filter((path) => !rawFiles.includes(path));
+        const excluded = new Set([...rawFiles, ...dependencyPaths]);
+        const peerFileIndex = files.filter((path) => !excluded.has(path)).sort();
+        workUnits.push({
+            unitKey: safeUnitKey(pagePath),
+            displayLabel: metadata.path,
+            rawFiles,
+            dependencyPaths,
+            peerFileIndex,
+            notes: GDRIVE_RECONCILE_GUIDANCE,
+        });
+    }
+    return {
+        workUnits,
+        eviction: diffSet && diffSet.deleted.length > 0
+            ? { deletedRawPaths: diffSet.deleted.map((path) => normalizeRawPath(path)).sort() }
+            : undefined,
+        reconcileNotes: ['Google Drive docs are knowledge-only in v1; keep output in wiki pages unless later follow-up work expands scope.'],
+        contextReport: { capped: false, warnings: manifest.warnings },
+    };
+}
+export async function describeGdriveScope(stagedDir) {
+    const manifest = await readManifest(stagedDir);
+    const scopeKey = JSON.stringify({
+        folderId: manifest.folderId,
+        recursive: manifest.recursive,
+    });
+    const fingerprint = createHash('sha256').update(scopeKey).digest('hex');
+    return {
+        fingerprint,
+        isPathInScope: (rawPath) => rawPath === 'manifest.json' || rawPath.startsWith('docs/'),
+    };
+}

package/dist/context/ingest/adapters/gdrive/detect.d.ts

@@ -0,0 +1 @@
+export declare function detectGdriveStagedDir(stagedDir: string): Promise<boolean>;