kandev 0.10.0 → 0.12.0

package/dist/cli.js

@@ -15,10 +15,10 @@ function printHelp() {
     console.log(`kandev launcher
 
 Usage:
-  kandev run [--version <tag>] [--backend-port <port>] [--web-port <port>]
+  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>]
+  kandev [--version <tag>] [--backend-port <port>] [--web-port <port>] [--verbose] [--debug]
   kandev --dev [--backend-port <port>] [--web-port <port>]
 
 Examples:
@@ -29,6 +29,7 @@ Examples:
   kandev start
   kandev --version v0.1.0
   kandev --backend-port 18080 --web-port 13000
+  kandev --debug
 
 Options:
   dev             Use local repo for dev (make dev + next dev) if available.
@@ -38,8 +39,8 @@ Options:
   --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).
-  --verbose, -v    Show info logs from backend + web (start mode only).
-  --debug          Show debug logs + agent message dumps (start mode only).
+  --verbose, -v    Show info logs from backend + web.
+  --debug          Show debug logs + agent message dumps.
   --help, -h       Show help.
 `);
 }
@@ -144,7 +145,13 @@ async function main() {
         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 });
+    await (0, run_1.runRelease)({
+        version: raw.version,
+        backendPort,
+        webPort,
+        verbose: raw.verbose,
+        debug: raw.debug,
+    });
 }
 main().catch((err) => {
     console.error(`[kandev] ${err instanceof Error ? err.message : String(err)}`);

package/dist/constants.js

@@ -16,7 +16,7 @@ exports.RANDOM_PORT_MIN = 10000;
 exports.RANDOM_PORT_MAX = 60000;
 exports.RANDOM_PORT_RETRIES = 10;
 // Backend healthcheck timeout during startup.
-exports.HEALTH_TIMEOUT_MS_RELEASE = 15000;
+exports.HEALTH_TIMEOUT_MS_RELEASE = 45000;
 exports.HEALTH_TIMEOUT_MS_DEV = 600000;
 // 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");

package/dist/dev.js

@@ -13,10 +13,11 @@ const shared_1 = require("./shared");
 const web_1 = require("./web");
 async function runDev({ repoRoot, backendPort, webPort }) {
     const ports = await (0, shared_1.pickPorts)(backendPort, webPort);
-    const dbPath = node_path_1.default.join(repoRoot, "apps", "backend", "kandev.db");
+    const dbPath = process.env.KANDEV_DATABASE_PATH || node_path_1.default.join(repoRoot, "apps", "backend", "kandev.db");
     const extra = {
         KANDEV_DATABASE_PATH: dbPath,
         KANDEV_MOCK_AGENT: process.env.KANDEV_MOCK_AGENT || "true",
+        KANDEV_DEBUG_PPROF_ENABLED: "true",
     };
     const backendEnv = (0, shared_1.buildBackendEnv)({ ports, extra });
     const webEnv = (0, shared_1.buildWebEnv)({ ports, debug: true });

package/dist/health.js

@@ -28,12 +28,13 @@ function resolveHealthTimeoutMs(defaultMs) {
     }
     return Math.floor(parsed);
 }
-async function waitForHealth(baseUrl, proc, timeoutMs) {
+async function waitForHealth(baseUrl, proc, timeoutMs, onFailure) {
     const deadline = Date.now() + timeoutMs;
     const healthUrl = `${baseUrl}/health`;
     while (Date.now() < deadline) {
         if (proc.exitCode !== null) {
-            throw new Error("Backend exited before healthcheck passed");
+            onFailure?.();
+            throw new Error(`Backend exited (code ${proc.exitCode}) before healthcheck passed`);
         }
         try {
             const res = await fetch(healthUrl);
@@ -46,7 +47,10 @@ async function waitForHealth(baseUrl, proc, timeoutMs) {
         }
         await delay(300);
     }
-    throw new Error(`Backend healthcheck timed out after ${timeoutMs}ms`);
+    onFailure?.();
+    throw new Error(`Backend healthcheck timed out after ${timeoutMs}ms at ${healthUrl}. ` +
+        `If your machine is slow on first run (antivirus scan, cold disk), ` +
+        `set KANDEV_HEALTH_TIMEOUT_MS=120000 and retry.`);
 }
 async function waitForUrlReady(url, proc, timeoutMs) {
     const deadline = Date.now() + timeoutMs;

package/dist/run.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findCachedRelease = findCachedRelease;
 exports.cleanOldReleases = cleanOldReleases;
+exports.attachRingBuffer = attachRingBuffer;
 exports.runRelease = runRelease;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -76,7 +77,7 @@ function cleanOldReleases(currentTag) {
         // Non-critical — don't fail the launch if cleanup errors.
     }
 }
-async function prepareReleaseBundle({ version, backendPort, webPort, }) {
+async function prepareReleaseBundle({ version, backendPort, webPort, verbose = false, debug = false, }) {
     const platformDir = (0, platform_1.getPlatformDir)();
     let tag;
     let cacheDir;
@@ -122,13 +123,14 @@ async function prepareReleaseBundle({ version, backendPort, webPort, }) {
     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 logLevel = process.env.KANDEV_LOG_LEVEL?.trim() || "warn";
+    const showOutput = verbose || debug;
+    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.
+    // via KANDEV_LOG_LEVEL or --verbose/--debug flags.
     const backendEnv = {
         ...process.env,
         KANDEV_SERVER_PORT: String(actualBackendPort),
@@ -136,11 +138,15 @@ async function prepareReleaseBundle({ version, backendPort, webPort, }) {
         KANDEV_AGENT_STANDALONE_PORT: String(agentctlPort),
         KANDEV_DATABASE_PATH: dbPath,
         KANDEV_LOG_LEVEL: logLevel,
+        ...(debug ? { KANDEV_DEBUG_AGENT_MESSAGES: "true", KANDEV_DEBUG_PPROF_ENABLED: "true" } : {}),
     };
     const webEnv = {
         ...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";
     return {
@@ -155,8 +161,24 @@ async function prepareReleaseBundle({ version, backendPort, webPort, }) {
         agentctlPort,
         dbPath,
         logLevel,
+        showOutput,
     };
 }
+/**
+ * Attach a ring buffer to a readable stream, keeping roughly the last `maxChars`
+ * characters. Note: the limit is measured in JS string length (UTF-16 code units),
+ * not bytes — fine for log output which is overwhelmingly ASCII.
+ */
+function attachRingBuffer(stream, maxChars = 64 * 1024) {
+    let buf = "";
+    stream?.on("data", (chunk) => {
+        buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        if (buf.length > maxChars) {
+            buf = buf.slice(buf.length - maxChars);
+        }
+    });
+    return () => buf;
+}
 function launchReleaseApps(prepared) {
     const releaseSource = prepared.requestedVersion
         ? `(requested: ${prepared.requestedVersion})`
@@ -176,25 +198,42 @@ 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,
-        stdio: "inherit",
+        stdio: prepared.showOutput ? ["ignore", "inherit", "inherit"] : ["ignore", "pipe", "inherit"],
     });
     supervisor.children.push(backendProc);
+    const readBuffered = prepared.showOutput ? () => "" : attachRingBuffer(backendProc.stdout);
+    let dumped = false;
+    const dumpBackendLogs = () => {
+        if (dumped)
+            return;
+        dumped = true;
+        const buffered = readBuffered();
+        if (buffered.trim().length === 0)
+            return;
+        console.error("[kandev] --- backend stdout (last captured output) ---");
+        console.error(buffered.trimEnd());
+        console.error("[kandev] --- end backend stdout ---");
+    };
     (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");
     }
-    return { supervisor, backendProc, webServerPath };
+    return { supervisor, backendProc, webServerPath, dumpBackendLogs };
 }
-async function runRelease({ version, backendPort, webPort }) {
-    const prepared = await prepareReleaseBundle({ version, backendPort, webPort });
-    const { supervisor, backendProc, webServerPath } = launchReleaseApps(prepared);
+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);
     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);
+    await (0, health_1.waitForHealth)(prepared.backendUrl, backendProc, healthTimeoutMs, dumpBackendLogs);
     console.log(`[kandev] backend ready at ${prepared.backendUrl}`);
     const webUrl = `http://localhost:${prepared.webPort}`;
     console.log("[kandev] starting web...");
@@ -205,7 +244,7 @@ async function runRelease({ version, backendPort, webPort }) {
         env: prepared.webEnv,
         supervisor,
         label: "web",
-        quiet: true,
+        quiet: !prepared.showOutput,
     });
     await (0, health_1.waitForUrlReady)(webUrl, webProc, healthTimeoutMs);
     console.log("[kandev] ready at " + prepared.backendUrl);

package/dist/shared.js

@@ -68,6 +68,9 @@ function buildWebEnv(options) {
         // In production, the backend reverse-proxies Next.js so the client uses same-origin.
         NEXT_PUBLIC_KANDEV_API_PORT: String(ports.backendPort),
         PORT: String(ports.webPort),
+        // 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",
     };
     if (production) {
         env.NODE_ENV = "production";

package/dist/start.js

@@ -81,7 +81,7 @@ async function runStart({ repoRoot, backendPort, webPort, verbose = false, debug
         logLevel,
         extra: {
             KANDEV_DATABASE_PATH: dbPath,
-            ...(debug ? { KANDEV_DEBUG_AGENT_MESSAGES: "true" } : {}),
+            ...(debug ? { KANDEV_DEBUG_AGENT_MESSAGES: "true", KANDEV_DEBUG_PPROF_ENABLED: "true" } : {}),
         },
     });
     const webEnv = (0, shared_1.buildWebEnv)({ ports, production: true, debug });
@@ -93,17 +93,14 @@ async function runStart({ repoRoot, backendPort, webPort, verbose = false, debug
     });
     const supervisor = (0, process_1.createProcessSupervisor)();
     supervisor.attachSignalHandlers();
-    // Start backend with piped stdio (quiet mode unless verbose/debug)
+    // Start backend: ignore stdin, show stdout only in verbose/debug mode, always show stderr
+    // Stderr is always inherited to ensure error messages are visible immediately (no pipe buffering)
     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"],
+        stdio: showOutput ? ["ignore", "inherit", "inherit"] : ["ignore", "ignore", "inherit"],
     });
     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);
     console.log("[kandev] starting backend...");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kandev",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "private": false,
   "description": "NPX launcher for Kandev",
   "license": "AGPL-3.0-only",
@@ -14,7 +14,7 @@
     "dist"
   ],
   "dependencies": {
-    "tar": "^7.5.10",
+    "tar": "^7.5.11",
     "tree-kill": "^1.2.2"
   },
   "devDependencies": {