@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/dist/managed-python-daemon.js

@@ -0,0 +1,585 @@
+import { execFile, 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 { promisify } from 'node:util';
+import { z } from 'zod';
+import { installManagedPythonRuntime, managedPythonDaemonLayout, runtimeFeatureSchema, } from './managed-python-runtime.js';
+const execFileAsync = promisify(execFile);
+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, signal = 'SIGTERM') {
+    try {
+        process.kill(pid, signal);
+    }
+    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 = managedPythonDaemonLayout(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);
+    }
+    const finalHealth = await healthOk({
+        state: input.state,
+        cliVersion: input.cliVersion,
+        fetch: input.fetch,
+    });
+    if (finalHealth.ok) {
+        return;
+    }
+    lastDetail = finalHealth.detail;
+    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);
+}
+async function removeStatePaths(paths) {
+    await Promise.all([...new Set(paths)].map((path) => rm(path, { force: true })));
+}
+function candidateUrl(candidate) {
+    if (!candidate.host || !candidate.port) {
+        return undefined;
+    }
+    return `http://${candidate.host}:${candidate.port}`;
+}
+function candidateEntry(candidate) {
+    return {
+        pid: candidate.pid,
+        source: candidate.source,
+        ...(candidateUrl(candidate) ? { url: candidateUrl(candidate) } : {}),
+        ...(candidate.version ? { version: candidate.version } : {}),
+        ...(candidate.command ? { command: candidate.command } : {}),
+        statePaths: [...candidate.statePaths],
+    };
+}
+async function probeCandidateHealth(candidate, timeoutMs) {
+    const url = candidateUrl(candidate);
+    if (!url) {
+        return undefined;
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        const response = await fetch(`${url}/health`, { signal: controller.signal });
+        if (!response.ok) {
+            return 'unreachable';
+        }
+        const body = (await response.json());
+        if (!body || typeof body !== 'object' || Array.isArray(body)) {
+            return 'unreachable';
+        }
+        return body.status === 'healthy' ? 'healthy' : 'unreachable';
+    }
+    catch {
+        return 'unreachable';
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function readStateCandidates(statePath) {
+    let state;
+    try {
+        state = await readState(statePath);
+    }
+    catch {
+        return [];
+    }
+    if (!state) {
+        return [];
+    }
+    return [
+        {
+            pid: state.pid,
+            source: 'state',
+            host: state.host,
+            port: state.port,
+            version: state.version,
+            statePaths: [statePath],
+        },
+    ];
+}
+function tokenizeCommand(command) {
+    const tokens = [];
+    for (const match of command.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)) {
+        tokens.push(match[1] ?? match[2] ?? match[3] ?? '');
+    }
+    return tokens;
+}
+function executableName(token) {
+    return token.split(/[\\/]/).at(-1) ?? token;
+}
+function isKtxDaemonExecutable(token) {
+    return executableName(token) === 'ktx-daemon' || executableName(token) === 'ktx-daemon.exe';
+}
+function normalizedExecutableName(token) {
+    return executableName(token).replace(/\.exe$/i, '').toLowerCase();
+}
+function hasUvRunPrefix(tokens, daemonIndex) {
+    return normalizedExecutableName(tokens[0] ?? '') === 'uv' && tokens.slice(1, daemonIndex).includes('run');
+}
+function isPythonExecutable(token) {
+    const name = normalizedExecutableName(token);
+    return name === 'python' || name === 'python3';
+}
+function hasPythonModulePrefix(tokens, moduleFlagIndex) {
+    if (moduleFlagIndex === 1 && isPythonExecutable(tokens[0] ?? '')) {
+        return true;
+    }
+    return (normalizedExecutableName(tokens[0] ?? '') === 'uv' &&
+        tokens.slice(1, moduleFlagIndex).includes('run') &&
+        tokens.some((token, index) => index < moduleFlagIndex && isPythonExecutable(token)));
+}
+function isKtxDaemonServeHttp(tokens) {
+    for (let index = 0; index < tokens.length; index += 1) {
+        if (isKtxDaemonExecutable(tokens[index] ?? '') &&
+            tokens[index + 1] === 'serve-http' &&
+            (index === 0 || hasUvRunPrefix(tokens, index))) {
+            return true;
+        }
+        if (tokens[index] === '-m' &&
+            tokens[index + 1] === 'ktx_daemon' &&
+            tokens[index + 2] === 'serve-http' &&
+            hasPythonModulePrefix(tokens, index)) {
+            return true;
+        }
+    }
+    return false;
+}
+function parseCommandOption(tokens, option) {
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token === option) {
+            return tokens[index + 1];
+        }
+        if (token?.startsWith(`${option}=`)) {
+            return token.slice(option.length + 1);
+        }
+    }
+    return undefined;
+}
+function processCandidate(processInfo) {
+    const tokens = tokenizeCommand(processInfo.command);
+    if (!isKtxDaemonServeHttp(tokens)) {
+        return undefined;
+    }
+    const host = parseCommandOption(tokens, '--host') ?? '127.0.0.1';
+    const rawPort = parseCommandOption(tokens, '--port');
+    const parsedPort = rawPort ? Number.parseInt(rawPort, 10) : 8765;
+    const port = Number.isInteger(parsedPort) && parsedPort >= 1 && parsedPort <= 65535 ? parsedPort : 8765;
+    return {
+        pid: processInfo.pid,
+        source: 'process',
+        host,
+        port,
+        command: processInfo.command,
+        statePaths: [],
+    };
+}
+function mergeCandidates(candidates) {
+    const byPid = new Map();
+    for (const candidate of candidates) {
+        const existing = byPid.get(candidate.pid);
+        if (!existing) {
+            byPid.set(candidate.pid, { ...candidate, statePaths: [...candidate.statePaths] });
+            continue;
+        }
+        existing.statePaths.push(...candidate.statePaths);
+        if (existing.source === 'process' && candidate.source === 'state') {
+            byPid.set(candidate.pid, {
+                ...candidate,
+                statePaths: [...new Set([...existing.statePaths, ...candidate.statePaths])],
+            });
+        }
+        else {
+            existing.statePaths = [...new Set(existing.statePaths)];
+        }
+    }
+    return [...byPid.values()].sort((left, right) => left.pid - right.pid);
+}
+function parsePosixProcessList(output) {
+    const processes = [];
+    for (const line of output.split(/\r?\n/)) {
+        const match = line.match(/^\s*(\d+)\s+(.+)$/);
+        if (!match) {
+            continue;
+        }
+        processes.push({ pid: Number.parseInt(match[1], 10), command: match[2] });
+    }
+    return processes;
+}
+function parseWindowsProcessList(output) {
+    if (!output.trim()) {
+        return [];
+    }
+    const parsed = JSON.parse(output);
+    const records = Array.isArray(parsed) ? parsed : [parsed];
+    const processes = [];
+    for (const record of records) {
+        if (!record || typeof record !== 'object') {
+            continue;
+        }
+        const value = record;
+        const pid = value.ProcessId;
+        const command = value.CommandLine;
+        if (typeof pid === 'number' && typeof command === 'string' && command.length > 0) {
+            processes.push({ pid, command });
+        }
+    }
+    return processes;
+}
+async function defaultListProcesses(platform = process.platform) {
+    if (platform === 'win32') {
+        const command = [
+            'Get-CimInstance Win32_Process',
+            '| Where-Object { $_.CommandLine -ne $null }',
+            '| Select-Object ProcessId,CommandLine',
+            '| ConvertTo-Json -Compress',
+        ].join(' ');
+        const { stdout } = await execFileAsync('powershell.exe', ['-NoProfile', '-Command', command], {
+            encoding: 'utf8',
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        return parseWindowsProcessList(stdout);
+    }
+    const { stdout } = await execFileAsync('ps', ['-axo', 'pid=,command='], {
+        encoding: 'utf8',
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return parsePosixProcessList(stdout);
+}
+async function waitUntilStopped(input) {
+    const deadline = Date.now() + input.timeoutMs;
+    do {
+        if (!input.processAlive(input.pid)) {
+            return true;
+        }
+        if (Date.now() >= deadline) {
+            break;
+        }
+        await delay(input.pollIntervalMs);
+    } while (Date.now() <= deadline);
+    return !input.processAlive(input.pid);
+}
+async function discoverStopAllCandidates(options) {
+    const layout = managedPythonDaemonLayout(options);
+    const stateCandidates = await readStateCandidates(layout.daemonStatePath);
+    const scanErrors = [];
+    let processCandidates = [];
+    try {
+        const processes = await (options.listProcesses ?? defaultListProcesses)();
+        processCandidates = processes.flatMap((processInfo) => {
+            const candidate = processCandidate(processInfo);
+            return candidate ? [candidate] : [];
+        });
+    }
+    catch (error) {
+        scanErrors.push(error instanceof Error ? error.message : String(error));
+    }
+    return {
+        layout,
+        candidates: mergeCandidates([...stateCandidates, ...processCandidates]),
+        scanErrors,
+    };
+}
+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 = managedPythonDaemonLayout({
+        cliVersion: options.cliVersion,
+        projectDir: options.projectDir,
+        ...layoutOverrides,
+    });
+    const processAlive = options.processAlive ?? defaultProcessAlive;
+    const killProcess = options.killProcess ?? defaultKillProcess;
+    const fetchImpl = options.fetch ?? defaultFetch;
+    const status = await readManagedPythonDaemonStatus({
+        cliVersion: options.cliVersion,
+        projectDir: options.projectDir,
+        ...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.daemonStateDir, { 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 = managedPythonDaemonLayout(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 };
+}
+export async function stopAllManagedPythonDaemons(options) {
+    const processAlive = options.processAlive ?? defaultProcessAlive;
+    const killProcess = options.killProcess ?? defaultKillProcess;
+    const stopGraceMs = options.stopGraceMs ?? 500;
+    const pollIntervalMs = options.pollIntervalMs ?? 50;
+    const healthProbeMs = options.healthProbeMs ?? 100;
+    const discovery = await discoverStopAllCandidates(options);
+    const stopped = [];
+    const stale = [];
+    const failed = [];
+    for (const candidate of discovery.candidates) {
+        const health = await probeCandidateHealth(candidate, healthProbeMs);
+        const entry = { ...candidateEntry(candidate), ...(health ? { health } : {}) };
+        if (!processAlive(candidate.pid)) {
+            await removeStatePaths(candidate.statePaths);
+            stale.push(entry);
+            continue;
+        }
+        try {
+            killProcess(candidate.pid, 'SIGTERM');
+            if (!(await waitUntilStopped({
+                pid: candidate.pid,
+                processAlive,
+                timeoutMs: stopGraceMs,
+                pollIntervalMs,
+            }))) {
+                killProcess(candidate.pid, 'SIGKILL');
+                if (!(await waitUntilStopped({
+                    pid: candidate.pid,
+                    processAlive,
+                    timeoutMs: stopGraceMs,
+                    pollIntervalMs,
+                }))) {
+                    failed.push({ ...entry, detail: 'Process still running after SIGKILL' });
+                    continue;
+                }
+            }
+            await removeStatePaths(candidate.statePaths);
+            stopped.push(entry);
+        }
+        catch (error) {
+            failed.push({ ...entry, detail: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return {
+        stopped,
+        stale,
+        failed,
+        scanErrors: discovery.scanErrors,
+    };
+}

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

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