kandev 0.1.3

package/README.md

@@ -0,0 +1,77 @@
+# Kandev Launcher (npx)
+
+This package powers `npx kandev` by downloading prebuilt release bundles from GitHub Releases and running them locally. It:
+- Detects OS/arch and fetches the matching bundle ZIP.
+- Verifies the SHA256 checksum when available.
+- Extracts the bundle into `~/.kandev/bin/<version>/<platform>/`.
+- Starts the backend binary and waits for the `/health` endpoint.
+- Starts the Next.js standalone server with runtime `KANDEV_API_BASE_URL`.
+- Uses the latest GitHub Release by default, so runtime bundles update automatically.
+It also supports local dev runs from a repo checkout.
+
+## Updates
+
+On `run`, the launcher checks npm for the latest `kandev` CLI version and prompts:
+
+```
+Update available: <current> -> <latest>. Update now? [y/N]
+```
+
+If you accept, it re-runs `npx kandev@latest` with the same arguments.
+This check is skipped in `dev` mode.
+
+Note: the runtime bundles are pulled from the latest GitHub Release by default, even if the CLI version is unchanged. So:
+- **New runtime release without CLI publish**: users get new runtime automatically, but no update prompt.
+- **New CLI publish**: users get an update prompt and then re-run with the new CLI.
+
+You can disable the prompt with:
+
+```bash
+KANDEV_NO_UPDATE_PROMPT=1 npx kandev
+```
+
+## Usage
+
+```bash
+# Run the latest release bundle
+npx kandev
+
+# Run a specific release tag
+npx kandev run --version v0.1.0
+
+# Local dev (from repo root)
+npx kandev dev
+
+
+# Local test the built CLI (from repo root)
+pnpm -C apps/cli build
+pnpm -C apps/cli start
+```
+
+## Local Development
+
+```bash
+pnpm -C apps/cli dev
+```
+
+## Build / Publish
+
+```bash
+pnpm -C apps/cli build
+npm publish --access public
+```
+
+The published package name is `kandev`, with a bin entry `kandev`.
+
+## Release
+
+```bash
+scripts/release/publish-launcher.sh 0.1.0
+```
+
+## Environment Overrides
+
+- `KANDEV_GITHUB_OWNER`, `KANDEV_GITHUB_REPO`: Override the GitHub repo to fetch releases from.
+- `KANDEV_GITHUB_TOKEN`: Optional token for GitHub API rate limits.
+- `KANDEV_NO_UPDATE_PROMPT=1`: Disable the update prompt.
+- `KANDEV_SKIP_UPDATE=1`: Internal guard to avoid update loops.

package/bin/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require("../dist/cli.js");

package/dist/bundle.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractZip = extractZip;
+exports.ensureExtracted = ensureExtracted;
+exports.findBundleRoot = findBundleRoot;
+exports.resolveWebServerPath = resolveWebServerPath;
+const adm_zip_1 = __importDefault(require("adm-zip"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function extractZip(zipPath, destDir) {
+    const zip = new adm_zip_1.default(zipPath);
+    zip.extractAllTo(destDir, true);
+}
+function ensureExtracted(zipPath, destDir) {
+    const marker = node_path_1.default.join(destDir, ".extracted");
+    if (node_fs_1.default.existsSync(marker)) {
+        return;
+    }
+    extractZip(zipPath, destDir);
+    node_fs_1.default.writeFileSync(marker, "");
+}
+function findBundleRoot(cacheDir) {
+    const candidate = node_path_1.default.join(cacheDir, "kandev");
+    if (node_fs_1.default.existsSync(candidate)) {
+        return candidate;
+    }
+    return cacheDir;
+}
+function resolveWebServerPath(bundleDir) {
+    const direct = node_path_1.default.join(bundleDir, "web", "server.js");
+    if (node_fs_1.default.existsSync(direct)) {
+        return direct;
+    }
+    const nested = node_path_1.default.join(bundleDir, "web", "apps", "web", "server.js");
+    if (node_fs_1.default.existsSync(nested)) {
+        return nested;
+    }
+    return null;
+}

package/dist/cli.js

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const package_json_1 = __importDefault(require("../package.json"));
+const dev_1 = require("./dev");
+const run_1 = require("./run");
+const ports_1 = require("./ports");
+const update_1 = require("./update");
+function printHelp() {
+    console.log(`kandev launcher
+
+Usage:
+  kandev run [--version <tag>] [--backend-port <port>] [--web-port <port>]
+  kandev dev [--backend-port <port>] [--web-port <port>]
+  kandev [--version <tag>] [--backend-port <port>] [--web-port <port>]
+  kandev --dev [--backend-port <port>] [--web-port <port>]
+
+Examples:
+  kandev
+  kandev run
+  kandev --dev
+  kandev dev
+  kandev --version v0.1.0
+  kandev --backend-port 18080 --web-port 13000
+
+Options:
+  dev             Use local repo for dev (make dev + next dev) if available.
+  run             Use release bundles (default).
+  --dev            Alias for "dev".
+  --version        Release tag to install (default: latest).
+  --backend-port   Override backend port.
+  --web-port       Override web port.
+  --help, -h       Show help.
+`);
+}
+function parseArgs(argv) {
+    const opts = { command: "run" };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        if (arg === "dev" || arg === "run") {
+            opts.command = arg;
+            continue;
+        }
+        if (arg === "--version") {
+            opts.version = argv[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--version=")) {
+            opts.version = arg.split("=")[1];
+            continue;
+        }
+        if (arg === "--dev") {
+            opts.command = "dev";
+            continue;
+        }
+        if (arg === "--backend-port") {
+            opts.backendPort = Number(argv[i + 1]);
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--backend-port=")) {
+            opts.backendPort = Number(arg.split("=")[1]);
+            continue;
+        }
+        if (arg === "--web-port") {
+            opts.webPort = Number(argv[i + 1]);
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--web-port=")) {
+            opts.webPort = Number(arg.split("=")[1]);
+            continue;
+        }
+    }
+    return opts;
+}
+function findRepoRoot(startDir) {
+    let current = node_path_1.default.resolve(startDir);
+    while (true) {
+        if (current.endsWith(`${node_path_1.default.sep}apps`)) {
+            const backendInApps = node_path_1.default.join(current, "backend");
+            const webInApps = node_path_1.default.join(current, "web");
+            if (node_fs_1.default.existsSync(backendInApps) && node_fs_1.default.existsSync(webInApps)) {
+                return node_path_1.default.dirname(current);
+            }
+        }
+        const backendDir = node_path_1.default.join(current, "apps", "backend");
+        const webDir = node_path_1.default.join(current, "apps", "web");
+        if (node_fs_1.default.existsSync(backendDir) && node_fs_1.default.existsSync(webDir)) {
+            return current;
+        }
+        const parent = node_path_1.default.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+async function main() {
+    const raw = parseArgs(process.argv.slice(2));
+    const backendPort = (0, ports_1.ensureValidPort)(raw.backendPort, "backend port");
+    const webPort = (0, ports_1.ensureValidPort)(raw.webPort, "web port");
+    if (raw.command === "dev") {
+        const repoRoot = findRepoRoot(process.cwd());
+        if (!repoRoot) {
+            throw new Error("Unable to locate repo root for dev. Run from the repo.");
+        }
+        await (0, dev_1.runDev)({ repoRoot, backendPort, webPort });
+        return;
+    }
+    await (0, update_1.maybePromptForUpdate)(package_json_1.default.version, process.argv.slice(2));
+    await (0, run_1.runRelease)({ version: raw.version, backendPort, webPort });
+}
+main().catch((err) => {
+    console.error(`[kandev] ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/dist/constants.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DATA_DIR = exports.CACHE_DIR = exports.HEALTH_TIMEOUT_MS = exports.RANDOM_PORT_RETRIES = exports.RANDOM_PORT_MAX = exports.RANDOM_PORT_MIN = exports.DEFAULT_AGENTCTL_PORT = exports.DEFAULT_WEB_PORT = exports.DEFAULT_BACKEND_PORT = void 0;
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+// Default service ports (will auto-fallback if busy).
+exports.DEFAULT_BACKEND_PORT = 8080;
+exports.DEFAULT_WEB_PORT = 3000;
+exports.DEFAULT_AGENTCTL_PORT = 9999;
+// Random fallback range for port selection.
+exports.RANDOM_PORT_MIN = 10000;
+exports.RANDOM_PORT_MAX = 60000;
+exports.RANDOM_PORT_RETRIES = 10;
+// Backend healthcheck timeout during startup.
+exports.HEALTH_TIMEOUT_MS = 15000;
+// Local user cache/data directories for release bundles and DB.
+exports.CACHE_DIR = node_path_1.default.join(node_os_1.default.homedir(), ".kandev", "bin");
+exports.DATA_DIR = node_path_1.default.join(node_os_1.default.homedir(), ".kandev", "data");

package/dist/dev.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDev = runDev;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = __importDefault(require("node:path"));
+const constants_1 = require("./constants");
+const health_1 = require("./health");
+const ports_1 = require("./ports");
+const process_1 = require("./process");
+const web_1 = require("./web");
+async function runDev({ repoRoot, backendPort, webPort }) {
+    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 backendEnv = {
+        ...process.env,
+        KANDEV_SERVER_PORT: String(actualBackendPort),
+        KANDEV_AGENT_STANDALONE_PORT: String(agentctlPort),
+    };
+    const webEnv = {
+        ...process.env,
+        KANDEV_API_BASE_URL: backendUrl,
+        NEXT_PUBLIC_KANDEV_API_BASE_URL: backendUrl,
+        PORT: String(actualWebPort),
+        NEXT_PUBLIC_KANDEV_DEBUG: "true",
+    };
+    console.log("[kandev] dev mode: using local repo");
+    console.log("[kandev] backend port:", actualBackendPort);
+    console.log("[kandev] web port:", actualWebPort);
+    console.log("[kandev] agentctl port:", agentctlPort);
+    const supervisor = (0, process_1.createProcessSupervisor)();
+    supervisor.attachSignalHandlers();
+    const backendProc = (0, node_child_process_1.spawn)("make", ["-C", node_path_1.default.join("apps", "backend"), "dev"], { cwd: repoRoot, env: backendEnv, stdio: "inherit" });
+    supervisor.children.push(backendProc);
+    backendProc.on("exit", (code, signal) => {
+        console.error(`[kandev] backend exited (code=${code}, signal=${signal})`);
+        const exitCode = signal ? 0 : code ?? 1;
+        void supervisor.shutdown("backend exit").then(() => process.exit(exitCode));
+    });
+    await (0, health_1.waitForHealth)(backendUrl, backendProc, constants_1.HEALTH_TIMEOUT_MS);
+    console.log(`[kandev] backend ready at ${backendUrl}`);
+    const webUrl = `http://localhost:${actualWebPort}`;
+    (0, web_1.launchWebApp)({
+        command: "pnpm",
+        args: ["-C", "apps", "--filter", "@kandev/web", "dev"],
+        cwd: repoRoot,
+        env: webEnv,
+        url: webUrl,
+        supervisor,
+        label: "web",
+    });
+    console.log(`[kandev] web ready at ${webUrl}`);
+}

package/dist/github.js

@@ -0,0 +1,155 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRelease = getRelease;
+exports.ensureAsset = ensureAsset;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_https_1 = __importDefault(require("node:https"));
+const node_path_1 = __importDefault(require("node:path"));
+// Allow overriding the GitHub repo for forks/testing.
+const OWNER = process.env.KANDEV_GITHUB_OWNER || "kandev";
+const REPO = process.env.KANDEV_GITHUB_REPO || "kandev";
+const API_BASE = `https://api.github.com/repos/${OWNER}/${REPO}`;
+function requestJson(url) {
+    return new Promise((resolve, reject) => {
+        const req = node_https_1.default.get(url, {
+            headers: {
+                "User-Agent": "kandev-npx",
+                Accept: "application/vnd.github+json",
+                ...(process.env.KANDEV_GITHUB_TOKEN
+                    ? { Authorization: `Bearer ${process.env.KANDEV_GITHUB_TOKEN}` }
+                    : {}),
+            },
+        }, (res) => {
+            if (res.statusCode !== 200) {
+                return reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
+            }
+            let body = "";
+            res.on("data", (chunk) => (body += chunk));
+            res.on("end", () => {
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch {
+                    reject(new Error(`Failed to parse JSON from ${url}`));
+                }
+            });
+        });
+        req.setTimeout(5000, () => {
+            req.destroy(new Error(`Request timed out fetching ${url}`));
+        });
+        req.on("error", reject);
+    });
+}
+function downloadFile(url, destPath, expectedSha256, onProgress) {
+    const tempPath = `${destPath}.tmp`;
+    return new Promise((resolve, reject) => {
+        const file = node_fs_1.default.createWriteStream(tempPath);
+        const hash = node_crypto_1.default.createHash("sha256");
+        const cleanup = () => {
+            try {
+                node_fs_1.default.unlinkSync(tempPath);
+            }
+            catch { }
+        };
+        const req = node_https_1.default.get(url, {
+            headers: {
+                "User-Agent": "kandev-npx",
+                Accept: "application/octet-stream",
+                ...(process.env.KANDEV_GITHUB_TOKEN
+                    ? { Authorization: `Bearer ${process.env.KANDEV_GITHUB_TOKEN}` }
+                    : {}),
+            },
+        }, (res) => {
+            if (res.statusCode !== 200) {
+                file.close();
+                cleanup();
+                return reject(new Error(`HTTP ${res.statusCode} downloading ${url}`));
+            }
+            const totalSize = parseInt(res.headers["content-length"] || "0", 10);
+            let downloadedSize = 0;
+            res.on("data", (chunk) => {
+                downloadedSize += chunk.length;
+                hash.update(chunk);
+                if (onProgress)
+                    onProgress(downloadedSize, totalSize);
+            });
+            res.pipe(file);
+            file.on("finish", () => {
+                file.close();
+                const actualSha256 = hash.digest("hex");
+                if (expectedSha256 && actualSha256 !== expectedSha256) {
+                    cleanup();
+                    return reject(new Error(`Checksum mismatch: expected ${expectedSha256}, got ${actualSha256}`));
+                }
+                try {
+                    node_fs_1.default.renameSync(tempPath, destPath);
+                    resolve(destPath);
+                }
+                catch (err) {
+                    cleanup();
+                    reject(err);
+                }
+            });
+        });
+        req.setTimeout(5000, () => {
+            req.destroy(new Error(`Request timed out downloading ${url}`));
+        });
+        req.on("error", (err) => {
+            file.close();
+            cleanup();
+            reject(err);
+        });
+    });
+}
+function findAsset(release, name) {
+    return release.assets?.find((asset) => asset.name === name);
+}
+function readSha256(pathToSha) {
+    if (!node_fs_1.default.existsSync(pathToSha)) {
+        return null;
+    }
+    const content = node_fs_1.default.readFileSync(pathToSha, "utf8").trim();
+    const first = content.split(/\s+/)[0];
+    return first || null;
+}
+async function getRelease(version) {
+    if (version) {
+        return requestJson(`${API_BASE}/releases/tags/${version}`);
+    }
+    return requestJson(`${API_BASE}/releases/latest`);
+}
+async function ensureAsset(release, assetName, cacheDir, onProgress) {
+    const asset = findAsset(release, assetName);
+    if (!asset) {
+        throw new Error(`Release asset not found: ${assetName}`);
+    }
+    node_fs_1.default.mkdirSync(cacheDir, { recursive: true });
+    const destPath = node_path_1.default.join(cacheDir, assetName);
+    const shaPath = `${destPath}.sha256`;
+    let expectedSha = readSha256(shaPath);
+    if (!expectedSha) {
+        const shaAsset = findAsset(release, `${assetName}.sha256`);
+        if (shaAsset) {
+            await downloadFile(shaAsset.browser_download_url, shaPath);
+            expectedSha = readSha256(shaPath);
+        }
+    }
+    if (node_fs_1.default.existsSync(destPath)) {
+        if (!expectedSha) {
+            return destPath;
+        }
+        const hash = node_crypto_1.default.createHash("sha256");
+        const file = node_fs_1.default.readFileSync(destPath);
+        hash.update(file);
+        if (hash.digest("hex") === expectedSha) {
+            return destPath;
+        }
+        node_fs_1.default.unlinkSync(destPath);
+    }
+    await downloadFile(asset.browser_download_url, destPath, expectedSha, onProgress);
+    return destPath;
+}

package/dist/health.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delay = delay;
+exports.waitForHealth = waitForHealth;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForHealth(baseUrl, proc, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const healthUrl = `${baseUrl}/health`;
+    while (Date.now() < deadline) {
+        if (proc.exitCode !== null) {
+            throw new Error("Backend exited before healthcheck passed");
+        }
+        try {
+            const res = await fetch(healthUrl);
+            if (res.ok) {
+                return;
+            }
+        }
+        catch {
+            // ignore until timeout
+        }
+        await delay(300);
+    }
+    throw new Error(`Backend healthcheck timed out after ${timeoutMs}ms`);
+}

package/dist/platform.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBinaryName = getBinaryName;
+exports.getPlatformDir = getPlatformDir;
+const node_child_process_1 = require("node:child_process");
+const isWindows = process.platform === "win32";
+function getBinaryName(base) {
+    return isWindows ? `${base}.exe` : base;
+}
+function getEffectiveArch() {
+    const platform = process.platform;
+    const nodeArch = process.arch;
+    if (platform === "darwin") {
+        if (nodeArch === "arm64")
+            return "arm64";
+        try {
+            const translated = (0, node_child_process_1.execSync)("sysctl -in sysctl.proc_translated", {
+                encoding: "utf8",
+            }).trim();
+            if (translated === "1")
+                return "arm64";
+        }
+        catch { }
+        return "x64";
+    }
+    if (/arm/i.test(nodeArch))
+        return "arm64";
+    if (platform === "win32") {
+        const pa = process.env.PROCESSOR_ARCHITECTURE || "";
+        const paw = process.env.PROCESSOR_ARCHITEW6432 || "";
+        if (/arm/i.test(pa) || /arm/i.test(paw))
+            return "arm64";
+    }
+    return "x64";
+}
+function getPlatformDir() {
+    const platform = process.platform;
+    const arch = getEffectiveArch();
+    if (platform === "linux" && arch === "x64")
+        return "linux-x64";
+    if (platform === "darwin" && arch === "x64")
+        return "macos-x64";
+    if (platform === "darwin" && arch === "arm64")
+        return "macos-arm64";
+    if (platform === "win32" && arch === "x64")
+        return "windows-x64";
+    if (platform === "win32" && arch === "arm64")
+        return "windows-arm64";
+    throw new Error(`Unsupported platform: ${platform}-${arch}`);
+}

package/dist/ports.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+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");
+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;
+}
+function isPortAvailable(port, host = "0.0.0.0") {
+    return new Promise((resolve) => {
+        const server = node_net_1.default.createServer();
+        server.unref();
+        server.on("error", (err) => {
+            if (err.code === "EADDRINUSE" || err.code === "EACCES") {
+                resolve(false);
+            }
+            else {
+                resolve(false);
+            }
+        });
+        server.listen(port, host, () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+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) {
+    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);
+        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`);
+}

package/dist/process.js

@@ -0,0 +1,28 @@
+"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;
+const tree_kill_1 = __importDefault(require("tree-kill"));
+function createProcessSupervisor() {
+    let shuttingDown = false;
+    const children = [];
+    const shutdown = async (reason) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log(`[kandev] shutting down (${reason})...`);
+        await Promise.all(children
+            .filter((child) => child.pid)
+            .map((child) => new Promise((resolve) => (0, tree_kill_1.default)(child.pid, "SIGTERM", () => resolve()))));
+    };
+    const onSignal = (signal) => {
+        void shutdown(`signal ${signal}`).then(() => process.exit(0));
+    };
+    const attachSignalHandlers = () => {
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+    };
+    return { children, shutdown, attachSignalHandlers };
+}

package/dist/run.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRelease = runRelease;
+const node_child_process_1 = require("node:child_process");
+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 constants_2 = require("./constants");
+const health_1 = require("./health");
+const platform_1 = require("./platform");
+const ports_1 = require("./ports");
+const process_1 = require("./process");
+const web_1 = require("./web");
+async function prepareReleaseBundle({ version, backendPort, webPort, }) {
+    const platformDir = (0, platform_1.getPlatformDir)();
+    const release = await (0, github_1.getRelease)(version);
+    const tag = release.tag_name || "latest";
+    const assetName = `kandev-${platformDir}.zip`;
+    const cacheDir = node_path_1.default.join(constants_2.CACHE_DIR, tag, platformDir);
+    const zipPath = await (0, github_1.ensureAsset)(release, 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)(zipPath, cacheDir);
+    const bundleDir = (0, bundle_1.findBundleRoot)(cacheDir);
+    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 at ${backendBin}`);
+    }
+    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 at ${agentctlBin}`);
+    }
+    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}`;
+    node_fs_1.default.mkdirSync(constants_1.DATA_DIR, { recursive: true });
+    const dbPath = node_path_1.default.join(constants_1.DATA_DIR, "kandev.db");
+    const backendEnv = {
+        ...process.env,
+        KANDEV_SERVER_PORT: String(actualBackendPort),
+        KANDEV_AGENT_STANDALONE_PORT: String(agentctlPort),
+        KANDEV_DB_PATH: dbPath,
+    };
+    const webEnv = {
+        ...process.env,
+        KANDEV_API_BASE_URL: backendUrl,
+        NEXT_PUBLIC_KANDEV_API_BASE_URL: backendUrl,
+        PORT: String(actualWebPort),
+        NODE_ENV: "production",
+    };
+    return {
+        bundleDir,
+        backendBin,
+        backendUrl,
+        backendEnv,
+        webEnv,
+        webPort: actualWebPort,
+        agentctlPort,
+    };
+}
+function launchReleaseApps(prepared) {
+    console.log("[kandev] backend port:", prepared.backendEnv.KANDEV_SERVER_PORT);
+    console.log("[kandev] web port:", prepared.webPort);
+    console.log("[kandev] agentctl port:", prepared.agentctlPort);
+    const supervisor = (0, process_1.createProcessSupervisor)();
+    supervisor.attachSignalHandlers();
+    const backendProc = (0, node_child_process_1.spawn)(prepared.backendBin, [], {
+        cwd: node_path_1.default.dirname(prepared.backendBin),
+        env: prepared.backendEnv,
+        stdio: "inherit",
+    });
+    supervisor.children.push(backendProc);
+    backendProc.on("exit", (code, signal) => {
+        console.error(`[kandev] backend exited (code=${code}, signal=${signal})`);
+        void supervisor.shutdown("backend exit").then(() => process.exit(code || 1));
+    });
+    const webServerPath = (0, bundle_1.resolveWebServerPath)(prepared.bundleDir);
+    if (!webServerPath) {
+        throw new Error("Web server entry (server.js) not found in bundle");
+    }
+    const webUrl = `http://localhost:${prepared.webPort}`;
+    const webProc = (0, web_1.launchWebApp)({
+        command: "node",
+        args: [webServerPath],
+        cwd: node_path_1.default.dirname(webServerPath),
+        env: prepared.webEnv,
+        url: webUrl,
+        supervisor,
+        label: "web",
+    });
+    return { supervisor, backendProc, webServerPath };
+}
+async function runRelease({ version, backendPort, webPort }) {
+    const prepared = await prepareReleaseBundle({ version, backendPort, webPort });
+    const { backendProc } = launchReleaseApps(prepared);
+    // Wait for backend before announcing the web URL.
+    await (0, health_1.waitForHealth)(prepared.backendUrl, backendProc, constants_1.HEALTH_TIMEOUT_MS);
+    console.log(`[kandev] backend ready at ${prepared.backendUrl}`);
+    console.log(`[kandev] web ready at http://localhost:${prepared.webPort}`);
+}

package/dist/update.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybePromptForUpdate = maybePromptForUpdate;
+const node_child_process_1 = require("node:child_process");
+const node_https_1 = __importDefault(require("node:https"));
+const node_readline_1 = __importDefault(require("node:readline"));
+function requestJson(url) {
+    return new Promise((resolve, reject) => {
+        const req = node_https_1.default.get(url, { headers: { "User-Agent": "kandev-npx" } }, (res) => {
+            if (res.statusCode !== 200) {
+                return reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
+            }
+            let body = "";
+            res.on("data", (chunk) => (body += chunk));
+            res.on("end", () => {
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch {
+                    reject(new Error(`Failed to parse JSON from ${url}`));
+                }
+            });
+        });
+        req.setTimeout(5000, () => {
+            req.destroy(new Error(`Request timed out fetching ${url}`));
+        });
+        req.on("error", reject);
+    });
+}
+async function getLatestNpmVersion() {
+    const data = await requestJson("https://registry.npmjs.org/kandev");
+    return data?.["dist-tags"]?.latest;
+}
+function compareVersions(a, b) {
+    const pa = String(a).replace(/^v/, "").split(".").map(Number);
+    const pb = String(b).replace(/^v/, "").split(".").map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+        const av = pa[i] ?? 0;
+        const bv = pb[i] ?? 0;
+        if (av > bv)
+            return 1;
+        if (av < bv)
+            return -1;
+    }
+    return 0;
+}
+function promptYesNo(question, defaultYes = false) {
+    return new Promise((resolve) => {
+        if (!process.stdin.isTTY) {
+            resolve(false);
+            return;
+        }
+        const rl = node_readline_1.default.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+        rl.question(`${question} ${suffix} `, (answer) => {
+            rl.close();
+            const normalized = String(answer || "").trim().toLowerCase();
+            if (!normalized) {
+                resolve(Boolean(defaultYes));
+                return;
+            }
+            resolve(normalized === "y" || normalized === "yes");
+        });
+    });
+}
+async function maybePromptForUpdate(currentVersion, args) {
+    // Allow disabling update checks for CI or automation.
+    if (process.env.KANDEV_SKIP_UPDATE === "1" || process.env.KANDEV_NO_UPDATE_PROMPT === "1") {
+        return;
+    }
+    try {
+        const latest = await getLatestNpmVersion();
+        if (!latest)
+            return;
+        if (compareVersions(latest, currentVersion) <= 0)
+            return;
+        const wantsUpdate = await promptYesNo(`Update available: ${currentVersion} -> ${latest}. Update now?`, false);
+        if (!wantsUpdate)
+            return;
+        const env = { ...process.env, KANDEV_SKIP_UPDATE: "1" };
+        const child = (0, node_child_process_1.spawn)("npx", ["kandev@latest", ...args], {
+            stdio: "inherit",
+            env,
+        });
+        child.on("exit", (code) => process.exit(code || 0));
+        await new Promise(() => { });
+    }
+    catch {
+        // ignore update errors
+    }
+}

package/dist/web.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openBrowser = openBrowser;
+exports.launchWebApp = launchWebApp;
+const node_child_process_1 = require("node:child_process");
+function openBrowser(url) {
+    if (process.env.KANDEV_NO_BROWSER === "1") {
+        return;
+    }
+    const opener = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = process.platform === "win32"
+        ? ["/c", "start", "", url]
+        : [url];
+    try {
+        const child = (0, node_child_process_1.spawn)(opener, args, { stdio: "ignore", detached: true });
+        child.unref();
+    }
+    catch {
+        // ignore browser launch errors
+    }
+}
+function launchWebApp({ command, args, cwd, env, url, supervisor, label, }) {
+    const proc = (0, node_child_process_1.spawn)(command, args, { cwd, env, stdio: "inherit" });
+    supervisor.children.push(proc);
+    proc.on("exit", (code, signal) => {
+        console.error(`[kandev] ${label} exited (code=${code}, signal=${signal})`);
+        const exitCode = signal ? 0 : code ?? 1;
+        void supervisor.shutdown(`${label} exit`).then(() => process.exit(exitCode));
+    });
+    openBrowser(url);
+    return proc;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "kandev",
+  "version": "0.1.3",
+  "private": false,
+  "description": "NPX launcher for Kandev",
+  "license": "UNLICENSED",
+  "type": "commonjs",
+  "bin": {
+    "kandev": "bin/cli.js"
+  },
+  "main": "dist/cli.js",
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "tree-kill": "^1.2.2"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.7",
+    "@types/node": "^20",
+    "tsx": "^4.15.7",
+    "typescript": "^5"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "pnpm build"
+  }
+}