@kaelio/ktx 0.9.0 → 0.10.0

package/dist/context-build-view.d.ts

@@ -2,6 +2,7 @@ import type { KtxCliIo } from './index.js';
 import type { KtxManagedPythonInstallPolicy } from './managed-python-command.js';
 import type { KtxPublicIngestArgs, KtxPublicIngestPlanTarget, KtxPublicIngestProject } from './public-ingest.js';
 import { executePublicIngestTarget } from './public-ingest.js';
+import { fetchGitHubStarCount as defaultFetchGitHubStarCount } from './star-prompt/star-count.js';
 type PhaseKey = 'database-schema' | 'query-history' | 'source-ingest';
 type PhaseStatus = 'queued' | 'running' | 'done' | 'failed' | 'skipped';
 interface PhaseState {
@@ -32,6 +33,7 @@ export interface ContextBuildViewState {
     frame: number;
     startedAt: number | null;
     totalElapsedMs: number;
+    starCount: number | null;
 }
 export interface ContextBuildArgs {
     projectDir: string;
@@ -73,6 +75,8 @@ interface CompletedItemName {
 interface ContextBuildRenderOptions {
     styled?: boolean;
     showHint?: boolean;
+    showStarPrompt?: boolean;
+    columns?: number;
     hintText?: string;
     projectDir?: string;
     title?: string;
@@ -89,6 +93,14 @@ export interface ContextBuildDeps {
     now?: () => number;
     onSourceProgress?: (sources: ContextBuildSourceProgressUpdate[]) => void;
     sourceProgressThrottleMs?: number;
+    fetchStarCount?: typeof defaultFetchGitHubStarCount;
+    starPromptEnv?: StarPromptEnv;
+    starPromptHomeDir?: string;
+}
+interface StarPromptEnv extends NodeJS.ProcessEnv {
+    CI?: string;
+    DO_NOT_TRACK?: string;
+    KTX_NO_STAR?: string;
 }
 export declare function renderContextBuildView(state: ContextBuildViewState, options?: ContextBuildRenderOptions): string;
 /** @internal */
@@ -101,6 +113,7 @@ export declare function parseIngestSummary(output: string): string | null;
 export declare function viewStateFromSourceProgress(sources: ContextBuildSourceProgressUpdate[], now: number, startedAtMs?: number): ContextBuildViewState;
 export declare function createRepainter(io: KtxCliIo): {
     paint(content: string): void;
+    columns(): number;
 };
 export declare function initViewState(targets: KtxPublicIngestPlanTarget[]): ContextBuildViewState;
 export declare function runContextBuild(project: KtxPublicIngestProject, args: ContextBuildArgs, io: KtxCliIo, deps?: ContextBuildDeps): Promise<ContextBuildResult>;

package/dist/context-build-view.js

@@ -2,6 +2,9 @@ import { buildPublicIngestPlan, executePublicIngestTarget, publicProgressMessage
 import { createAggregateProgressPort } from './progress-port-adapter.js';
 import { formatDuration } from './demo-metrics.js';
 import { profileMark } from './startup-profile.js';
+import { isFreshStarCountCache, readStarCountCache, writeStarCountCache, } from './star-prompt/cache.js';
+import { fetchGitHubStarCount as defaultFetchGitHubStarCount } from './star-prompt/star-count.js';
+import { renderStarPromptLine } from './star-prompt/star-line.js';
 profileMark('module:context-build-view');
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 const ESC = String.fromCharCode(0x1b);
@@ -286,6 +289,13 @@ export function renderContextBuildView(state, options = {}) {
         lines.push(styled ? green(summary) : summary);
         lines.push('');
     }
+    if (options.showStarPrompt && hasActive) {
+        const starPrompt = renderStarPromptLine({
+            count: state.starCount,
+            columns: options.columns ?? 80,
+        });
+        lines.push(styled ? dim(starPrompt) : starPrompt);
+    }
     if (options.showHint && hasActive) {
         const hintContent = options.hintText ?? 'Ctrl+C to stop';
         const hint = `  ${hintContent}`;
@@ -423,6 +433,7 @@ export function viewStateFromSourceProgress(sources, now, startedAtMs) {
         frame: 0,
         startedAt: startedAtMs ?? null,
         totalElapsedMs: startedAtMs ? now - startedAtMs : 0,
+        starCount: null,
     };
 }
 // --- Repaint ---
@@ -465,6 +476,9 @@ export function createRepainter(io) {
             hasPainted = true;
             lastCursorUpRows = cursorUpRowsAfterWrite(content);
         },
+        columns() {
+            return terminalColumns();
+        },
     };
 }
 // --- Orchestration ---
@@ -616,12 +630,42 @@ export function initViewState(targets) {
         frame: 0,
         startedAt: null,
         totalElapsedMs: 0,
+        starCount: null,
     };
 }
 function formatProgressDetail(update, target) {
     const percent = Math.max(0, Math.min(100, Math.round(update.percent)));
     return `[${percent}%] ${publicProgressMessage(update.message, target)}`;
 }
+const STAR_COUNT_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+function envFlag(value) {
+    return value !== undefined && value !== '' && value !== '0' && value !== 'false';
+}
+function shouldSuppressStarPrompt(env) {
+    return envFlag(env.CI) || envFlag(env.DO_NOT_TRACK) || envFlag(env.KTX_NO_STAR);
+}
+function startStarPromptCountRefresh(input) {
+    const cached = readStarCountCache({ homeDir: input.homeDir });
+    if (cached) {
+        input.state.starCount = cached.count;
+    }
+    if (isFreshStarCountCache(cached, new Date(input.now()), STAR_COUNT_CACHE_TTL_MS)) {
+        return;
+    }
+    void input.fetchStarCount()
+        .then((count) => {
+        if (typeof count !== 'number' || !Number.isFinite(count)) {
+            return;
+        }
+        input.state.starCount = count;
+        input.paint();
+        void writeStarCountCache({
+            count,
+            fetchedAt: new Date(input.now()).toISOString(),
+        }, { homeDir: input.homeDir });
+    })
+        .catch(() => undefined);
+}
 export async function runContextBuild(project, args, io, deps = {}) {
     const plan = buildPublicIngestPlan(project, {
         projectDir: args.projectDir,
@@ -636,13 +680,28 @@ export async function runContextBuild(project, args, io, deps = {}) {
     const nowFn = deps.now ?? (() => Date.now());
     state.startedAt = nowFn();
     const repainter = isTTY ? createRepainter(io) : null;
+    const starPromptEnabled = repainter !== null && !shouldSuppressStarPrompt(deps.starPromptEnv ?? process.env);
     const viewOpts = {
         styled: true,
         projectDir: args.projectDir,
         notices: plan.notices ?? [],
         warnings: plan.warnings,
     };
-    const paint = (hint) => repainter?.paint(renderContextBuildView(state, { ...viewOpts, showHint: hint }));
+    const paint = (hint) => repainter?.paint(renderContextBuildView(state, {
+        ...viewOpts,
+        showHint: hint,
+        showStarPrompt: starPromptEnabled && hint,
+        columns: repainter.columns(),
+    }));
+    if (starPromptEnabled) {
+        startStarPromptCountRefresh({
+            fetchStarCount: deps.fetchStarCount ?? defaultFetchGitHubStarCount,
+            homeDir: deps.starPromptHomeDir,
+            now: nowFn,
+            paint: () => paint(true),
+            state,
+        });
+    }
     paint(true);
     let spinnerInterval = null;
     if (repainter) {

package/dist/demo-metrics.d.ts

@@ -8,8 +8,6 @@ interface DemoMetricsTuning {
 interface DemoMetricsSnapshot {
     elapsedMs: number;
     etaMs: number | null;
-    agentSteps: number;
-    agentStepBudget: number;
     toolCalls: number;
     workUnitsStarted: number;
     workUnitsFinished: number;

package/dist/demo-metrics.js

@@ -5,13 +5,6 @@ const DEFAULT_OUTPUT_PRICE_PER_MTOK_USD = 15;
 function eventsOf(events, type) {
     return events.filter((event) => event.type === type);
 }
-function maxAgentStep(events) {
-    const steps = eventsOf(events, 'work_unit_step');
-    const started = eventsOf(events, 'work_unit_started');
-    const stepIndex = steps.reduce((max, event) => Math.max(max, event.stepIndex), 0);
-    const stepBudget = Math.max(0, ...steps.map((event) => event.stepBudget), ...started.map((event) => event.stepBudget));
-    return { step: stepIndex, budget: stepBudget };
-}
 function totalToolCalls(input) {
     return input.details.transcripts.reduce((total, transcript) => total + transcript.toolCallCount, 0);
 }
@@ -49,11 +42,10 @@ export function buildDemoMetrics(input, options = {}) {
     const outputPrice = tuning.outputPricePerMTokUsd ?? DEFAULT_OUTPUT_PRICE_PER_MTOK_USD;
     const nowMs = (options.now ?? Date.now)();
     const elapsedMs = elapsedMsFromEvents(input.events, nowMs);
-    const { step, budget } = maxAgentStep(input.events);
     const toolCalls = totalToolCalls(input);
     const progress = workUnitProgress(input);
     const finishedCount = eventsOf(input.events, 'work_unit_finished').length;
-    const stepDriver = Math.max(step, toolCalls, finishedCount * 4);
+    const stepDriver = Math.max(toolCalls, finishedCount * 4);
     const inputTokens = stepDriver * inputTokensPerStep;
     const outputTokens = stepDriver * outputTokensPerStep;
     const totalTokens = inputTokens + outputTokens;
@@ -63,8 +55,6 @@ export function buildDemoMetrics(input, options = {}) {
     return {
         elapsedMs,
         etaMs: estimateEtaMs(elapsedMs, progress.finished, progress.total, input.status),
-        agentSteps: step,
-        agentStepBudget: budget,
         toolCalls,
         workUnitsStarted: progress.started,
         workUnitsFinished: progress.finished,

package/dist/ingest.d.ts

@@ -58,6 +58,7 @@ export interface KtxIngestDeps {
     readReportFile?: typeof readIngestReportSnapshotFile;
     renderStoredMemoryFlow?: typeof renderMemoryFlowTui;
     startLiveMemoryFlow?: typeof startLiveMemoryFlowTui;
+    abortSignal?: AbortSignal;
     env?: NodeJS.ProcessEnv;
     localIngestOptions?: Pick<RunLocalIngestOptions, 'agentRunner' | 'llmRuntime' | 'memoryModel' | 'semanticLayerCompute' | 'queryExecutor' | 'logger' | 'pullConfigOptions'>;
     progress?: (update: KtxIngestProgressUpdate) => void;

package/dist/ingest.js

@@ -17,6 +17,22 @@ import { renderMemoryFlowTui, startLiveMemoryFlowTui, } from './memory-flow-tui.
 import { resolveVizFallback, warnVizFallbackOnce } from './viz-fallback.js';
 import { profileMark } from './startup-profile.js';
 profileMark('module:ingest');
+function createCliAbortSignal() {
+    const controller = new AbortController();
+    let interrupted = false;
+    const onSigint = () => {
+        if (interrupted) {
+            process.exit(130);
+        }
+        interrupted = true;
+        controller.abort(new DOMException('Aborted', 'AbortError'));
+    };
+    process.on('SIGINT', onSigint);
+    return {
+        signal: controller.signal,
+        dispose: () => process.off('SIGINT', onSigint),
+    };
+}
 const REPORT_SOURCE_LABELS = new Map([
     ['live-database', 'Database schema'],
     ['historic-sql', 'Query history'],
@@ -249,6 +265,12 @@ function plainIngestEventProgress(event, snapshot, eventIndex) {
                 message: event.message,
                 ...(event.transient !== undefined ? { transient: event.transient } : {}),
             };
+        case 'rate_limit_wait':
+            return {
+                percent: 50,
+                message: `Rate-limited (${event.provider}${event.rateLimitType ? ` ${event.rateLimitType}` : ''}); resuming in ${Math.ceil(event.remainingMs / 1_000)}s`,
+                transient: true,
+            };
         case 'work_unit_started': {
             const total = plannedWorkUnitCountThrough(snapshot, eventIndex);
             const ordinal = workUnitOrdinalThrough(snapshot, eventIndex, event.unitKey);
@@ -259,9 +281,8 @@ function plainIngestEventProgress(event, snapshot, eventIndex) {
             const total = plannedWorkUnitCountThrough(snapshot, eventIndex);
             const completed = completedWorkUnitCountThrough(snapshot, eventIndex);
             const active = activeWorkUnitCountThrough(snapshot, eventIndex);
-            const stepFraction = event.stepBudget > 0 ? Math.min(1, event.stepIndex / event.stepBudget) : 0;
-            const percent = total > 0 ? 55 + Math.ceil(((completed + stepFraction) / total) * 25) : 55;
-            const latest = `${event.unitKey} step ${event.stepIndex}/${event.stepBudget}`;
+            const percent = total > 0 ? 55 + Math.ceil((completed / total) * 25) : 55;
+            const latest = `${event.unitKey} · ${pluralize(event.toolCalls, 'action')}`;
             return {
                 percent,
                 message: `Processing tasks: ${completed}/${total} complete, ${active} active; latest ${latest}`,
@@ -546,6 +567,8 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                         : io, deps.progress);
                 plainProgress?.start();
                 structuredProgress?.start();
+                const cliAbort = deps.abortSignal ? null : createCliAbortSignal();
+                const abortSignal = deps.abortSignal ?? cliAbort?.signal;
                 let result;
                 try {
                     result = await executeMetabaseFanout({
@@ -559,6 +582,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                         embeddingProvider,
                         ...(memoryFlow ? { memoryFlow } : {}),
                         ...(progress ? { progress } : {}),
+                        ...(abortSignal ? { abortSignal } : {}),
                     });
                     plainProgress?.flush();
                     if (args.outputMode === 'json') {
@@ -570,6 +594,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                 }
                 finally {
                     plainProgress?.flush();
+                    cliAbort?.dispose();
                 }
                 return result.status === 'all_failed' ? 1 : 0;
             }
@@ -612,6 +637,8 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                 : undefined;
             plainProgress?.start();
             structuredProgress?.start();
+            const cliAbort = deps.abortSignal ? null : createCliAbortSignal();
+            const abortSignal = deps.abortSignal ?? cliAbort?.signal;
             try {
                 const result = await executeLocalIngest({
                     project: ingestProject,
@@ -627,6 +654,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                     embeddingProvider,
                     ...(args.debugLlmRequestFile ? { llmDebugRequestFile: args.debugLlmRequestFile } : {}),
                     ...(memoryFlow ? { memoryFlow } : {}),
+                    ...(abortSignal ? { abortSignal } : {}),
                 });
                 if (shouldUseLiveViz && memoryFlow) {
                     latestMemoryFlowSnapshot = finalRunMemoryFlowInput(memoryFlow.snapshot(), result.report);
@@ -646,6 +674,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
             finally {
                 plainProgress?.flush();
                 liveTui?.close();
+                cliAbort?.dispose();
             }
         }
         if (args.reportFile) {

package/dist/io/symbols.d.ts

@@ -1,6 +1,8 @@
 export declare const SYMBOLS: {
     readonly middot: "-" | "·";
     readonly emDash: "--" | "—";
+    readonly star: "*" | "★";
+    readonly rightArrow: "→" | "->";
 };
 export declare function dim(text: string): string;
 export declare function bold(text: string): string;

package/dist/io/symbols.js

@@ -12,6 +12,8 @@ const unicode = detectUnicodeSupport();
 export const SYMBOLS = {
     middot: unicode ? '·' : '-',
     emDash: unicode ? '—' : '--',
+    star: unicode ? '★' : '*',
+    rightArrow: unicode ? '→' : '->',
 };
 export function dim(text) {
     return styleText('dim', text);

package/dist/memory-flow-hud.js

@@ -97,27 +97,19 @@ function sourceDescription(input) {
 }
 function activeWorkUnits(input) {
     const finishedKeys = new Set();
-    const unitMap = new Map();
     for (const e of input.events) {
-        if (e.type === 'work_unit_started') {
-            unitMap.set(e.unitKey, { stepIndex: 0, stepBudget: e.stepBudget });
-        }
-        if (e.type === 'work_unit_step') {
-            const existing = unitMap.get(e.unitKey);
-            if (existing) {
-                existing.stepIndex = e.stepIndex;
-                existing.stepBudget = e.stepBudget;
-            }
-        }
         if (e.type === 'work_unit_finished')
             finishedKeys.add(e.unitKey);
     }
-    const result = [];
-    for (const [unitKey, data] of unitMap) {
-        if (!finishedKeys.has(unitKey))
-            result.push({ unitKey, ...data });
+    const active = [];
+    const seen = new Set();
+    for (const e of input.events) {
+        if (e.type === 'work_unit_started' && !finishedKeys.has(e.unitKey) && !seen.has(e.unitKey)) {
+            seen.add(e.unitKey);
+            active.push(e.unitKey);
+        }
     }
-    return result;
+    return active;
 }
 function queuedWorkUnits(input) {
     const startedKeys = new Set();

package/dist/public-ingest.js

@@ -8,7 +8,8 @@ import { createAggregateProgressPort } from './progress-port-adapter.js';
 import { resolvePublicIngestRuntimeRequirements } from './runtime-requirements.js';
 import { profileMark } from './startup-profile.js';
 import { isDemoConnection } from './telemetry/demo-detect.js';
-import { emitProjectStackSnapshot, emitTelemetryEvent } from './telemetry/index.js';
+import { emitProjectStackSnapshot, emitTelemetryEvent, reportException } from './telemetry/index.js';
+import { collectTelemetryRedactionSecrets } from './telemetry/redaction-secrets.js';
 import { formatErrorDetail } from './telemetry/scrubber.js';
 profileMark('module:public-ingest');
 const sourceAdapterByDriver = new Map([
@@ -733,26 +734,60 @@ export async function runKtxPublicIngest(args, io, deps = {}) {
                 });
             }
             catch (error) {
+                await reportException({
+                    error,
+                    context: { source: 'ingest runtime', handled: true, fatal: false },
+                    projectDir: args.projectDir,
+                    io,
+                    redactionSecrets: await collectTelemetryRedactionSecrets({
+                        project,
+                        projectDir: args.projectDir,
+                        connectionId: args.targetConnectionId,
+                        includeLlm: true,
+                        includeEmbeddings: true,
+                        env: deps.env ?? process.env,
+                    }),
+                });
                 io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
                 return 1;
             }
         }
         const { runContextBuild } = await import('./context-build-view.js');
         const contextBuild = deps.runContextBuild ?? runContextBuild;
-        const result = await contextBuild(project, {
-            projectDir: args.projectDir,
-            ...(args.targetConnectionId ? { targetConnectionId: args.targetConnectionId } : {}),
-            all: args.all,
-            entrypoint: 'ingest',
-            inputMode: args.inputMode,
-            ...(args.queryHistory ? { queryHistory: args.queryHistory } : {}),
-            ...(args.queryHistoryWindowDays !== undefined ? { queryHistoryWindowDays: args.queryHistoryWindowDays } : {}),
-            ...(args.scanMode ? { scanMode: args.scanMode } : {}),
-            ...(args.detectRelationships !== undefined ? { detectRelationships: args.detectRelationships } : {}),
-            ...(args.cliVersion ? { cliVersion: args.cliVersion } : {}),
-            ...(args.runtimeInstallPolicy ? { runtimeInstallPolicy: args.runtimeInstallPolicy } : {}),
-        }, io);
-        return result.exitCode;
+        try {
+            const result = await contextBuild(project, {
+                projectDir: args.projectDir,
+                ...(args.targetConnectionId ? { targetConnectionId: args.targetConnectionId } : {}),
+                all: args.all,
+                entrypoint: 'ingest',
+                inputMode: args.inputMode,
+                ...(args.queryHistory ? { queryHistory: args.queryHistory } : {}),
+                ...(args.queryHistoryWindowDays !== undefined ? { queryHistoryWindowDays: args.queryHistoryWindowDays } : {}),
+                ...(args.scanMode ? { scanMode: args.scanMode } : {}),
+                ...(args.detectRelationships !== undefined ? { detectRelationships: args.detectRelationships } : {}),
+                ...(args.cliVersion ? { cliVersion: args.cliVersion } : {}),
+                ...(args.runtimeInstallPolicy ? { runtimeInstallPolicy: args.runtimeInstallPolicy } : {}),
+            }, io);
+            return result.exitCode;
+        }
+        catch (error) {
+            await reportException({
+                error,
+                context: { source: 'ingest context-build', handled: true, fatal: false },
+                projectDir: args.projectDir,
+                io,
+                redactionSecrets: await collectTelemetryRedactionSecrets({
+                    project,
+                    projectDir: args.projectDir,
+                    connectionId: args.targetConnectionId,
+                    includeLlm: true,
+                    includeEmbeddings: true,
+                    env: deps.env ?? process.env,
+                }),
+            });
+            io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
     }
     const plan = buildPublicIngestPlan(project, args);
     const results = [];

package/dist/reveal-password-prompt.d.ts

@@ -0,0 +1,24 @@
+import { type PasswordOptions } from '@clack/core';
+/**
+ * Mask every character of `userInput` except the last `tail`, but only reveal the
+ * tail once the secret is long enough that the hidden portion still dominates
+ * (`length > tail * 2`). Short secrets stay fully masked so we never expose most
+ * of a small value. The returned string keeps the same code-unit length as the
+ * input so clack's cursor slicing in `userInputWithCursor` stays aligned.
+ *
+ * @internal
+ */
+export declare function maskRevealingTail(userInput: string, maskChar: string, tail: number): string;
+export interface RevealPasswordOptions {
+    message: string;
+    mask?: string;
+    tail?: number;
+    validate?: PasswordOptions['validate'];
+    signal?: AbortSignal;
+}
+/**
+ * Drop-in replacement for clack's `password()` that reveals the last few
+ * characters of the entered value while typing. Resolves to the raw value or the
+ * clack cancel symbol, matching `password()`'s contract.
+ */
+export declare function revealPassword(options: RevealPasswordOptions): Promise<string | symbol>;

package/dist/reveal-password-prompt.js

@@ -0,0 +1,78 @@
+import { styleText } from 'node:util';
+import { PasswordPrompt } from '@clack/core';
+import { S_BAR, S_BAR_END, S_PASSWORD_MASK, settings, symbol } from '@clack/prompts';
+// How many trailing characters of a pasted secret to leave visible so the user
+// can confirm what landed (e.g. `••••••a1b2`). Kept small on purpose.
+const REVEAL_TAIL_COUNT = 4;
+/**
+ * Mask every character of `userInput` except the last `tail`, but only reveal the
+ * tail once the secret is long enough that the hidden portion still dominates
+ * (`length > tail * 2`). Short secrets stay fully masked so we never expose most
+ * of a small value. The returned string keeps the same code-unit length as the
+ * input so clack's cursor slicing in `userInputWithCursor` stays aligned.
+ *
+ * @internal
+ */
+export function maskRevealingTail(userInput, maskChar, tail) {
+    const revealLength = userInput.length > tail * 2 ? tail : 0;
+    const hiddenLength = userInput.length - revealLength;
+    return maskChar.repeat(hiddenLength) + userInput.slice(hiddenLength);
+}
+class RevealTailPasswordPrompt extends PasswordPrompt {
+    #maskChar;
+    #tail;
+    constructor(options) {
+        super(options);
+        this.#maskChar = options.mask ?? S_PASSWORD_MASK;
+        this.#tail = options.tail;
+    }
+    get masked() {
+        return maskRevealingTail(this.userInput, this.#maskChar, this.#tail);
+    }
+}
+// Reproduces the @clack/prompts password frame (pinned to the installed version)
+// so this prompt is visually identical to every other setup prompt; the only
+// behavioral change is the tail-revealing `masked` getter above.
+function renderPasswordFrame(prompt, message) {
+    const withGuide = settings.withGuide;
+    const title = `${withGuide ? `${styleText('gray', S_BAR)}\n` : ''}${symbol(prompt.state)}  ${message}\n`;
+    const masked = prompt.masked;
+    switch (prompt.state) {
+        case 'error': {
+            const bar = withGuide ? `${styleText('yellow', S_BAR)}  ` : '';
+            const end = withGuide ? `${styleText('yellow', S_BAR_END)}  ` : '';
+            return `${title.trim()}\n${bar}${masked}\n${end}${styleText('yellow', prompt.error)}\n`;
+        }
+        case 'submit': {
+            const bar = withGuide ? `${styleText('gray', S_BAR)}  ` : '';
+            return `${title}${bar}${masked ? styleText('dim', masked) : ''}`;
+        }
+        case 'cancel': {
+            const bar = withGuide ? `${styleText('gray', S_BAR)}  ` : '';
+            const body = masked ? styleText(['strikethrough', 'dim'], masked) : '';
+            return `${title}${bar}${body}${masked && withGuide ? `\n${styleText('gray', S_BAR)}` : ''}`;
+        }
+        default: {
+            const bar = withGuide ? `${styleText('cyan', S_BAR)}  ` : '';
+            const end = withGuide ? styleText('cyan', S_BAR_END) : '';
+            return `${title}${bar}${prompt.userInputWithCursor}\n${end}\n`;
+        }
+    }
+}
+/**
+ * Drop-in replacement for clack's `password()` that reveals the last few
+ * characters of the entered value while typing. Resolves to the raw value or the
+ * clack cancel symbol, matching `password()`'s contract.
+ */
+export function revealPassword(options) {
+    const prompt = new RevealTailPasswordPrompt({
+        mask: options.mask ?? S_PASSWORD_MASK,
+        tail: options.tail ?? REVEAL_TAIL_COUNT,
+        validate: options.validate,
+        signal: options.signal,
+        render() {
+            return renderPasswordFrame(this, options.message);
+        },
+    });
+    return prompt.prompt();
+}

package/dist/scan.js

@@ -5,7 +5,8 @@ import { resolveProjectEmbeddingProvider } from './embedding-resolution.js';
 import { createKtxCliLocalIngestAdapters } from './local-adapters.js';
 import { createKtxCliScanConnector } from './local-scan-connectors.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 { formatErrorDetail, scrubErrorClass } from './telemetry/scrubber.js';
 profileMark('module:scan');
 function shouldUseStyledOutput(io) {
@@ -248,8 +249,9 @@ export function createCliScanProgress(io, state = { progress: 0, hasPendingTrans
 }
 export async function runKtxScan(args, io = process, deps = {}) {
     const startedAt = performance.now();
+    let project;
     try {
-        const project = await loadKtxProject({ projectDir: args.projectDir });
+        project = await loadKtxProject({ projectDir: args.projectDir });
         const resolveEmbeddingProvider = deps.resolveEmbeddingProvider ?? resolveProjectEmbeddingProvider;
         const resolution = await resolveEmbeddingProvider(project, {
             mode: 'ensure',
@@ -323,6 +325,20 @@ export async function runKtxScan(args, io = process, deps = {}) {
                 ...(errorDetail ? { errorDetail } : {}),
             },
         });
+        await reportException({
+            error,
+            context: { source: 'scan run', handled: true, fatal: false },
+            projectDir: args.projectDir,
+            io,
+            redactionSecrets: await collectTelemetryRedactionSecrets({
+                project,
+                projectDir: args.projectDir,
+                connectionId: args.connectionId,
+                includeLlm: true,
+                includeEmbeddings: true,
+                env: process.env,
+            }),
+        });
         io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
         return 1;
     }

package/dist/setup-databases.d.ts

@@ -12,6 +12,7 @@ export type KtxSetupDatabaseDriver = 'sqlite' | 'postgres' | 'mysql' | 'clickhou
 export interface KtxSetupDatabasesArgs {
     projectDir: string;
     inputMode: 'auto' | 'disabled';
+    debug?: boolean;
     yes?: boolean;
     cliVersion?: string;
     runtimeInstallPolicy?: KtxManagedPythonInstallPolicy;

package/dist/setup-databases.js

@@ -1206,7 +1206,10 @@ function hasServiceAccountsBlock(connection) {
     }
     return 'serviceAccounts' in filters;
 }
-function printQueryHistoryFilterProposal(io, proposal) {
+function printQueryHistoryFilterProposal(io, proposal, debug = false) {
+    if (debug && proposal.parseFailedTemplateIds.length > 0) {
+        io.stderr.write(`[debug] query-history filter picker could not parse ${proposal.parseFailedTemplateIds.length} template(s): ${proposal.parseFailedTemplateIds.join(', ')}\n`);
+    }
     if (proposal.excludedRoles.length === 0) {
         if (proposal.skipped?.reason === 'no-llm') {
             io.stdout.write('│  Query-history filter picker skipped: no LLM is configured.\n');
@@ -1217,6 +1220,10 @@ function printQueryHistoryFilterProposal(io, proposal) {
         else if (proposal.skipped?.reason === 'no-in-scope-history') {
             io.stdout.write('│  Query-history filter picker found no in-scope service-account exclusions.\n');
         }
+        if (proposal.parseFailedTemplateIds.length > 0) {
+            const count = proposal.parseFailedTemplateIds.length;
+            io.stdout.write(`│  Skipped ${count} query template${count === 1 ? '' : 's'} ktx could not parse (run with --debug to list them).\n`);
+        }
         for (const warning of proposal.warnings) {
             io.stdout.write(`│  ! ${warning}\n`);
         }
@@ -1286,7 +1293,8 @@ async function maybeProposeQueryHistoryFilters(input) {
             consideredRoleCount: 0,
             skipped: { reason: 'no-llm' },
             warnings: [],
-        });
+            parseFailedTemplateIds: [],
+        }, input.args.debug === true);
         return;
     }
     const runtime = createKtxCliHistoricSqlRuntime(project, input.connectionId, {
@@ -1325,7 +1333,19 @@ async function maybeProposeQueryHistoryFilters(input) {
         pullConfig,
         userServiceAccountsPresent,
     });
-    printQueryHistoryFilterProposal(input.io, proposal);
+    printQueryHistoryFilterProposal(input.io, proposal, input.args.debug === true);
+    await emitTelemetryEvent({
+        name: 'query_history_filter_completed',
+        projectDir: input.projectDir,
+        io: input.io,
+        fields: {
+            dialect,
+            consideredRoleCount: proposal.consideredRoleCount,
+            excludedRoleCount: proposal.excludedRoles.length,
+            parseFailedCount: proposal.parseFailedTemplateIds.length,
+            outcome: 'ok',
+        },
+    });
     if (proposal.skipped?.reason === 'user-block-present') {
         input.io.stdout.write('│  Existing query-history service-account filters left unchanged.\n');
         return;