@nathapp/nax 0.18.1

package/src/config/validate.ts

@@ -0,0 +1,103 @@
+/**
+ * Configuration Validation
+ *
+ * @deprecated Use NaxConfigSchema.safeParse() from schema.ts instead.
+ * This module is kept for backward compatibility only.
+ *
+ * Validates NaxConfig structure and constraints.
+ */
+
+import type { NaxConfig } from "./schema";
+
+/** Validation result */
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * Validate NaxConfig
+ *
+ * Checks:
+ * - version === 1
+ * - maxIterations > 0
+ * - costLimit > 0
+ * - sessionTimeoutSeconds > 0
+ * - defaultAgent is non-empty
+ * - escalation.tierOrder has at least one tier with valid attempts
+ */
+export function validateConfig(config: NaxConfig): ValidationResult {
+  const errors: string[] = [];
+
+  // Version check
+  if (config.version !== 1) {
+    errors.push(`Invalid version: expected 1, got ${config.version}`);
+  }
+
+  // Models mapping
+  const requiredTiers = ["fast", "balanced", "powerful"] as const;
+  if (!config.models) {
+    errors.push("models mapping is required");
+  } else {
+    for (const tier of requiredTiers) {
+      const entry = config.models[tier];
+      if (!entry) {
+        errors.push(`models.${tier} is required`);
+      } else if (typeof entry === "string") {
+        if (entry.trim() === "") {
+          errors.push(`models.${tier} must be a non-empty model identifier`);
+        }
+      } else {
+        if (!entry.provider || entry.provider.trim() === "") {
+          errors.push(`models.${tier}.provider must be non-empty`);
+        }
+        if (!entry.model || entry.model.trim() === "") {
+          errors.push(`models.${tier}.model must be non-empty`);
+        }
+      }
+    }
+  }
+
+  // Execution limits
+  if (config.execution.maxIterations <= 0) {
+    errors.push(`maxIterations must be > 0, got ${config.execution.maxIterations}`);
+  }
+
+  if (config.execution.costLimit <= 0) {
+    errors.push(`costLimit must be > 0, got ${config.execution.costLimit}`);
+  }
+
+  if (config.execution.sessionTimeoutSeconds <= 0) {
+    errors.push(`sessionTimeoutSeconds must be > 0, got ${config.execution.sessionTimeoutSeconds}`);
+  }
+
+  // Auto mode config
+  if (!config.autoMode.defaultAgent || config.autoMode.defaultAgent.trim() === "") {
+    errors.push("defaultAgent must be non-empty");
+  }
+
+  if (!config.autoMode.escalation.tierOrder || config.autoMode.escalation.tierOrder.length === 0) {
+    errors.push("escalation.tierOrder must have at least one tier");
+  } else {
+    for (const tc of config.autoMode.escalation.tierOrder) {
+      if (tc.attempts < 1 || tc.attempts > 20) {
+        errors.push(`escalation.tierOrder: tier "${tc.tier}" attempts must be 1-20, got ${tc.attempts}`);
+      }
+    }
+  }
+
+  // Validate complexityRouting values reference tiers that exist in models config
+  const configuredTiers = Object.keys(config.models);
+  const complexities = ["simple", "medium", "complex", "expert"] as const;
+  for (const complexity of complexities) {
+    const tier = config.autoMode.complexityRouting[complexity];
+    if (!configuredTiers.includes(tier)) {
+      errors.push(`complexityRouting.${complexity} must be one of: ${configuredTiers.join(", ")} (got '${tier}')`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/constitution/generator.ts

@@ -0,0 +1,191 @@
+/**
+ * Constitution Generator Orchestrator
+ *
+ * Generates agent-specific config files from nax/constitution.md.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { validateFilePath } from "../config/path-security";
+import { aiderGenerator } from "./generators/aider";
+import { claudeGenerator } from "./generators/claude";
+import { cursorGenerator } from "./generators/cursor";
+import { opencodeGenerator } from "./generators/opencode";
+import type { AgentConfigGenerator, AgentType, ConstitutionContent, GeneratorMap } from "./generators/types";
+import { windsurfGenerator } from "./generators/windsurf";
+
+/** Generator registry */
+const GENERATORS: GeneratorMap = {
+  claude: claudeGenerator,
+  opencode: opencodeGenerator,
+  cursor: cursorGenerator,
+  windsurf: windsurfGenerator,
+  aider: aiderGenerator,
+};
+
+/** Generation result for a single agent */
+export interface GenerationResult {
+  agent: AgentType;
+  outputFile: string;
+  content: string;
+  written: boolean;
+  error?: string;
+}
+
+/** Generate options */
+export interface GenerateOptions {
+  /** Constitution file path (default: nax/constitution.md) */
+  constitutionPath: string;
+  /** Output directory (default: project root) */
+  outputDir: string;
+  /** Dry run mode (don't write files) */
+  dryRun?: boolean;
+  /** Specific agent to generate for (default: all) */
+  agent?: AgentType;
+}
+
+/**
+ * Load constitution content from file
+ */
+async function loadConstitutionContent(constitutionPath: string): Promise<ConstitutionContent> {
+  if (!existsSync(constitutionPath)) {
+    throw new Error(`Constitution file not found: ${constitutionPath}`);
+  }
+
+  const file = Bun.file(constitutionPath);
+  const markdown = await file.text();
+
+  return {
+    markdown,
+    sections: {}, // TODO: implement section parsing if needed
+  };
+}
+
+/**
+ * Generate config for a specific agent
+ */
+function generateForAgent(
+  agent: AgentType,
+  constitution: ConstitutionContent,
+): { content: string; outputFile: string } {
+  const generator = GENERATORS[agent];
+  if (!generator) {
+    throw new Error(`Unknown agent type: ${agent}`);
+  }
+
+  const content = generator.generate(constitution);
+  return {
+    content,
+    outputFile: generator.outputFile,
+  };
+}
+
+/**
+ * Write generated content to file
+ */
+async function writeGeneratedFile(outputDir: string, filename: string, content: string): Promise<void> {
+  const outputPath = join(outputDir, filename);
+
+  // SEC-5: Validate path before writing
+  const validatedPath = validateFilePath(outputPath, outputDir);
+
+  await Bun.write(validatedPath, content);
+}
+
+/**
+ * Generate config for a specific agent
+ *
+ * @param agent - Agent type to generate for
+ * @param constitutionPath - Path to constitution file
+ * @param outputDir - Directory to write output file
+ * @param dryRun - If true, don't write files
+ * @returns Generation result
+ */
+export async function generateFor(
+  agent: AgentType,
+  constitutionPath: string,
+  outputDir: string,
+  dryRun = false,
+): Promise<GenerationResult> {
+  try {
+    const constitution = await loadConstitutionContent(constitutionPath);
+    const { content, outputFile } = generateForAgent(agent, constitution);
+
+    if (!dryRun) {
+      await writeGeneratedFile(outputDir, outputFile, content);
+    }
+
+    return {
+      agent,
+      outputFile,
+      content,
+      written: !dryRun,
+    };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    return {
+      agent,
+      outputFile: GENERATORS[agent].outputFile,
+      content: "",
+      written: false,
+      error,
+    };
+  }
+}
+
+/**
+ * Generate config files for all agents
+ *
+ * @param constitutionPath - Path to constitution file
+ * @param outputDir - Directory to write output files
+ * @param dryRun - If true, don't write files
+ * @returns Array of generation results
+ */
+export async function generateAll(
+  constitutionPath: string,
+  outputDir: string,
+  dryRun = false,
+): Promise<GenerationResult[]> {
+  const agents: AgentType[] = ["claude", "opencode", "cursor", "windsurf", "aider"];
+  const results: GenerationResult[] = [];
+
+  for (const agent of agents) {
+    const result = await generateFor(agent, constitutionPath, outputDir, dryRun);
+    results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * Check if constitution file is newer than generated configs
+ */
+export function isConstitutionNewer(constitutionPath: string, outputDir: string): boolean {
+  if (!existsSync(constitutionPath)) {
+    return false;
+  }
+
+  const constitutionStat = Bun.file(constitutionPath);
+  const constitutionMtime = constitutionStat.lastModified;
+
+  // Check all generated files
+  const agents: AgentType[] = ["claude", "opencode", "cursor", "windsurf", "aider"];
+  for (const agent of agents) {
+    const outputFile = GENERATORS[agent].outputFile;
+    const outputPath = join(outputDir, outputFile);
+
+    if (!existsSync(outputPath)) {
+      // If any config file is missing, consider constitution newer
+      return true;
+    }
+
+    const outputStat = Bun.file(outputPath);
+    const outputMtime = outputStat.lastModified;
+
+    if (constitutionMtime > outputMtime) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/constitution/generators/aider.ts

@@ -0,0 +1,41 @@
+/**
+ * Aider Config Generator
+ *
+ * Generates .aider.conf.yml from nax/constitution.md.
+ * Aider uses YAML format for configuration.
+ */
+
+import type { AgentConfigGenerator, ConstitutionContent } from "./types";
+
+/**
+ * Generate .aider.conf.yml from constitution
+ */
+function generateAiderConfig(constitution: ConstitutionContent): string {
+  const { markdown } = constitution;
+
+  // Build .aider.conf.yml format
+  const header = `# Aider Configuration
+# Auto-generated from nax/constitution.md
+# DO NOT EDIT MANUALLY
+
+# Project instructions
+instructions: |
+`;
+
+  // Indent all lines of markdown for YAML multi-line string
+  const indentedMarkdown = markdown
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n");
+
+  return `${header}${indentedMarkdown}\n`;
+}
+
+/**
+ * Aider generator
+ */
+export const aiderGenerator: AgentConfigGenerator = {
+  name: "aider",
+  outputFile: ".aider.conf.yml",
+  generate: generateAiderConfig,
+};

package/src/constitution/generators/claude.ts

@@ -0,0 +1,35 @@
+/**
+ * Claude Code Config Generator
+ *
+ * Generates CLAUDE.md from nax/constitution.md.
+ */
+
+import type { AgentConfigGenerator, ConstitutionContent } from "./types";
+
+/**
+ * Generate CLAUDE.md from constitution
+ */
+function generateClaudeConfig(constitution: ConstitutionContent): string {
+  const { markdown } = constitution;
+
+  // Build CLAUDE.md format
+  const header = `# Project Constitution
+
+This file is auto-generated from \`nax/constitution.md\`.
+DO NOT EDIT MANUALLY — changes will be overwritten.
+
+---
+
+`;
+
+  return header + markdown;
+}
+
+/**
+ * Claude Code generator
+ */
+export const claudeGenerator: AgentConfigGenerator = {
+  name: "claude",
+  outputFile: "CLAUDE.md",
+  generate: generateClaudeConfig,
+};

package/src/constitution/generators/cursor.ts

@@ -0,0 +1,36 @@
+/**
+ * Cursor Rules Generator
+ *
+ * Generates .cursorrules from nax/constitution.md.
+ * Cursor uses a simple text format similar to Claude but in a dotfile.
+ */
+
+import type { AgentConfigGenerator, ConstitutionContent } from "./types";
+
+/**
+ * Generate .cursorrules from constitution
+ */
+function generateCursorRules(constitution: ConstitutionContent): string {
+  const { markdown } = constitution;
+
+  // Build .cursorrules format
+  const header = `# Project Rules
+
+Auto-generated from nax/constitution.md
+DO NOT EDIT MANUALLY
+
+---
+
+`;
+
+  return header + markdown;
+}
+
+/**
+ * Cursor generator
+ */
+export const cursorGenerator: AgentConfigGenerator = {
+  name: "cursor",
+  outputFile: ".cursorrules",
+  generate: generateCursorRules,
+};

package/src/constitution/generators/opencode.ts

@@ -0,0 +1,38 @@
+/**
+ * OpenCode Config Generator
+ *
+ * Generates AGENTS.md from nax/constitution.md.
+ * Format is similar to CLAUDE.md but with OpenCode-specific headers.
+ */
+
+import type { AgentConfigGenerator, ConstitutionContent } from "./types";
+
+/**
+ * Generate AGENTS.md from constitution
+ */
+function generateOpencodeConfig(constitution: ConstitutionContent): string {
+  const { markdown } = constitution;
+
+  // Build AGENTS.md format (OpenCode/Codex format)
+  const header = `# Agent Instructions
+
+This file is auto-generated from \`nax/constitution.md\`.
+DO NOT EDIT MANUALLY — changes will be overwritten.
+
+These instructions apply to all AI coding agents in this project.
+
+---
+
+`;
+
+  return header + markdown;
+}
+
+/**
+ * OpenCode generator
+ */
+export const opencodeGenerator: AgentConfigGenerator = {
+  name: "opencode",
+  outputFile: "AGENTS.md",
+  generate: generateOpencodeConfig,
+};

package/src/constitution/generators/types.ts

@@ -0,0 +1,33 @@
+/**
+ * Constitution Generator Types
+ *
+ * Defines the interface for generating agent-specific config files from nax/constitution.md.
+ */
+
+/** Constitution content structure for generators */
+export interface ConstitutionContent {
+  /** Full constitution markdown content */
+  markdown: string;
+  /** Parsed sections (optional, for structured generation) */
+  sections?: Record<string, string>;
+}
+
+/** Agent config generator interface */
+export interface AgentConfigGenerator {
+  /** Generator name (e.g., 'claude', 'opencode', 'cursor') */
+  name: string;
+  /** Output filename (e.g., 'CLAUDE.md', '.cursorrules') */
+  outputFile: string;
+  /**
+   * Generate agent-specific config file content from constitution
+   * @param constitution - Constitution content
+   * @returns Generated config file content
+   */
+  generate(constitution: ConstitutionContent): string;
+}
+
+/** All available generator types */
+export type AgentType = "claude" | "opencode" | "cursor" | "windsurf" | "aider";
+
+/** Generator registry map */
+export type GeneratorMap = Record<AgentType, AgentConfigGenerator>;

package/src/constitution/generators/windsurf.ts

@@ -0,0 +1,36 @@
+/**
+ * Windsurf Rules Generator
+ *
+ * Generates .windsurfrules from nax/constitution.md.
+ * Windsurf uses a similar format to Cursor.
+ */
+
+import type { AgentConfigGenerator, ConstitutionContent } from "./types";
+
+/**
+ * Generate .windsurfrules from constitution
+ */
+function generateWindsurfRules(constitution: ConstitutionContent): string {
+  const { markdown } = constitution;
+
+  // Build .windsurfrules format
+  const header = `# Windsurf Project Rules
+
+Auto-generated from nax/constitution.md
+DO NOT EDIT MANUALLY
+
+---
+
+`;
+
+  return header + markdown;
+}
+
+/**
+ * Windsurf generator
+ */
+export const windsurfGenerator: AgentConfigGenerator = {
+  name: "windsurf",
+  outputFile: ".windsurfrules",
+  generate: generateWindsurfRules,
+};

package/src/constitution/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Constitution system
+ *
+ * Provides project-level governance by injecting a constitution.md file
+ * into every agent session prompt. The constitution defines coding standards,
+ * architectural rules, testing requirements, and forbidden patterns.
+ */
+
+export type { ConstitutionConfig, ConstitutionResult } from "./types";
+export { loadConstitution, estimateTokens, truncateToTokens } from "./loader";

package/src/constitution/loader.ts

@@ -0,0 +1,133 @@
+/**
+ * Constitution loader
+ *
+ * Loads and processes global + project constitution files.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { validateFilePath } from "../config/path-security";
+import { globalConfigDir } from "../config/paths";
+import type { ConstitutionConfig, ConstitutionResult } from "./types";
+
+/**
+ * Estimate token count for text
+ *
+ * Uses simple heuristic: 1 token ≈ 3 characters (conservative estimate)
+ * This is a rough approximation sufficient for quota management.
+ *
+ * @param text - Text to estimate tokens for
+ * @returns Estimated token count
+ */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 3);
+}
+
+/**
+ * Truncate text to fit within token limit
+ *
+ * Truncates at word boundaries to avoid cutting mid-word.
+ *
+ * @param text - Text to truncate
+ * @param maxTokens - Maximum tokens allowed
+ * @returns Truncated text
+ */
+export function truncateToTokens(text: string, maxTokens: number): string {
+  const maxChars = maxTokens * 3; // 1 token ≈ 3 chars
+
+  if (text.length <= maxChars) {
+    return text;
+  }
+
+  // Find last word boundary before maxChars
+  const truncated = text.slice(0, maxChars);
+  const lastSpace = truncated.lastIndexOf(" ");
+  const lastNewline = truncated.lastIndexOf("\n");
+  const cutPoint = Math.max(lastSpace, lastNewline);
+
+  if (cutPoint > 0) {
+    return truncated.slice(0, cutPoint);
+  }
+
+  // Fallback: hard cut if no word boundary found
+  return truncated;
+}
+
+/**
+ * Load constitution from global and project directories.
+ *
+ * Prepends global constitution to project constitution with --- separator.
+ * Respects skipGlobal flag in config.
+ *
+ * @param projectDir - Path to project nax/ directory
+ * @param config - Constitution configuration
+ * @returns Constitution result or null if disabled/missing
+ */
+export async function loadConstitution(
+  projectDir: string,
+  config: ConstitutionConfig,
+): Promise<ConstitutionResult | null> {
+  if (!config.enabled) {
+    return null;
+  }
+
+  let combinedContent = "";
+
+  // Load global constitution (unless skipGlobal is true)
+  if (!config.skipGlobal) {
+    const globalPath = join(globalConfigDir(), config.path);
+    if (existsSync(globalPath)) {
+      // SEC-5: Validate path before reading
+      const validatedPath = validateFilePath(globalPath, globalConfigDir());
+      const globalFile = Bun.file(validatedPath);
+      const globalContent = await globalFile.text();
+      if (globalContent.trim()) {
+        combinedContent = globalContent.trim();
+      }
+    }
+  }
+
+  // Load project constitution
+  const projectPath = join(projectDir, config.path);
+  if (existsSync(projectPath)) {
+    // SEC-5: Validate path before reading
+    const validatedPath = validateFilePath(projectPath, projectDir);
+    const projectFile = Bun.file(validatedPath);
+    const projectContent = await projectFile.text();
+    if (projectContent.trim()) {
+      // Concatenate with separator if both exist
+      if (combinedContent) {
+        combinedContent += `\n\n---\n\n${projectContent.trim()}`;
+      } else {
+        // If no global content, preserve exact project content (including trailing newline)
+        combinedContent = projectContent;
+      }
+    }
+  }
+
+  // Return null if no content loaded
+  if (!combinedContent) {
+    return null;
+  }
+
+  const tokens = estimateTokens(combinedContent);
+
+  if (tokens <= config.maxTokens) {
+    return {
+      content: combinedContent,
+      tokens,
+      truncated: false,
+    };
+  }
+
+  // Truncate to fit within maxTokens
+  const truncatedContent = truncateToTokens(combinedContent, config.maxTokens);
+  const truncatedTokens = estimateTokens(truncatedContent);
+
+  return {
+    content: truncatedContent,
+    tokens: truncatedTokens,
+    truncated: true,
+    originalTokens: tokens,
+  };
+}

package/src/constitution/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Constitution types
+ *
+ * The constitution is a project-level governance document that defines coding
+ * standards, architectural rules, testing requirements, and forbidden patterns.
+ * It gets injected into every agent session prompt.
+ */
+
+/** Constitution configuration */
+export interface ConstitutionConfig {
+  /** Enable constitution loading and injection */
+  enabled: boolean;
+  /** Path to constitution file relative to nax/ directory */
+  path: string;
+  /** Maximum tokens allowed for constitution content */
+  maxTokens: number;
+  /** Skip loading global constitution (default: false) */
+  skipGlobal?: boolean;
+}
+
+/** Constitution load result */
+export interface ConstitutionResult {
+  /** Constitution content (may be truncated) */
+  content: string;
+  /** Estimated token count */
+  tokens: number;
+  /** Whether content was truncated */
+  truncated: boolean;
+  /** Original token count before truncation (if truncated) */
+  originalTokens?: number;
+}