kandev 0.65.0 → 0.67.0

package/dist/ports.js

@@ -1,142 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.__testing = void 0;
-exports.ensureValidPort = ensureValidPort;
-exports.pickAvailablePort = pickAvailablePort;
-exports.pickAndReservePort = pickAndReservePort;
-const node_crypto_1 = __importDefault(require("node:crypto"));
-const node_net_1 = __importDefault(require("node:net"));
-const constants_1 = require("./constants");
-const CONNECT_PROBE_TIMEOUT_MS = 500;
-function ensureValidPort(port, name) {
-    if (port === undefined) {
-        return undefined;
-    }
-    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-        throw new Error(`${name} must be an integer between 1 and 65535`);
-    }
-    return port;
-}
-/**
- * Tries to connect to a port on the given host. Returns true if something
- * is already listening (i.e. the port is in use). Returns false on connection
- * refused, on any other socket error, or when the probe takes longer than
- * `timeoutMs` — under WSL2 mirrored networking the kernel can silently drop
- * the SYN to an unbound loopback port, so an unbounded connect would hang
- * forever and deadlock isPortAvailable.
- *
- * Used alongside canBindPort because it detects ports where a listener is
- * bound with SO_REUSEADDR (Node's default on macOS), which a bind-only check
- * would miss.
- */
-function isPortInUse(port, host, timeoutMs = CONNECT_PROBE_TIMEOUT_MS) {
-    return new Promise((resolve) => {
-        const socket = node_net_1.default.createConnection({ port, host });
-        let settled = false;
-        const done = (v) => {
-            if (settled)
-                return;
-            settled = true;
-            socket.destroy();
-            resolve(v);
-        };
-        socket.once("connect", () => done(true));
-        socket.once("error", () => done(false));
-        setTimeout(() => done(false), timeoutMs).unref();
-    });
-}
-/**
- * Tries to bind a port on the given host. Returns true if the bind succeeds
- * (port is free). Closes immediately on success.
- *
- * This catches Windows "phantom" port reservations: Hyper-V/WSL silently
- * reserve random port ranges at boot that don't appear in netstat or via a
- * connect probe (nothing is listening, so connect-check thinks the port is
- * free) — but bind fails with "Only one usage of each socket address". A
- * connect-only check causes kandev's backend to choose a reserved port and
- * then die when it tries to actually listen on it.
- */
-function canBindPort(port, host) {
-    return new Promise((resolve) => {
-        const server = node_net_1.default.createServer();
-        server.once("error", () => resolve(false));
-        server.listen(port, host, () => {
-            server.close(() => resolve(true));
-        });
-    });
-}
-/**
- * Checks if a port is available by probing both IPv4 and IPv6 loopback.
- *
- * Uses BOTH a connect check and a bind check:
- *   - connect: detects ports where a listener is bound with SO_REUSEADDR
- *     (Node's default on macOS — bind-only check would falsely succeed)
- *   - bind:    detects Windows phantom reservations (Hyper-V/WSL) and
- *     ports in TIME_WAIT that connect-only check misses
- *
- * The port is available IFF nobody answers a connect AND a fresh bind
- * succeeds — covers macOS, Linux, and Windows.
- */
-async function isPortAvailable(port) {
-    // Run connect probes first, then the bind probe — they cannot share the
-    // port concurrently. On loopback, server.listen() completes in the kernel
-    // before a connect SYN to the same address is processed, so a concurrent
-    // canBindPort+isPortInUse pair can answer each other and report a free
-    // port as occupied. Sequencing keeps the bind probe's temporary listener
-    // out of the connect probes' view.
-    const [v4InUse, v6InUse] = await Promise.all([
-        isPortInUse(port, "127.0.0.1"),
-        isPortInUse(port, "::1"),
-    ]);
-    if (v4InUse || v6InUse)
-        return false;
-    return canBindPort(port, "127.0.0.1");
-}
-async function reserveSpecificPort(port, host = "127.0.0.1") {
-    return new Promise((resolve) => {
-        const server = node_net_1.default.createServer();
-        server.on("error", () => resolve(null));
-        server.listen(port, host, () => resolve(server));
-    });
-}
-async function pickAvailablePort(preferred, retries = constants_1.RANDOM_PORT_RETRIES) {
-    if (await isPortAvailable(preferred)) {
-        return preferred;
-    }
-    for (let i = 0; i < retries; i += 1) {
-        const candidate = node_crypto_1.default.randomInt(constants_1.RANDOM_PORT_MIN, constants_1.RANDOM_PORT_MAX + 1);
-        if (await isPortAvailable(candidate)) {
-            return candidate;
-        }
-    }
-    throw new Error(`Unable to find a free port after ${retries + 1} attempts`);
-}
-async function pickAndReservePort(preferred, retries = constants_1.RANDOM_PORT_RETRIES) {
-    if (await isPortAvailable(preferred)) {
-        const reservedPreferred = await reserveSpecificPort(preferred);
-        if (reservedPreferred) {
-            return {
-                port: preferred,
-                release: () => new Promise((resolve) => reservedPreferred.close(() => resolve())),
-            };
-        }
-    }
-    for (let i = 0; i < retries; i += 1) {
-        const candidate = node_crypto_1.default.randomInt(constants_1.RANDOM_PORT_MIN, constants_1.RANDOM_PORT_MAX + 1);
-        if (!(await isPortAvailable(candidate)))
-            continue;
-        const reserved = await reserveSpecificPort(candidate);
-        if (reserved) {
-            return {
-                port: candidate,
-                release: () => new Promise((resolve) => reserved.close(() => resolve())),
-            };
-        }
-    }
-    throw new Error(`Unable to reserve a free port after ${retries + 1} attempts`);
-}
-// Exported for tests only.
-exports.__testing = { isPortInUse, isPortAvailable };

package/dist/process.js

@@ -1,122 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createProcessSupervisor = createProcessSupervisor;
-exports.ignoreBrokenPipe = ignoreBrokenPipe;
-exports.__resetBrokenPipeGuard = __resetBrokenPipeGuard;
-const tree_kill_1 = __importDefault(require("tree-kill"));
-const SHUTDOWN_TIMEOUT_MS = 10000;
-function createProcessSupervisor() {
-    let shutdownPromise = null;
-    const children = [];
-    const shutdown = async (reason) => {
-        // If already shutting down, wait for the existing shutdown to complete
-        if (shutdownPromise) {
-            return shutdownPromise;
-        }
-        console.log(`[kandev] shutting down (${reason})...`);
-        // Wait for all child processes to actually exit, not just for signal to be sent
-        shutdownPromise = Promise.all(children
-            .filter((child) => child.pid)
-            .map((child) => waitForProcessExit(child, SHUTDOWN_TIMEOUT_MS))).then(() => { });
-        return shutdownPromise;
-    };
-    const onSignal = (signal) => {
-        void shutdown(`signal ${signal}`).then(() => process.exit(0));
-    };
-    const attachSignalHandlers = () => {
-        // Ctrl-C sends SIGINT to the whole process group, so the parent (make/shell)
-        // exits and closes the pipe our stdout/stderr write to. Any console.log during
-        // shutdown then triggers an EPIPE 'error' event with no listener, which Node
-        // treats as fatal and crashes us before children are gracefully terminated.
-        // Swallow EPIPE so shutdown can finish.
-        ignoreBrokenPipe();
-        process.on("SIGINT", onSignal);
-        // SIGTERM is not available on Windows — only attach where supported
-        if (process.platform !== "win32") {
-            process.on("SIGTERM", onSignal);
-        }
-    };
-    return { children, shutdown, attachSignalHandlers };
-}
-let brokenPipeGuarded = false;
-/**
- * Install error handlers on stdout/stderr that swallow EPIPE (broken pipe).
- * Idempotent: only attaches once per process.
- */
-function ignoreBrokenPipe() {
-    if (brokenPipeGuarded)
-        return;
-    brokenPipeGuarded = true;
-    const onPipeError = (err) => {
-        if (err.code === "EPIPE")
-            return;
-        throw err;
-    };
-    process.stdout.on("error", onPipeError);
-    process.stderr.on("error", onPipeError);
-}
-/**
- * Test-only: resets the broken-pipe guard so a later `ignoreBrokenPipe()` call
- * reattaches listeners. Keeps the module guard consistent with suites that
- * remove the listeners they installed.
- */
-function __resetBrokenPipeGuard() {
-    brokenPipeGuarded = false;
-}
-/**
- * Terminate a process and wait for it to exit.
- * On Unix: sends SIGTERM, falls back to SIGKILL after timeout.
- * On Windows: tree-kill uses taskkill (no SIGTERM/SIGKILL distinction).
- */
-function waitForProcessExit(child, timeoutMs) {
-    const isWindows = process.platform === "win32";
-    return new Promise((resolve) => {
-        const pid = child.pid;
-        // Check if this is a ChildProcess with exit event support
-        const proc = child;
-        const hasExitEvent = typeof proc.on === "function" && typeof proc.exitCode !== "undefined";
-        // If process already exited, resolve immediately
-        if (hasExitEvent && proc.exitCode !== null) {
-            resolve();
-            return;
-        }
-        let resolved = false;
-        const done = () => {
-            if (resolved)
-                return;
-            resolved = true;
-            resolve();
-        };
-        // Set up timeout for force-kill fallback
-        const timeout = setTimeout(() => {
-            console.log(`[kandev] process ${pid} did not exit in time, force killing`);
-            // On Windows, tree-kill always force-kills (no signal distinction)
-            // On Unix, escalate to SIGKILL
-            (0, tree_kill_1.default)(pid, isWindows ? undefined : "SIGKILL", done);
-        }, timeoutMs);
-        // Listen for exit event if available
-        if (hasExitEvent) {
-            proc.once("exit", () => {
-                clearTimeout(timeout);
-                done();
-            });
-        }
-        // Graceful termination: SIGTERM on Unix, default kill on Windows
-        (0, tree_kill_1.default)(pid, isWindows ? undefined : "SIGTERM", (err) => {
-            // If kill fails (process already gone), we're done
-            if (err) {
-                clearTimeout(timeout);
-                done();
-            }
-            // If no exit event support, resolve after a brief delay
-            // (tree-kill callback fires when signal sent, not when process exits)
-            if (!hasExitEvent) {
-                // For non-ChildProcess objects, we can't wait for exit event
-                // Just wait for the timeout
-            }
-        });
-    });
-}

package/dist/run.js

@@ -1,283 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.findCachedRelease = findCachedRelease;
-exports.cleanOldReleases = cleanOldReleases;
-exports.attachRingBuffer = attachRingBuffer;
-exports.runRelease = runRelease;
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-const bundle_1 = require("./bundle");
-const constants_1 = require("./constants");
-const github_1 = require("./github");
-const health_1 = require("./health");
-const platform_1 = require("./platform");
-const version_1 = require("./version");
-const ports_1 = require("./ports");
-const process_1 = require("./process");
-const runtime_1 = require("./runtime");
-const shared_1 = require("./shared");
-const backend_1 = require("./supervisor/backend");
-const web_1 = require("./web");
-/**
- * Find a cached release binary to use when GitHub is unreachable.
- * If version is specified, checks that exact tag. Otherwise, picks
- * the highest semver tag available in the cache.
- */
-function findCachedRelease(platformDir, version) {
-    const rootCacheDir = (0, constants_1.resolveCacheDir)();
-    if (version) {
-        const cacheDir = node_path_1.default.join(rootCacheDir, version, platformDir);
-        const bundleDir = node_path_1.default.join(cacheDir, "kandev");
-        const backendBin = node_path_1.default.join(bundleDir, "bin", (0, platform_1.getBinaryName)("kandev"));
-        if (node_fs_1.default.existsSync(backendBin)) {
-            return { cacheDir, tag: version };
-        }
-        return null;
-    }
-    // No version specified — scan for cached tags and pick the latest.
-    if (!node_fs_1.default.existsSync(rootCacheDir))
-        return null;
-    const entries = node_fs_1.default.readdirSync(rootCacheDir).filter((d) => d.startsWith("v"));
-    if (entries.length === 0)
-        return null;
-    const sorted = (0, version_1.sortVersionsDesc)(entries);
-    for (const tag of sorted) {
-        const cacheDir = node_path_1.default.join(rootCacheDir, tag, platformDir);
-        const bundleDir = node_path_1.default.join(cacheDir, "kandev");
-        const backendBin = node_path_1.default.join(bundleDir, "bin", (0, platform_1.getBinaryName)("kandev"));
-        if (node_fs_1.default.existsSync(backendBin)) {
-            return { cacheDir, tag };
-        }
-    }
-    return null;
-}
-/**
- * Remove old cached releases, keeping only the 2 most recent tags.
- * Runs after a successful download so we don't accumulate stale versions.
- * The previous version is kept as a fallback for offline use.
- */
-function cleanOldReleases(currentTag) {
-    const rootCacheDir = (0, constants_1.resolveCacheDir)();
-    try {
-        if (!node_fs_1.default.existsSync(rootCacheDir))
-            return;
-        const entries = node_fs_1.default.readdirSync(rootCacheDir).filter((d) => d.startsWith("v"));
-        if (entries.length <= 2)
-            return;
-        const sorted = (0, version_1.sortVersionsDesc)(entries);
-        // Always keep currentTag + the next most recent.
-        const keep = new Set([currentTag, sorted[0], sorted[1]]);
-        for (const entry of entries) {
-            if (!keep.has(entry)) {
-                node_fs_1.default.rmSync(node_path_1.default.join(rootCacheDir, entry), { recursive: true, force: true });
-            }
-        }
-    }
-    catch {
-        // Non-critical — don't fail the launch if cleanup errors.
-    }
-}
-/**
- * Download a specific release version into the local cache.
- * Only used when --runtime-version is given explicitly.
- */
-async function downloadRuntimeVersion(runtimeVersion) {
-    const platformDir = (0, platform_1.getPlatformDir)();
-    const release = await (0, github_1.getRelease)(runtimeVersion);
-    const tag = release.tag_name;
-    const assetName = `kandev-${platformDir}.tar.gz`;
-    const cacheDir = node_path_1.default.join((0, constants_1.resolveCacheDir)(), tag, platformDir);
-    const archivePath = await (0, github_1.ensureAsset)(tag, assetName, cacheDir, (downloaded, total) => {
-        const percent = total ? Math.round((downloaded / total) * 100) : 0;
-        const mb = (downloaded / (1024 * 1024)).toFixed(1);
-        const totalMb = total ? (total / (1024 * 1024)).toFixed(1) : "?";
-        process.stderr.write(`\r   Downloading: ${mb}MB / ${totalMb}MB (${percent}%)`);
-    });
-    process.stderr.write("\n");
-    (0, bundle_1.ensureExtracted)(archivePath, cacheDir);
-    cleanOldReleases(tag);
-    return tag;
-}
-async function prepareBundleForLaunch({ runtimeVersion, backendPort, webPort, verbose = false, debug = false, }) {
-    let bundleDir;
-    let releaseTag;
-    if (runtimeVersion) {
-        // Explicit version: ensure it is in the cache (downloading if needed), then resolve.
-        const platformDir = (0, platform_1.getPlatformDir)();
-        const cached = findCachedRelease(platformDir, runtimeVersion);
-        let tag;
-        if (cached) {
-            tag = cached.tag;
-            bundleDir = (0, bundle_1.findBundleRoot)(cached.cacheDir);
-        }
-        else {
-            try {
-                tag = await downloadRuntimeVersion(runtimeVersion);
-                const cacheDir = node_path_1.default.join((0, constants_1.resolveCacheDir)(), tag, platformDir);
-                bundleDir = (0, bundle_1.findBundleRoot)(cacheDir);
-            }
-            catch (err) {
-                const reason = err instanceof Error ? err.message : String(err);
-                throw new Error(`Failed to fetch runtime version ${runtimeVersion}.\n` +
-                    `  Reason: ${reason}\n` +
-                    `  Run kandev once while online to cache a release for offline use.`);
-            }
-        }
-        // Validate the resolved bundle has all required binaries before launching.
-        (0, runtime_1.validateBundle)(bundleDir);
-        releaseTag = tag;
-    }
-    else {
-        // Default path: resolve from KANDEV_BUNDLE_DIR or installed npm runtime package.
-        const resolved = (0, runtime_1.resolveRuntime)();
-        bundleDir = resolved.bundleDir;
-        // Use KANDEV_VERSION if set (e.g. by Homebrew wrapper), otherwise show source.
-        releaseTag = process.env.KANDEV_VERSION ?? `(${resolved.source})`;
-    }
-    const actualBackendPort = backendPort ?? (await (0, ports_1.pickAvailablePort)(constants_1.DEFAULT_BACKEND_PORT));
-    const actualWebPort = webPort ?? (await (0, ports_1.pickAvailablePort)(constants_1.DEFAULT_WEB_PORT));
-    const agentctlPort = await (0, ports_1.pickAvailablePort)(constants_1.DEFAULT_AGENTCTL_PORT);
-    const backendUrl = `http://localhost:${actualBackendPort}`;
-    const showOutput = verbose || debug;
-    const logLevel = process.env.KANDEV_LOG_LEVEL?.trim() || (debug ? "debug" : verbose ? "info" : "warn");
-    const dataDir = (0, constants_1.resolveDataDir)();
-    node_fs_1.default.mkdirSync(dataDir, { recursive: true });
-    const dbPath = (0, constants_1.resolveDatabasePath)();
-    const backendBin = node_path_1.default.join(bundleDir, "bin", (0, platform_1.getBinaryName)("kandev"));
-    const backendEnv = (0, shared_1.buildBackendEnv)({
-        ports: {
-            backendPort: actualBackendPort,
-            webPort: actualWebPort,
-            agentctlPort,
-            backendUrl,
-        },
-        logLevel,
-        extra: {
-            KANDEV_DATABASE_PATH: dbPath,
-            ...(debug ? { KANDEV_DEBUG_AGENT_MESSAGES: "true", KANDEV_DEBUG_PPROF_ENABLED: "true" } : {}),
-        },
-    });
-    const webEnv = (0, shared_1.buildWebEnv)({
-        ports: {
-            backendPort: actualBackendPort,
-            webPort: actualWebPort,
-            agentctlPort,
-            backendUrl,
-        },
-        production: true,
-        debug,
-    });
-    return {
-        bundleDir,
-        backendBin,
-        backendUrl,
-        backendEnv,
-        webEnv,
-        releaseTag,
-        webPort: actualWebPort,
-        agentctlPort,
-        dbPath,
-        logLevel,
-        showOutput,
-    };
-}
-/**
- * Attach a ring buffer to a readable stream, keeping roughly the last `maxChars`
- * characters. Note: the limit is measured in JS string length (UTF-16 code units),
- * not bytes — fine for log output which is overwhelmingly ASCII.
- */
-function attachRingBuffer(stream, maxChars = 64 * 1024) {
-    let buf = "";
-    stream?.on("data", (chunk) => {
-        buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");
-        if (buf.length > maxChars) {
-            buf = buf.slice(buf.length - maxChars);
-        }
-    });
-    return () => buf;
-}
-async function launchBundle(prepared) {
-    (0, shared_1.logStartupInfo)({
-        header: `release: ${prepared.releaseTag}`,
-        ports: {
-            backendPort: Number(prepared.backendEnv.KANDEV_SERVER_PORT),
-            webPort: prepared.webPort,
-            agentctlPort: prepared.agentctlPort,
-            backendUrl: prepared.backendUrl,
-        },
-        dbPath: prepared.dbPath,
-        logLevel: prepared.logLevel,
-    });
-    const supervisor = (0, process_1.createProcessSupervisor)();
-    supervisor.attachSignalHandlers();
-    const backend = await (0, backend_1.launchRestartableBackend)({
-        command: prepared.backendBin,
-        args: [],
-        cwd: node_path_1.default.dirname(prepared.backendBin),
-        env: prepared.backendEnv,
-        homeDir: (0, constants_1.resolveKandevHomeDir)(),
-        ports: {
-            backendPort: Number(prepared.backendEnv.KANDEV_SERVER_PORT),
-            webPort: prepared.webPort,
-            agentctlPort: prepared.agentctlPort,
-            backendUrl: prepared.backendUrl,
-        },
-        mode: "run",
-        stdio: prepared.showOutput ? ["ignore", "inherit", "inherit"] : ["ignore", "pipe", "inherit"],
-        supervisor,
-    });
-    const backendProc = backend.proc;
-    const readBuffered = prepared.showOutput ? () => "" : attachRingBuffer(backendProc.stdout);
-    let dumped = false;
-    const dumpBackendLogs = () => {
-        if (dumped)
-            return;
-        dumped = true;
-        const buffered = readBuffered();
-        if (buffered.trim().length === 0)
-            return;
-        console.error("[kandev] --- backend stdout (last captured output) ---");
-        console.error(buffered.trimEnd());
-        console.error("[kandev] --- end backend stdout ---");
-    };
-    const webServerPath = (0, bundle_1.resolveWebServerPath)(prepared.bundleDir);
-    if (!webServerPath) {
-        throw new Error("Web server entry (server.js) not found in bundle");
-    }
-    return { supervisor, backendProc, webServerPath, dumpBackendLogs };
-}
-async function runRelease({ runtimeVersion, backendPort, webPort, verbose = false, debug = false, headless = false, }) {
-    const prepared = await prepareBundleForLaunch({
-        runtimeVersion,
-        backendPort,
-        webPort,
-        verbose,
-        debug,
-    });
-    const { supervisor, backendProc, webServerPath, dumpBackendLogs } = await launchBundle(prepared);
-    const healthTimeoutMs = (0, health_1.resolveHealthTimeoutMs)(constants_1.HEALTH_TIMEOUT_MS_RELEASE);
-    console.log("[kandev] starting backend...");
-    await (0, health_1.waitForHealth)(prepared.backendUrl, backendProc, healthTimeoutMs, dumpBackendLogs);
-    console.log(`[kandev] backend ready at ${prepared.backendUrl}`);
-    const webUrl = `http://localhost:${prepared.webPort}`;
-    console.log("[kandev] starting web...");
-    const webProc = (0, web_1.launchWebApp)({
-        command: "node",
-        args: [webServerPath],
-        cwd: node_path_1.default.dirname(webServerPath),
-        env: prepared.webEnv,
-        supervisor,
-        label: "web",
-        quiet: !prepared.showOutput,
-    });
-    await (0, health_1.waitForUrlReady)(webUrl, webProc, healthTimeoutMs);
-    if (headless) {
-        console.log(`[kandev] ready (headless) at ${prepared.backendUrl}`);
-        return;
-    }
-    console.log("[kandev] open: " + prepared.backendUrl);
-    (0, web_1.openBrowser)(prepared.backendUrl);
-}

package/dist/runtime.js

@@ -1,76 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveRuntime = resolveRuntime;
-exports.validateBundle = validateBundle;
-const node_path_1 = __importDefault(require("node:path"));
-const node_fs_1 = __importDefault(require("node:fs"));
-const bundle_1 = require("./bundle");
-const platform_1 = require("./platform");
-const PLATFORM_TO_NPM_PACKAGE = {
-    "linux-x64": "@kdlbs/runtime-linux-x64",
-    "linux-arm64": "@kdlbs/runtime-linux-arm64",
-    "macos-x64": "@kdlbs/runtime-darwin-x64",
-    "macos-arm64": "@kdlbs/runtime-darwin-arm64",
-    "windows-x64": "@kdlbs/runtime-win32-x64",
-};
-/**
- * Resolve the runtime bundle directory using a two-step priority chain:
- *
- * 1. KANDEV_BUNDLE_DIR env var — set by the Homebrew formula wrapper and
- *    useful for local testing. Skips all other resolution.
- * 2. Installed npm runtime package — looks for @kdlbs/runtime-{platform}
- *    in node_modules via Node module resolution. Works after
- *    `npx kandev@latest` or `npm install -g kandev` (requires npm 7+).
- *
- * The explicit `--runtime-version <tag>` download path is handled directly
- * in run.ts (which manages the GitHub download + cache itself); it does
- * not flow through this function.
- *
- * Throws with an actionable error message if no runtime is found.
- */
-function resolveRuntime() {
-    const envBundleDir = process.env.KANDEV_BUNDLE_DIR;
-    if (envBundleDir) {
-        validateBundle(envBundleDir);
-        return { bundleDir: envBundleDir, source: "env" };
-    }
-    const platformDir = (0, platform_1.getPlatformDir)();
-    const packageName = PLATFORM_TO_NPM_PACKAGE[platformDir];
-    let pkgJsonPath = null;
-    try {
-        pkgJsonPath = require.resolve(`${packageName}/package.json`);
-    }
-    catch {
-        // MODULE_NOT_FOUND — npm runtime package is not installed. Fall through
-        // to the actionable error below.
-    }
-    if (pkgJsonPath) {
-        // The package IS installed. If validateBundle throws here, the bundle is
-        // present but corrupt — surface the error rather than the generic
-        // "no runtime found" message below.
-        const packageRoot = node_path_1.default.dirname(pkgJsonPath);
-        validateBundle(packageRoot);
-        return { bundleDir: packageRoot, source: "npm" };
-    }
-    throw new Error(`No Kandev runtime found for ${platformDir}.\n` +
-        `  Install via npm (requires npm 7+): npx kandev@latest\n` +
-        `  Install via Homebrew: brew install kdlbs/kandev/kandev\n` +
-        `  Download a specific version (debug): kandev --runtime-version <tag>`);
-}
-function validateBundle(bundleDir) {
-    const backendBin = node_path_1.default.join(bundleDir, "bin", (0, platform_1.getBinaryName)("kandev"));
-    if (!node_fs_1.default.existsSync(backendBin)) {
-        throw new Error(`Backend binary not found in bundle at ${bundleDir}`);
-    }
-    const agentctlBin = node_path_1.default.join(bundleDir, "bin", (0, platform_1.getBinaryName)("agentctl"));
-    if (!node_fs_1.default.existsSync(agentctlBin)) {
-        throw new Error(`agentctl binary not found in bundle at ${bundleDir}`);
-    }
-    const webServerPath = (0, bundle_1.resolveWebServerPath)(bundleDir);
-    if (!webServerPath) {
-        throw new Error(`Web server (server.js) not found in bundle at ${bundleDir}`);
-    }
-}