@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/node_modules/@ktx/context/dist/project/driver-schemas.js

@@ -0,0 +1,180 @@
+import * as z from 'zod';
+import { lookerMappingsSchema, lookmlMappingsSchema, metabaseMappingsSchema, } from './mappings-yaml-schema.js';
+const warehouseDrivers = [
+    'postgres',
+    'postgresql',
+    '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.'),
+    })
+        .describe(`${driver} warehouse connection. Additional driver-tunable fields (e.g. historicSql, context.queryHistory) are accepted and passed through.`);
+}
+const warehouseConnectionSchemas = [
+    warehouseConnectionSchema('postgres'),
+    warehouseConnectionSchema('postgresql'),
+    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/node_modules/@ktx/context/dist/project/driver-schemas.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/project/driver-schemas.test.js

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import { connectionConfigSchema } from './driver-schemas.js';
+describe('connectionConfigSchema (driver discriminated union)', () => {
+    it.each([
+        ['postgres', 'postgres://user:pass@host:5432/db'], // pragma: allowlist secret
+        ['postgresql', 'postgresql://user:pass@host:5432/db'], // pragma: allowlist secret
+        ['mysql', 'mysql://user:pass@host:3306/db'], // pragma: allowlist secret
+        ['snowflake', 'snowflake://account/db'],
+        ['bigquery', 'bigquery://project/dataset'],
+        ['sqlite', 'sqlite:///tmp/db.sqlite'],
+        ['clickhouse', 'clickhouse://host:8123/db'],
+        ['sqlserver', 'sqlserver://host:1433;database=db'],
+    ])('parses %s warehouse connection', (driver, url) => {
+        expect(connectionConfigSchema.parse({ driver, url })).toMatchObject({ driver, url });
+    });
+    it('preserves unknown warehouse fields via looseObject passthrough', () => {
+        const parsed = connectionConfigSchema.parse({
+            driver: 'postgres',
+            url: 'postgres://x',
+            historicSql: { enabled: true },
+            context: { queryHistory: { enabled: false } },
+        });
+        expect(parsed).toMatchObject({
+            driver: 'postgres',
+            historicSql: { enabled: true },
+            context: { queryHistory: { enabled: false } },
+        });
+    });
+    it('rejects an unknown driver', () => {
+        expect(() => connectionConfigSchema.parse({ driver: 'nope', url: 'x' })).toThrow();
+    });
+});
+describe('connectionConfigSchema - context source drivers with mappings', () => {
+    it('parses a metabase connection with mappings', () => {
+        const parsed = connectionConfigSchema.parse({
+            driver: 'metabase',
+            api_url: 'https://metabase.example.com',
+            api_key_ref: 'env:METABASE_API_KEY', // pragma: allowlist secret
+            mappings: {
+                databaseMappings: { '3': 'prod-warehouse' },
+                syncEnabled: { '3': true },
+                syncMode: 'ONLY',
+            },
+        });
+        expect(parsed).toMatchObject({
+            driver: 'metabase',
+            api_url: 'https://metabase.example.com',
+            mappings: {
+                databaseMappings: { '3': 'prod-warehouse' },
+                syncMode: 'ONLY',
+            },
+        });
+    });
+    it('parses a looker connection with connectionMappings', () => {
+        const parsed = connectionConfigSchema.parse({
+            driver: 'looker',
+            base_url: 'https://looker.example.com',
+            client_id: 'abc',
+            client_secret_ref: 'env:LOOKER_CLIENT_SECRET', // pragma: allowlist secret
+            mappings: { connectionMappings: { bigquery_prod: 'wh' } },
+        });
+        expect(parsed.mappings).toEqual({ connectionMappings: { bigquery_prod: 'wh' } });
+    });
+    it('parses a lookml connection with expectedLookerConnectionName', () => {
+        const parsed = connectionConfigSchema.parse({
+            driver: 'lookml',
+            repoUrl: 'https://github.com/acme/looker.git',
+            branch: 'main',
+            mappings: { expectedLookerConnectionName: 'bigquery_prod' },
+        });
+        expect(parsed.mappings).toEqual({ expectedLookerConnectionName: 'bigquery_prod' });
+    });
+    it('rejects metabase mapping with non-integer database key', () => {
+        expect(() => connectionConfigSchema.parse({
+            driver: 'metabase',
+            api_url: 'https://x',
+            mappings: { databaseMappings: { abc: 'wh' } },
+        })).toThrow();
+    });
+});
+describe('connectionConfigSchema - notion / dbt / metricflow', () => {
+    it('parses a notion connection with selected_roots crawl', () => {
+        const parsed = connectionConfigSchema.parse({
+            driver: 'notion',
+            auth_token_ref: 'env:NOTION_TOKEN',
+            crawl_mode: 'selected_roots',
+            root_page_ids: ['abc', 'def'],
+            max_pages_per_run: 500,
+        });
+        expect(parsed).toMatchObject({
+            driver: 'notion',
+            crawl_mode: 'selected_roots',
+            root_page_ids: ['abc', 'def'],
+            max_pages_per_run: 500,
+        });
+    });
+    it('rejects notion with unknown crawl_mode', () => {
+        expect(() => connectionConfigSchema.parse({
+            driver: 'notion',
+            auth_token_ref: 'env:NOTION_TOKEN',
+            crawl_mode: 'everything',
+        })).toThrow();
+    });
+    it('parses a dbt connection from a local source_dir', () => {
+        const parsed = connectionConfigSchema.parse({
+            driver: 'dbt',
+            source_dir: '/tmp/dbt-project',
+            target: 'dev',
+        });
+        expect(parsed).toMatchObject({ driver: 'dbt', source_dir: '/tmp/dbt-project', target: 'dev' });
+    });
+    it('parses a metricflow connection with nested config', () => {
+        const parsed = connectionConfigSchema.parse({
+            driver: 'metricflow',
+            metricflow: {
+                repoUrl: 'https://github.com/acme/sl.git',
+                branch: 'main',
+            },
+        });
+        expect(parsed).toMatchObject({
+            driver: 'metricflow',
+            metricflow: { repoUrl: 'https://github.com/acme/sl.git' },
+        });
+    });
+});

package/node_modules/@ktx/context/dist/project/index.d.ts

@@ -0,0 +1,12 @@
+export type { KtxConfigIssue, KtxConfigValidation, KtxProjectConfig, KtxProjectConnectionConfig, KtxProjectEmbeddingConfig, KtxProjectLlmConfig, KtxSearchBackend, KtxStorageState, } from './config.js';
+export { buildDefaultKtxProjectConfig, generateKtxProjectConfigJsonSchema, parseKtxProjectConfig, serializeKtxProjectConfig, validateKtxProjectConfig, } from './config.js';
+export type { KtxConnectionConfig } from './driver-schemas.js';
+export type { LocalGitFileStoreDeps } from './local-git-file-store.js';
+export { LocalGitFileStore } from './local-git-file-store.js';
+export { ktxLocalStateDbPath } from './local-state-db.js';
+export type { ConnectionMappingBootstrap, LookerMappingBootstrap, LookmlMappingBootstrap, MetabaseMappingBootstrap, } from './mappings-yaml-schema.js';
+export { parseConnectionMappingBootstrap, parseLookerMappingBootstrap, parseLookmlMappingBootstrap, parseMetabaseMappingBootstrap, } from './mappings-yaml-schema.js';
+export type { InitKtxProjectOptions, InitKtxProjectResult, KtxLocalProject, LoadKtxProjectOptions } from './project.js';
+export { initKtxProject, loadKtxProject } from './project.js';
+export type { KtxSetupStep } from './setup-config.js';
+export { KTX_SETUP_STEPS, ktxSetupStatePath, markKtxSetupStateStepComplete, mergeKtxSetupGitignoreEntries, readKtxSetupState, setKtxSetupDatabaseConnectionIds, writeKtxSetupState, } from './setup-config.js';

package/node_modules/@ktx/context/dist/project/index.js

@@ -0,0 +1,6 @@
+export { buildDefaultKtxProjectConfig, generateKtxProjectConfigJsonSchema, parseKtxProjectConfig, serializeKtxProjectConfig, validateKtxProjectConfig, } from './config.js';
+export { LocalGitFileStore } from './local-git-file-store.js';
+export { ktxLocalStateDbPath } from './local-state-db.js';
+export { parseConnectionMappingBootstrap, parseLookerMappingBootstrap, parseLookmlMappingBootstrap, parseMetabaseMappingBootstrap, } from './mappings-yaml-schema.js';
+export { initKtxProject, loadKtxProject } from './project.js';
+export { KTX_SETUP_STEPS, ktxSetupStatePath, markKtxSetupStateStepComplete, mergeKtxSetupGitignoreEntries, readKtxSetupState, setKtxSetupDatabaseConnectionIds, writeKtxSetupState, } from './setup-config.js';

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

@@ -0,0 +1,23 @@
+import type { GitService, KtxFileHistoryEntry, KtxFileListResult, KtxFileReadResult, KtxFileStorePort, KtxFileWriteResult } from '../core/index.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;
+}

package/node_modules/@ktx/context/dist/project/local-git-file-store.js

@@ -0,0 +1,140 @@
+import { promises as fs } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+function normalizeRelativePath(filePath) {
+    return filePath.replaceAll('\\', '/').replace(/^\.\/+/, '');
+}
+function gitInfoToWriteResult(info) {
+    return {
+        success: true,
+        commitHash: info.commitHash,
+        commitMessage: info.message,
+        author: info.author,
+        authorEmail: info.authorEmail,
+        timestamp: info.timestamp,
+        created: info.created,
+    };
+}
+export class LocalGitFileStore {
+    rootDir;
+    git;
+    constructor(deps) {
+        this.rootDir = resolve(deps.rootDir);
+        this.git = deps.git;
+    }
+    forWorktree(workdir) {
+        return new LocalGitFileStore({ rootDir: workdir, git: this.git.forWorktree(workdir) });
+    }
+    async writeFile(path, content, author, authorEmail, commitMessage, options) {
+        const relativePath = this.safeRelativePath(path);
+        const absolutePath = this.absolutePath(relativePath);
+        await fs.mkdir(dirname(absolutePath), { recursive: true });
+        await fs.writeFile(absolutePath, content, 'utf-8');
+        if (options?.skipLock) {
+            return { success: true, commitHash: null, path: relativePath, operation: 'write' };
+        }
+        const info = await this.git.commitFile(relativePath, commitMessage, author, authorEmail);
+        return { ...gitInfoToWriteResult(info), path: relativePath, operation: 'write' };
+    }
+    async readFile(path) {
+        const relativePath = this.safeRelativePath(path);
+        const absolutePath = this.absolutePath(relativePath);
+        const content = await fs.readFile(absolutePath, 'utf-8');
+        const stats = await fs.stat(absolutePath);
+        return {
+            path: relativePath,
+            content,
+            size: stats.size,
+            modifiedAt: stats.mtime.toISOString(),
+        };
+    }
+    async deleteFile(path, author, authorEmail, commitMessage, options) {
+        const relativePath = this.safeRelativePath(path);
+        const absolutePath = this.absolutePath(relativePath);
+        try {
+            await fs.access(absolutePath);
+        }
+        catch {
+            return null;
+        }
+        await fs.unlink(absolutePath);
+        if (options?.skipLock) {
+            return { success: true, commitHash: null, path: relativePath, operation: 'delete' };
+        }
+        const info = await this.git.deleteFile(relativePath, commitMessage, author, authorEmail);
+        return { ...gitInfoToWriteResult(info), path: relativePath, operation: 'delete' };
+    }
+    async listFiles(path = '', stripPrefix = false) {
+        const relativePath = path ? this.safeRelativePath(path) : '';
+        const searchRoot = relativePath ? this.absolutePath(relativePath) : this.rootDir;
+        let files;
+        try {
+            files = await this.walk(searchRoot);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return { files: [] };
+            }
+            throw error;
+        }
+        const prefix = relativePath ? `${relativePath}/` : '';
+        const relativeFiles = files
+            .map((file) => normalizeRelativePath(relative(this.rootDir, file)))
+            .filter((file) => !file.startsWith('.git/') && !file.includes('/.git/'))
+            .filter((file) => !file.startsWith('.ktx/cache/'))
+            .map((file) => (stripPrefix && prefix && file.startsWith(prefix) ? file.slice(prefix.length) : file))
+            .sort();
+        return { files: relativeFiles };
+    }
+    async getFileHistory(path) {
+        const relativePath = this.safeRelativePath(path);
+        const history = await this.git.getFileHistory(relativePath);
+        return history.map((entry) => ({
+            sha: entry.commitHash,
+            commitHash: entry.commitHash,
+            shortHash: entry.shortHash,
+            message: entry.message,
+            author: entry.author,
+            authorEmail: entry.authorEmail,
+            timestamp: entry.timestamp,
+            committedDate: entry.committedDate,
+            created: entry.created,
+            enhancedMessage: entry.enhancedMessage,
+        }));
+    }
+    safeRelativePath(path) {
+        if (path.length === 0) {
+            return '';
+        }
+        if (isAbsolute(path)) {
+            throw new Error('Path must be relative');
+        }
+        const normalized = normalizeRelativePath(path);
+        if (normalized === '.git' || normalized.startsWith('.git/')) {
+            throw new Error('Path cannot access .git');
+        }
+        const absolute = resolve(this.rootDir, normalized);
+        if (absolute !== this.rootDir && !absolute.startsWith(`${this.rootDir}${sep}`)) {
+            throw new Error('Path escapes the project directory');
+        }
+        return normalized;
+    }
+    absolutePath(path) {
+        return path ? join(this.rootDir, path) : this.rootDir;
+    }
+    async walk(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            const absolute = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name !== '.git') {
+                    files.push(...(await this.walk(absolute)));
+                }
+            }
+            else if (entry.isFile()) {
+                files.push(absolute);
+            }
+        }
+        return files;
+    }
+}

package/node_modules/@ktx/context/dist/project/local-git-file-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/project/local-git-file-store.test.js

@@ -0,0 +1,71 @@
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { GitService } from '../core/index.js';
+import { LocalGitFileStore } from './local-git-file-store.js';
+describe('LocalGitFileStore', () => {
+    let tempDir;
+    let store;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-local-store-'));
+        const coreConfig = {
+            storage: { configDir: tempDir, homeDir: tempDir },
+            git: {
+                userName: 'ktx',
+                userEmail: 'ktx@example.com',
+                bootstrapMessage: 'Initialize test project',
+                bootstrapAuthor: 'ktx',
+                bootstrapAuthorEmail: 'ktx@example.com',
+            },
+        };
+        const git = new GitService(coreConfig);
+        await git.onModuleInit();
+        store = new LocalGitFileStore({ rootDir: tempDir, git });
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('writes, commits, and reads a project file', async () => {
+        const write = await store.writeFile('wiki/global/revenue.md', '# Revenue\n', 'Agent', 'agent@example.com', 'Add revenue page');
+        expect(write.commitHash).toMatch(/^[0-9a-f]{40}$/);
+        await expect(readFile(join(tempDir, 'wiki/global/revenue.md'), 'utf-8')).resolves.toBe('# Revenue\n');
+        await expect(store.readFile('wiki/global/revenue.md')).resolves.toMatchObject({
+            content: '# Revenue\n',
+        });
+    });
+    it('lists files recursively and can strip the requested prefix', async () => {
+        await store.writeFile('wiki/global/a.md', 'a', 'Agent', 'agent@example.com', 'Add a');
+        await store.writeFile('wiki/global/nested/b.md', 'b', 'Agent', 'agent@example.com', 'Add b');
+        await expect(store.listFiles('wiki')).resolves.toEqual({
+            files: ['wiki/global/a.md', 'wiki/global/nested/b.md'],
+        });
+        await expect(store.listFiles('wiki/global', true)).resolves.toEqual({
+            files: ['a.md', 'nested/b.md'],
+        });
+    });
+    it('deletes and commits an existing file', async () => {
+        await store.writeFile('semantic-layer/conn/orders.yaml', 'name: orders\n', 'Agent', 'agent@example.com', 'Add SL');
+        const deleted = await store.deleteFile('semantic-layer/conn/orders.yaml', 'Agent', 'agent@example.com', 'Delete SL');
+        expect(deleted?.commitHash).toMatch(/^[0-9a-f]{40}$/);
+        await expect(stat(join(tempDir, 'semantic-layer/conn/orders.yaml'))).rejects.toThrow();
+    });
+    it('returns null when deleting a missing file', async () => {
+        await expect(store.deleteFile('missing.md', 'Agent', 'agent@example.com', 'Delete missing')).resolves.toBeNull();
+    });
+    it('exposes Git history for a file', async () => {
+        await store.writeFile('wiki/global/history.md', 'v1', 'Agent', 'agent@example.com', 'Add history');
+        await store.writeFile('wiki/global/history.md', 'v2', 'Agent', 'agent@example.com', 'Update history');
+        const history = await store.getFileHistory('wiki/global/history.md');
+        expect(Array.isArray(history)).toBe(true);
+        expect(history[0]).toMatchObject({ message: 'Update history' });
+        expect(history[1]).toMatchObject({ message: 'Add history' });
+    });
+    it('rejects absolute paths and parent-directory traversal', async () => {
+        await expect(store.writeFile('/tmp/outside.md', 'bad', 'Agent', 'agent@example.com', 'Bad write')).rejects.toThrow('Path must be relative');
+        await expect(store.readFile('../outside.md')).rejects.toThrow('Path escapes the project directory');
+    });
+    it('rejects direct .git access', async () => {
+        await expect(store.readFile('.git/config')).rejects.toThrow('Path cannot access .git');
+    });
+});

package/node_modules/@ktx/context/dist/project/local-state-db.d.ts

@@ -0,0 +1,2 @@
+import type { KtxLocalProject } from './project.js';
+export declare function ktxLocalStateDbPath(project: Pick<KtxLocalProject, 'projectDir'>): string;

package/node_modules/@ktx/context/dist/project/local-state-db.js

@@ -0,0 +1,4 @@
+import { join } from 'node:path';
+export function ktxLocalStateDbPath(project) {
+    return join(project.projectDir, '.ktx', 'db.sqlite');
+}

package/node_modules/@ktx/context/dist/project/mappings-yaml-schema.d.ts

@@ -0,0 +1,58 @@
+import * as z from 'zod';
+declare const metabaseSyncModeSchema: z.ZodEnum<{
+    ALL: "ALL";
+    ONLY: "ONLY";
+    EXCEPT: "EXCEPT";
+}>;
+export declare const metabaseMappingsSchema: 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>;
+export declare const lookerMappingsSchema: z.ZodObject<{
+    connectionMappings: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>;
+}, z.core.$strip>;
+export declare const lookmlMappingsSchema: z.ZodObject<{
+    expectedLookerConnectionName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type MetabaseMappingBootstrap = {
+    adapter: 'metabase';
+    connectionId: string;
+    databaseMappings: Record<string, string | null>;
+    syncEnabled: Record<string, boolean>;
+    syncMode: z.infer<typeof metabaseSyncModeSchema>;
+    selections: {
+        collections: number[];
+        items: number[];
+    };
+    defaultTagNames: string[];
+};
+export type LookerMappingBootstrap = {
+    adapter: 'looker';
+    connectionId: string;
+    connectionMappings: Record<string, string | null>;
+};
+export type LookmlMappingBootstrap = {
+    adapter: 'lookml';
+    connectionId: string;
+    expectedLookerConnectionName: string | null;
+};
+export type ConnectionMappingBootstrap = MetabaseMappingBootstrap | LookerMappingBootstrap | LookmlMappingBootstrap;
+type MappingConnectionInput = Record<string, unknown> & {
+    driver?: unknown;
+    mappings?: unknown;
+};
+export declare function parseMetabaseMappingBootstrap(connectionId: string, connection: MappingConnectionInput): MetabaseMappingBootstrap;
+export declare function parseLookerMappingBootstrap(connectionId: string, connection: MappingConnectionInput): LookerMappingBootstrap;
+export declare function parseLookmlMappingBootstrap(connectionId: string, connection: MappingConnectionInput): LookmlMappingBootstrap;
+export declare function parseConnectionMappingBootstrap(connectionId: string, connection: MappingConnectionInput): ConnectionMappingBootstrap | null;
+export {};