@nathapp/nax 0.18.1

package/src/cli/init.ts

@@ -0,0 +1,188 @@
+/**
+ * Init Command
+ *
+ * Initializes nax configuration directories and files.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalConfigDir, projectConfigDir } from "../config/paths";
+import { DEFAULT_CONFIG } from "../config/schema";
+import { getLogger } from "../logger";
+
+/** Init command options */
+export interface InitOptions {
+  /** Initialize global config (~/.nax) */
+  global?: boolean;
+  /** Project root (default: cwd) */
+  projectRoot?: string;
+}
+
+/**
+ * Gitignore entries added by nax init
+ */
+const NAX_GITIGNORE_ENTRIES = [".nax-verifier-verdict.json"];
+
+/**
+ * Add nax-specific entries to .gitignore if not already present.
+ *
+ * Appends a clearly marked nax section to the project .gitignore.
+ */
+async function updateGitignore(projectRoot: string): Promise<void> {
+  const logger = getLogger();
+  const gitignorePath = join(projectRoot, ".gitignore");
+
+  let existing = "";
+  if (existsSync(gitignorePath)) {
+    existing = readFileSync(gitignorePath, "utf-8");
+  }
+
+  const missingEntries = NAX_GITIGNORE_ENTRIES.filter((entry) => !existing.includes(entry));
+
+  if (missingEntries.length === 0) {
+    logger.info("init", ".gitignore already has nax entries", { path: gitignorePath });
+    return;
+  }
+
+  const naxSection = `\n# nax — generated files\n${missingEntries.join("\n")}\n`;
+  await Bun.write(gitignorePath, existing + naxSection);
+  logger.info("init", "Updated .gitignore with nax entries", {
+    path: gitignorePath,
+    added: missingEntries,
+  });
+}
+
+/**
+ * Template for default constitution.md
+ */
+const DEFAULT_CONSTITUTION = `# Project Constitution
+
+## Goals
+- Deliver high-quality, maintainable code
+- Follow project conventions and best practices
+- Maintain comprehensive test coverage
+
+## Constraints
+- Use Bun-native APIs only
+- Follow functional style for pure logic
+- Keep files focused and under 400 lines
+
+## Preferences
+- Prefer immutability over mutation
+- Write tests first (TDD approach)
+- Clear, descriptive naming
+`;
+
+/**
+ * Template for minimal config.json (references defaults, only overrides)
+ */
+const MINIMAL_PROJECT_CONFIG = {
+  version: 1,
+  // Add project-specific overrides here
+};
+
+const MINIMAL_GLOBAL_CONFIG = {
+  version: 1,
+  // Add global preferences here (e.g., model tiers, execution limits)
+};
+
+/**
+ * Initialize global nax config directory (~/.nax)
+ */
+async function initGlobal(): Promise<void> {
+  const logger = getLogger();
+  const globalDir = globalConfigDir();
+
+  // Create ~/.nax if it doesn't exist
+  if (!existsSync(globalDir)) {
+    mkdirSync(globalDir, { recursive: true });
+    logger.info("init", "Created global config directory", { path: globalDir });
+  }
+
+  // Create ~/.nax/config.json if it doesn't exist
+  const configPath = join(globalDir, "config.json");
+  if (!existsSync(configPath)) {
+    await Bun.write(configPath, `${JSON.stringify(MINIMAL_GLOBAL_CONFIG, null, 2)}\n`);
+    logger.info("init", "Created global config", { path: configPath });
+  } else {
+    logger.info("init", "Global config already exists", { path: configPath });
+  }
+
+  // Create ~/.nax/constitution.md if it doesn't exist
+  const constitutionPath = join(globalDir, "constitution.md");
+  if (!existsSync(constitutionPath)) {
+    await Bun.write(constitutionPath, DEFAULT_CONSTITUTION);
+    logger.info("init", "Created global constitution", { path: constitutionPath });
+  } else {
+    logger.info("init", "Global constitution already exists", { path: constitutionPath });
+  }
+
+  // Create ~/.nax/hooks/ directory if it doesn't exist
+  const hooksDir = join(globalDir, "hooks");
+  if (!existsSync(hooksDir)) {
+    mkdirSync(hooksDir, { recursive: true });
+    logger.info("init", "Created global hooks directory", { path: hooksDir });
+  } else {
+    logger.info("init", "Global hooks directory already exists", { path: hooksDir });
+  }
+
+  logger.info("init", "Global config initialized successfully", { path: globalDir });
+}
+
+/**
+ * Initialize project nax directory (nax/)
+ */
+async function initProject(projectRoot: string): Promise<void> {
+  const logger = getLogger();
+  const projectDir = projectConfigDir(projectRoot);
+
+  // Create nax/ directory if it doesn't exist
+  if (!existsSync(projectDir)) {
+    mkdirSync(projectDir, { recursive: true });
+    logger.info("init", "Created project config directory", { path: projectDir });
+  }
+
+  // Create nax/config.json if it doesn't exist
+  const configPath = join(projectDir, "config.json");
+  if (!existsSync(configPath)) {
+    await Bun.write(configPath, `${JSON.stringify(MINIMAL_PROJECT_CONFIG, null, 2)}\n`);
+    logger.info("init", "Created project config", { path: configPath });
+  } else {
+    logger.info("init", "Project config already exists", { path: configPath });
+  }
+
+  // Create nax/constitution.md if it doesn't exist
+  const constitutionPath = join(projectDir, "constitution.md");
+  if (!existsSync(constitutionPath)) {
+    await Bun.write(constitutionPath, DEFAULT_CONSTITUTION);
+    logger.info("init", "Created project constitution", { path: constitutionPath });
+  } else {
+    logger.info("init", "Project constitution already exists", { path: constitutionPath });
+  }
+
+  // Create nax/hooks/ directory if it doesn't exist
+  const hooksDir = join(projectDir, "hooks");
+  if (!existsSync(hooksDir)) {
+    mkdirSync(hooksDir, { recursive: true });
+    logger.info("init", "Created project hooks directory", { path: hooksDir });
+  } else {
+    logger.info("init", "Project hooks directory already exists", { path: hooksDir });
+  }
+
+  // Update .gitignore to include nax-specific entries
+  await updateGitignore(projectRoot);
+
+  logger.info("init", "Project config initialized successfully", { path: projectDir });
+}
+
+/**
+ * Run init command
+ */
+export async function initCommand(options: InitOptions = {}): Promise<void> {
+  if (options.global) {
+    await initGlobal();
+  } else {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    await initProject(projectRoot);
+  }
+}

package/src/cli/interact.ts

@@ -0,0 +1,295 @@
+/**
+ * Interact CLI Command (v0.15.0 US-006)
+ *
+ * Manage pending interactions from CLI:
+ * - nax interact list -f <feature>
+ * - nax interact respond <id> --action approve|reject|choose|input --value <val>
+ * - nax interact cancel <id>
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import chalk from "chalk";
+import { resolveProject } from "../commands/common";
+import type { InteractionRequest, InteractionResponse } from "../interaction";
+import {
+  deletePendingInteraction,
+  listPendingInteractions,
+  loadPendingInteraction,
+  savePendingInteraction,
+} from "../interaction";
+
+/**
+ * Options for interact list command
+ */
+export interface InteractListOptions {
+  /** Feature name (required) */
+  feature: string;
+  /** Explicit project directory */
+  dir?: string;
+  /** JSON output mode */
+  json?: boolean;
+}
+
+/**
+ * Options for interact respond command
+ */
+export interface InteractRespondOptions {
+  /** Feature name */
+  feature?: string;
+  /** Explicit project directory */
+  dir?: string;
+  /** Action to take */
+  action: "approve" | "reject" | "choose" | "input" | "skip" | "abort";
+  /** Value (for choose/input) */
+  value?: string;
+  /** JSON output mode */
+  json?: boolean;
+}
+
+/**
+ * Options for interact cancel command
+ */
+export interface InteractCancelOptions {
+  /** Feature name */
+  feature?: string;
+  /** Explicit project directory */
+  dir?: string;
+  /** JSON output mode */
+  json?: boolean;
+}
+
+/**
+ * List pending interactions for a feature
+ */
+export async function interactListCommand(options: InteractListOptions): Promise<void> {
+  const resolved = resolveProject({
+    dir: options.dir,
+    feature: options.feature,
+  });
+
+  if (!resolved.featureDir) {
+    throw new Error("Feature directory not resolved");
+  }
+
+  const interactionsDir = join(resolved.featureDir, "interactions");
+  if (!existsSync(interactionsDir)) {
+    if (options.json) {
+      console.log(JSON.stringify({ interactions: [] }));
+    } else {
+      console.log(chalk.dim("No pending interactions."));
+    }
+    return;
+  }
+
+  const ids = await listPendingInteractions(resolved.featureDir);
+
+  if (ids.length === 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ interactions: [] }));
+    } else {
+      console.log(chalk.dim("No pending interactions."));
+    }
+    return;
+  }
+
+  // Load full requests
+  const requests: InteractionRequest[] = [];
+  for (const id of ids) {
+    const req = await loadPendingInteraction(id, resolved.featureDir);
+    if (req) {
+      requests.push(req);
+    }
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ interactions: requests }, null, 2));
+    return;
+  }
+
+  // Display table
+  console.log(chalk.bold(`\n📬 Pending Interactions (${options.feature})\n`));
+
+  for (const req of requests) {
+    const safety = req.metadata?.safety ?? "unknown";
+    const safetyIcon = safety === "red" ? "🔴" : safety === "yellow" ? "🟡" : "🟢";
+    const timeRemaining = req.timeout ? Math.max(0, req.createdAt + req.timeout - Date.now()) : null;
+
+    console.log(`${safetyIcon} ${chalk.bold(req.id)}`);
+    console.log(chalk.dim(`   Type:     ${req.type}`));
+    console.log(chalk.dim(`   Stage:    ${req.stage}`));
+    console.log(chalk.dim(`   Summary:  ${req.summary}`));
+    if (req.storyId) {
+      console.log(chalk.dim(`   Story:    ${req.storyId}`));
+    }
+    console.log(chalk.dim(`   Fallback: ${req.fallback}`));
+    if (timeRemaining !== null) {
+      const timeoutSec = Math.floor(timeRemaining / 1000);
+      console.log(chalk.dim(`   Timeout:  ${timeoutSec}s remaining`));
+    }
+    if (req.options && req.options.length > 0) {
+      console.log(chalk.dim("   Options:"));
+      for (const opt of req.options) {
+        console.log(chalk.dim(`     [${opt.key}] ${opt.label}`));
+      }
+    }
+    console.log();
+  }
+}
+
+/**
+ * Respond to a pending interaction
+ */
+export async function interactRespondCommand(requestId: string, options: InteractRespondOptions): Promise<void> {
+  // Find the feature by searching all features for the request
+  let featureDir: string | null = null;
+  let request: InteractionRequest | null = null;
+
+  if (options.feature) {
+    const resolved = resolveProject({
+      dir: options.dir,
+      feature: options.feature,
+    });
+    featureDir = resolved.featureDir ?? null;
+    if (featureDir) {
+      request = await loadPendingInteraction(requestId, featureDir);
+    }
+  } else {
+    // Search all features
+    const resolved = resolveProject({ dir: options.dir });
+    const featuresDir = join(resolved.projectDir, "nax", "features");
+    if (existsSync(featuresDir)) {
+      const { readdirSync } = await import("node:fs");
+      const features = readdirSync(featuresDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+
+      for (const feature of features) {
+        const dir = join(featuresDir, feature);
+        const req = await loadPendingInteraction(requestId, dir);
+        if (req) {
+          request = req;
+          featureDir = dir;
+          break;
+        }
+      }
+    }
+  }
+
+  if (!request || !featureDir) {
+    throw new Error(`Interaction request not found: ${requestId}`);
+  }
+
+  // Validate action matches request type
+  if (options.action === "choose" && request.type !== "choose") {
+    throw new Error(`Action "choose" only valid for type "choose" (request is ${request.type})`);
+  }
+
+  if (options.action === "input" && request.type !== "input") {
+    throw new Error(`Action "input" only valid for type "input" (request is ${request.type})`);
+  }
+
+  if (options.action === "choose" && !options.value) {
+    throw new Error("--value required for action choose");
+  }
+
+  if (options.action === "input" && !options.value) {
+    throw new Error("--value required for action input");
+  }
+
+  // Create response
+  const response: InteractionResponse = {
+    requestId,
+    action: options.action,
+    value: options.value,
+    respondedBy: "cli",
+    respondedAt: Date.now(),
+  };
+
+  // Save response (write to responses/ directory)
+  const responsesDir = join(featureDir, "responses");
+  await Bun.write(join(responsesDir, ".gitkeep"), "");
+  const responseFile = join(responsesDir, `${requestId}.json`);
+  await Bun.write(responseFile, JSON.stringify(response, null, 2));
+
+  // Delete pending interaction
+  await deletePendingInteraction(requestId, featureDir);
+
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, response }));
+  } else {
+    console.log(chalk.green(`✅ Response recorded: ${options.action}`));
+    if (options.value) {
+      console.log(chalk.dim(`   Value: ${options.value}`));
+    }
+  }
+}
+
+/**
+ * Cancel a pending interaction (applies fallback)
+ */
+export async function interactCancelCommand(requestId: string, options: InteractCancelOptions): Promise<void> {
+  // Find the feature by searching all features for the request
+  let featureDir: string | null = null;
+  let request: InteractionRequest | null = null;
+
+  if (options.feature) {
+    const resolved = resolveProject({
+      dir: options.dir,
+      feature: options.feature,
+    });
+    featureDir = resolved.featureDir ?? null;
+    if (featureDir) {
+      request = await loadPendingInteraction(requestId, featureDir);
+    }
+  } else {
+    // Search all features
+    const resolved = resolveProject({ dir: options.dir });
+    const featuresDir = join(resolved.projectDir, "nax", "features");
+    if (existsSync(featuresDir)) {
+      const { readdirSync } = await import("node:fs");
+      const features = readdirSync(featuresDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+
+      for (const feature of features) {
+        const dir = join(featuresDir, feature);
+        const req = await loadPendingInteraction(requestId, dir);
+        if (req) {
+          request = req;
+          featureDir = dir;
+          break;
+        }
+      }
+    }
+  }
+
+  if (!request || !featureDir) {
+    throw new Error(`Interaction request not found: ${requestId}`);
+  }
+
+  // Create response with fallback action
+  const fallbackAction = request.fallback === "continue" ? "approve" : request.fallback === "skip" ? "skip" : "abort";
+
+  const response: InteractionResponse = {
+    requestId,
+    action: fallbackAction,
+    respondedBy: "cli-cancel",
+    respondedAt: Date.now(),
+  };
+
+  // Save response
+  const responsesDir = join(featureDir, "responses");
+  await Bun.write(join(responsesDir, ".gitkeep"), "");
+  const responseFile = join(responsesDir, `${requestId}.json`);
+  await Bun.write(responseFile, JSON.stringify(response, null, 2));
+
+  // Delete pending interaction
+  await deletePendingInteraction(requestId, featureDir);
+
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, response }));
+  } else {
+    console.log(chalk.yellow(`⏭ Interaction cancelled (fallback: ${request.fallback})`));
+  }
+}

package/src/cli/plan.ts

@@ -0,0 +1,198 @@
+/**
+ * Plan Command — Interactive planning via agent plan mode
+ *
+ * Spawns a coding agent in plan mode to gather requirements,
+ * ask clarifying questions, and generate a structured specification.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { ClaudeCodeAdapter } from "../agents/claude";
+import type { PlanOptions } from "../agents/types";
+import { scanCodebase } from "../analyze/scanner";
+import type { NaxConfig } from "../config";
+import { resolveModel } from "../config/schema";
+import { getLogger } from "../logger";
+
+/**
+ * Template for structured specification output.
+ *
+ * This template guides the agent to produce a consistent spec format
+ * that can be parsed by the analyze command.
+ */
+const SPEC_TEMPLATE = `# Feature: [title]
+
+## Problem
+Why this is needed.
+
+## Requirements
+- REQ-1: ...
+- REQ-2: ...
+
+## Acceptance Criteria
+- AC-1: ...
+
+## Technical Notes
+Architecture hints, constraints, dependencies.
+
+## Out of Scope
+What this does NOT include.
+`;
+
+/**
+ * Run the plan command to generate a feature specification.
+ *
+ * @param prompt - The feature description or task
+ * @param workdir - Project root directory
+ * @param config - Ngent configuration
+ * @param options - Command options (interactive, from)
+ * @returns Path to the generated spec file
+ */
+export async function planCommand(
+  prompt: string,
+  workdir: string,
+  config: NaxConfig,
+  options: {
+    interactive?: boolean;
+    from?: string;
+  } = {},
+): Promise<string> {
+  const interactive = options.interactive !== false; // Default to true
+  const ngentDir = join(workdir, "nax");
+  const outputPath = join(ngentDir, config.plan.outputPath);
+
+  // Ensure nax directory exists
+  if (!existsSync(ngentDir)) {
+    throw new Error(`nax directory not found. Run 'nax init' first in ${workdir}`);
+  }
+
+  // Scan codebase for context
+  const logger = getLogger();
+  logger.info("cli", "Scanning codebase...");
+  const scan = await scanCodebase(workdir);
+
+  // Build codebase context markdown
+  const codebaseContext = buildCodebaseContext(scan);
+
+  // Resolve model for planning
+  const modelTier = config.plan.model;
+  const modelEntry = config.models[modelTier];
+  const modelDef = resolveModel(modelEntry);
+
+  // Build full prompt with template
+  const fullPrompt = buildPlanPrompt(prompt, SPEC_TEMPLATE);
+
+  // Prepare plan options
+  const planOptions: PlanOptions = {
+    prompt: fullPrompt,
+    workdir,
+    interactive,
+    codebaseContext,
+    inputFile: options.from,
+    modelTier,
+    modelDef,
+  };
+
+  // Run agent in plan mode
+  const adapter = new ClaudeCodeAdapter();
+
+  logger.info("cli", interactive ? "Starting interactive planning session..." : `Reading from ${options.from}...`, {
+    interactive,
+    from: options.from,
+  });
+
+  const result = await adapter.plan(planOptions);
+
+  // Write spec to output file
+  if (interactive) {
+    // In interactive mode, the agent may have written directly
+    // But we also capture and write to ensure consistency
+    if (result.specContent) {
+      await Bun.write(outputPath, result.specContent);
+    } else {
+      // If agent wrote directly, verify it exists
+      if (!existsSync(outputPath)) {
+        throw new Error(`Interactive planning completed but spec not found at ${outputPath}`);
+      }
+    }
+  } else {
+    // In non-interactive mode, we have the spec in result
+    if (!result.specContent) {
+      throw new Error("Agent did not produce specification content");
+    }
+    await Bun.write(outputPath, result.specContent);
+  }
+
+  logger.info("cli", "✓ Specification written to output", { outputPath });
+
+  return outputPath;
+}
+
+/**
+ * Build codebase context markdown from scan results.
+ *
+ * @param scan - Codebase scan result
+ * @returns Formatted context string
+ */
+function buildCodebaseContext(scan: {
+  fileTree: string;
+  dependencies: Record<string, string>;
+  devDependencies: Record<string, string>;
+  testPatterns: string[];
+}): string {
+  const sections: string[] = [];
+
+  // File tree
+  sections.push("## Codebase Structure\n");
+  sections.push("```");
+  sections.push(scan.fileTree);
+  sections.push("```\n");
+
+  // Dependencies
+  const allDeps = { ...scan.dependencies, ...scan.devDependencies };
+  const depList = Object.entries(allDeps)
+    .map(([name, version]) => `- ${name}@${version}`)
+    .join("\n");
+
+  if (depList) {
+    sections.push("## Dependencies\n");
+    sections.push(depList);
+    sections.push("");
+  }
+
+  // Test patterns
+  if (scan.testPatterns.length > 0) {
+    sections.push("## Test Setup\n");
+    sections.push(scan.testPatterns.map((p) => `- ${p}`).join("\n"));
+    sections.push("");
+  }
+
+  return sections.join("\n");
+}
+
+/**
+ * Build the full planning prompt with template.
+ *
+ * @param userPrompt - User's task description
+ * @param template - Spec template
+ * @returns Full prompt with instructions
+ */
+function buildPlanPrompt(userPrompt: string, template: string): string {
+  return `You are helping plan a new feature for this codebase.
+
+Task: ${userPrompt}
+
+Please gather requirements and produce a structured specification following this template:
+
+${template}
+
+Ask clarifying questions as needed to ensure the spec is complete and unambiguous.
+Focus on understanding:
+- The problem being solved
+- Specific requirements and constraints
+- Acceptance criteria for success
+- Technical approach and architecture
+- What is explicitly out of scope
+
+When done, output the complete specification in markdown format.`;
+}