kandev 0.16.0 → 0.39.2

package/README.md

@@ -4,18 +4,36 @@ Manage tasks. Orchestrate agents. Review changes. Ship value.
 
 ## Quick Start
 
+### Homebrew
+
+```bash
+brew install kdlbs/kandev/kandev
+kandev
+```
+
+### NPX (requires npm 7+)
+
 ```bash
-npx kandev
+npx kandev@latest
 ```
 
-Downloads the latest release, starts the backend + web app, and opens your browser. Data (worktrees, SQLite DB) is stored in `~/.kandev` by default.
+Either install path resolves a platform-matched runtime (Go backend, agentctl, Next.js standalone web), launches the backend + web, and opens your browser. Data (worktrees, SQLite DB) is stored in `~/.kandev` by default.
 
 ## Version and Updates
 
-- `npx kandev` (run mode) uses the latest GitHub release bundle by default.
-- At startup, the launcher prints the resolved release tag (for example: `[kandev] release: v0.2.3 (github latest)`).
-- Use `--version <tag>` to pin a specific runtime bundle release.
-- CLI package updates are checked from npm and shown as a prompt. They are not forced.
+The package manager owns the runtime version. `kandev@X.Y.Z` ships with the matching runtime.
+
+- **Update via Homebrew**: `brew upgrade kandev`
+- **Update via npm/npx**: `npx kandev@latest` or `npm install -g kandev@latest`
+- **Print CLI version**: `kandev --version`
+
+### Advanced: pin a specific runtime tag
+
+`--runtime-version <tag>` downloads a specific GitHub release runtime instead of using the installed one. For debugging compatibility issues only:
+
+```bash
+kandev --runtime-version v0.16.0
+```
 
 ## What You Get
 

package/dist/args.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParseError = void 0;
+exports.parseArgs = parseArgs;
+exports.resolvePorts = resolvePorts;
+class ParseError extends Error {
+}
+exports.ParseError = ParseError;
+function parseArgs(argv) {
+    const opts = { command: "run" };
+    let showHelp = false;
+    const deprecatedFlags = [];
+    const noteDeprecated = (flag) => {
+        if (!deprecatedFlags.includes(flag))
+            deprecatedFlags.push(flag);
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            showHelp = true;
+            continue;
+        }
+        if (arg === "--version" || arg === "-V") {
+            opts.showVersion = true;
+            continue;
+        }
+        if (arg === "dev" || arg === "run" || arg === "start") {
+            opts.command = arg;
+            continue;
+        }
+        if (arg === "--runtime-version") {
+            opts.runtimeVersion = takeValue(argv, i, "--runtime-version");
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--runtime-version=")) {
+            const value = arg.slice("--runtime-version=".length);
+            if (value.length === 0)
+                throw new ParseError("--runtime-version requires a value");
+            opts.runtimeVersion = value;
+            continue;
+        }
+        if (arg === "--dev") {
+            opts.command = "dev";
+            continue;
+        }
+        // --port is an alias for --backend-port (the user-facing port in run/start).
+        if (arg === "--port" || arg === "--backend-port") {
+            opts.backendPort = parsePort(takeValue(argv, i, arg), arg);
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--port=") || arg.startsWith("--backend-port=")) {
+            const flag = arg.startsWith("--port=") ? "--port" : "--backend-port";
+            opts.backendPort = parsePort(arg.slice(flag.length + 1), flag);
+            continue;
+        }
+        if (arg === "--web-internal-port") {
+            opts.webPort = parsePort(takeValue(argv, i, "--web-internal-port"), "--web-internal-port");
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--web-internal-port=")) {
+            opts.webPort = parsePort(arg.slice("--web-internal-port=".length), "--web-internal-port");
+            continue;
+        }
+        if (arg === "--web-port") {
+            opts.webPort = parsePort(takeValue(argv, i, "--web-port"), "--web-port");
+            noteDeprecated("--web-port");
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--web-port=")) {
+            opts.webPort = parsePort(arg.slice("--web-port=".length), "--web-port");
+            noteDeprecated("--web-port");
+            continue;
+        }
+        if (arg === "--verbose" || arg === "-v") {
+            opts.verbose = true;
+            continue;
+        }
+        if (arg === "--debug") {
+            opts.debug = true;
+            continue;
+        }
+    }
+    return { options: opts, showHelp, deprecatedFlags };
+}
+function takeValue(argv, i, flag) {
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith("-")) {
+        throw new ParseError(`${flag} requires a value`);
+    }
+    return v;
+}
+function parsePort(raw, flag) {
+    const n = Number(raw);
+    if (raw === "" || !Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new ParseError(`${flag} value must be an integer between 1 and 65535, got "${raw}"`);
+    }
+    return n;
+}
+// CLI flags beat env vars; KANDEV_PORT is an alias for KANDEV_BACKEND_PORT.
+function resolvePorts(options, env) {
+    return {
+        backendPort: options.backendPort ?? envPort(env, "KANDEV_BACKEND_PORT") ?? envPort(env, "KANDEV_PORT"),
+        webPort: options.webPort ?? envPort(env, "KANDEV_WEB_PORT"),
+    };
+}
+function envPort(env, name) {
+    const val = env[name];
+    if (val === undefined)
+        return undefined;
+    const n = Number(val);
+    if (val === "" || !Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new ParseError(`${name} must be an integer between 1 and 65535, got "${val}"`);
+    }
+    return n;
+}

package/dist/cli.js

@@ -6,20 +6,20 @@ 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 args_1 = require("./args");
 const dev_1 = require("./dev");
 const run_1 = require("./run");
 const start_1 = require("./start");
 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>] [--verbose] [--debug]
-  kandev dev [--backend-port <port>] [--web-port <port>]
-  kandev start [--backend-port <port>] [--web-port <port>] [--verbose] [--debug]
-  kandev [--version <tag>] [--backend-port <port>] [--web-port <port>] [--verbose] [--debug]
-  kandev --dev [--backend-port <port>] [--web-port <port>]
+  kandev run [--port <port>] [--verbose] [--debug]
+  kandev dev [--port <port>]
+  kandev start [--port <port>] [--verbose] [--debug]
+  kandev [--port <port>] [--verbose] [--debug]
+  kandev --dev [--port <port>]
 
 Examples:
   kandev
@@ -27,81 +27,34 @@ Examples:
   kandev --dev
   kandev dev
   kandev start
-  kandev --version v0.1.0
-  kandev --backend-port 18080 --web-port 13000
+  kandev --version
+  kandev --port 3000
   kandev --debug
 
 Options:
-  dev             Use local repo for dev (make dev + next dev) if available.
-  start           Use local production build (make build + next start).
-  run             Use release bundles (default).
+  dev              Use local repo for dev (make dev + next dev) if available.
+  start            Use local production build (make build + next start).
+  run              Use installed runtime bundle (default).
   --dev            Alias for "dev".
-  --version        Release tag to install (default: latest).
-  --backend-port   Override backend port (or KANDEV_BACKEND_PORT env var).
-  --web-port       Override web port (or KANDEV_WEB_PORT env var).
+  --version, -V    Print CLI version and exit.
+  --port           Port for the Go backend (the URL kandev opens on in
+                   start/run). Alias for --backend-port. Also reads
+                   KANDEV_PORT or KANDEV_BACKEND_PORT.
   --verbose, -v    Show info logs from backend + web.
   --debug          Show debug logs + agent message dumps.
   --help, -h       Show help.
+
+Advanced:
+  --backend-port         Same as --port.
+  --web-internal-port    Override the internal Next.js port. The Go backend
+                         reverse-proxies to it; users hit the backend port.
+                         Also reads KANDEV_WEB_PORT.
+  --web-port             Deprecated alias for --web-internal-port.
+  --runtime-version <tag>  Download and use a specific release tag instead of
+                           the installed runtime. For debugging only.
+                           Example: kandev --runtime-version v0.16.0
 `);
 }
-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" || arg === "start") {
-            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;
-        }
-        if (arg === "--verbose" || arg === "-v") {
-            opts.verbose = true;
-            continue;
-        }
-        if (arg === "--debug") {
-            opts.debug = true;
-            continue;
-        }
-    }
-    return opts;
-}
-function envPort(name) {
-    const val = process.env[name];
-    return val ? Number(val) : undefined;
-}
 function findRepoRoot(startDir) {
     let current = node_path_1.default.resolve(startDir);
     while (true) {
@@ -125,10 +78,22 @@ function findRepoRoot(startDir) {
     }
 }
 async function main() {
-    const raw = parseArgs(process.argv.slice(2));
-    const backendPort = (0, ports_1.ensureValidPort)(raw.backendPort ?? envPort("KANDEV_BACKEND_PORT"), "backend port");
-    const webPort = (0, ports_1.ensureValidPort)(raw.webPort ?? envPort("KANDEV_WEB_PORT"), "web port");
-    if (raw.command === "dev") {
+    const { options, showHelp, deprecatedFlags } = (0, args_1.parseArgs)(process.argv.slice(2));
+    if (options.showVersion) {
+        console.log(package_json_1.default.version);
+        return;
+    }
+    if (showHelp) {
+        printHelp();
+        return;
+    }
+    for (const flag of deprecatedFlags) {
+        process.stderr.write(`[kandev] ${flag} is deprecated; use --web-internal-port\n`);
+    }
+    const resolved = (0, args_1.resolvePorts)(options, process.env);
+    const backendPort = (0, ports_1.ensureValidPort)(resolved.backendPort, "backend port");
+    const webPort = (0, ports_1.ensureValidPort)(resolved.webPort, "web port");
+    if (options.command === "dev") {
         const repoRoot = findRepoRoot(process.cwd());
         if (!repoRoot) {
             throw new Error("Unable to locate repo root for dev. Run from the repo.");
@@ -136,24 +101,34 @@ async function main() {
         await (0, dev_1.runDev)({ repoRoot, backendPort, webPort });
         return;
     }
-    if (raw.command === "start") {
+    if (options.command === "start") {
         const repoRoot = findRepoRoot(process.cwd());
         if (!repoRoot) {
             throw new Error("Unable to locate repo root for start. Run from the repo.");
         }
-        await (0, start_1.runStart)({ repoRoot, backendPort, webPort, verbose: raw.verbose, debug: raw.debug });
+        await (0, start_1.runStart)({
+            repoRoot,
+            backendPort,
+            webPort,
+            verbose: options.verbose,
+            debug: options.debug,
+        });
         return;
     }
-    await (0, update_1.maybePromptForUpdate)(package_json_1.default.version, process.argv.slice(2));
     await (0, run_1.runRelease)({
-        version: raw.version,
+        runtimeVersion: options.runtimeVersion,
         backendPort,
         webPort,
-        verbose: raw.verbose,
-        debug: raw.debug,
+        verbose: options.verbose,
+        debug: options.debug,
     });
 }
 main().catch((err) => {
+    if (err instanceof args_1.ParseError) {
+        console.error(`[kandev] ${err.message}`);
+        console.error("[kandev] run --help for usage");
+        process.exit(2);
+    }
     console.error(`[kandev] ${err instanceof Error ? err.message : String(err)}`);
     process.exit(1);
 });

package/dist/constants.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEV_KANDEV_DOTDIR = exports.DATA_DIR = exports.CACHE_DIR = exports.KANDEV_TASKS_DIR = exports.KANDEV_HOME_DIR = exports.KANDEV_DOTDIR = exports.HEALTH_TIMEOUT_MS_DEV = exports.HEALTH_TIMEOUT_MS_RELEASE = exports.RANDOM_PORT_RETRIES = exports.RANDOM_PORT_MAX = exports.RANDOM_PORT_MIN = exports.DEFAULT_MCP_PORT = exports.DEFAULT_AGENTCTL_PORT = exports.DEFAULT_WEB_PORT = exports.DEFAULT_BACKEND_PORT = void 0;
+exports.DEV_KANDEV_DOTDIR = exports.DATA_DIR = exports.CACHE_DIR = exports.KANDEV_TASKS_DIR = exports.KANDEV_HOME_DIR = exports.KANDEV_DOTDIR = exports.HEALTH_TIMEOUT_MS_DEV = exports.HEALTH_TIMEOUT_MS_RELEASE = 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;
 exports.devKandevHome = devKandevHome;
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -13,7 +13,6 @@ const node_path_1 = __importDefault(require("node:path"));
 exports.DEFAULT_BACKEND_PORT = 38429;
 exports.DEFAULT_WEB_PORT = 37429;
 exports.DEFAULT_AGENTCTL_PORT = 39429;
-exports.DEFAULT_MCP_PORT = 40429;
 // Random fallback range for port selection.
 exports.RANDOM_PORT_MIN = 10000;
 exports.RANDOM_PORT_MAX = 60000;

package/dist/dev.js

@@ -19,6 +19,7 @@ async function runDev({ repoRoot, backendPort, webPort }) {
     const backendEnv = (0, shared_1.buildBackendEnv)({ ports, extra });
     const webEnv = (0, shared_1.buildWebEnv)({ ports, debug: true });
     const logLevel = process.env.KANDEV_LOGGING_LEVEL?.trim() || process.env.KANDEV_LOG_LEVEL?.trim() || "info";
+    const webUrl = `http://localhost:${ports.webPort}`;
     (0, shared_1.logStartupInfo)({
         header: "dev mode: using local repo",
         ports,
@@ -38,7 +39,6 @@ async function runDev({ repoRoot, backendPort, webPort }) {
     console.log("[kandev] starting backend...");
     await (0, health_1.waitForHealth)(ports.backendUrl, backendProc, healthTimeoutMs);
     console.log(`[kandev] backend ready at ${ports.backendUrl}`);
-    const webUrl = `http://localhost:${ports.webPort}`;
     console.log("[kandev] starting web...");
     const webProc = (0, web_1.launchWebApp)({
         command: "pnpm",
@@ -49,7 +49,7 @@ async function runDev({ repoRoot, backendPort, webPort }) {
         label: "web",
     });
     await (0, health_1.waitForUrlReady)(webUrl, webProc, healthTimeoutMs);
-    console.log(`[kandev] web ready at ${webUrl}`);
+    console.log(`[kandev] open: ${webUrl}`);
     (0, web_1.openBrowser)(webUrl);
 }
 // Computes the dev-mode backend env. Dev mode always roots kandev under

package/dist/run.js

@@ -18,6 +18,7 @@ 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 web_1 = require("./web");
 /**
@@ -77,47 +78,62 @@ function cleanOldReleases(currentTag) {
         // Non-critical — don't fail the launch if cleanup errors.
     }
 }
-async function prepareReleaseBundle({ version, backendPort, webPort, verbose = false, debug = false, }) {
+/**
+ * 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)();
-    let tag;
-    let cacheDir;
-    try {
-        const release = await (0, github_1.getRelease)(version);
-        tag = release.tag_name;
-        const assetName = `kandev-${platformDir}.tar.gz`;
-        cacheDir = node_path_1.default.join(constants_1.CACHE_DIR, 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);
-    }
-    catch (err) {
-        // GitHub unreachable — try to launch from cache.
-        const cached = findCachedRelease(platformDir, version);
-        if (!cached) {
-            const target = version ? `version ${version}` : "latest version";
-            const reason = err instanceof Error ? err.message : String(err);
-            throw new Error(`Failed to fetch ${target} and no cached release found.\n` +
-                `  Reason: ${reason}\n` +
-                `  Run kandev once while online to cache a release for offline use.`);
+    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(constants_1.CACHE_DIR, 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);
         }
-        tag = cached.tag;
-        cacheDir = cached.cacheDir;
-        process.stderr.write(`[kandev] GitHub unreachable — using cached release ${tag}\n`);
-    }
-    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}`);
+        else {
+            try {
+                tag = await downloadRuntimeVersion(runtimeVersion);
+                const cacheDir = node_path_1.default.join(constants_1.CACHE_DIR, 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;
     }
-    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}`);
+    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));
@@ -127,10 +143,7 @@ async function prepareReleaseBundle({ version, backendPort, webPort, verbose = f
     const logLevel = process.env.KANDEV_LOG_LEVEL?.trim() || (debug ? "debug" : verbose ? "info" : "warn");
     node_fs_1.default.mkdirSync(constants_1.DATA_DIR, { recursive: true });
     const dbPath = node_path_1.default.join(constants_1.DATA_DIR, "kandev.db");
-    // Note: Release mode doesn't configure MCP server ports as it uses
-    // the bundled configuration. Only backend and agentctl ports are set.
-    // Log level defaults to warn for clean output and can be overridden
-    // via KANDEV_LOG_LEVEL or --verbose/--debug flags.
+    const backendBin = node_path_1.default.join(bundleDir, "bin", (0, platform_1.getBinaryName)("kandev"));
     const backendEnv = {
         ...process.env,
         KANDEV_SERVER_PORT: String(actualBackendPort),
@@ -144,8 +157,6 @@ async function prepareReleaseBundle({ version, backendPort, webPort, verbose = f
         ...process.env,
         KANDEV_API_BASE_URL: backendUrl,
         PORT: String(actualWebPort),
-        // Ensure Next.js standalone server binds to 127.0.0.1 so localhost health checks work.
-        // Without this, HOSTNAME from the host environment can cause binding issues.
         HOSTNAME: "127.0.0.1",
     };
     webEnv.NODE_ENV = "production";
@@ -155,8 +166,7 @@ async function prepareReleaseBundle({ version, backendPort, webPort, verbose = f
         backendUrl,
         backendEnv,
         webEnv,
-        releaseTag: tag,
-        requestedVersion: version,
+        releaseTag,
         webPort: actualWebPort,
         agentctlPort,
         dbPath,
@@ -179,29 +189,20 @@ function attachRingBuffer(stream, maxChars = 64 * 1024) {
     });
     return () => buf;
 }
-function launchReleaseApps(prepared) {
-    const releaseSource = prepared.requestedVersion
-        ? `(requested: ${prepared.requestedVersion})`
-        : "(github latest)";
+function launchBundle(prepared) {
     (0, shared_1.logStartupInfo)({
-        header: `release: ${prepared.releaseTag} ${releaseSource}`,
+        header: `release: ${prepared.releaseTag}`,
         ports: {
             backendPort: Number(prepared.backendEnv.KANDEV_SERVER_PORT),
             webPort: prepared.webPort,
             agentctlPort: prepared.agentctlPort,
-            mcpPort: 0,
             backendUrl: prepared.backendUrl,
-            mcpUrl: "",
         },
         dbPath: prepared.dbPath,
         logLevel: prepared.logLevel,
     });
     const supervisor = (0, process_1.createProcessSupervisor)();
     supervisor.attachSignalHandlers();
-    // Start backend: ignore stdin, always show stderr immediately.
-    // In verbose/debug mode stream stdout live; otherwise capture it into a ring
-    // buffer so we can dump the last few KB if the healthcheck fails (users were
-    // previously seeing opaque "timed out" errors with no backend context).
     const backendProc = (0, node_child_process_1.spawn)(prepared.backendBin, [], {
         cwd: node_path_1.default.dirname(prepared.backendBin),
         env: prepared.backendEnv,
@@ -228,9 +229,15 @@ function launchReleaseApps(prepared) {
     }
     return { supervisor, backendProc, webServerPath, dumpBackendLogs };
 }
-async function runRelease({ version, backendPort, webPort, verbose = false, debug = false, }) {
-    const prepared = await prepareReleaseBundle({ version, backendPort, webPort, verbose, debug });
-    const { supervisor, backendProc, webServerPath, dumpBackendLogs } = launchReleaseApps(prepared);
+async function runRelease({ runtimeVersion, backendPort, webPort, verbose = false, debug = false, }) {
+    const prepared = await prepareBundleForLaunch({
+        runtimeVersion,
+        backendPort,
+        webPort,
+        verbose,
+        debug,
+    });
+    const { supervisor, backendProc, webServerPath, dumpBackendLogs } = 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);
@@ -247,6 +254,6 @@ async function runRelease({ version, backendPort, webPort, verbose = false, debu
         quiet: !prepared.showOutput,
     });
     await (0, health_1.waitForUrlReady)(webUrl, webProc, healthTimeoutMs);
-    console.log("[kandev] ready at " + prepared.backendUrl);
+    console.log("[kandev] open: " + prepared.backendUrl);
     (0, web_1.openBrowser)(prepared.backendUrl);
 }

package/dist/runtime.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.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}`);
+    }
+}

package/dist/shared.js

@@ -24,14 +24,11 @@ async function pickPorts(backendPort, webPort) {
     const resolvedBackendPort = backendPort ?? (await (0, ports_1.pickAvailablePort)(constants_1.DEFAULT_BACKEND_PORT));
     const resolvedWebPort = webPort ?? (await (0, ports_1.pickAvailablePort)(constants_1.DEFAULT_WEB_PORT));
     const agentctlPort = await (0, ports_1.pickAvailablePort)(constants_1.DEFAULT_AGENTCTL_PORT);
-    const mcpPort = await (0, ports_1.pickAvailablePort)(constants_1.DEFAULT_MCP_PORT);
     return {
         backendPort: resolvedBackendPort,
         webPort: resolvedWebPort,
         agentctlPort,
-        mcpPort,
         backendUrl: `http://localhost:${resolvedBackendPort}`,
-        mcpUrl: `http://localhost:${mcpPort}/sse`,
     };
 }
 /**
@@ -47,7 +44,6 @@ function buildBackendEnv(options) {
         KANDEV_SERVER_PORT: String(ports.backendPort),
         KANDEV_WEB_INTERNAL_URL: `http://localhost:${ports.webPort}`,
         KANDEV_AGENT_STANDALONE_PORT: String(ports.agentctlPort),
-        KANDEV_AGENT_MCP_SERVER_PORT: String(ports.mcpPort),
         ...(logLevel ? { KANDEV_LOG_LEVEL: logLevel } : {}),
         ...extra,
     };
@@ -85,11 +81,13 @@ function buildWebEnv(options) {
  */
 function logStartupInfo(options) {
     const { header, ports, dbPath, logLevel } = options;
+    const backendUrl = ports.backendUrl;
+    const webUrl = `http://localhost:${ports.webPort}`;
     console.log(`[kandev] ${header}`);
-    console.log("[kandev] url: http://localhost:" + ports.backendPort);
+    console.log("[kandev] backend:", backendUrl);
+    console.log("[kandev] web:", webUrl);
     console.log("[kandev] agentctl port:", ports.agentctlPort);
-    console.log("[kandev] mcp port:", ports.mcpPort);
-    console.log("[kandev] mcp url:", ports.mcpUrl);
+    console.log("[kandev] mcp url:", `${backendUrl}/mcp`);
     if (dbPath) {
         console.log("[kandev] db path:", dbPath);
     }

package/dist/start.js

@@ -171,6 +171,6 @@ async function runStart({ repoRoot, backendPort, webPort, verbose = false, debug
         quiet: !showOutput,
     });
     await (0, health_1.waitForUrlReady)(webUrl, webProc, healthTimeoutMs);
-    console.log("[kandev] ready at " + ports.backendUrl);
+    console.log("[kandev] open: " + ports.backendUrl);
     (0, web_1.openBrowser)(ports.backendUrl);
 }

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "kandev",
-  "version": "0.16.0",
+  "version": "0.39.2",
   "private": false,
-  "description": "NPX launcher for Kandev",
+  "description": "Launcher for Kandev — manage tasks, orchestrate agents, review changes, and ship value",
   "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kdlbs/kandev.git"
+  },
+  "homepage": "https://github.com/kdlbs/kandev",
   "type": "commonjs",
   "bin": {
     "kandev": "bin/cli.js"
@@ -13,12 +18,23 @@
     "bin",
     "dist"
   ],
+  "engines": {
+    "npm": ">=7"
+  },
+  "optionalDependencies": {
+    "@kdlbs/runtime-linux-x64": "0.39.2",
+    "@kdlbs/runtime-linux-arm64": "0.39.2",
+    "@kdlbs/runtime-darwin-x64": "0.39.2",
+    "@kdlbs/runtime-darwin-arm64": "0.39.2",
+    "@kdlbs/runtime-win32-x64": "0.39.2"
+  },
   "dependencies": {
     "tar": "^7.5.11",
     "tree-kill": "^1.2.2"
   },
   "devDependencies": {
     "@types/node": "^20",
+    "esbuild": "^0.24.0",
     "tsx": "^4.15.7",
     "typescript": "^5",
     "vitest": "^1.6.0"
@@ -26,6 +42,7 @@
   "scripts": {
     "dev": "unset npm_config_prefix && tsx src/cli.ts",
     "build": "tsc -p tsconfig.json",
+    "bundle": "esbuild dist/cli.js --bundle --platform=node --format=cjs --outfile=dist/cli.bundle.js",
     "start": "node dist/cli.js",
     "test": "vitest run",
     "prepublishOnly": "pnpm build"

package/dist/update.js

@@ -1,87 +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.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"));
-const version_1 = require("./version");
-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 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 ((0, version_1.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
-    }
-}