kandev 0.1.3 → 0.1.5

package/README.md

@@ -1,77 +1,56 @@
-# Kandev Launcher (npx)
+# Kandev
 
-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.
+Manage tasks. Orchestrate agents. Review changes. Ship value.
 
-## 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:
+## Quick Start
 
 ```bash
-KANDEV_NO_UPDATE_PROMPT=1 npx kandev
+npx kandev
 ```
 
-## Usage
+Downloads the latest release, starts the backend + web app, and opens your browser. Data (worktrees, SQLite DB) is stored in `~/.kandev` by default.
 
-```bash
-# Run the latest release bundle
-npx kandev
+## What You Get
 
-# Run a specific release tag
-npx kandev run --version v0.1.0
+- **Multi-agent support** - Claude Code, Codex, GitHub Copilot, Gemini CLI, Amp, Auggie, OpenCode
+- **Integrated workspace** - Terminal, code editor with LSP, git changes, browser preview, and chat
+- **Kanban & pipeline views** - Organize tasks with opinionated workflows and gates
+- **CLI passthrough** - Drop into raw agent TUI mode for full terminal access
+- **Workspace isolation** - Git worktrees prevent concurrent agents from conflicting
+- **Session management** - Resume and review agent conversations
 
-# Local dev (from repo root)
-npx kandev dev
+## Supported Agents
 
+| Agent              | Default Model  | Protocol    |
+| ------------------ | -------------- | ----------- |
+| **Claude Code**    | Sonnet 4.5     | stream-json |
+| **Codex**          | GPT-5.2 Codex  | Codex       |
+| **GitHub Copilot** | GPT-4.1        | Copilot SDK |
+| **Gemini CLI**     | Gemini 3 Flash | ACP         |
+| **Amp**            | Smart Mode     | stream-json |
+| **Auggie**         | Sonnet 4.5     | ACP         |
+| **OpenCode**       | GPT-5 Nano     | REST/SSE    |
 
-# Local test the built CLI (from repo root)
-pnpm -C apps/cli build
-pnpm -C apps/cli start
-```
+> **Beta** - Under active development. Expect rough edges and breaking changes.
 
-## Local Development
+## Requirements
 
-```bash
-pnpm -C apps/cli dev
-```
+- Node.js (for `npx`)
+- Git
+- Docker (optional - needed for container runtimes)
 
-## Build / Publish
+## Platforms
 
-```bash
-pnpm -C apps/cli build
-npm publish --access public
-```
+- macOS (Intel + Apple Silicon)
+- Linux (x64)
+- Windows (x64, WSL)
 
-The published package name is `kandev`, with a bin entry `kandev`.
+## Learn More
 
-## Release
+Open source, multi-provider, no telemetry, not tied to any cloud.
 
-```bash
-scripts/release/publish-launcher.sh 0.1.0
-```
+See the [GitHub repository](https://github.com/kdlbs/kandev) for architecture, vision, development setup, and contributing guidelines.
 
-## Environment Overrides
+## License
 
-- `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.
+[AGPL-3.0](https://github.com/kdlbs/kandev/blob/main/LICENSE)

package/dist/bundle.js

@@ -1,25 +1,57 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractZip = extractZip;
+exports.extractTarGz = extractTarGz;
 exports.ensureExtracted = ensureExtracted;
 exports.findBundleRoot = findBundleRoot;
 exports.resolveWebServerPath = resolveWebServerPath;
-const adm_zip_1 = __importDefault(require("adm-zip"));
+const tar = __importStar(require("tar"));
 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 extractTarGz(archivePath, destDir) {
+    tar.extract({ file: archivePath, cwd: destDir, sync: true });
 }
-function ensureExtracted(zipPath, destDir) {
+function ensureExtracted(archivePath, destDir) {
     const marker = node_path_1.default.join(destDir, ".extracted");
     if (node_fs_1.default.existsSync(marker)) {
         return;
     }
-    extractZip(zipPath, destDir);
+    extractTarGz(archivePath, destDir);
     node_fs_1.default.writeFileSync(marker, "");
 }
 function findBundleRoot(cacheDir) {
@@ -30,13 +62,19 @@ function findBundleRoot(cacheDir) {
     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;
+    // Next.js standalone output location depends on workspace structure:
+    //   - non-monorepo: web/server.js
+    //   - monorepo (apps/ root): web/web/server.js
+    //   - monorepo (project root): web/apps/web/server.js
+    const candidates = [
+        node_path_1.default.join(bundleDir, "web", "server.js"),
+        node_path_1.default.join(bundleDir, "web", "web", "server.js"),
+        node_path_1.default.join(bundleDir, "web", "apps", "web", "server.js"),
+    ];
+    for (const candidate of candidates) {
+        if (node_fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
     }
     return null;
 }

package/dist/cli.js

@@ -8,6 +8,7 @@ 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 start_1 = require("./start");
 const ports_1 = require("./ports");
 const update_1 = require("./update");
 function printHelp() {
@@ -16,6 +17,7 @@ function printHelp() {
 Usage:
   kandev run [--version <tag>] [--backend-port <port>] [--web-port <port>]
   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>]
   kandev --dev [--backend-port <port>] [--web-port <port>]
 
@@ -24,16 +26,20 @@ Examples:
   kandev run
   kandev --dev
   kandev dev
+  kandev start
   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.
+  start           Use local production build (make build + next start).
   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.
+  --verbose, -v    Show info logs from backend + web (start mode only).
+  --debug          Show debug logs + agent message dumps (start mode only).
   --help, -h       Show help.
 `);
 }
@@ -45,7 +51,7 @@ function parseArgs(argv) {
             printHelp();
             process.exit(0);
         }
-        if (arg === "dev" || arg === "run") {
+        if (arg === "dev" || arg === "run" || arg === "start") {
             opts.command = arg;
             continue;
         }
@@ -80,6 +86,14 @@ function parseArgs(argv) {
             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;
 }
@@ -117,6 +131,14 @@ async function main() {
         await (0, dev_1.runDev)({ repoRoot, backendPort, webPort });
         return;
     }
+    if (raw.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 });
+        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 });
 }

package/dist/constants.js

@@ -3,19 +3,21 @@ 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;
+exports.DATA_DIR = exports.CACHE_DIR = 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;
 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;
+exports.DEFAULT_MCP_PORT = 9090;
 // 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;
+exports.HEALTH_TIMEOUT_MS_RELEASE = 15000;
+exports.HEALTH_TIMEOUT_MS_DEV = 60000;
 // 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

@@ -8,42 +8,27 @@ 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 shared_1 = require("./shared");
 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 ports = await (0, shared_1.pickPorts)(backendPort, webPort);
+    const backendEnv = (0, shared_1.buildBackendEnv)({ ports, extra: { KANDEV_MOCK_AGENT: "true" } });
+    const webEnv = (0, shared_1.buildWebEnv)({ ports, includeMcp: true, debug: true });
+    (0, shared_1.logPortConfig)("dev", "using local repo", ports, true);
     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));
+    const backendProc = (0, node_child_process_1.spawn)("make", ["-C", node_path_1.default.join("apps", "backend"), "dev"], {
+        cwd: repoRoot,
+        env: backendEnv,
+        stdio: "inherit",
     });
-    await (0, health_1.waitForHealth)(backendUrl, backendProc, constants_1.HEALTH_TIMEOUT_MS);
-    console.log(`[kandev] backend ready at ${backendUrl}`);
-    const webUrl = `http://localhost:${actualWebPort}`;
+    supervisor.children.push(backendProc);
+    (0, shared_1.attachBackendExitHandler)(backendProc, supervisor);
+    const healthTimeoutMs = (0, health_1.resolveHealthTimeoutMs)(constants_1.HEALTH_TIMEOUT_MS_DEV);
+    await (0, health_1.waitForHealth)(ports.backendUrl, backendProc, healthTimeoutMs);
+    console.log(`[kandev] backend ready at ${ports.backendUrl}`);
+    const webUrl = `http://localhost:${ports.webPort}`;
     (0, web_1.launchWebApp)({
         command: "pnpm",
         args: ["-C", "apps", "--filter", "@kandev/web", "dev"],

package/dist/github.js

@@ -10,7 +10,7 @@ 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 OWNER = process.env.KANDEV_GITHUB_OWNER || "kdlbs";
 const REPO = process.env.KANDEV_GITHUB_REPO || "kandev";
 const API_BASE = `https://api.github.com/repos/${OWNER}/${REPO}`;
 function requestJson(url) {
@@ -55,15 +55,21 @@ function downloadFile(url, destPath, expectedSha256, onProgress) {
             }
             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) => {
+        const handleResponse = (res) => {
+            // Follow redirects (GitHub API returns 302 to signed S3 URL).
+            // Strip auth header on redirect to avoid S3 rejecting it.
+            if ((res.statusCode === 301 || res.statusCode === 302) && res.headers.location) {
+                const redirectReq = node_https_1.default.get(res.headers.location, { headers: { "User-Agent": "kandev-npx" } }, handleResponse);
+                redirectReq.setTimeout(30000, () => {
+                    redirectReq.destroy(new Error(`Request timed out downloading ${url}`));
+                });
+                redirectReq.on("error", (err) => {
+                    file.close();
+                    cleanup();
+                    reject(err);
+                });
+                return;
+            }
             if (res.statusCode !== 200) {
                 file.close();
                 cleanup();
@@ -94,8 +100,17 @@ function downloadFile(url, destPath, expectedSha256, onProgress) {
                     reject(err);
                 }
             });
-        });
-        req.setTimeout(5000, () => {
+        };
+        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}` }
+                    : {}),
+            },
+        }, handleResponse);
+        req.setTimeout(30000, () => {
             req.destroy(new Error(`Request timed out downloading ${url}`));
         });
         req.on("error", (err) => {
@@ -114,7 +129,7 @@ function readSha256(pathToSha) {
     }
     const content = node_fs_1.default.readFileSync(pathToSha, "utf8").trim();
     const first = content.split(/\s+/)[0];
-    return first || null;
+    return first?.toLowerCase() || null;
 }
 async function getRelease(version) {
     if (version) {
@@ -134,7 +149,7 @@ async function ensureAsset(release, assetName, cacheDir, onProgress) {
     if (!expectedSha) {
         const shaAsset = findAsset(release, `${assetName}.sha256`);
         if (shaAsset) {
-            await downloadFile(shaAsset.browser_download_url, shaPath);
+            await downloadFile(shaAsset.url, shaPath);
             expectedSha = readSha256(shaPath);
         }
     }
@@ -150,6 +165,6 @@ async function ensureAsset(release, assetName, cacheDir, onProgress) {
         }
         node_fs_1.default.unlinkSync(destPath);
     }
-    await downloadFile(asset.browser_download_url, destPath, expectedSha, onProgress);
+    await downloadFile(asset.url, destPath, expectedSha, onProgress);
     return destPath;
 }

package/dist/health.js

@@ -1,10 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.delay = delay;
+exports.resolveHealthTimeoutMs = resolveHealthTimeoutMs;
 exports.waitForHealth = waitForHealth;
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Resolves the health check timeout, allowing override via environment variable.
+ *
+ * The KANDEV_HEALTH_TIMEOUT_MS environment variable can override the default
+ * timeout for waiting on backend health checks. This is useful for slower
+ * machines or debugging scenarios where the backend takes longer to start.
+ *
+ * @param defaultMs - Default timeout in milliseconds if env var is not set
+ * @returns The resolved timeout in milliseconds
+ */
+function resolveHealthTimeoutMs(defaultMs) {
+    const raw = process.env.KANDEV_HEALTH_TIMEOUT_MS;
+    if (!raw) {
+        return defaultMs;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return defaultMs;
+    }
+    return Math.floor(parsed);
+}
 async function waitForHealth(baseUrl, proc, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     const healthUrl = `${baseUrl}/health`;

package/dist/platform.js

@@ -38,13 +38,16 @@ function getPlatformDir() {
     const arch = getEffectiveArch();
     if (platform === "linux" && arch === "x64")
         return "linux-x64";
+    if (platform === "linux" && arch === "arm64")
+        return "linux-arm64";
     if (platform === "darwin" && arch === "x64")
         return "macos-x64";
     if (platform === "darwin" && arch === "arm64")
         return "macos-arm64";
     if (platform === "win32" && arch === "x64")
         return "windows-x64";
+    // Windows ARM64 runs x64 binaries via emulation — no native arm64 build yet
     if (platform === "win32" && arch === "arm64")
-        return "windows-arm64";
+        return "windows-x64";
     throw new Error(`Unsupported platform: ${platform}-${arch}`);
 }

package/dist/ports.js

@@ -18,23 +18,39 @@ function ensureValidPort(port, name) {
     }
     return port;
 }
-function isPortAvailable(port, host = "0.0.0.0") {
+/**
+ * Tries to connect to a port on the given host. Returns true if something
+ * is already listening (i.e. the port is in use).
+ *
+ * This is more reliable than a bind-based check on macOS where
+ * SO_REUSEADDR (set by default in Node.js) can allow a bind to succeed
+ * even when another process is already listening on the same port.
+ */
+function isPortInUse(port, host) {
     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);
-            }
+        const socket = node_net_1.default.createConnection({ port, host });
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
         });
-        server.listen(port, host, () => {
-            server.close(() => resolve(true));
+        socket.once("error", () => {
+            resolve(false);
         });
     });
 }
+/**
+ * Checks if a port is available by probing both IPv4 and IPv6 loopback.
+ *
+ * Uses a connect-based check: if we can connect to the port on either
+ * 127.0.0.1 or ::1, something is already listening and the port is taken.
+ */
+async function isPortAvailable(port) {
+    const [v4InUse, v6InUse] = await Promise.all([
+        isPortInUse(port, "127.0.0.1"),
+        isPortInUse(port, "::1"),
+    ]);
+    return !v4InUse && !v6InUse;
+}
 async function reserveSpecificPort(port, host = "127.0.0.1") {
     return new Promise((resolve) => {
         const server = node_net_1.default.createServer();
@@ -55,15 +71,19 @@ async function pickAvailablePort(preferred, retries = constants_1.RANDOM_PORT_RE
     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())),
-        };
+    if (await isPortAvailable(preferred)) {
+        const reservedPreferred = await reserveSpecificPort(preferred);
+        if (reservedPreferred) {
+            return {
+                port: preferred,
+                release: () => new Promise((resolve) => reservedPreferred.close(() => resolve())),
+            };
+        }
     }
     for (let i = 0; i < retries; i += 1) {
         const candidate = node_crypto_1.default.randomInt(constants_1.RANDOM_PORT_MIN, constants_1.RANDOM_PORT_MAX + 1);
+        if (!(await isPortAvailable(candidate)))
+            continue;
         const reserved = await reserveSpecificPort(candidate);
         if (reserved) {
             return {

package/dist/process.js

@@ -5,24 +5,85 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createProcessSupervisor = createProcessSupervisor;
 const tree_kill_1 = __importDefault(require("tree-kill"));
+const SHUTDOWN_TIMEOUT_MS = 10000;
 function createProcessSupervisor() {
-    let shuttingDown = false;
+    let shutdownPromise = null;
     const children = [];
     const shutdown = async (reason) => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
+        // If already shutting down, wait for the existing shutdown to complete
+        if (shutdownPromise) {
+            return shutdownPromise;
+        }
         console.log(`[kandev] shutting down (${reason})...`);
-        await Promise.all(children
+        // Wait for all child processes to actually exit, not just for signal to be sent
+        shutdownPromise = Promise.all(children
             .filter((child) => child.pid)
-            .map((child) => new Promise((resolve) => (0, tree_kill_1.default)(child.pid, "SIGTERM", () => resolve()))));
+            .map((child) => waitForProcessExit(child, SHUTDOWN_TIMEOUT_MS))).then(() => { });
+        return shutdownPromise;
     };
     const onSignal = (signal) => {
         void shutdown(`signal ${signal}`).then(() => process.exit(0));
     };
     const attachSignalHandlers = () => {
         process.on("SIGINT", onSignal);
-        process.on("SIGTERM", onSignal);
+        // SIGTERM is not available on Windows — only attach where supported
+        if (process.platform !== "win32") {
+            process.on("SIGTERM", onSignal);
+        }
     };
     return { children, shutdown, attachSignalHandlers };
 }
+/**
+ * Terminate a process and wait for it to exit.
+ * On Unix: sends SIGTERM, falls back to SIGKILL after timeout.
+ * On Windows: tree-kill uses taskkill (no SIGTERM/SIGKILL distinction).
+ */
+function waitForProcessExit(child, timeoutMs) {
+    const isWindows = process.platform === "win32";
+    return new Promise((resolve) => {
+        const pid = child.pid;
+        // Check if this is a ChildProcess with exit event support
+        const proc = child;
+        const hasExitEvent = typeof proc.on === "function" && typeof proc.exitCode !== "undefined";
+        // If process already exited, resolve immediately
+        if (hasExitEvent && proc.exitCode !== null) {
+            resolve();
+            return;
+        }
+        let resolved = false;
+        const done = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            resolve();
+        };
+        // Set up timeout for force-kill fallback
+        const timeout = setTimeout(() => {
+            console.log(`[kandev] process ${pid} did not exit in time, force killing`);
+            // On Windows, tree-kill always force-kills (no signal distinction)
+            // On Unix, escalate to SIGKILL
+            (0, tree_kill_1.default)(pid, isWindows ? undefined : "SIGKILL", done);
+        }, timeoutMs);
+        // Listen for exit event if available
+        if (hasExitEvent) {
+            proc.once("exit", () => {
+                clearTimeout(timeout);
+                done();
+            });
+        }
+        // Graceful termination: SIGTERM on Unix, default kill on Windows
+        (0, tree_kill_1.default)(pid, isWindows ? undefined : "SIGTERM", (err) => {
+            // If kill fails (process already gone), we're done
+            if (err) {
+                clearTimeout(timeout);
+                done();
+            }
+            // If no exit event support, resolve after a brief delay
+            // (tree-kill callback fires when signal sent, not when process exits)
+            if (!hasExitEvent) {
+                // For non-ChildProcess objects, we can't wait for exit event
+                // Just wait for the timeout
+            }
+        });
+    });
+}

package/dist/run.js

@@ -15,21 +15,22 @@ const health_1 = require("./health");
 const platform_1 = require("./platform");
 const ports_1 = require("./ports");
 const process_1 = require("./process");
+const shared_1 = require("./shared");
 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 assetName = `kandev-${platformDir}.tar.gz`;
     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 archivePath = 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);
+    (0, bundle_1.ensureExtracted)(archivePath, 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)) {
@@ -45,19 +46,23 @@ async function prepareReleaseBundle({ version, backendPort, webPort, }) {
     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");
+    // Note: Release mode doesn't configure MCP server ports as it uses
+    // the bundled configuration. Only backend and agentctl ports are set.
+    // Log level is set to warn for clean production output.
     const backendEnv = {
         ...process.env,
         KANDEV_SERVER_PORT: String(actualBackendPort),
         KANDEV_AGENT_STANDALONE_PORT: String(agentctlPort),
-        KANDEV_DB_PATH: dbPath,
+        KANDEV_DATABASE_PATH: dbPath,
+        KANDEV_LOG_LEVEL: "warn",
     };
     const webEnv = {
         ...process.env,
         KANDEV_API_BASE_URL: backendUrl,
         NEXT_PUBLIC_KANDEV_API_BASE_URL: backendUrl,
         PORT: String(actualWebPort),
-        NODE_ENV: "production",
     };
+    webEnv.NODE_ENV = "production";
     return {
         bundleDir,
         backendBin,
@@ -80,16 +85,13 @@ function launchReleaseApps(prepared) {
         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));
-    });
+    (0, shared_1.attachBackendExitHandler)(backendProc, supervisor);
     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)({
+    (0, web_1.launchWebApp)({
         command: "node",
         args: [webServerPath],
         cwd: node_path_1.default.dirname(webServerPath),
@@ -104,7 +106,8 @@ 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);
+    const healthTimeoutMs = (0, health_1.resolveHealthTimeoutMs)(constants_1.HEALTH_TIMEOUT_MS_RELEASE);
+    await (0, health_1.waitForHealth)(prepared.backendUrl, backendProc, healthTimeoutMs);
     console.log(`[kandev] backend ready at ${prepared.backendUrl}`);
     console.log(`[kandev] web ready at http://localhost:${prepared.webPort}`);
 }

package/dist/shared.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Shared utilities for CLI commands (dev, start, run).
+ *
+ * This module extracts common patterns used across different launch modes
+ * to reduce duplication and ensure consistent behavior.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickPorts = pickPorts;
+exports.buildBackendEnv = buildBackendEnv;
+exports.buildWebEnv = buildWebEnv;
+exports.logPortConfig = logPortConfig;
+exports.attachBackendExitHandler = attachBackendExitHandler;
+const constants_1 = require("./constants");
+const ports_1 = require("./ports");
+/**
+ * Picks available ports for all services, using provided values or finding free ports.
+ *
+ * @param backendPort - Optional preferred backend port
+ * @param webPort - Optional preferred web port
+ * @returns Resolved ports for all services
+ */
+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`,
+    };
+}
+/**
+ * Builds environment variables for the backend process.
+ *
+ * @param options - Configuration options for the backend environment
+ * @returns Environment object for the backend process
+ */
+function buildBackendEnv(options) {
+    const { ports, logLevel, extra } = options;
+    return {
+        ...process.env,
+        KANDEV_SERVER_PORT: String(ports.backendPort),
+        KANDEV_AGENT_STANDALONE_PORT: String(ports.agentctlPort),
+        KANDEV_AGENT_MCP_SERVER_PORT: String(ports.mcpPort),
+        ...(logLevel ? { KANDEV_LOG_LEVEL: logLevel } : {}),
+        ...extra,
+    };
+}
+/**
+ * Builds environment variables for the web process.
+ *
+ * @param options - Configuration options for the web environment
+ * @returns Environment object for the web process
+ */
+function buildWebEnv(options) {
+    const { ports, includeMcp = false, production = false, debug = false } = options;
+    // Server-side env vars use localhost (SSR runs on same machine as backend)
+    // Client-side uses NEXT_PUBLIC_*_PORT to build URLs dynamically from window.location.hostname
+    // This allows accessing the app from any device (iPhone, Tailscale, etc.)
+    const env = {
+        ...process.env,
+        // Server-side: full localhost URL for SSR
+        KANDEV_API_BASE_URL: ports.backendUrl,
+        // Client-side: only pass ports, client builds URL from current hostname
+        NEXT_PUBLIC_KANDEV_API_PORT: String(ports.backendPort),
+        PORT: String(ports.webPort),
+    };
+    if (includeMcp) {
+        env.KANDEV_MCP_SERVER_URL = ports.mcpUrl;
+        env.NEXT_PUBLIC_KANDEV_MCP_PORT = String(ports.mcpPort);
+    }
+    if (production) {
+        env.NODE_ENV = "production";
+    }
+    if (debug) {
+        env.NEXT_PUBLIC_KANDEV_DEBUG = "true";
+    }
+    return env;
+}
+/**
+ * Logs port configuration to the console.
+ *
+ * @param mode - The launch mode name (e.g., "dev", "production", "release")
+ * @param modeDescription - Human-readable description of the mode
+ * @param ports - Port configuration to log
+ * @param includeMcp - Whether to log MCP-related ports
+ */
+function logPortConfig(mode, modeDescription, ports, includeMcp = false) {
+    console.log(`[kandev] ${mode} mode: ${modeDescription}`);
+    console.log("[kandev] backend port:", ports.backendPort);
+    console.log("[kandev] web port:", ports.webPort);
+    console.log("[kandev] agentctl port:", ports.agentctlPort);
+    if (includeMcp) {
+        console.log("[kandev] mcp port:", ports.mcpPort);
+        console.log("[kandev] mcp url:", ports.mcpUrl);
+    }
+}
+/**
+ * Attaches a standardized exit handler to a backend process.
+ *
+ * When the backend exits, this handler logs the exit reason and triggers
+ * a graceful shutdown of all supervised processes. If the process was
+ * killed by a signal, it exits with code 0; otherwise it uses the
+ * process exit code (defaulting to 1).
+ *
+ * @param backendProc - The backend child process
+ * @param supervisor - The process supervisor managing child processes
+ */
+function attachBackendExitHandler(backendProc, supervisor) {
+    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));
+    });
+}

package/dist/start.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Production start command for running local builds.
+ *
+ * This module implements the `kandev start` command, which runs the locally
+ * built backend binary and web app in production mode. Unlike `kandev dev`
+ * which uses hot-reloading, this runs the optimized production builds.
+ *
+ * Prerequisites:
+ * - Backend must be built: `make build-backend`
+ * - Web app must be built: `make build-web`
+ * - Or simply: `make build` (builds both)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStart = runStart;
+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 constants_1 = require("./constants");
+const health_1 = require("./health");
+const platform_1 = require("./platform");
+const process_1 = require("./process");
+const shared_1 = require("./shared");
+const web_1 = require("./web");
+/**
+ * Runs the application in production mode using local builds.
+ *
+ * This function:
+ * 1. Validates that build artifacts exist
+ * 2. Picks available ports for all services
+ * 3. Starts the backend binary (with warn log level for clean output)
+ * 4. Starts the web app via `pnpm start`
+ * 5. Waits for the backend to be healthy before announcing readiness
+ *
+ * @param options - Configuration for the start command
+ * @throws Error if backend binary or web build is not found
+ */
+async function runStart({ repoRoot, backendPort, webPort, verbose = false, debug = false, }) {
+    const ports = await (0, shared_1.pickPorts)(backendPort, webPort);
+    const backendBin = node_path_1.default.join(repoRoot, "apps", "backend", "bin", (0, platform_1.getBinaryName)("kandev"));
+    if (!node_fs_1.default.existsSync(backendBin)) {
+        throw new Error("Backend binary not found. Run `make build` first.");
+    }
+    // Check for standalone build (Next.js standalone output)
+    const webServerPath = node_path_1.default.join(repoRoot, "apps", "web", ".next", "standalone", "web", "server.js");
+    if (!node_fs_1.default.existsSync(webServerPath)) {
+        throw new Error("Web standalone build not found. Run `make build` first.");
+    }
+    const webStandaloneDir = node_path_1.default.dirname(webServerPath);
+    const webStaticDir = node_path_1.default.join(repoRoot, "apps", "web", ".next", "static");
+    const standaloneStaticDir = node_path_1.default.join(webStandaloneDir, ".next", "static");
+    if (node_fs_1.default.existsSync(webStaticDir) && !node_fs_1.default.existsSync(standaloneStaticDir)) {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(standaloneStaticDir), { recursive: true });
+        try {
+            node_fs_1.default.symlinkSync(webStaticDir, standaloneStaticDir, "junction");
+        }
+        catch (err) {
+            console.warn(`[kandev] failed to link Next.js static assets: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Link public directory (fonts, images, etc.) into standalone output
+    const webPublicDir = node_path_1.default.join(repoRoot, "apps", "web", "public");
+    const standalonePublicDir = node_path_1.default.join(webStandaloneDir, "public");
+    if (node_fs_1.default.existsSync(webPublicDir) && !node_fs_1.default.existsSync(standalonePublicDir)) {
+        try {
+            node_fs_1.default.symlinkSync(webPublicDir, standalonePublicDir, "junction");
+        }
+        catch (err) {
+            console.warn(`[kandev] failed to link public assets: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Production mode: use warn log level for clean output unless verbose/debug
+    const showOutput = verbose || debug;
+    const dbPath = node_path_1.default.join(constants_1.DATA_DIR, "kandev.db");
+    const backendEnv = (0, shared_1.buildBackendEnv)({
+        ports,
+        logLevel: debug ? "debug" : verbose ? "info" : "warn",
+        extra: {
+            KANDEV_DATABASE_PATH: dbPath,
+            ...(debug ? { KANDEV_DEBUG_AGENT_MESSAGES: "true" } : {}),
+        },
+    });
+    const webEnv = (0, shared_1.buildWebEnv)({ ports, includeMcp: true, production: true, debug });
+    const supervisor = (0, process_1.createProcessSupervisor)();
+    supervisor.attachSignalHandlers();
+    // Start backend with piped stdio (quiet mode unless verbose/debug)
+    const backendProc = (0, node_child_process_1.spawn)(backendBin, [], {
+        cwd: node_path_1.default.dirname(backendBin),
+        env: backendEnv,
+        stdio: showOutput ? ["ignore", "inherit", "inherit"] : ["ignore", "pipe", "pipe"],
+    });
+    supervisor.children.push(backendProc);
+    // Forward stderr only (warnings/errors) when quiet
+    if (!showOutput) {
+        backendProc.stderr?.pipe(process.stderr);
+    }
+    (0, shared_1.attachBackendExitHandler)(backendProc, supervisor);
+    const healthTimeoutMs = (0, health_1.resolveHealthTimeoutMs)(constants_1.HEALTH_TIMEOUT_MS_RELEASE);
+    await (0, health_1.waitForHealth)(ports.backendUrl, backendProc, healthTimeoutMs);
+    // Use standalone server.js directly (not pnpm start)
+    const webUrl = `http://localhost:${ports.webPort}`;
+    (0, web_1.launchWebApp)({
+        command: "node",
+        args: [webServerPath],
+        cwd: webStandaloneDir,
+        env: webEnv,
+        url: webUrl,
+        supervisor,
+        label: "web",
+        quiet: !showOutput,
+    });
+    // Print clean summary
+    console.log("");
+    console.log("[kandev] Server started successfully");
+    console.log("");
+    console.log(`  Web:      ${webUrl}`);
+    console.log(`  API:      ${ports.backendUrl}`);
+    console.log(`  MCP:      ${ports.mcpUrl}`);
+    console.log(`  Database: ${dbPath}`);
+    console.log("");
+}

package/dist/update.js

@@ -60,7 +60,9 @@ function promptYesNo(question, defaultYes = false) {
         const suffix = defaultYes ? "[Y/n]" : "[y/N]";
         rl.question(`${question} ${suffix} `, (answer) => {
             rl.close();
-            const normalized = String(answer || "").trim().toLowerCase();
+            const normalized = String(answer || "")
+                .trim()
+                .toLowerCase();
             if (!normalized) {
                 resolve(Boolean(defaultYes));
                 return;

package/dist/web.js

@@ -3,32 +3,46 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.openBrowser = openBrowser;
 exports.launchWebApp = launchWebApp;
 const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+let _isWSL;
+function isWSL() {
+    if (_isWSL === undefined) {
+        try {
+            _isWSL = (0, node_fs_1.readFileSync)("/proc/version", "utf8").toLowerCase().includes("microsoft");
+        }
+        catch {
+            _isWSL = false;
+        }
+    }
+    return _isWSL;
+}
 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];
+    const useCmd = process.platform === "win32" || isWSL();
+    const opener = process.platform === "darwin" ? "open" : useCmd ? "cmd.exe" : "xdg-open";
+    const args = useCmd ? ["/c", "start", "", url] : [url];
     try {
         const child = (0, node_child_process_1.spawn)(opener, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { }); // ignore async spawn errors (e.g. xdg-open missing)
         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" });
+function launchWebApp({ command, args, cwd, env, url, supervisor, label, quiet = false, }) {
+    const stdio = quiet ? ["ignore", "pipe", "pipe"] : "inherit";
+    const proc = (0, node_child_process_1.spawn)(command, args, { cwd, env, stdio });
     supervisor.children.push(proc);
+    // In quiet mode, only forward stderr
+    if (quiet && proc.stderr) {
+        proc.stderr.pipe(process.stderr);
+    }
     proc.on("exit", (code, signal) => {
         console.error(`[kandev] ${label} exited (code=${code}, signal=${signal})`);
-        const exitCode = signal ? 0 : code ?? 1;
+        const exitCode = signal ? 0 : (code ?? 1);
         void supervisor.shutdown(`${label} exit`).then(() => process.exit(exitCode));
     });
     openBrowser(url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kandev",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": false,
   "description": "NPX launcher for Kandev",
   "license": "UNLICENSED",
@@ -14,11 +14,10 @@
     "dist"
   ],
   "dependencies": {
-    "adm-zip": "^0.5.16",
+    "tar": "^7.5.0",
     "tree-kill": "^1.2.2"
   },
   "devDependencies": {
-    "@types/adm-zip": "^0.5.7",
     "@types/node": "^20",
     "tsx": "^4.15.7",
     "typescript": "^5"