@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/dist/managed-python-command.js

@@ -0,0 +1,81 @@
+import { cancel, confirm, isCancel } from '@clack/prompts';
+import { createPythonSemanticLayerComputePort } from '@ktx/context/daemon';
+import { installManagedPythonRuntime, readManagedPythonRuntimeStatus, } from './managed-python-runtime.js';
+export function runtimeInstallPolicyFromFlags(options) {
+    if (options.yes === true && options.input === false) {
+        throw new Error('Choose only one runtime install mode: --yes or --no-input');
+    }
+    if (options.yes === true) {
+        return 'auto';
+    }
+    return options.input === false ? 'never' : 'prompt';
+}
+export function managedRuntimeInstallCommand(feature) {
+    return feature === 'local-embeddings'
+        ? 'ktx runtime install --feature local-embeddings --yes'
+        : 'ktx runtime install --yes';
+}
+function installPrompt(feature) {
+    const label = feature === 'local-embeddings' ? 'local embeddings Python runtime' : 'core Python runtime';
+    return `KTX needs to install the ${label}. This downloads Python dependencies with uv. Continue?`;
+}
+function runtimeRequiredMessage(feature) {
+    return `KTX Python runtime is required for this command. Run: ${managedRuntimeInstallCommand(feature)}`;
+}
+function hasFeature(manifest, feature) {
+    return manifest.features.includes(feature);
+}
+async function defaultConfirmInstall(message) {
+    if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+        return false;
+    }
+    const response = await confirm({ message, initialValue: true });
+    if (isCancel(response)) {
+        cancel('Runtime installation cancelled.');
+        return false;
+    }
+    return response === true;
+}
+export async function ensureManagedPythonCommandRuntime(options) {
+    const feature = options.feature ?? 'core';
+    const readStatus = options.readStatus ?? readManagedPythonRuntimeStatus;
+    const installRuntime = options.installRuntime ?? installManagedPythonRuntime;
+    const status = await readStatus({ cliVersion: options.cliVersion });
+    if (status.kind === 'ready' && status.manifest && hasFeature(status.manifest, feature)) {
+        return { layout: status.layout, manifest: status.manifest };
+    }
+    if (options.installPolicy === 'never') {
+        throw new Error(runtimeRequiredMessage(feature));
+    }
+    if (options.installPolicy === 'prompt') {
+        const confirmInstall = options.confirmInstall ?? defaultConfirmInstall;
+        const confirmed = await confirmInstall(installPrompt(feature));
+        if (!confirmed) {
+            throw new Error(`KTX Python runtime installation was cancelled. Run: ${managedRuntimeInstallCommand(feature)}`);
+        }
+    }
+    options.io.stderr.write(`Installing KTX Python runtime (${feature}) with uv...\n`);
+    const installed = await installRuntime({
+        cliVersion: options.cliVersion,
+        features: [feature],
+        force: false,
+    });
+    options.io.stderr.write(`KTX Python runtime ready: ${installed.layout.versionDir}\n`);
+    return { layout: installed.layout, manifest: installed.manifest };
+}
+export async function createManagedPythonSemanticLayerComputePort(options) {
+    const runtime = await ensureManagedPythonCommandRuntime({
+        cliVersion: options.cliVersion,
+        installPolicy: options.installPolicy,
+        io: options.io,
+        feature: 'core',
+        ...(options.readStatus ? { readStatus: options.readStatus } : {}),
+        ...(options.installRuntime ? { installRuntime: options.installRuntime } : {}),
+        ...(options.confirmInstall ? { confirmInstall: options.confirmInstall } : {}),
+    });
+    const createPythonCompute = options.createPythonCompute ?? createPythonSemanticLayerComputePort;
+    return createPythonCompute({
+        command: runtime.manifest.python.daemonExecutable,
+        args: [],
+    });
+}

package/dist/managed-python-command.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/managed-python-command.test.js

@@ -0,0 +1,180 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createManagedPythonSemanticLayerComputePort, managedRuntimeInstallCommand, runtimeInstallPolicyFromFlags, } from './managed-python-command.js';
+function makeIo() {
+    let stdout = '';
+    let stderr = '';
+    return {
+        io: {
+            stdout: {
+                write: (chunk) => {
+                    stdout += chunk;
+                },
+            },
+            stderr: {
+                write: (chunk) => {
+                    stderr += chunk;
+                },
+            },
+        },
+        stdout: () => stdout,
+        stderr: () => stderr,
+    };
+}
+function layout() {
+    return {
+        cliVersion: '0.2.0',
+        runtimeRoot: '/runtime',
+        versionDir: '/runtime/0.2.0',
+        venvDir: '/runtime/0.2.0/.venv',
+        manifestPath: '/runtime/0.2.0/manifest.json',
+        installLogPath: '/runtime/0.2.0/install.log',
+        assetDir: '/assets/python',
+        assetManifestPath: '/assets/python/manifest.json',
+        pythonPath: '/runtime/0.2.0/.venv/bin/python',
+        daemonPath: '/runtime/0.2.0/.venv/bin/ktx-daemon',
+        daemonStatePath: '/runtime/0.2.0/daemon.json',
+        daemonStdoutPath: '/runtime/0.2.0/daemon.stdout.log',
+        daemonStderrPath: '/runtime/0.2.0/daemon.stderr.log',
+    };
+}
+function manifest(features = ['core']) {
+    return {
+        schemaVersion: 1,
+        cliVersion: '0.2.0',
+        installedAt: '2026-05-11T00:00:00.000Z',
+        asset: {
+            schemaVersion: 1,
+            distributionName: 'kaelio-ktx',
+            normalizedName: 'kaelio_ktx',
+            version: '0.2.0',
+            wheel: {
+                file: 'kaelio_ktx-0.2.0-py3-none-any.whl',
+                sha256: 'a'.repeat(64),
+                bytes: 123,
+            },
+        },
+        features,
+        python: {
+            executable: '/runtime/0.2.0/.venv/bin/python',
+            daemonExecutable: '/runtime/0.2.0/.venv/bin/ktx-daemon',
+        },
+        installLog: '/runtime/0.2.0/install.log',
+    };
+}
+function readyStatus(features = ['core']) {
+    return {
+        kind: 'ready',
+        detail: 'Runtime ready at /runtime/0.2.0',
+        layout: layout(),
+        manifest: manifest(features),
+    };
+}
+function missingStatus() {
+    return {
+        kind: 'missing',
+        detail: 'No runtime manifest at /runtime/0.2.0/manifest.json',
+        layout: layout(),
+    };
+}
+function installResult(features = ['core']) {
+    const installedManifest = manifest(features);
+    return {
+        status: 'installed',
+        layout: layout(),
+        asset: {
+            manifest: installedManifest.asset,
+            wheelPath: '/assets/python/kaelio_ktx-0.2.0-py3-none-any.whl',
+        },
+        manifest: installedManifest,
+    };
+}
+describe('managedRuntimeInstallCommand', () => {
+    it('prints the exact command for each managed runtime feature', () => {
+        expect(managedRuntimeInstallCommand('core')).toBe('ktx runtime install --yes');
+        expect(managedRuntimeInstallCommand('local-embeddings')).toBe('ktx runtime install --feature local-embeddings --yes');
+    });
+});
+describe('runtimeInstallPolicyFromFlags', () => {
+    it('maps command flags to managed runtime install policies', () => {
+        expect(runtimeInstallPolicyFromFlags({})).toBe('prompt');
+        expect(runtimeInstallPolicyFromFlags({ yes: false })).toBe('prompt');
+        expect(runtimeInstallPolicyFromFlags({ yes: true })).toBe('auto');
+        expect(runtimeInstallPolicyFromFlags({ input: false })).toBe('never');
+    });
+    it('rejects conflicting runtime install flags', () => {
+        expect(() => runtimeInstallPolicyFromFlags({ yes: true, input: false })).toThrow('Choose only one runtime install mode: --yes or --no-input');
+    });
+});
+describe('createManagedPythonSemanticLayerComputePort', () => {
+    it('uses the managed ktx-daemon executable when the runtime is ready', async () => {
+        const io = makeIo();
+        const compute = { query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() };
+        const createPythonCompute = vi.fn(() => compute);
+        await expect(createManagedPythonSemanticLayerComputePort({
+            cliVersion: '0.2.0',
+            installPolicy: 'never',
+            io: io.io,
+            readStatus: vi.fn(async () => readyStatus()),
+            installRuntime: vi.fn(),
+            createPythonCompute,
+        })).resolves.toBe(compute);
+        expect(createPythonCompute).toHaveBeenCalledWith({
+            command: '/runtime/0.2.0/.venv/bin/ktx-daemon',
+            args: [],
+        });
+        expect(io.stderr()).toBe('');
+    });
+    it('fails with a preparation command when input is disabled and the runtime is missing', async () => {
+        const io = makeIo();
+        const installRuntime = vi.fn();
+        await expect(createManagedPythonSemanticLayerComputePort({
+            cliVersion: '0.2.0',
+            installPolicy: 'never',
+            io: io.io,
+            readStatus: vi.fn(async () => missingStatus()),
+            installRuntime,
+        })).rejects.toThrow('KTX Python runtime is required for this command. Run: ktx runtime install --yes');
+        expect(installRuntime).not.toHaveBeenCalled();
+    });
+    it('installs the core runtime without prompting when policy is auto', async () => {
+        const io = makeIo();
+        const compute = { query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() };
+        const createPythonCompute = vi.fn(() => compute);
+        const installRuntime = vi.fn(async () => installResult());
+        await expect(createManagedPythonSemanticLayerComputePort({
+            cliVersion: '0.2.0',
+            installPolicy: 'auto',
+            io: io.io,
+            readStatus: vi.fn(async () => missingStatus()),
+            installRuntime,
+            createPythonCompute,
+        })).resolves.toBe(compute);
+        expect(installRuntime).toHaveBeenCalledWith({
+            cliVersion: '0.2.0',
+            features: ['core'],
+            force: false,
+        });
+        expect(io.stderr()).toContain('Installing KTX Python runtime (core) with uv');
+        expect(io.stderr()).toContain('KTX Python runtime ready: /runtime/0.2.0');
+    });
+    it('prompts before installing when policy is prompt', async () => {
+        const io = makeIo();
+        const confirmInstall = vi.fn(async () => true);
+        const installRuntime = vi.fn(async () => installResult());
+        await createManagedPythonSemanticLayerComputePort({
+            cliVersion: '0.2.0',
+            installPolicy: 'prompt',
+            io: io.io,
+            readStatus: vi.fn(async () => missingStatus()),
+            installRuntime,
+            createPythonCompute: vi.fn(() => ({ query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() })),
+            confirmInstall,
+        });
+        expect(confirmInstall).toHaveBeenCalledWith('KTX needs to install the core Python runtime. This downloads Python dependencies with uv. Continue?');
+        expect(installRuntime).toHaveBeenCalledWith({
+            cliVersion: '0.2.0',
+            features: ['core'],
+            force: false,
+        });
+    });
+});

package/dist/managed-python-daemon.d.ts

@@ -0,0 +1,79 @@
+import { type KtxRuntimeFeature, type ManagedPythonRuntimeInstallOptions, type ManagedPythonRuntimeInstallResult, type ManagedPythonRuntimeLayout, type ManagedPythonRuntimeLayoutOptions } from './managed-python-runtime.js';
+export interface ManagedPythonDaemonState {
+    schemaVersion: 1;
+    pid: number;
+    host: '127.0.0.1';
+    port: number;
+    version: string;
+    features: KtxRuntimeFeature[];
+    startedAt: string;
+    stdoutLog: string;
+    stderrLog: string;
+}
+export type ManagedPythonDaemonStatus = {
+    kind: 'stopped';
+    detail: string;
+    layout: ManagedPythonRuntimeLayout;
+} | {
+    kind: 'running';
+    detail: string;
+    layout: ManagedPythonRuntimeLayout;
+    state: ManagedPythonDaemonState;
+    baseUrl: string;
+} | {
+    kind: 'stale';
+    detail: string;
+    layout: ManagedPythonRuntimeLayout;
+    state?: ManagedPythonDaemonState;
+};
+export interface ManagedPythonDaemonStartResult {
+    status: 'started' | 'reused';
+    layout: ManagedPythonRuntimeLayout;
+    state: ManagedPythonDaemonState;
+    baseUrl: string;
+}
+export interface ManagedPythonDaemonStopResult {
+    status: 'stopped' | 'already-stopped';
+    layout: ManagedPythonRuntimeLayout;
+    state?: ManagedPythonDaemonState;
+}
+export interface ManagedPythonDaemonChild {
+    pid?: number;
+    unref(): void;
+}
+export type ManagedPythonDaemonSpawn = (command: string, args: string[], options: {
+    detached: boolean;
+    stdio: ['ignore', number, number];
+    env: NodeJS.ProcessEnv;
+}) => ManagedPythonDaemonChild;
+export type ManagedPythonDaemonFetch = (url: string) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+export interface ManagedPythonDaemonStartOptions extends ManagedPythonRuntimeLayoutOptions {
+    features: KtxRuntimeFeature[];
+    force?: boolean;
+    installRuntime?: (options: ManagedPythonRuntimeInstallOptions) => Promise<ManagedPythonRuntimeInstallResult>;
+    spawnDaemon?: ManagedPythonDaemonSpawn;
+    fetch?: ManagedPythonDaemonFetch;
+    allocatePort?: () => Promise<number>;
+    processAlive?: (pid: number) => boolean;
+    killProcess?: (pid: number) => void;
+    now?: () => Date;
+    startupTimeoutMs?: number;
+    pollIntervalMs?: number;
+}
+export interface ManagedPythonDaemonStatusOptions extends ManagedPythonRuntimeLayoutOptions {
+    fetch?: ManagedPythonDaemonFetch;
+    processAlive?: (pid: number) => boolean;
+}
+export interface ManagedPythonDaemonStopOptions extends ManagedPythonRuntimeLayoutOptions {
+    processAlive?: (pid: number) => boolean;
+    killProcess?: (pid: number) => void;
+}
+export declare function readManagedPythonDaemonStatus(options: ManagedPythonDaemonStatusOptions): Promise<ManagedPythonDaemonStatus>;
+export declare function allocateDaemonPort(): Promise<number>;
+export declare function startManagedPythonDaemon(options: ManagedPythonDaemonStartOptions): Promise<ManagedPythonDaemonStartResult>;
+export declare function stopManagedPythonDaemon(options: ManagedPythonDaemonStopOptions): Promise<ManagedPythonDaemonStopResult>;

package/dist/managed-python-daemon.js

@@ -0,0 +1,267 @@
+import { spawn } from 'node:child_process';
+import { mkdir, open, readFile, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { setTimeout as delay } from 'node:timers/promises';
+import { z } from 'zod';
+import { installManagedPythonRuntime, managedPythonRuntimeLayout, runtimeFeatureSchema, } from './managed-python-runtime.js';
+const daemonStateSchema = z.object({
+    schemaVersion: z.literal(1),
+    pid: z.number().int().positive(),
+    host: z.literal('127.0.0.1'),
+    port: z.number().int().min(1).max(65535),
+    version: z.string().min(1),
+    features: z.array(runtimeFeatureSchema).min(1),
+    startedAt: z.string().min(1),
+    stdoutLog: z.string().min(1),
+    stderrLog: z.string().min(1),
+});
+function normalizeFeatures(features) {
+    const requested = new Set(['core', ...features]);
+    return runtimeFeatureSchema.options.filter((feature) => requested.has(feature));
+}
+function hasFeatures(state, features) {
+    return normalizeFeatures(features).every((feature) => state.features.includes(feature));
+}
+function defaultFetch(url) {
+    return fetch(url);
+}
+function defaultProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultKillProcess(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ESRCH') {
+            throw error;
+        }
+    }
+}
+function defaultSpawnDaemon(command, args, options) {
+    return spawn(command, args, options);
+}
+function baseUrl(state) {
+    return `http://${state.host}:${state.port}`;
+}
+async function readState(path) {
+    try {
+        return daemonStateSchema.parse(JSON.parse(await readFile(path, 'utf8')));
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function writeState(path, state) {
+    await writeFile(path, `${JSON.stringify(state, null, 2)}\n`);
+}
+async function healthOk(input) {
+    try {
+        const response = await input.fetch(`${baseUrl(input.state)}/health`);
+        if (!response.ok) {
+            return { ok: false, detail: `Health check returned HTTP ${response.status}: ${await response.text()}` };
+        }
+        const body = (await response.json());
+        if (!body || typeof body !== 'object' || Array.isArray(body)) {
+            return { ok: false, detail: 'Health check returned non-object JSON' };
+        }
+        const record = body;
+        if (record.status !== 'healthy') {
+            return { ok: false, detail: `Health check returned status ${String(record.status)}` };
+        }
+        if (record.version !== input.cliVersion) {
+            return {
+                ok: false,
+                detail: `Daemon version ${String(record.version)} does not match CLI ${input.cliVersion}`,
+            };
+        }
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+export async function readManagedPythonDaemonStatus(options) {
+    const layout = managedPythonRuntimeLayout(options);
+    let state;
+    try {
+        state = await readState(layout.daemonStatePath);
+    }
+    catch (error) {
+        return {
+            kind: 'stale',
+            detail: `Daemon state is invalid: ${error instanceof Error ? error.message : String(error)}`,
+            layout,
+        };
+    }
+    if (!state) {
+        return { kind: 'stopped', detail: `No daemon state at ${layout.daemonStatePath}`, layout };
+    }
+    if (state.version !== options.cliVersion) {
+        return {
+            kind: 'stale',
+            detail: `Daemon is for CLI ${state.version}, current CLI is ${options.cliVersion}`,
+            layout,
+            state,
+        };
+    }
+    const processAlive = options.processAlive ?? defaultProcessAlive;
+    if (!processAlive(state.pid)) {
+        return { kind: 'stale', detail: `Daemon process ${state.pid} is not running`, layout, state };
+    }
+    const health = await healthOk({
+        state,
+        cliVersion: options.cliVersion,
+        fetch: options.fetch ?? defaultFetch,
+    });
+    if (!health.ok) {
+        return { kind: 'stale', detail: health.detail, layout, state };
+    }
+    return { kind: 'running', detail: `Daemon running at ${baseUrl(state)}`, layout, state, baseUrl: baseUrl(state) };
+}
+export async function allocateDaemonPort() {
+    return await new Promise((resolve, reject) => {
+        const server = createServer();
+        server.on('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            server.close(() => {
+                if (address && typeof address === 'object') {
+                    resolve(address.port);
+                    return;
+                }
+                reject(new Error('Failed to allocate a daemon port'));
+            });
+        });
+    });
+}
+async function waitForHealth(input) {
+    const deadline = Date.now() + input.timeoutMs;
+    let lastDetail = 'daemon did not answer health checks';
+    while (Date.now() <= deadline) {
+        const health = await healthOk({
+            state: input.state,
+            cliVersion: input.cliVersion,
+            fetch: input.fetch,
+        });
+        if (health.ok) {
+            return;
+        }
+        lastDetail = health.detail;
+        await delay(input.pollIntervalMs);
+    }
+    throw new Error(`KTX Python daemon failed to start: ${lastDetail}. stderr: ${input.state.stderrLog}`);
+}
+async function removeState(layout) {
+    await rm(layout.daemonStatePath, { force: true });
+}
+async function stopRecordedDaemon(input) {
+    if (input.processAlive(input.state.pid)) {
+        input.killProcess(input.state.pid);
+    }
+    await removeState(input.layout);
+}
+export async function startManagedPythonDaemon(options) {
+    const features = normalizeFeatures(options.features);
+    const installRuntime = options.installRuntime ?? installManagedPythonRuntime;
+    const layoutOverrides = {
+        ...(options.runtimeRoot !== undefined ? { runtimeRoot: options.runtimeRoot } : {}),
+        ...(options.assetDir !== undefined ? { assetDir: options.assetDir } : {}),
+        ...(options.platform !== undefined ? { platform: options.platform } : {}),
+        ...(options.env !== undefined ? { env: options.env } : {}),
+        ...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+    };
+    const layout = managedPythonRuntimeLayout({ cliVersion: options.cliVersion, ...layoutOverrides });
+    const processAlive = options.processAlive ?? defaultProcessAlive;
+    const killProcess = options.killProcess ?? defaultKillProcess;
+    const fetchImpl = options.fetch ?? defaultFetch;
+    const status = await readManagedPythonDaemonStatus({
+        cliVersion: options.cliVersion,
+        ...layoutOverrides,
+        fetch: fetchImpl,
+        processAlive,
+    });
+    if (options.force !== true && status.kind === 'running' && hasFeatures(status.state, features)) {
+        return { status: 'reused', layout, state: status.state, baseUrl: status.baseUrl };
+    }
+    if ('state' in status && status.state) {
+        await stopRecordedDaemon({ layout, state: status.state, processAlive, killProcess });
+    }
+    else {
+        await removeState(layout);
+    }
+    const installed = await installRuntime({
+        cliVersion: options.cliVersion,
+        ...layoutOverrides,
+        features,
+        force: false,
+    });
+    await mkdir(layout.versionDir, { recursive: true });
+    const stdout = await open(layout.daemonStdoutPath, 'a');
+    const stderr = await open(layout.daemonStderrPath, 'a');
+    try {
+        const port = await (options.allocatePort ?? allocateDaemonPort)();
+        const spawnDaemon = options.spawnDaemon ?? defaultSpawnDaemon;
+        const child = spawnDaemon(installed.manifest.python.daemonExecutable, ['serve-http', '--host', '127.0.0.1', '--port', String(port)], {
+            detached: true,
+            stdio: ['ignore', stdout.fd, stderr.fd],
+            env: {
+                ...process.env,
+                KTX_DAEMON_VERSION: options.cliVersion,
+            },
+        });
+        child.unref();
+        if (!child.pid) {
+            throw new Error(`KTX Python daemon did not report a pid. stderr: ${layout.daemonStderrPath}`);
+        }
+        const state = {
+            schemaVersion: 1,
+            pid: child.pid,
+            host: '127.0.0.1',
+            port,
+            version: options.cliVersion,
+            features: installed.manifest.features,
+            startedAt: (options.now ?? (() => new Date()))().toISOString(),
+            stdoutLog: layout.daemonStdoutPath,
+            stderrLog: layout.daemonStderrPath,
+        };
+        await waitForHealth({
+            state,
+            cliVersion: options.cliVersion,
+            fetch: fetchImpl,
+            timeoutMs: options.startupTimeoutMs ?? 10_000,
+            pollIntervalMs: options.pollIntervalMs ?? 100,
+        });
+        await writeState(layout.daemonStatePath, state);
+        return { status: 'started', layout, state, baseUrl: baseUrl(state) };
+    }
+    finally {
+        await stdout.close();
+        await stderr.close();
+    }
+}
+export async function stopManagedPythonDaemon(options) {
+    const layout = managedPythonRuntimeLayout(options);
+    const state = await readState(layout.daemonStatePath);
+    if (!state) {
+        return { status: 'already-stopped', layout };
+    }
+    await stopRecordedDaemon({
+        layout,
+        state,
+        processAlive: options.processAlive ?? defaultProcessAlive,
+        killProcess: options.killProcess ?? defaultKillProcess,
+    });
+    return { status: 'stopped', layout, state };
+}

package/dist/managed-python-daemon.test.d.ts

@@ -0,0 +1 @@
+export {};