@kaelio/ktx 0.8.0 → 0.10.0

package/dist/telemetry/exception.js

@@ -0,0 +1,162 @@
+import { inspect } from 'node:util';
+import { getKtxCliPackageInfo } from '../cli-runtime.js';
+import { buildCommonEnvelope } from './events.js';
+import { trackTelemetryException } from './emitter.js';
+import { computeTelemetryProjectId, loadTelemetryIdentity } from './identity.js';
+const reportedObjects = new WeakSet();
+const recentHandledPrimitives = [];
+const RECENT_PRIMITIVE_LIMIT = 128;
+function primitiveKey(value) {
+    return `${typeof value}:${String(value)}`;
+}
+function rememberHandledPrimitive(value) {
+    recentHandledPrimitives.push(primitiveKey(value));
+    if (recentHandledPrimitives.length > RECENT_PRIMITIVE_LIMIT) {
+        recentHandledPrimitives.splice(0, recentHandledPrimitives.length - RECENT_PRIMITIVE_LIMIT);
+    }
+}
+function consumeHandledPrimitive(value) {
+    const key = primitiveKey(value);
+    const index = recentHandledPrimitives.indexOf(key);
+    if (index < 0) {
+        return false;
+    }
+    recentHandledPrimitives.splice(index, 1);
+    return true;
+}
+function shouldSkipAsAlreadyReported(error, handled) {
+    if ((typeof error === 'object' || typeof error === 'function') && error !== null) {
+        if (reportedObjects.has(error)) {
+            return true;
+        }
+        reportedObjects.add(error);
+        return false;
+    }
+    if (handled) {
+        rememberHandledPrimitive(error);
+        return false;
+    }
+    return consumeHandledPrimitive(error);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function redactStaticPatterns(value) {
+    return value
+        .replace(/([a-z][a-z0-9+.-]*:\/\/[^:\s/@]+:)([^@\s/]+)(@)/gi, '$1[redacted]$3')
+        .replace(/\b(password|pwd)=([^;&\s]+)/gi, '$1=[redacted]')
+        .replace(/\bAuthorization\s*:\s*[^\r\n,;]+/gi, 'Authorization: [redacted]')
+        .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [redacted]')
+        .replace(/\b(api[_-]?key)\s*[:=]\s*([^\s,;]+)/gi, '$1=[redacted]')
+        .replace(/\b(KTX_[A-Z0-9_]*|[A-Z0-9_]*(?:TOKEN|SECRET))\s*[:=]\s*([^\s,;]+)/g, '$1=[redacted]')
+        .replace(/([?&](?:X-Amz-Signature|X-Goog-Signature|sig)=)[^&\s]+/gi, '$1[redacted]');
+}
+function redactText(value, secrets) {
+    let redacted = value;
+    for (const secret of secrets) {
+        if (secret) {
+            redacted = redacted.replace(new RegExp(escapeRegExp(secret), 'g'), '[redacted]');
+        }
+    }
+    return redactStaticPatterns(redacted);
+}
+const FORBIDDEN_EXTRA_PROPERTY_KEYS = new Set([
+    'argv',
+    'args',
+    'env',
+    'environment',
+    'sql',
+    'query',
+    'prompt',
+    'mcparguments',
+    'mcpargs',
+    'tablename',
+    'schemaname',
+    'columnname',
+    'databaseurl',
+    'connectionstring',
+    'url',
+    'password',
+    'token',
+    'apikey',
+    'api_key',
+    'authorization',
+]);
+function safeExtraProperties(extra) {
+    const safe = {};
+    for (const [key, value] of Object.entries(extra ?? {})) {
+        if (!FORBIDDEN_EXTRA_PROPERTY_KEYS.has(key.replace(/[^a-z0-9_]/gi, '').toLowerCase())) {
+            safe[key] = value;
+        }
+    }
+    return safe;
+}
+function toMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return inspect(error, { depth: 4, breakLength: 120 });
+}
+function sanitizedError(error, secrets) {
+    if (error instanceof Error) {
+        const cause = 'cause' in error ? error.cause : undefined;
+        const clone = new Error(redactText(error.message, secrets), {
+            ...(cause !== undefined ? { cause: sanitizedError(cause, secrets) } : {}),
+        });
+        clone.name = error.name;
+        if (error.stack) {
+            clone.stack = redactText(error.stack, secrets);
+        }
+        return clone;
+    }
+    return new Error(redactText(toMessage(error), secrets));
+}
+export async function reportException(input) {
+    try {
+        if (shouldSkipAsAlreadyReported(input.error, input.context.handled)) {
+            return;
+        }
+        const debug = process.env.KTX_TELEMETRY_DEBUG === '1';
+        const identity = await loadTelemetryIdentity({
+            stderr: input.io.stderr,
+            env: process.env,
+        });
+        if ((!identity.enabled || !identity.installId) && !debug) {
+            return;
+        }
+        const packageInfo = input.packageInfo ?? getKtxCliPackageInfo();
+        const installId = identity.installId ?? 'debug';
+        const projectId = input.projectDir ? computeTelemetryProjectId(installId, input.projectDir) : undefined;
+        const safeError = sanitizedError(input.error, input.redactionSecrets ?? []);
+        const properties = {
+            ...buildCommonEnvelope({
+                cliVersion: packageInfo.version,
+                isCi: Boolean(process.env.CI),
+            }),
+            source: input.context.source,
+            handled: input.context.handled,
+            fatal: input.context.fatal,
+            ...(projectId ? { projectId } : {}),
+            ...safeExtraProperties(input.context.extra),
+        };
+        delete properties.$groups;
+        await trackTelemetryException({
+            error: safeError,
+            distinctId: installId,
+            properties,
+            env: process.env,
+            stderr: input.io.stderr,
+            immediate: input.immediate,
+        });
+    }
+    catch {
+        return;
+    }
+}
+/** @internal */
+export function __resetTelemetryExceptionStateForTests() {
+    recentHandledPrimitives.length = 0;
+}

package/dist/telemetry/identity.d.ts

@@ -11,7 +11,6 @@ export interface TelemetryIdentityEnv {
 export interface LoadTelemetryIdentityOptions {
     homeDir?: string;
     env?: TelemetryIdentityEnv;
-    stdoutIsTTY: boolean;
     stderr: {
         write(chunk: string): void;
     };

package/dist/telemetry/identity.js

@@ -58,12 +58,12 @@ export async function loadTelemetryIdentity(options) {
             path,
         };
     }
-    // No identity yet. Minting one means showing the one-time opt-out notice, so
-    // first-run creation requires an interactive surface; a headless first run
-    // stays disabled and defers enablement until the next interactive run.
-    if (options.stdoutIsTTY !== true) {
-        return { enabled: false, createdFile: false, noticeShown: false, path };
-    }
+    // No identity yet → mint one regardless of surface. Telemetry is opt-out, so
+    // a fresh install is counted even when its first run is headless (an
+    // IDE-launched `ktx mcp stdio`, a scripted invocation); otherwise those
+    // installs would be permanently invisible. Opt-out env vars are honored
+    // above. The one-time notice is written to stderr — safe even under MCP
+    // stdio, which reserves stdout for its JSON-RPC protocol.
     const timestamp = (options.now ?? (() => new Date()))().toISOString();
     const next = {
         installId: randomUUID(),

package/dist/telemetry/index.d.ts

@@ -1,9 +1,10 @@
 import { type KtxCliIo, type KtxCliPackageInfo } from '../cli-runtime.js';
 import { beginCommandSpan, completeCommandSpan, type CommandOutcome, type CompletedCommandSpan } from './command-hook.js';
 import { shutdownTelemetryEmitter } from './emitter.js';
+import { reportException, type ExceptionContext } from './exception.js';
 import { type TelemetryCommonEnvelope, type TelemetryEventName, type TelemetryEventProperties } from './events.js';
-export { beginCommandSpan, completeCommandSpan, shutdownTelemetryEmitter };
-export type { CommandOutcome, CompletedCommandSpan };
+export { beginCommandSpan, completeCommandSpan, reportException, shutdownTelemetryEmitter };
+export type { CommandOutcome, CompletedCommandSpan, ExceptionContext };
 export declare function showTelemetryNoticeIfNeeded(io: KtxCliIo, packageInfo: KtxCliPackageInfo): Promise<void>;
 type TelemetryEventFields<Name extends TelemetryEventName> = Omit<TelemetryEventProperties<Name>, keyof TelemetryCommonEnvelope>;
 export declare function shouldEmitMcpTelemetry(): boolean;
@@ -25,3 +26,15 @@ export declare function emitCompletedCommand(input: {
     packageInfo: KtxCliPackageInfo;
     io: KtxCliIo;
 }): Promise<void>;
+/**
+ * Flush telemetry when the process is interrupted (Ctrl-C / kill). The normal
+ * `command` emit + flush lives in a `finally` that a signal skips, so without
+ * this an interrupted long-running command (ingest, `mcp stdio`) loses its
+ * `command` event and any queued events. Marks the active command span as
+ * `aborted`, emits it, and drains the emitter. Best-effort and idempotent: if
+ * the span was already completed (normal exit racing a signal) the emit no-ops.
+ */
+export declare function emitAbortedCommandAndShutdown(input: {
+    packageInfo: KtxCliPackageInfo;
+    io: KtxCliIo;
+}): Promise<void>;

package/dist/telemetry/index.js

@@ -2,13 +2,13 @@ import { getKtxCliPackageInfo } from '../cli-runtime.js';
 import { loadKtxProject } from '../context/project/project.js';
 import { beginCommandSpan, completeCommandSpan, } from './command-hook.js';
 import { shutdownTelemetryEmitter, trackTelemetryEvent } from './emitter.js';
+import { reportException } from './exception.js';
 import { buildCommonEnvelope, buildTelemetryEvent, } from './events.js';
 import { computeTelemetryProjectId, loadTelemetryIdentity } from './identity.js';
 import { buildProjectStackSnapshotFields } from './project-snapshot.js';
-export { beginCommandSpan, completeCommandSpan, shutdownTelemetryEmitter };
+export { beginCommandSpan, completeCommandSpan, reportException, shutdownTelemetryEmitter };
 export async function showTelemetryNoticeIfNeeded(io, packageInfo) {
     const identity = await loadTelemetryIdentity({
-        stdoutIsTTY: io.stdout.isTTY === true,
         stderr: io.stderr,
         env: process.env,
     });
@@ -45,7 +45,6 @@ export function mcpTelemetrySampleRate() {
 export async function emitTelemetryEvent(input) {
     const debug = telemetryDebugEnabled();
     const identity = await loadTelemetryIdentity({
-        stdoutIsTTY: input.io.stdout.isTTY === true,
         stderr: input.io.stderr,
         env: process.env,
     });
@@ -100,3 +99,16 @@ export async function emitCompletedCommand(input) {
         packageInfo: input.packageInfo,
     });
 }
+/**
+ * Flush telemetry when the process is interrupted (Ctrl-C / kill). The normal
+ * `command` emit + flush lives in a `finally` that a signal skips, so without
+ * this an interrupted long-running command (ingest, `mcp stdio`) loses its
+ * `command` event and any queued events. Marks the active command span as
+ * `aborted`, emits it, and drains the emitter. Best-effort and idempotent: if
+ * the span was already completed (normal exit racing a signal) the emit no-ops.
+ */
+export async function emitAbortedCommandAndShutdown(input) {
+    const completed = completeCommandSpan({ completedAt: performance.now(), outcome: 'aborted' });
+    await emitCompletedCommand({ completed, packageInfo: input.packageInfo, io: input.io });
+    await shutdownTelemetryEmitter();
+}

package/dist/telemetry/redaction-secrets.d.ts

@@ -0,0 +1,11 @@
+import { type KtxLocalProject } from '../context/project/project.js';
+type TelemetryRedactionProject = Pick<KtxLocalProject, 'config' | 'projectDir'>;
+export declare function collectTelemetryRedactionSecrets(input: {
+    project?: TelemetryRedactionProject;
+    projectDir?: string;
+    connectionId?: string;
+    includeLlm?: boolean;
+    includeEmbeddings?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): Promise<string[]>;
+export {};

package/dist/telemetry/redaction-secrets.js

@@ -0,0 +1,92 @@
+import { resolveKtxConfigReference } from '../context/core/config-reference.js';
+import { loadKtxProject } from '../context/project/project.js';
+const SENSITIVE_KEY = /(password|secret|token|api[_-]?key|auth[_-]?token|auth_token_ref|private[_-]?key|passphrase|credential|authorization|url)$/i;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function addSecret(values, value) {
+    const trimmed = value?.trim();
+    if (trimmed && !values.includes(trimmed)) {
+        values.push(trimmed);
+    }
+}
+function tryResolve(value, env) {
+    try {
+        return resolveKtxConfigReference(value, env);
+    }
+    catch {
+        return undefined;
+    }
+}
+function addUrlCredentials(values, value) {
+    try {
+        const parsed = new URL(value);
+        addSecret(values, parsed.password ? decodeURIComponent(parsed.password) : undefined);
+        addSecret(values, parsed.username ? decodeURIComponent(parsed.username) : undefined);
+    }
+    catch {
+        return;
+    }
+}
+function collectFromRecord(input, env, values) {
+    if (Array.isArray(input)) {
+        for (const item of input) {
+            collectFromRecord(item, env, values);
+        }
+        return;
+    }
+    if (!isRecord(input)) {
+        return;
+    }
+    for (const [key, raw] of Object.entries(input)) {
+        if (isRecord(raw) || Array.isArray(raw)) {
+            collectFromRecord(raw, env, values);
+            continue;
+        }
+        if (typeof raw !== 'string' || !SENSITIVE_KEY.test(key)) {
+            continue;
+        }
+        const resolved = tryResolve(raw, env);
+        addSecret(values, resolved);
+        if (resolved) {
+            addUrlCredentials(values, resolved);
+        }
+    }
+}
+function collectLlmSecrets(project, env, values) {
+    collectFromRecord(project.config.llm.provider, env, values);
+}
+function collectEmbeddingSecrets(project, env, values) {
+    collectFromRecord(project.config.ingest.embeddings, env, values);
+    collectFromRecord(project.config.scan.enrichment.embeddings, env, values);
+}
+function collectConnectionSecrets(project, connectionId, env, values) {
+    if (!connectionId) {
+        return;
+    }
+    collectFromRecord(project.config.connections[connectionId], env, values);
+}
+export async function collectTelemetryRedactionSecrets(input) {
+    const env = input.env ?? process.env;
+    let project = input.project;
+    if (!project && input.projectDir) {
+        try {
+            project = await loadKtxProject({ projectDir: input.projectDir });
+        }
+        catch {
+            project = undefined;
+        }
+    }
+    if (!project) {
+        return [];
+    }
+    const values = [];
+    if (input.includeLlm) {
+        collectLlmSecrets(project, env, values);
+    }
+    if (input.includeEmbeddings) {
+        collectEmbeddingSecrets(project, env, values);
+    }
+    collectConnectionSecrets(project, input.connectionId, env, values);
+    return values;
+}

package/dist/telemetry/scrubber.d.ts

@@ -1 +1,11 @@
 export declare function scrubErrorClass(error: unknown): string | undefined;
+/**
+ * Human-readable failure detail for telemetry: the error's `.code` (when
+ * present) prefixed onto its `message`, collapsed to a single line and
+ * length-capped. Captures the message only — never the stack.
+ *
+ * This intentionally forwards raw error text, which can include identifiers from
+ * the user's environment (table/column names, hostnames, usernames), so that
+ * funnel failures are diagnosable. Callers must gate it to the failure path.
+ */
+export declare function formatErrorDetail(error: unknown): string | undefined;

package/dist/telemetry/scrubber.js

@@ -20,3 +20,23 @@ export function scrubErrorClass(error) {
     }
     return constructorName;
 }
+const MAX_ERROR_DETAIL_LENGTH = 1000;
+/**
+ * Human-readable failure detail for telemetry: the error's `.code` (when
+ * present) prefixed onto its `message`, collapsed to a single line and
+ * length-capped. Captures the message only — never the stack.
+ *
+ * This intentionally forwards raw error text, which can include identifiers from
+ * the user's environment (table/column names, hostnames, usernames), so that
+ * funnel failures are diagnosable. Callers must gate it to the failure path.
+ */
+export function formatErrorDetail(error) {
+    if (error === undefined || error === null) {
+        return undefined;
+    }
+    const code = error.code;
+    const message = error instanceof Error ? error.message : String(error);
+    const prefix = typeof code === 'string' || typeof code === 'number' ? `${code}: ` : '';
+    const detail = `${prefix}${message}`.replace(/\s+/g, ' ').trim();
+    return detail.length > 0 ? detail.slice(0, MAX_ERROR_DETAIL_LENGTH) : undefined;
+}

package/dist/update-check/cache.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+declare const updateCheckCacheSchema: z.ZodObject<{
+    checkedAt: z.ZodString;
+    channel: z.ZodEnum<{
+        next: "next";
+        latest: "latest";
+    }>;
+    installedVersion: z.ZodString;
+    latestForChannel: z.ZodString;
+    lastNoticeAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type UpdateCheckCache = z.infer<typeof updateCheckCacheSchema>;
+/** @internal */
+export declare function updateCheckCachePath(homeDir?: string): string;
+export declare function readUpdateCheckCache(options?: {
+    homeDir?: string;
+}): Promise<UpdateCheckCache | null>;
+export declare function writeUpdateCheckCache(value: UpdateCheckCache, options?: {
+    homeDir?: string;
+}): Promise<void>;
+export {};

package/dist/update-check/cache.js

@@ -0,0 +1,38 @@
+import { renameSync, writeFileSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+const updateCheckCacheSchema = z
+    .object({
+    checkedAt: z.string(),
+    channel: z.enum(['latest', 'next']),
+    installedVersion: z.string(),
+    latestForChannel: z.string(),
+    lastNoticeAt: z.string().optional(),
+})
+    .strict();
+/** @internal */
+export function updateCheckCachePath(homeDir = homedir()) {
+    return join(homeDir, '.ktx', 'update-check.json');
+}
+export async function readUpdateCheckCache(options = {}) {
+    try {
+        return updateCheckCacheSchema.parse(JSON.parse(await readFile(updateCheckCachePath(options.homeDir), 'utf-8')));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeUpdateCheckCache(value, options = {}) {
+    try {
+        const path = updateCheckCachePath(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;
+    }
+}

package/dist/update-check/channel.d.ts

@@ -0,0 +1,15 @@
+export type UpdateChannel = 'latest' | 'next';
+export type UpdateDecision = {
+    status: 'skip';
+} | {
+    status: 'upToDate';
+    channel: UpdateChannel;
+    target: string;
+} | {
+    status: 'available';
+    channel: UpdateChannel;
+    target: string;
+};
+/** @internal */
+export declare function inferUpdateChannel(installed: string): UpdateChannel | null;
+export declare function decideUpdate(installed: string, distTags: Record<string, string>): UpdateDecision;

package/dist/update-check/channel.js

@@ -0,0 +1,30 @@
+import semver from 'semver';
+/** @internal */
+export function inferUpdateChannel(installed) {
+    const parsed = semver.parse(installed);
+    if (!parsed || installed === '0.0.0') {
+        return null;
+    }
+    const [prereleaseId] = parsed.prerelease;
+    if (prereleaseId === undefined) {
+        return 'latest';
+    }
+    if (prereleaseId === 'rc') {
+        return 'next';
+    }
+    return null;
+}
+export function decideUpdate(installed, distTags) {
+    const channel = inferUpdateChannel(installed);
+    if (!channel || !semver.valid(installed)) {
+        return { status: 'skip' };
+    }
+    const target = distTags[channel];
+    if (!target || !semver.valid(target)) {
+        return { status: 'skip' };
+    }
+    if (semver.gt(target, installed)) {
+        return { status: 'available', channel, target };
+    }
+    return { status: 'upToDate', channel, target };
+}

package/dist/update-check/registry.d.ts

@@ -0,0 +1 @@
+export declare function fetchDistTags(): Promise<Record<string, string>>;

package/dist/update-check/registry.js

@@ -0,0 +1,45 @@
+import { request as httpsRequest } from 'node:https';
+import { URL } from 'node:url';
+import { z } from 'zod';
+const DIST_TAGS_URL = new URL('https://registry.npmjs.org/-/package/@kaelio/ktx/dist-tags');
+const distTagsSchema = z.record(z.string(), z.string());
+function parseDistTags(raw) {
+    return distTagsSchema.parse(JSON.parse(raw));
+}
+export function fetchDistTags() {
+    return new Promise((resolve, reject) => {
+        const request = httpsRequest(DIST_TAGS_URL, {
+            method: 'GET',
+            headers: {
+                accept: 'application/json',
+            },
+        }, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            });
+            response.on('end', () => {
+                const text = Buffer.concat(chunks).toString('utf8');
+                const statusCode = response.statusCode ?? 0;
+                if (statusCode < 200 || statusCode >= 300) {
+                    reject(new Error(`npm dist-tags request failed with ${statusCode}: ${text}`));
+                    return;
+                }
+                try {
+                    resolve(parseDistTags(text));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        });
+        request.on('socket', (socket) => {
+            socket.unref();
+        });
+        request.on('error', reject);
+        request.setTimeout(5000, () => {
+            request.destroy(new Error('npm dist-tags request timed out'));
+        });
+        request.end();
+    });
+}

package/dist/update-check/update-check.d.ts

@@ -0,0 +1,43 @@
+import type { KtxCliIo } from '../cli-runtime.js';
+import { type CliStyleEnv } from '../clack.js';
+import { type UpdateChannel } from './channel.js';
+/** @internal */
+export interface UpdateCheckEnv extends NodeJS.ProcessEnv, CliStyleEnv {
+    CI?: string;
+    DO_NOT_TRACK?: string;
+    KTX_NO_UPDATE_CHECK?: string;
+    KTX_OUTPUT?: string;
+    NO_UPDATE_NOTIFIER?: string;
+}
+/** @internal */
+export interface UpdateCheckCommandOptions {
+    format?: unknown;
+    json?: unknown;
+    output?: unknown;
+}
+export interface PrepareUpdateCheckNoticeOptions {
+    commandOptions?: UpdateCheckCommandOptions;
+    env?: UpdateCheckEnv;
+    fetchDistTags?: () => Promise<Record<string, string>>;
+    homeDir?: string;
+    installedVersion: string;
+    io: KtxCliIo;
+    now?: () => Date;
+}
+export interface PreparedUpdateCheckNotice {
+    notice: string | null;
+}
+/** @internal */
+export declare function shouldSuppressUpdateCheck(args: {
+    commandOptions?: UpdateCheckCommandOptions;
+    env?: UpdateCheckEnv;
+    io: KtxCliIo;
+}): boolean;
+/** @internal */
+export declare function renderUpdateNotice(args: {
+    channel: UpdateChannel;
+    env?: CliStyleEnv;
+    installedVersion: string;
+    targetVersion: string;
+}): string;
+export declare function prepareUpdateCheckNotice(options: PrepareUpdateCheckNoticeOptions): Promise<PreparedUpdateCheckNotice>;