@nathapp/nax 0.46.3 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.46.3",
+  "version": "0.48.0",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {

package/src/cli/generate.ts

@@ -9,7 +9,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import chalk from "chalk";
 import { loadConfig } from "../config/loader";
-import { generateAll, generateFor } from "../context/generator";
+import { discoverPackages, generateAll, generateFor, generateForPackage } from "../context/generator";
 import type { AgentType } from "../context/types";
 
 /** Options for `nax generate` */
@@ -24,6 +24,17 @@ export interface GenerateCommandOptions {
   dryRun?: boolean;
   /** Disable auto-injection of project metadata */
   noAutoInject?: boolean;
+  /**
+   * Generate for a specific package directory (relative to repo root).
+   * Reads <package>/nax/context.md, writes <package>/CLAUDE.md.
+   * @example "packages/api"
+   */
+  package?: string;
+  /**
+   * Generate for all discovered packages.
+   * Auto-discovers packages with nax/context.md up to 2 levels deep.
+   */
+  allPackages?: boolean;
 }
 
 const VALID_AGENTS: AgentType[] = ["claude", "codex", "opencode", "cursor", "windsurf", "aider", "gemini"];
@@ -33,10 +44,70 @@ const VALID_AGENTS: AgentType[] = ["claude", "codex", "opencode", "cursor", "win
  */
 export async function generateCommand(options: GenerateCommandOptions): Promise<void> {
   const workdir = process.cwd();
+  const dryRun = options.dryRun ?? false;
+
+  // Load config early — needed for all paths
+  let config: Awaited<ReturnType<typeof loadConfig>>;
+  try {
+    config = await loadConfig(workdir);
+  } catch {
+    config = {} as Awaited<ReturnType<typeof loadConfig>>;
+  }
+
+  // --all-packages: discover and generate for all packages
+  if (options.allPackages) {
+    if (dryRun) {
+      console.log(chalk.yellow("⚠ Dry run — no files will be written"));
+    }
+    console.log(chalk.blue("→ Discovering packages with nax/context.md..."));
+    const packages = await discoverPackages(workdir);
+
+    if (packages.length === 0) {
+      console.log(chalk.yellow("  No packages found (no */nax/context.md or */*/nax/context.md)"));
+      return;
+    }
+
+    console.log(chalk.blue(`→ Generating CLAUDE.md for ${packages.length} package(s)...`));
+    let errorCount = 0;
+
+    for (const pkgDir of packages) {
+      const result = await generateForPackage(pkgDir, config, dryRun);
+      if (result.error) {
+        console.error(chalk.red(`✗ ${pkgDir}: ${result.error}`));
+        errorCount++;
+      } else {
+        const suffix = dryRun ? " (dry run)" : "";
+        console.log(chalk.green(`✓ ${pkgDir}/${result.outputFile} (${result.content.length} bytes${suffix})`));
+      }
+    }
+
+    if (errorCount > 0) {
+      console.error(chalk.red(`\n✗ ${errorCount} generation(s) failed`));
+      process.exit(1);
+    }
+    return;
+  }
+
+  // --package: generate for a specific package
+  if (options.package) {
+    const packageDir = join(workdir, options.package);
+    if (dryRun) {
+      console.log(chalk.yellow("⚠ Dry run — no files will be written"));
+    }
+    console.log(chalk.blue(`→ Generating CLAUDE.md for package: ${options.package}`));
+    const result = await generateForPackage(packageDir, config, dryRun);
+    if (result.error) {
+      console.error(chalk.red(`✗ ${result.error}`));
+      process.exit(1);
+    }
+    const suffix = dryRun ? " (dry run)" : "";
+    console.log(chalk.green(`✓ ${options.package}/${result.outputFile} (${result.content.length} bytes${suffix})`));
+    return;
+  }
+
   const contextPath = options.context ? join(workdir, options.context) : join(workdir, "nax/context.md");
   const outputDir = options.output ? join(workdir, options.output) : workdir;
   const autoInject = !options.noAutoInject;
-  const dryRun = options.dryRun ?? false;
 
   // Validate context file
   if (!existsSync(contextPath)) {
@@ -61,15 +132,6 @@ export async function generateCommand(options: GenerateCommandOptions): Promise<
     console.log(chalk.dim("  Auto-injecting project metadata..."));
   }
 
-  // Load config for metadata injection (best-effort, use defaults if not found)
-  let config: Awaited<ReturnType<typeof loadConfig>>;
-  try {
-    config = await loadConfig(workdir);
-  } catch {
-    // Config not required for generate — use empty defaults
-    config = {} as Awaited<ReturnType<typeof loadConfig>>;
-  }
-
   const genOptions = {
     contextPath,
     outputDir,
@@ -80,6 +142,7 @@ export async function generateCommand(options: GenerateCommandOptions): Promise<
 
   try {
     if (options.agent) {
+      // CLI --agent flag: single specific agent (overrides config)
       const agent = options.agent as AgentType;
       console.log(chalk.blue(`→ Generating config for ${agent}...`));
 
@@ -93,9 +156,19 @@ export async function generateCommand(options: GenerateCommandOptions): Promise<
       const suffix = dryRun ? " (dry run)" : "";
       console.log(chalk.green(`✓ ${agent} → ${result.outputFile} (${result.content.length} bytes${suffix})`));
     } else {
-      console.log(chalk.blue("→ Generating configs for all agents..."));
+      // No --agent flag: use config.generate.agents filter, or generate all
+      const configAgents = config?.generate?.agents;
+      const agentFilter = configAgents && configAgents.length > 0 ? configAgents : null;
+
+      if (agentFilter) {
+        console.log(chalk.blue(`→ Generating configs for: ${agentFilter.join(", ")} (from config)...`));
+      } else {
+        console.log(chalk.blue("→ Generating configs for all agents..."));
+      }
+
+      const allResults = await generateAll(genOptions, config);
+      const results = agentFilter ? allResults.filter((r) => agentFilter.includes(r.agent as AgentType)) : allResults;
 
-      const results = await generateAll(genOptions, config);
       let errorCount = 0;
 
       for (const result of results) {

package/src/cli/init-context.ts

@@ -312,6 +312,63 @@ Keep it under 2000 tokens. Use markdown formatting. Be specific to the detected
   }
 }
 
+/**
+ * Generate a minimal package context.md template.
+ *
+ * @param packagePath - Relative path of the package (e.g. "packages/api")
+ */
+export function generatePackageContextTemplate(packagePath: string): string {
+  const packageName = packagePath.split("/").pop() ?? packagePath;
+  return `# ${packageName} — Context
+
+<!-- Package-specific conventions. Root context.md provides shared rules. -->
+
+## Tech Stack
+
+<!-- TODO: Document this package's tech stack -->
+
+## Commands
+
+| Command | Purpose |
+|:--------|:--------|
+| \`bun test\` | Unit tests |
+
+## Development Guidelines
+
+<!-- TODO: Document package-specific guidelines -->
+`;
+}
+
+/**
+ * Initialize per-package nax/context.md scaffold.
+ *
+ * Creates \`<packageDir>/nax/context.md\` with a minimal template.
+ * Does not overwrite an existing file unless force is set.
+ *
+ * @param repoRoot - Absolute path to repo root
+ * @param packagePath - Relative path of the package (e.g. "packages/api")
+ * @param force - Overwrite existing file
+ */
+export async function initPackage(repoRoot: string, packagePath: string, force = false): Promise<void> {
+  const logger = getLogger();
+  const packageDir = join(repoRoot, packagePath);
+  const naxDir = join(packageDir, "nax");
+  const contextPath = join(naxDir, "context.md");
+
+  if (existsSync(contextPath) && !force) {
+    logger.info("init", "Package context.md already exists (use --force to overwrite)", { path: contextPath });
+    return;
+  }
+
+  if (!existsSync(naxDir)) {
+    await mkdir(naxDir, { recursive: true });
+  }
+
+  const content = generatePackageContextTemplate(packagePath);
+  await Bun.write(contextPath, content);
+  logger.info("init", "Created package context.md", { path: contextPath });
+}
+
 /**
  * Initialize context.md for a project
  */

package/src/cli/init.ts

@@ -9,7 +9,7 @@ import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { globalConfigDir, projectConfigDir } from "../config/paths";
 import { getLogger } from "../logger";
-import { initContext } from "./init-context";
+import { initContext, initPackage } from "./init-context";
 import { buildInitConfig, detectStack } from "./init-detect";
 import type { ProjectStack } from "./init-detect";
 import { promptsInitCommand } from "./prompts";
@@ -20,6 +20,11 @@ export interface InitOptions {
   global?: boolean;
   /** Project root (default: cwd) */
   projectRoot?: string;
+  /**
+   * Initialize a per-package nax/context.md scaffold.
+   * Relative path from repo root, e.g. "packages/api".
+   */
+  package?: string;
 }
 
 /** Options for initProject */
@@ -277,6 +282,14 @@ export async function initProject(projectRoot: string, options?: InitProjectOpti
 export async function initCommand(options: InitOptions = {}): Promise<void> {
   if (options.global) {
     await initGlobal();
+  } else if (options.package) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    await initPackage(projectRoot, options.package);
+    console.log("\n[OK] Package scaffold created.");
+    console.log(`  Created: ${options.package}/nax/context.md`);
+    console.log("\nNext steps:");
+    console.log(`  1. Review ${options.package}/nax/context.md and fill in TODOs`);
+    console.log(`  2. Run: nax generate --package ${options.package}`);
   } else {
     const projectRoot = options.projectRoot ?? process.cwd();
     await initProject(projectRoot);

package/src/cli/plan.ts

@@ -17,6 +17,7 @@ import type { CodebaseScan } from "../analyze/types";
 import type { NaxConfig } from "../config";
 import { resolvePermissions } from "../config/permissions";
 import { COMPLEXITY_GUIDE, GROUPING_RULES, TEST_STRATEGY_GUIDE } from "../config/test-strategy";
+import { discoverWorkspacePackages } from "../context/generator";
 import { PidRegistry } from "../execution/pid-registry";
 import { getLogger } from "../logger";
 import { validatePlanOutput } from "../prd/schema";
@@ -41,6 +42,15 @@ export const _deps = {
   },
   mkdirp: (path: string): Promise<void> => Bun.spawn(["mkdir", "-p", path]).exited.then(() => {}),
   existsSync: (path: string): boolean => existsSync(path),
+  discoverWorkspacePackages: (repoRoot: string): Promise<string[]> => discoverWorkspacePackages(repoRoot),
+  readPackageJsonAt: (path: string): Promise<Record<string, unknown> | null> =>
+    Bun.file(path)
+      .json()
+      .catch(() => null),
+  createInteractionBridge: (): {
+    detectQuestion: (text: string) => Promise<boolean>;
+    onQuestionDetected: (text: string) => Promise<string>;
+  } => createCliInteractionBridge(),
 };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -85,11 +95,29 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
 
   // Scan codebase for context
   logger?.info("plan", "Scanning codebase...");
-  const scan = await _deps.scanCodebase(workdir);
+  const [scan, discoveredPackages, pkg] = await Promise.all([
+    _deps.scanCodebase(workdir),
+    _deps.discoverWorkspacePackages(workdir),
+    _deps.readPackageJson(workdir),
+  ]);
   const codebaseContext = buildCodebaseContext(scan);
 
+  // Normalize to repo-relative paths (discoverWorkspacePackages returns relative,
+  // but mocks/legacy callers may return absolute — strip workdir prefix if present)
+  const relativePackages = discoveredPackages.map((p) => (p.startsWith("/") ? p.replace(`${workdir}/`, "") : p));
+
+  // Scan per-package tech stacks for richer monorepo planning context
+  const packageDetails =
+    relativePackages.length > 0
+      ? await Promise.all(
+          relativePackages.map(async (rel) => {
+            const pkgJson = await _deps.readPackageJsonAt(join(workdir, rel, "package.json"));
+            return buildPackageSummary(rel, pkgJson);
+          }),
+        )
+      : [];
+
   // Auto-detect project name
-  const pkg = await _deps.readPackageJson(workdir);
   const projectName = detectProjectName(workdir, pkg);
 
   // Compute output path early — needed for interactive file-write prompt
@@ -107,7 +135,7 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
   let rawResponse: string;
   if (options.auto) {
     // One-shot: use CLI adapter directly — simple completion doesn't need ACP session overhead
-    const prompt = buildPlanningPrompt(specContent, codebaseContext);
+    const prompt = buildPlanningPrompt(specContent, codebaseContext, undefined, relativePackages, packageDetails);
     const cliAdapter = _deps.getAgent(agentName);
     if (!cliAdapter) throw new Error(`[plan] No agent adapter found for '${agentName}'`);
     rawResponse = await cliAdapter.complete(prompt, { jsonMode: true, workdir, config });
@@ -122,10 +150,10 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
     }
   } else {
     // Interactive: agent writes PRD JSON directly to outputPath (avoids output truncation)
-    const prompt = buildPlanningPrompt(specContent, codebaseContext, outputPath);
+    const prompt = buildPlanningPrompt(specContent, codebaseContext, outputPath, relativePackages, packageDetails);
     const adapter = _deps.getAgent(agentName, config);
     if (!adapter) throw new Error(`[plan] No agent adapter found for '${agentName}'`);
-    const interactionBridge = createCliInteractionBridge();
+    const interactionBridge = _deps.createInteractionBridge();
     const pidRegistry = new PidRegistry(workdir);
     const resolvedPerm = resolvePermissions(config, "plan");
     const resolvedModel = config?.plan?.model ?? "balanced";
@@ -238,6 +266,91 @@ function detectProjectName(workdir: string, pkg: Record<string, unknown> | null)
   return "unknown";
 }
 
+/** Compact per-package summary for the planning prompt. */
+interface PackageSummary {
+  path: string;
+  name: string;
+  runtime: string;
+  framework: string;
+  testRunner: string;
+  keyDeps: string[];
+}
+
+const FRAMEWORK_PATTERNS: [RegExp, string][] = [
+  [/\bnext\b/, "Next.js"],
+  [/\bnuxt\b/, "Nuxt"],
+  [/\bremix\b/, "Remix"],
+  [/\bexpress\b/, "Express"],
+  [/\bfastify\b/, "Fastify"],
+  [/\bhono\b/, "Hono"],
+  [/\bnestjs|@nestjs\b/, "NestJS"],
+  [/\breact\b/, "React"],
+  [/\bvue\b/, "Vue"],
+  [/\bsvelte\b/, "Svelte"],
+  [/\bastro\b/, "Astro"],
+  [/\belectron\b/, "Electron"],
+];
+
+const TEST_RUNNER_PATTERNS: [RegExp, string][] = [
+  [/\bvitest\b/, "vitest"],
+  [/\bjest\b/, "jest"],
+  [/\bmocha\b/, "mocha"],
+  [/\bava\b/, "ava"],
+];
+
+const KEY_DEP_PATTERNS: [RegExp, string][] = [
+  [/\bprisma\b/, "prisma"],
+  [/\bdrizzle-orm\b/, "drizzle"],
+  [/\btypeorm\b/, "typeorm"],
+  [/\bmongoose\b/, "mongoose"],
+  [/\bsqlite\b|better-sqlite/, "sqlite"],
+  [/\bstripe\b/, "stripe"],
+  [/\bgraphql\b/, "graphql"],
+  [/\btrpc\b/, "tRPC"],
+  [/\bzod\b/, "zod"],
+  [/\btailwind\b/, "tailwind"],
+];
+
+/**
+ * Build a compact summary of a package's tech stack from its package.json.
+ */
+function buildPackageSummary(rel: string, pkg: Record<string, unknown> | null): PackageSummary {
+  const name = typeof pkg?.name === "string" ? pkg.name : rel;
+  const allDeps = { ...(pkg?.dependencies as object | undefined), ...(pkg?.devDependencies as object | undefined) };
+  const depNames = Object.keys(allDeps).join(" ");
+  const scripts = (pkg?.scripts ?? {}) as Record<string, string>;
+
+  // Detect runtime from scripts or lock files
+  const testScript = scripts.test ?? "";
+  const runtime = testScript.includes("bun ") ? "bun" : testScript.includes("node ") ? "node" : "unknown";
+
+  // Detect framework
+  const framework = FRAMEWORK_PATTERNS.find(([re]) => re.test(depNames))?.[1] ?? "";
+
+  // Detect test runner
+  const testRunner =
+    TEST_RUNNER_PATTERNS.find(([re]) => re.test(depNames))?.[1] ?? (testScript.includes("bun test") ? "bun:test" : "");
+
+  // Key deps
+  const keyDeps = KEY_DEP_PATTERNS.filter(([re]) => re.test(depNames)).map(([, label]) => label);
+
+  return { path: rel, name, runtime, framework, testRunner, keyDeps };
+}
+
+/**
+ * Render per-package summaries as a compact markdown table for the prompt.
+ */
+function buildPackageDetailsSection(details: PackageSummary[]): string {
+  if (details.length === 0) return "";
+
+  const rows = details.map((d) => {
+    const stack = [d.framework, d.testRunner, ...d.keyDeps].filter(Boolean).join(", ") || "—";
+    return `| \`${d.path}\` | ${d.name} | ${stack} |`;
+  });
+
+  return `\n## Package Tech Stacks\n\n| Path | Package | Stack |\n|:-----|:--------|:------|\n${rows.join("\n")}\n`;
+}
+
 /**
  * Build codebase context markdown from scan results.
  */
@@ -278,8 +391,26 @@ function buildCodebaseContext(scan: CodebaseScan): string {
  * - Output schema (exact prd.json JSON structure)
  * - Complexity classification guide
  * - Test strategy guide
+ * - MW-007: Monorepo hint and package list when packages are detected
  */
-function buildPlanningPrompt(specContent: string, codebaseContext: string, outputFilePath?: string): string {
+function buildPlanningPrompt(
+  specContent: string,
+  codebaseContext: string,
+  outputFilePath?: string,
+  packages?: string[],
+  packageDetails?: PackageSummary[],
+): string {
+  const isMonorepo = packages && packages.length > 0;
+  const packageDetailsSection =
+    packageDetails && packageDetails.length > 0 ? buildPackageDetailsSection(packageDetails) : "";
+  const monorepoHint = isMonorepo
+    ? `\n## Monorepo Context\n\nThis is a monorepo. Detected packages:\n${packages.map((p) => `- ${p}`).join("\n")}\n${packageDetailsSection}\nFor each user story, set the "workdir" field to the relevant package path (e.g. "packages/api"). Stories that span the root should omit "workdir".`
+    : "";
+
+  const workdirField = isMonorepo
+    ? `\n      "workdir": "string — optional, relative path to package (e.g. \\"packages/api\\"). Omit for root-level stories.",`
+    : "";
+
   return `You are a senior software architect generating a product requirements document (PRD) as JSON.
 
 ## Spec
@@ -288,7 +419,7 @@ ${specContent}
 
 ## Codebase Context
 
-${codebaseContext}
+${codebaseContext}${monorepoHint}
 
 ## Output Schema
 
@@ -307,7 +438,7 @@ Generate a JSON object with this exact structure (no markdown, no explanation
       "description": "string — detailed description of the story",
       "acceptanceCriteria": ["string — each AC line"],
       "tags": ["string — routing tags, e.g. feature, security, api"],
-      "dependencies": ["string — story IDs this story depends on"],
+      "dependencies": ["string — story IDs this story depends on"],${workdirField}
       "status": "pending",
       "passes": false,
       "routing": {

package/src/config/loader.ts

@@ -5,9 +5,10 @@
  */
 
 import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { getLogger } from "../logger";
 import { loadJsonFile } from "../utils/json-file";
+import { mergePackageConfig } from "./merge";
 import { deepMergeConfig } from "./merger";
 import { MAX_DIRECTORY_DEPTH } from "./path-security";
 import { globalConfigDir } from "./paths";
@@ -108,3 +109,35 @@ export async function loadConfig(projectDir?: string, cliOverrides?: Record<stri
 
   return result.data as NaxConfig;
 }
+
+/**
+ * Load config for a specific working directory (monorepo package).
+ *
+ * Resolution order:
+ * 1. Load root nax/config.json via loadConfig()
+ * 2. If packageDir is set, check <repoRoot>/<packageDir>/nax/config.json
+ * 3. If package config exists → merge quality.commands over root
+ * 4. Return merged config
+ *
+ * @param rootConfigPath - Absolute path to the root nax/config.json
+ * @param packageDir - Package directory relative to repo root (e.g. "packages/api")
+ */
+export async function loadConfigForWorkdir(rootConfigPath: string, packageDir?: string): Promise<NaxConfig> {
+  const rootNaxDir = dirname(rootConfigPath);
+  const rootConfig = await loadConfig(rootNaxDir);
+
+  if (!packageDir) {
+    return rootConfig;
+  }
+
+  const repoRoot = dirname(rootNaxDir);
+  const packageConfigPath = join(repoRoot, packageDir, "nax", "config.json");
+
+  const packageOverride = await loadJsonFile<Partial<NaxConfig>>(packageConfigPath, "config");
+
+  if (!packageOverride) {
+    return rootConfig;
+  }
+
+  return mergePackageConfig(rootConfig, packageOverride);
+}

package/src/config/merge.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-Package Config Merge Utility (MW-008)
+ *
+ * Only quality.commands is mergeable — routing, plugins, execution,
+ * and agents stay root-only.
+ */
+
+import type { NaxConfig } from "./schema";
+
+/**
+ * Merge a package-level partial config override into a root config.
+ *
+ * Only quality.commands keys are merged. All other sections remain
+ * unchanged from the root config.
+ *
+ * @param root - Full root NaxConfig (already validated)
+ * @param packageOverride - Partial package-level override (only quality.commands honored)
+ * @returns New merged NaxConfig (immutable — does not mutate inputs)
+ */
+export function mergePackageConfig(root: NaxConfig, packageOverride: Partial<NaxConfig>): NaxConfig {
+  const packageCommands = packageOverride.quality?.commands;
+
+  if (!packageCommands) {
+    return root;
+  }
+
+  return {
+    ...root,
+    quality: {
+      ...root.quality,
+      commands: {
+        ...root.quality.commands,
+        ...packageCommands,
+      },
+    },
+  };
+}

package/src/config/runtime-types.ts

@@ -476,6 +476,18 @@ export interface NaxConfig {
   decompose?: DecomposeConfig;
   /** Agent protocol settings (ACP-003) */
   agent?: AgentConfig;
+  /** Generate settings */
+  generate?: GenerateConfig;
+}
+
+/** Generate command configuration */
+export interface GenerateConfig {
+  /**
+   * Agents to generate config files for (default: all).
+   * Restricts `nax generate` to only the listed agents.
+   * @example ["claude", "opencode"]
+   */
+  agents?: Array<"claude" | "codex" | "opencode" | "cursor" | "windsurf" | "aider" | "gemini">;
 }
 
 /** Agent protocol configuration (ACP-003) */