kandev 0.17.0 → 0.40.0

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

@@ -20,20 +20,24 @@ function parseArgs(argv) {
             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 === "--version") {
-            opts.version = takeValue(argv, i, "--version");
+        if (arg === "--runtime-version") {
+            opts.runtimeVersion = takeValue(argv, i, "--runtime-version");
             i += 1;
             continue;
         }
-        if (arg.startsWith("--version=")) {
-            const value = arg.slice("--version=".length);
+        if (arg.startsWith("--runtime-version=")) {
+            const value = arg.slice("--runtime-version=".length);
             if (value.length === 0)
-                throw new ParseError("--version requires a value");
-            opts.version = value;
+                throw new ParseError("--runtime-version requires a value");
+            opts.runtimeVersion = value;
             continue;
         }
         if (arg === "--dev") {

package/dist/cli.js

@@ -11,15 +11,14 @@ 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>] [--port <port>] [--verbose] [--debug]
+  kandev run [--port <port>] [--verbose] [--debug]
   kandev dev [--port <port>]
   kandev start [--port <port>] [--verbose] [--debug]
-  kandev [--version <tag>] [--port <port>] [--verbose] [--debug]
+  kandev [--port <port>] [--verbose] [--debug]
   kandev --dev [--port <port>]
 
 Examples:
@@ -28,16 +27,16 @@ Examples:
   kandev --dev
   kandev dev
   kandev start
-  kandev --version v0.1.0
+  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).
+  run              Use installed runtime bundle (default).
   --dev            Alias for "dev".
-  --version        Release tag to install (default: latest).
+  --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.
@@ -46,11 +45,14 @@ Options:
   --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.
+  --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 findRepoRoot(startDir) {
@@ -77,6 +79,10 @@ function findRepoRoot(startDir) {
 }
 async function main() {
     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;
@@ -109,9 +115,8 @@ async function main() {
         });
         return;
     }
-    await (0, update_1.maybePromptForUpdate)(package_json_1.default.version, process.argv.slice(2));
     await (0, run_1.runRelease)({
-        version: options.version,
+        runtimeVersion: options.runtimeVersion,
         backendPort,
         webPort,
         verbose: options.verbose,

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,12 +189,9 @@ 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,
@@ -196,10 +203,6 @@ function launchReleaseApps(prepared) {
     });
     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,
@@ -226,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);

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/package.json

@@ -1,9 +1,14 @@
 {
   "name": "kandev",
-  "version": "0.17.0",
+  "version": "0.40.0",
   "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.40.0",
+    "@kdlbs/runtime-linux-arm64": "0.40.0",
+    "@kdlbs/runtime-darwin-x64": "0.40.0",
+    "@kdlbs/runtime-darwin-arm64": "0.40.0",
+    "@kdlbs/runtime-win32-x64": "0.40.0"
+  },
   "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
-    }
-}