@nathapp/nax 0.18.1

package/test/integration/config-loader.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Config Loader Tests
+ *
+ * Tests backward compatibility mapping of batchMode to mode enum.
+ *
+ * NOTE: The backward compat feature (loader.ts line 94-107) has a known limitation:
+ * The check `!("mode" in llm)` always fails because DEFAULT_CONFIG has mode:"hybrid",
+ * which gets merged before the backward compat check runs. This means batchMode->mode
+ * mapping never actually happens unless the user provides an invalid mode value that
+ * fails Zod validation, or unless they avoid the defaults entirely (global config).
+ *
+ * These tests document the ACTUAL behavior, not the intended behavior.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, renameSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { globalConfigPath, loadConfig } from "../../src/config/loader";
+
+describe("Config Loader - Backward Compatibility", () => {
+  let tempDir: string;
+  let globalBackup: string | null = null;
+
+  beforeEach(() => {
+    // Create a temporary test directory
+    tempDir = join(tmpdir(), `nax-test-${Date.now()}`);
+    mkdirSync(join(tempDir, "nax"), { recursive: true });
+
+    // Backup existing global config if present
+    const globalPath = globalConfigPath();
+    if (existsSync(globalPath)) {
+      globalBackup = `${globalPath}.test-backup-${Date.now()}`;
+      renameSync(globalPath, globalBackup);
+    }
+  });
+
+  afterEach(() => {
+    // Clean up temp directory
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+
+    // Restore global config if we backed it up
+    if (globalBackup && existsSync(globalBackup)) {
+      const globalPath = globalConfigPath();
+      if (existsSync(globalPath)) {
+        rmSync(globalPath);
+      }
+      renameSync(globalBackup, globalPath);
+      globalBackup = null;
+    }
+  });
+
+  test("batchMode:true maps to mode:one-shot (backward compat)", async () => {
+    const configPath = join(tempDir, "nax", "config.json");
+    const testConfig = {
+      routing: {
+        strategy: "llm",
+        llm: {
+          batchMode: true,
+          // mode not specified - should map from batchMode before default merge
+        },
+      },
+    };
+    writeFileSync(configPath, JSON.stringify(testConfig, null, 2));
+
+    const config = await loadConfig(join(tempDir, "nax"));
+
+    // applyBatchModeCompat runs on raw projConf before deepMerge with defaults,
+    // so batchMode:true correctly maps to mode:"one-shot" overriding DEFAULT_CONFIG's "hybrid"
+    expect(config.routing.llm?.mode).toBe("one-shot");
+    expect(config.routing.llm?.batchMode).toBe(true);
+  });
+
+  test("explicit mode takes precedence over batchMode", async () => {
+    const configPath = join(tempDir, "nax", "config.json");
+    const testConfig = {
+      routing: {
+        strategy: "llm",
+        llm: {
+          batchMode: true,
+          mode: "per-story", // Explicit mode overrides batchMode
+        },
+      },
+    };
+    writeFileSync(configPath, JSON.stringify(testConfig, null, 2));
+
+    const config = await loadConfig(join(tempDir, "nax"));
+
+    // Explicit mode is used, batchMode is ignored
+    expect(config.routing.llm?.mode).toBe("per-story");
+    expect(config.routing.llm?.batchMode).toBe(true);
+  });
+
+  test("rejects invalid batchMode value", async () => {
+    const configPath = join(tempDir, "nax", "config.json");
+    const testConfig = {
+      routing: {
+        strategy: "llm",
+        llm: {
+          batchMode: "yes", // Invalid - must be boolean
+        },
+      },
+    };
+    writeFileSync(configPath, JSON.stringify(testConfig, null, 2));
+
+    // Should throw validation error because Zod expects boolean
+    await expect(loadConfig(join(tempDir, "nax"))).rejects.toThrow("Invalid configuration");
+  });
+
+  test("uses DEFAULT_CONFIG mode when user config has no routing.llm", async () => {
+    const configPath = join(tempDir, "nax", "config.json");
+    const testConfig = {
+      routing: {
+        strategy: "keyword", // Different strategy, no llm config
+      },
+    };
+    writeFileSync(configPath, JSON.stringify(testConfig, null, 2));
+
+    const config = await loadConfig(join(tempDir, "nax"));
+
+    // Should get "hybrid" from DEFAULT_CONFIG.routing.llm.mode
+    expect(config.routing.llm?.mode).toBe("hybrid");
+  });
+});
+
+describe("Config Loader - Plugin Configuration (US-007)", () => {
+  let tempDir: string;
+  let globalBackup: string | null = null;
+
+  beforeEach(() => {
+    // Create a temporary test directory
+    tempDir = join(tmpdir(), `nax-test-plugins-${Date.now()}`);
+    mkdirSync(join(tempDir, "nax"), { recursive: true });
+
+    // Backup existing global config if present
+    const globalPath = globalConfigPath();
+    if (existsSync(globalPath)) {
+      globalBackup = `${globalPath}.test-backup-${Date.now()}`;
+      renameSync(globalPath, globalBackup);
+    }
+  });
+
+  afterEach(() => {
+    // Clean up temp directory
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+
+    // Restore global config if we backed it up
+    if (globalBackup && existsSync(globalBackup)) {
+      const globalPath = globalConfigPath();
+      if (existsSync(globalPath)) {
+        rmSync(globalPath);
+      }
+      renameSync(globalBackup, globalPath);
+      globalBackup = null;
+    }
+  });
+
+  test("loads plugins[] from config.json", async () => {
+    const configPath = join(tempDir, "nax", "config.json");
+    const testConfig = {
+      plugins: [
+        {
+          module: "./custom-plugins/my-plugin.ts",
+          config: {
+            apiKey: "test-123",
+            enabled: true,
+          },
+        },
+        {
+          module: "npm-plugin-package",
+          config: {
+            timeout: 5000,
+          },
+        },
+      ],
+    };
+    writeFileSync(configPath, JSON.stringify(testConfig, null, 2));
+
+    const config = await loadConfig(join(tempDir, "nax"));
+
+    // Verify plugins array is loaded
+    expect(config.plugins).toBeDefined();
+    expect(config.plugins).toHaveLength(2);
+    expect(config.plugins?.[0].module).toBe("./custom-plugins/my-plugin.ts");
+    expect(config.plugins?.[0].config).toEqual({
+      apiKey: "test-123",
+      enabled: true,
+    });
+    expect(config.plugins?.[1].module).toBe("npm-plugin-package");
+    expect(config.plugins?.[1].config).toEqual({
+      timeout: 5000,
+    });
+  });
+
+  test("handles missing plugins[] array (defaults to undefined)", async () => {
+    const configPath = join(tempDir, "nax", "config.json");
+    const testConfig = {
+      routing: {
+        strategy: "keyword",
+      },
+    };
+    writeFileSync(configPath, JSON.stringify(testConfig, null, 2));
+
+    const config = await loadConfig(join(tempDir, "nax"));
+
+    // plugins[] is optional, should be undefined if not provided
+    expect(config.plugins).toBeUndefined();
+  });
+
+  test("merges plugins[] from global and project config", async () => {
+    // Create global config with plugins
+    const globalPath = globalConfigPath();
+    mkdirSync(join(homedir(), ".nax"), { recursive: true });
+    const globalConfig = {
+      plugins: [
+        {
+          module: "global-plugin",
+          config: { global: true },
+        },
+      ],
+    };
+    writeFileSync(globalPath, JSON.stringify(globalConfig, null, 2));
+
+    // Create project config with plugins
+    const projectPath = join(tempDir, "nax", "config.json");
+    const projectConfig = {
+      plugins: [
+        {
+          module: "project-plugin",
+          config: { project: true },
+        },
+      ],
+    };
+    writeFileSync(projectPath, JSON.stringify(projectConfig, null, 2));
+
+    const config = await loadConfig(join(tempDir, "nax"));
+
+    // Verify plugins are merged (project overrides global)
+    expect(config.plugins).toBeDefined();
+    expect(config.plugins).toHaveLength(1);
+    expect(config.plugins?.[0].module).toBe("project-plugin");
+  });
+
+  test("validates plugin config entries have required fields", async () => {
+    const configPath = join(tempDir, "nax", "config.json");
+    const testConfig = {
+      plugins: [
+        {
+          // Missing module field
+          config: { foo: "bar" },
+        },
+      ],
+    };
+    writeFileSync(configPath, JSON.stringify(testConfig, null, 2));
+
+    // Should throw validation error
+    await expect(loadConfig(join(tempDir, "nax"))).rejects.toThrow("Invalid configuration");
+  });
+});

package/test/integration/config.test.ts

@@ -0,0 +1,444 @@
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_CONFIG, NaxConfigSchema } from "../../src/config/schema";
+import type { TddStrategy, TestStrategy } from "../../src/config/schema";
+
+describe("Config Validation", () => {
+  test("accepts valid default config", () => {
+    const result = NaxConfigSchema.safeParse(DEFAULT_CONFIG);
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects invalid version", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      version: 2, // Invalid version
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      const errorMessages = result.error.issues.map((e) => e.message);
+      expect(errorMessages.some((msg) => msg.includes("Invalid version"))).toBe(true);
+    }
+  });
+
+  test("rejects maxIterations <= 0", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      execution: {
+        ...DEFAULT_CONFIG.execution,
+        maxIterations: 0,
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      const errorMessages = result.error.issues.map((e) => e.message);
+      expect(errorMessages.some((e) => e.includes("maxIterations must be > 0"))).toBe(true);
+    }
+  });
+
+  test("rejects costLimit <= 0", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      execution: {
+        ...DEFAULT_CONFIG.execution,
+        costLimit: -1,
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      const errorMessages = result.error.issues.map((e) => e.message);
+      expect(errorMessages.some((e) => e.includes("costLimit must be > 0"))).toBe(true);
+    }
+  });
+
+  test("rejects sessionTimeoutSeconds <= 0", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      execution: {
+        ...DEFAULT_CONFIG.execution,
+        sessionTimeoutSeconds: 0,
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      const errorMessages = result.error.issues.map((e) => e.message);
+      expect(errorMessages.some((e) => e.includes("sessionTimeoutSeconds must be > 0"))).toBe(true);
+    }
+  });
+
+  test("rejects empty defaultAgent", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      autoMode: {
+        ...DEFAULT_CONFIG.autoMode,
+        defaultAgent: "",
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      const errorMessages = result.error.issues.map((e) => e.message);
+      expect(errorMessages.some((msg) => msg.includes("defaultAgent must be non-empty"))).toBe(true);
+    }
+  });
+
+  test("rejects whitespace-only defaultAgent", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      autoMode: {
+        ...DEFAULT_CONFIG.autoMode,
+        defaultAgent: "   ",
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+    // Zod's min(1) validation will trim and reject whitespace
+  });
+
+  test("rejects empty tierOrder", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      autoMode: {
+        ...DEFAULT_CONFIG.autoMode,
+        escalation: {
+          ...DEFAULT_CONFIG.autoMode.escalation,
+          tierOrder: [],
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      const errorMessages = result.error.issues.map((e) => e.message);
+      expect(errorMessages.some((e) => e.includes("tierOrder must have at least one tier"))).toBe(true);
+    }
+  });
+
+  test("rejects tierOrder with attempts out of range", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      autoMode: {
+        ...DEFAULT_CONFIG.autoMode,
+        escalation: {
+          ...DEFAULT_CONFIG.autoMode.escalation,
+          tierOrder: [{ tier: "fast", attempts: 0 }],
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+  });
+
+  test("accepts custom tier names in tierOrder", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      autoMode: {
+        ...DEFAULT_CONFIG.autoMode,
+        escalation: {
+          ...DEFAULT_CONFIG.autoMode.escalation,
+          tierOrder: [
+            { tier: "free", attempts: 10 },
+            { tier: "ultra", attempts: 1 },
+          ],
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+  });
+
+  test("collects multiple validation errors", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      version: 99,
+      execution: {
+        ...DEFAULT_CONFIG.execution,
+        maxIterations: 0,
+        costLimit: -5,
+      },
+      autoMode: {
+        ...DEFAULT_CONFIG.autoMode,
+        defaultAgent: "",
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues.length).toBeGreaterThanOrEqual(4);
+    }
+  });
+
+  test("accepts any non-empty string as complexityRouting tier", () => {
+    // Tiers are now extensible (z.string), validated against models at runtime
+    const config = {
+      ...DEFAULT_CONFIG,
+      autoMode: {
+        ...DEFAULT_CONFIG.autoMode,
+        complexityRouting: {
+          ...DEFAULT_CONFIG.autoMode.complexityRouting,
+          simple: "custom-tier",
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects empty string as complexityRouting tier", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      autoMode: {
+        ...DEFAULT_CONFIG.autoMode,
+        complexityRouting: {
+          ...DEFAULT_CONFIG.autoMode.complexityRouting,
+          simple: "",
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+  });
+
+  test("accepts all valid tiers in complexityRouting", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      autoMode: {
+        ...DEFAULT_CONFIG.autoMode,
+        complexityRouting: {
+          simple: "fast",
+          medium: "balanced",
+          complex: "powerful",
+          expert: "powerful",
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+  });
+
+  test("validates verificationTimeoutSeconds bounds", () => {
+    const tooLow = {
+      ...DEFAULT_CONFIG,
+      execution: { ...DEFAULT_CONFIG.execution, verificationTimeoutSeconds: 0 },
+    };
+    expect(NaxConfigSchema.safeParse(tooLow).success).toBe(false);
+
+    const tooHigh = {
+      ...DEFAULT_CONFIG,
+      execution: { ...DEFAULT_CONFIG.execution, verificationTimeoutSeconds: 7200 },
+    };
+    expect(NaxConfigSchema.safeParse(tooHigh).success).toBe(false);
+
+    const valid = {
+      ...DEFAULT_CONFIG,
+      execution: { ...DEFAULT_CONFIG.execution, verificationTimeoutSeconds: 120 },
+    };
+    expect(NaxConfigSchema.safeParse(valid).success).toBe(true);
+  });
+
+  test("validates quality config extensions", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      quality: {
+        ...DEFAULT_CONFIG.quality,
+        forceExit: true,
+        detectOpenHandles: false,
+        detectOpenHandlesRetries: 3,
+        gracePeriodMs: 10000,
+        drainTimeoutMs: 5000,
+        shell: "/bin/bash",
+        stripEnvVars: ["CLAUDECODE", "CUSTOM_VAR"],
+        environmentalEscalationDivisor: 3,
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("LLM Routing Mode Config", () => {
+  test("accepts one-shot mode", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      routing: {
+        ...DEFAULT_CONFIG.routing,
+        llm: {
+          mode: "one-shot" as const,
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.routing.llm?.mode).toBe("one-shot");
+    }
+  });
+
+  test("accepts per-story mode", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      routing: {
+        ...DEFAULT_CONFIG.routing,
+        llm: {
+          mode: "per-story" as const,
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.routing.llm?.mode).toBe("per-story");
+    }
+  });
+
+  test("accepts hybrid mode", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      routing: {
+        ...DEFAULT_CONFIG.routing,
+        llm: {
+          mode: "hybrid" as const,
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.routing.llm?.mode).toBe("hybrid");
+    }
+  });
+
+  test("rejects invalid mode value", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      routing: {
+        ...DEFAULT_CONFIG.routing,
+        llm: {
+          mode: "ultra-batch",
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+  });
+
+  test("defaults to hybrid when mode not specified", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      routing: {
+        ...DEFAULT_CONFIG.routing,
+        strategy: "llm" as const,
+        llm: {
+          cacheDecisions: true,
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+    // Default is applied by loader, schema allows undefined
+    expect(result.data.routing.llm?.mode).toBeUndefined();
+  });
+
+  test("accepts deprecated batchMode alongside mode", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      routing: {
+        ...DEFAULT_CONFIG.routing,
+        llm: {
+          mode: "one-shot" as const,
+          batchMode: true,
+        },
+      },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.routing.llm?.mode).toBe("one-shot");
+      expect(result.data.routing.llm?.batchMode).toBe(true);
+    }
+  });
+});
+
+describe("TDD Strategy Config", () => {
+  test("TestStrategy type includes three-session-tdd-lite", () => {
+    // Type-level check: ensure 'three-session-tdd-lite' is assignable to TestStrategy
+    const strategy: TestStrategy = "three-session-tdd-lite";
+    expect(strategy).toBe("three-session-tdd-lite");
+  });
+
+  test("TddStrategy type alias covers all four values", () => {
+    const strategies: TddStrategy[] = ["auto", "strict", "lite", "off"];
+    expect(strategies).toHaveLength(4);
+  });
+
+  test("default config has strategy: auto", () => {
+    expect(DEFAULT_CONFIG.tdd.strategy).toBe("auto");
+  });
+
+  test("default config parses successfully", () => {
+    const result = NaxConfigSchema.safeParse(DEFAULT_CONFIG);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.tdd.strategy).toBe("auto");
+    }
+  });
+
+  test("accepts strategy: strict", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      tdd: { ...DEFAULT_CONFIG.tdd, strategy: "strict" as const },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.tdd.strategy).toBe("strict");
+    }
+  });
+
+  test("accepts strategy: lite", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      tdd: { ...DEFAULT_CONFIG.tdd, strategy: "lite" as const },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.tdd.strategy).toBe("lite");
+    }
+  });
+
+  test("accepts strategy: off", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      tdd: { ...DEFAULT_CONFIG.tdd, strategy: "off" as const },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.tdd.strategy).toBe("off");
+    }
+  });
+
+  test("rejects invalid strategy value", () => {
+    const config = {
+      ...DEFAULT_CONFIG,
+      tdd: { ...DEFAULT_CONFIG.tdd, strategy: "invalid-strategy" },
+    };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(false);
+  });
+
+  test("backward compat: config without strategy field defaults to auto", () => {
+    // Simulate a config file that was written before strategy was added (no strategy key)
+    const { strategy: _omitted, ...tddWithoutStrategy } = DEFAULT_CONFIG.tdd;
+    const config = { ...DEFAULT_CONFIG, tdd: tddWithoutStrategy };
+    const result = NaxConfigSchema.safeParse(config);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.tdd.strategy).toBe("auto");
+    }
+  });
+});