@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/dist/managed-python-runtime.js

@@ -0,0 +1,311 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { access, appendFile, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { z } from 'zod';
+const execFileAsync = promisify(execFile);
+export const runtimeFeatureSchema = z.enum(['core', 'local-embeddings']);
+const runtimeAssetManifestSchema = z.object({
+    schemaVersion: z.literal(1),
+    distributionName: z.literal('kaelio-ktx'),
+    normalizedName: z.literal('kaelio_ktx'),
+    version: z.string().min(1),
+    wheel: z.object({
+        file: z.string().min(1),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        bytes: z.number().int().nonnegative(),
+    }),
+});
+const installedRuntimeManifestSchema = z.object({
+    schemaVersion: z.literal(1),
+    cliVersion: z.string().min(1),
+    installedAt: z.string().min(1),
+    asset: runtimeAssetManifestSchema,
+    features: z.array(runtimeFeatureSchema).min(1),
+    python: z.object({
+        executable: z.string().min(1),
+        daemonExecutable: z.string().min(1),
+    }),
+    installLog: z.string().min(1),
+});
+export const MISSING_UV_RUNTIME_INSTALL_MESSAGE = 'uv is required to install the KTX Python runtime. KTX does not download uv automatically. Install uv, make sure it is on PATH, and retry: ktx runtime install --yes';
+function defaultAssetDir() {
+    return fileURLToPath(new URL('../assets/python/', import.meta.url));
+}
+function runtimeRootFor(input) {
+    if (input.env.KTX_RUNTIME_ROOT) {
+        return input.env.KTX_RUNTIME_ROOT;
+    }
+    if (input.platform === 'darwin') {
+        return join(input.homeDir, 'Library', 'Application Support', 'kaelio', 'ktx', 'runtime');
+    }
+    if (input.platform === 'win32') {
+        return join(input.env.LOCALAPPDATA ?? join(input.homeDir, 'AppData', 'Local'), 'Kaelio', 'KTX', 'runtime');
+    }
+    return join(input.env.XDG_DATA_HOME ?? join(input.homeDir, '.local', 'share'), 'kaelio', 'ktx', 'runtime');
+}
+function executablePath(venvDir, platform, name) {
+    if (platform === 'win32') {
+        return join(venvDir, 'Scripts', `${name}.exe`);
+    }
+    return join(venvDir, 'bin', name);
+}
+export function managedPythonRuntimeLayout(options) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const homeDir = options.homeDir ?? homedir();
+    const runtimeRoot = options.runtimeRoot ?? runtimeRootFor({ platform, env, homeDir });
+    const versionDir = join(runtimeRoot, options.cliVersion);
+    const venvDir = join(versionDir, '.venv');
+    const assetDir = options.assetDir ?? defaultAssetDir();
+    return {
+        cliVersion: options.cliVersion,
+        runtimeRoot,
+        versionDir,
+        venvDir,
+        manifestPath: join(versionDir, 'manifest.json'),
+        installLogPath: join(versionDir, 'install.log'),
+        assetDir,
+        assetManifestPath: join(assetDir, 'manifest.json'),
+        pythonPath: executablePath(venvDir, platform, 'python'),
+        daemonPath: executablePath(venvDir, platform, 'ktx-daemon'),
+        daemonStatePath: join(versionDir, 'daemon.json'),
+        daemonStdoutPath: join(versionDir, 'daemon.stdout.log'),
+        daemonStderrPath: join(versionDir, 'daemon.stderr.log'),
+    };
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function assertSafeWheelFilename(file) {
+    if (file !== basename(file) || file.includes('/') || file.includes('\\')) {
+        throw new Error(`Unsafe runtime wheel filename in bundled manifest: ${file}`);
+    }
+}
+async function readJsonFile(path) {
+    return JSON.parse(await readFile(path, 'utf8'));
+}
+export async function verifyRuntimeAsset(input) {
+    const manifestPath = join(input.assetDir, 'manifest.json');
+    const manifest = runtimeAssetManifestSchema.parse(await readJsonFile(manifestPath));
+    assertSafeWheelFilename(manifest.wheel.file);
+    const wheelPath = join(input.assetDir, manifest.wheel.file);
+    const wheel = await readFile(wheelPath);
+    const sha256 = createHash('sha256').update(wheel).digest('hex');
+    if (sha256 !== manifest.wheel.sha256 || wheel.byteLength !== manifest.wheel.bytes) {
+        throw new Error(`Bundled Python runtime wheel checksum mismatch: ${wheelPath}`);
+    }
+    return { manifest, wheelPath };
+}
+function normalizeFeatures(features) {
+    const requested = new Set(['core', ...features]);
+    return runtimeFeatureSchema.options.filter((feature) => requested.has(feature));
+}
+async function readInstalledManifest(path) {
+    if (!(await pathExists(path))) {
+        return undefined;
+    }
+    return installedRuntimeManifestSchema.parse(await readJsonFile(path));
+}
+function hasFeatures(manifest, features) {
+    return normalizeFeatures(features).every((feature) => manifest.features.includes(feature));
+}
+async function defaultExec(command, args, options = {}) {
+    const result = await execFileAsync(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024 * 20,
+    });
+    return { stdout: result.stdout, stderr: result.stderr };
+}
+function errorOutput(error) {
+    const value = error;
+    return {
+        stdout: typeof value.stdout === 'string' ? value.stdout : '',
+        stderr: typeof value.stderr === 'string' ? value.stderr : '',
+    };
+}
+async function runLogged(input) {
+    await appendFile(input.logPath, `$ ${input.command} ${input.args.join(' ')}\n`);
+    try {
+        const result = await input.exec(input.command, input.args, { cwd: input.cwd });
+        if (result.stdout) {
+            await appendFile(input.logPath, result.stdout.endsWith('\n') ? result.stdout : `${result.stdout}\n`);
+        }
+        if (result.stderr) {
+            await appendFile(input.logPath, result.stderr.endsWith('\n') ? result.stderr : `${result.stderr}\n`);
+        }
+        return result;
+    }
+    catch (error) {
+        const output = errorOutput(error);
+        if (output.stdout) {
+            await appendFile(input.logPath, output.stdout.endsWith('\n') ? output.stdout : `${output.stdout}\n`);
+        }
+        if (output.stderr) {
+            await appendFile(input.logPath, output.stderr.endsWith('\n') ? output.stderr : `${output.stderr}\n`);
+        }
+        throw new Error(`Python runtime install failed. Install log: ${input.logPath}`);
+    }
+}
+async function ensureUv(exec) {
+    try {
+        const result = await exec('uv', ['--version']);
+        return result.stdout.trim() || 'uv available';
+    }
+    catch {
+        throw new Error(MISSING_UV_RUNTIME_INSTALL_MESSAGE);
+    }
+}
+export async function installManagedPythonRuntime(options) {
+    const layout = managedPythonRuntimeLayout(options);
+    const exec = options.exec ?? defaultExec;
+    const features = normalizeFeatures(options.features);
+    const asset = await verifyRuntimeAsset({ assetDir: layout.assetDir });
+    const existing = await readInstalledManifest(layout.manifestPath);
+    if (options.force !== true &&
+        existing &&
+        existing.cliVersion === options.cliVersion &&
+        existing.asset.wheel.sha256 === asset.manifest.wheel.sha256 &&
+        hasFeatures(existing, features) &&
+        (await pathExists(existing.python.executable)) &&
+        (await pathExists(existing.python.daemonExecutable))) {
+        return { status: 'ready', layout, asset, manifest: existing };
+    }
+    await rm(layout.versionDir, { recursive: true, force: true });
+    await mkdir(layout.versionDir, { recursive: true });
+    await writeFile(layout.installLogPath, '');
+    await ensureUv(exec);
+    await runLogged({ exec, logPath: layout.installLogPath, command: 'uv', args: ['venv', layout.venvDir] });
+    const wheelSpec = features.includes('local-embeddings') ? `${asset.wheelPath}[local-embeddings]` : asset.wheelPath;
+    await runLogged({
+        exec,
+        logPath: layout.installLogPath,
+        command: 'uv',
+        args: ['pip', 'install', '--python', layout.pythonPath, wheelSpec],
+    });
+    const manifest = {
+        schemaVersion: 1,
+        cliVersion: options.cliVersion,
+        installedAt: new Date().toISOString(),
+        asset: asset.manifest,
+        features,
+        python: {
+            executable: layout.pythonPath,
+            daemonExecutable: layout.daemonPath,
+        },
+        installLog: layout.installLogPath,
+    };
+    await writeFile(layout.manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return { status: 'installed', layout, asset, manifest };
+}
+export async function readManagedPythonRuntimeStatus(options) {
+    const layout = managedPythonRuntimeLayout(options);
+    let manifest;
+    try {
+        manifest = await readInstalledManifest(layout.manifestPath);
+    }
+    catch (error) {
+        return {
+            kind: 'broken',
+            detail: `Runtime manifest is invalid: ${error instanceof Error ? error.message : String(error)}`,
+            layout,
+        };
+    }
+    if (!manifest) {
+        return { kind: 'missing', detail: `No runtime manifest at ${layout.manifestPath}`, layout };
+    }
+    if (manifest.cliVersion !== options.cliVersion) {
+        return {
+            kind: 'mismatched',
+            detail: `Runtime is for CLI ${manifest.cliVersion}, current CLI is ${options.cliVersion}`,
+            layout,
+            manifest,
+        };
+    }
+    if (!(await pathExists(manifest.python.executable))) {
+        return { kind: 'broken', detail: `Missing Python executable: ${manifest.python.executable}`, layout, manifest };
+    }
+    if (!(await pathExists(manifest.python.daemonExecutable))) {
+        return { kind: 'broken', detail: `Missing ktx-daemon executable: ${manifest.python.daemonExecutable}`, layout, manifest };
+    }
+    return { kind: 'ready', detail: `Runtime ready at ${layout.versionDir}`, layout, manifest };
+}
+function check(status, input) {
+    return { status, ...input };
+}
+export async function doctorManagedPythonRuntime(options) {
+    const exec = options.exec ?? defaultExec;
+    const checks = [];
+    try {
+        const version = await ensureUv(exec);
+        checks.push(check('pass', { id: 'uv', label: 'uv', detail: version }));
+    }
+    catch (error) {
+        checks.push(check('fail', {
+            id: 'uv',
+            label: 'uv',
+            detail: error instanceof Error ? error.message : String(error),
+            fix: 'Install uv, make sure it is on PATH, and run: ktx runtime install --yes',
+        }));
+    }
+    try {
+        const asset = await verifyRuntimeAsset({ assetDir: managedPythonRuntimeLayout(options).assetDir });
+        checks.push(check('pass', { id: 'asset', label: 'Bundled Python wheel', detail: asset.wheelPath }));
+    }
+    catch (error) {
+        checks.push(check('fail', {
+            id: 'asset',
+            label: 'Bundled Python wheel',
+            detail: error instanceof Error ? error.message : String(error),
+            fix: 'Run: pnpm run artifacts:check',
+        }));
+    }
+    const status = await readManagedPythonRuntimeStatus(options);
+    checks.push(check(status.kind === 'ready' ? 'pass' : 'fail', {
+        id: 'runtime',
+        label: 'Managed Python runtime',
+        detail: status.detail,
+        ...(status.kind === 'ready' ? {} : { fix: 'Run: ktx runtime install --yes' }),
+    }));
+    return checks;
+}
+export async function pruneManagedPythonRuntimes(options) {
+    if (!(await pathExists(options.runtimeRoot))) {
+        return { runtimeRoot: options.runtimeRoot, stale: [], kept: [], removed: [] };
+    }
+    const entries = await readdir(options.runtimeRoot);
+    const stale = [];
+    const kept = [];
+    for (const entry of entries) {
+        const path = join(options.runtimeRoot, entry);
+        const info = await stat(path);
+        if (!info.isDirectory()) {
+            continue;
+        }
+        if (entry === options.cliVersion) {
+            kept.push(path);
+        }
+        else {
+            stale.push(path);
+        }
+    }
+    const removed = [];
+    if (options.dryRun !== true) {
+        for (const path of stale) {
+            await rm(path, { recursive: true, force: true });
+            removed.push(path);
+        }
+    }
+    return { runtimeRoot: options.runtimeRoot, stale, kept, removed };
+}

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

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

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

@@ -0,0 +1,373 @@
+import { createHash } from 'node:crypto';
+import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { MISSING_UV_RUNTIME_INSTALL_MESSAGE, doctorManagedPythonRuntime, installManagedPythonRuntime, managedPythonRuntimeLayout, pruneManagedPythonRuntimes, readManagedPythonRuntimeStatus, verifyRuntimeAsset, } from './managed-python-runtime.js';
+async function writeAsset(root, contents = 'wheel-bytes') {
+    const assetDir = join(root, 'assets', 'python');
+    await mkdir(assetDir, { recursive: true });
+    const wheelPath = join(assetDir, 'kaelio_ktx-0.1.0-py3-none-any.whl');
+    await writeFile(wheelPath, contents);
+    await writeFile(join(assetDir, 'manifest.json'), `${JSON.stringify({
+        schemaVersion: 1,
+        distributionName: 'kaelio-ktx',
+        normalizedName: 'kaelio_ktx',
+        version: '0.1.0',
+        wheel: {
+            file: 'kaelio_ktx-0.1.0-py3-none-any.whl',
+            sha256: createHash('sha256').update(contents).digest('hex'),
+            bytes: Buffer.byteLength(contents),
+        },
+    }, null, 2)}\n`);
+    return { assetDir, wheelPath };
+}
+describe('managedPythonRuntimeLayout', () => {
+    it('uses the macOS application-support runtime root', () => {
+        const layout = managedPythonRuntimeLayout({
+            cliVersion: '0.2.0',
+            platform: 'darwin',
+            env: {},
+            homeDir: '/Users/alex',
+            assetDir: '/repo/packages/cli/assets/python',
+        });
+        expect(layout.runtimeRoot).toBe('/Users/alex/Library/Application Support/kaelio/ktx/runtime');
+        expect(layout.versionDir).toBe('/Users/alex/Library/Application Support/kaelio/ktx/runtime/0.2.0');
+        expect(layout.venvDir).toBe('/Users/alex/Library/Application Support/kaelio/ktx/runtime/0.2.0/.venv');
+        expect(layout.pythonPath).toBe('/Users/alex/Library/Application Support/kaelio/ktx/runtime/0.2.0/.venv/bin/python');
+        expect(layout.daemonPath).toBe('/Users/alex/Library/Application Support/kaelio/ktx/runtime/0.2.0/.venv/bin/ktx-daemon');
+        expect(layout.daemonStatePath).toBe('/Users/alex/Library/Application Support/kaelio/ktx/runtime/0.2.0/daemon.json');
+        expect(layout.daemonStdoutPath).toBe('/Users/alex/Library/Application Support/kaelio/ktx/runtime/0.2.0/daemon.stdout.log');
+        expect(layout.daemonStderrPath).toBe('/Users/alex/Library/Application Support/kaelio/ktx/runtime/0.2.0/daemon.stderr.log');
+        expect(layout.assetManifestPath).toBe('/repo/packages/cli/assets/python/manifest.json');
+    });
+    it('honors KTX_RUNTIME_ROOT before platform defaults', () => {
+        const layout = managedPythonRuntimeLayout({
+            cliVersion: '0.2.0',
+            platform: 'darwin',
+            env: { KTX_RUNTIME_ROOT: '/tmp/ktx-runtime' },
+            homeDir: '/Users/alex',
+            assetDir: '/repo/packages/cli/assets/python',
+        });
+        expect(layout.runtimeRoot).toBe('/tmp/ktx-runtime');
+        expect(layout.versionDir).toBe('/tmp/ktx-runtime/0.2.0');
+    });
+    it('honors XDG_DATA_HOME on Linux', () => {
+        const layout = managedPythonRuntimeLayout({
+            cliVersion: '0.2.0',
+            platform: 'linux',
+            env: { XDG_DATA_HOME: '/var/xdg' },
+            homeDir: '/home/alex',
+            assetDir: '/repo/packages/cli/assets/python',
+        });
+        expect(layout.runtimeRoot).toBe('/var/xdg/kaelio/ktx/runtime');
+        expect(layout.versionDir).toBe('/var/xdg/kaelio/ktx/runtime/0.2.0');
+    });
+    it('uses LocalAppData on Windows', () => {
+        const layout = managedPythonRuntimeLayout({
+            cliVersion: '0.2.0',
+            platform: 'win32',
+            env: { LOCALAPPDATA: 'C:\\Users\\Alex\\AppData\\Local' },
+            homeDir: 'C:\\Users\\Alex',
+            assetDir: 'C:\\repo\\packages\\cli\\assets\\python',
+        });
+        expect(layout.runtimeRoot).toBe('C:\\Users\\Alex\\AppData\\Local/Kaelio/KTX/runtime');
+        expect(layout.pythonPath).toBe('C:\\Users\\Alex\\AppData\\Local/Kaelio/KTX/runtime/0.2.0/.venv/Scripts/python.exe');
+        expect(layout.daemonPath).toBe('C:\\Users\\Alex\\AppData\\Local/Kaelio/KTX/runtime/0.2.0/.venv/Scripts/ktx-daemon.exe');
+    });
+});
+describe('verifyRuntimeAsset', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-runtime-asset-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('reads the manifest and verifies the wheel checksum', async () => {
+        const { assetDir, wheelPath } = await writeAsset(tempDir, 'valid-wheel');
+        const asset = await verifyRuntimeAsset({ assetDir });
+        expect(asset.manifest.distributionName).toBe('kaelio-ktx');
+        expect(asset.manifest.normalizedName).toBe('kaelio_ktx');
+        expect(asset.wheelPath).toBe(wheelPath);
+    });
+    it('rejects a wheel whose checksum does not match the manifest', async () => {
+        const { assetDir, wheelPath } = await writeAsset(tempDir, 'original');
+        await writeFile(wheelPath, 'tampered');
+        await expect(verifyRuntimeAsset({ assetDir })).rejects.toThrow(/Bundled Python runtime wheel checksum mismatch/);
+    });
+    it('rejects an unsafe wheel filename in the manifest', async () => {
+        const { assetDir } = await writeAsset(tempDir, 'valid-wheel');
+        await writeFile(join(assetDir, 'manifest.json'), `${JSON.stringify({
+            schemaVersion: 1,
+            distributionName: 'kaelio-ktx',
+            normalizedName: 'kaelio_ktx',
+            version: '0.1.0',
+            wheel: {
+                file: '../kaelio_ktx-0.1.0-py3-none-any.whl',
+                sha256: 'a'.repeat(64),
+                bytes: 1,
+            },
+        })}\n`);
+        await expect(verifyRuntimeAsset({ assetDir })).rejects.toThrow(/Unsafe runtime wheel filename/);
+    });
+});
+describe('installManagedPythonRuntime', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-runtime-install-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('creates a venv, installs the core wheel, and writes a manifest', async () => {
+        const { assetDir } = await writeAsset(tempDir, 'core-wheel');
+        const commands = [];
+        const exec = vi.fn(async (command, args) => {
+            commands.push({ command, args });
+            return { stdout: command === 'uv' && args[0] === '--version' ? 'uv 0.9.5\n' : '', stderr: '' };
+        });
+        const result = await installManagedPythonRuntime({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+            features: ['core'],
+            exec,
+        });
+        expect(result.status).toBe('installed');
+        expect(commands).toEqual([
+            { command: 'uv', args: ['--version'] },
+            { command: 'uv', args: ['venv', result.layout.venvDir] },
+            {
+                command: 'uv',
+                args: ['pip', 'install', '--python', result.layout.pythonPath, result.asset.wheelPath],
+            },
+        ]);
+        const manifest = JSON.parse(await readFile(result.layout.manifestPath, 'utf8'));
+        expect(manifest.cliVersion).toBe('0.2.0');
+        expect(manifest.features).toEqual(['core']);
+        expect(manifest.python.executable).toBe(result.layout.pythonPath);
+        expect(manifest.python.daemonExecutable).toBe(result.layout.daemonPath);
+    });
+    it('installs the local-embeddings extra when requested', async () => {
+        const { assetDir } = await writeAsset(tempDir, 'embedding-wheel');
+        const commands = [];
+        const exec = vi.fn(async (command, args) => {
+            commands.push({ command, args });
+            return { stdout: command === 'uv' && args[0] === '--version' ? 'uv 0.9.5\n' : '', stderr: '' };
+        });
+        const result = await installManagedPythonRuntime({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+            features: ['local-embeddings'],
+            exec,
+        });
+        expect(commands.at(-1)).toEqual({
+            command: 'uv',
+            args: ['pip', 'install', '--python', result.layout.pythonPath, `${result.asset.wheelPath}[local-embeddings]`],
+        });
+        const manifest = JSON.parse(await readFile(result.layout.manifestPath, 'utf8'));
+        expect(manifest.features).toEqual(['core', 'local-embeddings']);
+    });
+    it('fails with the hard-prerequisite message when uv is missing', async () => {
+        const { assetDir } = await writeAsset(tempDir, 'core-wheel');
+        const commands = [];
+        const exec = vi.fn(async (command, args) => {
+            commands.push({ command, args });
+            throw new Error('spawn uv ENOENT');
+        });
+        await expect(installManagedPythonRuntime({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+            features: ['core'],
+            exec,
+        })).rejects.toThrow(MISSING_UV_RUNTIME_INSTALL_MESSAGE);
+        expect(commands).toEqual([{ command: 'uv', args: ['--version'] }]);
+    });
+    it('reuses an existing compatible runtime when force is false', async () => {
+        const { assetDir } = await writeAsset(tempDir, 'core-wheel');
+        const exec = vi.fn(async (command, args) => ({
+            stdout: command === 'uv' && args[0] === '--version' ? 'uv 0.9.5\n' : '',
+            stderr: '',
+        }));
+        const first = await installManagedPythonRuntime({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+            features: ['core'],
+            exec,
+        });
+        await mkdir(join(first.layout.venvDir, 'bin'), { recursive: true });
+        await writeFile(first.layout.pythonPath, '#!/usr/bin/env python\n');
+        await writeFile(first.layout.daemonPath, '#!/usr/bin/env python\n');
+        const second = await installManagedPythonRuntime({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+            features: ['core'],
+            exec,
+        });
+        expect(second.status).toBe('ready');
+        expect(exec).toHaveBeenCalledTimes(3);
+    });
+    it('keeps failed install logs in the versioned runtime directory', async () => {
+        const { assetDir } = await writeAsset(tempDir, 'core-wheel');
+        const exec = vi.fn(async (command, args) => {
+            if (command === 'uv' && args[0] === 'venv') {
+                throw Object.assign(new Error('uv venv failed'), { stdout: 'creating\n', stderr: 'bad python\n' });
+            }
+            return { stdout: command === 'uv' && args[0] === '--version' ? 'uv 0.9.5\n' : '', stderr: '' };
+        });
+        await expect(installManagedPythonRuntime({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+            features: ['core'],
+            exec,
+        })).rejects.toThrow(/Python runtime install failed/);
+        const log = await readFile(join(tempDir, 'runtime', '0.2.0', 'install.log'), 'utf8');
+        expect(log).toContain('$ uv venv');
+        expect(log).toContain('bad python');
+    });
+});
+describe('readManagedPythonRuntimeStatus', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-runtime-status-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('reports missing before install', async () => {
+        const status = await readManagedPythonRuntimeStatus({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir: join(tempDir, 'assets', 'python'),
+        });
+        expect(status.kind).toBe('missing');
+        expect(status.detail).toContain('No runtime manifest');
+    });
+    it('reports ready when manifest and executables exist', async () => {
+        const { assetDir } = await writeAsset(tempDir, 'core-wheel');
+        const exec = vi.fn(async (command, args) => ({
+            stdout: command === 'uv' && args[0] === '--version' ? 'uv 0.9.5\n' : '',
+            stderr: '',
+        }));
+        const install = await installManagedPythonRuntime({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+            features: ['core'],
+            exec,
+        });
+        await mkdir(join(install.layout.venvDir, 'bin'), { recursive: true });
+        await writeFile(install.layout.pythonPath, '#!/usr/bin/env python\n');
+        await writeFile(install.layout.daemonPath, '#!/usr/bin/env python\n');
+        const status = await readManagedPythonRuntimeStatus({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+        });
+        expect(status.kind).toBe('ready');
+        expect(status.manifest?.features).toEqual(['core']);
+    });
+    it('reports broken when an executable is missing', async () => {
+        const { assetDir } = await writeAsset(tempDir, 'core-wheel');
+        const exec = vi.fn(async (command, args) => ({
+            stdout: command === 'uv' && args[0] === '--version' ? 'uv 0.9.5\n' : '',
+            stderr: '',
+        }));
+        await installManagedPythonRuntime({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+            features: ['core'],
+            exec,
+        });
+        const status = await readManagedPythonRuntimeStatus({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+        });
+        expect(status.kind).toBe('broken');
+        expect(status.detail).toContain('Missing Python executable');
+    });
+});
+describe('doctorManagedPythonRuntime', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-runtime-doctor-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('checks uv, bundled assets, and installed runtime status', async () => {
+        const { assetDir } = await writeAsset(tempDir, 'core-wheel');
+        const exec = vi.fn(async (command, args) => ({
+            stdout: command === 'uv' && args[0] === '--version' ? 'uv 0.9.5\n' : '',
+            stderr: '',
+        }));
+        const checks = await doctorManagedPythonRuntime({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+            exec,
+        });
+        expect(checks.map((check) => [check.id, check.status])).toEqual([
+            ['uv', 'pass'],
+            ['asset', 'pass'],
+            ['runtime', 'fail'],
+        ]);
+        expect(checks[2]?.fix).toBe('Run: ktx runtime install --yes');
+    });
+    it('reports uv as a hard prerequisite when uv is missing', async () => {
+        const { assetDir } = await writeAsset(tempDir, 'core-wheel');
+        const exec = vi.fn(async () => {
+            throw new Error('spawn uv ENOENT');
+        });
+        const checks = await doctorManagedPythonRuntime({
+            cliVersion: '0.2.0',
+            runtimeRoot: join(tempDir, 'runtime'),
+            assetDir,
+            exec,
+        });
+        expect(checks[0]).toEqual({
+            id: 'uv',
+            label: 'uv',
+            status: 'fail',
+            detail: MISSING_UV_RUNTIME_INSTALL_MESSAGE,
+            fix: 'Install uv, make sure it is on PATH, and run: ktx runtime install --yes',
+        });
+    });
+});
+describe('pruneManagedPythonRuntimes', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-runtime-prune-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('removes stale version directories and keeps the current version', async () => {
+        const runtimeRoot = join(tempDir, 'runtime');
+        await mkdir(join(runtimeRoot, '0.1.0'), { recursive: true });
+        await mkdir(join(runtimeRoot, '0.2.0'), { recursive: true });
+        await writeFile(join(runtimeRoot, 'README.txt'), 'not a runtime directory\n');
+        const result = await pruneManagedPythonRuntimes({ cliVersion: '0.2.0', runtimeRoot });
+        expect(result.removed).toEqual([join(runtimeRoot, '0.1.0')]);
+        expect(result.kept).toEqual([join(runtimeRoot, '0.2.0')]);
+        await expect(stat(join(runtimeRoot, '0.1.0'))).rejects.toThrow();
+        expect(await readdir(runtimeRoot)).toEqual(['0.2.0', 'README.txt']);
+    });
+    it('supports dry-run without deleting stale directories', async () => {
+        const runtimeRoot = join(tempDir, 'runtime');
+        await mkdir(join(runtimeRoot, '0.1.0'), { recursive: true });
+        await mkdir(join(runtimeRoot, '0.2.0'), { recursive: true });
+        const result = await pruneManagedPythonRuntimes({ cliVersion: '0.2.0', runtimeRoot, dryRun: true });
+        expect(result.removed).toEqual([]);
+        expect(result.stale).toEqual([join(runtimeRoot, '0.1.0')]);
+        expect(await readdir(runtimeRoot)).toEqual(['0.1.0', '0.2.0']);
+    });
+});