@nathapp/nax 0.38.2 → 0.39.0

package/dist/nax.js

@@ -20793,7 +20793,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.38.2",
+    version: "0.39.0",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -20857,8 +20857,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("a4df623"))
-        return "a4df623";
+      if (/^[0-9a-f]{6,10}$/.test("e6f293e"))
+        return "e6f293e";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -65180,6 +65180,9 @@ async function exportPromptCommand(options) {
 // src/cli/init.ts
 init_paths();
 init_logger2();
+
+// src/cli/init-context.ts
+init_logger2();
 // src/cli/plugins.ts
 init_loader5();
 import * as os2 from "os";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.38.2",
-  "description": "AI Coding Agent Orchestrator — loops until done",
+  "version": "0.39.0",
+  "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
     "nax": "./dist/nax.js"

package/src/cli/init-context.ts

@@ -0,0 +1,348 @@
+/**
+ * Context.md Generation (INIT-002)
+ *
+ * Generates context.md from filesystem scan with optional LLM enhancement.
+ * Default mode: template from scan (zero LLM cost)
+ * AI mode (--ai flag): LLM-powered narrative context
+ */
+
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { getLogger } from "../logger";
+
+/** Project scan results */
+export interface ProjectScan {
+  projectName: string;
+  fileTree: string[];
+  packageManifest: {
+    name?: string;
+    description?: string;
+    scripts?: Record<string, string>;
+    dependencies?: Record<string, string>;
+  } | null;
+  readmeSnippet: string | null;
+  entryPoints: string[];
+  configFiles: string[];
+}
+
+/** Package manifest structure */
+interface PackageManifest {
+  name?: string;
+  description?: string;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+}
+
+/** initContext options */
+export interface InitContextOptions {
+  ai?: boolean;
+  force?: boolean;
+}
+
+/** Dependency injection for testing */
+export const _deps = {
+  callLLM: async (_prompt: string): Promise<string> => {
+    // Placeholder implementation
+    // In production, this would call the nax LLM infrastructure
+    throw new Error("callLLM not implemented");
+  },
+};
+
+/**
+ * Recursively find all files in a directory, excluding certain paths.
+ * Returns relative paths, limited to maxFiles entries.
+ */
+async function findFiles(dir: string, maxFiles = 200): Promise<string[]> {
+  // Use find command to locate files, excluding common directories
+  try {
+    const proc = Bun.spawnSync(
+      [
+        "find",
+        dir,
+        "-type",
+        "f",
+        "-not",
+        "-path",
+        "*/node_modules/*",
+        "-not",
+        "-path",
+        "*/.git/*",
+        "-not",
+        "-path",
+        "*/dist/*",
+      ],
+      { stdio: ["pipe", "pipe", "pipe"] },
+    );
+
+    if (proc.success) {
+      const output = new TextDecoder().decode(proc.stdout);
+      const files = output
+        .trim()
+        .split("\n")
+        .filter((f) => f.length > 0)
+        .map((f) => f.replace(`${dir}/`, ""))
+        .slice(0, maxFiles);
+      return files;
+    }
+  } catch {
+    // find command failed, use fallback
+  }
+
+  return [];
+}
+
+/**
+ * Read and parse package.json if it exists
+ */
+async function readPackageManifest(projectRoot: string): Promise<PackageManifest | null> {
+  const packageJsonPath = join(projectRoot, "package.json");
+
+  if (!existsSync(packageJsonPath)) {
+    return null;
+  }
+
+  try {
+    const content = await Bun.file(packageJsonPath).text();
+    const manifest = JSON.parse(content) as PackageManifest;
+    return {
+      name: manifest.name,
+      description: manifest.description,
+      scripts: manifest.scripts,
+      dependencies: manifest.dependencies,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read first 100 lines of README.md if it exists
+ */
+async function readReadmeSnippet(projectRoot: string): Promise<string | null> {
+  const readmePath = join(projectRoot, "README.md");
+
+  if (!existsSync(readmePath)) {
+    return null;
+  }
+
+  try {
+    const content = await Bun.file(readmePath).text();
+    const lines = content.split("\n");
+    return lines.slice(0, 100).join("\n");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Detect entry points in the project
+ */
+async function detectEntryPoints(projectRoot: string): Promise<string[]> {
+  const candidates = ["src/index.ts", "src/main.ts", "main.go", "src/lib.rs"];
+  const found: string[] = [];
+
+  for (const candidate of candidates) {
+    const path = join(projectRoot, candidate);
+    if (existsSync(path)) {
+      found.push(candidate);
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Detect config files in the project
+ */
+async function detectConfigFiles(projectRoot: string): Promise<string[]> {
+  const candidates = ["tsconfig.json", "biome.json", "turbo.json", ".env.example"];
+  const found: string[] = [];
+
+  for (const candidate of candidates) {
+    const path = join(projectRoot, candidate);
+    if (existsSync(path)) {
+      found.push(candidate);
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Scan a project for context information
+ */
+export async function scanProject(projectRoot: string): Promise<ProjectScan> {
+  const fileTree = await findFiles(projectRoot, 200);
+  const packageManifest = await readPackageManifest(projectRoot);
+  const readmeSnippet = await readReadmeSnippet(projectRoot);
+  const entryPoints = await detectEntryPoints(projectRoot);
+  const configFiles = await detectConfigFiles(projectRoot);
+
+  // Determine project name from package.json or directory basename
+  const projectName = packageManifest?.name || basename(projectRoot);
+
+  return {
+    projectName,
+    fileTree,
+    packageManifest,
+    readmeSnippet,
+    entryPoints,
+    configFiles,
+  };
+}
+
+/**
+ * Generate a markdown template for context.md from scan results
+ */
+export function generateContextTemplate(scan: ProjectScan): string {
+  const lines: string[] = [];
+
+  lines.push(`# ${scan.projectName}\n`);
+
+  if (scan.packageManifest?.description) {
+    lines.push(`${scan.packageManifest.description}\n`);
+  } else {
+    lines.push("<!-- TODO: Add project description -->\n");
+  }
+
+  if (scan.entryPoints.length > 0) {
+    lines.push("## Entry Points\n");
+    for (const ep of scan.entryPoints) {
+      lines.push(`- ${ep}`);
+    }
+    lines.push("");
+  } else {
+    lines.push("## Entry Points\n");
+    lines.push("<!-- TODO: Document entry points -->\n");
+  }
+
+  if (scan.fileTree.length > 0) {
+    lines.push("## Project Structure\n");
+    lines.push("```");
+    for (const file of scan.fileTree.slice(0, 20)) {
+      lines.push(file);
+    }
+    if (scan.fileTree.length > 20) {
+      lines.push(`... and ${scan.fileTree.length - 20} more files`);
+    }
+    lines.push("```\n");
+  } else {
+    lines.push("## Project Structure\n");
+    lines.push("<!-- TODO: Document project structure -->\n");
+  }
+
+  if (scan.configFiles.length > 0) {
+    lines.push("## Configuration Files\n");
+    for (const cf of scan.configFiles) {
+      lines.push(`- ${cf}`);
+    }
+    lines.push("");
+  } else {
+    lines.push("## Configuration Files\n");
+    lines.push("<!-- TODO: Document configuration files -->\n");
+  }
+
+  if (scan.packageManifest?.scripts) {
+    const hasScripts = Object.keys(scan.packageManifest.scripts).length > 0;
+    if (hasScripts) {
+      lines.push("## Scripts\n");
+      for (const [name, command] of Object.entries(scan.packageManifest.scripts)) {
+        lines.push(`- **${name}**: \`${command}\``);
+      }
+      lines.push("");
+    }
+  }
+
+  if (scan.packageManifest?.dependencies) {
+    const deps = Object.keys(scan.packageManifest.dependencies);
+    if (deps.length > 0) {
+      lines.push("## Dependencies\n");
+      lines.push("<!-- TODO: Document key dependencies and their purpose -->\n");
+    }
+  }
+
+  lines.push("## Development Guidelines\n");
+  lines.push("<!-- TODO: Document development guidelines and conventions -->\n");
+
+  return `${lines.join("\n").trim()}\n`;
+}
+
+/**
+ * Generate context.md with LLM enhancement
+ */
+async function generateContextWithLLM(scan: ProjectScan): Promise<string> {
+  const logger = getLogger();
+
+  // Build LLM prompt from scan results
+  const scanSummary = `
+Project: ${scan.projectName}
+Entry Points: ${scan.entryPoints.join(", ") || "None detected"}
+Config Files: ${scan.configFiles.join(", ") || "None detected"}
+Total Files: ${scan.fileTree.length}
+Description: ${scan.packageManifest?.description || "Not provided"}
+`;
+
+  const prompt = `
+You are a technical documentation expert. Generate a concise, well-structured context.md file for a software project based on this scan:
+
+${scanSummary}
+
+The context.md should include:
+1. Project overview (name, purpose, key technologies)
+2. Entry points and main modules
+3. Key dependencies and why they're used
+4. Development setup and common commands
+5. Architecture overview (brief)
+6. Development guidelines
+
+Keep it under 2000 tokens. Use markdown formatting. Be specific to the detected stack and structure.
+`;
+
+  try {
+    const result = await _deps.callLLM(prompt);
+    logger.info("init", "Generated context.md with LLM");
+    return result;
+  } catch (err) {
+    logger.warn(
+      "init",
+      `LLM context generation failed, falling back to template: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return generateContextTemplate(scan);
+  }
+}
+
+/**
+ * Initialize context.md for a project
+ */
+export async function initContext(projectRoot: string, options: InitContextOptions = {}): Promise<void> {
+  const logger = getLogger();
+  const naxDir = join(projectRoot, "nax");
+  const contextPath = join(naxDir, "context.md");
+
+  // Check if context.md already exists
+  if (existsSync(contextPath) && !options.force) {
+    logger.info("init", "context.md already exists, skipping (use --force to overwrite)", { path: contextPath });
+    return;
+  }
+
+  // Create nax directory if needed
+  if (!existsSync(naxDir)) {
+    await mkdir(naxDir, { recursive: true });
+  }
+
+  // Scan the project
+  const scan = await scanProject(projectRoot);
+
+  // Generate content (template or LLM-enhanced)
+  let content: string;
+  if (options.ai) {
+    content = await generateContextWithLLM(scan);
+  } else {
+    content = generateContextTemplate(scan);
+  }
+
+  // Write context.md
+  await Bun.write(contextPath, content);
+  logger.info("init", "Generated nax/context.md template from project scan", { path: contextPath });
+}

package/src/cli/init-detect.ts

@@ -0,0 +1,169 @@
+/**
+ * Project Stack Detection for nax init
+ *
+ * Scans the project root for stack indicators and builds quality.commands
+ * for nax/config.json.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** Detected project runtime */
+export type Runtime = "bun" | "node" | "unknown";
+
+/** Detected project language */
+export type Language = "typescript" | "python" | "rust" | "go" | "unknown";
+
+/** Detected linter */
+export type Linter = "biome" | "eslint" | "ruff" | "clippy" | "golangci-lint" | "unknown";
+
+/** Detected monorepo tooling */
+export type Monorepo = "turborepo" | "none";
+
+/** Full detected project stack */
+export interface ProjectStack {
+  runtime: Runtime;
+  language: Language;
+  linter: Linter;
+  monorepo: Monorepo;
+}
+
+/** Quality commands derived from stack detection */
+export interface QualityCommands {
+  typecheck?: string;
+  lint?: string;
+  test?: string;
+}
+
+function detectRuntime(projectRoot: string): Runtime {
+  if (existsSync(join(projectRoot, "bun.lockb")) || existsSync(join(projectRoot, "bunfig.toml"))) {
+    return "bun";
+  }
+  if (
+    existsSync(join(projectRoot, "package-lock.json")) ||
+    existsSync(join(projectRoot, "yarn.lock")) ||
+    existsSync(join(projectRoot, "pnpm-lock.yaml"))
+  ) {
+    return "node";
+  }
+  return "unknown";
+}
+
+function detectLanguage(projectRoot: string): Language {
+  if (existsSync(join(projectRoot, "tsconfig.json"))) return "typescript";
+  if (existsSync(join(projectRoot, "pyproject.toml")) || existsSync(join(projectRoot, "setup.py"))) {
+    return "python";
+  }
+  if (existsSync(join(projectRoot, "Cargo.toml"))) return "rust";
+  if (existsSync(join(projectRoot, "go.mod"))) return "go";
+  return "unknown";
+}
+
+function detectLinter(projectRoot: string): Linter {
+  if (existsSync(join(projectRoot, "biome.json")) || existsSync(join(projectRoot, "biome.jsonc"))) {
+    return "biome";
+  }
+  if (
+    existsSync(join(projectRoot, ".eslintrc.json")) ||
+    existsSync(join(projectRoot, ".eslintrc.js")) ||
+    existsSync(join(projectRoot, "eslint.config.js"))
+  ) {
+    return "eslint";
+  }
+  return "unknown";
+}
+
+function detectMonorepo(projectRoot: string): Monorepo {
+  if (existsSync(join(projectRoot, "turbo.json"))) return "turborepo";
+  return "none";
+}
+
+/**
+ * Detect the project stack by scanning for indicator files.
+ */
+export function detectProjectStack(projectRoot: string): ProjectStack {
+  return {
+    runtime: detectRuntime(projectRoot),
+    language: detectLanguage(projectRoot),
+    linter: detectLinter(projectRoot),
+    monorepo: detectMonorepo(projectRoot),
+  };
+}
+
+function resolveLintCommand(stack: ProjectStack, fallback: string): string {
+  if (stack.linter === "biome") return "biome check .";
+  if (stack.linter === "eslint") return "eslint .";
+  return fallback;
+}
+
+/**
+ * Build quality.commands from a detected project stack.
+ */
+export function buildQualityCommands(stack: ProjectStack): QualityCommands {
+  if (stack.runtime === "bun" && stack.language === "typescript") {
+    return {
+      typecheck: "bun run tsc --noEmit",
+      lint: resolveLintCommand(stack, "bun run lint"),
+      test: "bun test",
+    };
+  }
+
+  if (stack.runtime === "node" && stack.language === "typescript") {
+    return {
+      typecheck: "npx tsc --noEmit",
+      lint: resolveLintCommand(stack, "npm run lint"),
+      test: "npm test",
+    };
+  }
+
+  if (stack.language === "python") {
+    return {
+      lint: "ruff check .",
+      test: "pytest",
+    };
+  }
+
+  if (stack.language === "rust") {
+    return {
+      typecheck: "cargo check",
+      lint: "cargo clippy",
+      test: "cargo test",
+    };
+  }
+
+  if (stack.language === "go") {
+    return {
+      typecheck: "go vet ./...",
+      lint: "golangci-lint run",
+      test: "go test ./...",
+    };
+  }
+
+  return {};
+}
+
+function isStackDetected(stack: ProjectStack): boolean {
+  return stack.runtime !== "unknown" || stack.language !== "unknown";
+}
+
+/**
+ * Build the full init config object from a detected project stack.
+ * Falls back to minimal config when stack is undetected.
+ */
+export function buildInitConfig(stack: ProjectStack): object {
+  if (!isStackDetected(stack)) {
+    return { version: 1 };
+  }
+
+  const commands = buildQualityCommands(stack);
+  const hasCommands = Object.keys(commands).length > 0;
+
+  if (!hasCommands) {
+    return { version: 1 };
+  }
+
+  return {
+    version: 1,
+    quality: { commands },
+  };
+}

package/src/cli/init.ts

@@ -8,8 +8,10 @@ import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { globalConfigDir, projectConfigDir } from "../config/paths";
-import { DEFAULT_CONFIG } from "../config/schema";
 import { getLogger } from "../logger";
+import { initContext } from "./init-context";
+import { buildInitConfig, detectProjectStack } from "./init-detect";
+import type { ProjectStack } from "./init-detect";
 import { promptsInitCommand } from "./prompts";
 
 /** Init command options */
@@ -20,10 +22,18 @@ export interface InitOptions {
   projectRoot?: string;
 }
 
+/** Options for initProject */
+export interface InitProjectOptions {
+  /** Use LLM to generate context.md (--ai flag) */
+  ai?: boolean;
+  /** Force overwrite of existing files */
+  force?: boolean;
+}
+
 /**
  * Gitignore entries added by nax init
  */
-const NAX_GITIGNORE_ENTRIES = [".nax-verifier-verdict.json"];
+const NAX_GITIGNORE_ENTRIES = [".nax-verifier-verdict.json", "nax.lock", "nax/**/runs/", "nax/metrics.json"];
 
 /**
  * Add nax-specific entries to .gitignore if not already present.
@@ -55,33 +65,58 @@ async function updateGitignore(projectRoot: string): Promise<void> {
 }
 
 /**
- * Template for default constitution.md
+ * Build a stack-aware constitution.md from the detected project stack.
  */
-const DEFAULT_CONSTITUTION = `# Project Constitution
+function buildConstitution(stack: ProjectStack): string {
+  const sections: string[] = [];
 
-## Goals
-- Deliver high-quality, maintainable code
-- Follow project conventions and best practices
-- Maintain comprehensive test coverage
+  sections.push("# Project Constitution\n");
 
-## Constraints
-- Use Bun-native APIs only
-- Follow functional style for pure logic
-- Keep files focused and under 400 lines
+  sections.push("## Goals");
+  sections.push("- Deliver high-quality, maintainable code");
+  sections.push("- Follow project conventions and best practices");
+  sections.push("- Maintain comprehensive test coverage\n");
 
-## Preferences
-- Prefer immutability over mutation
-- Write tests first (TDD approach)
-- Clear, descriptive naming
-`;
+  sections.push("## Constraints");
+  sections.push("- Follow functional style for pure logic");
+  sections.push("- Keep files focused and under 400 lines\n");
 
-/**
- * Template for minimal config.json (references defaults, only overrides)
- */
-const MINIMAL_PROJECT_CONFIG = {
-  version: 1,
-  // Add project-specific overrides here
-};
+  if (stack.runtime === "bun") {
+    sections.push("## Bun-Native APIs");
+    sections.push("- Use `Bun.file()` for file reads, `Bun.write()` for file writes");
+    sections.push("- Use `Bun.spawn()` for subprocesses (never `child_process`)");
+    sections.push("- Use `Bun.sleep()` for delays");
+    sections.push("- Use `bun test` for running tests\n");
+  }
+
+  if (stack.language === "typescript") {
+    sections.push("## strict TypeScript");
+    sections.push("- Enable strict mode in tsconfig.json");
+    sections.push("- No `any` in public APIs — use `unknown` + type guards");
+    sections.push("- Explicit return types on all exported functions\n");
+  }
+
+  if (stack.language === "python") {
+    sections.push("## Python Standards");
+    sections.push("- Follow PEP 8 style guide for formatting and naming");
+    sections.push("- Add type hints to all function signatures");
+    sections.push("- Use type annotations for variables where non-obvious\n");
+  }
+
+  if (stack.monorepo === "turborepo") {
+    sections.push("## Monorepo Conventions");
+    sections.push("- Respect package boundaries — do not import across packages without explicit dependency");
+    sections.push("- Each package should be independently buildable and testable");
+    sections.push("- Shared utilities go in a dedicated `packages/shared` (or equivalent) package\n");
+  }
+
+  sections.push("## Preferences");
+  sections.push("- Prefer immutability over mutation");
+  sections.push("- Write tests first (TDD approach)");
+  sections.push("- Clear, descriptive naming");
+
+  return `${sections.join("\n")}\n`;
+}
 
 const MINIMAL_GLOBAL_CONFIG = {
   version: 1,
@@ -113,7 +148,10 @@ async function initGlobal(): Promise<void> {
   // Create ~/.nax/constitution.md if it doesn't exist
   const constitutionPath = join(globalDir, "constitution.md");
   if (!existsSync(constitutionPath)) {
-    await Bun.write(constitutionPath, DEFAULT_CONSTITUTION);
+    await Bun.write(
+      constitutionPath,
+      buildConstitution({ runtime: "unknown", language: "unknown", linter: "unknown", monorepo: "none" }),
+    );
     logger.info("init", "Created global constitution", { path: constitutionPath });
   } else {
     logger.info("init", "Global constitution already exists", { path: constitutionPath });
@@ -134,7 +172,7 @@ async function initGlobal(): Promise<void> {
 /**
  * Initialize project nax directory (nax/)
  */
-export async function initProject(projectRoot: string): Promise<void> {
+export async function initProject(projectRoot: string, options?: InitProjectOptions): Promise<void> {
   const logger = getLogger();
   const projectDir = projectConfigDir(projectRoot);
 
@@ -144,19 +182,32 @@ export async function initProject(projectRoot: string): Promise<void> {
     logger.info("init", "Created project config directory", { path: projectDir });
   }
 
+  // Detect project stack and build config
+  const stack = detectProjectStack(projectRoot);
+  const projectConfig = buildInitConfig(stack);
+  logger.info("init", "Detected project stack", {
+    runtime: stack.runtime,
+    language: stack.language,
+    linter: stack.linter,
+    monorepo: stack.monorepo,
+  });
+
   // Create nax/config.json if it doesn't exist
   const configPath = join(projectDir, "config.json");
   if (!existsSync(configPath)) {
-    await Bun.write(configPath, `${JSON.stringify(MINIMAL_PROJECT_CONFIG, null, 2)}\n`);
+    await Bun.write(configPath, `${JSON.stringify(projectConfig, null, 2)}\n`);
     logger.info("init", "Created project config", { path: configPath });
   } else {
     logger.info("init", "Project config already exists", { path: configPath });
   }
 
-  // Create nax/constitution.md if it doesn't exist
+  // Generate context.md (template or LLM-enhanced with --ai flag)
+  await initContext(projectRoot, { ai: options?.ai, force: options?.force });
+
+  // Create nax/constitution.md with stack-aware content
   const constitutionPath = join(projectDir, "constitution.md");
-  if (!existsSync(constitutionPath)) {
-    await Bun.write(constitutionPath, DEFAULT_CONSTITUTION);
+  if (!existsSync(constitutionPath) || options?.force) {
+    await Bun.write(constitutionPath, buildConstitution(stack));
     logger.info("init", "Created project constitution", { path: constitutionPath });
   } else {
     logger.info("init", "Project constitution already exists", { path: constitutionPath });
@@ -174,11 +225,25 @@ export async function initProject(projectRoot: string): Promise<void> {
   // Update .gitignore to include nax-specific entries
   await updateGitignore(projectRoot);
 
-  // Create prompt templates (final step)
+  // Create prompt templates
   // Pass autoWireConfig: false to prevent auto-wiring prompts.overrides
   // Templates are created but not activated until user explicitly configures them
   await promptsInitCommand({ workdir: projectRoot, force: false, autoWireConfig: false });
 
+  // Print summary
+  console.log("\n[OK] nax init complete. Created files:");
+  console.log("  - nax/config.json");
+  console.log("  - nax/context.md");
+  console.log("  - nax/constitution.md");
+  console.log("  - nax/hooks/");
+  console.log("  - nax/templates/");
+  console.log("\nNext steps:");
+  console.log("  1. Review nax/context.md and fill in TODOs");
+  console.log("  2. Review nax/config.json and adjust quality commands");
+  console.log("  3. Run: nax generate");
+  console.log("  4. Run: nax plan");
+  console.log("  5. Run: nax run");
+
   logger.info("init", "Project config initialized successfully", { path: projectDir });
 }