@nathapp/nax 0.41.0 → 0.42.1

package/README.md

@@ -671,6 +671,7 @@ User stories are defined in `nax/features/<name>/prd.json`:
 
 ---
 
+
 ## License
 
 MIT

package/bin/nax.ts

@@ -78,6 +78,50 @@ const program = new Command();
 
 program.name("nax").description("AI Coding Agent Orchestrator — loops until done").version(NAX_VERSION);
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Prompt user for a yes/no confirmation via stdin.
+ * In tests or non-TTY environments, defaults to true.
+ *
+ * @param question - Confirmation question to display
+ * @returns true if user answers Y/y, false if N/n, true by default for non-TTY
+ */
+async function promptForConfirmation(question: string): Promise<boolean> {
+  // In non-TTY mode (tests, pipes), default to true
+  if (!process.stdin.isTTY) {
+    return true;
+  }
+
+  return new Promise((resolve) => {
+    process.stdout.write(chalk.bold(`${question} [Y/n] `));
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    const handler = (char: string) => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener("data", handler);
+
+      const answer = char.toLowerCase();
+      process.stdout.write("\n");
+
+      if (answer === "n") {
+        resolve(false);
+      } else {
+        // Default to yes for Y, Enter, or any other input
+        resolve(true);
+      }
+    };
+
+    process.stdin.on("data", handler);
+  });
+}
+
 // ── init ─────────────────────────────────────────────
 program
   .command("init")
@@ -231,6 +275,9 @@ program
   .option("--no-context", "Disable context builder (skip file context in prompts)")
   .option("--no-batch", "Disable story batching (execute all stories individually)")
   .option("--parallel <n>", "Max parallel sessions (0=auto, omit=sequential)")
+  .option("--plan", "Run plan phase first before execution", false)
+  .option("--from <spec-path>", "Path to spec file (required when --plan is used)")
+  .option("--one-shot", "Skip interactive planning Q&A, use single LLM call (ACP only)", false)
   .option("--headless", "Force headless mode (disable TUI, use pipe mode)", false)
   .option("--verbose", "Enable verbose logging (debug level)", false)
   .option("--quiet", "Quiet mode (warnings and errors only)", false)
@@ -248,6 +295,18 @@ program
       process.exit(1);
     }
 
+    // Validate --plan and --from flags (AC-8: --plan without --from is error)
+    if (options.plan && !options.from) {
+      console.error(chalk.red("Error: --plan requires --from <spec-path>"));
+      process.exit(1);
+    }
+
+    // Validate --from path exists (AC-7: --from without existing file throws error)
+    if (options.from && !existsSync(options.from)) {
+      console.error(chalk.red(`Error: File not found: ${options.from} (required with --plan)`));
+      process.exit(1);
+    }
+
     // Determine log level from flags or env var (env var takes precedence)
     let logLevel: LogLevel = "info"; // default
     const envLevel = process.env.NAX_LOG_LEVEL?.toLowerCase();
@@ -282,6 +341,51 @@ program
     const featureDir = join(naxDir, "features", options.feature);
     const prdPath = join(featureDir, "prd.json");
 
+    // Run plan phase if --plan flag is set (AC-4: runs plan then execute)
+    if (options.plan && options.from) {
+      try {
+        console.log(chalk.dim("   [Planning phase: generating PRD from spec]"));
+        const generatedPrdPath = await planCommand(workdir, config, {
+          from: options.from,
+          feature: options.feature,
+          auto: options.oneShot ?? false, // interactive by default; --one-shot skips Q&A
+          branch: undefined,
+        });
+
+        // Load the generated PRD to display confirmation gate
+        const generatedPrd = await loadPRD(generatedPrdPath);
+
+        // Display story breakdown (AC-5: confirmation gate displays story breakdown)
+        console.log(chalk.bold("\n── Planning Summary ──────────────────────────────"));
+        console.log(chalk.dim(`Feature: ${generatedPrd.feature}`));
+        console.log(chalk.dim(`Stories: ${generatedPrd.userStories.length}`));
+        console.log();
+
+        for (const story of generatedPrd.userStories) {
+          const complexity = story.routing?.complexity || "unknown";
+          console.log(chalk.dim(`  ${story.id}: ${story.title} [${complexity}]`));
+        }
+        console.log();
+
+        // Show confirmation gate unless --headless (AC-5, AC-6)
+        if (!options.headless) {
+          // Prompt for user confirmation
+          const confirmationResult = await promptForConfirmation("Proceed with execution?");
+          if (!confirmationResult) {
+            console.log(chalk.yellow("Execution cancelled."));
+            process.exit(0);
+          }
+        }
+
+        // Continue with normal run using the generated prd.json
+        // (prdPath already points to the generated file)
+      } catch (err) {
+        console.error(chalk.red(`Error during planning: ${(err as Error).message}`));
+        process.exit(1);
+      }
+    }
+
+    // Check if prd.json exists (skip if --plan already generated it)
     if (!existsSync(prdPath)) {
       console.error(chalk.red(`Feature "${options.feature}" not found or missing prd.json`));
       process.exit(1);
@@ -463,7 +567,7 @@ features
     console.log(chalk.dim("   ├── plan.md"));
     console.log(chalk.dim("   ├── tasks.md"));
     console.log(chalk.dim("   └── progress.txt"));
-    console.log(chalk.dim(`\nNext: Edit spec.md and tasks.md, then: nax analyze --feature ${name}`));
+    console.log(chalk.dim(`\nNext: Edit spec.md and tasks.md, then: nax plan -f ${name} --from spec.md --auto`));
   });
 
 features
@@ -518,11 +622,22 @@ features
 
 // ── plan ─────────────────────────────────────────────
 program
-  .command("plan <description>")
-  .description("Interactive planning via agent plan mode")
-  .option("--from <file>", "Non-interactive mode: read from input file")
+  .command("plan [description]")
+  .description("Generate prd.json from a spec file via LLM one-shot call (replaces deprecated 'nax analyze')")
+  .requiredOption("--from <spec-path>", "Path to spec file (required)")
+  .requiredOption("-f, --feature <name>", "Feature name (required)")
+  .option("--auto", "Run in one-shot LLM mode (alias: --one-shot)", false)
+  .option("--one-shot", "Run in one-shot LLM mode (alias: --auto)", false)
+  .option("-b, --branch <branch>", "Override default branch name")
   .option("-d, --dir <path>", "Project directory", process.cwd())
-  .action(async (description: string, options) => {
+  .action(async (description, options) => {
+    // AC-3: Detect and reject old positional argument form
+    if (description) {
+      console.error(
+        chalk.red("Error: Positional args removed in plan v2.\n\nUse: nax plan -f <feature> --from <spec>"),
+      );
+      process.exit(1);
+    }
     // Validate directory path
     let workdir: string;
     try {
@@ -542,14 +657,16 @@ program
     const config = await loadConfig(workdir);
 
     try {
-      const specPath = await planCommand(description, workdir, config, {
-        interactive: !options.from,
+      const prdPath = await planCommand(workdir, config, {
         from: options.from,
+        feature: options.feature,
+        auto: options.auto || options.oneShot, // --auto and --one-shot are aliases
+        branch: options.branch,
       });
 
-      console.log(chalk.green("\n✅ Planning complete"));
-      console.log(chalk.dim(`   Spec: ${specPath}`));
-      console.log(chalk.dim("\nNext: nax analyze -f <feature-name>"));
+      console.log(chalk.green("\n[OK] PRD generated"));
+      console.log(chalk.dim(`   PRD: ${prdPath}`));
+      console.log(chalk.dim(`\nNext: nax run -f ${options.feature}`));
     } catch (err) {
       console.error(chalk.red(`Error: ${(err as Error).message}`));
       process.exit(1);
@@ -559,13 +676,17 @@ program
 // ── analyze ──────────────────────────────────────────
 program
   .command("analyze")
-  .description("Parse spec.md into prd.json via agent decompose")
+  .description("(deprecated) Parse spec.md into prd.json via agent decompose — use 'nax plan' instead")
   .requiredOption("-f, --feature <name>", "Feature name")
   .option("-b, --branch <name>", "Branch name", "feat/<feature>")
   .option("--from <path>", "Explicit spec path (overrides default spec.md)")
   .option("--reclassify", "Re-classify existing prd.json without decompose", false)
   .option("-d, --dir <path>", "Project directory", process.cwd())
   .action(async (options) => {
+    // AC-1: Print deprecation warning to stderr
+    const deprecationMsg = "⚠️  'nax analyze' is deprecated. Use 'nax plan -f <feature> --from <spec> --auto' instead.";
+    process.stderr.write(`${chalk.yellow(deprecationMsg)}\n`);
+
     // Validate directory path
     let workdir: string;
     try {