@nathapp/nax 0.18.1

package/README.md

@@ -0,0 +1,373 @@
+# nax
+
+**AI Coding Agent Orchestrator** — loops until done.
+
+Give it a spec. It writes tests, implements code, verifies quality, and retries until everything passes.
+
+## Install
+
+```bash
+npm install -g @nathapp/nax
+# or
+bun install -g @nathapp/nax
+```
+
+## Quick Start
+
+```bash
+cd your-project
+nax init
+nax features create my-feature
+# Edit nax/features/my-feature/prd.json with your user stories
+nax run -f my-feature
+```
+
+## How It Works
+
+```
+analyze → route → execute (loop until all stories pass)
+```
+
+1. **Analyze** each user story — classify complexity, select test strategy
+2. **Route** to the right model tier (cheap → standard → premium)
+3. **Execute** an agent session (Claude Code by default)
+4. **Verify** tests pass; escalate model on failure
+5. **Loop** until all stories are complete or a cost/iteration limit is hit
+
+---
+
+## CLI Reference
+
+### `nax init`
+
+Initialize nax in your project. Creates the `nax/` folder structure.
+
+```bash
+nax init
+```
+
+Creates:
+```
+nax/
+├── config.json       # Project-level config
+└── features/         # One folder per feature
+```
+
+---
+
+### `nax features create <name>`
+
+Scaffold a new feature.
+
+```bash
+nax features create user-auth
+```
+
+Creates `nax/features/user-auth/prd.json` — edit this file to define your user stories.
+
+### `nax features list`
+
+List all features and their story completion status.
+
+```bash
+nax features list
+```
+
+---
+
+### `nax analyze -f <name>`
+
+Parse a `spec.md` file into a structured `prd.json`. Useful if you prefer writing specs in markdown first.
+
+```bash
+nax analyze -f my-feature
+```
+
+---
+
+### `nax run -f <name>`
+
+Execute the orchestration loop for a feature.
+
+```bash
+nax run -f my-feature
+```
+
+**Flags:**
+
+| Flag | Description |
+|:-----|:------------|
+| `-f, --feature <name>` | Feature name (required) |
+| `--dry-run` | Preview story routing without running agents |
+| `--headless` | Non-interactive output (structured logs, no TUI) |
+| `-d, --dir <path>` | Project directory (defaults to `cwd`) |
+
+**Examples:**
+
+```bash
+# Preview what would run (no agents spawned)
+nax run -f user-auth --dry-run
+
+# Run in a different directory
+nax run -f user-auth -d /path/to/project
+
+# Run in CI/CD (structured output)
+nax run -f user-auth --headless
+```
+
+---
+
+### `nax precheck -f <name>`
+
+Validate your project is ready to run — checks git, PRD, CLI tools, deps, test/lint/typecheck scripts.
+
+```bash
+nax precheck -f my-feature
+```
+
+Run this before `nax run` to catch configuration issues early.
+
+---
+
+### `nax status -f <name>`
+
+Show live run progress — stories passed, failed, current story, cost so far.
+
+```bash
+nax status -f my-feature
+```
+
+---
+
+### `nax logs -f <name>`
+
+Stream logs from the current or last run.
+
+```bash
+nax logs -f my-feature
+
+# Follow in real-time
+nax logs -f my-feature --follow
+
+# Filter by story
+nax logs -f my-feature --story US-003
+
+# Filter by level
+nax logs -f my-feature --level error
+```
+
+---
+
+### `nax diagnose -f <name>`
+
+Analyze a failed run and suggest fixes. No LLM — pure pattern matching on PRD state, git log, and events.
+
+```bash
+nax diagnose -f my-feature
+
+# JSON output for scripting
+nax diagnose -f my-feature --json
+
+# Verbose (per-story tier/strategy detail)
+nax diagnose -f my-feature --verbose
+```
+
+Output sections:
+- **Run Summary** — status, stories passed/failed/pending, total cost
+- **Story Breakdown** — per-story pattern classification
+- **Failure Analysis** — pattern name, symptom, recommended fix
+- **Lock Check** — detects stale `nax.lock`
+- **Recommendations** — ordered next actions
+
+**Common failure patterns:**
+
+| Pattern | Symptom | Fix |
+|:--------|:--------|:----|
+| `GREENFIELD_TDD` | No source files exist yet | Use `test-after` or bootstrap files first |
+| `MAX_TIERS_EXHAUSTED` | All model tiers tried | Split story into smaller sub-stories |
+| `ENVIRONMENTAL` | Build/dep errors | Fix precheck issues before re-running |
+| `LOCK_STALE` | `nax.lock` blocking | Shown automatically with `rm nax.lock` |
+| `AUTO_RECOVERED` | nax self-healed | No action needed |
+
+---
+
+### `nax agents`
+
+List installed coding agents and which models they support.
+
+```bash
+nax agents
+```
+
+---
+
+## Configuration
+
+Config is layered — project overrides global:
+
+| File | Scope |
+|:-----|:------|
+| `~/.nax/config.json` | Global (all projects) |
+| `nax/config.json` | Project-level override |
+
+**Key options:**
+
+```json
+{
+  "execution": {
+    "maxIterations": 20,
+    "costLimit": 5.0
+  },
+  "tdd": {
+    "strategy": "auto"
+  },
+  "quality": {
+    "commands": {
+      "test": "bun test",
+      "lint": "bun run lint",
+      "typecheck": "bun x tsc --noEmit"
+    }
+  }
+}
+```
+
+**TDD strategy options:**
+
+| Value | Behaviour |
+|:------|:----------|
+| `auto` | nax decides based on complexity and tags |
+| `lite` | Prefer `three-session-tdd-lite` for complex stories |
+| `strict` | Always use full `three-session-tdd` for complex stories |
+
+---
+
+## Three-Session TDD
+
+For complex or security-critical stories, nax enforces strict role separation:
+
+| Session | Role | Allowed Files |
+|:--------|:-----|:--------------|
+| 1 | Test Writer | Test files only — no source code |
+| 2 | Implementer | Source files only — no test changes |
+| 3 | Verifier | Reviews quality, auto-approves or flags |
+
+Isolation is verified automatically via `git diff` between sessions. Violations cause an immediate failure.
+
+---
+
+## Hooks
+
+Integrate notifications, CI triggers, or custom scripts via lifecycle hooks.
+
+**Project hooks** (`nax/hooks.json`):
+
+```json
+{
+  "hooks": {
+    "on-complete": {
+      "command": "openclaw system event --text 'Feature done!'",
+      "enabled": true
+    },
+    "on-pause": {
+      "command": "bash hooks/notify.sh",
+      "enabled": true
+    }
+  }
+}
+```
+
+**Available events:**
+
+| Event | Fires when |
+|:------|:-----------|
+| `on-start` | Run begins |
+| `on-story-start` | A story starts |
+| `on-story-complete` | A story passes |
+| `on-story-fail` | A story exhausts all attempts |
+| `on-pause` | Run paused (awaiting input) |
+| `on-complete` | All stories done |
+| `on-error` | Unhandled error |
+
+Each hook receives context via `NAX_*` environment variables and full JSON on stdin.
+
+---
+
+## Plugins
+
+Extend nax with custom reporters or integrations. Configure in `nax/config.json`:
+
+```json
+{
+  "plugins": [
+    { "name": "my-reporter", "path": "./plugins/my-reporter.ts" }
+  ]
+}
+```
+
+Global plugin directory: `~/.nax/plugins/`
+
+---
+
+## Troubleshooting
+
+**`nax.lock` blocking a new run**
+
+```bash
+# Check if nax is actually running first
+pgrep -fa nax
+
+# If nothing is running, remove the lock
+rm nax.lock
+```
+
+**Story keeps failing**
+
+```bash
+nax diagnose -f my-feature
+```
+
+**Precheck fails**
+
+```bash
+nax precheck -f my-feature
+# Fix reported issues, then re-run
+```
+
+**Run stopped mid-way**
+
+nax saves progress in `nax/features/<name>/prd.json`. Re-run with the same command — completed stories are skipped automatically.
+
+---
+
+## PRD Format
+
+User stories are defined in `nax/features/<name>/prd.json`:
+
+```json
+{
+  "feature": "user-auth",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Add login endpoint",
+      "description": "POST /auth/login with email/password",
+      "acceptanceCriteria": [
+        "Returns JWT on success",
+        "Returns 401 on invalid credentials"
+      ],
+      "complexity": "medium",
+      "tags": ["auth", "security"],
+      "status": "pending"
+    }
+  ]
+}
+```
+
+> **Note:** Use `"status": "passed"` (not `"done"`) to manually mark a story complete.
+
+---
+
+## License
+
+MIT
+

package/US-007-IMPLEMENTATION.md

@@ -0,0 +1,139 @@
+# US-007 Implementation Summary
+
+## Story: Read plugin config entries from nax config.json
+
+**Status:** ✅ COMPLETE
+
+## Implementation Details
+
+The functionality described in US-007 was already implemented in the codebase. This document verifies that all acceptance criteria are met.
+
+### Acceptance Criteria Verification
+
+#### ✅ AC1: plugins[] from config.json are passed to loadPlugins() as configPlugins parameter
+
+**Implementation:**
+- `src/config/loader.ts`: Config schema includes `plugins?: PluginConfigEntry[]` (line 369)
+- `src/execution/runner.ts`: Reads `config.plugins` and passes to `loadPlugins()` (line 201)
+- `src/execution/run-lifecycle.ts`: Reads `config.plugins` and passes to `loadPlugins()` (line 88)
+- `src/cli/plugins.ts`: Reads `config.plugins` and passes to `loadPlugins()` (line 22)
+
+**Test Coverage:**
+- `test/integration/config-loader.test.ts`: New tests verify plugins[] are loaded from config.json
+- `test/integration/plugins/config-integration.test.ts`: End-to-end test with realistic scenario
+- `test/integration/plugins/config-resolution.test.ts`: Comprehensive path resolution tests
+
+#### ✅ AC2: Relative module paths in plugins[].module are resolved relative to project root
+
+**Implementation:**
+- `src/plugins/loader.ts`: `resolveModulePath()` function (lines 173-186)
+  - Relative paths (starting with `./` or `../`) are resolved relative to `projectRoot`
+  - Uses `path.resolve(projectRoot, modulePath)` for relative paths
+
+**Test Coverage:**
+- `test/integration/plugins/config-resolution.test.ts`:
+  - "AC2: Relative module paths resolved relative to project root"
+  - "resolves ./custom-plugins/plugin.ts relative to project root"
+
+#### ✅ AC3: Absolute module paths and npm package names work as-is
+
+**Implementation:**
+- `src/plugins/loader.ts`: `resolveModulePath()` function (lines 173-186)
+  - Absolute paths: `path.isAbsolute(modulePath)` returns true → no resolution needed
+  - NPM packages: No leading `./` or `../` → treated as package name, passed as-is
+
+**Test Coverage:**
+- `test/integration/plugins/config-resolution.test.ts`:
+  - "AC3: Absolute paths and npm packages work as-is"
+  - "resolves npm package names as-is"
+  - "resolves absolute paths as-is"
+
+#### ✅ AC4: If a plugin module cannot be found, a clear error message is logged with the path tried
+
+**Implementation:**
+- `src/plugins/loader.ts`: `loadAndValidatePlugin()` function (lines 225-241)
+  - Catches import errors and provides helpful error messages
+  - Lines 230-235: Special handling for "Cannot find module" and "ENOENT" errors
+  - Logs both original path and attempted resolved path
+  - Provides guidance: "Ensure the module exists and the path is correct (relative paths are resolved from project root)"
+
+**Test Coverage:**
+- `test/integration/plugins/config-resolution.test.ts`:
+  - "AC4: Clear error message when plugin module not found (relative path)"
+  - "AC4: Clear error message when plugin module not found (npm package)"
+
+**Example Error Output:**
+```
+[nax] Failed to load plugin module './custom-plugins/missing.ts'
+[nax] Attempted path: /path/to/project/custom-plugins/missing.ts
+[nax] Ensure the module exists and the path is correct (relative paths are resolved from project root)
+```
+
+#### ✅ AC5: Plugin-specific config (plugins[].config) is passed to the plugin's setup() function
+
+**Implementation:**
+- `src/plugins/loader.ts`: `loadAndValidatePlugin()` function (lines 214-221)
+  - Calls plugin's `setup()` function with the provided config
+  - Config is passed as the first parameter: `await validated.setup(config)`
+
+**Test Coverage:**
+- `test/integration/plugins/config-integration.test.ts`:
+  - "realistic scenario: project with relative plugin paths in config"
+  - Verifies that plugin configs are written to tracker file via setup()
+- `test/integration/plugins/config-resolution.test.ts`:
+  - "AC5: Plugin-specific config passed to setup() function"
+
+## Test Results
+
+All plugin-related tests pass:
+
+```bash
+$ bun test test/integration/plugins/ test/integration/config-loader.test.ts test/integration/runner-plugin-integration.test.ts
+
+✓ 101 tests passed
+✓ 154 expect() calls
+✓ 0 failures
+```
+
+### New Tests Added
+
+Added 4 new tests to `test/integration/config-loader.test.ts`:
+
+1. **"loads plugins[] from config.json"** - Verifies plugins array is loaded correctly
+2. **"handles missing plugins[] array"** - Verifies graceful handling of missing plugins
+3. **"merges plugins[] from global and project config"** - Verifies config merging behavior
+4. **"validates plugin config entries have required fields"** - Verifies validation works
+
+## Files Modified
+
+1. **test/integration/config-loader.test.ts**
+   - Added new test suite: "Config Loader - Plugin Configuration (US-007)"
+   - Added 4 tests covering config loading scenarios
+   - Tests verify plugins[] array is properly loaded and validated
+
+## Architecture Overview
+
+```
+config.json
+  └─> loadConfig() (src/config/loader.ts)
+      └─> NaxConfig { plugins?: PluginConfigEntry[] }
+          └─> Runner/CLI reads config.plugins
+              └─> loadPlugins(globalDir, projectDir, configPlugins, projectRoot)
+                  └─> resolveModulePath() for each entry
+                      └─> loadAndValidatePlugin()
+                          └─> import module
+                              └─> validatePlugin()
+                                  └─> plugin.setup(config)
+```
+
+## Conclusion
+
+All acceptance criteria for US-007 are met. The implementation correctly:
+1. Reads plugins[] from config.json
+2. Passes them to loadPlugins() as configPlugins parameter
+3. Resolves relative paths relative to project root
+4. Handles absolute paths and npm packages correctly
+5. Provides clear error messages when modules are not found
+6. Passes plugin-specific config to setup() functions
+
+The feature is production-ready and fully tested.