feat: add make start-debug

apps/cli/src/cli.ts

@@ -16,6 +16,7 @@ type CliOptions = {
   backendPort?: number;
   webPort?: number;
   verbose?: boolean;
+  debug?: boolean;
 };
 
 function printHelp() {
@@ -24,7 +25,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]
+  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>]
 
@@ -46,6 +47,7 @@ Options:
   --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.
 `);
 }
@@ -97,6 +99,10 @@ function parseArgs(argv: string[]): CliOptions {
       opts.verbose = true;
       continue;
     }
+    if (arg === "--debug") {
+      opts.debug = true;
+      continue;
+    }
   }
   return opts;
 }
@@ -143,7 +149,7 @@ async function main(): Promise<void> {
     if (!repoRoot) {
       throw new Error("Unable to locate repo root for start. Run from the repo.");
     }
-    await runStart({ repoRoot, backendPort, webPort, verbose: raw.verbose });
+    await runStart({ repoRoot, backendPort, webPort, verbose: raw.verbose, debug: raw.debug });
     return;
   }
 

apps/cli/src/start.ts

@@ -36,6 +36,8 @@ export type StartOptions = {
   webPort?: number;
   /** Show info logs from backend + web */
   verbose?: boolean;
+  /** Show debug logs + agent message dumps */
+  debug?: boolean;
 };
 
 /**
@@ -56,6 +58,7 @@ export async function runStart({
   backendPort,
   webPort,
   verbose = false,
+  debug = false,
 }: StartOptions): Promise<void> {
   const ports = await pickPorts(backendPort, webPort);
 
@@ -83,28 +86,32 @@ export async function runStart({
     }
   }
 
-  // Production mode: use warn log level for clean output unless verbose
+  // Production mode: use warn log level for clean output unless verbose/debug
+  const showOutput = verbose || debug;
   const dbPath = path.join(DATA_DIR, "kandev.db");
   const backendEnv = buildBackendEnv({
     ports,
-    logLevel: verbose ? "info" : "warn",
-    extra: { KANDEV_DB_PATH: dbPath },
+    logLevel: debug ? "debug" : verbose ? "info" : "warn",
+    extra: {
+      KANDEV_DB_PATH: dbPath,
+      ...(debug ? { KANDEV_DEBUG_AGENT_MESSAGES: "true" } : {}),
+    },
   });
   const webEnv = buildWebEnv({ ports, includeMcp: true, production: true });
 
   const supervisor = createProcessSupervisor();
   supervisor.attachSignalHandlers();
 
-  // Start backend with piped stdio (quiet mode unless verbose)
+  // Start backend with piped stdio (quiet mode unless verbose/debug)
   const backendProc = spawn(backendBin, [], {
     cwd: path.dirname(backendBin),
     env: backendEnv,
-    stdio: verbose ? ["ignore", "inherit", "inherit"] : ["ignore", "pipe", "pipe"],
+    stdio: showOutput ? ["ignore", "inherit", "inherit"] : ["ignore", "pipe", "pipe"],
   });
   supervisor.children.push(backendProc);
 
   // Forward stderr only (warnings/errors) when quiet
-  if (!verbose) {
+  if (!showOutput) {
     backendProc.stderr?.pipe(process.stderr);
   }
 
@@ -120,7 +127,7 @@ export async function runStart({
     url: webUrl,
     supervisor,
     label: "web",
-    quiet: !verbose,
+    quiet: !showOutput,
   });
 
   const healthTimeoutMs = resolveHealthTimeoutMs(HEALTH_TIMEOUT_MS_RELEASE);