@nathapp/nax 0.46.3 → 0.48.0

package/src/context/generator.ts

@@ -5,7 +5,7 @@
  * Replaces the old constitution generator.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { NaxConfig } from "../config";
 import { validateFilePath } from "../config/path-security";
@@ -129,5 +129,185 @@ async function generateAll(options: GenerateOptions, config: NaxConfig): Promise
   return results;
 }
 
+/** Result from generateForPackage */
+export interface PackageGenerationResult {
+  packageDir: string;
+  outputFile: string;
+  content: string;
+  written: boolean;
+  error?: string;
+}
+
+/**
+ * Discover packages that have nax/context.md files.
+ *
+ * Scans up to 2 levels deep (one-level and two-level patterns).
+ *
+ * @param repoRoot - Absolute repo root to scan
+ * @returns Array of package directory paths (absolute)
+ */
+export async function discoverPackages(repoRoot: string): Promise<string[]> {
+  const packages: string[] = [];
+  const seen = new Set<string>();
+
+  for (const pattern of ["*/nax/context.md", "*/*/nax/context.md"]) {
+    const glob = new Bun.Glob(pattern);
+    for await (const match of glob.scan(repoRoot)) {
+      // match is e.g. "packages/api/nax/context.md" — strip trailing /nax/context.md
+      const pkgRelative = match.replace(/\/nax\/context\.md$/, "");
+      const pkgAbsolute = join(repoRoot, pkgRelative);
+      if (!seen.has(pkgAbsolute)) {
+        seen.add(pkgAbsolute);
+        packages.push(pkgAbsolute);
+      }
+    }
+  }
+
+  return packages;
+}
+
+/**
+ * Discover packages from workspace manifests (turbo.json, package.json workspaces,
+ * pnpm-workspace.yaml). Used as fallback when no nax/context.md files exist yet.
+ *
+ * Returns relative paths (e.g. "packages/api") sorted alphabetically.
+ */
+export async function discoverWorkspacePackages(repoRoot: string): Promise<string[]> {
+  // 1. Prefer packages that already have nax/context.md
+  const existing = await discoverPackages(repoRoot);
+  if (existing.length > 0) {
+    return existing.map((p) => p.replace(`${repoRoot}/`, ""));
+  }
+
+  const seen = new Set<string>();
+  const results: string[] = [];
+
+  async function resolveGlobs(patterns: string[]): Promise<void> {
+    for (const pattern of patterns) {
+      if (pattern.startsWith("!")) continue; // skip negations
+      // Convert workspace pattern to package.json glob so Bun can scan files
+      // "packages/*"  → "packages/*/package.json"
+      // "packages/**" → "packages/**/package.json"
+      const base = pattern.replace(/\/+$/, ""); // strip trailing slashes
+      const pkgPattern = base.endsWith("*") ? `${base}/package.json` : `${base}/*/package.json`;
+
+      const g = new Bun.Glob(pkgPattern);
+      for await (const match of g.scan(repoRoot)) {
+        const rel = match.replace(/\/package\.json$/, "");
+        if (!seen.has(rel)) {
+          seen.add(rel);
+          results.push(rel);
+        }
+      }
+    }
+  }
+
+  // 2. turbo v2+: turbo.json top-level "packages" array
+  const turboPath = join(repoRoot, "turbo.json");
+  if (existsSync(turboPath)) {
+    try {
+      const turbo = JSON.parse(readFileSync(turboPath, "utf-8")) as Record<string, unknown>;
+      if (Array.isArray(turbo.packages)) {
+        await resolveGlobs(turbo.packages as string[]);
+      }
+    } catch {
+      // malformed turbo.json — skip
+    }
+  }
+
+  // 3. root package.json "workspaces" (npm/yarn/bun/turbo v1)
+  const pkgPath = join(repoRoot, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as Record<string, unknown>;
+      const ws = pkg.workspaces;
+      const patterns: string[] = Array.isArray(ws)
+        ? (ws as string[])
+        : Array.isArray((ws as Record<string, unknown>)?.packages)
+          ? ((ws as Record<string, unknown>).packages as string[])
+          : [];
+      if (patterns.length > 0) await resolveGlobs(patterns);
+    } catch {
+      // malformed package.json — skip
+    }
+  }
+
+  // 4. pnpm-workspace.yaml
+  const pnpmPath = join(repoRoot, "pnpm-workspace.yaml");
+  if (existsSync(pnpmPath)) {
+    try {
+      const raw = readFileSync(pnpmPath, "utf-8");
+      // Simple YAML parse for "packages:\n  - 'packages/*'" without full YAML dep
+      const lines = raw.split("\n");
+      let inPackages = false;
+      const patterns: string[] = [];
+      for (const line of lines) {
+        if (/^packages\s*:/.test(line)) {
+          inPackages = true;
+          continue;
+        }
+        if (inPackages && /^\s+-\s+/.test(line)) {
+          patterns.push(line.replace(/^\s+-\s+['"]?/, "").replace(/['"]?\s*$/, ""));
+        } else if (inPackages && !/^\s/.test(line)) {
+          break;
+        }
+      }
+      if (patterns.length > 0) await resolveGlobs(patterns);
+    } catch {
+      // malformed yaml — skip
+    }
+  }
+
+  return results.sort();
+}
+
+/**
+ * Generate the claude CLAUDE.md for a specific package.
+ *
+ * Reads `<packageDir>/nax/context.md` and writes `<packageDir>/CLAUDE.md`.
+ * Per-package CLAUDE.md contains only package-specific content — Claude Code's
+ * native directory hierarchy merges root CLAUDE.md + package CLAUDE.md at runtime.
+ */
+export async function generateForPackage(
+  packageDir: string,
+  config: NaxConfig,
+  dryRun = false,
+): Promise<PackageGenerationResult> {
+  const contextPath = join(packageDir, "nax", "context.md");
+
+  if (!existsSync(contextPath)) {
+    return {
+      packageDir,
+      outputFile: "CLAUDE.md",
+      content: "",
+      written: false,
+      error: `context.md not found: ${contextPath}`,
+    };
+  }
+
+  try {
+    const options: GenerateOptions = {
+      contextPath,
+      outputDir: packageDir,
+      workdir: packageDir,
+      dryRun,
+      autoInject: true,
+    };
+
+    const result = await generateFor("claude", options, config);
+
+    return {
+      packageDir,
+      outputFile: result.outputFile,
+      content: result.content,
+      written: result.written,
+      error: result.error,
+    };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    return { packageDir, outputFile: "CLAUDE.md", content: "", written: false, error };
+  }
+}
+
 export { generateFor, generateAll };
 export type { AgentType };

package/src/execution/story-context.ts

@@ -127,14 +127,33 @@ export async function buildStoryContext(prd: PRD, story: UserStory, _config: Nax
   }
 }
 
+/**
+ * Load package-level context.md content if it exists.
+ *
+ * Reads <packageWorkdir>/nax/context.md and returns its content, or null
+ * if the file does not exist.
+ *
+ * @internal
+ */
+async function loadPackageContextMd(packageWorkdir: string): Promise<string | null> {
+  const contextPath = `${packageWorkdir}/nax/context.md`;
+  const file = Bun.file(contextPath);
+  if (!(await file.exists())) return null;
+  return file.text();
+}
+
 /**
  * Build story context returning both markdown and element-level data.
  * Used by `nax prompts` CLI for accurate frontmatter token counts.
+ *
+ * When `packageWorkdir` is provided (absolute path of story.workdir),
+ * appends the package-level nax/context.md after the root context.
  */
 export async function buildStoryContextFull(
   prd: PRD,
   story: UserStory,
   config: NaxConfig,
+  packageWorkdir?: string,
 ): Promise<{ markdown: string; builtContext: BuiltContext } | undefined> {
   try {
     const storyContext: StoryContext = {
@@ -152,11 +171,23 @@ export async function buildStoryContextFull(
 
     const built = await buildContext(storyContext, budget);
 
-    if (built.elements.length === 0) {
+    // MW-003: append package-level context.md if workdir is set
+    let packageSection = "";
+    if (packageWorkdir) {
+      const pkgContent = await loadPackageContextMd(packageWorkdir);
+      if (pkgContent) {
+        packageSection = `\n---\n\n${pkgContent.trim()}`;
+      }
+    }
+
+    if (built.elements.length === 0 && !packageSection) {
       return undefined;
     }
 
-    return { markdown: formatContextAsMarkdown(built), builtContext: built };
+    const baseMarkdown = built.elements.length > 0 ? formatContextAsMarkdown(built) : "";
+    const markdown = packageSection ? `${baseMarkdown}${packageSection}` : baseMarkdown;
+
+    return { markdown, builtContext: built };
   } catch (error) {
     const logger = getSafeLogger();
     logger?.warn("context", "Context builder failed", {

package/src/pipeline/stages/context.ts

@@ -20,6 +20,7 @@
  * ```
  */
 
+import { join } from "node:path";
 import type { ContextElement } from "../../context/types";
 import { buildStoryContextFull } from "../../execution/helpers";
 import { getLogger } from "../../logger";
@@ -33,8 +34,11 @@ export const contextStage: PipelineStage = {
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
 
+    // MW-003: resolve package workdir for per-package context.md loading
+    const packageWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : undefined;
+
     // Build context from PRD with element-level tracking
-    const result = await buildStoryContextFull(ctx.prd, ctx.story, ctx.config);
+    const result = await buildStoryContextFull(ctx.prd, ctx.story, ctx.config, packageWorkdir);
 
     // SOFT FAILURE: Empty context is acceptable — agent can work without PRD context
     // This happens when no relevant stories/context is found, which is normal

package/src/pipeline/stages/execution.ts

@@ -30,6 +30,8 @@
  * ```
  */
 
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { getAgent, validateAgentForTier } from "../../agents";
 import { resolveModel } from "../../config";
 import { resolvePermissions } from "../../config/permissions";
@@ -40,6 +42,22 @@ import { runThreeSessionTdd } from "../../tdd";
 import { autoCommitIfDirty, detectMergeConflict } from "../../utils/git";
 import type { PipelineContext, PipelineStage, StageResult } from "../types";
 
+/**
+ * Resolve the effective working directory for a story.
+ * When story.workdir is set, returns join(repoRoot, story.workdir).
+ * Otherwise returns the repo root unchanged.
+ *
+ * MW-001 runtime check: throws if the resolved workdir does not exist on disk.
+ */
+export function resolveStoryWorkdir(repoRoot: string, storyWorkdir?: string): string {
+  if (!storyWorkdir) return repoRoot;
+  const resolved = join(repoRoot, storyWorkdir);
+  if (!existsSync(resolved)) {
+    throw new Error(`[execution] story.workdir "${storyWorkdir}" does not exist at "${resolved}"`);
+  }
+  return resolved;
+}
+
 /**
  * Detect if agent output contains ambiguity signals
  * Checks for keywords that indicate the agent is unsure about the implementation
@@ -128,11 +146,13 @@ export const executionStage: PipelineStage = {
         lite: isLiteMode,
       });
 
+      const effectiveWorkdir = _executionDeps.resolveStoryWorkdir(ctx.workdir, ctx.story.workdir);
+
       const tddResult = await runThreeSessionTdd({
         agent,
         story: ctx.story,
         config: ctx.config,
-        workdir: ctx.workdir,
+        workdir: effectiveWorkdir,
         modelTier: ctx.routing.modelTier,
         featureName: ctx.prd.feature,
         contextMarkdown: ctx.contextMarkdown,
@@ -212,9 +232,11 @@ export const executionStage: PipelineStage = {
       });
     }
 
+    const storyWorkdir = _executionDeps.resolveStoryWorkdir(ctx.workdir, ctx.story.workdir);
+
     const result = await agent.run({
       prompt: ctx.prompt,
-      workdir: ctx.workdir,
+      workdir: storyWorkdir,
       modelTier: ctx.routing.modelTier,
       modelDef: resolveModel(ctx.config.models[ctx.routing.modelTier]),
       timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
@@ -258,7 +280,7 @@ export const executionStage: PipelineStage = {
     ctx.agentResult = result;
 
     // BUG-058: Auto-commit if agent left uncommitted changes (single-session/test-after)
-    await autoCommitIfDirty(ctx.workdir, "execution", "single-session", ctx.story.id);
+    await autoCommitIfDirty(storyWorkdir, "execution", "single-session", ctx.story.id);
 
     // merge-conflict trigger: detect CONFLICT markers in agent output
     const combinedOutput = (result.output ?? "") + (result.stderr ?? "");
@@ -327,4 +349,5 @@ export const _executionDeps = {
   checkMergeConflict,
   isAmbiguousOutput,
   checkStoryAmbiguity,
+  resolveStoryWorkdir,
 };

package/src/pipeline/stages/review.ts

@@ -11,6 +11,7 @@
  */
 
 // RE-ARCH: rewrite
+import { join } from "node:path";
 import { checkSecurityReview, isTriggerEnabled } from "../../interaction/triggers";
 import { getLogger } from "../../logger";
 import { reviewOrchestrator } from "../../review/orchestrator";
@@ -25,12 +26,16 @@ export const reviewStage: PipelineStage = {
 
     logger.info("review", "Running review phase", { storyId: ctx.story.id });
 
+    // MW-010: scope review to package directory when story.workdir is set
+    const effectiveWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : ctx.workdir;
+
     const result = await reviewOrchestrator.review(
       ctx.config.review,
-      ctx.workdir,
+      effectiveWorkdir,
       ctx.config.execution,
       ctx.plugins,
       ctx.storyGitRef,
+      ctx.story.workdir, // MW-010: scope changed-file checks to package
     );
 
     ctx.reviewResult = result.builtIn;

package/src/pipeline/stages/verify.ts

@@ -9,6 +9,8 @@
  * - `escalate`: Tests failed (retry with escalation)
  */
 
+import { join } from "node:path";
+import { loadConfigForWorkdir } from "../../config/loader";
 import type { SmartTestRunnerConfig } from "../../config/types";
 import { getLogger } from "../../logger";
 import { logTestOutput } from "../../utils/log-test-output";
@@ -53,15 +55,20 @@ export const verifyStage: PipelineStage = {
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
 
+    // MW-009: resolve effective config for per-package test commands
+    const effectiveConfig = ctx.story.workdir
+      ? await _verifyDeps.loadConfigForWorkdir(join(ctx.workdir, "nax", "config.json"), ctx.story.workdir)
+      : ctx.config;
+
     // Skip verification if tests are not required
-    if (!ctx.config.quality.requireTests) {
+    if (!effectiveConfig.quality.requireTests) {
       logger.debug("verify", "Skipping verification (quality.requireTests = false)", { storyId: ctx.story.id });
       return { action: "continue" };
     }
 
     // Skip verification if no test command is configured
-    const testCommand = ctx.config.review?.commands?.test ?? ctx.config.quality.commands.test;
-    const testScopedTemplate = ctx.config.quality.commands.testScoped;
+    const testCommand = effectiveConfig.review?.commands?.test ?? effectiveConfig.quality.commands.test;
+    const testScopedTemplate = effectiveConfig.quality.commands.testScoped;
     if (!testCommand) {
       logger.debug("verify", "Skipping verification (no test command configured)", { storyId: ctx.story.id });
       return { action: "continue" };
@@ -69,6 +76,9 @@ export const verifyStage: PipelineStage = {
 
     logger.info("verify", "Running verification", { storyId: ctx.story.id });
 
+    // MW-006: resolve effective workdir for test execution
+    const effectiveWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : ctx.workdir;
+
     // Determine effective test command (smart runner or full suite)
     let effectiveCommand = testCommand;
     let isFullSuite = true;
@@ -76,10 +86,15 @@ export const verifyStage: PipelineStage = {
     const regressionMode = ctx.config.execution.regressionGate?.mode ?? "deferred";
 
     if (smartRunnerConfig.enabled) {
-      const sourceFiles = await _smartRunnerDeps.getChangedSourceFiles(ctx.workdir, ctx.storyGitRef);
+      // MW-006: pass packagePrefix so git diff is scoped to the package in monorepos
+      const sourceFiles = await _smartRunnerDeps.getChangedSourceFiles(
+        effectiveWorkdir,
+        ctx.storyGitRef,
+        ctx.story.workdir,
+      );
 
       // Pass 1: path convention mapping
-      const pass1Files = await _smartRunnerDeps.mapSourceToTests(sourceFiles, ctx.workdir);
+      const pass1Files = await _smartRunnerDeps.mapSourceToTests(sourceFiles, effectiveWorkdir);
       if (pass1Files.length > 0) {
         logger.info("verify", `[smart-runner] Pass 1: path convention matched ${pass1Files.length} test files`, {
           storyId: ctx.story.id,
@@ -90,7 +105,7 @@ export const verifyStage: PipelineStage = {
         // Pass 2: import-grep fallback
         const pass2Files = await _smartRunnerDeps.importGrepFallback(
           sourceFiles,
-          ctx.workdir,
+          effectiveWorkdir,
           smartRunnerConfig.testFilePatterns,
         );
         if (pass2Files.length > 0) {
@@ -126,7 +141,7 @@ export const verifyStage: PipelineStage = {
 
     // Use unified regression gate (includes 2s wait for agent process cleanup)
     const result = await _verifyDeps.regression({
-      workdir: ctx.workdir,
+      workdir: effectiveWorkdir,
       command: effectiveCommand,
       timeoutSeconds: ctx.config.execution.verificationTimeoutSeconds,
       acceptOnTimeout: ctx.config.execution.regressionGate?.acceptOnTimeout ?? true,
@@ -199,4 +214,5 @@ export const verifyStage: PipelineStage = {
  */
 export const _verifyDeps = {
   regression,
+  loadConfigForWorkdir,
 };

package/src/prd/schema.ts

@@ -155,6 +155,22 @@ function validateStory(raw: unknown, index: number, allIds: Set<string>): UserSt
   const rawTags = s.tags;
   const tags: string[] = Array.isArray(rawTags) ? (rawTags as string[]) : [];
 
+  // workdir — optional, relative path only, no traversal
+  const rawWorkdir = s.workdir;
+  let workdir: string | undefined;
+  if (rawWorkdir !== undefined && rawWorkdir !== null) {
+    if (typeof rawWorkdir !== "string") {
+      throw new Error(`[schema] story[${index}].workdir must be a string`);
+    }
+    if (rawWorkdir.startsWith("/")) {
+      throw new Error(`[schema] story[${index}].workdir must be relative (no leading /): "${rawWorkdir}"`);
+    }
+    if (rawWorkdir.includes("..")) {
+      throw new Error(`[schema] story[${index}].workdir must not contain '..': "${rawWorkdir}"`);
+    }
+    workdir = rawWorkdir;
+  }
+
   return {
     id,
     title: title.trim(),
@@ -172,6 +188,7 @@ function validateStory(raw: unknown, index: number, allIds: Set<string>): UserSt
       testStrategy,
       reasoning: "validated from LLM output",
     },
+    ...(workdir !== undefined ? { workdir } : {}),
   };
 }
 

package/src/prd/types.ts

@@ -127,6 +127,12 @@ export interface UserStory {
   failureCategory?: FailureCategory;
   /** Worktree path for parallel execution (set when --parallel is used) */
   worktreePath?: string;
+  /**
+   * Working directory for this story, relative to repo root.
+   * Overrides the global workdir for pipeline execution.
+   * @example "packages/api"
+   */
+  workdir?: string;
 }
 
 // ============================================================================

package/src/precheck/checks-system.ts

@@ -37,127 +37,65 @@ export async function checkDependenciesInstalled(workdir: string): Promise<Check
   };
 }
 
-/** Check if test command works. Skips silently if command is null/false. */
+/** Check if test command is configured. Downgraded to warning since the verify stage will catch actual failures. */
 export async function checkTestCommand(config: NaxConfig): Promise<Check> {
   const testCommand = config.execution.testCommand || (config.quality?.commands?.test as string | undefined);
 
   if (!testCommand || testCommand === null) {
     return {
       name: "test-command-works",
-      tier: "blocker",
+      tier: "warning",
       passed: true,
-      message: "Test command not configured (skipped)",
+      message: "Test command not configured (will use default: bun test)",
     };
   }
 
-  const parts = testCommand.split(" ");
-  const [cmd, ...args] = parts;
-
-  try {
-    const proc = Bun.spawn([cmd, ...args, "--help"], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-
-    const exitCode = await proc.exited;
-    const passed = exitCode === 0;
-
-    return {
-      name: "test-command-works",
-      tier: "blocker",
-      passed,
-      message: passed ? "Test command is available" : `Test command failed: ${testCommand}`,
-    };
-  } catch {
-    return {
-      name: "test-command-works",
-      tier: "blocker",
-      passed: false,
-      message: `Test command failed: ${testCommand}`,
-    };
-  }
+  return {
+    name: "test-command-works",
+    tier: "warning",
+    passed: true,
+    message: `Test command configured: ${testCommand}`,
+  };
 }
 
-/** Check if lint command works. Skips silently if command is null/false. */
+/** Check if lint command is configured. Downgraded to warning since the verify stage will catch actual failures. */
 export async function checkLintCommand(config: NaxConfig): Promise<Check> {
   const lintCommand = config.execution.lintCommand;
 
   if (!lintCommand || lintCommand === null) {
     return {
       name: "lint-command-works",
-      tier: "blocker",
+      tier: "warning",
       passed: true,
       message: "Lint command not configured (skipped)",
     };
   }
 
-  const parts = lintCommand.split(" ");
-  const [cmd, ...args] = parts;
-
-  try {
-    const proc = Bun.spawn([cmd, ...args, "--help"], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-
-    const exitCode = await proc.exited;
-    const passed = exitCode === 0;
-
-    return {
-      name: "lint-command-works",
-      tier: "blocker",
-      passed,
-      message: passed ? "Lint command is available" : `Lint command failed: ${lintCommand}`,
-    };
-  } catch {
-    return {
-      name: "lint-command-works",
-      tier: "blocker",
-      passed: false,
-      message: `Lint command failed: ${lintCommand}`,
-    };
-  }
+  return {
+    name: "lint-command-works",
+    tier: "warning",
+    passed: true,
+    message: `Lint command configured: ${lintCommand}`,
+  };
 }
 
-/** Check if typecheck command works. Skips silently if command is null/false. */
+/** Check if typecheck command is configured. Downgraded to warning since the verify stage will catch actual failures. */
 export async function checkTypecheckCommand(config: NaxConfig): Promise<Check> {
   const typecheckCommand = config.execution.typecheckCommand;
 
   if (!typecheckCommand || typecheckCommand === null) {
     return {
       name: "typecheck-command-works",
-      tier: "blocker",
+      tier: "warning",
       passed: true,
       message: "Typecheck command not configured (skipped)",
     };
   }
 
-  const parts = typecheckCommand.split(" ");
-  const [cmd, ...args] = parts;
-
-  try {
-    const proc = Bun.spawn([cmd, ...args, "--help"], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-
-    const exitCode = await proc.exited;
-    const passed = exitCode === 0;
-
-    return {
-      name: "typecheck-command-works",
-      tier: "blocker",
-      passed,
-      message: passed
-        ? `Typecheck command is available: ${typecheckCommand}`
-        : `Typecheck command failed: ${typecheckCommand}`,
-    };
-  } catch {
-    return {
-      name: "typecheck-command-works",
-      tier: "blocker",
-      passed: false,
-      message: `Typecheck command failed: ${typecheckCommand}`,
-    };
-  }
+  return {
+    name: "typecheck-command-works",
+    tier: "warning",
+    passed: true,
+    message: `Typecheck command configured: ${typecheckCommand}`,
+  };
 }