@spencer-kit/coder-studio 0.1.3

package/lib/http.mjs

@@ -0,0 +1,89 @@
+// @ts-nocheck
+import { setTimeout as delay } from 'node:timers/promises';
+import { buildEndpoint } from './config.mjs';
+function adminEndpoint(endpoint) {
+    const url = new URL(endpoint);
+    const host = url.hostname;
+    if (host === '0.0.0.0' || host === '::' || host === '[::]') {
+        url.hostname = '127.0.0.1';
+    }
+    return url.toString().replace(/\/$/, '');
+}
+async function requestJson(url, init = {}) {
+    const response = await fetch(url, {
+        ...init,
+        headers: {
+            'content-type': 'application/json',
+            ...(init.headers ?? {}),
+        },
+    });
+    let body = null;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = null;
+    }
+    if (!response.ok || body?.ok === false) {
+        const error = body?.error || `${response.status}`;
+        throw new Error(error);
+    }
+    return body?.data ?? body ?? null;
+}
+export async function fetchHealth(endpoint) {
+    const response = await fetch(`${endpoint.replace(/\/$/, '')}/health`);
+    if (!response.ok) {
+        throw new Error(`health_http_${response.status}`);
+    }
+    return response.json();
+}
+export async function waitForHealth(endpoint, { timeoutMs = 15000, intervalMs = 250 } = {}) {
+    const startedAt = Date.now();
+    let lastError = null;
+    while (Date.now() - startedAt < timeoutMs) {
+        try {
+            return await fetchHealth(endpoint);
+        }
+        catch (error) {
+            lastError = error;
+            await delay(intervalMs);
+        }
+    }
+    throw lastError ?? new Error('health_timeout');
+}
+export async function requestShutdown(endpoint) {
+    const response = await fetch(`${endpoint.replace(/\/$/, '')}/api/system/shutdown`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json'
+        }
+    });
+    if (!response.ok) {
+        throw new Error(`shutdown_http_${response.status}`);
+    }
+    return response.json().catch(() => ({ ok: true }));
+}
+export async function fetchAdminConfig(endpoint) {
+    return requestJson(`${adminEndpoint(endpoint)}/api/system/config`, { method: 'GET' });
+}
+export async function patchAdminConfig(endpoint, updates) {
+    return requestJson(`${adminEndpoint(endpoint)}/api/system/config`, {
+        method: 'PATCH',
+        body: JSON.stringify({ updates }),
+    });
+}
+export async function fetchAdminAuthStatus(endpoint) {
+    return requestJson(`${adminEndpoint(endpoint)}/api/system/auth/status`, { method: 'GET' });
+}
+export async function fetchAdminIpBlocks(endpoint) {
+    return requestJson(`${adminEndpoint(endpoint)}/api/system/auth/ip-blocks`, { method: 'GET' });
+}
+export async function unblockAdminIp(endpoint, payload) {
+    return requestJson(`${adminEndpoint(endpoint)}/api/system/auth/ip-blocks/unblock`, {
+        method: 'POST',
+        body: JSON.stringify(payload),
+    });
+}
+export function buildAdminEndpoint(host, port) {
+    return adminEndpoint(buildEndpoint(host, port));
+}

package/lib/platform.mjs

@@ -0,0 +1,50 @@
+// @ts-nocheck
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const PLATFORM_PACKAGES = {
+    'linux:x64': '@spencer-kit/coder-studio-linux-x64',
+    'darwin:arm64': '@spencer-kit/coder-studio-darwin-arm64',
+    'darwin:x64': '@spencer-kit/coder-studio-darwin-x64',
+    'win32:x64': '@spencer-kit/coder-studio-win32-x64'
+};
+export function resolvePlatformPackage(options = {}) {
+    const { env = process.env, platform = process.platform, arch = process.arch } = options;
+    const binaryName = platform === 'win32' ? 'coder-studio.exe' : 'coder-studio';
+    const binaryPath = env.CODER_STUDIO_BINARY_PATH ? path.resolve(env.CODER_STUDIO_BINARY_PATH) : '';
+    const distDir = env.CODER_STUDIO_DIST_DIR ? path.resolve(env.CODER_STUDIO_DIST_DIR) : '';
+    if (binaryPath) {
+        return {
+            packageName: 'override',
+            packageDir: path.dirname(binaryPath),
+            binaryPath,
+            distDir,
+            binaryName
+        };
+    }
+    const packageName = PLATFORM_PACKAGES[`${platform}:${arch}`];
+    if (!packageName) {
+        throw new Error(`Unsupported platform: ${platform}/${arch}`);
+    }
+    const packageJsonPath = require.resolve(`${packageName}/package.json`);
+    const packageDir = path.dirname(packageJsonPath);
+    return {
+        packageName,
+        packageDir,
+        binaryPath: path.join(packageDir, 'bin', binaryName),
+        distDir: path.join(packageDir, 'dist'),
+        binaryName
+    };
+}
+export function assertRuntimeBundle(bundle) {
+    if (!bundle.binaryPath || !fs.existsSync(bundle.binaryPath)) {
+        throw new Error(`Runtime binary not found: ${bundle.binaryPath || 'unknown'}`);
+    }
+    if (process.platform !== 'win32') {
+        fs.chmodSync(bundle.binaryPath, 0o755);
+    }
+    if (!bundle.distDir || !fs.existsSync(bundle.distDir)) {
+        throw new Error(`Frontend dist not found: ${bundle.distDir || 'unknown'}`);
+    }
+}

package/lib/process-utils.mjs

@@ -0,0 +1,76 @@
+// @ts-nocheck
+import fs from 'node:fs/promises';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function isPidRunning(pid) {
+    if (!pid || !Number.isInteger(pid))
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function terminateProcess(pid, { force = false } = {}) {
+    if (!pid)
+        return;
+    if (process.platform === 'win32') {
+        const args = ['/PID', String(pid), '/T'];
+        if (force)
+            args.push('/F');
+        await execFileAsync('taskkill', args);
+        return;
+    }
+    process.kill(pid, force ? 'SIGKILL' : 'SIGTERM');
+}
+export async function waitForProcessExit(pid, timeoutMs = 8000) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        if (!isPidRunning(pid)) {
+            return true;
+        }
+        await sleep(200);
+    }
+    return !isPidRunning(pid);
+}
+export function spawnBackground(command, args, options = {}) {
+    return spawn(command, args, {
+        ...options,
+        detached: true,
+        stdio: options.stdio ?? 'ignore',
+        windowsHide: true
+    });
+}
+export function spawnForeground(command, args, options = {}) {
+    return spawn(command, args, {
+        ...options,
+        stdio: options.stdio ?? 'inherit',
+        windowsHide: true
+    });
+}
+export async function openExternal(targetUrl, env = process.env) {
+    if (env.CODER_STUDIO_OPEN_COMMAND) {
+        const [command, ...extraArgs] = env.CODER_STUDIO_OPEN_COMMAND.split(' ');
+        await execFileAsync(command, [...extraArgs, targetUrl]);
+        return;
+    }
+    if (process.platform === 'darwin') {
+        await execFileAsync('open', [targetUrl]);
+        return;
+    }
+    if (process.platform === 'win32') {
+        await execFileAsync('cmd', ['/c', 'start', '', targetUrl]);
+        return;
+    }
+    await execFileAsync('xdg-open', [targetUrl]);
+}
+export async function ensureFile(pathname) {
+    const handle = await fs.open(pathname, 'a');
+    return handle;
+}

package/lib/runtime-controller.mjs

@@ -0,0 +1,350 @@
+// @ts-nocheck
+import { once } from 'node:events';
+import fs from 'node:fs/promises';
+import { buildEndpoint, DEFAULT_HOST, DEFAULT_LOG_TAIL_LINES, DEFAULT_PORT, resolveDataDir, resolveLogPath, resolveStateDir } from './config.mjs';
+import { fetchHealth, requestShutdown, waitForHealth } from './http.mjs';
+import { assertRuntimeBundle, resolvePlatformPackage } from './platform.mjs';
+import { ensureFile, isPidRunning, openExternal, spawnBackground, spawnForeground, terminateProcess, waitForProcessExit } from './process-utils.mjs';
+import { buildRuntimeState, clearRuntimeState, ensureStateDirs, readPackageVersion, readRuntimeState, readLogTail, writeRuntimeState } from './state.mjs';
+const DEFAULT_START_TIMEOUT_MS = 15000;
+function resolveStartTimeout(input, env) {
+    const candidate = input ?? env?.CODER_STUDIO_START_TIMEOUT_MS;
+    const timeout = Number(candidate);
+    return Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_START_TIMEOUT_MS;
+}
+function resolveOptions(input = {}) {
+    const stateDir = input.stateDir || resolveStateDir(input.env);
+    const env = input.env || process.env;
+    const host = input.host || DEFAULT_HOST;
+    const port = Number(input.port ?? DEFAULT_PORT);
+    const endpoint = input.endpoint || buildEndpoint(host, port);
+    const dataDir = input.dataDir || resolveDataDir(stateDir, env);
+    const logPath = input.logPath || resolveLogPath(stateDir);
+    const tailLines = Number(input.tailLines ?? DEFAULT_LOG_TAIL_LINES);
+    const timeoutMs = resolveStartTimeout(input.timeoutMs, env);
+    return {
+        ...input,
+        stateDir,
+        host,
+        port,
+        endpoint,
+        dataDir,
+        logPath,
+        timeoutMs,
+        tailLines: Number.isFinite(tailLines) && tailLines > 0 ? tailLines : DEFAULT_LOG_TAIL_LINES,
+        openCommand: input.openCommand || null,
+        env
+    };
+}
+async function probeManagedStatus(options) {
+    const runtime = await readRuntimeState(options.stateDir);
+    if (!runtime)
+        return null;
+    const endpoint = runtime.endpoint || options.endpoint;
+    const pid = Number(runtime.pid || 0);
+    const running = pid > 0 && isPidRunning(pid);
+    if (!running) {
+        await clearRuntimeState(options.stateDir);
+        return {
+            status: 'stopped',
+            managed: true,
+            stale: true,
+            endpoint,
+            pid,
+            runtime
+        };
+    }
+    try {
+        const health = await fetchHealth(endpoint);
+        return {
+            status: 'running',
+            managed: true,
+            stale: false,
+            endpoint,
+            pid,
+            runtime,
+            health
+        };
+    }
+    catch (error) {
+        return {
+            status: 'degraded',
+            managed: true,
+            stale: false,
+            endpoint,
+            pid,
+            runtime,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+export async function getStatus(input = {}) {
+    const options = resolveOptions(input);
+    const managed = await probeManagedStatus(options);
+    if (managed) {
+        return {
+            ...managed,
+            stateDir: options.stateDir,
+            logPath: managed.runtime?.logPath || options.logPath,
+            dataDir: options.dataDir
+        };
+    }
+    try {
+        const health = await fetchHealth(options.endpoint);
+        return {
+            status: 'running',
+            managed: false,
+            stale: false,
+            endpoint: options.endpoint,
+            pid: null,
+            runtime: null,
+            health,
+            stateDir: options.stateDir,
+            logPath: options.logPath,
+            dataDir: options.dataDir
+        };
+    }
+    catch (error) {
+        return {
+            status: 'stopped',
+            managed: false,
+            stale: false,
+            endpoint: options.endpoint,
+            pid: null,
+            runtime: null,
+            error: error instanceof Error ? error.message : String(error),
+            stateDir: options.stateDir,
+            logPath: options.logPath,
+            dataDir: options.dataDir
+        };
+    }
+}
+async function waitForReady(endpoint, pid, timeoutMs) {
+    const startedAt = Date.now();
+    let lastError = null;
+    while (Date.now() - startedAt < timeoutMs) {
+        if (pid && !isPidRunning(pid)) {
+            throw new Error('runtime_exited_early');
+        }
+        try {
+            return await waitForHealth(endpoint, { timeoutMs: 500, intervalMs: 200 });
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw lastError ?? new Error('health_timeout');
+}
+function buildChildEnv(options, bundle) {
+    return {
+        ...process.env,
+        ...options.env,
+        CODER_STUDIO_HOST: options.host,
+        CODER_STUDIO_PORT: String(options.port),
+        CODER_STUDIO_DATA_DIR: options.dataDir,
+        CODER_STUDIO_DIST_DIR: bundle.distDir
+    };
+}
+async function writeStateForPid(options, bundle, pid) {
+    const version = await readPackageVersion();
+    const state = buildRuntimeState({
+        version,
+        pid,
+        endpoint: options.endpoint,
+        binaryPath: bundle.binaryPath,
+        logPath: options.logPath
+    });
+    await writeRuntimeState(options.stateDir, state);
+    return state;
+}
+async function cleanupIfManagedPid(options, pid) {
+    const runtime = await readRuntimeState(options.stateDir);
+    if (runtime && Number(runtime.pid) === Number(pid)) {
+        await clearRuntimeState(options.stateDir);
+    }
+}
+export async function startRuntime(input = {}) {
+    const options = resolveOptions(input);
+    await ensureStateDirs(options.stateDir, options.dataDir);
+    const current = await getStatus(options);
+    if (current.status === 'running' || current.status === 'degraded') {
+        return {
+            changed: false,
+            ...current
+        };
+    }
+    const bundle = resolvePlatformPackage({ env: options.env });
+    assertRuntimeBundle(bundle);
+    const env = buildChildEnv(options, bundle);
+    if (options.foreground) {
+        const child = spawnForeground(bundle.binaryPath, [], {
+            cwd: options.stateDir,
+            env
+        });
+        if (!child.pid) {
+            throw new Error('runtime_pid_missing');
+        }
+        const exitPromise = once(child, 'exit').then(([code, signal]) => ({ code, signal }));
+        const errorPromise = once(child, 'error').then(([error]) => { throw error; });
+        await Promise.race([
+            waitForReady(options.endpoint, child.pid, options.timeoutMs),
+            exitPromise.then(() => {
+                throw new Error('runtime_exited_early');
+            }),
+            errorPromise
+        ]);
+        await writeStateForPid(options, bundle, child.pid);
+        if (typeof options.onReady === 'function') {
+            await options.onReady({ endpoint: options.endpoint, pid: child.pid, logPath: options.logPath });
+        }
+        const forward = (signal) => {
+            try {
+                child.kill(signal);
+            }
+            catch {
+                // Ignore when already stopped.
+            }
+        };
+        process.on('SIGINT', forward);
+        process.on('SIGTERM', forward);
+        try {
+            const { code, signal } = await Promise.race([exitPromise, errorPromise]);
+            await cleanupIfManagedPid(options, child.pid);
+            return {
+                changed: true,
+                status: code === 0 ? 'stopped' : 'failed',
+                endpoint: options.endpoint,
+                pid: child.pid,
+                exitCode: code,
+                signal
+            };
+        }
+        finally {
+            process.off('SIGINT', forward);
+            process.off('SIGTERM', forward);
+        }
+    }
+    const logHandle = await ensureFile(options.logPath);
+    const child = spawnBackground(bundle.binaryPath, [], {
+        cwd: options.stateDir,
+        env,
+        stdio: ['ignore', logHandle.fd, logHandle.fd]
+    });
+    if (!child.pid) {
+        await logHandle.close();
+        throw new Error('runtime_pid_missing');
+    }
+    child.unref();
+    await logHandle.close();
+    const exitPromise = once(child, 'exit').then(([code, signal]) => ({ code, signal }));
+    const errorPromise = once(child, 'error').then(([error]) => {
+        throw error;
+    });
+    try {
+        await Promise.race([
+            waitForReady(options.endpoint, child.pid, options.timeoutMs),
+            exitPromise.then(() => {
+                throw new Error('runtime_exited_early');
+            }),
+            errorPromise
+        ]);
+        await writeStateForPid(options, bundle, child.pid);
+        return {
+            changed: true,
+            status: 'running',
+            endpoint: options.endpoint,
+            pid: child.pid,
+            logPath: options.logPath,
+            stateDir: options.stateDir,
+            dataDir: options.dataDir
+        };
+    }
+    catch (error) {
+        await Promise.allSettled([
+            terminateProcess(child.pid, { force: false }),
+            clearRuntimeState(options.stateDir)
+        ]);
+        throw error;
+    }
+}
+export async function stopRuntime(input = {}) {
+    const options = resolveOptions(input);
+    const status = await getStatus(options);
+    if (status.status === 'stopped') {
+        return {
+            changed: false,
+            ...status
+        };
+    }
+    let shutdownError = null;
+    try {
+        await requestShutdown(status.endpoint);
+    }
+    catch (error) {
+        shutdownError = error instanceof Error ? error.message : String(error);
+    }
+    if (status.pid) {
+        const gracefulExit = await waitForProcessExit(status.pid, 8000);
+        if (!gracefulExit) {
+            try {
+                await terminateProcess(status.pid, { force: false });
+            }
+            catch {
+                // Ignore fallback kill failure here and try force next.
+            }
+            const terminated = await waitForProcessExit(status.pid, 4000);
+            if (!terminated) {
+                await terminateProcess(status.pid, { force: true });
+                await waitForProcessExit(status.pid, 2000);
+            }
+        }
+    }
+    await clearRuntimeState(options.stateDir);
+    return {
+        changed: true,
+        status: 'stopped',
+        endpoint: status.endpoint,
+        pid: status.pid,
+        shutdownError
+    };
+}
+export async function restartRuntime(input = {}) {
+    await stopRuntime(input);
+    return startRuntime(input);
+}
+export async function openRuntime(input = {}) {
+    const options = resolveOptions(input);
+    const status = await getStatus(options);
+    const running = status.status === 'running' || status.status === 'degraded';
+    const active = running ? status : await startRuntime(options);
+    const openEnv = options.openCommand ? { ...options.env, CODER_STUDIO_OPEN_COMMAND: options.openCommand } : options.env;
+    await openExternal(active.endpoint, openEnv);
+    return active;
+}
+export async function readRuntimeLogs(input = {}) {
+    const options = resolveOptions(input);
+    return readLogTail(options.logPath, input.lines ?? options.tailLines ?? DEFAULT_LOG_TAIL_LINES);
+}
+export async function doctorRuntime(input = {}) {
+    const options = resolveOptions(input);
+    const bundle = (() => {
+        try {
+            return resolvePlatformPackage({ env: options.env });
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : String(error) };
+        }
+    })();
+    const status = await getStatus(options);
+    const logExists = await fs.stat(options.logPath).then(() => true).catch(() => false);
+    const runtime = await readRuntimeState(options.stateDir);
+    return {
+        status,
+        bundle,
+        stateDir: options.stateDir,
+        dataDir: options.dataDir,
+        logPath: options.logPath,
+        logExists,
+        runtime
+    };
+}

package/lib/state.mjs

@@ -0,0 +1,75 @@
+// @ts-nocheck
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveLogPath, resolvePidPath, resolveRuntimePath } from './config.mjs';
+const PACKAGE_JSON_PATH = fileURLToPath(new URL('../package.json', import.meta.url));
+export async function readPackageVersion() {
+    const raw = await fs.readFile(PACKAGE_JSON_PATH, 'utf8');
+    return JSON.parse(raw).version;
+}
+export async function ensureStateDirs(stateDir, dataDir) {
+    await fs.mkdir(stateDir, { recursive: true });
+    await fs.mkdir(dataDir, { recursive: true });
+}
+export async function readRuntimeState(stateDir) {
+    try {
+        const raw = await fs.readFile(resolveRuntimePath(stateDir), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeRuntimeState(stateDir, state) {
+    const runtimePath = resolveRuntimePath(stateDir);
+    const pidPath = resolvePidPath(stateDir);
+    await fs.writeFile(runtimePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+    await fs.writeFile(pidPath, `${state.pid}\n`, 'utf8');
+}
+export async function clearRuntimeState(stateDir) {
+    await Promise.allSettled([
+        fs.rm(resolveRuntimePath(stateDir), { force: true }),
+        fs.rm(resolvePidPath(stateDir), { force: true })
+    ]);
+}
+export function buildRuntimeState({ version, pid, endpoint, binaryPath, logPath }) {
+    return {
+        version,
+        pid,
+        endpoint,
+        binaryPath,
+        logPath,
+        startedAt: new Date().toISOString()
+    };
+}
+export async function readLogTail(logPath, lineCount = 80) {
+    try {
+        const raw = await fs.readFile(logPath, 'utf8');
+        return raw.trimEnd().split(/\r?\n/).slice(-lineCount).join('\n');
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return '';
+        }
+        throw error;
+    }
+}
+export async function statIfExists(filePath) {
+    try {
+        return await fs.stat(filePath);
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+export function resolvePackageRoot() {
+    return path.dirname(PACKAGE_JSON_PATH);
+}
+export { resolveLogPath, resolvePidPath, resolveRuntimePath };