@kaelio/ktx 0.4.1 → 0.6.0

package/dist/context/project/config.js

@@ -0,0 +1,325 @@
+import { KTX_MODEL_ROLES } from '../../llm/types.js';
+import YAML from 'yaml';
+import * as z from 'zod';
+import { connectionConfigSchema } from './driver-schemas.js';
+const KTX_LLM_BACKENDS = ['none', 'anthropic', 'vertex', 'gateway', 'claude-code'];
+const KTX_EMBEDDING_BACKENDS = ['none', 'openai', 'sentence-transformers'];
+const KTX_PROMPT_CACHE_TTLS = ['5m', '1h'];
+const KTX_ENRICHMENT_MODES = ['none', 'deterministic', 'llm'];
+const KTX_WORK_UNIT_FAILURE_MODES = ['abort', 'continue'];
+const KTX_STORAGE_STATES = ['sqlite', 'postgres'];
+const KTX_SEARCH_BACKENDS = ['sqlite-fts5', 'postgres-hybrid'];
+const apiCredentialsSchema = z
+    .strictObject({
+    api_key: z.string().min(1).optional().describe('API key for the provider. Read from this value or the provider-specific environment variable.'),
+    base_url: z.string().min(1).optional().describe('Override the provider\'s default API base URL (e.g. a proxy or self-hosted gateway).'),
+})
+    .describe('API credentials block: optional key and base URL for an LLM or embedding provider.');
+const vertexProviderSchema = z
+    .strictObject({
+    project: z.string().min(1).optional().describe('Google Cloud project ID hosting the Vertex AI endpoint.'),
+    location: z.string().min(1).describe('Vertex AI region (e.g. "us-east5"). Required whenever the vertex provider block is present.'),
+})
+    .describe('Google Vertex AI provider configuration.');
+const sentenceTransformersSchema = z
+    .strictObject({
+    base_url: z.string().default('').describe('Base URL of the sentence-transformers HTTP server. Leave empty (or omit) when the `ktx` CLI is expected to start and manage a local daemon for this project; programmatic consumers must populate it explicitly.'),
+    pathPrefix: z.string().optional().describe('Optional URL path prefix prepended to embedding requests.'),
+})
+    .describe('Sentence-transformers embedding server configuration.');
+const llmProviderSchema = z
+    .strictObject({
+    backend: z
+        .enum(KTX_LLM_BACKENDS)
+        .default('none')
+        .describe('LLM provider backend. "none" disables LLM features; "anthropic" / "vertex" / "gateway" require the matching nested credentials block; "claude-code" uses the local Claude Code session.'),
+    vertex: vertexProviderSchema.optional().describe('Vertex AI credentials, used when backend is "vertex".'),
+    anthropic: apiCredentialsSchema.optional().describe('Anthropic API credentials, used when backend is "anthropic".'),
+    gateway: apiCredentialsSchema.optional().describe('AI Gateway credentials, used when backend is "gateway".'),
+})
+    .describe('LLM provider selection and credentials.');
+const promptCachingSchema = z
+    .strictObject({
+    enabled: z.boolean().optional().describe('Master switch for Anthropic-style prompt caching. When omitted, the backend\'s default applies.'),
+    systemTtl: z.enum(KTX_PROMPT_CACHE_TTLS).optional().describe('Cache TTL for the system prompt segment ("5m" or "1h").'),
+    toolsTtl: z.enum(KTX_PROMPT_CACHE_TTLS).optional().describe('Cache TTL for the tools/schema segment ("5m" or "1h").'),
+    historyTtl: z.enum(KTX_PROMPT_CACHE_TTLS).optional().describe('Cache TTL for conversation-history cache breakpoints ("5m" or "1h").'),
+    vertexFallbackTo5m: z.boolean().optional().describe('When true, transparently downgrade 1h TTLs to 5m on Vertex, which does not support 1h caching.'),
+})
+    .describe('Prompt-caching tunables for Anthropic-compatible providers.');
+const llmSchema = z
+    .strictObject({
+    provider: llmProviderSchema.prefault({}).describe('LLM provider backend and credentials.'),
+    models: z
+        .partialRecord(z.enum(KTX_MODEL_ROLES), z.string().min(1))
+        .default({})
+        .describe('Per-role model overrides keyed by KTX model role (e.g. "default", "triage"). Values are provider-specific model identifiers.'),
+    promptCaching: promptCachingSchema.optional().describe('Optional prompt-caching tunables.'),
+})
+    .describe('LLM provider, per-role model overrides, and prompt-caching tunables.');
+const embeddingSchema = z
+    .strictObject({
+    backend: z
+        .enum(KTX_EMBEDDING_BACKENDS)
+        .default('none')
+        .describe('Embedding backend. "openai" and "sentence-transformers" call out to those providers; "none" disables embeddings.'),
+    model: z.string().min(1).optional().describe('Provider-specific embedding model identifier (e.g. "text-embedding-3-small").'),
+    dimensions: z
+        .int()
+        .positive()
+        .default(8)
+        .describe('Embedding vector dimensionality. The default value 8 is a placeholder that is only valid alongside backend: none; ' +
+        'before switching backend to openai/sentence-transformers, set this explicitly to match the chosen model ' +
+        '(e.g. 384 for all-MiniLM-L6-v2, 1536 for text-embedding-3-small).'),
+    openai: apiCredentialsSchema.optional().describe('OpenAI credentials, used when backend is "openai".'),
+    sentenceTransformers: sentenceTransformersSchema.optional().describe('Sentence-transformers server config, used when backend is "sentence-transformers".'),
+    batchSize: z.int().positive().optional().describe('Number of texts per embedding API call. Omit to use the backend default.'),
+})
+    .describe('Embedding backend, model, and provider credentials.');
+const workUnitsSchema = z
+    .strictObject({
+    stepBudget: z.int().positive().default(40).describe('Maximum number of agent steps allowed per work unit before it is force-terminated.'),
+    maxConcurrency: z.int().positive().default(1).describe('Maximum number of work units run concurrently during ingest.'),
+    failureMode: z
+        .enum(KTX_WORK_UNIT_FAILURE_MODES)
+        .default('continue')
+        .describe('Behavior when a work unit fails: "abort" stops the whole ingest run; "continue" records the failure and keeps going.'),
+})
+    .describe('Concurrency and failure handling for ingest work units.');
+const ingestSchema = z
+    .strictObject({
+    adapters: z
+        .array(z.string().min(1))
+        .default([])
+        .describe('Ingest adapter identifiers to run (e.g. "metabase", "looker", "historic-sql"). Empty array means no adapters are run.'),
+    embeddings: embeddingSchema
+        .prefault({ backend: 'none' })
+        .describe('Embedding configuration used when ingest adapters need to embed documents.'),
+    workUnits: workUnitsSchema.prefault({}).describe('Concurrency and failure handling for ingest work units.'),
+})
+    .describe('Ingest pipeline configuration: adapters, embeddings, and work-unit policy.');
+const scanEnrichmentSchema = z
+    .strictObject({
+    mode: z
+        .enum(KTX_ENRICHMENT_MODES)
+        .default('none')
+        .describe('Column/table enrichment mode. "none" disables enrichment; "deterministic" uses local heuristics; "llm" calls the configured LLM provider.'),
+    embeddings: embeddingSchema.optional().describe('Optional embedding override for enrichment-time vectorization. Falls back to ingest.embeddings when omitted.'),
+})
+    .describe('Schema-scan enrichment: how columns and tables are described.');
+const scanRelationshipsSchema = z
+    .strictObject({
+    enabled: z.boolean().default(true).describe('Master switch for relationship discovery during scan.'),
+    llmProposals: z.boolean().default(true).describe('When true, propose relationships using the configured LLM in addition to deterministic candidates.'),
+    validationRequiredForManifest: z
+        .boolean()
+        .default(true)
+        .describe('When true, only relationships that pass database-side validation are written to the manifest.'),
+    acceptThreshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.85)
+        .describe('Confidence score (0–1) at or above which an LLM-proposed relationship is auto-accepted into the manifest.'),
+    reviewThreshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.55)
+        .describe('Confidence score (0–1) at or above which a proposal is surfaced for human review (but not auto-accepted).'),
+    maxLlmTablesPerBatch: z
+        .int()
+        .positive()
+        .default(40)
+        .describe('Maximum number of tables included in a single LLM relationship-proposal batch.'),
+    maxCandidatesPerColumn: z
+        .int()
+        .positive()
+        .default(25)
+        .describe('Maximum number of candidate join partners considered per column during relationship discovery.'),
+    profileSampleRows: z.int().positive().default(10000).describe('Number of rows sampled per table when profiling values for relationship inference.'),
+    profileConcurrency: z
+        .int()
+        .positive()
+        .default(4)
+        .describe('Parallel relationship-profile queries run against the database during scan.'),
+    validationConcurrency: z.int().positive().default(4).describe('Number of relationship validation queries run in parallel against the database.'),
+    validationBudget: z
+        .union([z.literal('all'), z.int().nonnegative()])
+        .optional()
+        .describe('Cap on validation queries per scan run. Use "all" for unlimited, an integer for a hard cap, or omit for the runtime default.'),
+})
+    .describe('Schema-scan relationship discovery and validation tunables.');
+const scanSchema = z
+    .strictObject({
+    enrichment: scanEnrichmentSchema.prefault({}).describe('Column/table enrichment configuration.'),
+    relationships: scanRelationshipsSchema.prefault({}).describe('Relationship discovery and validation configuration.'),
+})
+    .describe('Schema-scan configuration: enrichment and relationship discovery.');
+const setupSchema = z
+    .strictObject({
+    database_connection_ids: z
+        .array(z.string().min(1))
+        .default([])
+        .describe('Connection IDs (keys of the top-level `connections` map) that the setup wizard treats as the project\'s primary databases.'),
+})
+    .describe('Setup-wizard state captured during `ktx setup`.');
+const storageGitSchema = z
+    .strictObject({
+    auto_commit: z.boolean().default(true).describe('When true, KTX automatically commits state changes to the local Git-backed store.'),
+    author: z
+        .string()
+        .min(1)
+        .default('ktx <ktx@example.com>')
+        .describe('Git author identity used for auto-commits, in standard "Name <email>" form.'),
+})
+    .describe('Git-backed storage commit policy.');
+const storageSchema = z
+    .strictObject({
+    state: z
+        .enum(KTX_STORAGE_STATES)
+        .default('sqlite')
+        .describe('Backend for KTX state storage. "sqlite" uses .ktx/db.sqlite; "postgres" expects a configured Postgres connection.'),
+    search: z
+        .enum(KTX_SEARCH_BACKENDS)
+        .default('sqlite-fts5')
+        .describe('Backend for search indexes. "sqlite-fts5" uses SQLite FTS5; "postgres-hybrid" uses Postgres lexical + vector hybrid search.'),
+    git: storageGitSchema.prefault({}).describe('Git-backed storage commit policy.'),
+})
+    .describe('Storage backends and commit policy for KTX state and search indexes.');
+const connectionSchema = connectionConfigSchema;
+const agentSchema = z
+    .strictObject({
+    run_research: z
+        .strictObject({
+        enabled: z.boolean().default(false).describe('Master switch for the research agent.'),
+        max_iterations: z
+            .number()
+            .int()
+            .nonnegative()
+            .default(20)
+            .describe('Maximum number of tool-call iterations the research agent may take per run.'),
+        default_toolset: z
+            .array(z.string().min(1))
+            .default(['sl_query', 'wiki_search', 'sl_read_source'])
+            .describe('Default list of tool identifiers exposed to the research agent.'),
+    })
+        .prefault({})
+        .describe('Research-agent configuration.'),
+})
+    .describe('Agent feature configuration.');
+const memorySchema = z
+    .strictObject({
+    auto_commit: z.boolean().default(true).describe('When true, KTX automatically commits memory updates to the Git-backed store.'),
+})
+    .describe('Memory subsystem configuration.');
+const ktxProjectConfigSchema = z
+    .strictObject({
+    setup: setupSchema.optional().describe('Setup-wizard state. Written by `ktx setup`; may be omitted.'),
+    connections: z
+        .record(z.string(), connectionSchema)
+        .default({})
+        .describe('Map of connection ID to connector configuration. Keys are user-chosen names referenced elsewhere in the config.'),
+    storage: storageSchema.prefault({}).describe('Storage backends and commit policy for KTX state and search indexes.'),
+    llm: llmSchema.prefault({}).describe('LLM provider, per-role model overrides, and prompt-caching tunables.'),
+    ingest: ingestSchema.prefault({}).describe('Ingest pipeline configuration.'),
+    agent: agentSchema.prefault({}).describe('Agent feature configuration.'),
+    memory: memorySchema.prefault({}).describe('Memory subsystem configuration.'),
+    scan: scanSchema.prefault({}).describe('Schema-scan configuration: enrichment and relationship discovery.'),
+})
+    .describe('Configuration schema for KTX project files (ktx.yaml).');
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function dottedPath(path) {
+    return path.map((segment) => String(segment)).join('.');
+}
+function valueAtPath(root, path) {
+    let cursor = root;
+    for (const segment of path) {
+        if (cursor === null || typeof cursor !== 'object')
+            return undefined;
+        cursor = cursor[segment];
+    }
+    return cursor;
+}
+function formatIssue(issue, input) {
+    const basePath = dottedPath(issue.path);
+    if (issue.code === 'unrecognized_keys') {
+        const keys = issue.keys ?? [];
+        return keys.map((key) => {
+            const fullPath = basePath.length > 0 ? `${basePath}.${key}` : key;
+            return { path: fullPath, message: `Unsupported ${fullPath}: unknown field` };
+        });
+    }
+    const lastSegment = issue.path[issue.path.length - 1];
+    if (lastSegment === 'backend' && (issue.code === 'invalid_value' || issue.code === 'invalid_type')) {
+        const value = valueAtPath(input, issue.path);
+        return [{ path: basePath, message: `Unsupported ${basePath}: ${String(value)}` }];
+    }
+    return [{ path: basePath, message: basePath.length > 0 ? `${basePath}: ${issue.message}` : issue.message }];
+}
+function collectIssues(error, input) {
+    return error.issues.flatMap((issue) => formatIssue(issue, input));
+}
+function formatZodError(error, input) {
+    return collectIssues(error, input)
+        .map((issue) => issue.message)
+        .join('\n');
+}
+export function buildDefaultKtxProjectConfig() {
+    return ktxProjectConfigSchema.parse({});
+}
+export function parseKtxProjectConfig(raw) {
+    const parsed = YAML.parse(raw);
+    if (!isRecord(parsed)) {
+        throw new Error('ktx.yaml must contain a YAML object');
+    }
+    const result = ktxProjectConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(formatZodError(result.error, parsed));
+    }
+    return result.data;
+}
+export function validateKtxProjectConfig(raw) {
+    let parsed;
+    try {
+        parsed = YAML.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, issues: [{ path: '', message: `ktx.yaml parse error: ${message}` }] };
+    }
+    if (!isRecord(parsed)) {
+        return { ok: false, issues: [{ path: '', message: 'ktx.yaml must contain a YAML object' }] };
+    }
+    const result = ktxProjectConfigSchema.safeParse(parsed);
+    if (result.success) {
+        return { ok: true, issues: [] };
+    }
+    return { ok: false, issues: collectIssues(result.error, parsed) };
+}
+export function generateKtxProjectConfigJsonSchema() {
+    const schema = z.toJSONSchema(ktxProjectConfigSchema, {
+        target: 'draft-7',
+        io: 'input',
+    });
+    return {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        $id: 'https://ktx.dev/schemas/ktx-project-config.json',
+        title: 'ktx.yaml',
+        ...schema,
+    };
+}
+export function serializeKtxProjectConfig(config) {
+    const serializedConfig = config.ingest.adapters.length === 0
+        ? {
+            ...config,
+            ingest: {
+                embeddings: config.ingest.embeddings,
+                workUnits: config.ingest.workUnits,
+            },
+        }
+        : config;
+    return `${YAML.stringify(serializedConfig, { indent: 2, lineWidth: 0 }).trimEnd()}\n`;
+}

package/dist/context/project/driver-schemas.d.ts

@@ -0,0 +1,101 @@
+import * as z from 'zod';
+export declare const connectionConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    driver: z.ZodLiteral<"postgres">;
+    url: z.ZodOptional<z.ZodString>;
+    enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"mysql">;
+    url: z.ZodOptional<z.ZodString>;
+    enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"snowflake">;
+    url: z.ZodOptional<z.ZodString>;
+    enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"bigquery">;
+    url: z.ZodOptional<z.ZodString>;
+    enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"sqlite">;
+    url: z.ZodOptional<z.ZodString>;
+    enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"clickhouse">;
+    url: z.ZodOptional<z.ZodString>;
+    enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"sqlserver">;
+    url: z.ZodOptional<z.ZodString>;
+    enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"metabase">;
+    api_url: z.ZodString;
+    api_key: z.ZodOptional<z.ZodString>;
+    api_key_ref: z.ZodOptional<z.ZodString>;
+    network_proxy: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    networkProxy: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    mappings: z.ZodOptional<z.ZodObject<{
+        databaseMappings: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>;
+        syncEnabled: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+        syncMode: z.ZodDefault<z.ZodEnum<{
+            ALL: "ALL";
+            ONLY: "ONLY";
+            EXCEPT: "EXCEPT";
+        }>>;
+        selections: z.ZodDefault<z.ZodObject<{
+            collections: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+            items: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strip>>;
+        defaultTagNames: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"looker">;
+    base_url: z.ZodString;
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+    client_secret_ref: z.ZodOptional<z.ZodString>;
+    mappings: z.ZodOptional<z.ZodObject<{
+        connectionMappings: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>;
+    }, z.core.$strip>>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"lookml">;
+    repoUrl: z.ZodString;
+    branch: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    auth_token_ref: z.ZodOptional<z.ZodString>;
+    mappings: z.ZodOptional<z.ZodObject<{
+        expectedLookerConnectionName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"notion">;
+    auth_token: z.ZodOptional<z.ZodString>;
+    auth_token_ref: z.ZodOptional<z.ZodString>;
+    crawl_mode: z.ZodOptional<z.ZodEnum<{
+        selected_roots: "selected_roots";
+        all_accessible: "all_accessible";
+    }>>;
+    root_page_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    root_database_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    root_data_source_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    max_pages_per_run: z.ZodOptional<z.ZodNumber>;
+    max_knowledge_creates_per_run: z.ZodOptional<z.ZodNumber>;
+    max_knowledge_updates_per_run: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"dbt">;
+    source_dir: z.ZodOptional<z.ZodString>;
+    repo_url: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    auth_token_ref: z.ZodOptional<z.ZodString>;
+    profiles_path: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodString>;
+    project_name: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"metricflow">;
+    metricflow: z.ZodObject<{
+        repoUrl: z.ZodString;
+        branch: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        auth_token_ref: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+}, z.core.$loose>], "driver">;

package/dist/context/project/driver-schemas.js

@@ -0,0 +1,182 @@
+import * as z from 'zod';
+import { lookerMappingsSchema, lookmlMappingsSchema, metabaseMappingsSchema, } from './mappings-yaml-schema.js';
+const warehouseDrivers = [
+    'postgres',
+    'mysql',
+    'snowflake',
+    'bigquery',
+    'sqlite',
+    'clickhouse',
+    'sqlserver',
+];
+function warehouseConnectionSchema(driver) {
+    return z
+        .looseObject({
+        driver: z.literal(driver),
+        url: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Warehouse connection URL or DSN; may contain environment-variable references like env:DATABASE_URL.'),
+        enabled_tables: z
+            .array(z.string().min(1))
+            .optional()
+            .describe('Optional allowlist of fully-qualified table names ("schema.table") to ingest. When set, live-database ingest discards any table whose schema-qualified name is not in this list. Useful for smoke-testing deep ingest on a single table.'),
+    })
+        .describe(`${driver} warehouse connection. Additional driver-tunable fields (e.g. context.queryHistory) are accepted and passed through.`);
+}
+const warehouseConnectionSchemas = [
+    warehouseConnectionSchema('postgres'),
+    warehouseConnectionSchema('mysql'),
+    warehouseConnectionSchema('snowflake'),
+    warehouseConnectionSchema('bigquery'),
+    warehouseConnectionSchema('sqlite'),
+    warehouseConnectionSchema('clickhouse'),
+    warehouseConnectionSchema('sqlserver'),
+];
+const positiveIntKeyMessage = (field) => `${field} keys must be positive-integer strings (e.g. "1", "42")`;
+const positiveIntKeyRegex = /^[1-9]\d*$/;
+const metabaseMappingsStrictSchema = metabaseMappingsSchema.superRefine((value, ctx) => {
+    for (const key of Object.keys(value.databaseMappings ?? {})) {
+        if (!positiveIntKeyRegex.test(key)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['databaseMappings', key],
+                message: positiveIntKeyMessage('databaseMappings'),
+            });
+        }
+    }
+    for (const key of Object.keys(value.syncEnabled ?? {})) {
+        if (!positiveIntKeyRegex.test(key)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['syncEnabled', key],
+                message: positiveIntKeyMessage('syncEnabled'),
+            });
+        }
+    }
+});
+const metabaseConnectionSchema = z
+    .looseObject({
+    driver: z.literal('metabase'),
+    api_url: z.string().url().describe('Metabase instance API URL (e.g. https://metabase.example.com).'),
+    api_key: z.string().min(1).optional().describe('Literal Metabase API key. Prefer api_key_ref for safety.'),
+    api_key_ref: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Reference to Metabase API key (e.g. env:METABASE_API_KEY or file:/path).'),
+    network_proxy: z.looseObject({}).optional().describe('Optional network proxy configuration (snake_case form).'),
+    networkProxy: z.looseObject({}).optional().describe('Optional network proxy configuration (camelCase form).'),
+    mappings: metabaseMappingsStrictSchema
+        .optional()
+        .describe('Metabase database-to-warehouse mappings and sync configuration.'),
+})
+    .describe('Metabase context-source connection.');
+const lookerConnectionSchema = z
+    .looseObject({
+    driver: z.literal('looker'),
+    base_url: z.string().url().describe('Looker instance base URL (e.g. https://looker.example.com).'),
+    client_id: z.string().min(1).describe('Looker OAuth client ID.'),
+    client_secret: z.string().min(1).optional().describe('Literal Looker OAuth client secret. Prefer client_secret_ref.'),
+    client_secret_ref: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Reference to Looker OAuth client secret (e.g. env:LOOKER_CLIENT_SECRET).'),
+    mappings: lookerMappingsSchema.optional().describe('Looker connection-name to KTX warehouse mappings.'),
+})
+    .describe('Looker context-source connection.');
+const lookmlConnectionSchema = z
+    .looseObject({
+    driver: z.literal('lookml'),
+    repoUrl: z
+        .string()
+        .min(1)
+        .describe('Git URL of the LookML project (https, ssh, or file:). Field is camelCase by convention.'),
+    branch: z.string().min(1).optional().describe('Git branch (default "main" downstream).'),
+    path: z.string().optional().describe('Subdirectory within the repo when the LookML project lives in a monorepo.'),
+    auth_token_ref: z.string().min(1).optional().describe('Reference to Git auth token for private repos (e.g. env:GITHUB_TOKEN).'),
+    mappings: lookmlMappingsSchema.optional().describe('LookML expected-connection mapping for ingest gating.'),
+})
+    .describe('LookML context-source connection.');
+const notionConnectionSchema = z
+    .looseObject({
+    driver: z.literal('notion'),
+    auth_token: z.string().min(1).optional().describe('Literal Notion integration token. Prefer auth_token_ref.'),
+    auth_token_ref: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Reference to Notion integration token (e.g. env:NOTION_TOKEN).'),
+    crawl_mode: z
+        .enum(['selected_roots', 'all_accessible'])
+        .optional()
+        .describe('Crawl scope. "selected_roots" requires at least one of root_page_ids, root_database_ids, root_data_source_ids.'),
+    root_page_ids: z.array(z.string().min(1)).optional().describe('Notion page IDs to crawl when crawl_mode is selected_roots.'),
+    root_database_ids: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('Notion database IDs to crawl when crawl_mode is selected_roots.'),
+    root_data_source_ids: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('Notion data source IDs to crawl when crawl_mode is selected_roots.'),
+    max_pages_per_run: z
+        .number()
+        .int()
+        .min(1)
+        .max(10000)
+        .optional()
+        .describe('Maximum Notion pages fetched in a single ingest run.'),
+    max_knowledge_creates_per_run: z
+        .number()
+        .int()
+        .min(0)
+        .max(25)
+        .optional()
+        .describe('Maximum new wiki pages created per run.'),
+    max_knowledge_updates_per_run: z
+        .number()
+        .int()
+        .min(0)
+        .max(100)
+        .optional()
+        .describe('Maximum existing wiki pages updated per run.'),
+})
+    .describe('Notion context-source connection.');
+const dbtConnectionSchema = z
+    .looseObject({
+    driver: z.literal('dbt'),
+    source_dir: z.string().min(1).optional().describe('Absolute or project-relative path to a local dbt project.'),
+    repo_url: z.string().min(1).optional().describe('Git URL of the dbt project (https, ssh, or file:).'),
+    branch: z.string().min(1).optional().describe('Git branch when using repo_url.'),
+    path: z.string().optional().describe('Subdirectory within the repo when the dbt project lives in a monorepo.'),
+    auth_token_ref: z.string().min(1).optional().describe('Reference to Git auth token for private repos.'),
+    profiles_path: z.string().optional().describe('Override path to dbt profiles.yml.'),
+    target: z.string().min(1).optional().describe('dbt target name (e.g. dev, prod).'),
+    project_name: z.string().min(1).optional().describe('Override auto-detected dbt project name.'),
+})
+    .describe('dbt context-source connection.');
+const metricflowConnectionSchema = z
+    .looseObject({
+    driver: z.literal('metricflow'),
+    metricflow: z
+        .looseObject({
+        repoUrl: z.string().min(1).describe('Git URL of the MetricFlow / SL project.'),
+        branch: z.string().min(1).optional().describe('Git branch (default "main").'),
+        path: z.string().optional().describe('Subdirectory within the repo when the SL config lives in a monorepo.'),
+        auth_token_ref: z.string().min(1).optional().describe('Reference to Git auth token for private repos.'),
+    })
+        .describe('Nested MetricFlow configuration block.'),
+})
+    .describe('MetricFlow / SL context-source connection.');
+export const connectionConfigSchema = z.discriminatedUnion('driver', [
+    ...warehouseConnectionSchemas,
+    metabaseConnectionSchema,
+    lookerConnectionSchema,
+    lookmlConnectionSchema,
+    notionConnectionSchema,
+    dbtConnectionSchema,
+    metricflowConnectionSchema,
+]);

package/dist/context/project/local-git-file-store.d.ts

@@ -0,0 +1,24 @@
+import type { GitService } from '../../context/core/git.service.js';
+import type { KtxFileHistoryEntry, KtxFileListResult, KtxFileReadResult, KtxFileStorePort, KtxFileWriteResult } from '../../context/core/file-store.js';
+export interface LocalGitFileStoreDeps {
+    rootDir: string;
+    git: GitService;
+}
+export declare class LocalGitFileStore implements KtxFileStorePort<LocalGitFileStore> {
+    private readonly rootDir;
+    private readonly git;
+    constructor(deps: LocalGitFileStoreDeps);
+    forWorktree(workdir: string): LocalGitFileStore;
+    writeFile(path: string, content: string, author: string, authorEmail: string, commitMessage: string, options?: {
+        skipLock?: boolean;
+    }): Promise<KtxFileWriteResult>;
+    readFile(path: string): Promise<KtxFileReadResult>;
+    deleteFile(path: string, author: string, authorEmail: string, commitMessage: string, options?: {
+        skipLock?: boolean;
+    }): Promise<KtxFileWriteResult | null>;
+    listFiles(path?: string, stripPrefix?: boolean): Promise<KtxFileListResult>;
+    getFileHistory(path: string): Promise<KtxFileHistoryEntry[]>;
+    private safeRelativePath;
+    private absolutePath;
+    private walk;
+}