tlc-claude-code 1.5.2 → 1.5.4

package/.claude/commands/tlc/refactor.md

@@ -0,0 +1,190 @@
+# /tlc:refactor - Step-by-Step Standards Refactoring
+
+Fix coding standards violations one step at a time with previews and checkpoints.
+
+## What This Does
+
+Same fixes as `/tlc:cleanup` but:
+- Shows preview before each change
+- Waits for confirmation
+- Can skip individual steps
+- Can abort at any point
+- Saves checkpoints for resume
+
+## Usage
+
+```
+/tlc:refactor
+```
+
+## Process
+
+### Step 1: Create or Resume Session
+
+Check for existing checkpoint:
+
+```javascript
+const { loadCheckpoint, createRefactorSession } = require('./lib/standards/refactor-stepper');
+
+let session = await loadCheckpoint(projectPath);
+if (session) {
+  console.log('Found checkpoint from', session.savedAt);
+  console.log('Resume? [Y/n]');
+  // If yes, resume; if no, start fresh
+} else {
+  const auditResults = await auditProject(projectPath);
+  session = await createRefactorSession(projectPath, auditResults);
+}
+```
+
+### Step 2: Show Session Overview
+
+```
+TLC Refactor - Step-by-Step Standards Fix
+═══════════════════════════════════════════════════════════════
+
+Session: abc123
+Steps: 11 total
+  - 4 config extractions
+  - 3 folder migrations
+  - 2 interface extractions
+  - 2 constant replacements
+
+Press Enter to start, or 'q' to quit: _
+```
+
+### Step 3: For Each Step
+
+#### Show Preview
+
+```
+Step 1/11: Extract hardcoded URL
+═══════════════════════════════════════════════════════════════
+
+File: src/api.ts
+
+BEFORE:
+  15 │ fetch('http://localhost:3000/api/users');
+
+AFTER:
+  15 │ fetch((process.env.API_URL || 'http://localhost:3000') + '/api/users');
+
+Environment variable: API_URL
+Default value: http://localhost:3000
+
+───────────────────────────────────────────────────────────────
+[Enter] Apply  [s] Skip  [q] Quit  [?] Help: _
+```
+
+#### Handle User Input
+
+| Key | Action |
+|-----|--------|
+| Enter | Apply the change |
+| s | Skip this step |
+| q | Quit and save checkpoint |
+| ? | Show help |
+
+#### After Apply
+
+```
+✓ Applied: Extracted API_URL
+
+Commit this change? [Y/n]: y
+✓ Committed: refactor(api): extract API_URL to environment
+
+Continuing to step 2/11...
+```
+
+### Step 4: Handle Skip
+
+```
+Step 5/11: Migrate src/services/user.service.ts
+═══════════════════════════════════════════════════════════════
+
+Skip this step? Enter reason (optional): Not applicable - this is a shared utility
+
+✓ Skipped: Migrate user.service.ts
+  Reason: Not applicable - this is a shared utility
+
+Continuing to step 6/11...
+```
+
+### Step 5: Handle Abort
+
+```
+Aborting session...
+
+Progress saved to: .planning/refactor-checkpoint.json
+
+Completed: 4/11 steps
+Skipped: 1 step
+Remaining: 6 steps
+
+Resume later with: /tlc:refactor
+```
+
+### Step 6: Completion
+
+```
+TLC Refactor Complete
+═══════════════════════════════════════════════════════════════
+
+Session: abc123
+Duration: 12 minutes
+
+Results:
+  ✓ Applied: 9 steps
+  ○ Skipped: 2 steps
+
+Commits created: 5
+  - refactor(api): extract environment variables
+  - refactor(user): migrate to entity folder
+  - refactor(user): extract interfaces to types/
+  - refactor(product): migrate to entity folder
+  - refactor(shared): add JSDoc comments
+
+All selected fixes applied. Run /tlc:audit to verify.
+```
+
+## Checkpoint Format
+
+Saved to `.planning/refactor-checkpoint.json`:
+
+```json
+{
+  "id": "session-abc123",
+  "projectPath": "/path/to/project",
+  "savedAt": "2024-01-15T10:30:00Z",
+  "currentStep": 4,
+  "steps": [
+    { "id": "1", "type": "extract-config", "status": "completed" },
+    { "id": "2", "type": "extract-config", "status": "completed" },
+    { "id": "3", "type": "migrate-folder", "status": "completed" },
+    { "id": "4", "type": "migrate-folder", "status": "skipped", "skipReason": "Shared utility" },
+    { "id": "5", "type": "extract-interface", "status": "pending" }
+  ]
+}
+```
+
+## Step Priority Order
+
+Steps are ordered for safe execution:
+
+1. **Extract config** - Environment variables first (no structural changes)
+2. **Migrate folders** - Move files to entity structure
+3. **Extract interfaces** - Pull types to separate files
+4. **Replace constants** - Add constants files
+5. **Add JSDoc** - Documentation last (doesn't affect imports)
+
+## When to Use
+
+- **Learning**: Understand what each change does
+- **Selective fixes**: Skip changes that don't apply
+- **Large codebase**: Take breaks, resume later
+- **Review**: Want to approve each change
+
+## See Also
+
+- `/tlc:audit` - Check without fixing
+- `/tlc:cleanup` - Fix everything automatically

package/.claude/commands/tlc/release.md

@@ -0,0 +1,135 @@
+# /tlc:release - Release a Task
+
+Release a task you claimed so others can work on it.
+
+## Usage
+
+```
+/tlc:release [task-number]
+```
+
+## When to Use
+
+- Blocked and can't continue
+- Switching to a different task
+- End of day, won't finish
+- Decided task approach needs rethinking
+
+## Process
+
+### Step 1: Identify User
+
+Get current user identity (same as `/tlc:claim`):
+
+```bash
+if [ -n "$TLC_USER" ]; then
+  user=$TLC_USER
+else
+  user=$(git config user.name | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+fi
+```
+
+### Step 2: Find Your Claims
+
+Parse current phase PLAN.md for tasks claimed by you:
+
+```
+Looking for tasks claimed by @alice...
+
+Your claimed tasks:
+  2. Add validation [>@alice]
+  5. Error handling [>@alice]
+```
+
+### Step 3: Select Task to Release
+
+If task-number provided:
+- Verify you own that task
+- If not yours, show error
+
+If not provided:
+- Show your claimed tasks
+- Prompt to select one
+
+### Step 4: Update Task Marker
+
+Change from claimed to available:
+
+```markdown
+### Task 2: Add validation [>@alice]
+```
+
+becomes:
+
+```markdown
+### Task 2: Add validation [ ]
+```
+
+### Step 5: Commit and Push
+
+```bash
+git add .planning/phases/{N}-PLAN.md
+git commit -m "release: task {N} - {title} (@{user})"
+git push
+```
+
+## Example Session
+
+```
+> /tlc:release
+
+Your claimed tasks in Phase 1:
+  2. Add validation [>@alice]
+  5. Error handling [>@alice]
+
+Release which task? [2/5]: 2
+
+Task 2: Add validation [>@alice] → [ ]
+
+✓ Committed: release: task 2 - Add validation (@alice)
+✓ Pushed
+
+Task 2 is now available for others.
+```
+
+## With Task Number
+
+```
+> /tlc:release 2
+
+Task 2: Add validation [>@alice] → [ ]
+
+✓ Committed: release: task 2 - Add validation (@alice)
+✓ Pushed
+
+Task 2 is now available for others.
+```
+
+## Error Handling
+
+**Not your task:**
+```
+Task 2 is claimed by @bob, not you.
+You can only release your own tasks.
+
+Your tasks: 5
+```
+
+**Task not claimed:**
+```
+Task 2 is not claimed (already available).
+Nothing to release.
+```
+
+**No tasks claimed:**
+```
+You have no claimed tasks in Phase 1.
+Use /tlc:claim to claim a task.
+```
+
+## Notes
+
+- Releasing doesn't undo any work you've done
+- Your commits remain in history
+- Another teammate can claim and continue where you left off
+- Consider adding a note to the task if you made partial progress

package/.claude/commands/tlc/review-pr.md

@@ -0,0 +1,184 @@
+# /tlc:review-pr - Review a Pull Request
+
+Review a GitHub/GitLab pull request for TLC compliance.
+
+## What This Does
+
+1. Fetches PR diff from GitHub/GitLab
+2. Checks test coverage for all changed files
+3. Analyzes commit order for TDD compliance
+4. Scans for security issues
+5. Posts review comment with verdict
+
+## Usage
+
+```
+/tlc:review-pr <pr_number>
+/tlc:review-pr <pr_url>
+/tlc:review-pr              # Review current PR (if on PR branch)
+```
+
+## Process
+
+### Step 1: Fetch PR Information
+
+```bash
+# Get PR details
+gh pr view <number> --json number,title,headRefName,baseRefName,additions,deletions
+
+# Get changed files
+gh pr diff <number> --name-only
+```
+
+### Step 2: Checkout PR Branch (if needed)
+
+```bash
+gh pr checkout <number>
+```
+
+### Step 3: Run Full Review
+
+Same checks as `/tlc:review`:
+- Test coverage for changed files
+- TDD compliance (commit order)
+- Security scan
+
+### Step 4: Generate PR Comment
+
+```markdown
+## 🤖 TLC Code Review
+
+| Check | Status |
+|-------|--------|
+| Test Coverage | ✅ All files covered |
+| TDD Score | ✅ 75% |
+| Security | ✅ No issues |
+
+### Summary
+
+- 8 files changed (5 impl, 3 tests)
+- 4 commits analyzed
+- No security vulnerabilities detected
+
+### Verdict: ✅ APPROVED
+
+---
+*Automated review by [TLC](https://github.com/jurgencalleja/TLC)*
+```
+
+### Step 5: Post Review
+
+```bash
+# Post as PR comment
+gh pr comment <number> --body "<review_markdown>"
+
+# Or submit as review
+gh pr review <number> --approve --body "<review_markdown>"
+gh pr review <number> --request-changes --body "<review_markdown>"
+```
+
+## Example Output
+
+### Reviewing PR #42
+
+```
+/tlc:review-pr 42
+
+Fetching PR #42: "Add user authentication"
+Branch: feature/auth → main
+Author: @alice
+
+Fetching diff...
+Changed files: 6
+├── src/auth/login.js (+120, -0)
+├── src/auth/login.test.js (+85, -0) ✓
+├── src/auth/session.js (+45, -0)
+├── src/auth/session.test.js (+60, -0) ✓
+├── src/middleware/auth.js (+30, -0)
+└── src/middleware/auth.test.js (+40, -0) ✓
+
+Running checks...
+
+Test coverage: ✅ All implementation files have tests
+TDD Score: 67% ✅
+Security: ✅ No issues
+
+Posting review...
+
+─────────────────────────────────
+✅ PR #42 APPROVED
+
+Review posted: https://github.com/org/repo/pull/42#review-123456
+─────────────────────────────────
+```
+
+### PR with Issues
+
+```
+/tlc:review-pr 43
+
+Fetching PR #43: "Quick fix for login"
+Branch: hotfix/login → main
+
+Changed files: 2
+├── src/auth/login.js (+15, -3)
+└── src/config.js (+2, -0)
+
+Running checks...
+
+Test coverage: ❌ 2 files without tests
+├── src/auth/login.js (modified, existing tests may not cover changes)
+└── src/config.js (no test file found)
+
+TDD Score: 0% ❌
+Security: ⚠️ 1 medium severity issue
+└── console.log with sensitive data
+
+Posting review...
+
+─────────────────────────────────
+❌ PR #43 CHANGES REQUESTED
+
+Review posted with requested changes.
+See: https://github.com/org/repo/pull/43#review-123457
+
+Required actions:
+1. Add/update tests for modified files
+2. Remove console.log with sensitive data
+─────────────────────────────────
+```
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--no-post` | Generate review but don't post to PR |
+| `--approve` | Force approve (skip checks) |
+| `--comment-only` | Post as comment instead of review |
+
+## GitHub Actions Integration
+
+Add to your workflow:
+
+```yaml
+name: TLC Review
+on: [pull_request]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: TLC Review
+        run: |
+          npx tlc-claude-code review-pr ${{ github.event.pull_request.number }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## ARGUMENTS
+
+$ARGUMENTS

package/.claude/commands/tlc/review.md

@@ -0,0 +1,200 @@
+# /tlc:review - Review Current Branch
+
+Review changes on current branch before pushing.
+
+## What This Does
+
+1. Compares current branch to main/master
+2. Checks test coverage for all changed files
+3. Analyzes commit order for TDD compliance
+4. Scans for security issues
+5. Generates verdict: APPROVED or CHANGES_REQUESTED
+
+**This runs automatically at the end of `/tlc:build`.**
+
+## Usage
+
+```
+/tlc:review              # Review current branch vs main
+/tlc:review --base dev   # Review vs different base branch
+```
+
+## Process
+
+### Step 1: Identify Changes
+
+```bash
+git diff --name-status main...HEAD
+```
+
+Categorize files:
+- Implementation files (`.js`, `.ts`, `.py`, etc.)
+- Test files (`*.test.*`, `test_*`, `*_test.*`)
+- Other files (docs, config, etc.)
+
+### Step 2: Check Test Coverage
+
+For each implementation file, verify a corresponding test exists:
+
+| Implementation | Expected Test |
+|---------------|---------------|
+| `src/auth.js` | `src/auth.test.js` or `test/auth.test.js` |
+| `lib/utils.ts` | `lib/utils.test.ts` or `tests/utils.test.ts` |
+| `pkg/main.go` | `pkg/main_test.go` |
+| `src/login.py` | `tests/test_login.py` |
+
+**Fail if:** Implementation files have no corresponding test (in changeset or on disk).
+
+### Step 3: Analyze TDD Compliance
+
+Check commit order to verify tests were written first:
+
+```bash
+git log --oneline --name-status main..HEAD
+```
+
+**Score calculation:**
+- Test-only commits → +1 TDD point
+- Implementation-only commits → -1 TDD point (except fix/refactor/chore)
+- Mixed commits → neutral
+
+**TDD Score = (test-first commits / total commits) × 100**
+
+**Fail if:** TDD score < 50% with more than 2 commits.
+
+### Step 4: Security Scan
+
+Scan diff for common security issues:
+
+| Pattern | Issue | Severity |
+|---------|-------|----------|
+| `password = "..."` | Hardcoded password | HIGH |
+| `api_key = "..."` | Hardcoded API key | HIGH |
+| `eval(...)` | Code injection risk | MEDIUM |
+| `innerHTML =` | XSS risk | MEDIUM |
+| `dangerouslySetInnerHTML` | React XSS risk | MEDIUM |
+| `exec("..." + var)` | Command injection | HIGH |
+| `SELECT...WHERE...+` | SQL injection | HIGH |
+
+**Fail if:** Any HIGH severity issues found.
+
+### Step 5: Generate Report
+
+```markdown
+# Code Review Report
+
+**Date:** 2024-01-15T10:30:00Z
+**Base:** main → **Head:** feature/auth
+
+## ✅ Verdict: APPROVED
+
+## Summary
+
+- ✅ All changed files have tests
+- ✅ TDD score: 75%
+- ✅ No security issues detected
+
+## Statistics
+
+- Files changed: 8
+- Implementation files: 5
+- Test files: 3
+- Commits: 4
+- TDD Score: 75%
+```
+
+### Step 6: Return Verdict
+
+**APPROVED** - All checks pass. Ready to push/merge.
+
+**CHANGES_REQUESTED** - Issues found:
+- Missing tests → Add tests for flagged files
+- Low TDD score → Consider reordering commits or adding test commits
+- Security issues → Fix flagged patterns
+
+## Example Output
+
+### Passing Review
+
+```
+/tlc:review
+
+Reviewing current branch vs main...
+
+Changed files: 6
+├── src/auth/login.js (impl)
+├── src/auth/login.test.js (test) ✓
+├── src/auth/session.js (impl)
+├── src/auth/session.test.js (test) ✓
+└── README.md (docs)
+
+Test coverage: ✅ All implementation files have tests
+
+Commit analysis:
+├── abc1234 test: add login tests
+├── def5678 feat: implement login
+├── ghi9012 test: add session tests
+└── jkl3456 feat: implement session
+
+TDD Score: 50% ✅
+
+Security scan: ✅ No issues found
+
+─────────────────────────────
+✅ APPROVED - Ready to push
+─────────────────────────────
+```
+
+### Failing Review
+
+```
+/tlc:review
+
+Reviewing current branch vs main...
+
+Changed files: 4
+├── src/api/users.js (impl)
+├── src/api/auth.js (impl)
+└── src/utils.js (impl)
+
+Test coverage: ❌ 3 files missing tests
+├── src/api/users.js → needs src/api/users.test.js
+├── src/api/auth.js → needs src/api/auth.test.js
+└── src/utils.js → needs src/utils.test.js
+
+Commit analysis:
+└── abc1234 feat: add all features
+
+TDD Score: 0% ❌ (target: 50%+)
+
+Security scan: ❌ 1 high severity issue
+└── src/api/auth.js: password = "admin123"
+
+───────────────────────────────────
+❌ CHANGES_REQUESTED
+
+Action required:
+1. Add tests for 3 implementation files
+2. Fix hardcoded password in src/api/auth.js
+3. Consider splitting into test-first commits
+───────────────────────────────────
+```
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--base <branch>` | Compare against different base (default: main) |
+| `--strict` | Fail on any TDD violation |
+| `--no-security` | Skip security scan |
+
+## Integration
+
+This review runs automatically:
+- At the end of `/tlc:build` (blocks completion if fails)
+- Before `/tlc:verify` (informational)
+- Can be run manually anytime
+
+## ARGUMENTS
+
+$ARGUMENTS