@kaelio/ktx 0.8.0 → 0.10.0

package/dist/setup-ready-menu.d.ts

@@ -1,6 +1,11 @@
 import { type KtxSetupPromptOption } from './setup-prompts.js';
 import type { KtxSetupStatus } from './setup.js';
 export type KtxSetupReadyAction = 'models' | 'embeddings' | 'databases' | 'sources' | 'runtime' | 'context' | 'agents' | 'exit';
+/**
+ * Where a project stands once its `ktx.yaml` exists. Single source of truth for the
+ * end-of-setup interception: each state maps to exactly one obvious next action.
+ */
+export type KtxSetupCompletion = 'incomplete' | 'needs-context' | 'needs-agents' | 'ready';
 interface KtxSetupReadyMenuPromptAdapter {
     select(options: {
         message: string;
@@ -11,8 +16,17 @@ interface KtxSetupReadyMenuPromptAdapter {
 export interface KtxSetupReadyMenuDeps {
     prompts?: KtxSetupReadyMenuPromptAdapter;
 }
-export declare function isKtxPreAgentSetupReady(status: KtxSetupStatus): boolean;
-export declare function isKtxSetupReady(status: KtxSetupStatus): boolean;
+export declare function setupHasContextTargets(status: KtxSetupStatus): boolean;
+export declare function classifyKtxSetupCompletion(status: KtxSetupStatus): KtxSetupCompletion;
+/**
+ * Shown when a returning user re-runs `ktx setup` on a fully-ready project. Leads with
+ * "you're done" (the readiness note is printed by the caller first) and keeps the
+ * section editor one explicit step away rather than defaulting into it.
+ */
+export declare function runKtxSetupReadyMenu(status: KtxSetupStatus, deps?: KtxSetupReadyMenuDeps): Promise<{
+    action: KtxSetupReadyAction;
+}>;
+/** @internal Reached only through {@link runKtxSetupReadyMenu}; exported for unit tests. */
 export declare function runKtxSetupReadyChangeMenu(status: KtxSetupStatus, deps?: KtxSetupReadyMenuDeps): Promise<{
     action: KtxSetupReadyAction;
 }>;

package/dist/setup-ready-menu.js

@@ -1,23 +1,55 @@
 import { createKtxSetupPromptAdapter, } from './setup-prompts.js';
-export function isKtxPreAgentSetupReady(status) {
+export function setupHasContextTargets(status) {
+    return status.databases.length > 0 || status.sources.length > 0;
+}
+function setupConfigReady(status) {
     return (status.project.ready &&
         status.llm.ready &&
         status.embeddings.ready &&
         status.databases.every((database) => database.ready) &&
         status.sources.every((source) => source.ready) &&
         status.runtime.ready &&
-        status.context.ready);
+        setupHasContextTargets(status));
 }
-export function isKtxSetupReady(status) {
-    return isKtxPreAgentSetupReady(status) && status.agents.some((agent) => agent.ready);
+export function classifyKtxSetupCompletion(status) {
+    if (!setupConfigReady(status)) {
+        return 'incomplete';
+    }
+    if (!status.context.ready) {
+        return 'needs-context';
+    }
+    if (!status.agents.some((agent) => agent.ready)) {
+        return 'needs-agents';
+    }
+    return 'ready';
 }
 function createPromptAdapter() {
     return createKtxSetupPromptAdapter({ selectCancelValue: 'exit' });
 }
+/**
+ * Shown when a returning user re-runs `ktx setup` on a fully-ready project. Leads with
+ * "you're done" (the readiness note is printed by the caller first) and keeps the
+ * section editor one explicit step away rather than defaulting into it.
+ */
+export async function runKtxSetupReadyMenu(status, deps = {}) {
+    const prompts = deps.prompts ?? createPromptAdapter();
+    const choice = await prompts.select({
+        message: 'Anything else?',
+        options: [
+            { value: 'done', label: "Done — I'll start using ktx" },
+            { value: 'change', label: 'Change a setting' },
+        ],
+    });
+    if (choice !== 'change') {
+        return { action: 'exit' };
+    }
+    return runKtxSetupReadyChangeMenu(status, { prompts });
+}
+/** @internal Reached only through {@link runKtxSetupReadyMenu}; exported for unit tests. */
 export async function runKtxSetupReadyChangeMenu(status, deps = {}) {
     const prompts = deps.prompts ?? createPromptAdapter();
     const action = (await prompts.select({
-        message: `KTX is already set up for ${status.project.name ?? status.project.path}. What would you like to change?`,
+        message: 'What would you like to change?',
         options: [
             { value: 'models', label: 'Models' },
             { value: 'embeddings', label: 'Embeddings' },

package/dist/setup-sources.js

@@ -19,6 +19,7 @@ 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 { runConnectionSetupWithRecovery, } from './connection-recovery.js';
 import { withMultiselectNavigation, withTextInputNavigation } from './prompt-navigation.js';
 import { runKtxPublicIngest } from './public-ingest.js';
 import { writeProjectLocalSecretReference } from './setup-secrets.js';
@@ -28,11 +29,11 @@ import { createKtxSetupPromptAdapter, } from './setup-prompts.js';
 const DEFAULT_NOTION_MAX_KNOWLEDGE_CREATES_PER_RUN = 25;
 const SOURCE_OPTIONS = [
     { value: 'dbt', label: 'dbt' },
-    { value: 'metricflow', label: 'MetricFlow' },
     { value: 'metabase', label: 'Metabase' },
+    { value: 'notion', label: 'Notion' },
+    { value: 'metricflow', label: 'MetricFlow' },
     { value: 'looker', label: 'Looker' },
     { value: 'lookml', label: 'LookML' },
-    { value: 'notion', label: 'Notion' },
 ];
 const SOURCE_LABELS = Object.fromEntries(SOURCE_OPTIONS.map((option) => [option.value, option.label]));
 const PRIMARY_SOURCE_DRIVERS = new Set([
@@ -145,8 +146,8 @@ async function chooseSourceCredentialRef(input) {
             message: `How should KTX find your ${input.label}?`,
             options: [
                 ...(input.existingRef ? [{ value: 'keep', label: 'Keep existing credential' }] : []),
-                { value: 'env', label: `Use ${input.envName} from the environment` },
                 { value: 'paste', label: 'Paste a key and save it as a local secret file' },
+                { value: 'env', label: `Use ${input.envName} from the environment` },
                 { value: 'back', label: 'Back' },
             ],
         });
@@ -178,8 +179,8 @@ async function chooseGitAuthCredentialRef(input) {
             message: `${label} repo requires authentication.`,
             options: [
                 ...(input.existingRef ? [{ value: 'keep', label: 'Keep existing credential' }] : []),
-                { value: 'env', label: 'Use GITHUB_TOKEN from the environment' },
                 { value: 'paste', label: 'Paste a token and save it as a local secret file' },
+                { value: 'env', label: 'Use GITHUB_TOKEN from the environment' },
                 { value: 'skip', label: 'Skip — try without authentication' },
                 { value: 'back', label: 'Back' },
             ],
@@ -799,8 +800,8 @@ async function promptForInteractiveSource(args, source, prompts, io, deps, defau
                 const selectedLocation = await prompts.select({
                     message: `${source} source location`,
                     options: [
-                        { value: 'path', label: 'Local path' },
                         { value: 'git', label: 'Git URL' },
+                        { value: 'path', label: 'Local path' },
                         { value: 'back', label: 'Back' },
                     ],
                 });
@@ -1100,8 +1101,8 @@ async function promptForInteractiveSource(args, source, prompts, io, deps, defau
             const crawlMode = await prompts.select({
                 message: 'Which Notion pages should KTX ingest?',
                 options: [
-                    { value: 'selected_roots', label: 'Specific pages and their subpages (choose them in a picker)' },
                     { value: 'all_accessible', label: 'All pages the integration can access' },
+                    { value: 'selected_roots', label: 'Specific pages and their subpages (choose them in a picker)' },
                     { value: 'back', label: 'Back' },
                 ],
             });
@@ -1434,56 +1435,125 @@ async function validateSource(source, args, deps) {
     }
     return await (deps.validateNotion ?? defaultValidateNotion)(args.connection);
 }
-async function saveValidateAndMaybeBuildSource(input) {
-    const connectionId = input.sourceChoice.kind === 'existing'
+async function createSourceSetupRollback(projectDir) {
+    const project = await loadKtxProject({ projectDir });
+    const previousConfig = project.config;
+    const configPath = project.configPath;
+    return async () => {
+        await writeFile(configPath, serializeKtxProjectConfig(previousConfig), 'utf-8');
+    };
+}
+function sourceConnectionId(input) {
+    return input.sourceChoice.kind === 'existing' || input.sourceChoice.kind === 'edited'
         ? input.sourceChoice.connectionId
-        : input.sourceChoice.kind === 'edited'
-            ? input.sourceChoice.connectionId
-            : (input.sourceChoice.args.sourceConnectionId ?? `${input.source}-main`);
-    const connection = input.sourceChoice.kind === 'existing'
-        ? input.sourceChoice.connection
-        : buildConnection(input.source, input.sourceChoice.args);
-    const rollback = input.sourceChoice.kind === 'existing'
-        ? undefined
-        : await writeSourceConnection(input.args.projectDir, connectionId, connection, sourceAdapter(input.source), input.io);
-    if (input.sourceChoice.kind === 'existing') {
-        await ensureSourceAdapterEnabled(input.args.projectDir, input.source);
-    }
-    const validation = await validateSource(input.source, { projectDir: input.args.projectDir, connectionId, connection }, input.deps);
+        : (input.sourceChoice.args.sourceConnectionId ?? `${input.source}-main`);
+}
+async function validateSourceConnectionAndMapping(input) {
+    const validation = await validateSource(input.source, { projectDir: input.args.projectDir, connectionId: input.connectionId, connection: input.connection }, input.deps);
     if (!validation.ok) {
-        await rollback?.();
         input.io.stderr.write(`${validation.message}\n`);
         return { status: 'failed' };
     }
     if (input.source === 'metabase' || input.source === 'looker') {
-        input.prompts.log?.(`Validating ${sourceLabel(input.source)} mapping…`);
-        const mappingCode = await (input.deps.runMapping ?? defaultRunMapping)(input.args.projectDir, connectionId, createSetupPrefixedIo(input.io));
+        input.prompts.log?.(`Validating ${sourceLabel(input.source)} mapping...`);
+        const mappingCode = await (input.deps.runMapping ?? defaultRunMapping)(input.args.projectDir, input.connectionId, createSetupPrefixedIo(input.io));
         if (mappingCode !== 0) {
-            await rollback?.();
             return { status: 'failed' };
         }
     }
+    return { status: 'ok' };
+}
+async function saveValidateAndMaybeBuildSource(input) {
+    let latestChoice = input.sourceChoice;
+    let latestConnectionId = sourceConnectionId({ source: input.source, sourceChoice: latestChoice });
+    let latestConnection = latestChoice.kind === 'existing'
+        ? latestChoice.connection
+        : buildConnection(input.source, latestChoice.args);
+    let configureCount = 0;
+    let rollbackAfterConfigure;
+    const outcome = await runConnectionSetupWithRecovery({
+        label: latestConnectionId,
+        interactive: input.args.inputMode !== 'disabled',
+        allowSkip: true,
+        io: input.io,
+        prompts: input.prompts,
+        snapshot: async () => {
+            rollbackAfterConfigure = await createSourceSetupRollback(input.args.projectDir);
+            return rollbackAfterConfigure;
+        },
+        configure: async () => {
+            configureCount += 1;
+            if (latestChoice.kind === 'existing' && configureCount === 1) {
+                await ensureSourceAdapterEnabled(input.args.projectDir, input.source);
+                return 'configured';
+            }
+            const project = await loadKtxProject({ projectDir: input.args.projectDir });
+            const currentConnection = project.config.connections[latestConnectionId] ?? latestConnection;
+            const useAlreadyPromptedArgs = configureCount === 1 && latestChoice.kind !== 'existing';
+            const sourceArgs = useAlreadyPromptedArgs && latestChoice.kind !== 'existing'
+                ? latestChoice.args
+                : input.args.inputMode === 'disabled'
+                    ? sourceArgsFromExistingConnection({
+                        args: input.args,
+                        source: input.source,
+                        connectionId: latestConnectionId,
+                        connection: currentConnection,
+                    })
+                    : await promptForInteractiveSource(sourceArgsFromExistingConnection({
+                        args: input.args,
+                        source: input.source,
+                        connectionId: latestConnectionId,
+                        connection: currentConnection,
+                    }), input.source, input.prompts, input.io, {
+                        pickNotionRootPages: input.deps.pickNotionRootPages,
+                        discoverMetabaseDatabases: input.deps.discoverMetabaseDatabases,
+                    }, latestConnectionId, input.deps.testGitRepo, input.deps.discoverMetabaseDatabases);
+            if (sourceArgs === 'back') {
+                return 'back';
+            }
+            latestConnectionId = sourceArgs.sourceConnectionId ?? latestConnectionId;
+            latestConnection = buildConnection(input.source, sourceArgs);
+            latestChoice =
+                latestChoice.kind === 'new'
+                    ? { kind: 'new', args: sourceArgs }
+                    : { kind: 'edited', connectionId: latestConnectionId, args: sourceArgs };
+            await writeSourceConnection(input.args.projectDir, latestConnectionId, latestConnection, sourceAdapter(input.source), input.io);
+            return 'configured';
+        },
+        validate: () => validateSourceConnectionAndMapping({
+            args: input.args,
+            source: input.source,
+            connectionId: latestConnectionId,
+            connection: latestConnection,
+            prompts: input.prompts,
+            io: input.io,
+            deps: input.deps,
+        }),
+    });
+    if (outcome !== 'ready') {
+        return { status: outcome };
+    }
     if (input.args.runInitialSourceIngest) {
         const ingestResult = await runInitialSourceIngestWithRecovery({
             args: input.args,
-            connectionId,
+            connectionId: latestConnectionId,
             io: input.io,
             prompts: input.prompts,
             deps: input.deps,
         });
         if (ingestResult === 'failed') {
-            await rollback?.();
+            await rollbackAfterConfigure?.();
             return { status: 'failed' };
         }
         if (ingestResult === 'back') {
-            await rollback?.();
+            await rollbackAfterConfigure?.();
             return { status: 'back' };
         }
     }
     else {
-        input.io.stdout.write(`│  Context source ${connectionId} saved. It will be built during the context build step.\n`);
+        input.io.stdout.write(`│  Context source ${latestConnectionId} saved. It will be built during the context build step.\n`);
     }
-    return { status: 'ready', connectionId };
+    return { status: 'ready', connectionId: latestConnectionId };
 }
 export async function runKtxSetupSourcesStep(args, io, deps = {}) {
     try {
@@ -1579,8 +1649,13 @@ export async function runKtxSetupSourcesStep(args, io, deps = {}) {
                     returnToSourceSelection = true;
                     break;
                 }
-                if (!readyConnectionIds.includes(choiceResult.connectionId)) {
-                    readyConnectionIds.push(choiceResult.connectionId);
+                if (choiceResult.status === 'skip') {
+                    continue;
+                }
+                if (choiceResult.status === 'ready') {
+                    if (!readyConnectionIds.includes(choiceResult.connectionId)) {
+                        readyConnectionIds.push(choiceResult.connectionId);
+                    }
                 }
             }
             if (returnToSourceSelection) {
@@ -1592,7 +1667,7 @@ export async function runKtxSetupSourcesStep(args, io, deps = {}) {
                     const addMore = await prompts.select({
                         message: `${readyConnectionIds.length} context source${readyConnectionIds.length > 1 ? 's' : ''} configured (${readyConnectionIds.join(', ')}). Add another?`,
                         options: [
-                            { value: 'done', label: 'Done — continue to context build' },
+                            { value: 'done', label: 'Done adding context sources' },
                             { value: 'edit', label: 'Edit an existing context source' },
                             { value: 'add', label: 'Add another context source' },
                         ],
@@ -1640,8 +1715,13 @@ export async function runKtxSetupSourcesStep(args, io, deps = {}) {
                         if (choiceResult.status === 'back') {
                             continue;
                         }
-                        if (!readyConnectionIds.includes(choiceResult.connectionId)) {
-                            readyConnectionIds.push(choiceResult.connectionId);
+                        if (choiceResult.status === 'skip') {
+                            continue;
+                        }
+                        if (choiceResult.status === 'ready') {
+                            if (!readyConnectionIds.includes(choiceResult.connectionId)) {
+                                readyConnectionIds.push(choiceResult.connectionId);
+                            }
                         }
                         continue;
                     }

package/dist/setup.d.ts

@@ -58,12 +58,12 @@ export type KtxSetupArgs = {
     agentScope?: KtxAgentScope;
     skipAgents?: boolean;
     inputMode: 'auto' | 'disabled';
+    debug?: boolean;
     yes: boolean;
     cliVersion: string;
     llmBackend?: KtxSetupLlmBackend;
     anthropicApiKeyEnv?: string;
     anthropicApiKeyFile?: string;
-    llmModel?: string;
     vertexProject?: string;
     vertexLocation?: string;
     skipLlm: boolean;

package/dist/setup.js

@@ -6,7 +6,7 @@ import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
 import { loadKtxProject } from './context/project/project.js';
 import { readKtxSetupState } from './context/project/setup-config.js';
 import { getKtxCliPackageInfo } from './cli-runtime.js';
-import { formatSetupNextStepLines } from './next-steps.js';
+import { formatNextStepLines, formatSetupNextStepLines } from './next-steps.js';
 import { runtimeInstallPolicyFromFlags } from './managed-python-command.js';
 import { readManagedPythonRuntimeStatus } from './managed-python-runtime.js';
 import { resolveProjectRuntimeRequirements } from './runtime-requirements.js';
@@ -16,7 +16,7 @@ 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 { isKtxPreAgentSetupReady, isKtxSetupReady, runKtxSetupReadyChangeMenu, } from './setup-ready-menu.js';
+import { classifyKtxSetupCompletion, runKtxSetupReadyMenu, setupHasContextTargets, } from './setup-ready-menu.js';
 import { runKtxSetupSourcesStep } from './setup-sources.js';
 import { runKtxSetupRuntimeStep, } from './setup-runtime.js';
 import { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
@@ -47,6 +47,7 @@ async function recordSetupStep(input) {
             step: input.step,
             outcome: setupTelemetryOutcome(input.status),
             durationMs: Math.max(0, performance.now() - input.startedAt),
+            ...(input.errorDetail ? { errorDetail: input.errorDetail } : {}),
         },
     });
 }
@@ -286,9 +287,6 @@ function setupStatusReady(status) {
         status.sources.every((source) => source.ready) &&
         status.runtime.ready);
 }
-function setupHasContextTargets(status) {
-    return status.databases.length > 0 || status.sources.length > 0;
-}
 function setupContextReady(status) {
     return status.context.ready;
 }
@@ -371,14 +369,22 @@ async function runKtxSetupInner(args, io, deps = {}) {
         const currentStatus = await readKtxSetupStatus(projectResult.projectDir, { cliVersion: args.cliVersion });
         let readyAction;
         if (args.inputMode !== 'disabled' && !agentsRequested) {
-            if (isKtxSetupReady(currentStatus)) {
-                readyAction = (await runKtxSetupReadyChangeMenu(currentStatus, deps.readyMenuDeps)).action;
-                if (readyAction === 'exit')
+            const completion = classifyKtxSetupCompletion(currentStatus);
+            if (completion === 'ready') {
+                setupUi.note(formatNextStepLines().join('\n'), 'ktx is ready', io);
+                const choice = (await runKtxSetupReadyMenu(currentStatus, deps.readyMenuDeps)).action;
+                if (choice === 'exit')
                     return 0;
+                readyAction = choice;
+            }
+            else if (completion === 'needs-context') {
+                // Config is done; skip the re-walk and land straight on the build prompt.
+                readyAction = 'context';
             }
-            else if (isKtxPreAgentSetupReady(currentStatus)) {
+            else if (completion === 'needs-agents') {
                 readyAction = 'agents';
             }
+            // 'incomplete' → readyAction stays undefined → run the full setup walk.
         }
         const runOnly = readyAction;
         const agentOnlySetup = agentsRequested || runOnly === 'agents';
@@ -437,7 +443,6 @@ async function runKtxSetupInner(args, io, deps = {}) {
                     ...(args.llmBackend ? { llmBackend: args.llmBackend } : {}),
                     ...(args.anthropicApiKeyEnv ? { anthropicApiKeyEnv: args.anthropicApiKeyEnv } : {}),
                     ...(args.anthropicApiKeyFile ? { anthropicApiKeyFile: args.anthropicApiKeyFile } : {}),
-                    ...(args.llmModel ? { llmModel: args.llmModel } : {}),
                     ...(args.vertexProject ? { vertexProject: args.vertexProject } : {}),
                     ...(args.vertexLocation ? { vertexLocation: args.vertexLocation } : {}),
                     forcePrompt: forcePromptSteps.has('models') || runOnly === 'models',
@@ -467,6 +472,10 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 const databaseResult = await databasesRunner({
                     projectDir: projectResult.projectDir,
                     inputMode: args.inputMode,
+                    ...(args.debug !== undefined ? { debug: args.debug } : {}),
+                    yes: args.yes,
+                    cliVersion: args.cliVersion,
+                    runtimeInstallPolicy: setupRuntimeInstallPolicy(args),
                     ...(args.databaseDrivers ? { databaseDrivers: args.databaseDrivers } : {}),
                     ...(args.databaseConnectionIds ? { databaseConnectionIds: args.databaseConnectionIds } : {}),
                     ...(args.databaseConnectionId ? { databaseConnectionId: args.databaseConnectionId } : {}),
@@ -565,6 +574,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 startedAt: stepStartedAt,
                 io,
                 cliVersion: args.cliVersion,
+                ...(stepResult.errorDetail ? { errorDetail: stepResult.errorDetail } : {}),
             });
             if (stepResult.status === 'failed') {
                 return 1;
@@ -589,7 +599,9 @@ async function runKtxSetupInner(args, io, deps = {}) {
             }
             if (step === 'context' && stepResult.status !== 'ready') {
                 if (shouldRunAgents && args.skipAgents !== true) {
-                    return 0;
+                    // Context isn't built, so skip agent install — but still reach the
+                    // completion screen, which states readiness and points at `ktx ingest`.
+                    break setupLoop;
                 }
             }
             forcePromptSteps.delete(step);

package/dist/sl.d.ts

@@ -1,7 +1,7 @@
 import type { KtxCliIo } from './cli-runtime.js';
 import type { KtxSqlQueryExecutorPort } from './context/connections/query-executor.js';
 import type { KtxSemanticLayerComputePort } from './context/daemon/semantic-layer-compute.js';
-import { loadKtxProject } from './context/project/project.js';
+import { loadKtxProject, type KtxLocalProject } from './context/project/project.js';
 import { searchLocalSlSources as defaultSearchLocalSlSources } from './context/sl/local-sl.js';
 import type { SemanticLayerQueryInput } from './context/sl/types.js';
 import { resolveProjectEmbeddingProvider } from './embedding-resolution.js';
@@ -57,7 +57,7 @@ interface KtxSlDeps {
         io: KtxSlIo;
         projectDir?: string;
     }) => Promise<KtxSemanticLayerComputePort>;
-    createQueryExecutor?: () => KtxSqlQueryExecutorPort;
+    createQueryExecutor?: (project: KtxLocalProject) => KtxSqlQueryExecutorPort;
 }
 export declare function runKtxSl(args: KtxSlArgs, io?: KtxSlIo, deps?: KtxSlDeps): Promise<number>;
 export {};

package/dist/sl.js

@@ -1,13 +1,14 @@
 import { readFile } from 'node:fs/promises';
-import { createDefaultLocalQueryExecutor } from './context/connections/local-query-executor.js';
 import { KtxIngestEmbeddingPortAdapter } from './context/llm/embedding-port.js';
 import { loadKtxProject } from './context/project/project.js';
 import { compileLocalSlQuery } from './context/sl/local-query.js';
 import { listLocalSlSources, resolveLocalSlSource, searchLocalSlSources as defaultSearchLocalSlSources, validateLocalSlSource, } from './context/sl/local-sl.js';
 import { resolveProjectEmbeddingProvider, } from './embedding-resolution.js';
+import { createKtxCliIngestQueryExecutor } from './ingest-query-executor.js';
 import { createManagedPythonSemanticLayerComputePort, } from './managed-python-command.js';
 import { profileMark } from './startup-profile.js';
-import { emitTelemetryEvent } from './telemetry/index.js';
+import { emitTelemetryEvent, reportException } from './telemetry/index.js';
+import { collectTelemetryRedactionSecrets } from './telemetry/redaction-secrets.js';
 import { scrubErrorClass } from './telemetry/scrubber.js';
 profileMark('module:sl');
 function resolutionToEmbeddingPort(resolution) {
@@ -91,8 +92,9 @@ function ambiguousSourceMessage(sourceName, connectionIds) {
 export async function runKtxSl(args, io = process, deps = {}) {
     const startedAt = performance.now();
     let queryForTelemetry;
+    let project;
     try {
-        const project = await (deps.loadProject ?? loadKtxProject)({ projectDir: args.projectDir });
+        project = await (deps.loadProject ?? loadKtxProject)({ projectDir: args.projectDir });
         if (args.command === 'list') {
             const sources = await listLocalSlSources(project, { connectionId: args.connectionId });
             await printSlSources({
@@ -204,7 +206,7 @@ export async function runKtxSl(args, io = process, deps = {}) {
                     io,
                     projectDir: args.projectDir,
                 });
-            const queryExecutor = args.execute ? (deps.createQueryExecutor ?? createDefaultLocalQueryExecutor)() : undefined;
+            const queryExecutor = args.execute ? (deps.createQueryExecutor ?? createKtxCliIngestQueryExecutor)(project) : undefined;
             const result = await compileLocalSlQuery(project, {
                 connectionId: args.connectionId,
                 query,
@@ -237,6 +239,20 @@ export async function runKtxSl(args, io = process, deps = {}) {
         throw new Error(`Unsupported sl command: ${JSON.stringify(_exhaustive)}`);
     }
     catch (error) {
+        await reportException({
+            error,
+            context: { source: `sl ${args.command}`, handled: true, fatal: false },
+            projectDir: args.projectDir,
+            io,
+            redactionSecrets: await collectTelemetryRedactionSecrets({
+                project,
+                projectDir: args.projectDir,
+                connectionId: args.connectionId,
+                includeLlm: args.command === 'query',
+                includeEmbeddings: args.command === 'search' || args.command === 'query',
+                env: process.env,
+            }),
+        });
         if (args.command === 'validate') {
             const errorClass = scrubErrorClass(error);
             await emitTelemetryEvent({

package/dist/sql.js

@@ -4,7 +4,8 @@ import { createKtxCliScanConnector } from './local-scan-connectors.js';
 import { createManagedDaemonSqlAnalysisPort } from './managed-python-http.js';
 import { profileMark } from './startup-profile.js';
 import { isDemoConnection } from './telemetry/demo-detect.js';
-import { emitTelemetryEvent } from './telemetry/index.js';
+import { emitTelemetryEvent, reportException } from './telemetry/index.js';
+import { collectTelemetryRedactionSecrets } from './telemetry/redaction-secrets.js';
 import { scrubErrorClass } from './telemetry/scrubber.js';
 profileMark('module:sql');
 function sqlAnalysisDialectForDriver(driver) {
@@ -96,8 +97,9 @@ export async function runKtxSql(args, io = process, deps = {}) {
     const startedAt = performance.now();
     let driver = 'unknown';
     let demoConnection = false;
+    let project;
     try {
-        const project = await (deps.loadProject ?? loadKtxProject)({ projectDir: args.projectDir });
+        project = await (deps.loadProject ?? loadKtxProject)({ projectDir: args.projectDir });
         const connection = project.config.connections[args.connectionId];
         if (!connection) {
             throw new Error(`Connection "${args.connectionId}" is not configured in ktx.yaml`);
@@ -167,6 +169,20 @@ export async function runKtxSql(args, io = process, deps = {}) {
                 ...(errorClass ? { errorClass } : {}),
             },
         });
+        await reportException({
+            error,
+            context: { source: 'sql run', handled: true, fatal: false },
+            projectDir: args.projectDir,
+            io,
+            redactionSecrets: await collectTelemetryRedactionSecrets({
+                project,
+                projectDir: args.projectDir,
+                connectionId: args.connectionId,
+                includeLlm: false,
+                includeEmbeddings: false,
+                env: process.env,
+            }),
+        });
         io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
         return 1;
     }

package/dist/star-prompt/cache.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+declare const starCountCacheSchema: z.ZodObject<{
+    count: z.ZodNumber;
+    fetchedAt: z.ZodString;
+}, z.core.$strict>;
+export type StarCountCache = z.infer<typeof starCountCacheSchema>;
+/** @internal */
+export declare function starCountCachePath(homeDir?: string): string;
+export declare function readStarCountCache(options?: {
+    homeDir?: string;
+}): StarCountCache | null;
+export declare function writeStarCountCache(value: StarCountCache, options?: {
+    homeDir?: string;
+}): Promise<void>;
+export declare function isFreshStarCountCache(cache: StarCountCache | null, now: Date, ttlMs: number): boolean;
+export {};

package/dist/star-prompt/cache.js

@@ -0,0 +1,45 @@
+import { readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+const starCountCacheSchema = z
+    .object({
+    count: z.number().int().nonnegative(),
+    fetchedAt: z.string(),
+})
+    .strict();
+/** @internal */
+export function starCountCachePath(homeDir = homedir()) {
+    return join(homeDir, '.ktx', 'star-count.json');
+}
+export function readStarCountCache(options = {}) {
+    try {
+        return starCountCacheSchema.parse(JSON.parse(readFileSync(starCountCachePath(options.homeDir), 'utf-8')));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeStarCountCache(value, options = {}) {
+    try {
+        const path = starCountCachePath(options.homeDir);
+        await mkdir(dirname(path), { recursive: true });
+        const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+        renameSync(tempPath, path);
+    }
+    catch {
+        return;
+    }
+}
+export function isFreshStarCountCache(cache, now, ttlMs) {
+    if (!cache) {
+        return false;
+    }
+    const fetchedAtMs = Date.parse(cache.fetchedAt);
+    if (Number.isNaN(fetchedAtMs)) {
+        return false;
+    }
+    return now.getTime() - fetchedAtMs < ttlMs;
+}

package/dist/star-prompt/star-count.d.ts

@@ -0,0 +1,7 @@
+import { request as httpsRequest } from 'node:https';
+type HttpsRequest = typeof httpsRequest;
+export declare function fetchGitHubStarCount(options?: {
+    request?: HttpsRequest;
+    timeoutMs?: number;
+}): Promise<number | null>;
+export {};