@kaelio/ktx 0.8.0 → 0.10.0

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/status-project.d.ts

@@ -62,6 +62,16 @@ type ClaudeCodeAuthProbe = (input: {
     ok: false;
     message: string;
 }>;
+type CodexAuthProbe = (input: {
+    projectDir: string;
+    model: string;
+}) => Promise<{
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    fix: string;
+}>;
 interface LocalStatsIngestPerConnection {
     connectionId: string;
     adapter: string;
@@ -135,6 +145,7 @@ export interface BuildProjectStatusOptions {
     env?: NodeJS.ProcessEnv;
     queryHistoryReadinessProbe?: HistoricSqlReadinessProbe;
     claudeCodeAuthProbe?: ClaudeCodeAuthProbe;
+    codexAuthProbe?: CodexAuthProbe;
     configIssues?: KtxConfigIssue[];
     fast?: boolean;
     useSpinner?: boolean;

package/dist/status-project.js

@@ -1,6 +1,8 @@
 import { stat as statAsync, readdir as readdirAsync } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { runClaudeCodeAuthProbe } from './context/llm/claude-code-runtime.js';
+import { CODEX_ISOLATION_WARNING, CODEX_ISOLATION_WARNING_FIX, } from './context/llm/codex-isolation.js';
+import { runCodexAuthProbe } from './context/llm/codex-runtime.js';
 import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
 import { isQueryHistoryEnabled, queryHistoryDialectForConnection, } from './context/ingest/adapters/historic-sql/connection-dialect.js';
 import { historicSqlProbeCatalogName, runHistoricSqlReadinessProbe, } from './context/ingest/historic-sql-probes.js';
@@ -49,6 +51,18 @@ async function buildLlmStatus(config, options) {
             fix: 'Run: ktx setup (choose an LLM provider)',
         };
     }
+    // The runtime (resolveModelSlots) hard-requires llm.models.default for every
+    // non-none backend; without it ingest/scan/memory throw. Report that here so
+    // status never marks a project ready that the runtime would refuse to run.
+    if (!model || model.trim().length === 0) {
+        return {
+            backend,
+            model,
+            status: 'fail',
+            detail: `llm.models.default is required for backend "${backend}"`,
+            fix: 'Set llm.models.default in ktx.yaml, then rerun `ktx status` (or rerun `ktx setup`).',
+        };
+    }
     if (backend === 'anthropic') {
         const ref = config.provider.anthropic?.api_key;
         const resolved = resolveRef(ref, env);
@@ -90,7 +104,7 @@ async function buildLlmStatus(config, options) {
         };
     }
     if (backend === 'claude-code') {
-        const modelName = model ?? 'sonnet';
+        const modelName = model;
         if (options.fast === true) {
             return {
                 backend,
@@ -117,6 +131,34 @@ async function buildLlmStatus(config, options) {
             fix: 'Authenticate Claude Code locally with the Claude Code CLI, then rerun `ktx status`.',
         };
     }
+    if (backend === 'codex') {
+        const modelName = model;
+        if (options.fast === true) {
+            return {
+                backend,
+                model: modelName,
+                status: 'skipped',
+                detail: 'auth probe skipped (--fast)',
+            };
+        }
+        const probe = options.codexAuthProbe ?? runCodexAuthProbe;
+        const auth = await withSpinner(options.useSpinner === true, 'Probing Codex authentication', () => probe({ projectDir: options.projectDir, model: modelName }));
+        if (auth.ok) {
+            return {
+                backend,
+                model: modelName,
+                status: 'ok',
+                detail: 'local Codex session authenticated',
+            };
+        }
+        return {
+            backend,
+            model: modelName,
+            status: 'fail',
+            detail: auth.message,
+            fix: auth.fix,
+        };
+    }
     return { backend, model, status: 'warn', detail: 'unknown LLM backend' };
 }
 function buildEmbeddingsStatus(config, env) {
@@ -378,6 +420,12 @@ function buildWarnings(config, connections, llm, embeddings) {
             fix: formatClaudeCodePromptCachingFix(),
         });
     }
+    if (llm.backend === 'codex') {
+        warnings.push({
+            message: CODEX_ISOLATION_WARNING,
+            fix: CODEX_ISOLATION_WARNING_FIX,
+        });
+    }
     return warnings;
 }
 function buildVerdict(llm, embeddings, connections, queryHistory, warnings) {
@@ -625,6 +673,7 @@ export async function buildProjectStatus(project, options = {}) {
         projectDir: project.projectDir,
         env,
         claudeCodeAuthProbe: options.claudeCodeAuthProbe,
+        codexAuthProbe: options.codexAuthProbe,
         fast: options.fast,
         useSpinner: options.useSpinner,
     });

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

@@ -12,6 +12,7 @@ export interface CompletedCommandSpan {
     durationMs: number;
     outcome: CommandOutcome;
     errorClass?: string;
+    errorDetail?: string;
     flagsPresent: Record<string, boolean>;
     hasProject: boolean;
     projectDir?: string;

package/dist/telemetry/command-hook.js

@@ -1,4 +1,4 @@
-import { scrubErrorClass } from './scrubber.js';
+import { formatErrorDetail, scrubErrorClass } from './scrubber.js';
 let activeCommandSpan;
 export function beginCommandSpan(input) {
     activeCommandSpan = input;
@@ -10,11 +10,13 @@ export function completeCommandSpan(input) {
         return undefined;
     }
     const errorClass = input.error ? scrubErrorClass(input.error) : undefined;
+    const errorDetail = input.error ? formatErrorDetail(input.error) : undefined;
     return {
         commandPath: span.commandPath,
         durationMs: Math.max(0, input.completedAt - span.startedAt),
         outcome: input.outcome,
         ...(errorClass ? { errorClass } : {}),
+        ...(errorDetail ? { errorDetail } : {}),
         flagsPresent: span.flagsPresent,
         hasProject: span.hasProject,
         projectDir: span.projectDir,

package/dist/telemetry/emitter.d.ts

@@ -15,6 +15,16 @@ export declare function trackTelemetryEvent(input: {
     projectApiKey?: string;
     host?: string;
 }): Promise<void>;
+export declare function trackTelemetryException(input: {
+    error: Error;
+    distinctId: string;
+    properties: Record<string, unknown>;
+    env?: TelemetryEmitterEnv;
+    stderr: TelemetrySink;
+    projectApiKey?: string;
+    host?: string;
+    immediate?: boolean;
+}): Promise<void>;
 export declare function shutdownTelemetryEmitter(): Promise<void>;
 /** @internal */
 export declare function __resetTelemetryEmitterForTests(): void;

package/dist/telemetry/emitter.js

@@ -56,6 +56,37 @@ export async function trackTelemetryEvent(input) {
         return;
     }
 }
+function writeDebugExceptionPayload(input) {
+    input.stderr.write(`[telemetry-exception] ${JSON.stringify({
+        distinctId: input.distinctId,
+        message: input.error.message,
+        name: input.error.name,
+        properties: input.properties,
+    })}\n`);
+}
+export async function trackTelemetryException(input) {
+    const env = input.env ?? process.env;
+    if (debugEnabled(env)) {
+        writeDebugExceptionPayload(input);
+        return;
+    }
+    const projectApiKey = telemetryProjectApiKey(input.projectApiKey);
+    const host = telemetryHost(env, input.host);
+    const client = await getPostHogClient(projectApiKey, host);
+    if (!client) {
+        return;
+    }
+    try {
+        if (input.immediate) {
+            await client.captureExceptionImmediate(input.error, input.distinctId, input.properties);
+            return;
+        }
+        client.captureException(input.error, input.distinctId, input.properties);
+    }
+    catch {
+        return;
+    }
+}
 export async function shutdownTelemetryEmitter() {
     const client = await clientPromise;
     if (!client) {

package/dist/telemetry/events.d.ts

@@ -44,6 +44,7 @@ export declare const telemetryEventSchemas: {
             aborted: "aborted";
         }>;
         errorClass: z.ZodOptional<z.ZodString>;
+        errorDetail: z.ZodOptional<z.ZodString>;
         flagsPresent: z.ZodRecord<z.ZodString, z.ZodBoolean>;
         hasProject: z.ZodBoolean;
         projectGroupAttached: z.ZodBoolean;
@@ -67,8 +68,8 @@ export declare const telemetryEventSchemas: {
             databases: "databases";
             context: "context";
             runtime: "runtime";
-            agents: "agents";
             secrets: "secrets";
+            agents: "agents";
             "demo-tour": "demo-tour";
         }>;
         outcome: z.ZodEnum<{
@@ -77,6 +78,7 @@ export declare const telemetryEventSchemas: {
             abandoned: "abandoned";
         }>;
         durationMs: z.ZodNumber;
+        errorDetail: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     readonly connection_added: z.ZodObject<{
         cliVersion: z.ZodString;
@@ -110,6 +112,7 @@ export declare const telemetryEventSchemas: {
             error: "error";
         }>;
         errorClass: z.ZodOptional<z.ZodString>;
+        errorDetail: z.ZodOptional<z.ZodString>;
         durationMs: z.ZodNumber;
         serverVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
@@ -163,6 +166,7 @@ export declare const telemetryEventSchemas: {
             error: "error";
         }>;
         errorClass: z.ZodOptional<z.ZodString>;
+        errorDetail: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     readonly scan_completed: z.ZodObject<{
         cliVersion: z.ZodString;
@@ -186,6 +190,7 @@ export declare const telemetryEventSchemas: {
             error: "error";
         }>;
         errorClass: z.ZodOptional<z.ZodString>;
+        errorDetail: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     readonly sl_validate_completed: z.ZodObject<{
         cliVersion: z.ZodString;
@@ -381,6 +386,26 @@ export declare const telemetryEventSchemas: {
         errorClass: z.ZodOptional<z.ZodString>;
         durationMs: z.ZodNumber;
     }, z.core.$strict>;
+    readonly query_history_filter_completed: z.ZodObject<{
+        cliVersion: z.ZodString;
+        nodeVersion: z.ZodString;
+        osPlatform: z.ZodString;
+        osRelease: z.ZodString;
+        arch: z.ZodString;
+        runtime: z.ZodEnum<{
+            node: "node";
+            "daemon-py": "daemon-py";
+        }>;
+        isCi: z.ZodBoolean;
+        dialect: z.ZodString;
+        consideredRoleCount: z.ZodNumber;
+        excludedRoleCount: z.ZodNumber;
+        parseFailedCount: z.ZodNumber;
+        outcome: z.ZodEnum<{
+            ok: "ok";
+            error: "error";
+        }>;
+    }, z.core.$strict>;
 };
 /** @internal */
 export declare const telemetryEventCatalog: readonly [{
@@ -390,11 +415,11 @@ export declare const telemetryEventCatalog: readonly [{
 }, {
     readonly name: "command";
     readonly description: "Emitted once for each Commander action that reaches preAction.";
-    readonly fields: readonly ["commandPath", "durationMs", "outcome", "errorClass", "flagsPresent", "hasProject", "projectGroupAttached"];
+    readonly fields: readonly ["commandPath", "durationMs", "outcome", "errorClass", "errorDetail", "flagsPresent", "hasProject", "projectGroupAttached"];
 }, {
     readonly name: "setup_step";
     readonly description: "Emitted after an interactive setup step completes, skips, or aborts.";
-    readonly fields: readonly ["step", "outcome", "durationMs"];
+    readonly fields: readonly ["step", "outcome", "durationMs", "errorDetail"];
 }, {
     readonly name: "connection_added";
     readonly description: "Emitted when setup writes a database, source, or demo connection.";
@@ -402,7 +427,7 @@ export declare const telemetryEventCatalog: readonly [{
 }, {
     readonly name: "connection_test";
     readonly description: "Emitted after ktx connection test completes.";
-    readonly fields: readonly ["driver", "isDemoConnection", "outcome", "errorClass", "durationMs", "serverVersion"];
+    readonly fields: readonly ["driver", "isDemoConnection", "outcome", "errorClass", "errorDetail", "durationMs", "serverVersion"];
 }, {
     readonly name: "project_stack_snapshot";
     readonly description: "Emitted after commands that can summarize the local project stack.";
@@ -410,11 +435,11 @@ export declare const telemetryEventCatalog: readonly [{
 }, {
     readonly name: "ingest_completed";
     readonly description: "Emitted after a public ingest target completes.";
-    readonly fields: readonly ["driver", "isDemoConnection", "schemaCount", "tableCount", "columnCount", "rowsBucket", "durationMs", "outcome", "errorClass"];
+    readonly fields: readonly ["driver", "isDemoConnection", "schemaCount", "tableCount", "columnCount", "rowsBucket", "durationMs", "outcome", "errorClass", "errorDetail"];
 }, {
     readonly name: "scan_completed";
     readonly description: "Emitted after schema scan or relationship inference completes.";
-    readonly fields: readonly ["driver", "tableCount", "columnCount", "inferredFkCount", "declaredFkCount", "durationMs", "outcome", "errorClass"];
+    readonly fields: readonly ["driver", "tableCount", "columnCount", "inferredFkCount", "declaredFkCount", "durationMs", "outcome", "errorClass", "errorDetail"];
 }, {
     readonly name: "sl_validate_completed";
     readonly description: "Emitted after ktx sl validate completes.";
@@ -451,6 +476,10 @@ export declare const telemetryEventCatalog: readonly [{
     readonly name: "sql_gen_completed";
     readonly description: "Emitted after daemon SQL generation completes.";
     readonly fields: readonly ["outcome", "dialect", "errorClass", "durationMs"];
+}, {
+    readonly name: "query_history_filter_completed";
+    readonly description: "Emitted after the setup query-history service-account filter picker runs.";
+    readonly fields: readonly ["dialect", "consideredRoleCount", "excludedRoleCount", "parseFailedCount", "outcome"];
 }];
 export type TelemetryEventName = keyof typeof telemetryEventSchemas;
 export type TelemetryCommonEnvelope = z.infer<typeof telemetryCommonEnvelopeSchema>;

package/dist/telemetry/events.js

@@ -18,6 +18,7 @@ const commandSchema = telemetryCommonEnvelopeSchema
     durationMs: z.number().nonnegative(),
     outcome: z.enum(['ok', 'error', 'aborted']),
     errorClass: z.string().optional(),
+    errorDetail: z.string().max(1000).optional(),
     flagsPresent: z.record(z.string(), z.boolean()),
     hasProject: z.boolean(),
     projectGroupAttached: z.boolean(),
@@ -40,6 +41,7 @@ const setupStepSchema = telemetryCommonEnvelopeSchema
     ]),
     outcome: z.enum(['completed', 'skipped', 'abandoned']),
     durationMs: z.number().nonnegative(),
+    errorDetail: z.string().max(1000).optional(),
 })
     .strict();
 const connectionAddedSchema = telemetryCommonEnvelopeSchema
@@ -54,6 +56,7 @@ const connectionTestSchema = telemetryCommonEnvelopeSchema
     isDemoConnection: z.boolean(),
     outcome: outcomeSchema,
     errorClass: z.string().optional(),
+    errorDetail: z.string().max(1000).optional(),
     durationMs: z.number().nonnegative(),
     serverVersion: z.string().optional(),
 })
@@ -80,6 +83,7 @@ const ingestCompletedSchema = telemetryCommonEnvelopeSchema
     durationMs: z.number().nonnegative(),
     outcome: outcomeSchema,
     errorClass: z.string().optional(),
+    errorDetail: z.string().max(1000).optional(),
 })
     .strict();
 const scanCompletedSchema = telemetryCommonEnvelopeSchema
@@ -92,6 +96,7 @@ const scanCompletedSchema = telemetryCommonEnvelopeSchema
     durationMs: z.number().nonnegative(),
     outcome: outcomeSchema,
     errorClass: z.string().optional(),
+    errorDetail: z.string().max(1000).optional(),
 })
     .strict();
 const slValidateCompletedSchema = telemetryCommonEnvelopeSchema
@@ -180,6 +185,15 @@ const sqlGenCompletedSchema = telemetryCommonEnvelopeSchema
     durationMs: z.number().nonnegative(),
 })
     .strict();
+const queryHistoryFilterCompletedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    dialect: z.string(),
+    consideredRoleCount: z.number().int().nonnegative(),
+    excludedRoleCount: z.number().int().nonnegative(),
+    parseFailedCount: z.number().int().nonnegative(),
+    outcome: outcomeSchema,
+})
+    .strict();
 /** @internal */
 export const telemetryEventSchemas = {
     install_first_run: installFirstRunSchema,
@@ -199,6 +213,7 @@ export const telemetryEventSchemas = {
     daemon_stopped: daemonStoppedSchema,
     sl_plan_completed: slPlanCompletedSchema,
     sql_gen_completed: sqlGenCompletedSchema,
+    query_history_filter_completed: queryHistoryFilterCompletedSchema,
 };
 /** @internal */
 export const telemetryEventCatalog = [
@@ -215,6 +230,7 @@ export const telemetryEventCatalog = [
             'durationMs',
             'outcome',
             'errorClass',
+            'errorDetail',
             'flagsPresent',
             'hasProject',
             'projectGroupAttached',
@@ -223,7 +239,7 @@ export const telemetryEventCatalog = [
     {
         name: 'setup_step',
         description: 'Emitted after an interactive setup step completes, skips, or aborts.',
-        fields: ['step', 'outcome', 'durationMs'],
+        fields: ['step', 'outcome', 'durationMs', 'errorDetail'],
     },
     {
         name: 'connection_added',
@@ -233,7 +249,7 @@ export const telemetryEventCatalog = [
     {
         name: 'connection_test',
         description: 'Emitted after ktx connection test completes.',
-        fields: ['driver', 'isDemoConnection', 'outcome', 'errorClass', 'durationMs', 'serverVersion'],
+        fields: ['driver', 'isDemoConnection', 'outcome', 'errorClass', 'errorDetail', 'durationMs', 'serverVersion'],
     },
     {
         name: 'project_stack_snapshot',
@@ -253,6 +269,7 @@ export const telemetryEventCatalog = [
             'durationMs',
             'outcome',
             'errorClass',
+            'errorDetail',
         ],
     },
     {
@@ -267,6 +284,7 @@ export const telemetryEventCatalog = [
             'durationMs',
             'outcome',
             'errorClass',
+            'errorDetail',
         ],
     },
     {
@@ -330,6 +348,11 @@ export const telemetryEventCatalog = [
         description: 'Emitted after daemon SQL generation completes.',
         fields: ['outcome', 'dialect', 'errorClass', 'durationMs'],
     },
+    {
+        name: 'query_history_filter_completed',
+        description: 'Emitted after the setup query-history service-account filter picker runs.',
+        fields: ['dialect', 'consideredRoleCount', 'excludedRoleCount', 'parseFailedCount', 'outcome'],
+    },
 ];
 export function buildCommonEnvelope(input) {
     return {

package/dist/telemetry/exception.d.ts

@@ -0,0 +1,18 @@
+import { type KtxCliIo, type KtxCliPackageInfo } from '../cli-runtime.js';
+export interface ExceptionContext {
+    source: string;
+    handled: boolean;
+    fatal: boolean;
+    extra?: Record<string, string | number | boolean>;
+}
+export declare function reportException(input: {
+    error: unknown;
+    context: ExceptionContext;
+    io: KtxCliIo;
+    packageInfo?: KtxCliPackageInfo;
+    projectDir?: string;
+    immediate?: boolean;
+    redactionSecrets?: ReadonlyArray<string>;
+}): Promise<void>;
+/** @internal */
+export declare function __resetTelemetryExceptionStateForTests(): void;