@nathapp/nax 0.18.1

package/test/unit/helpers.test.ts

@@ -0,0 +1,317 @@
+/**
+ * Tests for src/execution/helpers.ts
+ *
+ * Covers: hookCtx, getAllReadyStories, acquireLock, releaseLock, formatProgress
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+  type StoryCounts,
+  acquireLock,
+  formatProgress,
+  getAllReadyStories,
+  hookCtx,
+  releaseLock,
+} from "../../src/execution/helpers";
+import type { PRD, UserStory } from "../../src/prd";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Test fixtures
+// ─────────────────────────────────────────────────────────────────────────────
+
+const mockStory = (
+  id: string,
+  passes: boolean,
+  status: "pending" | "skipped",
+  dependencies: string[] = [],
+): UserStory => ({
+  id,
+  title: `Story ${id}`,
+  description: `Description for ${id}`,
+  acceptanceCriteria: [],
+  dependencies,
+  passes,
+  status,
+  estimatedComplexity: "medium",
+});
+
+const createMockPRD = (stories: UserStory[]): PRD => ({
+  feature: "test-feature",
+  userStories: stories,
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// hookCtx
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("hookCtx", () => {
+  it("creates hook context with minimal args", () => {
+    const ctx = hookCtx("my-feature");
+    expect(ctx.event).toBe("on-start");
+    expect(ctx.feature).toBe("my-feature");
+  });
+
+  it("merges optional fields", () => {
+    const ctx = hookCtx("my-feature", {
+      storyId: "US-001",
+      cost: 0.42,
+    });
+    expect(ctx.event).toBe("on-start");
+    expect(ctx.feature).toBe("my-feature");
+    expect(ctx.storyId).toBe("US-001");
+    expect(ctx.cost).toBe(0.42);
+  });
+
+  it("overrides defaults with opts", () => {
+    const ctx = hookCtx("my-feature", {
+      storyId: "US-999",
+    });
+    expect(ctx.storyId).toBe("US-999");
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// getAllReadyStories
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("getAllReadyStories", () => {
+  it("returns pending stories with no dependencies", () => {
+    const prd = createMockPRD([mockStory("US-001", false, "pending"), mockStory("US-002", false, "pending")]);
+
+    const ready = getAllReadyStories(prd);
+    expect(ready.length).toBe(2);
+    expect(ready.map((s) => s.id)).toEqual(["US-001", "US-002"]);
+  });
+
+  it("excludes stories that already passed", () => {
+    const prd = createMockPRD([mockStory("US-001", true, "pending"), mockStory("US-002", false, "pending")]);
+
+    const ready = getAllReadyStories(prd);
+    expect(ready.length).toBe(1);
+    expect(ready[0].id).toBe("US-002");
+  });
+
+  it("excludes skipped stories", () => {
+    const prd = createMockPRD([mockStory("US-001", false, "skipped"), mockStory("US-002", false, "pending")]);
+
+    const ready = getAllReadyStories(prd);
+    expect(ready.length).toBe(1);
+    expect(ready[0].id).toBe("US-002");
+  });
+
+  it("includes stories whose dependencies are complete", () => {
+    const prd = createMockPRD([
+      mockStory("US-001", true, "pending"),
+      mockStory("US-002", false, "pending", ["US-001"]),
+    ]);
+
+    const ready = getAllReadyStories(prd);
+    expect(ready.length).toBe(1);
+    expect(ready[0].id).toBe("US-002");
+  });
+
+  it("excludes stories with unsatisfied dependencies", () => {
+    const prd = createMockPRD([
+      mockStory("US-001", false, "pending"),
+      mockStory("US-002", false, "pending", ["US-001"]),
+    ]);
+
+    const ready = getAllReadyStories(prd);
+    expect(ready.length).toBe(1);
+    expect(ready[0].id).toBe("US-001");
+  });
+
+  it("handles complex dependency chains", () => {
+    const prd = createMockPRD([
+      mockStory("US-001", true, "pending"),
+      mockStory("US-002", true, "pending", ["US-001"]),
+      mockStory("US-003", false, "pending", ["US-001", "US-002"]),
+      mockStory("US-004", false, "pending", ["US-002"]),
+    ]);
+
+    const ready = getAllReadyStories(prd);
+    expect(ready.length).toBe(2);
+    expect(ready.map((s) => s.id).sort()).toEqual(["US-003", "US-004"]);
+  });
+
+  it("returns empty array when all stories are complete", () => {
+    const prd = createMockPRD([mockStory("US-001", true, "pending"), mockStory("US-002", true, "pending")]);
+
+    const ready = getAllReadyStories(prd);
+    expect(ready.length).toBe(0);
+  });
+
+  it("handles skipped dependencies correctly", () => {
+    const prd = createMockPRD([
+      mockStory("US-001", false, "skipped"),
+      mockStory("US-002", false, "pending", ["US-001"]),
+    ]);
+
+    const ready = getAllReadyStories(prd);
+    // US-002 is ready because US-001 is skipped (treated as complete)
+    expect(ready.length).toBe(1);
+    expect(ready[0].id).toBe("US-002");
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// acquireLock / releaseLock
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("acquireLock / releaseLock", () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    // Create a temporary directory for lock tests
+    testDir = path.join(os.tmpdir(), `nax-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fs.mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    // Clean up lock file and test directory
+    await releaseLock(testDir);
+    try {
+      fs.rmSync(testDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  it("acquires lock when no lock exists", async () => {
+    const acquired = await acquireLock(testDir);
+    expect(acquired).toBe(true);
+
+    // Verify lock file was created
+    const lockPath = path.join(testDir, "nax.lock");
+    expect(fs.existsSync(lockPath)).toBe(true);
+  });
+
+  it("fails to acquire lock when already locked", async () => {
+    const first = await acquireLock(testDir);
+    expect(first).toBe(true);
+
+    const second = await acquireLock(testDir);
+    expect(second).toBe(false);
+  });
+
+  it("releases lock successfully", async () => {
+    await acquireLock(testDir);
+    await releaseLock(testDir);
+
+    // Verify lock file was removed
+    const lockPath = path.join(testDir, "nax.lock");
+    expect(fs.existsSync(lockPath)).toBe(false);
+  });
+
+  it("can reacquire lock after release", async () => {
+    const first = await acquireLock(testDir);
+    expect(first).toBe(true);
+
+    await releaseLock(testDir);
+
+    const second = await acquireLock(testDir);
+    expect(second).toBe(true);
+  });
+
+  it("removes stale lock from dead process", async () => {
+    // Create a lock with a non-existent PID
+    const lockPath = path.join(testDir, "nax.lock");
+    const staleLock = {
+      pid: 999999, // Non-existent process
+      timestamp: Date.now() - 1000000,
+    };
+    fs.writeFileSync(lockPath, JSON.stringify(staleLock));
+
+    // Should acquire lock by removing stale lock
+    const acquired = await acquireLock(testDir);
+    expect(acquired).toBe(true);
+  });
+
+  it("handles non-existent directory gracefully during release", async () => {
+    const nonExistentDir = path.join(os.tmpdir(), "nax-nonexistent");
+    await expect(releaseLock(nonExistentDir)).resolves.toBeUndefined();
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// formatProgress
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("formatProgress", () => {
+  it("formats progress with all stories pending", () => {
+    const counts: StoryCounts = {
+      total: 12,
+      passed: 0,
+      failed: 0,
+      pending: 12,
+    };
+
+    const progress = formatProgress(counts, 0, 5.0, 0, 12);
+    expect(progress).toContain("0/12 stories");
+    expect(progress).toContain("0 passed");
+    expect(progress).toContain("0 failed");
+    expect(progress).toContain("$0.00/$5.00");
+    expect(progress).toContain("calculating...");
+  });
+
+  it("formats progress with some completed stories", () => {
+    const counts: StoryCounts = {
+      total: 12,
+      passed: 5,
+      failed: 1,
+      pending: 6,
+    };
+
+    const progress = formatProgress(counts, 0.45, 5.0, 600000, 12);
+    expect(progress).toContain("6/12 stories");
+    expect(progress).toContain("5 passed");
+    expect(progress).toContain("1 failed");
+    expect(progress).toContain("$0.45/$5.00");
+    expect(progress).toContain("min remaining");
+  });
+
+  it("formats progress when all stories complete", () => {
+    const counts: StoryCounts = {
+      total: 12,
+      passed: 10,
+      failed: 2,
+      pending: 0,
+    };
+
+    const progress = formatProgress(counts, 4.5, 5.0, 3600000, 12);
+    expect(progress).toContain("12/12 stories");
+    expect(progress).toContain("10 passed");
+    expect(progress).toContain("2 failed");
+    expect(progress).toContain("$4.50/$5.00");
+    expect(progress).toContain("complete");
+  });
+
+  it("calculates ETA correctly", () => {
+    const counts: StoryCounts = {
+      total: 10,
+      passed: 5,
+      failed: 0,
+      pending: 5,
+    };
+
+    // 5 completed in 600000ms (10 minutes) = 120000ms per story
+    // 5 remaining = 600000ms (10 minutes)
+    const progress = formatProgress(counts, 1.0, 5.0, 600000, 10);
+    expect(progress).toContain("~10 min remaining");
+  });
+
+  it("handles zero elapsed time", () => {
+    const counts: StoryCounts = {
+      total: 10,
+      passed: 1,
+      failed: 0,
+      pending: 9,
+    };
+
+    const progress = formatProgress(counts, 0.1, 5.0, 0, 10);
+    expect(progress).toContain("~0 min remaining");
+  });
+});

package/test/unit/interaction/human-review-trigger.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Unit Tests: human-review trigger (BUG-025)
+ *
+ * Verifies that 'human-review' is added to TriggerName and TRIGGER_METADATA,
+ * and that createTriggerRequest/executeTrigger work with this new trigger.
+ *
+ * These tests FAIL until BUG-025 is implemented.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+import type { NaxConfig } from "../../../src/config";
+import { InteractionChain } from "../../../src/interaction/chain";
+import type { InteractionPlugin, InteractionResponse, TriggerName } from "../../../src/interaction/types";
+import { TRIGGER_METADATA } from "../../../src/interaction/types";
+import { createTriggerRequest, executeTrigger } from "../../../src/interaction/triggers";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Fixtures
+// ─────────────────────────────────────────────────────────────────────────────
+
+const minimalConfig = {
+  interaction: {
+    triggers: {
+      "human-review": { enabled: true },
+    },
+    defaults: {
+      timeout: 30000,
+      fallback: "skip" as const,
+    },
+  },
+} as unknown as NaxConfig;
+
+function makeSkipPlugin(requestId: string): InteractionPlugin {
+  return {
+    name: "test-skip",
+    send: mock(async () => {}),
+    receive: mock(async (_id: string): Promise<InteractionResponse> => ({
+      requestId,
+      action: "skip",
+      respondedBy: "user",
+      respondedAt: Date.now(),
+    })),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TRIGGER_METADATA — must include 'human-review'
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TRIGGER_METADATA — human-review", () => {
+  test("TRIGGER_METADATA contains 'human-review' key", () => {
+    // FAILS until BUG-025 adds 'human-review' to TRIGGER_METADATA
+    const allTriggers = Object.keys(TRIGGER_METADATA);
+    expect(allTriggers).toContain("human-review");
+  });
+
+  test("human-review metadata has defaultFallback of 'skip'", () => {
+    // FAILS until BUG-025 adds 'human-review' to TRIGGER_METADATA
+    const meta = (TRIGGER_METADATA as Record<string, (typeof TRIGGER_METADATA)[TriggerName]>)["human-review"];
+    expect(meta).toBeDefined();
+    expect(meta?.defaultFallback).toBe("skip");
+  });
+
+  test("human-review metadata has safety tier of 'yellow'", () => {
+    // FAILS until BUG-025 adds 'human-review' to TRIGGER_METADATA
+    const meta = (TRIGGER_METADATA as Record<string, (typeof TRIGGER_METADATA)[TriggerName]>)["human-review"];
+    expect(meta).toBeDefined();
+    expect(meta?.safety).toBe("yellow");
+  });
+
+  test("human-review metadata has a non-empty defaultSummary", () => {
+    // FAILS until BUG-025 adds 'human-review' to TRIGGER_METADATA
+    const meta = (TRIGGER_METADATA as Record<string, (typeof TRIGGER_METADATA)[TriggerName]>)["human-review"];
+    expect(meta).toBeDefined();
+    expect(typeof meta?.defaultSummary).toBe("string");
+    expect(meta?.defaultSummary.length).toBeGreaterThan(0);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// createTriggerRequest — accepts 'human-review'
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("createTriggerRequest — human-review", () => {
+  test("creates a valid request for human-review trigger", () => {
+    // FAILS until BUG-025 adds 'human-review' to TriggerName and TRIGGER_METADATA
+    const request = createTriggerRequest(
+      "human-review" as TriggerName,
+      { featureName: "my-feature", storyId: "US-001", iteration: 3 },
+      minimalConfig,
+    );
+
+    expect(request.id).toContain("human-review");
+    expect(request.featureName).toBe("my-feature");
+    expect(request.storyId).toBe("US-001");
+    expect(request.type).toBe("confirm");
+    expect(request.fallback).toBe("skip");
+  });
+
+  test("human-review request summary contains storyId when provided", () => {
+    // FAILS until BUG-025 adds 'human-review' to TRIGGER_METADATA with {{storyId}} in summary
+    const request = createTriggerRequest(
+      "human-review" as TriggerName,
+      { featureName: "my-feature", storyId: "US-042" },
+      minimalConfig,
+    );
+
+    // Summary should contain the story ID for human readability
+    expect(request.summary).toContain("US-042");
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// executeTrigger — 'human-review' flows through chain
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("executeTrigger — human-review", () => {
+  test("executeTrigger sends human-review request through chain and returns response", async () => {
+    // FAILS until BUG-025 adds 'human-review' to TriggerName + TRIGGER_METADATA
+    const chain = new InteractionChain({ defaultTimeout: 5000, defaultFallback: "skip" });
+    const plugin = makeSkipPlugin("trigger-human-review-test");
+    chain.register(plugin, 10);
+
+    const response = await executeTrigger(
+      "human-review" as TriggerName,
+      { featureName: "my-feature", storyId: "US-001" },
+      minimalConfig,
+      chain,
+    );
+
+    expect(response).toBeDefined();
+    expect(response.action).toBe("skip");
+    expect(plugin.send).toHaveBeenCalledTimes(1);
+    expect(plugin.receive).toHaveBeenCalledTimes(1);
+  });
+
+  test("executeTrigger request metadata includes trigger name and safety", async () => {
+    // FAILS until BUG-025 adds 'human-review' to TriggerName + TRIGGER_METADATA
+    const sentRequests: unknown[] = [];
+    const chain = new InteractionChain({ defaultTimeout: 5000, defaultFallback: "skip" });
+    const plugin: InteractionPlugin = {
+      name: "capture",
+      send: mock(async (req) => { sentRequests.push(req); }),
+      receive: mock(async (_id: string): Promise<InteractionResponse> => ({
+        requestId: _id,
+        action: "skip",
+        respondedAt: Date.now(),
+      })),
+    };
+    chain.register(plugin, 10);
+
+    await executeTrigger(
+      "human-review" as TriggerName,
+      { featureName: "my-feature", storyId: "US-007" },
+      minimalConfig,
+      chain,
+    );
+
+    expect(sentRequests.length).toBe(1);
+    const req = sentRequests[0] as { metadata?: { trigger?: string; safety?: string } };
+    expect(req.metadata?.trigger).toBe("human-review");
+    expect(req.metadata?.safety).toBe("yellow");
+  });
+});