tlc-claude-code 1.2.6 → 1.2.8

package/build.md

@@ -354,6 +354,138 @@ Status: ✅ All tests passing (Green)
 {test runner output showing all pass}
 ```
 
+### Step 10: E2E Testing (Optional)
+
+After unit tests pass, offer E2E testing:
+
+```
+✅ Unit tests passing (11/11)
+
+Run E2E tests?
+  [1] Yes - run full E2E suite
+  [2] Skip - proceed to verify
+
+Choice [1/2]: _
+```
+
+**If user chooses E2E:**
+
+#### 10a. Detect E2E Framework
+
+Check `.tlc.json` or detect from project:
+
+```bash
+# Check config
+e2eFramework=$(jq -r '.e2e.framework // ""' .tlc.json)
+
+# Or detect
+if [ -f "playwright.config.ts" ]; then
+  e2eFramework="playwright"
+elif [ -f "cypress.config.ts" ]; then
+  e2eFramework="cypress"
+fi
+```
+
+If no E2E framework:
+```
+No E2E framework detected.
+
+Set up E2E testing?
+  [1] Playwright (recommended)
+  [2] Cypress
+  [3] Skip for now
+
+Choice [1/2/3]: _
+```
+
+#### 10b. Generate E2E Tests from Acceptance Criteria
+
+Read acceptance criteria from PLAN.md and generate E2E scenarios:
+
+```
+Analyzing phase acceptance criteria...
+
+E2E scenarios for Phase 1:
+  1. User can log in with valid credentials
+  2. User sees error for invalid password
+  3. User session persists after refresh
+  4. User can log out
+
+Generate E2E tests? (Y/n)
+```
+
+Create `tests/e2e/phase-{N}.spec.ts`:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Phase 1: Authentication', () => {
+  test('user can log in with valid credentials', async ({ page }) => {
+    await page.goto('/login');
+    await page.fill('[name="email"]', 'user@test.com');
+    await page.fill('[name="password"]', 'password123');
+    await page.click('button[type="submit"]');
+
+    await expect(page).toHaveURL('/dashboard');
+  });
+
+  test('user sees error for invalid password', async ({ page }) => {
+    await page.goto('/login');
+    await page.fill('[name="email"]', 'user@test.com');
+    await page.fill('[name="password"]', 'wrong');
+    await page.click('button[type="submit"]');
+
+    await expect(page.locator('.error')).toContainText('Invalid credentials');
+  });
+
+  // ... more tests from acceptance criteria
+});
+```
+
+#### 10c. Run E2E Tests
+
+```bash
+# Playwright
+npx playwright test
+
+# Cypress
+npx cypress run
+
+# Docker (if configured)
+docker-compose --profile test up playwright
+```
+
+Output:
+```
+Running E2E tests...
+
+  ✓ user can log in with valid credentials (1.2s)
+  ✓ user sees error for invalid password (0.8s)
+  ✓ user session persists after refresh (1.5s)
+  ✓ user can log out (0.6s)
+
+✅ 4 E2E tests passing
+
+Phase 1 complete. Ready for /tlc:verify 1
+```
+
+#### 10d. E2E Failures
+
+If E2E tests fail:
+```
+E2E test failed: user can log in with valid credentials
+
+Error: Expected URL '/dashboard', got '/login'
+Screenshot: tests/e2e/screenshots/login-failure.png
+
+Options:
+  [1] Fix and retry
+  [2] Skip E2E (proceed to verify)
+  [3] Debug (open headed browser)
+
+Choice [1/2/3]: _
+```
+
 ## Framework Defaults
 
 ### TLC Default: Mocha Stack
@@ -425,6 +557,51 @@ Projects can have multiple test frameworks. Configure in `.tlc.json`:
 
 When running tests, TLC will execute all frameworks in the `run` array.
 
+### E2E Framework Configuration
+
+Configure E2E testing in `.tlc.json`:
+
+```json
+{
+  "e2e": {
+    "framework": "playwright",
+    "baseUrl": "http://localhost:5001",
+    "command": "npx playwright test",
+    "docker": true
+  }
+}
+```
+
+**Playwright setup** (recommended):
+```bash
+npm init playwright@latest
+```
+
+Creates `playwright.config.ts`:
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  baseURL: process.env.BASE_URL || 'http://localhost:5001',
+  use: {
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+});
+```
+
+**Cypress setup**:
+```bash
+npm install -D cypress
+npx cypress open
+```
+
+**Docker E2E** (already in docker-compose.dev.yml):
+```bash
+docker-compose --profile test up playwright
+```
+
 Default pytest.ini (Python):
 ```ini
 [pytest]
@@ -472,6 +649,14 @@ Committed: feat: session management - phase 1
 Running tests again...
 ✅ 11 tests passing
 
+Run E2E tests? [1] Yes [2] Skip: 1
+
+Running E2E tests...
+  ✓ user can log in with valid credentials
+  ✓ user sees error for invalid password
+  ✓ session persists after refresh
+✅ 3 E2E tests passing
+
 Phase 1 complete. Ready for /tlc:verify 1
 ```
 

package/help.md

@@ -37,7 +37,7 @@ Launches the visual dashboard. Detects where you are, shows what's next.
 |---------|--------------|
 | `/tlc:discuss` | Shape implementation approach |
 | `/tlc:plan` | Create task plan |
-| `/tlc:build` | Write tests → implement → verify |
+| `/tlc:build` | Write tests → implement → E2E (optional) → verify |
 | `/tlc:verify` | Human acceptance testing |
 
 ### Quality & Testing
@@ -49,7 +49,7 @@ Launches the visual dashboard. Detects where you are, shows what's next.
 | `/tlc:quality` | Test quality scoring and analysis |
 | `/tlc:edge-cases` | Generate edge case tests |
 | `/tlc:autofix` | Auto-fix failing tests |
-| `/tlc:config` | Configure test frameworks |
+| `/tlc:config` | Configure test frameworks (unit + E2E) |
 
 ### Utility
 
@@ -115,6 +115,8 @@ That's it. `/tlc` handles everything:
  ↓
  Rebase detected? → "Run sync? (Y/n)" → Reconcile
  ↓
+ Main ahead? → "Integrate? [1/2]" → Read & rebuild (no rebase)
+ ↓
  Already synced? → Dashboard + next actions
 ```
 
@@ -125,6 +127,13 @@ git rebase origin/main
 /tlc                    ← Detects changes, asks, syncs, continues
 ```
 
+**When main is ahead (no rebase):**
+```
+/tlc                    ← Detects main ahead, offers to integrate
+    ↓
+[1] Integrate          ← Claude reads changes, rebuilds locally
+```
+
 ---
 
 ## What `/tlc` Does

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc": "./bin/tlc.js",

package/sync.md

@@ -8,6 +8,8 @@ The unified entry point for TLC adoption and codebase synchronization.
 
 **Post-rebase:** Detect changes and reconcile incoming code with TLC standards.
 
+**Main ahead:** Read changes from main, understand context, rebuild locally without rebasing.
+
 ## Usage
 
 ```
@@ -24,17 +26,27 @@ No arguments. TLC auto-detects the scenario.
 Step 1: Check for .tlc.json
         │
         ├── NOT FOUND → Execute "Scenario 1: First-Time Adoption" ONLY
-        │               (Skip Scenario 2 entirely)
         │
-        └── FOUND → Step 2: Compare HEAD with lastSync
+        └── FOUND → Step 2: Check branch status
+                    │
+                    ├── HEAD == lastSync AND main not ahead → "✓ Already synced" STOP
                     │
-                    ├── HEAD == lastSync → Print "✓ Already synced" and STOP
+                    ├── HEAD != lastSync → Execute "Scenario 2: Post-Rebase" ONLY
                     │
-                    └── HEAD != lastSync → Execute "Scenario 2: Post-Rebase" ONLY
-                                           (Skip Scenario 1 entirely)
+                    └── Main is ahead of current branch → Execute "Scenario 3: Integrate Main" ONLY
 ```
 
-**DO NOT run both scenarios. Pick ONE based on detection.**
+**Detection for "main ahead":**
+```bash
+mainBranch=$(jq -r '.git.mainBranch // "main"' .tlc.json)
+git fetch origin $mainBranch
+behindCount=$(git rev-list HEAD..origin/$mainBranch --count)
+if [ "$behindCount" -gt 0 ]; then
+  # Main is ahead - offer Scenario 3
+fi
+```
+
+**DO NOT run multiple scenarios. Pick ONE based on detection.**
 
 ---
 
@@ -431,6 +443,164 @@ git commit -m "sync: reconcile changes from rebase"
 
 ---
 
+## Scenario 3: Integrate Main (No Rebase)
+
+**ONLY run this if main branch is ahead of current branch.**
+
+This is for when you want to incorporate changes from main WITHOUT rebasing. Claude reads and understands the changes, then rebuilds them in your branch's context.
+
+### When to Use This
+
+- Rebase would cause too many conflicts
+- You want to cherry-pick specific improvements
+- You need to understand what changed before integrating
+- Your branch has diverged significantly from main
+
+### Step 3.1: Detect Main Ahead
+
+```bash
+mainBranch=$(jq -r '.git.mainBranch // "main"' .tlc.json)
+git fetch origin $mainBranch
+
+behindCount=$(git rev-list HEAD..origin/$mainBranch --count)
+aheadCount=$(git rev-list origin/$mainBranch..HEAD --count)
+
+if [ "$behindCount" -gt 0 ]; then
+  echo "─────────────────────────────────────────────────────"
+  echo " MAIN IS AHEAD"
+  echo "─────────────────────────────────────────────────────"
+  echo ""
+  echo "Your branch: $(git branch --show-current)"
+  echo "Main branch: $mainBranch"
+  echo ""
+  echo "  $behindCount commits behind main"
+  echo "  $aheadCount commits ahead of main"
+  echo ""
+  echo "Options:"
+  echo "  [1] Integrate changes (read & rebuild without rebase)"
+  echo "  [2] Skip for now"
+  echo ""
+  echo "Choice [1/2]: _"
+fi
+```
+
+### Step 3.2: Analyze Main's Changes
+
+If user chooses to integrate:
+
+```bash
+# Get the changes from main that we don't have
+git log --oneline HEAD..origin/$mainBranch
+git diff HEAD...origin/$mainBranch --stat
+```
+
+Present summary:
+
+```
+─────────────────────────────────────────────────────
+ CHANGES IN MAIN
+─────────────────────────────────────────────────────
+
+12 commits to integrate:
+
+  abc1234 feat: add payment processing
+  def5678 fix: user validation bug
+  ghi9012 refactor: cleanup auth module
+  ...
+
+Files changed: 23
+  + 8 new files
+  ~ 12 modified files
+  - 3 deleted files
+
+Key changes:
+  • New payment system (src/payments/*)
+  • Auth module refactored
+  • Bug fixes in user validation
+```
+
+### Step 3.3: Read and Understand
+
+**Claude reads the actual changes (not just filenames):**
+
+```bash
+# Read new files entirely
+for f in $(git diff --name-only --diff-filter=A HEAD...origin/$mainBranch); do
+  git show origin/$mainBranch:$f
+done
+
+# Read diffs for modified files
+git diff HEAD...origin/$mainBranch
+```
+
+**Build context:**
+- What new features were added?
+- What bugs were fixed?
+- What was refactored and why?
+- What was deleted and why?
+
+### Step 3.4: Rebuild Locally
+
+Instead of rebasing, Claude:
+
+1. **Creates new files** based on understanding (not copy-paste)
+2. **Applies fixes** to your branch's version of files
+3. **Incorporates refactors** that make sense in your context
+4. **Skips changes** that conflict with your work (notes them)
+
+```
+─────────────────────────────────────────────────────
+ INTEGRATING CHANGES
+─────────────────────────────────────────────────────
+
+Reading main's changes...
+
+✓ New: src/payments/processor.ts
+  → Created in your branch (adapted to your patterns)
+
+✓ Fix: src/api/users.ts - validation bug
+  → Applied fix to your version
+
+✓ Refactor: src/auth/login.ts
+  → Incorporated improvements
+
+⚠ Skipped: src/api/orders.ts
+  → Conflicts with your changes (noted for manual review)
+
+─────────────────────────────────────────────────────
+
+Integrated 11 of 12 changes.
+1 change skipped (see .planning/INTEGRATION-NOTES.md)
+
+Commit these changes? (Y/n): _
+```
+
+### Step 3.5: Commit Integration
+
+```bash
+git add -A
+git commit -m "integrate: incorporate changes from main (no rebase)
+
+Changes integrated:
+- Payment processing system
+- User validation fix
+- Auth module improvements
+
+Skipped (manual review needed):
+- src/api/orders.ts (conflicts with current work)"
+```
+
+### Step 3.6: Update Sync State
+
+```bash
+# Note that we've seen main's changes (even if not fully merged)
+mainHead=$(git rev-parse origin/$mainBranch)
+jq ".lastMainCheck = \"$mainHead\"" .tlc.json > .tlc.json.tmp
+mv .tlc.json.tmp .tlc.json
+```
+
+---
+
 ## Auto-Detection in /tlc
 
 The main `/tlc` command should check sync status first:

package/tlc.md

@@ -64,6 +64,23 @@ if [ -f ".tlc-rebase-marker" ] || [ "$lastSync" != "$currentHead" ]; then
   # If yes → Run sync.md "Scenario 2: Post-Rebase Reconciliation" ONLY
   # DO NOT run Scenario 1 (no questionnaire!)
   # Then continue to Step 1
+  exit  # Don't fall through to main-ahead check
+fi
+
+# Check if main is ahead of current branch
+mainBranch=$(jq -r '.git.mainBranch // "main"' .tlc.json)
+git fetch origin $mainBranch 2>/dev/null
+behindCount=$(git rev-list HEAD..origin/$mainBranch --count 2>/dev/null)
+
+if [ "$behindCount" -gt 0 ]; then
+  echo "⚠️ Main branch is $behindCount commits ahead."
+  echo ""
+  echo "Options:"
+  echo "  [1] Integrate changes (read & rebuild without rebase)"
+  echo "  [2] Skip for now"
+  echo ""
+  # If 1 → Run sync.md "Scenario 3: Integrate Main" ONLY
+  # If 2 → Continue to dashboard
 fi
 
 # If we get here, sync is current
@@ -76,9 +93,10 @@ echo "✓ Synced"
 |-----------|--------|
 | No `.tlc.json` | Run sync.md **Scenario 1** (questionnaire) |
 | `.tlc.json` exists, HEAD changed | Run sync.md **Scenario 2** (reconciliation only, NO questionnaire) |
-| `.tlc.json` exists, HEAD matches | Already synced, skip to dashboard |
+| Main is ahead of current branch | Run sync.md **Scenario 3** (integrate without rebase) |
+| `.tlc.json` exists, all synced | Already synced, skip to dashboard |
 
-**The questionnaire ONLY runs on first-time setup, NEVER after rebase.**
+**The questionnaire ONLY runs on first-time setup, NEVER after rebase or integrate.**
 
 User never needs to know about `/tlc:sync` as a separate command - `/tlc` handles everything.