@jonit-dev/night-watch-cli 1.8.3 → 1.8.4-beta.1

package/dist/scripts/publish.sh

@@ -4,6 +4,14 @@ set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
 CLI_PKG="$REPO_ROOT/packages/cli"
 PROJECTS_FILE="$HOME/.night-watch/projects.json"
+BETA=false
+
+# Parse flags
+for arg in "$@"; do
+  case $arg in
+    --beta) BETA=true ;;
+  esac
+done
 
 cd "$REPO_ROOT"
 
@@ -11,16 +19,70 @@ cd "$REPO_ROOT"
 # Force all npm calls to use the official registry where the auth token is stored.
 export npm_config_registry=https://registry.npmjs.org
 
+CURRENT_VERSION=$(node -p "require('$CLI_PKG/package.json').version")
+
+# Confirmation prompt
+echo ""
+if [[ "$BETA" == true ]]; then
+  echo "  ┌─────────────────────────────────────────────────────────┐"
+  echo "  │                  BETA RELEASE                           │"
+  echo "  │                                                         │"
+  echo "  │  Published to: npm tag @beta                           │"
+  echo "  │  Install with: npm i -g @jonit-dev/night-watch-cli@beta │"
+  echo "  │  Current version: $CURRENT_VERSION"
+  echo "  └─────────────────────────────────────────────────────────┘"
+  echo ""
+  read -r -p "  Publish beta release? [y/N] " confirm
+else
+  echo "  ┌─────────────────────────────────────────────────────────┐"
+  echo "  │              STABLE (LATEST) RELEASE                    │"
+  echo "  │                                                         │"
+  echo "  │  WARNING: This publishes to the @latest npm tag.       │"
+  echo "  │  All users running 'npm update' will receive this.     │"
+  echo "  │                                                         │"
+  echo "  │  Only proceed if this version is production-ready.     │"
+  echo "  │  Current version: $CURRENT_VERSION"
+  echo "  └─────────────────────────────────────────────────────────┘"
+  echo ""
+  read -r -p "  Publish stable release to ALL users? [y/N] " confirm
+fi
+
+if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
+  echo "Aborted."
+  exit 0
+fi
+
+echo ""
 echo "==> Running verify + tests..."
 yarn verify && yarn test
 
-echo "==> Bumping patch version..."
-CURRENT_VERSION=$(node -p "require('$CLI_PKG/package.json').version")
-IFS='.' read -r major minor patch <<< "$CURRENT_VERSION"
-NEW_VERSION="$major.$minor.$((patch + 1))"
-echo "    $CURRENT_VERSION -> $NEW_VERSION"
+# Version bumping
+IFS='.' read -r major minor patch_full <<< "$CURRENT_VERSION"
+
+if [[ "$BETA" == true ]]; then
+  # Strip any existing pre-release suffix from patch
+  patch="${patch_full%%-*}"
+
+  # Check if current version is already a beta of the next patch
+  if [[ "$CURRENT_VERSION" =~ ^([0-9]+\.[0-9]+\.[0-9]+)-beta\.([0-9]+)$ ]]; then
+    # Bump beta number: 1.8.4-beta.0 -> 1.8.4-beta.1
+    base="${BASH_REMATCH[1]}"
+    beta_num="${BASH_REMATCH[2]}"
+    NEW_VERSION="$base-beta.$((beta_num + 1))"
+  else
+    # Start new beta: 1.8.3 -> 1.8.4-beta.0
+    NEW_VERSION="$major.$minor.$((patch + 1))-beta.0"
+  fi
+  NPM_TAG="beta"
+else
+  # Stable: strip any pre-release suffix and bump patch
+  patch="${patch_full%%-*}"
+  NEW_VERSION="$major.$minor.$((patch + 1))"
+  NPM_TAG="latest"
+fi
+
+echo "==> Bumping version: $CURRENT_VERSION -> $NEW_VERSION"
 
-# Update package.json
 node -e "
   const fs = require('fs');
   const pkg = JSON.parse(fs.readFileSync('$CLI_PKG/package.json', 'utf8'));
@@ -33,9 +95,9 @@ git add "$CLI_PKG/package.json"
 git commit -m "chore: bump version to $NEW_VERSION"
 git push origin master
 
-echo "==> Publishing to npm..."
+echo "==> Publishing to npm (tag: $NPM_TAG)..."
 cd "$CLI_PKG"
-npm publish --access public
+npm publish --access public --tag "$NPM_TAG"
 
 echo "==> Installing globally (waiting for registry propagation)..."
 echo "    Waiting 60s for npm registry to propagate..."
@@ -54,25 +116,31 @@ for attempt in 1 2 3 4 5; do
 done
 night-watch --version
 
-echo "==> Updating registered projects (skipping /tmp/*)..."
-if [[ -f "$PROJECTS_FILE" ]]; then
-  node -e "
-    const projects = JSON.parse(require('fs').readFileSync('$PROJECTS_FILE', 'utf8'));
-    projects
-      .filter(p => p.path && !p.path.startsWith('/tmp/'))
-      .forEach(p => {
-        console.log('  Project: ' + p.name + ' (' + p.path + ')');
-        const { execSync } = require('child_process');
-        try {
-          execSync('night-watch update --projects ' + p.path, { stdio: 'inherit' });
-        } catch (e) {
-          console.error('  WARN: update failed for ' + p.name);
-        }
-      });
-  "
+# Only update registered projects for stable releases
+if [[ "$BETA" == true ]]; then
+  echo ""
+  echo "==> Skipping project updates (beta release)."
 else
-  echo "    No projects file found at $PROJECTS_FILE, skipping."
+  echo "==> Updating registered projects (skipping /tmp/*)..."
+  if [[ -f "$PROJECTS_FILE" ]]; then
+    node -e "
+      const projects = JSON.parse(require('fs').readFileSync('$PROJECTS_FILE', 'utf8'));
+      projects
+        .filter(p => p.path && !p.path.startsWith('/tmp/'))
+        .forEach(p => {
+          console.log('  Project: ' + p.name + ' (' + p.path + ')');
+          const { execSync } = require('child_process');
+          try {
+            execSync('night-watch update --projects ' + p.path, { stdio: 'inherit' });
+          } catch (e) {
+            console.error('  WARN: update failed for ' + p.name);
+          }
+        });
+    "
+  else
+    echo "    No projects file found at $PROJECTS_FILE, skipping."
+  fi
 fi
 
 echo ""
-echo "Done! Published $NEW_VERSION"
+echo "Done! Published $NEW_VERSION (@$NPM_TAG)"

package/dist/templates/pr-reviewer.md

@@ -187,7 +187,7 @@ Parse the review score from the comment body. Look for patterns like:
    <If CI was fixed>### CI Failures Fixed:
    - <job>: <what was wrong and how it was fixed><end>
 
-   \`npm run verify\` passes locally. Ready for re-review.
+   Verification passes locally. Ready for re-review.
 
    Night Watch PR Reviewer"
    ```

package/dist/templates/prd-creator.md

@@ -0,0 +1,330 @@
+You are a **Principal Software Architect**. Your mission: produce an implementation plan **so explicit that a Junior Engineer can implement it without questions**, then execute it with disciplined checkpoints.
+
+When this activates: `Planning Mode: Principal Architect`
+
+---
+
+## Step 0: Complexity Assessment (REQUIRED FIRST)
+
+Before writing ANY plan, determine complexity level:
+
+```
+COMPLEXITY SCORE (sum all that apply):
++1  Touches 1-5 files
++2  Touches 6-10 files
++3  Touches 10+ files
++2  New system/module from scratch
++2  Complex state logic / concurrency
++2  Multi-package changes
++1  Database schema changes
++1  External API integration
+```
+
+| Score | Level  | Template Mode                                   |
+| ----- | ------ | ----------------------------------------------- |
+| 1-3   | LOW    | Minimal (skip sections marked with MEDIUM/HIGH) |
+| 4-6   | MEDIUM | Standard (all sections)                         |
+| 7+    | HIGH   | Full + mandatory checkpoints every phase        |
+
+**State at plan start:** `Complexity: [SCORE] → [LOW/MEDIUM/HIGH] mode`
+
+---
+
+## Pre-Planning (Do Before Writing)
+
+1. **Explore:** Read all relevant files. Never guess. Reuse existing code (DRY). Take a look at config/env files for relevant variables — use the project's existing pattern for loading them (e.g., env.ts, config.ts), never access `process.env` directly unless that's already the project pattern.
+2. **Verify:** Identify existing utilities, schemas, helpers.
+3. **Impact:** List files touched, features affected, risks.
+4. **Ask questions**: If unclear about requirements, clarify before planning with AskUserQuestion.
+5. **Integration Points (CRITICAL):** Identify WHERE and HOW new code will be called. New code that isn't connected to existing flows is dead code.
+6. **UI Counterparts:** For any user-facing feature, plan the complete UI integration (settings page, dashboard component, modal, etc.)
+
+### Integration Points Checklist (REQUIRED)
+
+Before writing ANY plan, answer these questions:
+
+```markdown
+**How will this feature be reached?**
+- [ ] Entry point identified: [e.g., route, event, cron, CLI command]
+- [ ] Caller file identified: [file that will invoke this new code]
+- [ ] Registration/wiring needed: [e.g., add route to router, register handler, add menu item]
+
+**Is this user-facing?**
+- [ ] YES → UI components required (list them)
+- [ ] NO → Internal/background feature (explain how it's triggered)
+
+**Full user flow:**
+1. User does: [action]
+2. Triggers: [what code path]
+3. Reaches new feature via: [specific connection point]
+4. Result displayed in: [where user sees outcome]
+```
+
+**If you cannot complete this checklist, the feature design is incomplete.**
+
+---
+
+## Plan Structure
+
+### 1. Context (Keep Brief)
+
+**Problem:** 1-sentence issue being solved.
+
+**Files Analyzed:** List paths inspected.
+
+**Current Behavior:** 3-5 bullets max.
+
+### 2. Solution
+
+**Approach:** 3-5 bullets explaining the chosen solution.
+
+**Architecture Diagram** (MEDIUM/HIGH complexity):
+
+```mermaid
+flowchart LR
+    Client --> API --> Service --> DB[(Database)]
+```
+
+**Key Decisions:**
+
+- [ ] Library/framework choices
+- [ ] Error-handling strategy
+- [ ] Reused utilities
+
+**Data Changes:** New schemas/migrations, or "None"
+
+### 3. Sequence Flow (MEDIUM/HIGH complexity)
+
+```mermaid
+sequenceDiagram
+    participant C as Controller
+    participant S as Service
+    participant DB
+    C->>S: methodName(dto)
+    alt Error case
+        S-->>C: ErrorType
+    else Success
+        S->>DB: query
+        DB-->>S: result
+        S-->>C: Response
+    end
+```
+
+---
+
+## 4. Execution Phases
+
+**CRITICAL RULES:**
+
+1. Each phase = ONE user-testable vertical slice
+2. Max 5 files per phase (split if larger)
+3. Each phase MUST include concrete tests
+4. **Checkpoint after each phase** (automated ALWAYS required, manual ADDITIONAL for HIGH when needed)
+
+### Phase Template
+
+```markdown
+#### Phase N: [Name] - [User-visible outcome in 1 sentence]
+
+**Files (max 5):**
+
+- `src/path/file.ts` - what changes
+
+**Implementation:**
+
+- [ ] Step 1
+- [ ] Step 2
+
+**Tests Required:**
+| Test File | Test Name | Assertion |
+|-----------|-----------|-----------|
+| `src/__tests__/feature.test.ts` | `should do X when Y` | `expect(result).toBe(Z)` |
+
+**User Verification:**
+
+- Action: [what to do]
+- Expected: [what should happen]
+```
+
+---
+
+## 5. Checkpoint Protocol
+
+After completing each phase, execute the checkpoint review.
+
+### Automated Checkpoint (ALL complexities - ALWAYS REQUIRED)
+
+Spawn the `prd-work-reviewer` agent to perform automated review:
+
+```
+Use Task tool with:
+- subagent_type: "prd-work-reviewer"
+- prompt: "Review checkpoint for phase [N] of PRD at [prd_path]"
+```
+
+The agent will:
+
+1. Compare implementation against PRD requirements
+2. Run the project's verification commands
+3. Identify any drift from specifications
+4. Report corrections needed
+
+**Continue to next phase only when agent reports PASS.**
+
+---
+
+### Manual Checkpoint (HIGH complexity - ADDITIONAL to automated)
+
+For phases requiring manual verification IN ADDITION to automated checks (e.g., visual UI changes, external integrations):
+
+```
+## PHASE [N] COMPLETE - CHECKPOINT
+
+Files changed: [list]
+Tests passing: [yes/no]
+Verify: [pass/fail]
+
+**Manual verification needed:**
+1. [ ] [Specific test action → expected result]
+
+Reply "continue" to proceed to Phase [N+1], or report issues.
+```
+
+### When to Add Manual Checkpoint (in addition to automated)
+
+| Scenario                      | Checkpoint Type                |
+| ----------------------------- | ------------------------------ |
+| API/backend changes           | Automated only                 |
+| Database migrations           | Automated only                 |
+| Business logic                | Automated only                 |
+| UI visual changes             | Automated + Manual             |
+| External service integration  | Automated + Manual             |
+| Performance-sensitive changes | Automated + Manual             |
+
+**Automated is ALWAYS required.** Add manual when automated verification alone is insufficient.
+
+---
+
+## 6. Verification Strategy
+
+### Philosophy: Don't Trust, VERIFY
+
+The goal is **proving things work**, not just "writing tests". Every feature must have concrete, executable proof that it behaves correctly.
+
+**Core principle:** Code without verification is a liability. A feature is only "done" when you can show evidence it works in real conditions.
+
+### Verification Types (Use Multiple)
+
+| Type | When to Use | Example |
+|------|-------------|---------|
+| **Unit Tests** | Pure logic, utilities, transformers | `expect(calculatePrice(100, 0.1)).toBe(90)` |
+| **Integration Tests** | Service interactions, DB operations | Test service method with real/mocked DB |
+| **API Tests (curl/httpie)** | Endpoints, auth flows, webhooks | `curl -X POST /api/endpoint -d '{"data":"test"}'` |
+| **E2E Tests** | User flows, UI behavior, full journeys | Navigate → interact → assert |
+| **Manual Verification** | Visual changes, external integrations | Screenshot comparison, third-party dashboard check |
+
+### Phase Verification Template
+
+Each phase MUST include a **Verification Plan**:
+
+```markdown
+**Verification Plan:**
+
+1. **Unit Tests:**
+   - File: `tests/unit/feature.test.ts`
+   - Tests: `should X when Y`, `should handle Z error`
+
+2. **Integration Test:**
+   - File: `tests/integration/feature.test.ts`
+   - Tests: `should persist data correctly`, `should rollback on failure`
+
+3. **API Proof (curl command):**
+   ```bash
+   curl -X POST http://localhost:3000/api/feature \
+     -H "Content-Type: application/json" \
+     -d '{"input": "test"}' | jq .
+   # Expected: {"success": true, "id": "..."}
+   ```
+
+4. **Evidence Required:**
+   - [ ] All tests pass
+   - [ ] curl commands return expected responses
+   - [ ] Verify command passes
+```
+
+### Verification Checklist by Feature Type
+
+**API Endpoint:**
+- [ ] Unit test for request validation
+- [ ] Integration test for business logic
+- [ ] curl command with expected response documented
+- [ ] Error cases tested (400, 401, 403, 404, 500)
+
+**Database Change:**
+- [ ] Migration runs without error
+- [ ] Rollback works
+- [ ] Data integrity constraints tested
+
+**UI Feature:**
+- [ ] Component renders correctly (unit/snapshot test)
+- [ ] User flow works E2E
+- [ ] Loading and error states handled
+
+**Background Job/Cron:**
+- [ ] Job executes successfully
+- [ ] Failure handling tested
+- [ ] Idempotency verified (safe to re-run)
+
+### Test Naming Convention
+
+`should [expected behavior] when [condition]`
+
+Examples:
+- `should return 401 when token is missing`
+- `should create user when valid data provided`
+- `should rollback transaction when payment fails`
+
+---
+
+## 7. Acceptance Criteria
+
+Binary done checks:
+
+- [ ] All phases complete
+- [ ] All specified tests pass
+- [ ] Project's verify command passes
+- [ ] All automated checkpoint reviews passed (manual also passed if required)
+- [ ] Feature is reachable (entry point connected, not orphaned code)
+- [ ] UI exists for user-facing features (or explicitly marked internal-only)
+
+---
+
+## Quick Reference
+
+### Vertical Slice (Good) vs Horizontal Layer (Bad)
+
+| Good Phase                       | Bad Phase            |
+| -------------------------------- | -------------------- |
+| One endpoint returning real data | All types and DTOs   |
+| One socket event working e2e     | All socket handlers  |
+| One button doing one action      | Entire backend layer |
+
+**Litmus test:** Can you describe it as "User does X → sees Y"?
+
+### Anti-Patterns
+
+- Implementing multiple phases without checkpoints
+- Phases with no user-testable outcome
+- Type-check pass as sole verification
+- Touching 10+ files in one phase
+- Skipping automated review when available
+- **Creating features in isolation** - code that exists but is never called from existing flows
+- **Backend without UI** - user-facing features with no way for users to access them
+
+## Principles
+
+- **SRP, KISS, DRY, YAGNI** - Always
+- **Composition > inheritance**
+- **Explicit errors** - No silent failures
+- **Automated verification** - Let the agent catch drift
+- **Follow project conventions** - Check CLAUDE.md, AGENTS.md, or similar AI assistant docs

package/dist/templates/prd-executor.md

@@ -233,3 +233,4 @@ If two parallel agents modify the same file:
 - **Full context** - each agent gets the complete phase spec + project rules
 - **Verify always** - never skip verification between waves
 - **Task tracking** - every phase is a tracked task with status updates
+- **Clean up worktrees** - after opening a PR for a worktree branch, immediately remove the worktree to avoid blocking future `git checkout` operations

package/dist/templates/qa.md

@@ -98,17 +98,21 @@ Based on this output:
 
 ### Step 5: Run Tests
 
+Use the paths and commands discovered in Step 3. Run tests from the project root using the project's test runner.
+
 **UI Tests:**
 
 ```bash
-npx playwright test tests/e2e/qa/ --reporter=list
+# Use the playwright config and test directory discovered in Step 3
+npx playwright test <discovered-e2e-dir> --reporter=list
 ```
 
-**API Tests:**
+**API/Unit Tests:**
 
 ```bash
-npx vitest run tests/integration/qa/ --reporter=verbose
-# (or equivalent for the project's test runner)
+# Use the test runner and directory discovered in Step 3
+# e.g.: npx vitest run <discovered-test-dir> --reporter=verbose
+#       npx jest <discovered-test-dir> --verbose
 ```
 
 Capture the test output for the report.

package/dist/templates/skills/_codex-block.md

@@ -0,0 +1,58 @@
+## Night Watch Skills
+
+The following Night Watch CLI commands are available. Use them when the user asks to manage PRDs, board issues, or trigger Night Watch operations.
+
+### Create a PRD (`/nw-create-prd`)
+
+Create a new PRD at `docs/prds/<name>.md`. Ask for feature title, assess complexity (1=Simple, 2=Medium, 3=Complex), split into phases with checkbox tasks, then write the file. Tell the user to run `night-watch run` to execute immediately.
+
+### Add Issue to Board (`/nw-add-issue`)
+
+Add a GitHub issue to the Night Watch board:
+
+```
+night-watch board add-issue <issue-number>
+night-watch board add-issue <issue-number> --column "In Progress"
+```
+
+Available columns: Draft, Ready, In Progress, Review, Done.
+
+### Run Next PRD (`/nw-run`)
+
+Manually trigger Night Watch to execute the next PRD:
+
+```
+night-watch prd list         # see what's queued
+night-watch run              # execute next PRD
+night-watch run --prd <file> # run specific PRD
+night-watch logs --follow    # monitor progress
+```
+
+### Slice Roadmap (`/nw-slice`)
+
+Break a high-level feature into multiple PRD files:
+
+```
+night-watch slice
+```
+
+Reads `docs/roadmap.md` and generates PRDs. Review and adjust output in `docs/prds/`.
+
+### Sync Board (`/nw-board-sync`)
+
+Sync the GitHub board with PRD/PR state:
+
+```
+night-watch board status
+night-watch board sync
+```
+
+### Review PRs (`/nw-review`)
+
+Run automated PR review:
+
+```
+night-watch review
+night-watch review --pr <number>
+night-watch logs --type review
+```

package/dist/templates/skills/nw-add-issue.md

@@ -0,0 +1,39 @@
+# Skill: nw-add-issue
+
+Add an existing GitHub issue to the Night Watch project board for tracking and execution.
+
+## When to use
+
+When the user wants to add a GitHub issue to the Night Watch Kanban board.
+
+## Steps
+
+1. **Check for issue number** — if not provided, list open issues:
+
+   ```
+   gh issue list --state open --limit 20
+   ```
+
+   Ask the user which issue(s) to add.
+
+2. **Add the issue to the board**:
+
+   ```
+   night-watch board add-issue <issue-number>
+   ```
+
+3. **Optionally specify a column** (default: "Ready"):
+
+   ```
+   night-watch board add-issue <issue-number> --column "In Progress"
+   ```
+
+   Available columns: `Draft`, `Ready`, `In Progress`, `Review`, `Done`
+
+4. **Confirm** the issue was added and show its board position.
+
+## Notes
+
+- Issues in "Ready" are picked up automatically by Night Watch on the next run
+- Move issues to "Draft" if they're not yet ready for autonomous execution
+- Use `night-watch board sync` if the board gets out of sync with PRDs

package/dist/templates/skills/nw-board-sync.md

@@ -0,0 +1,47 @@
+# Skill: nw-board-sync
+
+Sync the GitHub Project board with the current state of Night Watch PRDs and pull requests.
+
+## When to use
+
+When the board is out of sync with PRD/PR status, or after manual changes to issues or PRDs.
+
+## Steps
+
+1. **View current board state**:
+
+   ```
+   night-watch board status
+   ```
+
+2. **Sync board with PRD filesystem**:
+
+   ```
+   night-watch board sync
+   ```
+
+3. **List open issues that may need board assignment**:
+
+   ```
+   gh issue list --state open --label "night-watch"
+   ```
+
+4. **Add any missing issues to the board**:
+   ```
+   night-watch board add-issue <number>
+   ```
+
+## Board Columns
+
+| Column      | Meaning                                          |
+| ----------- | ------------------------------------------------ |
+| Draft       | Not ready for execution                          |
+| Ready       | Queued for Night Watch — picked up automatically |
+| In Progress | Currently being implemented                      |
+| Review      | PR opened, awaiting review                       |
+| Done        | Merged and complete                              |
+
+## Notes
+
+- Night Watch auto-moves issues from Ready → In Progress when starting, and In Progress → Review when opening a PR
+- Use `night-watch board setup` to create the board if it doesn't exist yet