@nathapp/nax 0.18.1

package/src/cli/plugins.ts

@@ -0,0 +1,111 @@
+/**
+ * Plugins Command
+ *
+ * Lists loaded plugins with their metadata.
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+import type { NaxConfig } from "../config/schema";
+import { loadPlugins } from "../plugins/loader";
+
+/**
+ * List all loaded plugins with their metadata.
+ *
+ * @param config - nax configuration
+ * @param workdir - Working directory for resolving plugin paths
+ * @param overrideGlobalPluginsDir - Override global plugins directory (used in tests)
+ */
+export async function pluginsListCommand(
+  config: NaxConfig,
+  workdir: string,
+  overrideGlobalPluginsDir?: string,
+): Promise<void> {
+  // Load plugins from all sources
+  const globalPluginsDir = overrideGlobalPluginsDir ?? path.join(os.homedir(), ".nax", "plugins");
+  const projectPluginsDir = path.join(workdir, "nax", "plugins");
+  const configPlugins = config.plugins || [];
+  const registry = await loadPlugins(globalPluginsDir, projectPluginsDir, configPlugins, workdir);
+  const plugins = registry.plugins;
+
+  if (plugins.length === 0) {
+    console.log("No plugins installed.");
+    console.log("\nTo install plugins:");
+    console.log("  • Add to global directory: ~/.nax/plugins/");
+    console.log("  • Add to project directory: ./nax/plugins/");
+    console.log("  • Configure in nax/config.json");
+    console.log("\nSee https://github.com/nax/nax#plugins for more details.");
+    return;
+  }
+
+  // Build table data
+  const rows: Array<{
+    name: string;
+    version: string;
+    provides: string;
+    source: string;
+  }> = plugins.map((plugin) => {
+    const source = registry.getSource(plugin.name);
+    const sourceStr = source ? formatSource(source.type, source.path) : "unknown";
+
+    return {
+      name: plugin.name,
+      version: plugin.version,
+      provides: plugin.provides.join(", "),
+      source: sourceStr,
+    };
+  });
+
+  // Calculate column widths
+  const widths = {
+    name: Math.max(4, ...rows.map((r) => r.name.length)),
+    version: Math.max(7, ...rows.map((r) => r.version.length)),
+    provides: Math.max(8, ...rows.map((r) => r.provides.length)),
+    source: Math.max(6, ...rows.map((r) => r.source.length)),
+  };
+
+  // Display table
+  console.log("\nInstalled Plugins:\n");
+  console.log(
+    `${pad("Name", widths.name)}  ${pad("Version", widths.version)}  ${pad("Provides", widths.provides)}  ${pad("Source", widths.source)}`,
+  );
+  console.log(
+    `${"-".repeat(widths.name)}  ${"-".repeat(widths.version)}  ${"-".repeat(widths.provides)}  ${"-".repeat(widths.source)}`,
+  );
+
+  for (const row of rows) {
+    console.log(
+      `${pad(row.name, widths.name)}  ${pad(row.version, widths.version)}  ${pad(row.provides, widths.provides)}  ${pad(row.source, widths.source)}`,
+    );
+  }
+
+  console.log();
+}
+
+/**
+ * Format source type and path for display.
+ *
+ * @param type - Source type (global/project/config)
+ * @param sourcePath - Full path to plugin
+ * @returns Formatted source string
+ */
+function formatSource(type: "global" | "project" | "config", sourcePath: string): string {
+  if (type === "global") {
+    return `global (${path.basename(sourcePath)})`;
+  }
+  if (type === "project") {
+    return `project (${path.basename(sourcePath)})`;
+  }
+  return `config (${sourcePath})`;
+}
+
+/**
+ * Pad string to width.
+ *
+ * @param str - String to pad
+ * @param width - Target width
+ * @returns Padded string
+ */
+function pad(str: string, width: number): string {
+  return str.padEnd(width);
+}

package/src/cli/prompts.ts

@@ -0,0 +1,295 @@
+/**
+ * Prompts CLI Command
+ *
+ * Assembles prompts for all stories in a feature without executing agents.
+ * Used for debugging prompt isolation and context leakage.
+ *
+ * Executes: routing → constitution → context → prompt stages only.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { NaxConfig } from "../config";
+import type { BuiltContext } from "../context/types";
+import { getLogger } from "../logger";
+import { runPipeline } from "../pipeline";
+import type { PipelineContext } from "../pipeline";
+import { constitutionStage, contextStage, promptStage, routingStage } from "../pipeline/stages";
+import type { UserStory } from "../prd";
+import { loadPRD } from "../prd";
+
+export interface PromptsCommandOptions {
+  /** Feature name */
+  feature: string;
+  /** Working directory (project root) */
+  workdir: string;
+  /** Ngent configuration */
+  config: NaxConfig;
+  /** Optional: filter to single story ID */
+  storyId?: string;
+  /** Optional: output directory (stdout if not provided) */
+  outputDir?: string;
+}
+
+/**
+ * Execute the `nax prompts` command.
+ *
+ * Runs the pipeline through routing → constitution → context → prompt stages
+ * for each story, then outputs the assembled prompts to stdout or files.
+ *
+ * @param options - Command options
+ * @returns Array of story IDs that were processed
+ *
+ * @example
+ * ```bash
+ * # Dump all story prompts to stdout
+ * nax prompts -f core
+ *
+ * # Write to directory
+ * nax prompts -f core --out ./prompt-dump/
+ *
+ * # Single story
+ * nax prompts -f core --story US-003
+ * ```
+ */
+export async function promptsCommand(options: PromptsCommandOptions): Promise<string[]> {
+  const logger = getLogger();
+  const { feature, workdir, config, storyId, outputDir } = options;
+
+  // Find nax directory
+  const naxDir = join(workdir, "nax");
+  if (!existsSync(naxDir)) {
+    throw new Error(`nax directory not found. Run 'nax init' first in ${workdir}`);
+  }
+
+  // Load PRD
+  const featureDir = join(naxDir, "features", feature);
+  const prdPath = join(featureDir, "prd.json");
+
+  if (!existsSync(prdPath)) {
+    throw new Error(`Feature "${feature}" not found or missing prd.json`);
+  }
+
+  const prd = await loadPRD(prdPath);
+
+  // Filter stories
+  const stories = storyId ? prd.userStories.filter((s) => s.id === storyId) : prd.userStories;
+
+  if (stories.length === 0) {
+    throw new Error(
+      storyId ? `Story "${storyId}" not found in feature "${feature}"` : `No stories found in feature "${feature}"`,
+    );
+  }
+
+  // Create output directory if specified
+  if (outputDir) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  logger.info("cli", "Assembling prompts", {
+    feature,
+    storyCount: stories.length,
+    outputMode: outputDir ? "files" : "stdout",
+  });
+
+  // Process each story through the pipeline (routing → constitution → context → prompt)
+  const processedStories: string[] = [];
+  const promptPipeline = [routingStage, constitutionStage, contextStage, promptStage];
+
+  for (const story of stories) {
+    // Build initial pipeline context
+    const ctx: PipelineContext = {
+      config,
+      prd,
+      story,
+      stories: [story], // Single story, not batch
+      routing: {
+        complexity: "simple",
+        modelTier: "fast",
+        testStrategy: "test-after",
+        reasoning: "Placeholder routing",
+      }, // Will be set by routingStage
+      workdir,
+      featureDir,
+      hooks: { hooks: {} }, // Empty hooks config
+    };
+
+    // Run the prompt assembly pipeline
+    const result = await runPipeline(promptPipeline, ctx);
+
+    if (!result.success) {
+      logger.warn("cli", "Failed to assemble prompt for story", {
+        storyId: story.id,
+        reason: result.reason,
+      });
+      continue;
+    }
+
+    // Handle three-session TDD stories separately
+    if (ctx.routing.testStrategy === "three-session-tdd") {
+      await handleThreeSessionTddPrompts(story, ctx, outputDir, logger);
+      processedStories.push(story.id);
+      continue;
+    }
+
+    // For non-TDD stories, ensure prompt was built
+    if (!ctx.prompt) {
+      logger.warn("cli", "No prompt generated for story", {
+        storyId: story.id,
+      });
+      continue;
+    }
+
+    // Build YAML frontmatter
+    const frontmatter = buildFrontmatter(story, ctx);
+
+    // Full output: frontmatter + prompt
+    const fullOutput = `---\n${frontmatter}---\n\n${ctx.prompt}`;
+
+    // Write to file or stdout
+    if (outputDir) {
+      const promptFile = join(outputDir, `${story.id}.prompt.md`);
+      await Bun.write(promptFile, fullOutput);
+
+      // Also write context-only file for isolation audit
+      if (ctx.contextMarkdown) {
+        const contextFile = join(outputDir, `${story.id}.context.md`);
+        const contextOutput = `---\n${frontmatter}---\n\n${ctx.contextMarkdown}`;
+        await Bun.write(contextFile, contextOutput);
+      }
+
+      logger.info("cli", "Written prompt files", {
+        storyId: story.id,
+        promptFile,
+      });
+    } else {
+      // Stdout mode: print separator + story ID + prompt
+      console.log(`\n${"=".repeat(80)}`);
+      console.log(`Story: ${story.id} — ${story.title}`);
+      console.log("=".repeat(80));
+      console.log(fullOutput);
+    }
+
+    processedStories.push(story.id);
+  }
+
+  logger.info("cli", "Prompt assembly complete", {
+    processedCount: processedStories.length,
+  });
+
+  return processedStories;
+}
+
+/**
+ * Build YAML frontmatter for a story prompt.
+ *
+ * Uses actual token counts from BuiltContext elements (computed by context builder
+ * using CHARS_PER_TOKEN=3) rather than re-estimating independently.
+ *
+ * @param story - User story
+ * @param ctx - Pipeline context after running prompt assembly
+ * @param role - Optional role for three-session TDD (test-writer, implementer, verifier)
+ * @returns YAML frontmatter string (without delimiters)
+ */
+function buildFrontmatter(story: UserStory, ctx: PipelineContext, role?: string): string {
+  const lines: string[] = [];
+
+  lines.push(`storyId: ${story.id}`);
+  lines.push(`title: "${story.title}"`);
+  lines.push(`testStrategy: ${ctx.routing.testStrategy}`);
+  lines.push(`modelTier: ${ctx.routing.modelTier}`);
+
+  if (role) {
+    lines.push(`role: ${role}`);
+  }
+
+  // Use actual token counts from BuiltContext if available
+  const builtContext = ctx.builtContext;
+  const contextTokens = builtContext?.totalTokens ?? 0;
+  const promptTokens = ctx.prompt ? Math.ceil(ctx.prompt.length / 3) : 0;
+
+  lines.push(`contextTokens: ${contextTokens}`);
+  lines.push(`promptTokens: ${promptTokens}`);
+
+  // Dependencies
+  if (story.dependencies && story.dependencies.length > 0) {
+    lines.push(`dependencies: [${story.dependencies.join(", ")}]`);
+  }
+
+  // Context elements breakdown from actual BuiltContext
+  lines.push("contextElements:");
+
+  if (builtContext) {
+    for (const element of builtContext.elements) {
+      lines.push(`  - type: ${element.type}`);
+      if (element.storyId) {
+        lines.push(`    storyId: ${element.storyId}`);
+      }
+      if (element.filePath) {
+        lines.push(`    filePath: ${element.filePath}`);
+      }
+      lines.push(`    tokens: ${element.tokens}`);
+    }
+  }
+
+  if (builtContext?.truncated) {
+    lines.push("truncated: true");
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Handle three-session TDD prompts by building separate prompts for each role.
+ *
+ * @param story - User story
+ * @param ctx - Pipeline context
+ * @param outputDir - Output directory (undefined for stdout)
+ * @param logger - Logger instance
+ */
+async function handleThreeSessionTddPrompts(
+  story: UserStory,
+  ctx: PipelineContext,
+  outputDir: string | undefined,
+  logger: ReturnType<typeof getLogger>,
+): Promise<void> {
+  // Import TDD prompt builders
+  const { buildTestWriterPrompt, buildImplementerPrompt, buildVerifierPrompt } = await import("../tdd/prompts");
+
+  // Build prompts for each session
+  const sessions = [
+    { role: "test-writer", prompt: buildTestWriterPrompt(story, ctx.contextMarkdown) },
+    { role: "implementer", prompt: buildImplementerPrompt(story, ctx.contextMarkdown) },
+    { role: "verifier", prompt: buildVerifierPrompt(story) },
+  ];
+
+  for (const session of sessions) {
+    const frontmatter = buildFrontmatter(story, ctx, session.role);
+    const fullOutput = `---\n${frontmatter}---\n\n${session.prompt}`;
+
+    if (outputDir) {
+      const promptFile = join(outputDir, `${story.id}.${session.role}.md`);
+      await Bun.write(promptFile, fullOutput);
+
+      logger.info("cli", "Written TDD prompt file", {
+        storyId: story.id,
+        role: session.role,
+        promptFile,
+      });
+    } else {
+      // Stdout mode: print separator + story ID + role + prompt
+      console.log(`\n${"=".repeat(80)}`);
+      console.log(`Story: ${story.id} — ${story.title} [${session.role}]`);
+      console.log("=".repeat(80));
+      console.log(fullOutput);
+    }
+  }
+
+  // Also write context-only file for isolation audit
+  if (outputDir && ctx.contextMarkdown) {
+    const contextFile = join(outputDir, `${story.id}.context.md`);
+    const frontmatter = buildFrontmatter(story, ctx);
+    const contextOutput = `---\n${frontmatter}---\n\n${ctx.contextMarkdown}`;
+    await Bun.write(contextFile, contextOutput);
+  }
+}

package/src/cli/runs.ts

@@ -0,0 +1,174 @@
+/**
+ * Runs CLI Commands
+ *
+ * Display run history from JSONL log files.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { NaxError } from "../errors";
+import { getLogger } from "../logger";
+import type { LogEntry } from "../logger/types";
+
+/**
+ * Options for runs list command.
+ */
+export interface RunsListOptions {
+  /** Feature name */
+  feature: string;
+  /** Project directory */
+  workdir: string;
+}
+
+/**
+ * Options for runs show command.
+ */
+export interface RunsShowOptions {
+  /** Run ID to display */
+  runId: string;
+  /** Feature name */
+  feature: string;
+  /** Project directory */
+  workdir: string;
+}
+
+/**
+ * Parse JSONL log file and extract run events.
+ *
+ * @param logPath - Path to .jsonl log file
+ * @returns Array of log entries
+ */
+async function parseRunLog(logPath: string): Promise<LogEntry[]> {
+  const logger = getLogger();
+  try {
+    const content = await Bun.file(logPath).text();
+    const lines = content.trim().split("\n").filter(Boolean);
+    return lines.map((line) => JSON.parse(line) as LogEntry);
+  } catch (err) {
+    logger.warn("cli", "Failed to parse run log", { logPath, error: (err as Error).message });
+    return [];
+  }
+}
+
+/**
+ * List all runs for a feature.
+ *
+ * @param options - Command options
+ *
+ * @example
+ * ```bash
+ * nax runs list -f auth-system
+ * ```
+ */
+export async function runsListCommand(options: RunsListOptions): Promise<void> {
+  const logger = getLogger();
+  const { feature, workdir } = options;
+
+  const runsDir = join(workdir, "nax", "features", feature, "runs");
+
+  if (!existsSync(runsDir)) {
+    logger.info("cli", "No runs found for feature", { feature, hint: `Directory not found: ${runsDir}` });
+    return;
+  }
+
+  // List all .jsonl files in runs directory
+  const files = readdirSync(runsDir).filter((f) => f.endsWith(".jsonl"));
+
+  if (files.length === 0) {
+    logger.info("cli", "No runs found for feature", { feature });
+    return;
+  }
+
+  logger.info("cli", `Runs for ${feature}`, { count: files.length });
+
+  // Parse each run file and extract run.start event
+  for (const file of files.sort().reverse()) {
+    const logPath = join(runsDir, file);
+    const entries = await parseRunLog(logPath);
+
+    // Find run.start and run.complete events
+    const startEvent = entries.find((e) => e.message === "run.start");
+    const completeEvent = entries.find((e) => e.message === "run.complete");
+
+    if (!startEvent) {
+      logger.warn("cli", "Run log missing run.start event", { file });
+      continue;
+    }
+
+    const runId = startEvent.data?.runId || file.replace(".jsonl", "");
+    const startedAt = startEvent.timestamp;
+    const status = completeEvent ? "completed" : "in-progress";
+    const totalCost = completeEvent?.data?.totalCost || 0;
+    const storiesCompleted = completeEvent?.data?.storiesCompleted || 0;
+    const totalStories = completeEvent?.data?.totalStories || 0;
+
+    logger.info("cli", `  ${runId}`, {
+      status,
+      startedAt,
+      totalCost,
+      storiesCompleted,
+      totalStories,
+    });
+  }
+}
+
+/**
+ * Show detailed information for a specific run.
+ *
+ * @param options - Command options
+ *
+ * @example
+ * ```bash
+ * nax runs show run-20260220-103045 -f auth-system
+ * ```
+ */
+export async function runsShowCommand(options: RunsShowOptions): Promise<void> {
+  const logger = getLogger();
+  const { runId, feature, workdir } = options;
+
+  const logPath = join(workdir, "nax", "features", feature, "runs", `${runId}.jsonl`);
+
+  if (!existsSync(logPath)) {
+    logger.error("cli", "Run not found", { runId, feature, logPath });
+    throw new NaxError("Run not found", "RUN_NOT_FOUND", { runId, feature, logPath });
+  }
+
+  const entries = await parseRunLog(logPath);
+
+  // Find key events
+  const startEvent = entries.find((e) => e.message === "run.start");
+  const completeEvent = entries.find((e) => e.message === "run.complete");
+  const storyEvents = entries.filter((e) => e.stage === "execution" && e.data?.storyId);
+
+  if (!startEvent) {
+    logger.error("cli", "Run log missing run.start event", { runId });
+    throw new NaxError("Run log missing run.start event", "INVALID_RUN_LOG", { runId });
+  }
+
+  // Display run summary
+  logger.info("cli", `Run: ${runId}`, {
+    feature,
+    startedAt: startEvent.timestamp,
+    completedAt: completeEvent?.timestamp,
+    status: completeEvent ? "completed" : "in-progress",
+  });
+
+  if (completeEvent) {
+    logger.info("cli", "Run Summary", {
+      totalStories: completeEvent.data?.totalStories,
+      storiesCompleted: completeEvent.data?.storiesCompleted,
+      storiesFailed: completeEvent.data?.storiesFailed,
+      totalCost: completeEvent.data?.totalCost,
+      totalDurationMs: completeEvent.data?.totalDurationMs,
+    });
+  }
+
+  // Display per-story events
+  logger.info("cli", "Story Events", { count: storyEvents.length });
+  for (const event of storyEvents) {
+    logger.info("cli", `  ${event.data?.storyId}: ${event.message}`, {
+      timestamp: event.timestamp,
+      data: event.data,
+    });
+  }
+}