@kaelio/ktx 0.0.0 → 0.1.0-rc.0

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

@@ -0,0 +1,85 @@
+import * as z from 'zod';
+const metabaseSyncModeSchema = z.enum(['ALL', 'ONLY', 'EXCEPT']);
+const positiveIntegerValueSchema = z.number().int().positive();
+const stringTargetSchema = z.string().min(1).nullable();
+const metabaseSelectionsSchema = z
+    .object({
+    collections: z.array(positiveIntegerValueSchema).default([]),
+    items: z.array(positiveIntegerValueSchema).default([]),
+});
+const metabaseMappingsSchema = z
+    .object({
+    databaseMappings: z.record(z.string(), stringTargetSchema).default({}),
+    syncEnabled: z.record(z.string(), z.boolean()).default({}),
+    syncMode: metabaseSyncModeSchema.default('ALL'),
+    selections: metabaseSelectionsSchema.default({ collections: [], items: [] }),
+    defaultTagNames: z.array(z.string().min(1)).default([]),
+});
+const lookerMappingsSchema = z
+    .object({
+    connectionMappings: z.record(z.string().min(1), stringTargetSchema).default({}),
+});
+const lookmlMappingsSchema = z
+    .object({
+    expectedLookerConnectionName: z.string().min(1).nullable().default(null),
+});
+function recordValue(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : {};
+}
+function assertPositiveIntegerKeys(field, record) {
+    for (const key of Object.keys(record)) {
+        if (!/^[1-9]\d*$/.test(key)) {
+            throw new Error(`${field} key "${key}" must be a positive integer string`);
+        }
+    }
+}
+function driverOf(connection) {
+    return String(connection.driver ?? '').toLowerCase();
+}
+export function parseMetabaseMappingBootstrap(connectionId, connection) {
+    const rawMappings = recordValue(connection.mappings);
+    assertPositiveIntegerKeys('databaseMappings', recordValue(rawMappings.databaseMappings));
+    assertPositiveIntegerKeys('syncEnabled', recordValue(rawMappings.syncEnabled));
+    const parsed = metabaseMappingsSchema.parse(rawMappings);
+    return {
+        adapter: 'metabase',
+        connectionId,
+        databaseMappings: parsed.databaseMappings,
+        syncEnabled: parsed.syncEnabled,
+        syncMode: parsed.syncMode,
+        selections: parsed.selections,
+        defaultTagNames: parsed.defaultTagNames,
+    };
+}
+export function parseLookerMappingBootstrap(connectionId, connection) {
+    const parsed = lookerMappingsSchema.parse(recordValue(connection.mappings));
+    return {
+        adapter: 'looker',
+        connectionId,
+        connectionMappings: parsed.connectionMappings,
+    };
+}
+export function parseLookmlMappingBootstrap(connectionId, connection) {
+    const parsed = lookmlMappingsSchema.parse(recordValue(connection.mappings));
+    return {
+        adapter: 'lookml',
+        connectionId,
+        expectedLookerConnectionName: parsed.expectedLookerConnectionName,
+    };
+}
+export function parseConnectionMappingBootstrap(connectionId, connection) {
+    if (!connection.mappings || typeof connection.mappings !== 'object' || Array.isArray(connection.mappings)) {
+        return null;
+    }
+    const driver = driverOf(connection);
+    if (driver === 'metabase') {
+        return parseMetabaseMappingBootstrap(connectionId, connection);
+    }
+    if (driver === 'looker') {
+        return parseLookerMappingBootstrap(connectionId, connection);
+    }
+    if (driver === 'lookml') {
+        return parseLookmlMappingBootstrap(connectionId, connection);
+    }
+    return null;
+}

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

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

package/node_modules/@ktx/context/dist/project/mappings-yaml-schema.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { parseConnectionMappingBootstrap, parseLookmlMappingBootstrap, parseLookerMappingBootstrap, parseMetabaseMappingBootstrap, } from './mappings-yaml-schema.js';
+describe('ktx.yaml mapping bootstrap schema', () => {
+    it('parses Metabase mapping intent with CLI syncMode default ALL', () => {
+        const bootstrap = parseMetabaseMappingBootstrap('prod-metabase', {
+            driver: 'metabase',
+            mappings: {
+                databaseMappings: { '1': 'prod-warehouse', '2': null },
+                syncEnabled: { '1': true, '2': false },
+                selections: { collections: [12], items: [345] },
+                defaultTagNames: ['ktx', 'prod'],
+            },
+        });
+        expect(bootstrap).toEqual({
+            adapter: 'metabase',
+            connectionId: 'prod-metabase',
+            databaseMappings: { '1': 'prod-warehouse', '2': null },
+            syncEnabled: { '1': true, '2': false },
+            syncMode: 'ALL',
+            selections: { collections: [12], items: [345] },
+            defaultTagNames: ['ktx', 'prod'],
+        });
+    });
+    it('rejects Metabase non-integer mapping keys', () => {
+        expect(() => parseMetabaseMappingBootstrap('prod-metabase', {
+            driver: 'metabase',
+            mappings: { databaseMappings: { abc: 'warehouse' } },
+        })).toThrow(/databaseMappings key "abc" must be a positive integer string/);
+    });
+    it('parses Looker connection mapping intent', () => {
+        const bootstrap = parseLookerMappingBootstrap('prod-looker', {
+            driver: 'looker',
+            mappings: {
+                connectionMappings: {
+                    bigquery_prod: 'prod-warehouse',
+                    snowflake_dev: null,
+                },
+            },
+        });
+        expect(bootstrap).toEqual({
+            adapter: 'looker',
+            connectionId: 'prod-looker',
+            connectionMappings: {
+                bigquery_prod: 'prod-warehouse',
+                snowflake_dev: null,
+            },
+        });
+    });
+    it('parses LookML expected connection from mappings block', () => {
+        expect(parseLookmlMappingBootstrap('prod-lookml', {
+            driver: 'lookml',
+            repo_url: 'https://github.com/acme/looker.git',
+            mappings: { expectedLookerConnectionName: 'bigquery_prod' },
+        })).toEqual({
+            adapter: 'lookml',
+            connectionId: 'prod-lookml',
+            expectedLookerConnectionName: 'bigquery_prod',
+        });
+    });
+    it('dispatches by flat driver and returns null for connections with no mappings block', () => {
+        expect(parseConnectionMappingBootstrap('warehouse', { driver: 'postgres', url: 'env:DATABASE_URL' })).toBeNull();
+        expect(parseConnectionMappingBootstrap('prod-looker', {
+            driver: 'looker',
+            mappings: { connectionMappings: { analytics: 'prod-warehouse' } },
+        })).toMatchObject({ adapter: 'looker', connectionId: 'prod-looker' });
+    });
+});

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

@@ -0,0 +1,30 @@
+import { GitService, type KtxCoreConfig, type KtxLogger } from '../core/index.js';
+import type { KtxProjectConfig } from './config.js';
+import { LocalGitFileStore } from './local-git-file-store.js';
+export interface InitKtxProjectOptions {
+    projectDir: string;
+    projectName?: string;
+    force?: boolean;
+    authorName?: string;
+    authorEmail?: string;
+    logger?: KtxLogger;
+}
+export interface LoadKtxProjectOptions {
+    projectDir: string;
+    authorName?: string;
+    authorEmail?: string;
+    logger?: KtxLogger;
+}
+export interface KtxLocalProject {
+    projectDir: string;
+    configPath: string;
+    config: KtxProjectConfig;
+    coreConfig: KtxCoreConfig;
+    git: GitService;
+    fileStore: LocalGitFileStore;
+}
+export interface InitKtxProjectResult extends KtxLocalProject {
+    commitHash: string | null;
+}
+export declare function initKtxProject(options: InitKtxProjectOptions): Promise<InitKtxProjectResult>;
+export declare function loadKtxProject(options: LoadKtxProjectOptions): Promise<KtxLocalProject>;

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

@@ -0,0 +1,90 @@
+import { promises as fs } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { GitService, noopLogger } from '../core/index.js';
+import { buildDefaultKtxProjectConfig, parseKtxProjectConfig, serializeKtxProjectConfig } from './config.js';
+import { LocalGitFileStore } from './local-git-file-store.js';
+const TRACKED_SCAFFOLD_FILES = [
+    { path: '.ktx/.gitignore', content: 'cache/\ndb.sqlite\nsecrets/\nsetup/\nagents/\n' },
+    { path: '.ktx/prompts/.gitkeep', content: '' },
+    { path: '.ktx/skills/.gitkeep', content: '' },
+    { path: 'knowledge/global/.gitkeep', content: '' },
+    { path: 'semantic-layer/.gitkeep', content: '' },
+    { path: 'raw-sources/.gitkeep', content: '' },
+];
+function createCoreConfig(projectDir, authorName, authorEmail) {
+    return {
+        storage: {
+            configDir: projectDir,
+            homeDir: dirname(projectDir),
+            worktreesDir: join(projectDir, '.ktx/worktrees'),
+        },
+        git: {
+            userName: authorName,
+            userEmail: authorEmail,
+            bootstrapMessage: 'Initialize ktx project repository',
+            bootstrapAuthor: authorName,
+            bootstrapAuthorEmail: authorEmail,
+        },
+    };
+}
+async function fileExists(path) {
+    try {
+        await fs.access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeProjectFile(projectDir, relativePath, content) {
+    const absolutePath = join(projectDir, relativePath);
+    await fs.mkdir(dirname(absolutePath), { recursive: true });
+    await fs.writeFile(absolutePath, content, 'utf-8');
+}
+async function createRuntime(projectDir, config, authorName, authorEmail, logger) {
+    const coreConfig = createCoreConfig(projectDir, authorName, authorEmail);
+    const git = new GitService(coreConfig, logger);
+    await git.onModuleInit();
+    return {
+        projectDir,
+        configPath: join(projectDir, 'ktx.yaml'),
+        config,
+        coreConfig,
+        git,
+        fileStore: new LocalGitFileStore({ rootDir: projectDir, git }),
+    };
+}
+export async function initKtxProject(options) {
+    const projectDir = resolve(options.projectDir);
+    const projectName = options.projectName?.trim() || basename(projectDir) || 'ktx-project';
+    const authorName = options.authorName ?? 'ktx';
+    const authorEmail = options.authorEmail ?? 'ktx@example.com';
+    const logger = options.logger ?? noopLogger;
+    const configPath = join(projectDir, 'ktx.yaml');
+    await fs.mkdir(projectDir, { recursive: true });
+    if (!options.force && (await fileExists(configPath))) {
+        throw new Error(`Project already contains ktx.yaml: ${configPath}`);
+    }
+    const config = buildDefaultKtxProjectConfig(projectName);
+    const runtime = await createRuntime(projectDir, config, authorName, authorEmail, logger);
+    await writeProjectFile(projectDir, 'ktx.yaml', serializeKtxProjectConfig(config));
+    await fs.mkdir(join(projectDir, '.ktx/cache'), { recursive: true });
+    for (const file of TRACKED_SCAFFOLD_FILES) {
+        await writeProjectFile(projectDir, file.path, file.content);
+    }
+    const commit = await runtime.git.commitFiles(['ktx.yaml', ...TRACKED_SCAFFOLD_FILES.map((file) => file.path)], `Initialize KTX project: ${projectName}`, authorName, authorEmail);
+    return {
+        ...runtime,
+        commitHash: commit.commitHash,
+    };
+}
+export async function loadKtxProject(options) {
+    const projectDir = resolve(options.projectDir);
+    const authorName = options.authorName ?? 'ktx';
+    const authorEmail = options.authorEmail ?? 'ktx@example.com';
+    const logger = options.logger ?? noopLogger;
+    const configPath = join(projectDir, 'ktx.yaml');
+    const raw = await fs.readFile(configPath, 'utf-8');
+    const config = parseKtxProjectConfig(raw);
+    return createRuntime(projectDir, config, authorName, authorEmail, logger);
+}

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

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

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

@@ -0,0 +1,58 @@
+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 { initKtxProject, loadKtxProject } from './project.js';
+describe('KTX local project runtime', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-project-runtime-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('initializes the standalone project layout and commits it', async () => {
+        const projectDir = join(tempDir, 'warehouse');
+        const result = await initKtxProject({
+            projectDir,
+            projectName: 'warehouse',
+            authorName: 'Agent',
+            authorEmail: 'agent@example.com',
+        });
+        expect(result.projectDir).toBe(projectDir);
+        expect(result.config.project).toBe('warehouse');
+        expect(result.commitHash).toMatch(/^[0-9a-f]{40}$/);
+        await expect(readFile(join(projectDir, 'ktx.yaml'), 'utf-8')).resolves.toContain('project: warehouse');
+        const gitignore = await readFile(join(projectDir, '.ktx/.gitignore'), 'utf-8');
+        expect(gitignore).toContain('cache/');
+        expect(gitignore).toContain('db.sqlite');
+        expect(gitignore).toContain('secrets/');
+        expect(gitignore).toContain('setup/');
+        expect(gitignore).toContain('agents/');
+        await expect(stat(join(projectDir, 'knowledge/global/.gitkeep'))).resolves.toBeDefined();
+        await expect(stat(join(projectDir, 'semantic-layer/.gitkeep'))).resolves.toBeDefined();
+        await expect(stat(join(projectDir, '_schema/.gitkeep'))).rejects.toMatchObject({ code: 'ENOENT' });
+        await expect(stat(join(projectDir, 'raw-sources/.gitkeep'))).resolves.toBeDefined();
+        await expect(stat(join(projectDir, '.git'))).resolves.toBeDefined();
+    });
+    it('loads an initialized project with a working file store', async () => {
+        const projectDir = join(tempDir, 'warehouse');
+        await initKtxProject({ projectDir, projectName: 'warehouse' });
+        const loaded = await loadKtxProject({ projectDir });
+        await loaded.fileStore.writeFile('knowledge/global/revenue.md', '# Revenue\n', 'Agent', 'agent@example.com', 'Add revenue page');
+        expect(loaded.config.project).toBe('warehouse');
+        await expect(loaded.fileStore.readFile('knowledge/global/revenue.md')).resolves.toMatchObject({
+            content: '# Revenue\n',
+        });
+    });
+    it('rejects reinitializing an existing project unless force is set', async () => {
+        const projectDir = join(tempDir, 'warehouse');
+        await initKtxProject({ projectDir, projectName: 'warehouse' });
+        await expect(initKtxProject({ projectDir, projectName: 'warehouse' })).rejects.toThrow('Project already contains ktx.yaml');
+        await expect(initKtxProject({ projectDir, projectName: 'warehouse-v2', force: true })).resolves.toMatchObject({
+            config: {
+                project: 'warehouse-v2',
+            },
+        });
+    });
+});

package/node_modules/@ktx/context/dist/project/setup-config.d.ts

@@ -0,0 +1,8 @@
+import type { KtxProjectConfig } from './config.js';
+export declare const KTX_SETUP_STEPS: readonly ["project", "llm", "embeddings", "databases", "sources", "context", "agents"];
+export type KtxSetupStep = (typeof KTX_SETUP_STEPS)[number];
+export declare function markKtxSetupStepComplete(config: KtxProjectConfig, step: KtxSetupStep): KtxProjectConfig;
+export declare function setKtxSetupDatabaseConnectionIds(config: KtxProjectConfig, connectionIds: string[], options?: {
+    complete?: boolean;
+}): KtxProjectConfig;
+export declare function mergeKtxSetupGitignoreEntries(content: string): string;

package/node_modules/@ktx/context/dist/project/setup-config.js

@@ -0,0 +1,41 @@
+export const KTX_SETUP_STEPS = ['project', 'llm', 'embeddings', 'databases', 'sources', 'context', 'agents'];
+const SETUP_GITIGNORE_ENTRIES = ['secrets/', 'setup/', 'agents/'];
+export function markKtxSetupStepComplete(config, step) {
+    const databaseConnectionIds = config.setup?.database_connection_ids ?? [];
+    const completedSteps = config.setup?.completed_steps ?? [];
+    return {
+        ...config,
+        setup: {
+            database_connection_ids: [...databaseConnectionIds],
+            completed_steps: completedSteps.includes(step) ? [...completedSteps] : [...completedSteps, step],
+        },
+    };
+}
+export function setKtxSetupDatabaseConnectionIds(config, connectionIds, options = {}) {
+    const uniqueConnectionIds = [...new Set(connectionIds.filter((connectionId) => connectionId.trim().length > 0))];
+    const completedSteps = config.setup?.completed_steps ?? [];
+    const nextCompletedSteps = options.complete === true && !completedSteps.includes('databases')
+        ? [...completedSteps, 'databases']
+        : [...completedSteps];
+    return {
+        ...config,
+        setup: {
+            database_connection_ids: uniqueConnectionIds,
+            completed_steps: nextCompletedSteps,
+        },
+    };
+}
+export function mergeKtxSetupGitignoreEntries(content) {
+    const lines = content
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line, index, all) => line.length > 0 || index < all.length - 1);
+    const existing = new Set(lines);
+    for (const entry of SETUP_GITIGNORE_ENTRIES) {
+        if (!existing.has(entry)) {
+            lines.push(entry);
+            existing.add(entry);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}

package/node_modules/@ktx/context/dist/project/setup-config.test.d.ts

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

package/node_modules/@ktx/context/dist/project/setup-config.test.js

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { buildDefaultKtxProjectConfig } from './config.js';
+import { markKtxSetupStepComplete, mergeKtxSetupGitignoreEntries, setKtxSetupDatabaseConnectionIds, } from './setup-config.js';
+describe('KTX setup config helpers', () => {
+    it('marks setup steps complete without duplicating existing state', () => {
+        const config = buildDefaultKtxProjectConfig('warehouse');
+        const withProject = markKtxSetupStepComplete(config, 'project');
+        const withProjectAgain = markKtxSetupStepComplete(withProject, 'project');
+        const withLlm = markKtxSetupStepComplete(withProjectAgain, 'llm');
+        const withContext = markKtxSetupStepComplete(withLlm, 'context');
+        expect(withProject.setup).toEqual({
+            database_connection_ids: [],
+            completed_steps: ['project'],
+        });
+        expect(withProjectAgain.setup?.completed_steps).toEqual(['project']);
+        expect(withLlm.setup?.completed_steps).toEqual(['project', 'llm']);
+        expect(withContext.setup?.completed_steps).toEqual(['project', 'llm', 'context']);
+        expect(config.setup).toBeUndefined();
+    });
+    it('preserves database connection ids while marking a step complete', () => {
+        const config = {
+            ...buildDefaultKtxProjectConfig('warehouse'),
+            setup: {
+                database_connection_ids: ['warehouse'],
+                completed_steps: ['databases'],
+            },
+        };
+        expect(markKtxSetupStepComplete(config, 'project').setup).toEqual({
+            database_connection_ids: ['warehouse'],
+            completed_steps: ['databases', 'project'],
+        });
+    });
+    it('sets setup database connection ids without duplicates', () => {
+        const config = buildDefaultKtxProjectConfig('warehouse');
+        const withDatabases = setKtxSetupDatabaseConnectionIds(config, ['warehouse', 'analytics', 'warehouse']);
+        expect(withDatabases.setup).toEqual({
+            database_connection_ids: ['warehouse', 'analytics'],
+            completed_steps: [],
+        });
+        expect(config.setup).toBeUndefined();
+    });
+    it('marks databases complete only when requested', () => {
+        const config = markKtxSetupStepComplete(buildDefaultKtxProjectConfig('warehouse'), 'project');
+        const withDatabases = setKtxSetupDatabaseConnectionIds(config, ['warehouse'], { complete: true });
+        const withDatabasesAgain = setKtxSetupDatabaseConnectionIds(withDatabases, ['warehouse'], { complete: true });
+        expect(withDatabases.setup).toEqual({
+            database_connection_ids: ['warehouse'],
+            completed_steps: ['project', 'databases'],
+        });
+        expect(withDatabasesAgain.setup).toEqual(withDatabases.setup);
+    });
+    it('merges setup-local gitignore entries without removing existing lines', () => {
+        expect(mergeKtxSetupGitignoreEntries('cache/\ndb.sqlite\n')).toBe(['cache/', 'db.sqlite', 'secrets/', 'setup/', 'agents/', ''].join('\n'));
+        expect(mergeKtxSetupGitignoreEntries('cache/\nsecrets/\n')).toBe(['cache/', 'secrets/', 'setup/', 'agents/', ''].join('\n'));
+    });
+});

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

@@ -0,0 +1,2 @@
+export type { PromptContext, PromptServiceOptions } from './prompt.service.js';
+export { PromptService } from './prompt.service.js';

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

@@ -0,0 +1 @@
+export { PromptService } from './prompt.service.js';

package/node_modules/@ktx/context/dist/prompts/prompt.service.d.ts

@@ -0,0 +1,28 @@
+import { type KtxLogger } from '../core/index.js';
+export interface PromptContext {
+    current_date?: string;
+    business_rules?: string;
+    datasource_description?: string;
+    tables_and_columns_summary?: string;
+    metadata?: string;
+    settings?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface PromptServiceOptions {
+    promptsDir: string;
+    additionalPromptDirs?: string[];
+    defaultSettings?: Record<string, unknown>;
+    partials?: string[];
+    logger?: KtxLogger;
+}
+export declare class PromptService {
+    private readonly options;
+    private readonly logger;
+    private readonly partials;
+    private partialsRegistered;
+    constructor(options: PromptServiceOptions);
+    private promptDirs;
+    private ensurePartials;
+    loadPrompt(promptName: string, extension?: string): Promise<string>;
+    formatPrompt(promptName: string, context: PromptContext): Promise<string>;
+}

package/node_modules/@ktx/context/dist/prompts/prompt.service.js

@@ -0,0 +1,84 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import Handlebars from 'handlebars';
+import { noopLogger } from '../core/index.js';
+export class PromptService {
+    options;
+    logger;
+    partials;
+    partialsRegistered = false;
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger ?? noopLogger;
+        this.partials = options.partials ?? ['clinical_policy'];
+        Handlebars.registerHelper('eq', (a, b) => a === b);
+        Handlebars.registerHelper('json', (context) => JSON.stringify(context, null, 2));
+        Handlebars.registerHelper('truncate', (str, len) => typeof str === 'string' && str.length > len ? `${str.substring(0, len)}...` : str);
+        Handlebars.registerHelper('addOne', (index) => index + 1);
+        this.logger.log(`Prompt service initialized with directory: ${options.promptsDir}`);
+    }
+    promptDirs() {
+        return [this.options.promptsDir, ...(this.options.additionalPromptDirs ?? [])];
+    }
+    async ensurePartials() {
+        if (this.partialsRegistered) {
+            return;
+        }
+        for (const name of this.partials) {
+            let registered = false;
+            for (const promptsDir of this.promptDirs()) {
+                try {
+                    const content = await readFile(join(promptsDir, `${name}.md`), 'utf-8');
+                    Handlebars.registerPartial(name, content);
+                    registered = true;
+                    break;
+                }
+                catch { }
+            }
+            if (!registered) {
+                this.logger.warn(`Could not register ${name} partial`);
+            }
+        }
+        this.partialsRegistered = true;
+    }
+    async loadPrompt(promptName, extension = 'md') {
+        const tried = [];
+        for (const promptsDir of this.promptDirs()) {
+            const promptFile = join(promptsDir, `${promptName}.${extension}`);
+            tried.push(promptFile);
+            try {
+                const content = await readFile(promptFile, 'utf-8');
+                this.logger.debug(`Loaded prompt template: ${promptName}.${extension}`);
+                return content;
+            }
+            catch { }
+        }
+        const paths = tried.join(', ');
+        this.logger.error(`Prompt file not found: ${paths}`);
+        throw new Error(`Prompt file not found in any configured directory: ${paths}`);
+    }
+    async formatPrompt(promptName, context) {
+        await this.ensurePartials();
+        try {
+            const fullContext = {
+                current_date: context.current_date || new Date().toISOString().split('T')[0],
+                business_rules: context.business_rules || '',
+                ...context,
+                settings: {
+                    ...this.options.defaultSettings,
+                    ...context.settings,
+                },
+            };
+            const templateSource = await this.loadPrompt(promptName);
+            const template = Handlebars.compile(templateSource, { noEscape: true });
+            const rendered = template(fullContext);
+            this.logger.debug(`Formatted prompt: ${promptName} (${rendered.length} chars)`);
+            return rendered;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error(`Error formatting prompt ${promptName}: ${errorMessage}`);
+            throw new Error(`Failed to format prompt ${promptName}: ${errorMessage}`);
+        }
+    }
+}

package/node_modules/@ktx/context/dist/prompts/prompt.service.test.d.ts

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

package/node_modules/@ktx/context/dist/prompts/prompt.service.test.js

@@ -0,0 +1,43 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { PromptService } from './prompt.service.js';
+describe('PromptService', () => {
+    let dir;
+    beforeEach(async () => {
+        dir = await mkdtemp(join(tmpdir(), 'ktx-prompts-'));
+    });
+    afterEach(async () => {
+        await rm(dir, { recursive: true, force: true });
+    });
+    it('loads prompt files from the configured prompt directory', async () => {
+        await writeFile(join(dir, 'hello.md'), 'Hello {{name}}', 'utf-8');
+        const service = new PromptService({ promptsDir: dir, partials: [] });
+        await expect(service.loadPrompt('hello')).resolves.toBe('Hello {{name}}');
+    });
+    it('loads prompts from additional directories when the primary directory misses', async () => {
+        const extraDir = await mkdtemp(join(tmpdir(), 'ktx-prompts-extra-'));
+        try {
+            await writeFile(join(extraDir, 'memory_agent_research.md'), '<role>Packaged memory prompt</role>', 'utf-8');
+            const service = new PromptService({ promptsDir: dir, additionalPromptDirs: [extraDir], partials: [] });
+            await expect(service.loadPrompt('memory_agent_research')).resolves.toBe('<role>Packaged memory prompt</role>');
+        }
+        finally {
+            await rm(extraDir, { recursive: true, force: true });
+        }
+    });
+    it('formats prompts with default settings and context settings', async () => {
+        await writeFile(join(dir, 'settings.md'), '{{settings.flag}} {{settings.mode}} {{name}}', 'utf-8');
+        const service = new PromptService({
+            promptsDir: dir,
+            partials: [],
+            defaultSettings: { flag: true, mode: 'default' },
+        });
+        const rendered = await service.formatPrompt('settings', {
+            name: 'Ada',
+            settings: { mode: 'override' },
+        });
+        expect(rendered).toBe('true override Ada');
+    });
+});

package/node_modules/@ktx/context/dist/scan/credentials.d.ts

@@ -0,0 +1,8 @@
+import { REDACTED_KTX_CREDENTIAL_VALUE } from '../core/redaction.js';
+import type { KtxCredentialEnvelope, KtxScanReport, KtxScanWarning } from './types.js';
+export { REDACTED_KTX_CREDENTIAL_VALUE };
+export declare function redactKtxCredentialValue(key: string, value: unknown): unknown;
+export declare function redactKtxScanMetadata(metadata: Record<string, unknown>): Record<string, unknown>;
+export declare function redactKtxCredentialEnvelope(envelope: KtxCredentialEnvelope): KtxCredentialEnvelope;
+export declare function redactKtxScanWarning(warning: KtxScanWarning): KtxScanWarning;
+export declare function redactKtxScanReport(report: KtxScanReport): KtxScanReport;