@kaelio/ktx 0.5.0 → 0.7.0

package/dist/setup-embeddings.js

@@ -4,8 +4,9 @@ import { serializeKtxProjectConfig } from './context/project/config.js';
 import { loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete, readKtxSetupState } from './context/project/setup-config.js';
 import { runKtxEmbeddingHealthCheck } from './llm/embedding-health.js';
-import { createStaticCliSpinner } from './clack.js';
+import { createStaticCliSpinner, errorMessage, writePrefixedLines } from './clack.js';
 import { ensureManagedLocalEmbeddingsDaemon, managedLocalEmbeddingHealthConfig, } from './managed-local-embeddings.js';
+import { ManagedPythonDaemonStartError } from './managed-python-daemon.js';
 import { withTextInputNavigation } from './prompt-navigation.js';
 import { envCredentialReference, writeProjectLocalSecretReference } from './setup-secrets.js';
 import { createKtxSetupPromptAdapter, } from './setup-prompts.js';
@@ -305,7 +306,14 @@ export async function runKtxSetupEmbeddingsStep(args, io, deps = {}) {
                 });
             }
             catch (error) {
-                io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+                const write = (chunk) => io.stderr.write(chunk);
+                if (error instanceof ManagedPythonDaemonStartError) {
+                    const tail = await readLocalEmbeddingDaemonStderrTail(error.stderrLog);
+                    writePrefixedLines(write, localEmbeddingSetupMessage(error.detail, tail));
+                }
+                else {
+                    writePrefixedLines(write, errorMessage(error));
+                }
                 return { status: 'failed', projectDir: args.projectDir };
             }
         }

package/dist/setup-project.d.ts

@@ -10,19 +10,11 @@ export interface KtxSetupProjectArgs {
     yes: boolean;
     allowBack?: boolean;
 }
-export type KtxSetupCreatedProjectCleanup = {
-    kind: 'remove-project-dir';
-    projectDir: string;
-} | {
-    kind: 'remove-ktx-scaffold';
-    projectDir: string;
-};
 export type KtxSetupProjectResult = {
     status: 'ready';
     projectDir: string;
     project: KtxLocalProject;
     confirmedCreation?: boolean;
-    createdProjectCleanup?: KtxSetupCreatedProjectCleanup;
 } | {
     status: 'back';
     projectDir: string;

package/dist/setup-project.js

@@ -39,15 +39,6 @@ async function existingFolderState(projectDir) {
         throw error;
     }
 }
-function cleanupForFolderState(projectDir, state) {
-    if (state === 'missing') {
-        return { kind: 'remove-project-dir', projectDir };
-    }
-    if (state === 'empty-directory') {
-        return { kind: 'remove-ktx-scaffold', projectDir };
-    }
-    return undefined;
-}
 async function confirmProjectDir(selectedDir, io, prompts) {
     const state = await existingFolderState(selectedDir);
     if (state === 'not-directory') {
@@ -86,7 +77,7 @@ async function confirmProjectDir(selectedDir, io, prompts) {
         return { status: 'back' };
     if (action !== 'create')
         return { status: 'cancelled' };
-    return { status: 'confirmed', confirmedCreation: true, createdProjectCleanup: cleanupForFolderState(selectedDir, state) };
+    return { status: 'confirmed', confirmedCreation: true };
 }
 async function normalizeSetupGitignore(projectDir) {
     const gitignorePath = join(projectDir, '.ktx/.gitignore');
@@ -162,19 +153,9 @@ async function promptForNewProjectDir(projectDir, homeDir, io, prompts) {
             status: 'selected',
             projectDir: selectedDir,
             confirmedCreation: confirmed.confirmedCreation,
-            ...(confirmed.createdProjectCleanup ? { createdProjectCleanup: confirmed.createdProjectCleanup } : {}),
         };
     }
 }
-async function createProjectWithCleanup(projectDir, deps) {
-    const state = await existingFolderState(projectDir);
-    const project = await createProject(projectDir, deps);
-    const createdProjectCleanup = cleanupForFolderState(projectDir, state);
-    return {
-        project,
-        ...(createdProjectCleanup ? { createdProjectCleanup } : {}),
-    };
-}
 export async function runKtxSetupProjectStep(args, io, deps = {}) {
     const projectDir = resolve(args.projectDir);
     const homeDir = deps.homeDir ?? homedir();
@@ -203,7 +184,6 @@ export async function runKtxSetupProjectStep(args, io, deps = {}) {
             projectDir: selected.projectDir,
             project,
             confirmedCreation: selected.confirmedCreation,
-            ...(selected.createdProjectCleanup ? { createdProjectCleanup: selected.createdProjectCleanup } : {}),
         };
     }
     if (exists) {
@@ -216,13 +196,12 @@ export async function runKtxSetupProjectStep(args, io, deps = {}) {
             io.stderr.write('Missing setup choice: pass --yes to create a project in non-interactive setup.\n');
             return { status: 'missing-input', projectDir };
         }
-        const { project, createdProjectCleanup } = await createProjectWithCleanup(projectDir, deps);
+        const project = await createProject(projectDir, deps);
         printProjectSummary(io, projectDir);
         return {
             status: 'ready',
             projectDir,
             project,
-            ...(createdProjectCleanup ? { createdProjectCleanup } : {}),
         };
     }
     if (!io.stdout.isTTY && !deps.prompts) {
@@ -255,13 +234,12 @@ export async function runKtxSetupProjectStep(args, io, deps = {}) {
             return { status: 'cancelled', projectDir };
         }
         if (choice === 'current') {
-            const { project, createdProjectCleanup } = await createProjectWithCleanup(projectDir, deps);
+            const project = await createProject(projectDir, deps);
             printProjectSummary(io, projectDir);
             return {
                 status: 'ready',
                 projectDir,
                 project,
-                ...(createdProjectCleanup ? { createdProjectCleanup } : {}),
             };
         }
         if (choice === 'new-default') {
@@ -279,7 +257,6 @@ export async function runKtxSetupProjectStep(args, io, deps = {}) {
                 projectDir: defaultProjectDir,
                 project,
                 confirmedCreation: confirmed.confirmedCreation,
-                ...(confirmed.createdProjectCleanup ? { createdProjectCleanup: confirmed.createdProjectCleanup } : {}),
             };
         }
         if (choice === 'new-custom') {
@@ -309,7 +286,6 @@ export async function runKtxSetupProjectStep(args, io, deps = {}) {
                 projectDir: customDir,
                 project,
                 confirmedCreation: confirmed.confirmedCreation,
-                ...(confirmed.createdProjectCleanup ? { createdProjectCleanup: confirmed.createdProjectCleanup } : {}),
             };
         }
         prompts.cancel('Setup cancelled.');

package/dist/setup-runtime.js

@@ -1,5 +1,6 @@
 import { loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete } from './context/project/setup-config.js';
+import { errorMessage, writePrefixedLines } from './clack.js';
 import { ensureManagedLocalEmbeddingsDaemon, } from './managed-local-embeddings.js';
 import { ensureManagedPythonCommandRuntime, } from './managed-python-command.js';
 import { resolveProjectRuntimeRequirements, } from './runtime-requirements.js';
@@ -39,7 +40,7 @@ export async function runKtxSetupRuntimeStep(args, io, deps = {}) {
         }
     }
     catch (error) {
-        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        writePrefixedLines((chunk) => io.stderr.write(chunk), errorMessage(error));
         return { status: 'failed', projectDir: args.projectDir, requirements };
     }
     await markKtxSetupStateStepComplete(args.projectDir, 'runtime');

package/dist/setup-sources.js

@@ -16,6 +16,7 @@ import { parseMetricflowFiles } from './context/ingest/adapters/metricflow/deep-
 import { serializeKtxProjectConfig } from './context/project/config.js';
 import { loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete } from './context/project/setup-config.js';
+import { errorMessage, writePrefixedLines } from './clack.js';
 import { pickNotionRootPages } from './notion-page-picker.js';
 import { runKtxSourceMapping } from './source-mapping.js';
 import { withMultiselectNavigation, withTextInputNavigation } from './prompt-navigation.js';
@@ -1627,7 +1628,7 @@ export async function runKtxSetupSourcesStep(args, io, deps = {}) {
         }
     }
     catch (error) {
-        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        writePrefixedLines((chunk) => io.stderr.write(chunk), errorMessage(error));
         return { status: 'failed', projectDir: args.projectDir };
     }
 }

package/dist/setup.js

@@ -1,5 +1,4 @@
 import { existsSync } from 'node:fs';
-import { rm } from 'node:fs/promises';
 import { basename, join, resolve } from 'node:path';
 import { getLatestLocalIngestStatus } from './context/ingest/local-ingest.js';
 import { savedMemoryCountsForReport } from './context/ingest/reports.js';
@@ -16,13 +15,14 @@ import { readKtxAgentInstallManifest, runKtxSetupAgentsStep, targetDisplayName,
 import { runKtxSetupDatabasesStep, } from './setup-databases.js';
 import { runKtxSetupEmbeddingsStep } from './setup-embeddings.js';
 import { isKtxSetupLlmConfigReady, runKtxSetupAnthropicModelStep, } from './setup-models.js';
-import { runKtxSetupProjectStep, } from './setup-project.js';
+import { runKtxSetupProjectStep } from './setup-project.js';
 import { isKtxPreAgentSetupReady, isKtxSetupReady, runKtxSetupReadyChangeMenu, } from './setup-ready-menu.js';
 import { runKtxSetupSourcesStep } from './setup-sources.js';
 import { runKtxSetupRuntimeStep, } from './setup-runtime.js';
 import { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
 import { readKtxSetupContextState, runKtxSetupContextStep, setupContextStatusFromState, } from './setup-context.js';
 const SOURCE_DRIVERS = new Set(['dbt', 'metricflow', 'metabase', 'looker', 'lookml', 'notion']);
+const KTX_DOCS_URL = 'https://docs.kaelio.com/ktx';
 function createEntryMenuPromptAdapter() {
     return createKtxSetupPromptAdapter({
         selectCancelValue: 'exit',
@@ -305,17 +305,6 @@ async function commitSetupConfigChanges(projectDir) {
     const project = await loadKtxProject({ projectDir });
     await project.git.commitFile('ktx.yaml', 'setup: update KTX project config', 'ktx setup', 'setup@ktx.local');
 }
-const KTX_SETUP_SCAFFOLD_PATHS = ['ktx.yaml', '.ktx', 'wiki', 'semantic-layer', 'raw-sources', '.git'];
-async function cleanupCreatedProjectScaffold(cleanup) {
-    if (!cleanup) {
-        return;
-    }
-    if (cleanup.kind === 'remove-project-dir') {
-        await rm(cleanup.projectDir, { recursive: true, force: true });
-        return;
-    }
-    await Promise.all(KTX_SETUP_SCAFFOLD_PATHS.map((relativePath) => rm(join(cleanup.projectDir, relativePath), { recursive: true, force: true })));
-}
 export async function runKtxSetup(args, io, deps = {}) {
     try {
         return await runKtxSetupInner(args, io, deps);
@@ -330,6 +319,7 @@ export async function runKtxSetup(args, io, deps = {}) {
 async function runKtxSetupInner(args, io, deps = {}) {
     const setupUi = deps.setupUi ?? createKtxSetupUiAdapter();
     setupUi.intro('KTX setup', io);
+    setupUi.note(KTX_DOCS_URL, '📚 Docs', io);
     let entryAction;
     let projectResult;
     let agentNextActions;
@@ -400,6 +390,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
         const shouldRunContext = !agentOnlySetup && (!runOnly || runOnly === 'context');
         const shouldRunAgents = agentsRequested || !runOnly || runOnly === 'agents';
         const showPromptInstructions = projectResult.confirmedCreation !== true;
+        let skipSourcesFromDatabaseMenu = false;
         const setupSteps = agentOnlySetup
             ? []
             : ['models', 'embeddings', 'databases', 'sources', 'runtime', 'context'];
@@ -414,8 +405,9 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 return !args.skipEmbeddings && shouldRunEmbeddings;
             if (step === 'databases')
                 return !args.skipDatabases && shouldRunDatabases;
-            if (step === 'sources')
-                return args.skipSources !== true && shouldRunSources;
+            if (step === 'sources') {
+                return args.skipSources !== true && !skipSourcesFromDatabaseMenu && shouldRunSources;
+            }
             if (step === 'runtime')
                 return shouldRunRuntime;
             if (step === 'context')
@@ -472,7 +464,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
             else if (step === 'databases') {
                 const databasesRunner = deps.databases ??
                     ((databaseArgs, databaseIo) => runKtxSetupDatabasesStep(databaseArgs, databaseIo, deps.databasesDeps));
-                stepResult = await databasesRunner({
+                const databaseResult = await databasesRunner({
                     projectDir: projectResult.projectDir,
                     inputMode: args.inputMode,
                     ...(args.databaseDrivers ? { databaseDrivers: args.databaseDrivers } : {}),
@@ -494,6 +486,8 @@ async function runKtxSetupInner(args, io, deps = {}) {
                         : {}),
                     skipDatabases: args.skipDatabases || !shouldRunDatabases,
                 }, io);
+                skipSourcesFromDatabaseMenu = databaseResult.status === 'ready' && databaseResult.skipSources === true;
+                stepResult = databaseResult;
             }
             else if (step === 'sources') {
                 const sourcesRunner = deps.sources ?? ((sourceArgs, sourceIo) => runKtxSetupSourcesStep(sourceArgs, sourceIo, deps.sourcesDeps));
@@ -519,7 +513,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
                     ...(args.notionCrawlMode ? { notionCrawlMode: args.notionCrawlMode } : {}),
                     ...(args.notionRootPageIds ? { notionRootPageIds: args.notionRootPageIds } : {}),
                     runInitialSourceIngest: args.runInitialSourceIngest ?? false,
-                    skipSources: args.skipSources === true || !shouldRunSources,
+                    skipSources: args.skipSources === true || !shouldRunSources || skipSourcesFromDatabaseMenu,
                 }, io);
             }
             else if (step === 'runtime') {
@@ -573,7 +567,6 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 cliVersion: args.cliVersion,
             });
             if (stepResult.status === 'failed') {
-                await cleanupCreatedProjectScaffold(projectResult.createdProjectCleanup);
                 return 1;
             }
             if (stepResult.status === 'missing-input') {

package/dist/skills/historic_sql_patterns/SKILL.md

@@ -15,8 +15,7 @@ Use this skill when the WorkUnit raw file is a `patterns-input/part-0001.json` s
 3. Call `read_raw_file` for that exact raw file path.
 4. Identify recurring analytical intents that span at least two tables and have repeated usage signal.
 5. Emit one `pattern` evidence object per durable cross-table intent by calling `emit_historic_sql_evidence`.
-6. Set each evidence object's `rawPath` to the exact raw file path read in step 3.
-7. Stop after all pattern evidence has been emitted.
+6. Stop after all pattern evidence has been emitted.
 
 Every join column mentioned in pattern descriptions must be verified via
 entity_details for both sides of the join.
@@ -56,7 +55,6 @@ Each call to `emit_historic_sql_evidence` must use this shape:
 ```json
 {
   "kind": "pattern",
-  "rawPath": "patterns-input/part-0001.json",
   "pattern": {
     "slug": "order-lifecycle-analysis",
     "title": "Order Lifecycle Analysis",

package/dist/skills/historic_sql_table_digest/SKILL.md

@@ -53,7 +53,6 @@ Call `emit_historic_sql_evidence` with this shape:
 {
   "kind": "table_usage",
   "table": "public.orders",
-  "rawPath": "tables/public.orders.json",
   "usage": {
     "narrative": "Orders are repeatedly queried for paid/refunded lifecycle analysis and customer-level rollups.",
     "frequencyTier": "high",

package/dist/skills/sl/SKILL.md

@@ -124,7 +124,7 @@ Every standalone column requires `name` and `type`. Overlays have computed colum
 
 ### Grain
 
-`grain: [col_a, col_b]` - the set of columns that uniquely identify one row. The query engine uses grain to prevent fan-out in joins. Overlays inherit grain from the manifest unless they override.
+`grain: [col_a, col_b]` - the set of columns that uniquely identify one row. The query engine uses grain to prevent fanout in joins. Overlays inherit grain from the manifest unless they override.
 
 ### Joins
 
@@ -177,7 +177,7 @@ The reverse edge (wiki pages that cite this source) is derived automatically fro
 
 ## Part 2 - Querying via `sl_query`
 
-The `sl_query` tool generates correct SQL from a structured query. It handles joins, fan-out prevention, aggregation correctness, and filter classification automatically. Prefer it over writing raw SQL whenever the SL has the relevant sources.
+The `sl_query` tool generates correct SQL from a structured query. It handles joins, fanout prevention, aggregation correctness, and filter classification automatically. Prefer it over writing raw SQL whenever the SL has the relevant sources.
 
 ### When to prefer sl_query over raw SQL
 

package/dist/sql.js

@@ -11,16 +11,12 @@ function sqlAnalysisDialectForDriver(driver) {
     const normalized = String(driver ?? '').trim().toLowerCase();
     const map = {
         postgres: 'postgres',
-        postgresql: 'postgres',
         bigquery: 'bigquery',
         snowflake: 'snowflake',
         mysql: 'mysql',
         sqlserver: 'tsql',
-        mssql: 'tsql',
         sqlite: 'sqlite',
-        sqlite3: 'sqlite',
         clickhouse: 'clickhouse',
-        redshift: 'redshift',
     };
     return map[normalized] ?? 'postgres';
 }

package/dist/status-project.d.ts

@@ -1,6 +1,6 @@
-import type { KtxConfigIssue, KtxProjectConnectionConfig } from './context/project/config.js';
+import type { KtxConfigIssue } from './context/project/config.js';
 import type { KtxLocalProject } from './context/project/project.js';
-import type { PostgresPgssProbeResult } from './context/ingest/adapters/historic-sql/types.js';
+import { type HistoricSqlReadinessProbe } from './context/ingest/historic-sql-probes.js';
 import type { DoctorCheck } from './doctor.js';
 type ProjectStatusLevel = 'ok' | 'warn' | 'fail' | 'skipped';
 type ProjectVerdict = 'ready' | 'partial' | 'blocked';
@@ -131,24 +131,9 @@ export interface ProjectStatus {
         validationConcurrency: number;
     };
 }
-interface QueryHistoryProbeInput {
-    projectDir: string;
-    connectionId: string;
-    connection: KtxProjectConnectionConfig;
-    env: NodeJS.ProcessEnv;
-}
-interface GenericProbeResult {
-    warnings: string[];
-    info?: string[];
-}
-type PostgresQueryHistoryProbe = (input: QueryHistoryProbeInput) => Promise<PostgresPgssProbeResult>;
-type SnowflakeQueryHistoryProbe = (input: QueryHistoryProbeInput) => Promise<GenericProbeResult>;
-type BigQueryQueryHistoryProbe = (input: QueryHistoryProbeInput) => Promise<GenericProbeResult>;
 export interface BuildProjectStatusOptions {
     env?: NodeJS.ProcessEnv;
-    postgresQueryHistoryProbe?: PostgresQueryHistoryProbe;
-    snowflakeQueryHistoryProbe?: SnowflakeQueryHistoryProbe;
-    bigqueryQueryHistoryProbe?: BigQueryQueryHistoryProbe;
+    queryHistoryReadinessProbe?: HistoricSqlReadinessProbe;
     claudeCodeAuthProbe?: ClaudeCodeAuthProbe;
     configIssues?: KtxConfigIssue[];
     fast?: boolean;