feat(cli): add --headless flag for non-interactive run-and-exit mode

Add --headless option that allows deepcode to run a prompt and exit
automatically without entering the interactive TUI. This enables:
- CI/CD pipeline integration
- Shell scripting / automation
- Batch processing

Changes:
- cli-args.ts: add --headless boolean flag and validation (requires --prompt)
- cli.tsx: add runHeadless() function that creates SessionManager,
  submits prompt, streams output to stdout, and exits cleanly.
  In headless mode, permissions are forced to allowAll since there
  is no user to ask for approval.

Closes #139

Author: go-app-cloud

packages/cli/src/cli-args.ts

@@ -33,6 +33,8 @@ export interface ParsedCliArgs {
   version: boolean;
   /** True when --help / -h was passed */
   help: boolean;
+  /** True when --headless was passed (non-interactive, run-and-exit mode) */
+  headless: boolean;
 }
 
 const EPILOG = [
@@ -73,7 +75,7 @@ async function configureYargs(argv?: string[]) {
     .locale("en")
     .scriptName("deepcode")
     .usage(
-      "Usage: $0 [options] [command]\n\nDeep Code - Launch an interactive CLI, use -p/--prompt for non-interactive mode"
+      "Usage: $0 [options] [command]\n\nDeep Code - Launch an interactive CLI, use -p/--prompt with --headless for non-interactive mode"
     )
     .command("$0 [query..]", "Launch Deep Code CLI", (yargsInstance: Argv) =>
       yargsInstance
@@ -82,6 +84,10 @@ async function configureYargs(argv?: string[]) {
           type: "string",
           describe: "Submit a prompt on launch",
         })
+        .option("headless", {
+          type: "boolean",
+          describe: "Run in non-interactive (headless) mode. Use with --prompt to execute and exit automatically.",
+        })
         .option("resume", {
           alias: "r",
           type: "string",
@@ -106,6 +112,10 @@ async function configureYargs(argv?: string[]) {
           if (argv["prompt"] === "") {
             return "--prompt / -p requires a non-empty value.";
           }
+          // headless mode requires --prompt
+          if (argv["headless"] && !argv["prompt"]) {
+            return "--headless mode requires --prompt / -p with a non-empty value.";
+          }
           return true;
         })
     )
@@ -156,5 +166,6 @@ export async function parseArguments(argv?: string[]): Promise<ParsedCliArgs> {
     resume,
     version: parsed.version === true,
     help: parsed.help === true,
+    headless: parsed.headless === true,
   };
 }

packages/cli/src/cli.tsx

@@ -3,7 +3,14 @@ import { render } from "ink";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import { setShellIfWindows, getProjectCode } from "@vegamo/deepcode-core";
+import {
+  setShellIfWindows,
+  getProjectCode,
+  SessionManager,
+  createOpenAIClient,
+  resolveCurrentSettings,
+} from "@vegamo/deepcode-core";
+import type { SessionMessage, LlmStreamProgress } from "@vegamo/deepcode-core";
 import { checkForNpmUpdate, promptForPendingUpdate } from "./common/update-check";
 import { AppContainer } from "./ui";
 import { parseArguments } from "./cli-args";
@@ -32,6 +39,11 @@ async function main(): Promise<void> {
   let resumeSessionId = parsed.resume;
   const projectRoot = process.cwd();
 
+  if (parsed.headless && parsed.prompt) {
+    await runHeadless(parsed.prompt, projectRoot);
+    return;
+  }
+
   if (!process.stdin.isTTY) {
     writeStderrLine("deepcode requires an interactive terminal (TTY). Re-run from a real terminal session.\n");
     process.exit(1);
@@ -115,3 +127,65 @@ function configureWindowsShell(): void {
     process.exit(1);
   }
 }
+
+/**
+ * Run in headless (non-interactive) mode.
+ * Creates a SessionManager, submits the prompt, outputs the final response, and exits.
+ */
+async function runHeadless(promptText: string, projectRoot: string): Promise<void> {
+  process.stderr.write("[headless] Starting non-interactive mode...\n");
+
+  const assistantMessages: SessionMessage[] = [];
+
+  const sessionManager = new SessionManager({
+    projectRoot,
+    createOpenAIClient: () => createOpenAIClient(projectRoot),
+    getResolvedSettings: () => {
+      const settings = resolveCurrentSettings(projectRoot);
+      // Headless = no user to ask → auto-approve all permissions
+      return {
+        ...settings,
+        permissions: {
+          allow: [],
+          deny: [],
+          ask: [],
+          defaultMode: "allowAll" as const,
+        },
+      };
+    },
+    renderMarkdown: (text: string) => text,
+    onAssistantMessage: (message: SessionMessage) => {
+      assistantMessages.push(message);
+      // Stream content to stdout as it arrives
+      if (message.content) {
+        process.stdout.write(message.content as string);
+      }
+    },
+    onLlmStreamProgress: (progress: LlmStreamProgress) => {
+      if (progress.phase === "start") {
+        process.stderr.write("[headless] Model is thinking...\n");
+      } else if (progress.phase === "end") {
+        process.stderr.write("[headless] Response complete.\n");
+      }
+    },
+  });
+
+  try {
+    // Initialize MCP servers from settings
+    const settings = resolveCurrentSettings(projectRoot);
+    await sessionManager.initMcpServers(settings.mcpServers);
+
+    // Submit the prompt
+    await sessionManager.handleUserPrompt({ text: promptText });
+
+    process.stdout.write("\n");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[headless] Error: ${message}\n`);
+    process.exit(1);
+  } finally {
+    sessionManager.dispose();
+  }
+
+  process.exit(0);
+}