claude-dev-env 1.0.0

package/docs/DJANGO_PATTERNS.md

@@ -0,0 +1,80 @@
+# Django Patterns Reference
+
+> Load this file when working with Django models, views, templates, or migrations.
+
+## Model Patterns
+
+**NEVER:**
+
+- **Create separate user models** - Extend Django's User with OneToOneField
+  - Example: `UserProfile(user=OneToOneField(User, related_name='profile'))`
+  - See: https://docs.djangoproject.com/en/5.2/topics/auth/customizing/#extending-the-existing-user-model
+
+- **Use confusing model/field names** - Match semantics & avoid conflicts
+  - "Settings" = user preferences (preferences, settings, display options), "UserProfile" = user metadata
+  - `custom_name` avoids conflict with User.username
+
+- **Break model fields across multiple lines** - Match the style of other fields in the model
+  - Bad: Multi-line ForeignKey definition
+  - Good: `evolves_from = models.ForeignKey('self', on_delete=models.SET_NULL, null=True, blank=True, related_name='evolutions')`
+  - Consistency within the model class matters more than arbitrary line length rules
+
+- **Circumvent Django ORM for database operations** - Always use Django models for DB access
+  - Django ORM handles migrations, relationships, and abstractions under the hood
+  - Bypassing it creates inconsistencies with migrations and model state
+  - For DB operations: Use Django models, views, management commands
+  - For non-DB tools: Use pure Python scripts (file processing, API calls, asset uploads)
+
+## Template Patterns
+
+**NEVER:**
+
+- **Put view-specific template code in base.html** - Only in the template that uses it
+  - Example: `{% if layout %}` in base.html when only home view defines layout
+  - If variable is always present in specific template, no conditional needed
+
+## Production Migrations (Post-Launch ONLY)
+
+**CRITICAL:** After launch, model changes MUST be backwards-compatible.
+
+**Why:** Manual migration takes 2+ minutes. New code runs against old schema during this window.
+
+### Safe vs Unsafe Changes
+
+| Safe | Unsafe |
+|------|--------|
+| Nullable fields | Removing fields |
+| Fields with defaults | Renaming fields |
+| New models | Non-null without defaults |
+| | Type changes |
+
+### Migration Strategy
+
+1. Deploy code working with both schemas
+2. Run migration (2+ min)
+3. Verify production
+4. Deploy cleanup if needed
+
+*During development: manual migration is fine, no big deal.*
+
+## API Contract Changes (Post-Launch)
+
+**CRITICAL:** After launch, API contract changes MUST be backwards-compatible.
+
+**Why:** Users may have old client code cached. Old clients must work with new API.
+
+### Safe vs Unsafe Changes
+
+| Safe | Unsafe |
+|------|--------|
+| New optional fields | Removing fields |
+| New endpoints | Renaming fields |
+| Additive changes | Changing field types |
+| | Removing endpoints |
+
+### API Evolution Strategy
+
+1. Add new fields/endpoints alongside old ones
+2. Deploy frontend that handles both old and new
+3. Deprecate old fields (but keep working)
+4. Remove old fields only after all clients updated

package/docs/REACT_PATTERNS.md

@@ -0,0 +1,185 @@
+# React Patterns Reference
+
+> Load this file when working with React components, state management, hooks, or testing.
+
+## Component Patterns
+
+**NEVER:**
+
+- **Create wrapper components for single use** - Use the component directly
+  - Example: `<ButtonWrapper><Button /></ButtonWrapper>` when Button is only used once
+  - Ask: "Is this wrapper adding any value?"
+
+- **Put page-specific logic in shared components** - Keep shared components pure
+  - Example: `if (pathname === '/home')` inside a shared Header component
+  - Shared components should be context-agnostic
+
+- **Use class components for new code** - Always use functional components with hooks
+  - Exception: Error boundaries still require class components (React limitation)
+
+- **Create HOCs when hooks work** - Prefer custom hooks over HOCs
+  - Example: `withAuth(Component)` -> `useAuth()` hook
+  - HOCs add wrapper layers; hooks are composable
+
+- **Prop drill more than 2 levels** - Use Context or state management
+  - Example: `<Parent data={x}><Child data={x}><GrandChild data={x} /></Child></Parent>`
+  - Solution: Create context or lift state appropriately
+
+## State Management Patterns
+
+**NEVER:**
+
+- **Store derived state** - Calculate on render
+  - Bad: `const [fullName, setFullName] = useState(first + ' ' + last)`
+  - Good: `const fullName = first + ' ' + last`
+
+- **Mutate state directly** - Always create new references
+  - Bad: `items.push(newItem); setItems(items)`
+  - Good: `setItems([...items, newItem])`
+
+- **Use useState for complex state logic** - Use useReducer
+  - When: Multiple sub-values, next state depends on previous, complex update logic
+  - Example: Form with many fields, shopping cart, multi-step wizard
+
+- **Create global state for local concerns** - Colocate state
+  - If only one component uses the state, keep it in that component
+  - Lift state only when siblings need to share
+
+- **Forget to memoize expensive calculations** - Use useMemo
+  - Bad: `const sorted = items.sort((a, b) => ...)` on every render
+  - Good: `const sorted = useMemo(() => items.sort(...), [items])`
+
+## Hooks Patterns
+
+**NEVER:**
+
+- **Call hooks conditionally** - Hooks must be at top level
+  - Bad: `if (condition) { const [x, setX] = useState() }`
+  - Good: Always call hooks, use condition inside
+
+- **Create effects without cleanup** - Return cleanup function when needed
+  - Subscriptions, timers, event listeners MUST be cleaned up
+  - Bad: `useEffect(() => { window.addEventListener(...) }, [])`
+  - Good: `useEffect(() => { window.addEventListener(...); return () => window.removeEventListener(...) }, [])`
+
+- **Use empty dependency arrays incorrectly** - Include all dependencies
+  - Bad: `useEffect(() => { fetchData(userId) }, [])` (missing userId)
+  - Good: `useEffect(() => { fetchData(userId) }, [userId])`
+  - Use ESLint exhaustive-deps rule
+
+- **Create new functions in render without useCallback** - Memoize callbacks passed to children
+  - Bad: `<Child onClick={() => handleClick(id)} />`
+  - Good: `const handleChildClick = useCallback(() => handleClick(id), [id])`
+
+- **Overuse useMemo/useCallback** - Only optimize when needed
+  - Memoization has cost; don't wrap everything
+  - Profile first, then optimize specific bottlenecks
+
+## Component Organization
+
+**File structure:**
+```
+components/
+  ComponentName/
+    ComponentName.tsx      # Component logic
+    ComponentName.test.tsx # Tests (colocated)
+    index.ts               # Public export
+```
+
+**NEVER:**
+
+- **Mix business logic with UI** - Separate concerns
+  - Custom hooks for business logic: `useTaskManager()`
+  - Components for UI: `<TaskList tasks={tasks} />`
+
+- **Create god components** - Split into focused components
+  - If component > 200 lines, likely doing too much
+  - Extract sub-components or custom hooks
+
+- **Export internal components** - Only export what's needed
+  - Internal helpers stay private to the component folder
+  - Only `index.ts` defines the public API
+
+## Code Standards
+
+- **Complete type annotations** - All props, state, and return types defined
+- **No `any` types** - Use generics, union types, or `unknown` with type guards
+- **No `@ts-ignore` or `@ts-expect-error`** without clear justification
+- **Functional components only** - No class components (except error boundaries)
+- **Custom hooks for logic** - Separate business logic from UI
+- **Props interfaces** - Define explicit Props type for every component
+- **Immutable updates** - Never mutate state or props
+- **Small components** - Target 50-100 lines, max 200 lines
+- **Max 2 nesting levels** - Extract sub-components
+- **No inline styles** - Use CSS modules, styled-components, or Tailwind
+
+## Testing Patterns
+
+- **Use React Testing Library** - Not Enzyme
+- **Query by accessibility** - Role, label, text (not test-id as first choice)
+- **Test user flows** - Render, interact, assert on visible changes
+- **Mock API boundaries** - Not internal functions
+- **Colocate tests** - `Component.test.tsx` next to `Component.tsx`
+
+**Testing anti-patterns:**
+
+- **Snapshot test everything** - Only for stable, visual components
+- **Mock too much** - Prefer integration tests
+- **Test implementation details** - Test what user experiences
+- **Forget async handling** - Use waitFor, findBy queries
+
+## Example: God Component Refactoring
+
+**Bad:**
+```tsx
+function TaskDashboard() {
+  const [tasks, setTasks] = useState([]);
+  const [filter, setFilter] = useState('all');
+  const [sortBy, setSortBy] = useState('date');
+  // ... 200 more lines of logic
+  return (
+    <div>{/* 150 lines of JSX */}</div>
+  );
+}
+```
+
+**Good:**
+```tsx
+function TaskDashboard() {
+  const { tasks, filter, sortBy, actions } = useTaskManager();
+  return (
+    <div>
+      <TaskFilters filter={filter} onFilterChange={actions.setFilter} />
+      <TaskList tasks={tasks} sortBy={sortBy} />
+    </div>
+  );
+}
+
+function useTaskManager() {
+  const [tasks, setTasks] = useState<Task[]>([]);
+  const [filter, setFilter] = useState<Filter>('all');
+  // ... focused logic
+  return { tasks, filter, sortBy, actions };
+}
+```
+
+## Example: Derived State
+
+**Bad:**
+```tsx
+const [items, setItems] = useState<Item[]>([]);
+const [filteredItems, setFilteredItems] = useState<Item[]>([]);
+
+useEffect(() => {
+  setFilteredItems(items.filter(i => i.active));
+}, [items]);
+```
+
+**Good:**
+```tsx
+const [items, setItems] = useState<Item[]>([]);
+const filteredItems = useMemo(
+  () => items.filter(i => i.active),
+  [items]
+);
+```

package/docs/TEST_QUALITY.md

@@ -0,0 +1,104 @@
+# Test Quality Reference
+
+> Load this file when writing tests, reviewing test code, or setting up test infrastructure.
+
+## Test Infrastructure Anti-Patterns
+
+**CRITICAL: Test helpers get over-engineered MORE than any other code.**
+
+**ALWAYS:**
+- Single file
+- Simple functions
+- Minimal abstractions
+- Pragmatic approach
+
+**NEVER:**
+- Multi-file packages
+- Cache classes
+- Abstractions "for future"
+- Rigid constraints
+
+**Pre-check (MANDATORY):**
+- [ ] ONE file?
+- [ ] Functions not classes?
+- [ ] Solving problem not building infrastructure?
+- [ ] Junior-dev-understandable?
+
+## Delete Useless Tests
+
+**Tests must add value.** Delete these types of tests:
+
+### NEVER test:
+
+**Function existence** - "Testing that the function exists doesn't add value. If the function doesn't exist, the code will not run."
+- Bad: `test_public_api_exports_download_function()` only verified `callable(func)`
+- Action: DELETE
+
+**Constant values** - "It's silly to test that constant values have not changed."
+- Bad: `assert CACHE_DIR == "cache"`
+- Action: DELETE
+
+**Duplicate coverage** - "Isn't this test case the same as test_X?"
+- Action: DELETE redundant tests
+
+## Test Dependencies MUST FAIL
+
+"The tests should fail if they can't run. Missing system dependencies should make the test fail."
+
+- **NEVER** use `@skip_if_missing_dependency` or similar skip decorators
+- Tests FAIL with clear error -> forces installation
+
+## Core Testing Principles
+
+- **Behavior-driven** - Verify expected behavior, not implementation
+- **Test through public API** - Never examine internals
+- **100% coverage via business behavior** - Not implementation coverage
+- **No 1:1 mapping** - Test files test behavior, not individual implementation files
+- **Tests document behavior** - Tests are the spec
+
+## React Testing Patterns
+
+### ALWAYS:
+
+**Test behavior, not implementation** - What user sees/does, not internal state
+- Bad: `expect(component.state.isOpen).toBe(true)`
+- Good: `expect(screen.getByRole('dialog')).toBeVisible()`
+
+**Use Testing Library queries correctly** - Priority order:
+1. `getByRole` (best)
+2. `getByLabelText`
+3. `getByText`
+4. `getByTestId` (last resort)
+
+- Bad: `getByTestId('submit-button')` as first choice
+- Good: `getByRole('button', { name: /submit/i })`
+
+**Test user interactions**
+- Use `userEvent` over `fireEvent` (more realistic)
+- `await userEvent.click(button)` then assert result
+
+### NEVER:
+
+**Snapshot test everything** - Only for stable, visual components
+- Snapshots break on any change, creating noise
+- Reserve for design system components, icons
+
+**Mock too much** - Prefer integration tests
+- Bad: Mock every hook and function
+- Good: Render with real hooks, mock only API calls
+
+**Test implementation details** - Test what user experiences
+- Bad: Assert on state values, hook return values
+- Good: Assert on rendered output, user-visible behavior
+
+**Forget async handling** - Use waitFor, findBy queries
+- Bad: Expect immediately after async action
+- Good: `await waitFor(() => expect(...))` or `await screen.findByText(...)`
+
+## Test File Organization
+
+- **Use React Testing Library** - Not Enzyme
+- **Query by accessibility** - Role, label, text (not test-id as first choice)
+- **Test user flows** - Render, interact, assert on visible changes
+- **Mock API boundaries** - Not internal functions
+- **Colocate tests** - `Component.test.tsx` next to `Component.tsx`

package/hooks/advisory/migration-safety-advisor.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Advisory hook: warn when Django migrations contain unsafe operations."""
+
+import json
+import re
+import sys
+
+MIGRATION_PATH_PATTERN = re.compile(r"[/\\]migrations[/\\]\d{4}_\w+\.py$")
+UNSAFE_OPERATIONS = ["RemoveField", "RenameField", "DeleteModel", "RenameModel"]
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_input = hook_input.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if not MIGRATION_PATH_PATTERN.search(file_path):
+        sys.exit(0)
+
+    content = tool_input.get("content", "") or tool_input.get("new_string", "")
+    found_unsafe = [op for op in UNSAFE_OPERATIONS if op in content]
+
+    if found_unsafe:
+        operations = ", ".join(found_unsafe)
+        print(
+            json.dumps(
+                {
+                    "hookSpecificOutput": {
+                        "hookEventName": "PreToolUse",
+                        "permissionDecision": "ask",
+                        "permissionDecisionReason": (
+                            f"MIGRATION SAFETY: Contains {operations}. "
+                            "Post-launch, model changes MUST be backwards-compatible. "
+                            "Verify this won't break running instances during deployment."
+                        ),
+                    }
+                }
+            )
+        )
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/advisory/refactor-guard.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""
+Refactor guard - blocks edits that rename/restructure existing code not in the git diff.
+
+Detects when an Edit tool call is modifying existing code (renaming variables,
+functions, restructuring) rather than writing new code or replacing wholesale.
+
+Only fires for Edit operations (not Write, which creates/replaces entire files).
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+REFACTOR_BYPASS_TOKEN_PATH = Path.home() / ".claude" / ".refactor-bypass-token"
+
+
+def get_git_diff_added_lines(file_path: str) -> set[str]:
+    """Get the set of added lines (stripped) from git diff for a file."""
+    added_lines: set[str] = set()
+    try:
+        result = subprocess.run(
+            ["git", "diff", "HEAD", "--", file_path],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        for line in result.stdout.split("\n"):
+            if line.startswith("+") and not line.startswith("+++"):
+                added_lines.add(line[1:].strip())
+
+        staged_result = subprocess.run(
+            ["git", "diff", "--staged", "--", file_path],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        for line in staged_result.stdout.split("\n"):
+            if line.startswith("+") and not line.startswith("+++"):
+                added_lines.add(line[1:].strip())
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return set()
+    return added_lines
+
+
+def is_new_file(file_path: str) -> bool:
+    """Check if file is untracked (entirely new)."""
+    try:
+        result = subprocess.run(
+            ["git", "ls-files", "--others", "--exclude-standard", "--", file_path],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        return bool(result.stdout.strip())
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return False
+
+
+def is_hook_infrastructure(file_path: str) -> bool:
+    """Check if file is a Claude Code hook."""
+    path_lower = file_path.lower().replace("\\", "/")
+    return "/.claude/" in path_lower
+
+
+def extract_identifiers(code: str) -> set[str]:
+    """Extract meaningful identifiers (variable/function/class names) from code."""
+    identifier_pattern = re.compile(r'\b([a-zA-Z_][a-zA-Z0-9_]{2,})\b')
+    identifiers = set(identifier_pattern.findall(code))
+    python_keywords = {
+        "def", "class", "return", "import", "from", "if", "elif", "else",
+        "for", "while", "try", "except", "finally", "with", "as", "yield",
+        "raise", "pass", "break", "continue", "and", "or", "not", "in",
+        "is", "lambda", "None", "True", "False", "self", "cls", "async",
+        "await", "global", "nonlocal", "assert", "del", "print", "len",
+        "range", "list", "dict", "set", "str", "int", "float", "bool",
+        "type", "isinstance", "hasattr", "getattr", "setattr", "super",
+        "property", "staticmethod", "classmethod", "abstractmethod",
+        "Optional", "Union", "List", "Dict", "Set", "Tuple", "Any",
+    }
+    return identifiers - python_keywords
+
+
+def is_refactor_edit(old_string: str, new_string: str) -> Optional[str]:
+    """Detect if an edit is a rename/refactor rather than a functional change.
+
+    Returns a description of the refactor if detected, None otherwise.
+    """
+    old_lines = [line.strip() for line in old_string.strip().split("\n") if line.strip()]
+    new_lines = [line.strip() for line in new_string.strip().split("\n") if line.strip()]
+
+    if not old_lines or not new_lines:
+        return None
+
+    if abs(len(old_lines) - len(new_lines)) > max(len(old_lines) // 2, 3):
+        return None
+
+    old_identifiers = extract_identifiers(old_string)
+    new_identifiers = extract_identifiers(new_string)
+
+    removed_identifiers = old_identifiers - new_identifiers
+    added_identifiers = new_identifiers - old_identifiers
+
+    if not removed_identifiers or not added_identifiers:
+        return None
+
+    old_no_ids = old_string
+    new_no_ids = new_string
+    for identifier in old_identifiers | new_identifiers:
+        old_no_ids = old_no_ids.replace(identifier, "ID")
+        new_no_ids = new_no_ids.replace(identifier, "ID")
+
+    old_structure = re.sub(r'\s+', ' ', old_no_ids.strip())
+    new_structure = re.sub(r'\s+', ' ', new_no_ids.strip())
+
+    if old_structure == new_structure:
+        renamed = []
+        for old_id in sorted(removed_identifiers):
+            for new_id in sorted(added_identifiers):
+                if old_id.lower().replace("_", "") == new_id.lower().replace("_", ""):
+                    renamed.append(f"{old_id} -> {new_id}")
+                    break
+                old_words = set(re.findall(r'[a-z]+|[A-Z][a-z]*', old_id))
+                new_words = set(re.findall(r'[a-z]+|[A-Z][a-z]*', new_id))
+                if old_words and new_words and len(old_words & new_words) >= len(old_words) * 0.5:
+                    renamed.append(f"{old_id} -> {new_id}")
+                    break
+
+        if renamed:
+            return f"Renaming detected: {', '.join(renamed[:3])}"
+
+        if len(removed_identifiers) >= 2 and len(added_identifiers) >= 2:
+            return f"Multiple identifiers changed with same structure: removed {sorted(removed_identifiers)[:3]}, added {sorted(added_identifiers)[:3]}"
+
+    return None
+
+
+def is_bypass_approved() -> bool:
+    """Check if user explicitly approved a refactor bypass via one-time token file.
+
+    The token file is deleted after a single use, so each refactor
+    requires fresh explicit approval from the user.
+    """
+    if REFACTOR_BYPASS_TOKEN_PATH.exists():
+        REFACTOR_BYPASS_TOKEN_PATH.unlink()
+        return True
+    return False
+
+
+def main() -> None:
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    if tool_name != "Edit":
+        sys.exit(0)
+
+    if is_bypass_approved():
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+    old_string = tool_input.get("old_string", "")
+    new_string = tool_input.get("new_string", "")
+
+    if not file_path or not old_string or not new_string:
+        sys.exit(0)
+
+    if is_hook_infrastructure(file_path):
+        sys.exit(0)
+
+    if is_new_file(file_path):
+        sys.exit(0)
+
+    refactor_description = is_refactor_edit(old_string, new_string)
+    if not refactor_description:
+        sys.exit(0)
+
+    diff_added_lines = get_git_diff_added_lines(file_path)
+
+    old_lines_stripped = {line.strip() for line in old_string.split("\n") if line.strip()}
+    old_lines_in_diff = old_lines_stripped & diff_added_lines
+
+    if old_lines_in_diff and len(old_lines_in_diff) >= len(old_lines_stripped) * 0.5:
+        sys.exit(0)
+
+    result = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+            "additionalContext": f"[HOOK ADVISORY] Refactor guard — {refactor_description} in {file_path}. Only modify lines already changed in the current git diff. Ask the user for explicit approval first. If the user approves, create the bypass token then retry.",
+        }
+    }
+    print(json.dumps(result))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()