tlc-claude-code 0.6.4 → 0.7.1

package/build.md

@@ -24,14 +24,63 @@ This is the core TLC command. Tests before code, one task at a time.
 
 Read all `.planning/phases/{phase}-*-PLAN.md` files for this phase.
 
+### Step 1b: Sync and Claim (Multi-User)
+
+Before starting work, coordinate with teammates:
+
+1. **Pull latest:** `git pull --rebase`
+2. **Get user identity:**
+   ```bash
+   if [ -n "$TLC_USER" ]; then
+     user=$TLC_USER
+   else
+     user=$(git config user.name | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+   fi
+   ```
+3. **Parse task status:** Read `[>@user]` and `[x@user]` markers from plan
+4. **Show availability:**
+   ```
+   Phase 1 Tasks:
+     [x@alice] 1. Create schema (done)
+     [ ] 2. Add validation (available)
+     [>@bob] 3. Write migrations (bob is working)
+     [ ] 4. Integration tests (available)
+
+   Work on task 2? (Y/n)
+   ```
+5. **Claim selected task:** Update `[ ]` → `[>@{user}]`
+6. **Commit claim:** `git commit -m "claim: task 2 (@{user})"`
+7. **Push:** Prompt user or auto-push
+
+If no markers exist in PLAN.md, skip this step (single-user mode).
+
 ### Step 2: Detect Test Framework
 
+#### Check TLC Config First
+
+If `.tlc.json` exists, use configured frameworks:
+
+```json
+{
+  "testFrameworks": {
+    "primary": "mocha",
+    "installed": ["mocha", "chai", "sinon", "proxyquire"],
+    "run": ["mocha"]
+  }
+}
+```
+
+#### Auto-Detection (No Config)
+
 Check what's already set up:
+- `.tlc.json` → Use configured framework
+- `mocha` in package.json → Mocha (TLC default)
+- `.mocharc.*` or `mocha.opts` → Mocha
 - `vitest.config.*` → Vitest
 - `jest.config.*` → Jest
 - `pytest.ini` or `pyproject.toml` with pytest → pytest
 - `spec/` directory → RSpec
-- None found → Set up based on PROJECT.md stack (see framework defaults below)
+- None found → Set up mocha stack (TLC default)
 
 ### Step 3: Plan Tests for Each Task
 
@@ -84,7 +133,49 @@ Follow the project's test patterns. Test names should describe expected behavior
 ✗ "test login" (too vague)
 ```
 
-**Vitest/Jest (TypeScript):**
+**Mocha/Chai (TLC Default):**
+```javascript
+const { expect } = require('chai')
+const sinon = require('sinon')
+const proxyquire = require('proxyquire')
+
+describe('login', () => {
+  let login, dbStub
+
+  beforeEach(() => {
+    dbStub = sinon.stub()
+    login = proxyquire('../src/auth/login', {
+      './db': { findUser: dbStub }
+    })
+  })
+
+  afterEach(() => {
+    sinon.restore()
+  })
+
+  it('returns user object for valid credentials', async () => {
+    dbStub.resolves({ id: 1, email: 'user@test.com' })
+
+    const result = await login('user@test.com', 'password123')
+
+    expect(result.user).to.exist
+    expect(result.user.email).to.equal('user@test.com')
+  })
+
+  it('throws AuthError for invalid password', async () => {
+    dbStub.resolves(null)
+
+    try {
+      await login('user@test.com', 'wrong')
+      expect.fail('Should have thrown')
+    } catch (err) {
+      expect(err.message).to.equal('Invalid credentials')
+    }
+  })
+})
+```
+
+**Vitest/Jest (Alternative):**
 ```typescript
 import { describe, it, expect } from 'vitest'
 import { login } from '../src/auth/login'
@@ -223,7 +314,15 @@ git add src/auth/login.ts tests/auth/login.test.ts
 git commit -m "feat: {task-title} - phase {N}"
 ```
 
-#### 7e. Move to next task
+#### 7e. Mark Task Complete (Multi-User)
+
+If using multi-user mode (task had `[>@user]` marker):
+
+1. Update marker: `[>@{user}]` → `[x@{user}]`
+2. Commit: `git commit -m "complete: task {N} - {title} (@{user})"`
+3. Push to share progress with team
+
+#### 7f. Move to next task
 Repeat 7a-7d for each task in the phase.
 
 **Critical Rules:**
@@ -255,31 +354,78 @@ Status: ✅ All tests passing (Green)
 {test runner output showing all pass}
 ```
 
-## Framework Defaults (for new projects)
+## Framework Defaults
 
-If no test framework detected, set up based on PROJECT.md:
+### TLC Default: Mocha Stack
 
-| Stack in PROJECT.md | Framework | Setup |
-|---------------------|-----------|-------|
-| Next.js, React, Vite | Vitest | `npm install -D vitest`, create `vitest.config.ts` |
-| Node.js, Express | Vitest | `npm install -D vitest`, create `vitest.config.ts` |
-| Python, FastAPI, Flask | pytest | `pip install pytest`, create `pytest.ini` |
-| Go | go test | Built-in, create `*_test.go` files |
-| Ruby, Rails | RSpec | `gem install rspec`, `rspec --init` |
+For JavaScript/TypeScript projects, TLC defaults to the mocha ecosystem:
 
-Default Vitest config:
-```typescript
-import { defineConfig } from 'vitest/config'
+| Library | Purpose | Install |
+|---------|---------|---------|
+| **mocha** | Test runner | `npm install -D mocha` |
+| **chai** | Assertions | `npm install -D chai` |
+| **sinon** | Mocks/stubs/spies | `npm install -D sinon` |
+| **proxyquire** | Module mocking | `npm install -D proxyquire` |
 
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node', // or 'jsdom' for React
+Full setup:
+```bash
+npm install -D mocha chai sinon proxyquire @types/mocha @types/chai @types/sinon
+```
+
+Default `.mocharc.json`:
+```json
+{
+  "extension": ["js", "ts"],
+  "spec": "test/**/*.test.{js,ts}",
+  "require": ["ts-node/register"],
+  "timeout": 5000
+}
+```
+
+Default `package.json` scripts:
+```json
+{
+  "scripts": {
+    "test": "mocha",
+    "test:watch": "mocha --watch"
+  }
+}
+```
+
+### Alternative Frameworks
+
+| Stack | Framework | Setup |
+|-------|-----------|-------|
+| Vite projects | Vitest | `npm install -D vitest` |
+| React/Meta ecosystem | Jest | `npm install -D jest` |
+| Python | pytest | `pip install pytest` |
+| Go | go test | Built-in |
+| Ruby | RSpec | `gem install rspec` |
+
+To use an alternative, run `/tlc:config` to configure.
+
+### Multi-Framework Support
+
+Projects can have multiple test frameworks. Configure in `.tlc.json`:
+
+```json
+{
+  "testFrameworks": {
+    "primary": "mocha",
+    "installed": ["mocha", "chai", "sinon", "jest"],
+    "run": ["mocha", "jest"]
   },
-})
+  "commands": {
+    "mocha": "npx mocha 'test/**/*.test.js'",
+    "jest": "npx jest",
+    "all": "npm test"
+  }
+}
 ```
 
-Default pytest.ini:
+When running tests, TLC will execute all frameworks in the `run` array.
+
+Default pytest.ini (Python):
 ```ini
 [pytest]
 testpaths = tests

package/ci.md

@@ -0,0 +1,414 @@
+# /tlc:ci - CI/CD Integration
+
+Generate CI/CD pipeline configuration for your TLC project.
+
+## Usage
+
+```
+/tlc:ci [provider]
+```
+
+Providers: `github`, `gitlab`, `bitbucket`, `azure`, `circle`
+
+If no provider specified, auto-detects from git remote.
+
+## What This Does
+
+1. Detects your CI/CD platform from git remote
+2. Generates appropriate config file
+3. Includes test-first validation
+4. Adds regression test gates
+
+## GitHub Actions
+
+Creates `.github/workflows/tlc.yml`:
+
+```yaml
+name: TLC Pipeline
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        if: always()
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run lint
+
+  regression:
+    runs-on: ubuntu-latest
+    needs: [test]
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Check for untested code
+        run: |
+          # Get changed files
+          CHANGED=$(git diff --name-only origin/main...HEAD | grep -E '\.(ts|js|tsx|jsx)$' | grep -v '\.test\.' || true)
+
+          if [ -n "$CHANGED" ]; then
+            echo "Changed source files:"
+            echo "$CHANGED"
+
+            # Check each has corresponding test
+            for file in $CHANGED; do
+              testfile="${file%.*}.test.${file##*.}"
+              if [ ! -f "$testfile" ]; then
+                echo "::warning file=$file::No test file found for $file"
+              fi
+            done
+          fi
+
+      - name: Run regression tests
+        run: npm test -- --coverage
+
+      - name: Coverage diff
+        run: |
+          # Compare coverage with base branch
+          echo "Coverage report generated"
+```
+
+## GitLab CI
+
+Creates `.gitlab-ci.yml`:
+
+```yaml
+stages:
+  - test
+  - regression
+
+default:
+  image: node:20
+  cache:
+    paths:
+      - node_modules/
+
+test:
+  stage: test
+  script:
+    - npm ci
+    - npm test
+  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage/cobertura-coverage.xml
+
+lint:
+  stage: test
+  script:
+    - npm ci
+    - npm run lint
+  allow_failure: true
+
+regression:
+  stage: regression
+  only:
+    - merge_requests
+  script:
+    - npm ci
+    - |
+      CHANGED=$(git diff --name-only $CI_MERGE_REQUEST_DIFF_BASE_SHA...HEAD | grep -E '\.(ts|js)$' | grep -v '\.test\.' || true)
+      if [ -n "$CHANGED" ]; then
+        echo "Checking tests for changed files..."
+        for file in $CHANGED; do
+          testfile="${file%.*}.test.${file##*.}"
+          if [ ! -f "$testfile" ]; then
+            echo "WARNING: No test file for $file"
+          fi
+        done
+      fi
+    - npm test -- --coverage
+```
+
+## Bitbucket Pipelines
+
+Creates `bitbucket-pipelines.yml`:
+
+```yaml
+image: node:20
+
+definitions:
+  caches:
+    npm: ~/.npm
+
+pipelines:
+  default:
+    - step:
+        name: Test
+        caches:
+          - npm
+        script:
+          - npm ci
+          - npm test
+
+  pull-requests:
+    '**':
+      - step:
+          name: Test
+          caches:
+            - npm
+          script:
+            - npm ci
+            - npm test
+      - step:
+          name: Regression Check
+          caches:
+            - npm
+          script:
+            - npm ci
+            - npm test -- --coverage
+```
+
+## Azure Pipelines
+
+Creates `azure-pipelines.yml`:
+
+```yaml
+trigger:
+  - main
+  - develop
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+stages:
+  - stage: Test
+    jobs:
+      - job: Test
+        steps:
+          - task: NodeTool@0
+            inputs:
+              versionSpec: '20.x'
+
+          - script: npm ci
+            displayName: Install dependencies
+
+          - script: npm test
+            displayName: Run tests
+
+          - task: PublishCodeCoverageResults@2
+            inputs:
+              summaryFileLocation: '$(System.DefaultWorkingDirectory)/coverage/cobertura-coverage.xml'
+
+  - stage: Regression
+    condition: eq(variables['Build.Reason'], 'PullRequest')
+    jobs:
+      - job: Regression
+        steps:
+          - task: NodeTool@0
+            inputs:
+              versionSpec: '20.x'
+          - script: npm ci
+          - script: npm test -- --coverage
+            displayName: Regression tests
+```
+
+## CircleCI
+
+Creates `.circleci/config.yml`:
+
+```yaml
+version: 2.1
+
+executors:
+  node:
+    docker:
+      - image: cimg/node:20.0
+
+jobs:
+  test:
+    executor: node
+    steps:
+      - checkout
+      - restore_cache:
+          keys:
+            - npm-{{ checksum "package-lock.json" }}
+      - run: npm ci
+      - save_cache:
+          paths:
+            - node_modules
+          key: npm-{{ checksum "package-lock.json" }}
+      - run: npm test
+      - store_test_results:
+          path: test-results
+      - store_artifacts:
+          path: coverage
+
+  regression:
+    executor: node
+    steps:
+      - checkout
+      - restore_cache:
+          keys:
+            - npm-{{ checksum "package-lock.json" }}
+      - run: npm ci
+      - run:
+          name: Check for untested code
+          command: |
+            CHANGED=$(git diff --name-only origin/main...HEAD | grep -E '\.(ts|js)$' | grep -v '\.test\.' || true)
+            if [ -n "$CHANGED" ]; then
+              echo "Changed files: $CHANGED"
+            fi
+      - run: npm test -- --coverage
+
+workflows:
+  test-and-deploy:
+    jobs:
+      - test
+      - regression:
+          filters:
+            branches:
+              ignore: main
+```
+
+## Regression Test Features
+
+### Automatic Detection
+
+The CI config includes regression checks that:
+
+1. **Identify changed files** in the PR/MR
+2. **Verify test coverage** for changed files
+3. **Run full test suite** to catch regressions
+4. **Report coverage diff** vs base branch
+
+### Configuring Regression Behavior
+
+In `.tlc.json`:
+
+```json
+{
+  "ci": {
+    "requireTestsForNewFiles": true,
+    "coverageThreshold": 80,
+    "failOnCoverageDecrease": true,
+    "regressionOnPR": true
+  }
+}
+```
+
+### Coverage Requirements
+
+Set minimum coverage in `package.json`:
+
+```json
+{
+  "jest": {
+    "coverageThreshold": {
+      "global": {
+        "branches": 80,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    }
+  }
+}
+```
+
+Or for mocha with nyc:
+
+```json
+{
+  "nyc": {
+    "check-coverage": true,
+    "lines": 80,
+    "functions": 80,
+    "branches": 80
+  }
+}
+```
+
+## Import/Merge Regression
+
+When importing external code (`/tlc:import-project`), automatically run regression:
+
+```
+> /tlc:import-project ../legacy-api
+
+Importing legacy-api...
+
+Found 47 source files without tests.
+
+Running regression tests on merge...
+  ✓ 23 existing tests pass
+  ⚠ 12 new files need tests
+
+Create tasks for missing tests? (Y/n)
+```
+
+## Example Session
+
+```
+> /tlc:ci
+
+Detecting CI/CD platform...
+  Remote: git@github.com:acme/myproject.git
+  Platform: GitHub
+
+Generating .github/workflows/tlc.yml...
+
+Created CI pipeline with:
+  ✓ Test job (runs on all pushes)
+  ✓ Lint job (runs on all pushes)
+  ✓ Regression job (runs on PRs)
+  ✓ Coverage reporting (Codecov)
+
+Commit this file? (Y/n) y
+
+Committed: ci: add TLC GitHub Actions pipeline
+
+Next steps:
+  1. Push to GitHub
+  2. Add CODECOV_TOKEN secret (optional)
+  3. PRs will now require passing tests
+```
+
+## Notes
+
+- CI config respects `.tlc.json` settings
+- Coverage thresholds match project config
+- Regression checks are PR-only by default
+- Use `/tlc:ci --dry-run` to preview without creating files