@nathapp/nax 0.18.6 → 0.19.0

package/test/unit/utils/path-security.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import { validateModulePath } from "../../../src/utils/path-security";
+import { resolve } from "node:path";
+
+describe("path-security utility", () => {
+  const projectRoot = "/home/project";
+  const globalRoot = "/home/global";
+  const roots = [projectRoot, globalRoot];
+
+  test("allows relative path within project root", () => {
+    // Relative paths are resolved relative to the first allowed root by our validator
+    const result = validateModulePath("./plugins/my-plugin.ts", roots);
+    expect(result.valid).toBe(true);
+    expect(result.absolutePath).toBe(resolve(projectRoot, "plugins/my-plugin.ts"));
+  });
+
+  test("allows absolute path within global root", () => {
+    const result = validateModulePath("/home/global/plugins/my-plugin.ts", roots);
+    expect(result.valid).toBe(true);
+    expect(result.absolutePath).toBe("/home/global/plugins/my-plugin.ts");
+  });
+
+  test("blocks traversal out of root (../)", () => {
+    // resolve handles the ../ then our startsWith check fails
+    const result = validateModulePath("../../etc/passwd", roots);
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain("outside allowed roots");
+  });
+
+  test("blocks absolute path outside roots", () => {
+    const result = validateModulePath("/usr/bin/node", roots);
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain("outside allowed roots");
+  });
+
+  test("handles root itself", () => {
+    const result = validateModulePath("/home/project", roots);
+    expect(result.valid).toBe(true);
+    expect(result.absolutePath).toBe("/home/project");
+  });
+
+  test("blocks empty path", () => {
+    const result = validateModulePath("", roots);
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain("empty");
+  });
+});

package/src/execution/lifecycle/run-lifecycle.ts

@@ -1,312 +0,0 @@
-/**
- * Run Lifecycle — Setup & Teardown Logic
- *
- * Encapsulates the bookend operations for a nax execution run:
- * - Setup: lock acquisition, PRD loading, plugin initialization, reporter setup
- * - Teardown: metrics computation, final status write, lock release, plugin cleanup
- */
-
-import * as os from "node:os";
-import path from "node:path";
-import { getAgent } from "../../agents";
-import type { NaxConfig } from "../../config";
-import {
-  AgentNotFoundError,
-  AgentNotInstalledError,
-  LockAcquisitionError,
-  StoryLimitExceededError,
-} from "../../errors";
-import { type LoadedHooksConfig, fireHook } from "../../hooks";
-import { getSafeLogger } from "../../logger";
-import { type StoryMetrics, saveRunMetrics } from "../../metrics";
-import { loadPlugins } from "../../plugins/loader";
-import type { PluginRegistry } from "../../plugins/registry";
-import type { PRD } from "../../prd";
-import { countStories, isComplete, isStalled, loadPRD } from "../../prd";
-import { clearCache as clearLlmCache, routeBatch as llmRouteBatch } from "../../routing/strategies/llm";
-import { type StoryBatch, precomputeBatchPlan } from "../batching";
-import { acquireLock, getAllReadyStories, hookCtx, releaseLock } from "../helpers";
-import type { StatusWriter } from "../status-writer";
-
-/** Setup result containing initialized state */
-export interface SetupResult {
-  prd: PRD;
-  pluginRegistry: PluginRegistry;
-  batchPlan: StoryBatch[];
-}
-
-/** Teardown options */
-export interface TeardownOptions {
-  runId: string;
-  feature: string;
-  startedAt: string;
-  prd: PRD;
-  allStoryMetrics: StoryMetrics[];
-  totalCost: number;
-  storiesCompleted: number;
-  startTime: number;
-  workdir: string;
-  pluginRegistry: PluginRegistry;
-  statusWriter: StatusWriter;
-  iterations: number;
-}
-
-/**
- * Run lifecycle manager — handles setup and teardown for nax execution
- */
-export class RunLifecycle {
-  constructor(
-    private readonly prdPath: string,
-    private readonly workdir: string,
-    private readonly config: NaxConfig,
-    private readonly hooks: LoadedHooksConfig,
-    private readonly feature: string,
-    private readonly dryRun: boolean,
-    private readonly useBatch: boolean,
-    private readonly statusWriter: StatusWriter,
-    private readonly runId: string,
-    private readonly startedAt: string,
-  ) {}
-
-  /**
-   * Setup: Acquire lock, load PRD, initialize plugins, setup reporters
-   */
-  async setup(): Promise<SetupResult> {
-    const logger = getSafeLogger();
-
-    // Acquire lock to prevent concurrent execution
-    const lockAcquired = await acquireLock(this.workdir);
-    if (!lockAcquired) {
-      logger?.error("execution", "Another nax process is already running in this directory");
-      logger?.error("execution", "If you believe this is an error, remove nax.lock manually");
-      throw new LockAcquisitionError(this.workdir);
-    }
-
-    // Load plugins
-    const globalPluginsDir = path.join(os.homedir(), ".nax", "plugins");
-    const projectPluginsDir = path.join(this.workdir, "nax", "plugins");
-    const configPlugins = this.config.plugins || [];
-    const pluginRegistry = await loadPlugins(globalPluginsDir, projectPluginsDir, configPlugins, this.workdir);
-    const reporters = pluginRegistry.getReporters();
-
-    logger?.info("plugins", `Loaded ${pluginRegistry.plugins.length} plugins`, {
-      plugins: pluginRegistry.plugins.map((p) => ({ name: p.name, version: p.version, provides: p.provides })),
-    });
-
-    // Log run start
-    const routingMode = this.config.routing.llm?.mode ?? "hybrid";
-    logger?.info("run.start", `Starting feature: ${this.feature}`, {
-      runId: this.runId,
-      feature: this.feature,
-      workdir: this.workdir,
-      dryRun: this.dryRun,
-      useBatch: this.useBatch,
-      routingMode,
-    });
-
-    // Fire on-start hook
-    await fireHook(this.hooks, "on-start", hookCtx(this.feature), this.workdir);
-
-    // Check agent installation before starting
-    const agent = getAgent(this.config.autoMode.defaultAgent);
-    if (!agent) {
-      logger?.error("execution", "Agent not found", {
-        agent: this.config.autoMode.defaultAgent,
-      });
-      throw new AgentNotFoundError(this.config.autoMode.defaultAgent);
-    }
-
-    const installed = await agent.isInstalled();
-    if (!installed) {
-      logger?.error("execution", "Agent is not installed or not in PATH", {
-        agent: this.config.autoMode.defaultAgent,
-        binary: agent.binary,
-      });
-      logger?.error("execution", "Please install the agent and try again");
-      throw new AgentNotInstalledError(this.config.autoMode.defaultAgent, agent.binary);
-    }
-
-    // Load PRD
-    const prd = await loadPRD(this.prdPath);
-    const counts = countStories(prd);
-
-    // Status write point: run started
-    this.statusWriter.setPrd(prd);
-    this.statusWriter.setRunStatus("running");
-    this.statusWriter.setCurrentStory(null);
-    await this.statusWriter.update(0, 0);
-
-    // Update reporters with correct totalStories count
-    for (const reporter of reporters) {
-      if (reporter.onRunStart) {
-        try {
-          await reporter.onRunStart({
-            runId: this.runId,
-            feature: this.feature,
-            totalStories: counts.total,
-            startTime: this.startedAt,
-          });
-        } catch (error) {
-          logger?.warn("plugins", `Reporter '${reporter.name}' onRunStart failed`, { error });
-        }
-      }
-    }
-
-    // MEM-1: Validate story count doesn't exceed limit
-    if (counts.total > this.config.execution.maxStoriesPerFeature) {
-      logger?.error("execution", "Feature exceeds story limit", {
-        totalStories: counts.total,
-        limit: this.config.execution.maxStoriesPerFeature,
-      });
-      logger?.error("execution", "Split this feature into smaller features or increase maxStoriesPerFeature in config");
-      throw new StoryLimitExceededError(counts.total, this.config.execution.maxStoriesPerFeature);
-    }
-
-    logger?.info("execution", `Starting ${this.feature}`, {
-      totalStories: counts.total,
-      doneStories: counts.passed,
-      pendingStories: counts.pending,
-      batchingEnabled: this.useBatch,
-    });
-
-    // Clear LLM routing cache at start of new run
-    clearLlmCache();
-
-    // PERF-1: Precompute batch plan once from ready stories
-    let batchPlan: StoryBatch[] = [];
-    if (this.useBatch) {
-      const readyStories = getAllReadyStories(prd);
-      batchPlan = precomputeBatchPlan(readyStories, 4);
-
-      // Initial batch routing
-      const mode = this.config.routing.llm?.mode ?? "hybrid";
-      if (this.config.routing.strategy === "llm" && mode !== "per-story" && readyStories.length > 0) {
-        try {
-          logger?.debug("routing", "LLM batch routing: routing", { storyCount: readyStories.length, mode });
-          await llmRouteBatch(readyStories, { config: this.config });
-          logger?.debug("routing", "LLM batch routing complete", { label: "routing" });
-        } catch (err) {
-          logger?.warn("routing", "LLM batch routing failed, falling back to individual routing", {
-            error: (err as Error).message,
-            label: "routing",
-          });
-        }
-      }
-    }
-
-    return {
-      prd,
-      pluginRegistry,
-      batchPlan,
-    };
-  }
-
-  /**
-   * Teardown: Compute final metrics, write final status, release lock, cleanup plugins
-   */
-  async teardown(options: TeardownOptions): Promise<void> {
-    const logger = getSafeLogger();
-    const {
-      runId,
-      feature,
-      startedAt,
-      prd,
-      allStoryMetrics,
-      totalCost,
-      storiesCompleted,
-      startTime,
-      workdir,
-      pluginRegistry,
-      statusWriter,
-      iterations,
-    } = options;
-
-    const durationMs = Date.now() - startTime;
-
-    // Save run metrics
-    const runCompletedAt = new Date().toISOString();
-    const runMetrics = {
-      runId,
-      feature,
-      startedAt,
-      completedAt: runCompletedAt,
-      totalCost,
-      totalStories: allStoryMetrics.length,
-      storiesCompleted,
-      storiesFailed: countStories(prd).failed,
-      totalDurationMs: durationMs,
-      stories: allStoryMetrics,
-    };
-
-    await saveRunMetrics(workdir, runMetrics);
-
-    // Log run completion
-    const finalCounts = countStories(prd);
-
-    // Prepare per-story metrics summary
-    const storyMetricsSummary = allStoryMetrics.map((sm) => ({
-      storyId: sm.storyId,
-      complexity: sm.complexity,
-      modelTier: sm.modelTier,
-      modelUsed: sm.modelUsed,
-      attempts: sm.attempts,
-      finalTier: sm.finalTier,
-      success: sm.success,
-      cost: sm.cost,
-      durationMs: sm.durationMs,
-      firstPassSuccess: sm.firstPassSuccess,
-    }));
-
-    logger?.info("run.complete", "Feature execution completed", {
-      runId,
-      feature,
-      success: isComplete(prd),
-      iterations,
-      totalStories: finalCounts.total,
-      storiesCompleted,
-      storiesFailed: finalCounts.failed,
-      storiesPending: finalCounts.pending,
-      totalCost,
-      durationMs,
-      storyMetrics: storyMetricsSummary,
-    });
-
-    // Emit onRunEnd to reporters
-    const reporters = pluginRegistry.getReporters();
-    for (const reporter of reporters) {
-      if (reporter.onRunEnd) {
-        try {
-          await reporter.onRunEnd({
-            runId,
-            totalDurationMs: durationMs,
-            totalCost,
-            storySummary: {
-              completed: storiesCompleted,
-              failed: finalCounts.failed,
-              skipped: finalCounts.skipped,
-              paused: finalCounts.paused,
-            },
-          });
-        } catch (error) {
-          logger?.warn("plugins", `Reporter '${reporter.name}' onRunEnd failed`, { error });
-        }
-      }
-    }
-
-    // Status write point: run end
-    statusWriter.setPrd(prd);
-    statusWriter.setCurrentStory(null);
-    statusWriter.setRunStatus(isComplete(prd) ? "completed" : isStalled(prd) ? "stalled" : "running");
-    await statusWriter.update(totalCost, iterations);
-
-    // Teardown plugins
-    try {
-      await pluginRegistry.teardownAll();
-    } catch (error) {
-      logger?.warn("plugins", "Plugin teardown failed", { error });
-    }
-
-    // Always release lock, even if execution fails
-    await releaseLock(workdir);
-  }
-}

package/test/unit/run-lifecycle.test.ts

@@ -1,140 +0,0 @@
-/**
- * Tests for src/execution/run-lifecycle.ts
- *
- * Covers: RunLifecycle teardown critical paths
- */
-
-import { describe, expect, it, mock } from "bun:test";
-import type { NaxConfig } from "../../src/config";
-import { RunLifecycle } from "../../src/execution/lifecycle";
-import type { LoadedHooksConfig } from "../../src/hooks";
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Test fixtures
-// ─────────────────────────────────────────────────────────────────────────────
-
-const mockConfig: NaxConfig = {
-  autoMode: { defaultAgent: "claude" },
-  routing: { strategy: "complexity", llm: { mode: "hybrid" } },
-  execution: {
-    maxStoriesPerFeature: 100,
-    sessionTimeoutSeconds: 600,
-    maxIterations: 50,
-    costLimitUSD: 10.0,
-  },
-  models: {
-    fast: { provider: "anthropic", name: "claude-3-haiku-20240307" },
-    balanced: { provider: "anthropic", name: "claude-3-5-sonnet-20241022" },
-    powerful: { provider: "anthropic", name: "claude-opus-4-20250514" },
-  },
-  tierOrder: [
-    { tier: "fast", attempts: 3 },
-    { tier: "balanced", attempts: 2 },
-    { tier: "powerful", attempts: 1 },
-  ],
-  plugins: [],
-  tdd: { enabled: true },
-} as NaxConfig;
-
-const mockHooks: LoadedHooksConfig = {
-  "on-start": [],
-  "on-story-start": [],
-  "on-story-end": [],
-  "on-error": [],
-  "on-escalate": [],
-  "on-end": [],
-};
-
-const mockStatusWriter = {
-  setPrd: mock(() => {}),
-  setRunStatus: mock(() => {}),
-  setCurrentStory: mock(() => {}),
-  update: mock(async () => {}),
-};
-
-// ─────────────────────────────────────────────────────────────────────────────
-// RunLifecycle.teardown()
-// ─────────────────────────────────────────────────────────────────────────────
-
-describe("RunLifecycle.teardown", () => {
-  it("calls plugin teardownAll during teardown", async () => {
-    const teardownAllMock = mock(async () => {});
-    const mockPluginRegistry = {
-      teardownAll: teardownAllMock,
-      plugins: [],
-      getReporters: () => [],
-    } as any;
-
-    const lifecycle = new RunLifecycle(
-      "/tmp/prd.json",
-      "/tmp",
-      mockConfig,
-      mockHooks,
-      "test-feature",
-      false,
-      false,
-      // @ts-expect-error - partial mock
-      mockStatusWriter,
-      "run-001",
-      new Date().toISOString(),
-    );
-
-    await lifecycle.teardown({
-      runId: "run-001",
-      feature: "test-feature",
-      startedAt: new Date().toISOString(),
-      prd: { feature: "test-feature", userStories: [] },
-      allStoryMetrics: [],
-      totalCost: 0,
-      storiesCompleted: 0,
-      startTime: Date.now(),
-      workdir: "/tmp",
-      pluginRegistry: mockPluginRegistry,
-      statusWriter: mockStatusWriter as any,
-      iterations: 0,
-    });
-
-    expect(teardownAllMock).toHaveBeenCalledTimes(1);
-  });
-
-  it("updates status writer during teardown", async () => {
-    const mockPluginRegistry = {
-      teardownAll: async () => {},
-      plugins: [],
-      getReporters: () => [],
-    } as any;
-
-    const lifecycle = new RunLifecycle(
-      "/tmp/prd.json",
-      "/tmp",
-      mockConfig,
-      mockHooks,
-      "test-feature",
-      false,
-      false,
-      // @ts-expect-error - partial mock
-      mockStatusWriter,
-      "run-001",
-      new Date().toISOString(),
-    );
-
-    await lifecycle.teardown({
-      runId: "run-001",
-      feature: "test-feature",
-      startedAt: new Date().toISOString(),
-      prd: { feature: "test-feature", userStories: [] },
-      allStoryMetrics: [],
-      totalCost: 1.5,
-      storiesCompleted: 5,
-      startTime: Date.now(),
-      workdir: "/tmp",
-      pluginRegistry: mockPluginRegistry,
-      statusWriter: mockStatusWriter as any,
-      iterations: 10,
-    });
-
-    expect(mockStatusWriter.setPrd).toHaveBeenCalled();
-    expect(mockStatusWriter.setRunStatus).toHaveBeenCalled();
-    expect(mockStatusWriter.update).toHaveBeenCalled();
-  });
-});