@kaelio/ktx 0.8.0 → 0.10.0

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/next-steps.js

@@ -53,8 +53,7 @@ export function formatSetupNextStepLines(state, indent = '  ') {
     }
     if (!state.contextReady) {
         return [
-            `${indent}Build KTX context next.`,
-            `${indent}Run ingest to build database schema context before context-source ingest.`,
+            `${indent}Setup is complete. The only step left is to build context for your agents.`,
             ...commandLines(KTX_CONTEXT_BUILD_COMMANDS, indent),
         ];
     }

package/dist/progress-port-adapter.d.ts

@@ -0,0 +1,6 @@
+import type { KtxProgressPort } from './context/scan/types.js';
+import type { KtxIngestProgressUpdate } from './ingest.js';
+export interface AggregateProgressState {
+    progress: number;
+}
+export declare function createAggregateProgressPort(onProgress: (update: KtxIngestProgressUpdate) => void, state?: AggregateProgressState, start?: number, weight?: number): KtxProgressPort;

package/dist/progress-port-adapter.js

@@ -0,0 +1,18 @@
+export function createAggregateProgressPort(onProgress, state = { progress: 0 }, start = 0, weight = 1) {
+    return {
+        async update(value, message, options) {
+            const absoluteValue = start + Math.max(0, Math.min(1, value)) * weight;
+            state.progress = Math.max(state.progress, Math.min(1, absoluteValue));
+            if (!message)
+                return;
+            onProgress({
+                percent: Math.max(0, Math.min(100, Math.round(state.progress * 100))),
+                message,
+                ...(options?.transient !== undefined ? { transient: options.transient } : {}),
+            });
+        },
+        startPhase(phaseWeight) {
+            return createAggregateProgressPort(onProgress, state, state.progress, weight * phaseWeight);
+        },
+    };
+}

package/dist/public-ingest.d.ts

@@ -5,6 +5,7 @@ import type { KtxIngestArgs, KtxIngestDeps, KtxIngestProgressUpdate } from './in
 import { type KtxManagedPythonInstallPolicy, type ManagedPythonCommandRuntime } from './managed-python-command.js';
 import type { KtxRuntimeFeature } from './managed-python-runtime.js';
 import type { KtxScanArgs, KtxScanDeps } from './scan.js';
+import type { KtxTableRef } from './context/scan/types.js';
 type KtxPublicIngestStepName = 'database-schema' | 'query-history' | 'source-ingest' | 'memory-update';
 type KtxPublicIngestStepStatus = 'done' | 'skipped' | 'failed' | 'not-run';
 type KtxPublicIngestInputMode = 'auto' | 'disabled';
@@ -98,6 +99,17 @@ interface KtxPublicContextBuildArgs {
     cliVersion?: string;
     runtimeInstallPolicy?: KtxManagedPythonInstallPolicy;
 }
+export declare function publicProgressMessage(message: string, target: KtxPublicIngestPlanTarget): string;
+/** @internal */
+export declare function queryHistoryPullConfig(input: {
+    stored: Record<string, unknown>;
+    dialect: HistoricSqlDialect;
+    windowDays?: number;
+    enabledTables?: KtxTableRef[];
+    enabledSchemas?: string[];
+    modeledTableCatalog?: KtxTableRef[];
+    scopeFloorWarnings?: string[];
+}): Record<string, unknown>;
 export declare function buildPublicIngestPlan(project: KtxPublicIngestProject, args: {
     projectDir: string;
     targetConnectionId?: string;
@@ -108,8 +120,15 @@ export declare function buildPublicIngestPlan(project: KtxPublicIngestProject, a
         command: 'run';
     }>['mode'];
 }): KtxPublicIngestPlan;
+/**
+ * Run one ingest target through its scan/ingest steps. The single per-target
+ * chokepoint reached by every entrypoint — standalone `ktx ingest` (plain/json
+ * and foreground) and `ktx setup` (via `runContextBuild`). The exported
+ * `executePublicIngestTarget` wraps this and emits the `ingest_completed`
+ * telemetry event exactly once, so every path is counted.
+ */
 export declare function executePublicIngestTarget(target: KtxPublicIngestPlanTarget, args: Extract<KtxPublicIngestArgs, {
     command: 'run';
-}>, io: KtxCliIo, deps: KtxPublicIngestDeps): Promise<KtxPublicIngestTargetResult>;
+}>, io: KtxCliIo, deps: KtxPublicIngestDeps, project: KtxPublicIngestProject): Promise<KtxPublicIngestTargetResult>;
 export declare function runKtxPublicIngest(args: KtxPublicIngestArgs, io: KtxCliIo, deps?: KtxPublicIngestDeps): Promise<number>;
 export {};

package/dist/public-ingest.js

@@ -1,12 +1,16 @@
 import { getKtxCliPackageInfo } from './cli-runtime.js';
 import { loadKtxProject } from './context/project/project.js';
 import { isDatabaseDriver, normalizeConnectionDriver } from './connection-drivers.js';
+import { resolveQueryHistoryScopeFloor } from './context/ingest/adapters/historic-sql/scope-floor.js';
 import { ensureManagedPythonCommandRuntime, } from './managed-python-command.js';
-import { publicIngestOutputLine } from './public-ingest-copy.js';
+import { publicDatabaseIngestMessage, publicIngestOutputLine, publicQueryHistoryMessage, } from './public-ingest-copy.js';
+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([
     ['metabase', 'metabase'],
@@ -17,6 +21,16 @@ const sourceAdapterByDriver = new Map([
     ['dbt', 'dbt'],
     ['lookml', 'lookml'],
 ]);
+export function publicProgressMessage(message, target) {
+    let current = message;
+    if (target.operation === 'database-ingest') {
+        current = publicDatabaseIngestMessage(current);
+    }
+    if (target.steps.includes('query-history')) {
+        current = publicQueryHistoryMessage(current, target.connectionId);
+    }
+    return current;
+}
 const queryHistoryDialectByDriver = new Map([
     ['postgres', 'postgres'],
     ['bigquery', 'bigquery'],
@@ -99,20 +113,20 @@ function storedQueryHistory(connection) {
 function positiveInteger(value) {
     return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
 }
-function enabledTablesForConnection(connection) {
-    const raw = connection.enabled_tables;
-    if (!Array.isArray(raw)) {
-        return undefined;
-    }
-    const tables = raw.filter((value) => typeof value === 'string' && value.trim().length > 0);
-    return tables.length > 0 ? tables : undefined;
-}
-function queryHistoryPullConfig(input) {
-    const { enabled: _enabled, dialect: _dialect, ...storedConfig } = input.stored;
+/** @internal */
+export function queryHistoryPullConfig(input) {
+    const { enabled: _enabled, dialect: _dialect, enabledTables: _enabledTables, enabledSchemas: _enabledSchemas, scopeFloorWarnings: _scopeFloorWarnings, ...storedConfig } = input.stored;
     return {
         ...storedConfig,
         dialect: input.dialect,
-        ...(input.enabledTables ? { enabledTables: input.enabledTables } : {}),
+        ...(input.enabledTables && input.enabledTables.length > 0 ? { enabledTables: input.enabledTables } : {}),
+        ...(input.enabledSchemas && input.enabledSchemas.length > 0 ? { enabledSchemas: input.enabledSchemas } : {}),
+        ...(input.modeledTableCatalog && input.modeledTableCatalog.length > 0
+            ? { modeledTableCatalog: input.modeledTableCatalog }
+            : {}),
+        ...(input.scopeFloorWarnings && input.scopeFloorWarnings.length > 0
+            ? { scopeFloorWarnings: input.scopeFloorWarnings }
+            : {}),
         ...(input.windowDays !== undefined ? { windowDays: input.windowDays } : {}),
     };
 }
@@ -157,7 +171,6 @@ function resolveDatabaseTargetOptions(input) {
                     stored: storedQh,
                     dialect,
                     windowDays: queryHistory.windowDays,
-                    enabledTables: enabledTablesForConnection(input.connection),
                 }),
             },
             steps: ['database-schema', 'query-history'],
@@ -168,6 +181,37 @@ function resolveDatabaseTargetOptions(input) {
         steps: ['database-schema'],
     };
 }
+async function resolvedQueryHistoryPullConfigForTarget(target, project) {
+    if (target.operation !== 'database-ingest' || target.queryHistory?.enabled !== true || !target.queryHistory.dialect) {
+        return null;
+    }
+    const connection = project.config.connections[target.connectionId];
+    if (!connection) {
+        return (target.queryHistory.pullConfig ??
+            queryHistoryPullConfig({
+                stored: {},
+                dialect: target.queryHistory.dialect,
+                windowDays: target.queryHistory.windowDays,
+            }));
+    }
+    const stored = storedQueryHistory(connection);
+    const scopeFloor = await resolveQueryHistoryScopeFloor({
+        projectDir: project.projectDir,
+        connectionId: target.connectionId,
+        driver: target.driver,
+        connection: connection,
+        storedQueryHistory: stored,
+    });
+    return queryHistoryPullConfig({
+        stored,
+        dialect: target.queryHistory.dialect,
+        windowDays: target.queryHistory.windowDays,
+        enabledTables: scopeFloor.enabledTables,
+        enabledSchemas: scopeFloor.enabledSchemas,
+        modeledTableCatalog: scopeFloor.modeledTableCatalog,
+        scopeFloorWarnings: scopeFloor.warnings,
+    });
+}
 function enrichmentReadinessGaps(config) {
     const gaps = [];
     if (config.llm.provider.backend === 'none' || !config.llm.models.default) {
@@ -348,6 +392,9 @@ function rowsBucket() {
 }
 async function emitIngestCompleted(input) {
     const failed = resultFailed(input.result);
+    const failureDetail = failed
+        ? formatErrorDetail(input.result.steps.find((step) => step.status === 'failed')?.detail)
+        : undefined;
     await emitTelemetryEvent({
         name: 'ingest_completed',
         projectDir: input.args.projectDir,
@@ -361,6 +408,7 @@ async function emitIngestCompleted(input) {
             rowsBucket: rowsBucket(),
             durationMs: Math.max(0, performance.now() - input.startedAt),
             outcome: failed ? 'error' : 'ok',
+            ...(failureDetail ? { errorDetail: failureDetail } : {}),
         },
     });
 }
@@ -427,6 +475,65 @@ function createCapturedPublicIngestIo() {
         },
     };
 }
+function isCapturedPublicIngestIo(io) {
+    return typeof io.capturedOutput === 'function';
+}
+const PLAIN_PUBLIC_INGEST_PHASE_LABELS = {
+    'database-schema': 'database schema',
+    'query-history': 'query history',
+    'source-ingest': 'source ingest',
+};
+function firstSummaryLine(summary) {
+    if (!summary)
+        return undefined;
+    return summary.split(/\r?\n/).find((line) => line.trim().length > 0)?.trim();
+}
+function plainPhaseHeader(options, phaseKey) {
+    const prefix = options.total > 1 ? `[${options.index + 1}/${options.total}] ` : '';
+    return `${prefix}${options.target.connectionId} · ${PLAIN_PUBLIC_INGEST_PHASE_LABELS[phaseKey]}`;
+}
+function plainPhaseEndLine(status, summary) {
+    const firstLine = firstSummaryLine(summary);
+    return firstLine ? `  ${status} · ${firstLine}` : `  ${status}`;
+}
+function createPlainPublicIngestProgress(io, options) {
+    let currentPhase = null;
+    const startedPhases = new Set();
+    const lastPercentByPhase = new Map();
+    const startPhase = (phaseKey) => {
+        currentPhase = phaseKey;
+        startedPhases.add(phaseKey);
+        lastPercentByPhase.set(phaseKey, -1);
+        io.stderr.write(`${plainPhaseHeader(options, phaseKey)}\n`);
+    };
+    const ensurePhaseStarted = (phaseKey) => {
+        if (!startedPhases.has(phaseKey)) {
+            startPhase(phaseKey);
+            return;
+        }
+        currentPhase = phaseKey;
+    };
+    const emitProgress = (update) => {
+        if (currentPhase === null)
+            return;
+        const rounded = Math.max(0, Math.min(100, Math.round(update.percent)));
+        const lastPercent = lastPercentByPhase.get(currentPhase) ?? -1;
+        if (rounded <= lastPercent)
+            return;
+        lastPercentByPhase.set(currentPhase, rounded);
+        io.stderr.write(`  [${rounded}%] ${publicProgressMessage(update.message, options.target)}\n`);
+    };
+    return {
+        onPhaseStart: startPhase,
+        onPhaseEnd(phaseKey, status, summary) {
+            ensurePhaseStarted(phaseKey);
+            io.stderr.write(`${plainPhaseEndLine(status, summary)}\n`);
+            currentPhase = null;
+        },
+        scanProgress: createAggregateProgressPort(emitProgress),
+        ingestProgress: emitProgress,
+    };
+}
 const INTERNAL_STATUS_LINE_RE = /^(Report|Run|Job|Status|Adapter|Connection|Sync|Diff|Tasks|Work units|Failed tasks|Saved memory|Provenance rows):\s*/;
 const ACTIONABLE_FAILURE_LINE_RE = /^(Missing bundled Python runtime manifest|KTX Python runtime is required|KTX daemon HTTP|Error:|Failed\b|Could not\b|Cannot\b)/;
 const RUNTIME_BACKED_RETRY_LINE_RE = /^Then retry the runtime-backed KTX command\.?$/;
@@ -457,7 +564,23 @@ function capturedFailureMessage(output) {
         .filter((line) => line.startsWith('In a source checkout, build the local runtime assets with:'));
     return [firstLine, ...followupLines].join('\n');
 }
-export async function executePublicIngestTarget(target, args, io, deps) {
+/**
+ * Run one ingest target through its scan/ingest steps. The single per-target
+ * chokepoint reached by every entrypoint — standalone `ktx ingest` (plain/json
+ * and foreground) and `ktx setup` (via `runContextBuild`). The exported
+ * `executePublicIngestTarget` wraps this and emits the `ingest_completed`
+ * telemetry event exactly once, so every path is counted.
+ */
+export async function executePublicIngestTarget(target, args, io, deps, project) {
+    const startedAt = performance.now();
+    const result = await runIngestTargetSteps(target, args, io, deps, project);
+    // `io` may be a capture buffer for the scan/ingest step output; the telemetry
+    // debug echo belongs on the real user-facing stream, which callers expose as
+    // `deps.runtimeIo` (falling back to `io` when the step io is already real).
+    await emitIngestCompleted({ args, project, target, result, startedAt, io: deps.runtimeIo ?? io });
+    return result;
+}
+async function runIngestTargetSteps(target, args, io, deps, project) {
     if (target.preflightFailure) {
         if (target.operation === 'database-ingest') {
             deps.onPhaseEnd?.('database-schema', 'failed', target.preflightFailure);
@@ -475,7 +598,7 @@ export async function executePublicIngestTarget(target, args, io, deps) {
                 ? {
                     ...step,
                     status: 'failed',
-                    detail: target.preflightFailure,
+                    detail: `${target.connectionId} failed: ${target.preflightFailure}`,
                 }
                 : step),
         };
@@ -493,7 +616,11 @@ export async function executePublicIngestTarget(target, args, io, deps) {
             ...(args.runtimeInstallPolicy ? { runtimeInstallPolicy: args.runtimeInstallPolicy } : {}),
         };
         const runScan = deps.runScan ?? runKtxScan;
-        const capturedScanIo = deps.scanProgress ? null : createCapturedPublicIngestIo();
+        const capturedScanIo = deps.scanProgress
+            ? isCapturedPublicIngestIo(io)
+                ? io
+                : null
+            : createCapturedPublicIngestIo();
         const scanIo = capturedScanIo ?? io;
         const scanDeps = {
             ...(deps.scanProgress ? { progress: deps.scanProgress } : {}),
@@ -512,6 +639,10 @@ export async function executePublicIngestTarget(target, args, io, deps) {
         if (target.queryHistory?.enabled === true) {
             const { runKtxIngest } = await import('./ingest.js');
             const runIngest = deps.runIngest ?? runKtxIngest;
+            const historicSqlPullConfigOverride = (await resolvedQueryHistoryPullConfigForTarget(target, project)) ?? {
+                dialect: target.queryHistory.dialect,
+                ...(target.queryHistory.windowDays !== undefined ? { windowDays: target.queryHistory.windowDays } : {}),
+            };
             const ingestArgs = {
                 command: 'run',
                 projectDir: args.projectDir,
@@ -522,12 +653,14 @@ export async function executePublicIngestTarget(target, args, io, deps) {
                 ...(args.cliVersion ? { cliVersion: args.cliVersion } : {}),
                 ...(args.runtimeInstallPolicy ? { runtimeInstallPolicy: args.runtimeInstallPolicy } : {}),
                 allowImplicitAdapter: true,
-                historicSqlPullConfigOverride: target.queryHistory.pullConfig ?? {
-                    dialect: target.queryHistory.dialect,
-                    ...(target.queryHistory.windowDays !== undefined ? { windowDays: target.queryHistory.windowDays } : {}),
-                },
+                historicSqlPullConfigOverride,
             };
-            const capturedIngestIo = deps.ingestProgress ? null : createCapturedPublicIngestIo();
+            // Query history runs after the schema scan has already written its report
+            // into the shared target io, so it needs a phase-local capture. Reusing
+            // `io` here would let leftover scan text (e.g. "Mode: enriched") surface as
+            // the query-history failure detail. Only skip capture when progress is
+            // active and the caller manages its own buffer (io is not a capture).
+            const capturedIngestIo = deps.ingestProgress && !isCapturedPublicIngestIo(io) ? null : createCapturedPublicIngestIo();
             const ingestIo = capturedIngestIo ?? io;
             const ingestDeps = {
                 ...(deps.ingestProgress ? { progress: deps.ingestProgress } : {}),
@@ -564,7 +697,11 @@ export async function executePublicIngestTarget(target, args, io, deps) {
         allowImplicitAdapter: true,
     };
     const runIngest = deps.runIngest ?? runKtxIngest;
-    const capturedIngestIo = deps.ingestProgress ? null : createCapturedPublicIngestIo();
+    const capturedIngestIo = deps.ingestProgress
+        ? isCapturedPublicIngestIo(io)
+            ? io
+            : null
+        : createCapturedPublicIngestIo();
     const ingestIo = capturedIngestIo ?? io;
     const ingestDeps = {
         ...(deps.ingestProgress ? { progress: deps.ingestProgress } : {}),
@@ -597,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 = [];
@@ -628,11 +799,26 @@ export async function runKtxPublicIngest(args, io, deps = {}) {
             io.stderr.write(`Warning: ${warning}\n`);
         }
     }
-    for (const target of plan.targets) {
-        const startedAt = performance.now();
-        const result = await executePublicIngestTarget(target, args, io, deps);
-        results.push(result);
-        await emitIngestCompleted({ args, project, target, result, startedAt, io });
+    for (const [index, target] of plan.targets.entries()) {
+        if (args.json) {
+            results.push(await executePublicIngestTarget(target, args, io, deps, project));
+            continue;
+        }
+        const capture = createCapturedPublicIngestIo();
+        const progress = createPlainPublicIngestProgress(io, {
+            target,
+            index,
+            total: plan.targets.length,
+        });
+        const targetDeps = {
+            ...deps,
+            scanProgress: progress.scanProgress,
+            ingestProgress: progress.ingestProgress,
+            onPhaseStart: progress.onPhaseStart,
+            onPhaseEnd: progress.onPhaseEnd,
+            runtimeIo: deps.runtimeIo ?? io,
+        };
+        results.push(await executePublicIngestTarget(target, args, capture, targetDeps, project));
     }
     if (args.json) {
         io.stdout.write(`${JSON.stringify({ plan, results }, null, 2)}\n`);

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();
+}