@kaelio/ktx 0.9.0 → 0.11.0

package/dist/setup-sources.js

@@ -29,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([
@@ -146,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' },
             ],
         });
@@ -179,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' },
             ],
@@ -800,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' },
                     ],
                 });
@@ -1101,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' },
                 ],
             });
@@ -1667,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' },
                         ],

package/dist/setup.d.ts

@@ -1,5 +1,6 @@
 import { type KtxCliIo } from './cli-runtime.js';
 import { readManagedPythonRuntimeStatus } from './managed-python-runtime.js';
+import type { CommandOutcome } from './telemetry/index.js';
 import { type KtxAgentScope, type KtxAgentTarget, type KtxSetupAgentsDeps, runKtxSetupAgentsStep } from './setup-agents.js';
 import { type KtxSetupDatabaseDriver, type KtxSetupDatabasesDeps, runKtxSetupDatabasesStep } from './setup-databases.js';
 import { type KtxSetupEmbeddingsDeps, runKtxSetupEmbeddingsStep } from './setup-embeddings.js';
@@ -58,12 +59,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;
@@ -125,6 +126,7 @@ export interface KtxSetupDeps {
     entryMenuDeps?: KtxSetupEntryMenuDeps;
     setupUi?: KtxSetupUiAdapter;
 }
+type TelemetrySetupStep = 'project' | 'runtime' | 'models' | 'embeddings' | 'databases' | 'sources' | 'context' | 'agents' | 'demo-tour';
 export interface KtxSetupEntryMenuPromptAdapter {
     select(options: {
         message: string;
@@ -135,6 +137,28 @@ export interface KtxSetupEntryMenuPromptAdapter {
 export interface KtxSetupEntryMenuDeps {
     prompts?: KtxSetupEntryMenuPromptAdapter;
 }
+interface SetupCommandAnnotation {
+    outcome: CommandOutcome;
+    errorClass?: string;
+    errorDetail?: string;
+}
+/**
+ * Single source of truth for how a non-ready setup step ends: the process exit
+ * code and the telemetry annotation are both derived from one classification,
+ * so they can never disagree. A genuine failure (`error`) exits non-zero; an
+ * abort — the user leaving an interactive wizard — exits 0, matching the entry
+ * menu's "Exit", a project cancellation, and a confirmed Ctrl+C.
+ */
+/** @internal */
+export declare function setupTerminalOutcome(input: {
+    status: 'failed' | 'missing-input' | 'cancelled';
+    step: TelemetrySetupStep;
+    interactive: boolean;
+    errorDetail?: string;
+}): {
+    exitCode: number;
+    annotation: SetupCommandAnnotation;
+};
 export interface ReadKtxSetupStatusOptions {
     cliVersion?: string;
     env?: NodeJS.ProcessEnv;
@@ -146,3 +170,4 @@ export declare function formatKtxSetupCompletionSummary(status: KtxSetupStatus,
     agentNextActions?: string;
 }): string;
 export declare function runKtxSetup(args: KtxSetupArgs, io: KtxCliIo, deps?: KtxSetupDeps): Promise<number>;
+export {};

package/dist/setup.js

@@ -6,6 +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 { SLACK_SETUP_NOTE } from './community-cta.js';
 import { formatNextStepLines, formatSetupNextStepLines } from './next-steps.js';
 import { runtimeInstallPolicyFromFlags } from './managed-python-command.js';
 import { readManagedPythonRuntimeStatus } from './managed-python-runtime.js';
@@ -36,6 +37,61 @@ function setupTelemetryOutcome(status) {
         return 'skipped';
     return 'abandoned';
 }
+/**
+ * Classify a terminal non-ready setup status into the `command` telemetry
+ * outcome. The setup flow is the decision-maker and knows the difference:
+ * - `failed` is a genuine error; attach a step-scoped reason so the dashboard
+ *   shows an actionable signature instead of a blank.
+ * - `missing-input` from a *non-interactive* run is an automation error
+ *   (required flags absent and no prompt was possible); attach a reason too.
+ * - `missing-input` from an interactive prompt, or a project `cancelled`, is the
+ *   user backing out of the wizard — an abort, not a failure. Keep it out of
+ *   error telemetry so it stops inflating the error count.
+ *
+ * `interactive` must reflect whether a prompt could actually be shown — input
+ * is enabled AND a TTY is attached. `inputMode: 'auto'` alone is not enough: a
+ * piped/CI run without `--no-input` is still non-interactive, and steps such as
+ * the project step return `missing-input` ("pass --yes …") there without ever
+ * prompting. Treating that as an abort would make a broken automation run exit
+ * 0, so it must classify as an error.
+ *
+ * Reasons are synthetic, step-scoped strings (no user input), so they satisfy
+ * the telemetry privacy rules. The step's own `errorDetail`, when present, has
+ * already been vetted for the `setup_step` event and is safe to reuse.
+ */
+function setupCommandOutcomeAnnotation(input) {
+    if (input.status === 'failed') {
+        return {
+            outcome: 'error',
+            errorClass: 'KtxSetupStepFailed',
+            errorDetail: input.errorDetail ?? `${input.step} setup step failed`,
+        };
+    }
+    if (input.status === 'missing-input' && !input.interactive) {
+        return {
+            outcome: 'error',
+            errorClass: 'KtxSetupMissingInput',
+            errorDetail: `${input.step} setup step requires input not provided in a non-interactive run`,
+        };
+    }
+    return { outcome: 'aborted' };
+}
+/**
+ * Single source of truth for how a non-ready setup step ends: the process exit
+ * code and the telemetry annotation are both derived from one classification,
+ * so they can never disagree. A genuine failure (`error`) exits non-zero; an
+ * abort — the user leaving an interactive wizard — exits 0, matching the entry
+ * menu's "Exit", a project cancellation, and a confirmed Ctrl+C.
+ */
+/** @internal */
+export function setupTerminalOutcome(input) {
+    const annotation = setupCommandOutcomeAnnotation(input);
+    return { exitCode: annotation.outcome === 'error' ? 1 : 0, annotation };
+}
+async function annotateSetupCommandOutcome(annotation) {
+    const { annotateCommandOutcome } = await import('./telemetry/index.js');
+    annotateCommandOutcome(annotation);
+}
 async function recordSetupStep(input) {
     const { emitTelemetryEvent } = await import('./telemetry/index.js');
     await emitTelemetryEvent({
@@ -325,6 +381,10 @@ async function runKtxSetupInner(args, io, deps = {}) {
         args.inputMode !== 'disabled' &&
         !args.agents &&
         (io.stdout.isTTY === true || deps.entryMenuDeps?.prompts !== undefined);
+    // A prompt is only possible when input is enabled AND a TTY is attached. A
+    // piped/CI `ktx setup` without `--no-input` is still `inputMode: 'auto'` but
+    // cannot prompt, so its `missing-input` is an automation error, not an abort.
+    const interactive = args.inputMode !== 'disabled' && io.stdout.isTTY === true;
     setupLoop: while (true) {
         entryAction = undefined;
         if (canShowEntryMenu) {
@@ -363,7 +423,13 @@ async function runKtxSetupInner(args, io, deps = {}) {
             continue;
         }
         if (projectResult.status !== 'ready') {
-            return projectResult.status === 'cancelled' ? 0 : 1;
+            const terminal = setupTerminalOutcome({
+                status: projectResult.status,
+                step: 'project',
+                interactive,
+            });
+            await annotateSetupCommandOutcome(terminal.annotation);
+            return terminal.exitCode;
         }
         const agentsRequested = args.agents || entryAction === 'agents';
         const currentStatus = await readKtxSetupStatus(projectResult.projectDir, { cliVersion: args.cliVersion });
@@ -443,7 +509,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',
@@ -473,6 +538,7 @@ 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),
@@ -576,11 +642,15 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 cliVersion: args.cliVersion,
                 ...(stepResult.errorDetail ? { errorDetail: stepResult.errorDetail } : {}),
             });
-            if (stepResult.status === 'failed') {
-                return 1;
-            }
-            if (stepResult.status === 'missing-input') {
-                return 1;
+            if (stepResult.status === 'failed' || stepResult.status === 'missing-input') {
+                const terminal = setupTerminalOutcome({
+                    status: stepResult.status,
+                    step,
+                    interactive,
+                    ...(stepResult.errorDetail ? { errorDetail: stepResult.errorDetail } : {}),
+                });
+                await annotateSetupCommandOutcome(terminal.annotation);
+                return terminal.exitCode;
             }
             if (stepResult.status === 'back') {
                 const previousIndex = previousNavigableStepIndex(stepIndex);
@@ -630,5 +700,6 @@ async function runKtxSetupInner(args, io, deps = {}) {
             }).join('\n'), 'What you can do next', io);
         }
     }
+    setupUi.note(SLACK_SETUP_NOTE.body, SLACK_SETUP_NOTE.title, io);
     return 0;
 }

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 {};

package/dist/star-prompt/star-count.js

@@ -0,0 +1,66 @@
+import { request as httpsRequest } from 'node:https';
+import { URL } from 'node:url';
+import { z } from 'zod';
+const GITHUB_REPO_URL = new URL('https://api.github.com/repos/Kaelio/ktx');
+const DEFAULT_TIMEOUT_MS = 5000;
+const githubRepoSchema = z.object({
+    stargazers_count: z.number().int().nonnegative(),
+});
+function parseStarCount(raw) {
+    return githubRepoSchema.parse(JSON.parse(raw)).stargazers_count;
+}
+export function fetchGitHubStarCount(options = {}) {
+    const requestImpl = options.request ?? httpsRequest;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (count) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve(count);
+        };
+        try {
+            const request = requestImpl(GITHUB_REPO_URL, {
+                method: 'GET',
+                headers: {
+                    accept: 'application/vnd.github+json',
+                    'user-agent': 'ktx-star-prompt',
+                },
+            }, (response) => {
+                const chunks = [];
+                response.on('data', (chunk) => {
+                    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                });
+                response.on('end', () => {
+                    const statusCode = response.statusCode ?? 0;
+                    if (statusCode < 200 || statusCode >= 300) {
+                        finish(null);
+                        return;
+                    }
+                    try {
+                        finish(parseStarCount(Buffer.concat(chunks).toString('utf8')));
+                    }
+                    catch {
+                        finish(null);
+                    }
+                });
+            });
+            request.on('socket', (socket) => {
+                socket.unref();
+            });
+            request.on('error', () => {
+                finish(null);
+            });
+            request.setTimeout(timeoutMs, () => {
+                request.destroy(new Error('GitHub star count request timed out'));
+                finish(null);
+            });
+            request.end();
+        }
+        catch {
+            finish(null);
+        }
+    });
+}

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

@@ -0,0 +1,12 @@
+interface StarPromptSymbols {
+    star: string;
+    middot: string;
+    rightArrow: string;
+}
+export interface RenderStarPromptLineOptions {
+    columns: number;
+    count?: number | null;
+    symbols?: StarPromptSymbols;
+}
+export declare function renderStarPromptLine(options: RenderStarPromptLineOptions): string;
+export {};

package/dist/star-prompt/star-line.js

@@ -0,0 +1,26 @@
+import { SYMBOLS } from '../io/symbols.js';
+const STAR_PROMPT_URL = 'github.com/Kaelio/ktx';
+const STAR_PROMPT_TEXT = 'This takes a few minutes - mind giving ktx a star while you wait?';
+function usableColumns(columns) {
+    return Number.isFinite(columns) && columns > 0 ? Math.floor(columns) : 80;
+}
+function starCountSegment(count, symbols) {
+    if (typeof count !== 'number' || !Number.isFinite(count)) {
+        return '';
+    }
+    const formatted = new Intl.NumberFormat('en-US').format(count);
+    return ` ${symbols.middot} ${formatted} ${symbols.star}`;
+}
+export function renderStarPromptLine(options) {
+    const symbols = options.symbols ?? SYMBOLS;
+    const columns = usableColumns(options.columns);
+    const base = `  ${symbols.star}  ${STAR_PROMPT_TEXT}  ${STAR_PROMPT_URL}`;
+    const withCount = `${base}${starCountSegment(options.count, symbols)}`;
+    if (withCount.length <= columns) {
+        return withCount;
+    }
+    if (base.length <= columns) {
+        return base;
+    }
+    return `  ${symbols.star} Star ktx ${symbols.rightArrow} ${STAR_PROMPT_URL}`;
+}

package/dist/telemetry/command-hook.d.ts

@@ -6,6 +6,9 @@ interface CommandSpan {
     hasProject: boolean;
     attachProjectGroup: boolean;
     startedAt: number;
+    annotatedOutcome?: CommandOutcome;
+    annotatedErrorClass?: string;
+    annotatedErrorDetail?: string;
 }
 export interface CompletedCommandSpan {
     commandPath: string[];
@@ -19,6 +22,27 @@ export interface CompletedCommandSpan {
     projectGroupAttached: boolean;
 }
 export declare function beginCommandSpan(input: CommandSpan): void;
+/**
+ * Let a command action record the true outcome and reason on the active span.
+ *
+ * The Commander wrapper can only derive an outcome from a thrown error or the
+ * process exit code, so a command that exits non-zero *without throwing* (e.g.
+ * `ktx setup` when the user abandons the wizard) lands as `outcome: 'error'`
+ * with no `errorClass`/`errorDetail` — an unactionable blank in the dashboard.
+ * The action is the decision-maker: it can mark the run `aborted`, or attach a
+ * scrubbed reason so the next occurrence is self-diagnosing. A later thrown
+ * error still wins (see {@link completeCommandSpan}), since that is the most
+ * authoritative signal and also feeds the `$exception` stream. No-ops when no
+ * span is active so call sites stay safe in tests and bare-help paths.
+ *
+ * Values are emitted verbatim and must already satisfy the telemetry privacy
+ * rules — pass synthetic or already-scrubbed strings, never raw user input.
+ */
+export declare function annotateCommandOutcome(input: {
+    outcome?: CommandOutcome;
+    errorClass?: string;
+    errorDetail?: string;
+}): void;
 export declare function completeCommandSpan(input: {
     completedAt: number;
     outcome: CommandOutcome;

package/dist/telemetry/command-hook.js

@@ -3,18 +3,52 @@ let activeCommandSpan;
 export function beginCommandSpan(input) {
     activeCommandSpan = input;
 }
+/**
+ * Let a command action record the true outcome and reason on the active span.
+ *
+ * The Commander wrapper can only derive an outcome from a thrown error or the
+ * process exit code, so a command that exits non-zero *without throwing* (e.g.
+ * `ktx setup` when the user abandons the wizard) lands as `outcome: 'error'`
+ * with no `errorClass`/`errorDetail` — an unactionable blank in the dashboard.
+ * The action is the decision-maker: it can mark the run `aborted`, or attach a
+ * scrubbed reason so the next occurrence is self-diagnosing. A later thrown
+ * error still wins (see {@link completeCommandSpan}), since that is the most
+ * authoritative signal and also feeds the `$exception` stream. No-ops when no
+ * span is active so call sites stay safe in tests and bare-help paths.
+ *
+ * Values are emitted verbatim and must already satisfy the telemetry privacy
+ * rules — pass synthetic or already-scrubbed strings, never raw user input.
+ */
+export function annotateCommandOutcome(input) {
+    if (!activeCommandSpan) {
+        return;
+    }
+    if (input.outcome !== undefined) {
+        activeCommandSpan.annotatedOutcome = input.outcome;
+    }
+    if (input.errorClass !== undefined) {
+        activeCommandSpan.annotatedErrorClass = input.errorClass;
+    }
+    if (input.errorDetail !== undefined) {
+        activeCommandSpan.annotatedErrorDetail = input.errorDetail;
+    }
+}
 export function completeCommandSpan(input) {
     const span = activeCommandSpan;
     activeCommandSpan = undefined;
     if (!span) {
         return undefined;
     }
-    const errorClass = input.error ? scrubErrorClass(input.error) : undefined;
-    const errorDetail = input.error ? formatErrorDetail(input.error) : undefined;
+    // Precedence: a thrown error is authoritative; otherwise an action's own
+    // annotation; otherwise the wrapper's exit-code-derived outcome.
+    const thrown = Boolean(input.error);
+    const outcome = thrown ? input.outcome : (span.annotatedOutcome ?? input.outcome);
+    const errorClass = thrown ? scrubErrorClass(input.error) : span.annotatedErrorClass;
+    const errorDetail = thrown ? formatErrorDetail(input.error) : span.annotatedErrorDetail;
     return {
         commandPath: span.commandPath,
         durationMs: Math.max(0, input.completedAt - span.startedAt),
-        outcome: input.outcome,
+        outcome,
         ...(errorClass ? { errorClass } : {}),
         ...(errorDetail ? { errorDetail } : {}),
         flagsPresent: span.flagsPresent,