@nathapp/nax 0.18.1

package/src/config/defaults.ts

@@ -0,0 +1,160 @@
+/**
+ * Default Configuration
+ *
+ * The default NaxConfig used as a base for all projects.
+ */
+
+import type { NaxConfig } from "./types";
+
+/** Default configuration */
+export const DEFAULT_CONFIG: NaxConfig = {
+  version: 1,
+  models: {
+    fast: { provider: "anthropic", model: "haiku" },
+    balanced: { provider: "anthropic", model: "sonnet" },
+    powerful: { provider: "anthropic", model: "opus" },
+  },
+  autoMode: {
+    enabled: true,
+    defaultAgent: "claude",
+    fallbackOrder: ["claude", "codex", "opencode", "gemini"],
+    complexityRouting: {
+      simple: "fast",
+      medium: "balanced",
+      complex: "powerful",
+      expert: "powerful",
+    },
+    escalation: {
+      enabled: true,
+      tierOrder: [
+        { tier: "fast", attempts: 5 },
+        { tier: "balanced", attempts: 3 },
+        { tier: "powerful", attempts: 2 },
+      ],
+      escalateEntireBatch: true,
+    },
+  },
+  routing: {
+    strategy: "keyword",
+    adaptive: {
+      minSamples: 10,
+      costThreshold: 0.8,
+      fallbackStrategy: "llm",
+    },
+    llm: {
+      model: "fast",
+      fallbackToKeywords: true,
+      cacheDecisions: true,
+      mode: "hybrid",
+      timeoutMs: 15000,
+    },
+  },
+  execution: {
+    maxIterations: 10, // auto-calculated: sum of tier attempts (5+3+2=10)
+    iterationDelayMs: 2000,
+    costLimit: 5.0,
+    sessionTimeoutSeconds: 600, // 10 minutes
+    verificationTimeoutSeconds: 300, // 5 minutes
+    maxStoriesPerFeature: 500,
+    rectification: {
+      enabled: true,
+      maxRetries: 2,
+      fullSuiteTimeoutSeconds: 120,
+      maxFailureSummaryChars: 2000,
+      abortOnIncreasingFailures: true,
+    },
+    regressionGate: {
+      enabled: true,
+      timeoutSeconds: 120,
+    },
+    contextProviderTokenBudget: 2000,
+  },
+  quality: {
+    requireTypecheck: true,
+    requireLint: true,
+    requireTests: true,
+    commands: {},
+    forceExit: false,
+    detectOpenHandles: true,
+    detectOpenHandlesRetries: 1,
+    gracePeriodMs: 5000,
+    drainTimeoutMs: 2000,
+    shell: "/bin/sh",
+    stripEnvVars: ["CLAUDECODE", "REPL_ID", "AGENT"],
+    environmentalEscalationDivisor: 2,
+  },
+  tdd: {
+    maxRetries: 2,
+    autoVerifyIsolation: true,
+    autoApproveVerifier: true,
+    strategy: "auto",
+    sessionTiers: {
+      testWriter: "balanced",
+      // implementer: undefined = uses story's routed tier
+      verifier: "fast",
+    },
+    testWriterAllowedPaths: ["src/index.ts", "src/**/index.ts"],
+    rollbackOnFailure: true,
+    greenfieldDetection: true,
+  },
+  constitution: {
+    enabled: true,
+    path: "constitution.md",
+    maxTokens: 2000,
+  },
+  analyze: {
+    llmEnhanced: true,
+    model: "balanced",
+    fallbackToKeywords: true,
+    maxCodebaseSummaryTokens: 5000,
+  },
+  review: {
+    enabled: true,
+    checks: ["typecheck", "lint", "test"],
+    commands: {},
+  },
+  plan: {
+    model: "balanced",
+    outputPath: "spec.md",
+  },
+  acceptance: {
+    enabled: true,
+    maxRetries: 2,
+    generateTests: true,
+    testPath: "acceptance.test.ts",
+  },
+  context: {
+    testCoverage: {
+      enabled: true,
+      detail: "names-and-counts",
+      maxTokens: 500,
+      testPattern: "**/*.test.{ts,js,tsx,jsx}",
+      scopeToStory: true,
+    },
+    autoDetect: {
+      enabled: true,
+      maxFiles: 5,
+      traceImports: false,
+    },
+  },
+  interaction: {
+    plugin: "cli",
+    config: {},
+    defaults: {
+      timeout: 600000, // 10 minutes
+      fallback: "escalate",
+    },
+    triggers: {
+      "security-review": true,
+      "cost-warning": true,
+    },
+  },
+  precheck: {
+    storySizeGate: {
+      enabled: true,
+      maxAcCount: 6,
+      maxDescriptionLength: 2000,
+      maxBulletPoints: 8,
+    },
+  },
+};

package/src/config/index.ts

@@ -0,0 +1,22 @@
+export type {
+  NaxConfig,
+  Complexity,
+  TestStrategy,
+  TddStrategy,
+  ModelTier,
+  ModelDef,
+  ModelEntry,
+  ModelMap,
+  AutoModeConfig,
+  ExecutionConfig,
+  QualityConfig,
+  TddConfig,
+  TierConfig,
+  RectificationConfig,
+} from "./schema";
+export { DEFAULT_CONFIG, resolveModel, NaxConfigSchema } from "./schema";
+export { loadConfig, findProjectDir, globalConfigPath } from "./loader";
+export { validateConfig, type ValidationResult } from "./validate"; // @deprecated: Use NaxConfigSchema.safeParse() instead
+export { validateDirectory, validateFilePath, isWithinDirectory, MAX_DIRECTORY_DEPTH } from "./path-security";
+export { globalConfigDir, projectConfigDir } from "./paths";
+export { deepMergeConfig } from "./merger";

package/src/config/loader.ts

@@ -0,0 +1,121 @@
+/**
+ * Configuration Loader
+ *
+ * Merges global + project config with defaults.
+ */
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getLogger } from "../logger";
+import { deepMergeConfig } from "./merger";
+import { MAX_DIRECTORY_DEPTH } from "./path-security";
+import { globalConfigDir, projectConfigDir } from "./paths";
+import { DEFAULT_CONFIG, type NaxConfig, NaxConfigSchema } from "./schema";
+
+/** Global config path */
+export function globalConfigPath(): string {
+  return join(globalConfigDir(), "config.json");
+}
+
+/** Find project nax directory (walks up from cwd) */
+export function findProjectDir(startDir: string = process.cwd()): string | null {
+  let dir = resolve(startDir);
+  let depth = 0;
+
+  while (depth < MAX_DIRECTORY_DEPTH) {
+    const candidate = join(dir, "nax");
+    if (existsSync(join(candidate, "config.json"))) {
+      return candidate;
+    }
+    const parent = join(dir, "..");
+    if (parent === dir) break; // Root reached
+    dir = parent;
+    depth++;
+  }
+
+  return null;
+}
+
+/** Load and parse a JSON config file */
+async function loadJsonFile<T>(path: string): Promise<T | null> {
+  if (!existsSync(path)) return null;
+  try {
+    return await Bun.file(path).json();
+  } catch (err) {
+    const logger = getLogger();
+    logger.warn("config", "Failed to parse config file", { path, error: String(err) });
+    return null;
+  }
+}
+
+/** @internal Backward compat: map deprecated routing.llm.batchMode to routing.llm.mode.
+ * Returns a new object (immutable -- does not mutate the input). */
+function applyBatchModeCompat(conf: Record<string, unknown>): Record<string, unknown> {
+  const routing = conf.routing as Record<string, unknown> | undefined;
+  const llm = routing?.llm as Record<string, unknown> | undefined;
+  if (llm && "batchMode" in llm && !("mode" in llm)) {
+    const batchMode = llm.batchMode;
+    if (typeof batchMode === "boolean") {
+      const mappedMode = batchMode ? "one-shot" : "per-story";
+      try {
+        getLogger().warn(
+          "config",
+          `routing.llm.batchMode is deprecated and will be removed in v1.0. Mapped to mode="${mappedMode}". Update your config to use routing.llm.mode instead.`,
+        );
+      } catch {
+        /* logger may not be init yet */
+      }
+      return {
+        ...conf,
+        routing: {
+          ...routing,
+          llm: { ...llm, mode: mappedMode },
+        },
+      };
+    }
+  }
+  return conf;
+}
+
+/** Load merged configuration (defaults < global < project < CLI overrides) */
+export async function loadConfig(projectDir?: string, cliOverrides?: Record<string, unknown>): Promise<NaxConfig> {
+  // Start with defaults as a plain object
+  let rawConfig: Record<string, unknown> = structuredClone(DEFAULT_CONFIG as unknown as Record<string, unknown>);
+
+  // Layer 1: Global config (~/.nax/config.json)
+  const globalConfRaw = await loadJsonFile<Record<string, unknown>>(globalConfigPath());
+  if (globalConfRaw) {
+    // Backward compatibility: apply batchMode->mode shim before merge so defaults don't shadow it
+    const globalConf = applyBatchModeCompat(globalConfRaw);
+    rawConfig = deepMergeConfig(rawConfig, globalConf);
+  }
+
+  // Layer 2: Project config (nax/config.json)
+  const projDir = projectDir ?? findProjectDir();
+  if (projDir) {
+    const projConf = await loadJsonFile<Record<string, unknown>>(join(projDir, "config.json"));
+    if (projConf) {
+      // Backward compatibility: map deprecated batchMode -> mode on raw user config
+      // MUST run before deepMergeConfig so defaults don't shadow the check.
+      const resolvedProjConf = applyBatchModeCompat(projConf);
+      rawConfig = deepMergeConfig(rawConfig, resolvedProjConf);
+    }
+  }
+
+  // Layer 3: CLI overrides (highest priority)
+  if (cliOverrides) {
+    rawConfig = deepMergeConfig(rawConfig, cliOverrides);
+  }
+
+  // Parse and validate with Zod
+  const result = NaxConfigSchema.safeParse(rawConfig);
+  if (!result.success) {
+    const errors = result.error.issues.map((err) => {
+      const path = String(err.path.join("."));
+      return path ? `${path}: ${err.message}` : err.message;
+    });
+    throw new Error(`Invalid configuration:\n${errors.join("\n")}`);
+  }
+
+  return result.data as NaxConfig;
+}

package/src/config/merger.ts

@@ -0,0 +1,147 @@
+/**
+ * Configuration Merger Utility
+ *
+ * Deep merge utility for NaxConfig with special handling:
+ * - Arrays: replace (not merge)
+ * - Null values: remove keys
+ * - Hooks: concatenate from both configs
+ * - Constitution content: concatenate with newline separator
+ */
+
+import type { NaxConfig } from "./schema";
+
+/**
+ * Deep merge two configuration objects.
+ *
+ * Rules:
+ * - Objects are merged recursively
+ * - Arrays replace (override completely replaces base)
+ * - Null values in override remove the key from result
+ * - Undefined values in override are skipped
+ * - Hooks are concatenated (both base and override hooks preserved)
+ * - Constitution content is concatenated with newline separator
+ *
+ * @param base - Base configuration object
+ * @param override - Override configuration object
+ * @returns New merged configuration (immutable - does not mutate inputs)
+ */
+export function deepMergeConfig<T = NaxConfig>(base: Record<string, unknown>, override: Record<string, unknown>): T {
+  // Start with a clone of base to ensure immutability
+  const result: Record<string, unknown> = { ...base };
+
+  for (const key of Object.keys(override)) {
+    const overrideValue = override[key];
+
+    // Skip undefined values
+    if (overrideValue === undefined) {
+      continue;
+    }
+
+    // Handle null values - remove key from result
+    if (overrideValue === null) {
+      delete result[key];
+      continue;
+    }
+
+    const baseValue = result[key];
+
+    // Special case: hooks concatenation
+    if (key === "hooks" && isPlainObject(baseValue) && isPlainObject(overrideValue)) {
+      const baseHooks = baseValue as Record<string, unknown>;
+      const overrideHooks = overrideValue as Record<string, unknown>;
+      const merged: Record<string, unknown> = { ...baseHooks };
+
+      // Merge the nested hooks object
+      if (isPlainObject(baseHooks.hooks) && isPlainObject(overrideHooks.hooks)) {
+        const baseHookDefs = baseHooks.hooks as Record<string, unknown>;
+        const overrideHookDefs = overrideHooks.hooks as Record<string, unknown>;
+        const mergedHookDefs: Record<string, unknown> = {};
+
+        // Collect all hook event names
+        const allHookNames = new Set([...Object.keys(baseHookDefs), ...Object.keys(overrideHookDefs)]);
+
+        // For each hook event, concatenate hooks into an array
+        for (const hookName of allHookNames) {
+          const baseHook = baseHookDefs[hookName];
+          const overrideHook = overrideHookDefs[hookName];
+
+          if (baseHook && overrideHook) {
+            // Both exist - create array with both
+            mergedHookDefs[hookName] = [baseHook, overrideHook];
+          } else if (overrideHook) {
+            // Only override exists
+            mergedHookDefs[hookName] = overrideHook;
+          } else {
+            // Only base exists
+            mergedHookDefs[hookName] = baseHook;
+          }
+        }
+
+        merged.hooks = mergedHookDefs;
+      } else if (overrideHooks.hooks) {
+        merged.hooks = overrideHooks.hooks;
+      }
+
+      // Handle other hook config fields (e.g., skipGlobal)
+      for (const hookKey of Object.keys(overrideHooks)) {
+        if (hookKey !== "hooks") {
+          merged[hookKey] = overrideHooks[hookKey];
+        }
+      }
+
+      result[key] = merged;
+      continue;
+    }
+
+    // Special case: constitution content concatenation
+    if (key === "constitution" && isPlainObject(baseValue) && isPlainObject(overrideValue)) {
+      const baseConst = baseValue as Record<string, unknown>;
+      const overrideConst = overrideValue as Record<string, unknown>;
+
+      const baseContent = typeof baseConst.content === "string" ? baseConst.content : "";
+      const overrideContent = typeof overrideConst.content === "string" ? overrideConst.content : "";
+
+      // Merge constitution object, but concatenate content field
+      const mergedConstitution = deepMergeConfig(baseConst, overrideConst);
+
+      // Concatenate content if both exist
+      if (baseContent && overrideContent) {
+        (mergedConstitution as unknown as Record<string, unknown>).content = `${baseContent}\n\n${overrideContent}`;
+      } else if (overrideContent) {
+        (mergedConstitution as unknown as Record<string, unknown>).content = overrideContent;
+      } else if (baseContent) {
+        (mergedConstitution as unknown as Record<string, unknown>).content = baseContent;
+      }
+
+      result[key] = mergedConstitution;
+      continue;
+    }
+
+    // Arrays replace completely (no merging)
+    if (Array.isArray(overrideValue)) {
+      result[key] = [...overrideValue];
+      continue;
+    }
+
+    // Recursive merge for plain objects
+    if (isPlainObject(overrideValue) && isPlainObject(baseValue)) {
+      result[key] = deepMergeConfig(baseValue as Record<string, unknown>, overrideValue as Record<string, unknown>);
+      continue;
+    }
+
+    // Default: override replaces base
+    result[key] = overrideValue;
+  }
+
+  return result as T;
+}
+
+/**
+ * Check if value is a plain object (not null, not array, not class instance).
+ *
+ * @param value - Value to check
+ * @returns True if value is a plain object
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && value.constructor === Object;
+}

package/src/config/path-security.ts

@@ -0,0 +1,121 @@
+/**
+ * Path Security Utilities
+ *
+ * Prevents path traversal attacks by validating and resolving paths.
+ */
+
+import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { isAbsolute, normalize, resolve } from "node:path";
+
+/** Maximum directory depth to prevent infinite loops */
+export const MAX_DIRECTORY_DEPTH = 10;
+
+/**
+ * Validate and resolve a directory path safely
+ * @param dirPath - The directory path to validate
+ * @param baseDir - Optional base directory to check bounds (if provided, dirPath must be within baseDir)
+ * @returns Resolved absolute path
+ * @throws Error if path is invalid, not a directory, or outside bounds
+ */
+export function validateDirectory(dirPath: string, baseDir?: string): string {
+  // Resolve to absolute path
+  const resolved = resolve(dirPath);
+
+  // Check if path exists
+  if (!existsSync(resolved)) {
+    throw new Error(`Directory does not exist: ${dirPath}`);
+  }
+
+  // Get real path (resolves symlinks)
+  let realPath: string;
+  try {
+    realPath = realpathSync(resolved);
+  } catch (error) {
+    throw new Error(`Failed to resolve path: ${dirPath} (${(error as Error).message})`);
+  }
+
+  // Check if it's a directory
+  try {
+    const stats = lstatSync(realPath);
+    if (!stats.isDirectory()) {
+      throw new Error(`Not a directory: ${dirPath}`);
+    }
+  } catch (error) {
+    throw new Error(`Failed to stat path: ${dirPath} (${(error as Error).message})`);
+  }
+
+  // If baseDir provided, ensure realPath is within baseDir
+  if (baseDir) {
+    const resolvedBase = resolve(baseDir);
+    const realBase = existsSync(resolvedBase) ? realpathSync(resolvedBase) : resolvedBase;
+
+    if (!isWithinDirectory(realPath, realBase)) {
+      throw new Error(`Path is outside allowed directory: ${dirPath} (resolved to ${realPath}, base: ${realBase})`);
+    }
+  }
+
+  return realPath;
+}
+
+/**
+ * Check if a path is within a base directory (prevents path traversal)
+ * @param targetPath - The path to check (must be absolute)
+ * @param basePath - The base directory (must be absolute)
+ * @returns true if targetPath is within basePath
+ */
+export function isWithinDirectory(targetPath: string, basePath: string): boolean {
+  const normalizedTarget = normalize(targetPath);
+  const normalizedBase = normalize(basePath);
+
+  // Ensure both are absolute
+  if (!isAbsolute(normalizedTarget) || !isAbsolute(normalizedBase)) {
+    return false;
+  }
+
+  // Add trailing slash to base to prevent partial matches
+  const baseWithSlash = normalizedBase.endsWith("/") ? normalizedBase : `${normalizedBase}/`;
+  const targetWithSlash = normalizedTarget.endsWith("/") ? normalizedTarget : `${normalizedTarget}/`;
+
+  // Check if target starts with base
+  return targetWithSlash.startsWith(baseWithSlash) || normalizedTarget === normalizedBase;
+}
+
+/**
+ * Validate file path and ensure it's within a base directory
+ * @param filePath - The file path to validate
+ * @param baseDir - Base directory (filePath must be within this directory)
+ * @returns Resolved absolute path
+ * @throws Error if path is invalid or outside bounds
+ */
+export function validateFilePath(filePath: string, baseDir: string): string {
+  const resolved = resolve(filePath);
+
+  // Get real path (resolves symlinks)
+  let realPath: string;
+  try {
+    // For non-existent files, use parent directory's real path
+    if (!existsSync(resolved)) {
+      const parent = resolve(resolved, "..");
+      if (existsSync(parent)) {
+        const realParent = realpathSync(parent);
+        realPath = resolve(realParent, filePath.split("/").pop() || "");
+      } else {
+        realPath = resolved;
+      }
+    } else {
+      realPath = realpathSync(resolved);
+    }
+  } catch (error) {
+    throw new Error(`Failed to resolve path: ${filePath} (${(error as Error).message})`);
+  }
+
+  // Ensure realPath is within baseDir
+  const resolvedBase = resolve(baseDir);
+  const realBase = existsSync(resolvedBase) ? realpathSync(resolvedBase) : resolvedBase;
+
+  if (!isWithinDirectory(realPath, realBase)) {
+    throw new Error(`Path is outside allowed directory: ${filePath} (resolved to ${realPath}, base: ${realBase})`);
+  }
+
+  return realPath;
+}

package/src/config/paths.ts

@@ -0,0 +1,27 @@
+/**
+ * Configuration Path Utilities
+ *
+ * Provides path resolution for global and project-level config directories.
+ */
+
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/**
+ * Returns the global config directory path (~/.nax).
+ *
+ * @returns Absolute path to global config directory
+ */
+export function globalConfigDir(): string {
+  return join(homedir(), ".nax");
+}
+
+/**
+ * Returns the project config directory path (projectRoot/nax).
+ *
+ * @param projectRoot - Absolute or relative path to project root
+ * @returns Absolute path to project config directory
+ */
+export function projectConfigDir(projectRoot: string): string {
+  return join(resolve(projectRoot), "nax");
+}

package/src/config/schema.ts

@@ -0,0 +1,56 @@
+/**
+ * Configuration Schema — Re-export Barrel
+ *
+ * Backward-compatible re-exports from split modules:
+ * - types.ts: All TypeScript interfaces, type aliases, resolveModel
+ * - schemas.ts: Zod validation schemas
+ * - defaults.ts: DEFAULT_CONFIG constant
+ */
+
+// Types and resolveModel
+export type {
+  Complexity,
+  TestStrategy,
+  TddStrategy,
+  EscalationEntry,
+  ModelTier,
+  TokenPricing,
+  ModelDef,
+  ModelEntry,
+  ModelMap,
+  TierConfig,
+  AutoModeConfig,
+  RectificationConfig,
+  RegressionGateConfig,
+  ExecutionConfig,
+  QualityConfig,
+  TddConfig,
+  ConstitutionConfig,
+  AnalyzeConfig,
+  ReviewConfig,
+  PlanConfig,
+  AcceptanceConfig,
+  OptimizerConfig,
+  PluginConfigEntry,
+  HooksConfig,
+  InteractionConfig,
+  TestCoverageConfig,
+  ContextAutoDetectConfig,
+  ContextConfig,
+  RoutingStrategyName,
+  AdaptiveRoutingConfig,
+  LlmRoutingMode,
+  LlmRoutingConfig,
+  RoutingConfig,
+  StorySizeGateConfig,
+  PrecheckConfig,
+  NaxConfig,
+} from "./types";
+
+export { resolveModel } from "./types";
+
+// Zod schemas
+export { NaxConfigSchema } from "./schemas";
+
+// Default config
+export { DEFAULT_CONFIG } from "./defaults";