safeword 0.2.3 → 0.2.4

package/.safeword/planning/versioned-distribution.md

@@ -0,0 +1,740 @@
+# Versioned Distribution Plan (Project-Local SAFEWORD)
+
+**Goal:** Make the setup scripts distributable with proper versioning, zero global dependencies, and minimal bloat using project-local SAFEWORD.
+
+**Status:** Planning
+**Created:** 2025-11-22
+
+---
+
+## Problem Statement
+
+**Current state (to eliminate):**
+
+- Quality review hooks referenced from a global location
+- Projects reference absolute paths
+- External users rely on a global folder
+- No versioning system
+- Linting setup works (self-contained via heredocs), quality review doesn't
+
+**Requirements:**
+
+1. External users can download and use without ANY global .agents folder
+2. All projects are 100% self-contained (no global dependencies, no shared folders)
+3. Setup scripts contain ALL code inline (heredocs only, no external file references)
+4. Versioned releases using git tags
+5. Each project knows what version generated its files
+6. Simple upgrade path (re-run setup script)
+7. Zero bloat (no CLI, no lock files, no package managers, no global folders)
+
+---
+
+## Architecture
+
+### Development (You)
+
+```
+framework/scripts/                   # Project-local setup scripts
+├── setup-linting.sh                 # ✅ Self-contained (all code inline via heredocs)
+├── setup-quality.sh                 # ✅ Self-contained (all code inline)
+└── ../guides/                       # Reference docs copied into projects
+```
+
+**Key principle:** Setup scripts ARE the source of truth. They contain all code inline using heredocs. No external file dependencies.
+
+### Distribution (External Users)
+
+```bash
+# Users run ONE command per feature (project-local only, no global folder needed):
+curl https://raw.githubusercontent.com/YOU/agents/v1.0.0/setup-linting.sh | bash -s -- --biome
+curl https://raw.githubusercontent.com/YOU/safeword/v1.0.0/framework/scripts/setup-quality.sh | bash
+
+# Creates in their project (100% self-contained):
+project/.claude/
+├── hooks/
+│   ├── auto-lint.sh                 # Generated from heredoc in setup-linting.sh
+│   ├── run-linters.sh               # Generated from heredoc in setup-linting.sh
+│   ├── auto-quality-review.sh       # Generated from heredoc in setup-quality.sh
+│   └── run-quality-review.sh        # Generated from heredoc in setup-quality.sh
+├── commands/
+│   ├── lint.md                      # Generated from heredoc in setup-linting.sh
+│   └── quality-review.md            # Generated from heredoc in setup-quality.sh
+└── settings.json                    # Merged by both scripts
+```
+
+**Key principles:**
+
+- No global folders
+- Everything generated from inline heredocs in setup scripts
+- Setup scripts are self-contained (can be distributed as single files)
+- Zero external dependencies
+
+---
+
+## Implementation Tasks
+
+### Task 1: Create `setup-quality.sh`
+
+**Status:** Not started
+**Analogous to:** `setup-linting.sh`
+
+**What it does:**
+
+1. Checks for dependencies (jq, bash)
+2. Creates `.claude/hooks/` directory
+3. **Generates** `auto-quality-review.sh` from inline heredoc (no external file)
+4. **Generates** `run-quality-review.sh` from inline heredoc (no external file)
+5. Creates `.claude/commands/quality-review.md` from inline heredoc
+6. Updates `.claude/settings.json` (adds Stop hook with LOCAL path)
+7. Adds version comment to all generated files
+
+**Source of code:**
+
+- Inline heredocs embedded directly inside `setup-quality.sh`
+- Add `chmod +x` for generated hooks
+- Result: setup-quality.sh is 100% self-contained
+
+**Script structure:**
+
+```bash
+#!/bin/bash
+# setup-quality.sh
+
+VERSION="v1.0.0"  # Updated by git tag
+PROJECT_ROOT="$(pwd)"
+
+echo "================================="
+echo "Claude Code Quality Review Setup"
+echo "Version: $VERSION"
+echo "================================="
+
+# Step 1: Check dependencies
+# Step 2: Create directories
+# Step 3: Copy hooks (inline heredoc, not file copy)
+# Step 4: Create slash command
+# Step 5: Update settings.json (merge, don't overwrite)
+# Step 6: Print success message
+```
+
+**Files to generate:**
+
+1. `.claude/hooks/auto-quality-review.sh`
+
+   ```bash
+   #!/bin/bash
+   # Generated by https://github.com/YOU/agents v1.0.0
+   # To update: curl https://raw.../v1.0.0/framework/scripts/setup-quality.sh | bash
+
+   # [inline copy of current auto-quality-review.sh]
+   ```
+
+2. `.claude/hooks/run-quality-review.sh`
+
+   ```bash
+   #!/bin/bash
+   # Generated by https://github.com/YOU/agents v1.0.0
+   # To update: curl https://raw.../v1.0.0/framework/scripts/setup-quality.sh | bash
+
+   # [inline copy of current run-quality-review.sh]
+   ```
+
+3. `.claude/commands/quality-review.md`
+
+   ````markdown
+   Trigger a quality review to double-check your work.
+
+   Execute:
+
+   ```bash
+   bash .claude/hooks/run-quality-review.sh
+   ```
+   ````
+
+   ```
+
+   ```
+
+4. `.claude/settings.json` (merge with existing)
+   ```json
+   {
+     "hooks": {
+       "Stop": [
+         {
+           "hooks": [
+             {
+               "type": "command",
+               "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/auto-quality-review.sh"
+             }
+           ]
+         }
+       ]
+     }
+   }
+   ```
+
+**Critical:**
+
+- Use `$CLAUDE_PROJECT_DIR/.claude/hooks/...` (project-local)
+- All code must be inline via heredocs (no external file references)
+- Script must work without any global folder existing
+
+---
+
+### Task 2: Ensure setup-linting.sh Creates Slash Command
+
+**Status:** Not started
+**Modify:** `framework/scripts/setup-linting.sh`
+
+**Problem:** setup-linting.sh doesn't create `.claude/commands/lint.md` (currently manual)
+
+**Changes:**
+
+1. Add command directory creation
+2. Generate `lint.md` from inline heredoc
+
+**Code to add:**
+
+````bash
+# Add after hooks creation
+mkdir -p .claude/commands
+
+cat > .claude/commands/lint.md << 'EOF'
+Run linting on all project files.
+
+Execute:
+```bash
+bash .claude/hooks/run-linters.sh .
+````
+
+EOF
+
+````
+
+---
+
+### Task 3: Add Version Comments to `setup-linting.sh`
+**Status:** Not started
+**Modify:** `framework/scripts/setup-linting.sh`
+
+**Changes:**
+1. Add VERSION variable at top (hardcoded, updated manually before each release)
+2. Add version comment to all generated files
+
+**Example:**
+```bash
+# At top of setup-linting.sh
+VERSION="v1.0.0"  # UPDATE THIS MANUALLY BEFORE EACH RELEASE
+
+# In heredoc for auto-lint.sh
+cat > .claude/hooks/auto-lint.sh << EOF
+#!/bin/bash
+# Generated by https://github.com/YOU/agents $VERSION
+# To upgrade: curl https://raw.githubusercontent.com/YOU/agents/v1.1.0/coding/setup-linting.sh | bash -s -- --biome
+
+[rest of file]
+EOF
+````
+
+**Important:** VERSION must be manually updated before tagging. Add to release checklist.
+
+**Apply to these files:**
+
+- `.claude/hooks/auto-lint.sh`
+- `.claude/hooks/run-linters.sh`
+- `.claude/commands/lint.md`
+- `eslint.config.mjs` / `biome.jsonc`
+
+---
+
+### Task 4: Handle `settings.json` Merging
+
+**Status:** Not started
+**Problem:** Both `setup-linting.sh` and `setup-quality.sh` write to `.claude/settings.json`
+
+**Current behavior:** setup-linting.sh OVERWRITES entire file (breaks quality review if already installed)
+
+**Solution: Order-independent merging using jq**
+
+- UPDATE setup-linting.sh to use jq merging (not cat overwrite)
+- Implement same pattern in setup-quality.sh
+
+```bash
+# Both scripts use this pattern:
+
+# 1. Create base structure if file doesn't exist
+if [ ! -f .claude/settings.json ]; then
+  echo '{"hooks": {}}' > .claude/settings.json
+fi
+
+# 2. Merge using jq (order-independent)
+# setup-linting.sh adds PostToolUse:
+jq '.hooks.PostToolUse = [{"matcher": "Write|Edit|MultiEdit|NotebookEdit", "hooks": [{"type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/auto-lint.sh", "timeout": 15}]}]' \
+  .claude/settings.json > .claude/settings.json.tmp
+mv .claude/settings.json.tmp .claude/settings.json
+
+# setup-quality.sh adds Stop:
+jq '.hooks.Stop = [{"hooks": [{"type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/auto-quality-review.sh"}]}]' \
+  .claude/settings.json > .claude/settings.json.tmp
+mv .claude/settings.json.tmp .claude/settings.json
+```
+
+**Critical: Make jq REQUIRED**
+
+```bash
+# Check for jq (both scripts)
+if ! command -v jq &> /dev/null; then
+  echo "ERROR: jq is required for settings.json merging."
+  echo "Install it:"
+  echo "  • macOS: brew install jq"
+  echo "  • Ubuntu/Debian: sudo apt-get install jq"
+  echo "  • Other: https://jqlang.github.io/jq/download/"
+  exit 1  # FAIL if missing (not a warning)
+fi
+```
+
+**Benefit:** Scripts can run in ANY order, settings.json always merges correctly
+
+---
+
+### Task 5: Git Tagging and Release Process
+
+**Status:** Not started
+
+**Process:**
+
+1. Make changes in this repo
+2. Test in a project
+3. Commit changes
+4. Tag release with semver
+5. Push tags
+
+**Commands:**
+
+```bash
+cd /Users/alex/projects/safeword
+
+# Make changes
+git add .
+git commit -m "Add biome support to setup-linting.sh"
+
+# Tag release
+git tag v1.0.0 -m "Initial release"
+git tag v1.1.0 -m "Add biome support"
+git tag v1.1.1 -m "Fix quality review bug"
+
+# Push
+git push origin main --tags
+```
+
+**Versioning scheme:**
+
+- `v1.0.0` - Initial release
+- `v1.1.0` - New features (backward compatible)
+- `v1.1.1` - Bug fixes
+- `v2.0.0` - Breaking changes
+
+**Release Checklist:**
+
+```bash
+# 1. Update VERSION in both scripts
+vim framework/scripts/setup-linting.sh  # Change VERSION="v1.1.0"
+vim framework/scripts/setup-quality.sh  # Change VERSION="v1.1.0"
+
+# 2. Test scripts
+cd /tmp/test-project
+bash ./framework/scripts/setup-linting.sh --biome
+bash ./framework/scripts/setup-quality.sh
+# Verify generated files have correct version
+
+# 3. Commit, tag, push
+git commit -am "Release v1.1.0"
+git tag v1.1.0 -m "Add biome support"
+git push origin main --tags
+```
+
+---
+
+### Task 6: Update Existing Projects
+
+**Status:** Not started
+**Projects to update:**
+
+- `~/projects/soulless-monorepo`
+- `~/projects/chat`
+
+**Current state:**
+Both have:
+
+- ✅ `.claude/hooks/auto-lint.sh` (project-local, good)
+- ✅ `.claude/hooks/run-linters.sh` (project-local, good)
+- ❌ `.claude/settings.json` referencing `/Users/alex/.agents/hooks/auto-quality-review.sh` (global, bad)
+
+**Migration steps:**
+
+1. Run `setup-quality.sh` in each project
+2. Verify `.claude/hooks/auto-quality-review.sh` is copied locally
+3. Verify `.claude/settings.json` uses `$CLAUDE_PROJECT_DIR/.claude/hooks/...`
+4. Delete any old global references
+
+---
+
+### Task 7: Delete hooks/ Directory (After Migration)
+
+**Status:** Not started
+**Decision:** Rely only on project-local generated hooks (no global hooks directory)
+
+**Reasoning:**
+
+- ✅ Single source of truth (setup scripts with inline heredocs)
+- ✅ No drift between hooks/\*.sh and heredocs
+- ✅ Cleaner architecture
+- ❌ Slightly less convenient to edit (but syntax highlighting still works in heredocs)
+
+**Steps:**
+
+1. Create setup-quality.sh with inline heredocs (Task 1)
+2. Migrate existing projects to local hooks (Task 6)
+3. Verify no projects reference a global hooks directory
+
+**Alternative:** Keep as deprecated examples
+
+- Mark with README: "DEPRECATED - Use setup scripts instead"
+- Risk: Confuses new users, two sources of truth
+
+**Recommendation:** Delete. Setup scripts are sufficient.
+
+---
+
+### Task 8: Add SessionStart Version Check Hook
+
+**Status:** Not started
+**Modify:** Both `setup-linting.sh` and `setup-quality.sh`
+
+**What it does:**
+
+- Checks for newer version of agents (once per 24 hours)
+- Shows upgrade command if update available
+- Fails silently if offline/network issues
+- Can be disabled by creating `.agents-no-check` file
+
+**Implementation:**
+
+1. **Both setup scripts generate `.claude/hooks/session-start.sh`:**
+
+   ```bash
+   cat > .claude/hooks/session-start.sh << 'EOF'
+   #!/bin/bash
+   # Generated by https://github.com/YOU/agents $VERSION
+   # Session start hook - checks for updates
+
+   # Skip if disabled
+   [ -f .agents-no-check ] && exit 0
+
+   # Extract installed version from generated file
+   INSTALLED_VERSION=$(grep -m1 "# Generated by.*agents v" .claude/hooks/auto-lint.sh 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "")
+
+   # Skip if can't determine version
+   [ -z "$INSTALLED_VERSION" ] && exit 0
+
+   # Use cache to avoid checking too frequently
+   CACHE_FILE=".claude/.version-cache"
+   CACHE_MAX_AGE=86400  # 24 hours
+
+   # Check if cache is fresh
+   if [ -f "$CACHE_FILE" ]; then
+     CACHE_AGE=$(($(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0)))
+     if [ $CACHE_AGE -lt $CACHE_MAX_AGE ]; then
+       LATEST=$(cat "$CACHE_FILE" 2>/dev/null)
+     fi
+   fi
+
+   # If no cached value, check GitHub (with timeout)
+   if [ -z "$LATEST" ]; then
+     LATEST=$(timeout 2 curl -sf https://api.github.com/repos/USER/agents/releases/latest 2>/dev/null | jq -r '.tag_name' 2>/dev/null || echo "")
+
+     # Cache the result (even if empty)
+     echo "$LATEST" > "$CACHE_FILE" 2>/dev/null
+   fi
+
+   # Compare versions and notify
+   if [ -n "$LATEST" ] && [ "$LATEST" != "$INSTALLED_VERSION" ]; then
+     echo "📦 Agents update available: $INSTALLED_VERSION → $LATEST"
+     echo "   Upgrade linting: curl https://raw.githubusercontent.com/YOU/safeword/$LATEST/framework/scripts/setup-linting.sh | bash -s -- --biome"
+     echo "   Upgrade quality: curl https://raw.githubusercontent.com/YOU/safeword/$LATEST/framework/scripts/setup-quality.sh | bash"
+     echo ""
+   fi
+   EOF
+
+   chmod +x .claude/hooks/session-start.sh
+   ```
+
+2. **Both setup scripts add SessionStart to settings.json:**
+   ```bash
+   # Use jq to add SessionStart hook
+   jq '.hooks.SessionStart = [{"hooks": [{"type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"}]}]' \
+     .claude/settings.json > .claude/settings.json.tmp
+   mv .claude/settings.json.tmp .claude/settings.json
+   ```
+
+**Features:**
+
+- ✅ Cached (24hr) - won't spam API
+- ✅ Fast (2s timeout) - won't hang
+- ✅ Fails silently - works offline
+- ✅ Helpful - shows exact upgrade commands
+- ✅ Opt-out - create `.agents-no-check` to disable
+
+**Edge cases handled:**
+
+- Offline → skips silently
+- GitHub down → uses cached value
+- Rate limited → uses cached value
+- Can't parse version → skips silently
+
+---
+
+### Task 9: Documentation
+
+**Status:** Not started
+
+**Create/Update:**
+
+1. **README.md** (project-local)
+
+   ````markdown
+   # Claude Code Agents
+
+   Automated linting and quality review for Claude Code projects.
+
+   ## Quick Start
+
+   ### Linting Setup
+
+   ```bash
+   curl https://raw.githubusercontent.com/YOU/safeword/v1.0.0/framework/scripts/setup-linting.sh | bash -s -- --biome
+   ```
+   ````
+
+   ### Quality Review Setup
+
+   ```bash
+   curl https://raw.githubusercontent.com/YOU/safeword/v1.0.0/framework/scripts/setup-quality.sh | bash
+   ```
+
+   ## Versioning
+
+   Use git tags to pin versions:
+   - Latest: Replace `v1.0.0` with `main` in URLs (rolling release)
+   - Stable: Use specific tag like `v1.0.0`
+
+   ## Upgrading
+
+   Re-run setup scripts with new version:
+
+   ```bash
+   curl https://raw.githubusercontent.com/YOU/safeword/v1.1.0/framework/scripts/setup-linting.sh | bash -s -- --biome
+   ```
+
+   ```
+
+   ```
+
+2. **Update consolidated setup guide (framework/README.md)**
+   - Add "Installation" section with curl commands
+   - Add "Versioning" section explaining git tags
+   - Add "Upgrading" section
+   - Add "Auto-update check" section (explain SessionStart hook, how to disable)
+   - Add "Requirements" section (bash, jq, npm, git, curl, timeout)
+   - Add security note: inspect scripts before piping to bash
+   - Add note about version controlling .claude directory
+
+---
+
+## Success Criteria
+
+**Distribution:**
+
+- [ ] External user can run single curl command to set up linting (no global folder needed)
+- [ ] External user can run single curl command to set up quality review (no global folder needed)
+- [ ] Setup scripts are 100% self-contained (all code inline via heredocs)
+- [ ] Scripts work on machine with zero global .agents folder
+- [ ] Can specify version via URL: `v1.0.0`, `v1.1.0`, `main`
+
+**Generated Files:**
+
+- [ ] All hooks are project-local (no global references)
+- [ ] Generated files have version comments with upgrade instructions
+- [ ] setup-linting.sh creates `.claude/commands/lint.md` automatically
+- [ ] setup-quality.sh creates `.claude/commands/quality-review.md` automatically
+- [ ] Both setup scripts create `.claude/hooks/session-start.sh` with version check
+- [ ] SessionStart hook added to settings.json
+
+**Robustness:**
+
+- [ ] Scripts work in ANY order (settings.json merging via jq)
+- [ ] Scripts fail gracefully with clear error if jq is missing
+- [ ] jq is REQUIRED dependency (not optional)
+- [ ] Version check fails silently if offline/network issues
+- [ ] Version check cached (24hr) to avoid API spam
+- [ ] Version check can be disabled (create `.agents-no-check`)
+
+**Migration:**
+
+- [ ] Projects migrated to project-local hooks
+- [ ] No projects reference global paths
+
+**Documentation:**
+
+- [ ] README explains installation and upgrading
+- [ ] Release checklist documents VERSION update process
+- [ ] Documentation explains jq requirement
+
+---
+
+## Non-Goals (Avoiding Bloat)
+
+- ❌ CLI wrapper (`agents` command)
+- ❌ Lock files (`.agents.lock`)
+- ❌ Global installation (`~/.agents` for external users)
+- ❌ Global shared folder for hooks
+- ❌ Package manager (npm, homebrew)
+- ❌ PATH modifications
+- ❌ Automatic updates
+- ❌ Migration scripts
+- ❌ Dependency management beyond jq/bash/git
+- ❌ External file references (everything inline via heredocs)
+
+---
+
+## Rollout Plan
+
+### Phase 1: Development (Week 1)
+
+1. Create `setup-quality.sh`
+2. Add version comments to `setup-linting.sh`
+3. Test both scripts in clean directory
+4. Tag `v1.0.0`
+
+### Phase 2: Migration (Week 1)
+
+1. Run both setup scripts in `soulless-monorepo`
+2. Run both setup scripts in `chat`
+3. Verify no references to any global absolute paths
+4. Delete global hooks if no longer needed
+
+### Phase 3: Documentation (Week 1)
+
+1. Create `README.md` in `coding/`
+2. Update `framework/README.md`
+3. Create release notes for v1.0.0
+
+### Phase 4: Distribution (Week 2)
+
+1. Push to GitHub with tags
+2. Test installation from clean machine
+3. Share with external users
+
+---
+
+## Open Questions
+
+1. **Settings.json merging:** ~~Use jq or document script order?~~
+   - **RESOLVED:** Use jq for order-independent merging, make jq REQUIRED
+
+2. **Global hooks directory:** ~~Keep global hooks or delete?~~
+   - **RESOLVED:** Delete after migration (Task 7) - DONE
+   - Setup scripts (with inline heredocs) are the ONLY source of truth
+   - Simpler, no drift, cleaner architecture
+
+3. **Chat repo uses Biome via ultracite:** Should setup-quality.sh work with both?
+   - **Recommendation:** Yes, quality review is independent of linting
+
+4. **Version in script:** ~~Hardcoded or extract from git?~~
+   - **RESOLVED:** Hardcoded, update manually on release (see Task 5 checklist)
+   - Accept manual step, not a burden for 2 files
+
+5. **GitHub repo:** Public or private?
+   - **MUST BE PUBLIC** - SessionStart version check uses GitHub API (requires public repo)
+   - If private: version check won't work (API requires auth)
+   - Alternative: Host version file elsewhere for private repos
+
+---
+
+## Risks and Mitigations
+
+### Risk: Breaking changes in hooks
+
+**Impact:** External users' projects break on upgrade
+**Mitigation:**
+
+- Follow semver strictly
+- Test upgrades before tagging
+- Document breaking changes in release notes
+
+### Risk: Settings.json conflicts
+
+**Impact:** One setup overwrites another's hooks
+**Mitigation:**
+
+- Document script order
+- Use jq to merge instead of overwrite
+- Test both scripts together
+
+### Risk: Users run wrong version
+
+**Impact:** Mismatched hook versions in same project
+**Mitigation:**
+
+- Version comment in every file
+- Document "upgrade all at once"
+
+---
+
+## Timeline
+
+**Target completion:** 1 week
+
+- **Day 1:** Create `setup-quality.sh` (Task 1)
+- **Day 2:** Fix setup-linting.sh (Tasks 2, 3, 4, 8)
+- **Day 3:** Test both scripts together, verify settings.json merging, test version check
+- **Day 4:** Migrate `soulless-monorepo` and `chat` (Task 6)
+- **Day 5:** Delete hooks/ directory (Task 7), write documentation (Task 9)
+- **Day 6:** Tag v1.0.0, push to GitHub (Task 5)
+- **Day 7:** Test installation from clean machine, verify success criteria
+
+---
+
+## Implementation Order
+
+**Critical path:**
+
+1. Task 1: Create setup-quality.sh (enables migration)
+2. Task 2: Fix setup-linting.sh command creation
+3. Task 3: Add version comments to setup-linting.sh
+4. Task 4: Implement settings.json merging (both scripts)
+5. Task 8: Add SessionStart version check (both scripts)
+6. Task 6: Migrate existing projects
+7. Task 7: Delete hooks/ directory
+8. Task 9: Documentation
+9. Task 5: Tag and release
+
+**Dependencies:**
+
+- Tasks 2, 3, 4, 8 can be done in parallel after Task 1
+- Task 6 requires Tasks 1-4, 8 complete
+- Task 7 requires Task 6 complete
+- Task 9 can be done in parallel with Task 7
+- Task 5 (release) requires all tasks complete
+
+---
+
+## Next Actions
+
+1. ✅ Review this plan
+2. Answer remaining open question (#5: GitHub public/private?)
+3. Approve approach
+4. Begin implementation (start with Task 1)
+
+---
+
+**End of Plan**