tlc-claude-code 1.5.3 → 1.5.4

package/.claude/commands/tlc/discuss.md

@@ -0,0 +1,185 @@
+# /tlc:discuss - Discuss Phase Implementation
+
+Capture implementation preferences before planning.
+
+## What This Does
+
+Gathers your preferences for HOW a phase should be built through adaptive questioning. Saves decisions to guide planning and test writing.
+
+## Usage
+
+```
+/tlc:discuss [phase_number]
+```
+
+If no phase number, auto-detect current phase from ROADMAP.md.
+
+## Process
+
+### Step 1: Load Phase Context
+
+Read from `.planning/ROADMAP.md` to get:
+- Phase name and goal
+- What comes before (context)
+- What comes after (constraints)
+
+### Step 2: Adaptive Questioning
+
+Ask about implementation preferences. Adapt questions based on phase type.
+
+**For UI/Frontend phases:**
+```
+Layout approach?
+1) Component library (shadcn, MUI, etc.)
+2) Custom components
+3) Minimal styling (Tailwind only)
+
+State management?
+1) React state + context
+2) Zustand / Jotai
+3) Redux
+4) Server state only (React Query)
+
+Form handling?
+1) React Hook Form
+2) Formik
+3) Native forms
+```
+
+**For API/Backend phases:**
+```
+API style?
+1) REST
+2) tRPC
+3) GraphQL
+
+Validation approach?
+1) Zod schemas
+2) Yup
+3) Manual validation
+
+Error handling?
+1) Return error objects
+2) Throw exceptions
+3) Result types (Ok/Err)
+```
+
+**For Data/Database phases:**
+```
+Query approach?
+1) Raw SQL
+2) Query builder (Kysely, Knex)
+3) ORM (Prisma, Drizzle)
+
+Migration strategy?
+1) Schema-first (Prisma migrate)
+2) Code-first
+3) Manual SQL migrations
+```
+
+**For Auth phases:**
+```
+Auth provider?
+1) Custom (JWT + bcrypt)
+2) NextAuth / Auth.js
+3) Clerk / Auth0 / Supabase Auth
+
+Session storage?
+1) JWT in httpOnly cookie
+2) Database sessions
+3) Redis sessions
+```
+
+### Step 3: Capture Edge Cases
+
+```
+What edge cases should we handle?
+
+- Empty states?
+- Error states?
+- Loading states?
+- Offline behavior?
+- Rate limiting?
+```
+
+### Step 4: Capture Constraints
+
+```
+Any constraints or requirements?
+
+- Performance targets?
+- Accessibility requirements?
+- Browser support?
+- Mobile considerations?
+```
+
+### Step 5: Save Discussion
+
+Create `.planning/phases/{N}-DISCUSSION.md`:
+
+```markdown
+# Phase {N}: {Name} - Discussion
+
+## Implementation Preferences
+
+| Decision | Choice | Notes |
+|----------|--------|-------|
+| State management | Zustand | Simple, minimal boilerplate |
+| Form handling | React Hook Form | Good validation support |
+| API style | tRPC | Type-safe, good DX |
+
+## Edge Cases to Handle
+
+- [ ] Empty state when no data
+- [ ] Error toast on API failure
+- [ ] Optimistic updates for better UX
+
+## Constraints
+
+- Must work on mobile
+- Target 100ms API response time
+
+## Notes
+
+[Any additional context from discussion]
+```
+
+### Step 6: Confirm and Continue
+
+```
+Discussion saved to .planning/phases/{N}-DISCUSSION.md
+
+Ready to plan this phase?
+1) Yes, continue to /tlc:plan
+2) No, I'll plan later
+```
+
+## Example
+
+```
+> /tlc:discuss 2
+
+Phase 2: User Dashboard
+
+Let's discuss how to build this.
+
+State management approach?
+1) React state + context
+2) Zustand
+3) Server state only (React Query)
+
+> 3
+
+Data fetching?
+1) REST + fetch
+2) tRPC
+3) React Query + REST
+
+> 2
+
+[...continues until preferences captured...]
+
+Discussion saved.
+
+Ready to plan? (Y/n)
+```

package/.claude/commands/tlc/docs.md

@@ -0,0 +1,194 @@
+# /tlc:docs - Documentation Maintenance
+
+Automatically maintain your project's documentation, screenshots, and wiki.
+
+## Usage
+
+```bash
+/tlc:docs                    # Full docs update
+/tlc:docs setup              # Set up automation (first time)
+/tlc:docs screenshots        # Capture app screenshots
+/tlc:docs readme             # Update README
+/tlc:docs api                # Generate API docs
+```
+
+## What This Does
+
+### Setup (`/tlc:docs setup`)
+
+First-time setup for your project:
+
+1. Creates `docs/` directory structure
+2. Adds `.github/workflows/docs-sync.yml` for auto-sync on push
+3. Adds npm scripts (`npm run docs`, `npm run docs:screenshots`)
+4. Creates initial `docs/getting-started.md`
+
+After setup, docs update automatically on every push.
+
+### Full Update (`/tlc:docs`)
+
+1. **Updates version references** in all docs
+2. **Generates API docs** (TypeDoc for TypeScript)
+3. **Captures screenshots** of running app (via Playwright)
+4. **Validates links** in documentation
+
+### Screenshots (`/tlc:docs screenshots`)
+
+Uses Playwright to capture real screenshots:
+
+1. Installs Playwright if not present
+2. Launches headless browser
+3. Captures pages at common URLs:
+   - `localhost:3000` (homepage)
+   - `localhost:3000/dashboard`
+   - `localhost:5001` (TLC app proxy)
+   - `localhost:3147` (TLC dashboard)
+4. Saves to `docs/images/`
+
+**Note:** Your app should be running for screenshots to work.
+
+## Automation
+
+Once set up, GitHub Actions automatically:
+
+1. **On every push to main:**
+   - Updates version references
+   - Syncs to GitHub Wiki
+   - Commits any doc changes
+
+2. **You don't need to manually maintain docs.** Just push code.
+
+## Process
+
+### Step 1: Run Setup (Once)
+
+```
+/tlc:docs setup
+
+Setting up documentation automation...
+
+  ✓ Created docs/ directory
+  ✓ Created docs/images/ directory
+  ✓ Created .github/workflows/docs-sync.yml
+  ✓ Added docs scripts to package.json
+  ✓ Created docs/getting-started.md
+
+✓ Documentation setup complete!
+
+Next steps:
+  1. Push to GitHub to enable wiki sync
+  2. Run /tlc:docs to update documentation
+  3. Run /tlc:docs screenshots to capture app screenshots
+```
+
+### Step 2: Update Docs (Anytime)
+
+```
+/tlc:docs
+
+TLC Documentation Update
+══════════════════════════════════════════════════
+
+Project: my-app v1.2.0
+
+📄 README
+  ✓ Updated version references
+
+📚 API Documentation
+  Detecting TypeScript, using TypeDoc...
+  ✓ Generated API docs in docs/api/
+
+📸 Screenshots
+  ✓ homepage.png
+  ✓ dashboard.png
+  ⚠ app.png (app not running)
+
+══════════════════════════════════════════════════
+
+✓ Documentation updated!
+```
+
+### Step 3: Push (Auto-Sync)
+
+```bash
+git push
+```
+
+GitHub Actions will:
+- Sync docs to GitHub Wiki
+- Update any version references
+- Commit changes back
+
+## Configuration
+
+In `.tlc.json` (optional):
+
+```json
+{
+  "docs": {
+    "dir": "docs",
+    "screenshots": {
+      "urls": [
+        { "url": "http://localhost:3000", "name": "home" },
+        { "url": "http://localhost:3000/login", "name": "login" }
+      ]
+    },
+    "api": {
+      "enabled": true,
+      "output": "docs/api"
+    }
+  }
+}
+```
+
+## CLI Usage
+
+Also available as standalone command:
+
+```bash
+npx tlc-docs              # Full update
+npx tlc-docs setup        # First-time setup
+npx tlc-docs screenshots  # Capture screenshots
+npx tlc-docs api          # Generate API docs
+```
+
+Or add to package.json scripts:
+
+```json
+{
+  "scripts": {
+    "docs": "tlc-docs",
+    "docs:screenshots": "tlc-docs screenshots"
+  }
+}
+```
+
+## Requirements
+
+- **Playwright** (auto-installed for screenshots)
+- **TypeDoc** (auto-used if TypeScript detected)
+- **GitHub repo** (for wiki sync)
+
+## Troubleshooting
+
+### Screenshots not capturing
+
+Make sure your app is running:
+```bash
+npm start
+# In another terminal:
+/tlc:docs screenshots
+```
+
+### Wiki not syncing
+
+1. Enable GitHub Wiki in repo settings
+2. Push to main branch
+3. Check Actions tab for workflow status
+
+### API docs not generating
+
+TypeDoc requires TypeScript. Check:
+```bash
+npm install -D typescript typedoc
+```

package/.claude/commands/tlc/edge-cases.md

@@ -0,0 +1,241 @@
+# /tlc:edge-cases - Generate Edge Case Tests
+
+Analyze code and generate comprehensive edge case tests to improve test coverage.
+
+## What This Does
+
+1. Analyzes target file/function
+2. Identifies parameter types
+3. Generates edge cases by category
+4. Presents selection interface
+5. Writes tests to appropriate file
+
+## Usage
+
+```
+/tlc:edge-cases [file_path] [function_name]
+```
+
+If no arguments, prompts for target.
+
+## Process
+
+### Step 1: Identify Target
+
+If no path provided, ask:
+
+```
+Generate edge cases for:
+
+1) A specific file - enter path
+2) A specific function - enter file:function
+3) Current phase tests - analyze phase plan
+
+Choice:
+```
+
+### Step 2: Parse Target Code
+
+Read and parse the target to extract:
+- Function names
+- Parameter names
+- Parameter types (from TypeScript or inference)
+- Async status
+
+### Step 3: Generate Edge Cases
+
+For each parameter type, generate appropriate edge cases:
+
+**String Parameters:**
+- `null` - null check
+- `undefined` - undefined check
+- `''` - empty string
+- `'   '` - whitespace only
+- Very long string (10,000 chars)
+
+**Number Parameters:**
+- `null` / `undefined`
+- `0` - zero
+- `-1` - negative
+- `Number.MAX_SAFE_INTEGER`
+- `NaN`
+- `Infinity`
+
+**Array Parameters:**
+- `null` / `undefined`
+- `[]` - empty array
+- Single element
+- 1000+ elements
+
+**Security (String Inputs):**
+- SQL injection: `'; DROP TABLE users; --`
+- XSS: `<script>alert('xss')</script>`
+- Path traversal: `../../../etc/passwd`
+- Template injection: `{{7*7}}`
+
+### Step 4: Display Summary
+
+```
+Edge Case Analysis
+══════════════════
+
+Functions: 2
+Edge Cases: 24
+
+By Category:
+  null-check: 4
+  undefined-check: 4
+  empty-string: 2
+  boundary: 8
+  security: 6
+
+Functions:
+  validateEmail(email) - 12 edge cases
+  formatName(first, last) - 12 edge cases
+
+Generate tests? (Y/n)
+```
+
+### Step 5: Selection Interface
+
+```
+Select edge cases to generate:
+
+null-check:
+  [1] handles null email
+  [2] handles null first name
+
+boundary:
+  [3] handles zero-length input
+  [4] handles very long input
+
+security:
+  [5] rejects SQL injection
+  [6] rejects XSS payload
+
+[A] All - Generate all edge cases
+[N] None - Cancel
+
+Selection (comma-separated, e.g., 1,3,5):
+```
+
+### Step 6: Generate Test Code
+
+For each selected edge case, generate test:
+
+```typescript
+it('handles null email', () => {
+  expect(() => validateEmail(null)).toThrow();
+});
+
+it('rejects SQL injection', () => {
+  expect(() => validateEmail("'; DROP TABLE users; --")).toThrow();
+});
+```
+
+### Step 7: Write to Test File
+
+Append to existing test file or create new one:
+
+```
+Generated tests written to:
+  tests/validate.test.ts (8 new tests)
+
+Run tests? (Y/n)
+```
+
+### Step 8: Run Tests (Optional)
+
+If user chooses to run:
+
+```bash
+npm test -- tests/validate.test.ts
+```
+
+Expected: Most edge case tests will FAIL initially (Red phase).
+This is correct - you now write code to make them pass.
+
+## Edge Case Categories
+
+| Category | Description | Example Input |
+|----------|-------------|---------------|
+| null-check | Null value handling | `null` |
+| undefined-check | Undefined handling | `undefined` |
+| empty-string | Empty string handling | `''` |
+| whitespace | Whitespace-only | `'   '` |
+| boundary | Edge values | `0`, `-1`, `MAX_INT` |
+| large-input | Very large values | 10KB string, 1000 items |
+| security | Malicious input | SQL injection, XSS |
+
+## Configuration
+
+In `.tlc.json`:
+
+```json
+{
+  "edgeCases": {
+    "patterns": ["null-check", "boundary", "security"],
+    "maxPerFunction": 20,
+    "includeSecurity": true
+  }
+}
+```
+
+## Example Session
+
+```
+User: /tlc:edge-cases src/auth/validate.ts
+
+Claude: Analyzing src/auth/validate.ts...
+
+Edge Case Analysis
+══════════════════
+
+Functions: 1
+Edge Cases: 14
+
+Function: validateLogin(email: string, password: string)
+
+By Category:
+  null-check: 2
+  undefined-check: 2
+  empty-string: 2
+  whitespace: 2
+  security: 6
+
+Generate all 14 tests? (Y/n)
+
+User: y
+
+Claude: Generating tests...
+
+Created: tests/auth/validate.edge-cases.test.ts
+
+  ✓ handles null email
+  ✓ handles null password
+  ✓ handles undefined email
+  ✓ handles undefined password
+  ✓ handles empty email
+  ✓ handles empty password
+  ✓ handles whitespace email
+  ✓ handles whitespace password
+  ✓ rejects SQL injection in email
+  ✓ rejects SQL injection in password
+  ✓ rejects XSS in email
+  ✓ rejects XSS in password
+  ✓ rejects path traversal
+  ✓ rejects template injection
+
+Run tests now?
+1) Yes - expect failures (Red phase)
+2) No - I'll run later
+
+User: 1
+
+Claude: Running tests...
+
+  14 tests, 12 failing, 2 passing
+
+This is expected! The failing tests show gaps in your error handling.
+Fix them using /tlc:build or implement manually.
+```