@kaelio/ktx 0.1.0-rc.5 → 0.1.0

package/dist/public-ingest.test.js

@@ -575,6 +575,42 @@ describe('runKtxPublicIngest', () => {
         }), io.io);
         expect(runScan).not.toHaveBeenCalled();
     });
+    it('preflights foreground query-history runtime before starting the context-build view', async () => {
+        const io = makeIo({ isTTY: true, interactive: true });
+        const calls = [];
+        const project = projectWithConnections({
+            warehouse: { driver: 'postgres', context: { depth: 'deep' } },
+        });
+        const ensureRuntime = vi.fn(async () => {
+            calls.push('runtime');
+            return {};
+        });
+        const runContextBuild = vi.fn(async () => {
+            calls.push('context-build');
+            return { exitCode: 0 };
+        });
+        await expect(runKtxPublicIngest({
+            command: 'run',
+            projectDir: '/tmp/project',
+            targetConnectionId: 'warehouse',
+            all: false,
+            json: false,
+            inputMode: 'auto',
+            queryHistory: 'enabled',
+            cliVersion: '0.2.0',
+            runtimeInstallPolicy: 'prompt',
+        }, io.io, {
+            loadProject: vi.fn(async () => project),
+            ensureRuntime,
+            runContextBuild,
+        })).resolves.toBe(0);
+        expect(calls).toEqual(['runtime', 'context-build']);
+        expect(ensureRuntime).toHaveBeenCalledWith(expect.objectContaining({
+            cliVersion: '0.2.0',
+            installPolicy: 'prompt',
+            feature: 'core',
+        }));
+    });
     it('runs all independent targets and reports partial failures', async () => {
         const io = makeIo();
         const project = projectWithConnections({
@@ -616,7 +652,10 @@ describe('runKtxPublicIngest', () => {
             warehouse: { driver: 'postgres', context: { depth: 'deep' } },
         });
         const runScan = vi.fn(async () => 0);
-        const runIngest = vi.fn(async () => 1);
+        const runIngest = vi.fn(async (_args, ingestIo) => {
+            ingestIo.stdout.write('Error: Query history failed for 60 tasks. First failure: Google Cloud authentication failed while analyzing query history: application-default credentials expired or require reauthentication (invalid_grant / invalid_rapt). Run `gcloud auth application-default login`, then retry.\n');
+            return 1;
+        });
         await expect(runKtxPublicIngest({
             command: 'run',
             projectDir: '/tmp/project',
@@ -626,10 +665,38 @@ describe('runKtxPublicIngest', () => {
             inputMode: 'disabled',
             queryHistory: 'enabled',
         }, io.io, { loadProject: vi.fn(async () => project), runScan, runIngest })).resolves.toBe(1);
-        expect(io.stdout()).toContain('warehouse failed at query-history.');
+        expect(io.stdout()).toMatch(/warehouse\s+done\s+failed\s+skipped\s+skipped/);
+        expect(io.stdout()).toContain('warehouse failed: Query history failed for 60 tasks. First failure: Google Cloud authentication failed while analyzing query history');
+        expect(io.stdout()).not.toContain('warehouse failed: Error:');
         expect(io.stdout()).toContain('Retry: ktx ingest warehouse --project-dir /tmp/project --deep --query-history');
         expect(io.stdout()).not.toContain('historic-sql');
     });
+    it('prints the runtime artifact build hint for missing query-history runtime assets', async () => {
+        const io = makeIo();
+        const project = deepReadyProject({
+            warehouse: { driver: 'postgres', context: { depth: 'deep' } },
+        });
+        const runScan = vi.fn(async () => 0);
+        const runIngest = vi.fn(async (_args, ingestIo) => {
+            ingestIo.stderr.write('Missing bundled Python runtime manifest: /repo/packages/cli/assets/python/manifest.json\n');
+            ingestIo.stderr.write('In a source checkout, build the local runtime assets with: pnpm run artifacts:build\n');
+            ingestIo.stderr.write('Then retry the runtime-backed KTX command.\n');
+            return 1;
+        });
+        await expect(runKtxPublicIngest({
+            command: 'run',
+            projectDir: '/tmp/project',
+            targetConnectionId: 'warehouse',
+            all: false,
+            json: false,
+            inputMode: 'disabled',
+            queryHistory: 'enabled',
+        }, io.io, { loadProject: vi.fn(async () => project), runScan, runIngest })).resolves.toBe(1);
+        expect(io.stdout()).toContain('Missing bundled Python runtime manifest');
+        expect(io.stdout()).toContain('In a source checkout, build the local runtime assets with: pnpm run artifacts:build');
+        expect(io.stdout()).toContain('Retry: ktx ingest warehouse --project-dir /tmp/project --deep --query-history');
+        expect(io.stdout()).not.toContain('Then retry the runtime-backed KTX command');
+    });
     it('fails deep-readiness targets before work starts while continuing independent --all targets', async () => {
         const io = makeIo();
         const project = projectWithConnections({

package/dist/release-version.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveKtxRuntimeVersion(input: {
+    packageName: string;
+    packageVersion: string;
+    startDir?: string;
+}): string;

package/dist/release-version.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertReleaseVersion(value, source) {
+    if (typeof value !== 'string' || !semverPattern.test(value)) {
+        throw new Error(`Invalid KTX release version in ${source}`);
+    }
+    return value;
+}
+function findReleasePolicyPath(startDir) {
+    let current = startDir;
+    const root = parse(current).root;
+    while (true) {
+        const candidate = join(current, 'release-policy.json');
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        if (current === root) {
+            return undefined;
+        }
+        current = dirname(current);
+    }
+}
+function readSourceReleaseVersion(startDir = dirname(fileURLToPath(import.meta.url))) {
+    const policyPath = findReleasePolicyPath(startDir);
+    if (!policyPath) {
+        return undefined;
+    }
+    const policy = JSON.parse(readFileSync(policyPath, 'utf8'));
+    if (!isPlainObject(policy)) {
+        throw new Error(`Invalid KTX release policy: ${policyPath}`);
+    }
+    return assertReleaseVersion(policy.publicNpmPackageVersion, policyPath);
+}
+export function resolveKtxRuntimeVersion(input) {
+    if (input.packageName === '@kaelio/ktx') {
+        return assertReleaseVersion(input.packageVersion, `${input.packageName}/package.json`);
+    }
+    return readSourceReleaseVersion(input.startDir) ?? input.packageVersion;
+}

package/dist/runtime-requirements.d.ts

@@ -0,0 +1,23 @@
+import type { KtxProjectConfig } from '@ktx/context/project';
+import type { KtxRuntimeFeature } from './managed-python-runtime.js';
+import type { KtxPublicIngestPlan } from './public-ingest.js';
+type KtxRuntimeRequirementReason = 'query-history' | 'looker-source' | 'database-introspection' | 'local-embeddings';
+interface KtxRuntimeRequirement {
+    feature: KtxRuntimeFeature;
+    reason: KtxRuntimeRequirementReason;
+    detail: string;
+}
+export interface KtxRuntimeRequirements {
+    features: KtxRuntimeFeature[];
+    requirements: KtxRuntimeRequirement[];
+}
+export interface KtxProjectRuntimeRequirementOptions {
+    databaseIntrospectionFallback?: boolean;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+}
+export interface KtxPublicIngestRuntimeRequirementOptions {
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+}
+export declare function resolveProjectRuntimeRequirements(config: KtxProjectConfig, options?: KtxProjectRuntimeRequirementOptions): KtxRuntimeRequirements;
+export declare function resolvePublicIngestRuntimeRequirements(plan: KtxPublicIngestPlan, options?: KtxPublicIngestRuntimeRequirementOptions): KtxRuntimeRequirements;
+export {};

package/dist/runtime-requirements.js

@@ -0,0 +1,99 @@
+import { MANAGED_SENTENCE_TRANSFORMERS_BASE_URL } from '@ktx/context';
+function normalizeDriver(driver) {
+    return String(driver ?? '').trim().toLowerCase();
+}
+function recordValue(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+function hasEnabledQueryHistory(connection) {
+    const context = recordValue(recordValue(connection).context);
+    const queryHistory = recordValue(context.queryHistory);
+    return queryHistory.enabled === true;
+}
+function hasDaemonOverride(env) {
+    return typeof env.KTX_DAEMON_URL === 'string' && env.KTX_DAEMON_URL.trim().length > 0;
+}
+function hasSqlAnalysisOverride(env) {
+    return ((typeof env.KTX_SQL_ANALYSIS_URL === 'string' && env.KTX_SQL_ANALYSIS_URL.trim().length > 0) ||
+        hasDaemonOverride(env));
+}
+function requiresManagedLocalEmbeddings(embeddings) {
+    if (embeddings.backend !== 'sentence-transformers') {
+        return false;
+    }
+    const baseUrl = embeddings.sentenceTransformers?.base_url;
+    return baseUrl === undefined || baseUrl === '' || baseUrl === MANAGED_SENTENCE_TRANSFORMERS_BASE_URL;
+}
+function uniqueRequirements(requirements) {
+    const seen = new Set();
+    const deduped = [];
+    for (const requirement of requirements) {
+        const key = `${requirement.feature}:${requirement.reason}:${requirement.detail}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(requirement);
+    }
+    const features = [...new Set(deduped.map((requirement) => requirement.feature))].sort((left, right) => left.localeCompare(right));
+    return { features, requirements: deduped };
+}
+export function resolveProjectRuntimeRequirements(config, options = {}) {
+    const env = options.env ?? process.env;
+    const requirements = [];
+    if (options.databaseIntrospectionFallback === true && !hasDaemonOverride(env)) {
+        requirements.push({
+            feature: 'core',
+            reason: 'database-introspection',
+            detail: 'Database introspection fallback uses the Python daemon.',
+        });
+    }
+    for (const [connectionId, connection] of Object.entries(config.connections)) {
+        const driver = normalizeDriver(connection.driver);
+        if ((driver === 'looker' || driver === 'local_looker') && !hasDaemonOverride(env)) {
+            requirements.push({
+                feature: 'core',
+                reason: 'looker-source',
+                detail: `${connectionId} uses Looker identifier parsing.`,
+            });
+        }
+        if (hasEnabledQueryHistory(connection) && !hasSqlAnalysisOverride(env)) {
+            requirements.push({
+                feature: 'core',
+                reason: 'query-history',
+                detail: `${connectionId} has query history enabled.`,
+            });
+        }
+    }
+    if (requiresManagedLocalEmbeddings(config.ingest.embeddings)) {
+        requirements.push({
+            feature: 'local-embeddings',
+            reason: 'local-embeddings',
+            detail: 'Local sentence-transformers embeddings use the managed Python runtime.',
+        });
+    }
+    return uniqueRequirements(requirements);
+}
+export function resolvePublicIngestRuntimeRequirements(plan, options = {}) {
+    const env = options.env ?? process.env;
+    const requirements = [];
+    for (const target of plan.targets) {
+        const driver = normalizeDriver(target.driver);
+        const adapter = normalizeDriver(target.adapter);
+        if (target.queryHistory?.enabled === true && !hasSqlAnalysisOverride(env)) {
+            requirements.push({
+                feature: 'core',
+                reason: 'query-history',
+                detail: `${target.connectionId} query-history ingest uses SQL analysis.`,
+            });
+        }
+        if ((driver === 'looker' || driver === 'local_looker' || adapter === 'looker') && !hasDaemonOverride(env)) {
+            requirements.push({
+                feature: 'core',
+                reason: 'looker-source',
+                detail: `${target.connectionId} uses Looker identifier parsing.`,
+            });
+        }
+    }
+    return uniqueRequirements(requirements);
+}

package/dist/runtime-requirements.test.d.ts

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

package/dist/runtime-requirements.test.js

@@ -0,0 +1,63 @@
+import { MANAGED_SENTENCE_TRANSFORMERS_BASE_URL } from '@ktx/context';
+import { buildDefaultKtxProjectConfig } from '@ktx/context/project';
+import { describe, expect, it } from 'vitest';
+import { resolveProjectRuntimeRequirements, resolvePublicIngestRuntimeRequirements, } from './runtime-requirements.js';
+describe('runtime requirement detection', () => {
+    it('does not require runtime for agent/MCP setup alone', () => {
+        const config = buildDefaultKtxProjectConfig();
+        expect(resolveProjectRuntimeRequirements(config).features).toEqual([]);
+    });
+    it('requires core for Looker source ingest unless an external daemon is configured', () => {
+        const config = {
+            ...buildDefaultKtxProjectConfig(),
+            connections: {
+                looker: { driver: 'looker', base_url: 'https://looker.example.com', client_id: 'client-id' },
+            },
+        };
+        expect(resolveProjectRuntimeRequirements(config).features).toEqual(['core']);
+        expect(resolveProjectRuntimeRequirements(config, { env: { KTX_DAEMON_URL: 'http://127.0.0.1:8765' } }).features).toEqual([]);
+    });
+    it('requires core for query-history ingest unless SQL analysis is externally configured', () => {
+        const config = {
+            ...buildDefaultKtxProjectConfig(),
+            connections: {
+                warehouse: { driver: 'postgres', context: { queryHistory: { enabled: true } } },
+            },
+        };
+        expect(resolveProjectRuntimeRequirements(config).features).toEqual(['core']);
+        expect(resolveProjectRuntimeRequirements(config, { env: { KTX_SQL_ANALYSIS_URL: 'http://127.0.0.1:8765' } }).features).toEqual([]);
+    });
+    it('requires local-embeddings for managed sentence-transformers embeddings', () => {
+        const config = {
+            ...buildDefaultKtxProjectConfig(),
+            ingest: {
+                ...buildDefaultKtxProjectConfig().ingest,
+                embeddings: {
+                    backend: 'sentence-transformers',
+                    model: 'all-MiniLM-L6-v2',
+                    dimensions: 384,
+                    sentenceTransformers: {
+                        base_url: MANAGED_SENTENCE_TRANSFORMERS_BASE_URL,
+                    },
+                },
+            },
+        };
+        expect(resolveProjectRuntimeRequirements(config).features).toEqual(['local-embeddings']);
+    });
+    it('detects foreground ingest runtime needs from selected query-history targets', () => {
+        expect(resolvePublicIngestRuntimeRequirements({
+            projectDir: '/tmp/project',
+            warnings: [],
+            targets: [
+                {
+                    connectionId: 'warehouse',
+                    driver: 'postgres',
+                    operation: 'database-ingest',
+                    debugCommand: 'ktx ingest warehouse --debug',
+                    steps: ['database-schema', 'query-history'],
+                    queryHistory: { enabled: true },
+                },
+            ],
+        }).features).toEqual(['core']);
+    });
+});

package/dist/setup-agents.d.ts

@@ -12,6 +12,7 @@ export interface KtxSetupAgentsArgs {
     scope: KtxAgentScope;
     mode: KtxAgentInstallMode;
     skipAgents: boolean;
+    showNextActions?: boolean;
 }
 export type KtxSetupAgentsResult = {
     status: 'ready';
@@ -21,6 +22,7 @@ export type KtxSetupAgentsResult = {
         scope: KtxAgentScope;
         mode: KtxAgentInstallMode;
     }>;
+    nextActions?: string;
 } | {
     status: 'skipped';
     projectDir: string;
@@ -46,7 +48,7 @@ export interface KtxAgentInstallManifest {
     entries: Array<{
         kind: 'file';
         path: string;
-        role?: 'skill' | 'rule' | 'analytics-skill' | 'claude-plugin' | 'launcher';
+        role?: 'skill' | 'rule' | 'analytics-skill' | 'claude-desktop-skill-bundle' | 'launcher';
     } | {
         kind: 'json-key';
         path: string;
@@ -54,6 +56,7 @@ export interface KtxAgentInstallManifest {
     }>;
 }
 type InstallEntry = KtxAgentInstallManifest['entries'][number];
+export declare function createAgentNextActionsLineFormatter(stdout: KtxCliIo['stdout']): (line: string) => string;
 export declare function collectClaudeDesktopForwardedEnv(source: NodeJS.ProcessEnv): Record<string, string>;
 export declare function agentInstallManifestPath(projectDir: string): string;
 export declare function plannedKtxAgentFiles(input: {
@@ -79,10 +82,15 @@ export interface KtxSetupAgentsPromptAdapter {
 export interface KtxSetupAgentsDeps {
     prompts?: KtxSetupAgentsPromptAdapter;
 }
-export declare function formatInstallSummary(installs: Array<{
+export declare function targetDisplayName(target: string): string;
+export interface InstallSummaryEntry {
+    title: string;
+    lines: string[];
+}
+export declare function formatInstallSummaryLines(installs: Array<{
     target: KtxAgentTarget;
     scope: KtxAgentScope;
     mode: KtxAgentInstallMode;
-}>, entries: InstallEntry[], projectDir: string): string;
+}>, entries: InstallEntry[], projectDir: string): InstallSummaryEntry[];
 export declare function runKtxSetupAgentsStep(args: KtxSetupAgentsArgs, io: KtxCliIo, deps?: KtxSetupAgentsDeps): Promise<KtxSetupAgentsResult>;
 export {};