@mindfoldhq/trellis 0.5.0-beta.8 → 0.5.0-beta.9

package/dist/templates/markdown/spec/guides/code-reuse-thinking-guide.md

@@ -1,118 +0,0 @@
-# Code Reuse Thinking Guide
-
-> **Purpose**: Stop and think before creating new code - does it already exist?
-
----
-
-## The Problem
-
-**Duplicated code is the #1 source of inconsistency bugs.**
-
-When you copy-paste or rewrite existing logic:
-- Bug fixes don't propagate
-- Behavior diverges over time
-- Codebase becomes harder to understand
-
----
-
-## Before Writing New Code
-
-### Step 1: Search First
-
-```bash
-# Search for similar function names
-grep -r "functionName" .
-
-# Search for similar logic
-grep -r "keyword" .
-```
-
-### Step 2: Ask These Questions
-
-| Question | If Yes... |
-|----------|-----------|
-| Does a similar function exist? | Use or extend it |
-| Is this pattern used elsewhere? | Follow the existing pattern |
-| Could this be a shared utility? | Create it in the right place |
-| Am I copying code from another file? | **STOP** - extract to shared |
-
----
-
-## Common Duplication Patterns
-
-### Pattern 1: Copy-Paste Functions
-
-**Bad**: Copying a validation function to another file
-
-**Good**: Extract to shared utilities, import where needed
-
-### Pattern 2: Similar Components
-
-**Bad**: Creating a new component that's 80% similar to existing
-
-**Good**: Extend existing component with props/variants
-
-### Pattern 3: Repeated Constants
-
-**Bad**: Defining the same constant in multiple files
-
-**Good**: Single source of truth, import everywhere
-
----
-
-## When to Abstract
-
-**Abstract when**:
-- Same code appears 3+ times
-- Logic is complex enough to have bugs
-- Multiple people might need this
-
-**Don't abstract when**:
-- Only used once
-- Trivial one-liner
-- Abstraction would be more complex than duplication
-
----
-
-## After Batch Modifications
-
-When you've made similar changes to multiple files:
-
-1. **Review**: Did you catch all instances?
-2. **Search**: Run grep to find any missed
-3. **Consider**: Should this be abstracted?
-
----
-
-## Checklist Before Commit
-
-- [ ] Searched for existing similar code
-- [ ] No copy-pasted logic that should be shared
-- [ ] Constants defined in one place
-- [ ] Similar patterns follow same structure
-
----
-
-## Template File Registration (Trellis-specific)
-
-When adding new files to `src/templates/trellis/scripts/`:
-
-**CRITICAL**: New script files must be registered in THREE places:
-
-1. **`src/templates/trellis/index.ts`**:
-   - Add `export const xxxScript = readTemplate("scripts/path/file.py");`
-   - Add to `getAllScripts()` Map
-
-2. **`src/commands/update.ts`**:
-   - Add to import statement
-   - Add to `collectTemplateFiles()` Map
-
-**Why this matters**: Without registration, `trellis update` won't sync the file to user projects. Bug fixes and features won't propagate.
-
-### Quick Checklist for New Scripts
-
-```bash
-# After adding a new .py file, verify:
-grep -l "newFileName" src/templates/trellis/index.ts  # Should match
-grep -l "newFileName" src/commands/update.ts          # Should match
-```

package/dist/templates/markdown/spec/guides/cross-platform-thinking-guide.md

@@ -1,394 +0,0 @@
-# Cross-Platform Thinking Guide
-
-> **Purpose**: Catch platform-specific assumptions before they become bugs.
-
----
-
-## Why This Matters
-
-**Most cross-platform bugs come from implicit assumptions**:
-
-- Assumed shebang works → breaks on Windows
-- Assumed `/` path separator → breaks on Windows
-- Assumed `\n` line endings → inconsistent behavior
-- Assumed command availability → `grep` vs `findstr`
-
----
-
-## Platform Differences Checklist
-
-### 1. Script Execution
-
-| Assumption | macOS/Linux | Windows |
-|------------|-------------|---------|
-| Shebang (`#!/usr/bin/env python3`) | ✅ Works | ❌ Ignored |
-| Direct execution (`./script.py`) | ✅ Works | ❌ Fails |
-| `python3` command | ✅ Always available | ⚠️ May need `python` |
-| `python` command | ⚠️ May be Python 2 | ✅ Usually Python 3 |
-
-**Rule 1**: Always use explicit `python3` in documentation, help text, and error messages.
-
-```python
-# BAD - Assumes shebang works
-print("Usage: ./script.py <args>")
-print("Run: script.py <args>")
-
-# GOOD - Explicit interpreter
-print("Usage: python3 script.py <args>")
-print("Run: python3 ./script.py <args>")
-```
-
-**Rule 2**: When calling Python from TypeScript/Node.js, detect the available command:
-
-```typescript
-function getPythonCommand(): string {
-  try {
-    execSync("python3 --version", { stdio: "pipe" });
-    return "python3";
-  } catch {
-    try {
-      execSync("python --version", { stdio: "pipe" });
-      return "python";
-    } catch {
-      return "python3"; // Default, will fail with clear error
-    }
-  }
-}
-```
-
-**Rule 3**: When calling Python from Python, use `sys.executable`:
-
-```python
-import sys
-import subprocess
-
-# BAD - Hardcoded command
-subprocess.run(["python3", "other_script.py"])
-
-# GOOD - Use current interpreter
-subprocess.run([sys.executable, "other_script.py"])
-```
-
-### 2. Path Handling
-
-| Assumption | macOS/Linux | Windows |
-|------------|-------------|---------|
-| `/` separator | ✅ Works | ⚠️ Sometimes works |
-| `\` separator | ❌ Escape char | ✅ Native |
-| `pathlib.Path` | ✅ Works | ✅ Works |
-
-**Rule**: Use `pathlib.Path` for all path operations.
-
-```python
-# BAD - String concatenation
-path = base + "/" + filename
-
-# GOOD - pathlib
-from pathlib import Path
-path = Path(base) / filename
-```
-
-### 3. Line Endings
-
-| Format | macOS/Linux | Windows | Git |
-|--------|-------------|---------|-----|
-| `\n` (LF) | ✅ Native | ⚠️ Some tools | ✅ Normalized |
-| `\r\n` (CRLF) | ⚠️ Extra char | ✅ Native | Converted |
-
-**Rule**: Use `.gitattributes` to enforce consistent line endings.
-
-```gitattributes
-* text=auto eol=lf
-*.sh text eol=lf
-*.py text eol=lf
-```
-
-### 4. Environment Variables
-
-| Variable | macOS/Linux | Windows |
-|----------|-------------|---------|
-| `HOME` | ✅ Set | ❌ Use `USERPROFILE` |
-| `PATH` separator | `:` | `;` |
-| Case sensitivity | ✅ Case-sensitive | ❌ Case-insensitive |
-
-**Rule**: Use `pathlib.Path.home()` instead of environment variables.
-
-```python
-# BAD
-home = os.environ.get("HOME")
-
-# GOOD
-home = Path.home()
-```
-
-### 5. Command Availability
-
-| Command | macOS/Linux | Windows |
-|---------|-------------|---------|
-| `grep` | ✅ Built-in | ❌ Not available |
-| `find` | ✅ Built-in | ⚠️ Different syntax |
-| `cat` | ✅ Built-in | ❌ Use `type` |
-| `tail -f` | ✅ Built-in | ❌ Not available |
-
-**Rule**: Use Python standard library instead of shell commands when possible.
-
-```python
-# BAD - tail -f is not available on Windows
-subprocess.run(["tail", "-f", log_file])
-
-# GOOD - Cross-platform implementation
-def tail_follow(file_path: Path) -> None:
-    """Follow a file like 'tail -f', cross-platform compatible."""
-    with open(file_path, "r", encoding="utf-8", errors="replace") as f:
-        f.seek(0, 2)  # Go to end
-        while True:
-            line = f.readline()
-            if line:
-                print(line, end="", flush=True)
-            else:
-                time.sleep(0.1)
-```
-
-### 6. File Encoding
-
-| Default Encoding | macOS/Linux | Windows |
-|------------------|-------------|---------|
-| Terminal | UTF-8 | Often CP1252 or GBK |
-| File I/O | UTF-8 | System locale |
-| Git output | UTF-8 | May vary |
-
-**Rule**: Always explicitly specify `encoding="utf-8"` and use `errors="replace"`.
-
-> **Checklist**: When writing scripts that print non-ASCII, did you configure stdout encoding?
-> See `backend/script-conventions.md` for the specific pattern.
-
-```python
-# BAD - Relies on system default
-with open(file, "r") as f:
-    content = f.read()
-
-result = subprocess.run(cmd, capture_output=True, text=True)
-
-# GOOD - Explicit encoding with error handling
-with open(file, "r", encoding="utf-8", errors="replace") as f:
-    content = f.read()
-
-result = subprocess.run(
-    cmd,
-    capture_output=True,
-    text=True,
-    encoding="utf-8",
-    errors="replace"
-)
-```
-
-**Git commands**: Force UTF-8 output encoding:
-
-```python
-# Force git to output UTF-8
-git_args = ["git", "-c", "i18n.logOutputEncoding=UTF-8"] + args
-result = subprocess.run(
-    git_args,
-    capture_output=True,
-    text=True,
-    encoding="utf-8",
-    errors="replace"
-)
-```
-
----
-
-## Change Propagation Checklist
-
-When making platform-related changes, check **all these locations**:
-
-### Documentation & Help Text
-- [ ] Docstrings at top of Python files
-- [ ] `--help` output / argparse descriptions
-- [ ] Usage examples in README
-- [ ] Error messages that suggest commands
-- [ ] Markdown documentation (`.md` files)
-
-### Code Locations
-- [ ] `src/templates/` - Template files for new projects
-- [ ] `.trellis/scripts/` - Project's own scripts (if self-hosting)
-- [ ] `dist/` - Built output (rebuild after changes)
-
-### Search Pattern
-```bash
-# Find all places that might need updating
-grep -r "python [a-z]" --include="*.py" --include="*.md"
-grep -r "\./" --include="*.py" --include="*.md" | grep -v python3
-```
-
----
-
-## Pre-Commit Checklist
-
-Before committing cross-platform code:
-
-- [ ] All Python invocations use `python3` explicitly (docs) or `sys.executable` (code)
-- [ ] All paths use `pathlib.Path`
-- [ ] No hardcoded path separators (`/` or `\`)
-- [ ] No platform-specific commands without fallbacks (e.g., `tail -f`)
-- [ ] All file I/O specifies `encoding="utf-8"` and `errors="replace"`
-- [ ] All subprocess calls specify `encoding="utf-8"` and `errors="replace"`
-- [ ] Git commands use `-c i18n.logOutputEncoding=UTF-8`
-- [ ] External tool API formats verified from documentation
-- [ ] Documentation matches code behavior
-- [ ] Ran search to find all affected locations
-
-### 7. External Tool API Contracts
-
-When integrating with external tools (Claude Code, Cursor, etc.), their API contracts are **implicit assumptions**.
-
-**Rule**: Verify API formats from official documentation, don't guess.
-
-```python
-# BAD - Guessed format
-output = {"continue": True, "message": "..."}
-
-# GOOD - Verified format from documentation
-output = {
-    "hookSpecificOutput": {
-        "hookEventName": "SessionStart",
-        "additionalContext": "..."
-    }
-}
-```
-
-> **Warning**: Different hook types may have different output formats.
-> Always check the specific documentation for each hook event.
-
----
-
-## JSON/External Data Defensive Checks
-
-When parsing JSON or external data, TypeScript types are **compile-time only**. Runtime data may not match.
-
-**Rule**: Always add defensive checks for required fields before using them.
-
-```typescript
-// BAD - Trusts TypeScript type definition
-interface MigrationItem {
-  from: string;  // TypeScript says required
-  to?: string;
-}
-
-function process(item: MigrationItem) {
-  const path = item.from;  // Runtime: could be undefined!
-}
-
-// GOOD - Defensive check before use
-function process(item: MigrationItem) {
-  if (!item.from) return;  // Skip invalid data
-  const path = item.from;  // Now guaranteed
-}
-```
-
-**When to apply**:
-- Parsing JSON files (manifests, configs)
-- API responses
-- User input
-- Any data from external sources
-
-**Pattern**: Check existence → then use
-
-```typescript
-// Filter pattern - skip invalid items
-const validItems = items.filter(item => item.from && item.to);
-
-// Early return pattern - bail on invalid
-if (!data.requiredField) {
-  console.warn("Missing required field");
-  return defaultValue;
-}
-```
-
----
-
-## Common Mistakes
-
-### 1. "It works on my Mac"
-
-```python
-# Developer's Mac
-subprocess.run(["./script.py"])  # Works!
-
-# User's Windows
-subprocess.run(["./script.py"])  # FileNotFoundError
-```
-
-### 2. "The shebang should handle it"
-
-```python
-#!/usr/bin/env python3
-# This line is IGNORED on Windows
-```
-
-### 3. "I updated the template"
-
-```
-src/templates/script.py  ← Updated
-.trellis/scripts/script.py  ← Forgot to sync!
-```
-
-### 4. "Python 3 is always python3"
-
-```bash
-# Developer's Mac/Linux
-python3 script.py  # Works!
-
-# User's Windows (Python from python.org)
-python3 script.py  # 'python3' is not recognized
-python script.py   # Works!
-```
-
-### 5. "UTF-8 is the default everywhere"
-
-```python
-# Developer's Mac (UTF-8 default)
-subprocess.run(cmd, capture_output=True, text=True)  # Works!
-
-# User's Windows (GBK/CP1252 default)
-subprocess.run(cmd, capture_output=True, text=True)  # Garbled Chinese/Unicode
-```
-
-> **Note**: stdout encoding is also affected. See `backend/script-conventions.md` for the fix.
-
----
-
-## Recovery: When You Find a Platform Bug
-
-1. **Fix the immediate issue**
-2. **Search for similar patterns** (grep the codebase)
-3. **Update this guide** with the new pattern
-4. **Add to pre-commit checklist** if recurring
-
----
-
-**Core Principle**: If it's not explicit, it's an assumption. And assumptions break.
-
----
-
-## Release Checklist: Versioned Files
-
-When releasing a new version, ensure **all versioned files** are created/updated:
-
-- [ ] `src/migrations/manifests/{version}.json` - Migration manifest exists
-- [ ] Manifest has correct version, description, changelog
-- [ ] `pnpm build` copies manifests to `dist/`
-- [ ] Test upgrade path from older versions (not just adjacent)
-
-**Why this matters**: Missing manifests cause "path undefined" errors when users upgrade from older versions.
-
-```bash
-# Verify all expected manifests exist
-ls src/migrations/manifests/
-
-# Test upgrade path
-node -e "
-const { getMigrationsForVersion } = require('./dist/migrations/index.js');
-console.log('From 0.2.12:', getMigrationsForVersion('0.2.12', 'CURRENT').length);
-"
-```