claudetools/.claude/skills/gitea/README.md

# Gitea Skill — Bulletproof Git/Gitea Operations

Comprehensive git/Gitea operations extracted from `sync.sh` into reusable commands for the fleet.

## Quick Start

```bash
# Fix a broken submodule (what you needed for radio-show)
bash .claude/skills/gitea/scripts/gitea.sh submodule fix projects/radio-show

# Health check before sync
bash .claude/skills/gitea/scripts/gitea.sh health

# Status with all submodules
bash .claude/skills/gitea/scripts/gitea.sh status --verbose

# Initialize all missing submodules
bash .claude/skills/gitea/scripts/gitea.sh submodule init

# Sync submodules to remote tips (opt-in, like --with-submodules)
bash .claude/skills/gitea/scripts/gitea.sh submodule sync
```

## What This Solves

### Problem: Manual Submodule Fixes
Before this skill, fixing a broken submodule like `radio-show` required:
1. Manually running `git submodule init`
2. Then `git submodule update --init`
3. Dealing with collision errors
4. Checking if it worked
5. Fixing detached HEADs

**Now:** `bash .claude/skills/gitea/scripts/gitea.sh submodule fix projects/radio-show`

### Problem: Sync.sh Patterns Locked Away
The battle-tested patterns in `sync.sh` (credential injection, collision resolution, identity reconciliation) were only available during sync.

**Now:** Available as standalone commands for any git operation.

### Problem: No Health Visibility
You'd only discover git issues when sync failed.

**Now:** `bash .claude/skills/gitea/scripts/gitea.sh health` proactively checks everything.

## Integration with Existing Scripts

### Using in sync.sh (Future Refactor)

Replace inline submodule handling with skill calls:

```bash
# Instead of 150 lines of submodule init/update logic:
bash .claude/skills/gitea/scripts/gitea.sh submodule init

# Instead of resolve_submodule_collisions + retry:
bash .claude/skills/gitea/scripts/gitea.sh submodule update
```

### Using in Other Scripts

```bash
# Backup script needs health check before backup:
bash .claude/skills/gitea/scripts/gitea.sh health || exit 1

# Deployment script needs clean status:
bash .claude/skills/gitea/scripts/gitea.sh status --verbose
```

## Commands Reference

### Submodule Operations

| Command | Use Case | What It Does |
|---------|----------|--------------|
| `submodule init [PATH]` | Fresh clone, new submodule added | Init & populate at pinned commit, inject creds, reconcile identity |
| `submodule update [PATH]` | After parent pull | Checkout to pinned commit, handle collisions |
| `submodule sync [PATH]` | Want latest upstream | Fetch + ff-merge to remote tip (opt-in) |
| `submodule status` | Check all submodules | Show status with color coding |
| `submodule fix [PATH]` | Any submodule issue | Auto-detect & fix common problems |

### Repository Operations

| Command | Use Case | What It Does |
|---------|----------|--------------|
| `status [--verbose]` | Quick check | Show repo + optional submodule status |
| `health` | Pre-sync validation | Full diagnostic: identity, config, subs, remote |
| `fetch [--recurse]` | Inspect before pull | Fetch from origin, optional submodule recursion |
| `pull [--recurse]` | Sync from remote | Fetch + rebase, update subs after |
| `push` | Publish work | Push to origin/main |
| `commit "msg"` | Commit staged changes | Simple commit wrapper |

### Utilities

| Command | Use Case | What It Does |
|---------|----------|--------------|
| `verify-identity` | Fix git config drift | Reconcile user.name/email from identity.json |
| `inject-creds` | Submodule auth issues | Inject parent HTTPS creds to submodules |

## Error Codes

- `0` — Success
- `1` — General error (bad args, command failed)
- `2` — identity.json missing/unreadable
- `3` — Not a git repo
- `75` — Lock contention (reserved for future use)

## Common Workflows

### 1. Fix Broken Submodule (Like radio-show)

```bash
bash .claude/skills/gitea/scripts/gitea.sh submodule fix projects/radio-show
```

Detects and fixes:
- Not initialized
- Detached HEAD
- Colliding untracked files
- Pointer mismatch with parent

### 2. Pre-Sync Health Check

```bash
if bash .claude/skills/gitea/scripts/gitea.sh health; then
    bash .claude/scripts/sync.sh
else
    echo "Fix issues first"
fi
```

### 3. Initialize All Submodules on Fresh Clone

```bash
bash .claude/skills/gitea/scripts/gitea.sh submodule init
```

Auto-injects credentials, reconciles identity, handles all 22 submodules.

### 4. Advance Submodules to Remote Tips

```bash
# Like sync.sh --with-submodules, but standalone
bash .claude/skills/gitea/scripts/gitea.sh submodule sync
```

### 5. Debug Submodule Issues

```bash
# See what's wrong
bash .claude/skills/gitea/scripts/gitea.sh submodule status

# Try auto-fix
bash .claude/skills/gitea/scripts/gitea.sh submodule fix

# Still broken? Manual intervention with context
```

## Fleet Deployment

### Current Status
- Skill created and tested on `Mikes-MacBook-Air`
- Works with existing identity.json
- No changes required to sync.sh (but refactor recommended)

### Rollout Plan
1. Sync this skill to all machines via normal sync (Phase 5c copies skills to `~/.claude/skills`)
2. Test `health` command on each machine
3. Document any machine-specific issues
4. Optionally refactor sync.sh to use skill helpers
5. Train team on common commands

### Testing Checklist
- [ ] `gitea.sh health` runs successfully
- [ ] `gitea.sh submodule status` shows all submodules
- [ ] `gitea.sh submodule fix` resolves issues
- [ ] `gitea.sh verify-identity` matches identity.json
- [ ] Works on Windows (test garbled path handling)
- [ ] Works on Linux
- [ ] Works on macOS (tested ✓)

## What's Extracted from sync.sh

This skill encapsulates:
- `reconcile_git_identity()` — now `verify-identity` command
- `resolve_submodule_collisions()` — used in `update` and `fix`
- `inject_credentials()` — now `inject-creds` command
- Submodule init/update/sync logic — now dedicated commands
- Health checks — new `health` command
- Python detection — reused from sync.sh
- identity.json loading — reused from sync.sh

## Future Enhancements

### Potential Additions
- `gitea.sh submodule detach <path>` — revert to pinned commit (undo accidental advance)
- `gitea.sh bisect` — wrapper for git bisect with submodule awareness
- `gitea.sh blame <file>` — enhanced blame with submodule context
- `gitea.sh clone <url>` — clone with auto credential injection
- Lock integration — claim sync lock via coord API

### Integration Opportunities
- Call from `sync.sh` to deduplicate logic
- Call from backup scripts for pre-backup health
- Call from deployment scripts for clean-state validation
- Coord API integration for fleet-wide submodule status

## Troubleshooting

### Command Not Found
```bash
# Skill not synced yet
bash .claude/scripts/sync.sh  # Copies to ~/.claude/skills

# Or run directly from repo
bash /path/to/ClaudeTools/.claude/skills/gitea/scripts/gitea.sh health
```

### identity.json Errors
```bash
# Check identity.json exists and is valid JSON
cat .claude/identity.json | python3 -m json.tool
```

### Submodule Fix Not Working
```bash
# Check what's actually wrong
bash .claude/skills/gitea/scripts/gitea.sh submodule status

# Try manual intervention
cd projects/problematic-submodule
git status
git log --oneline -5
```

### Credential Injection Not Working
```bash
# Check parent URL has embedded credentials
git config --get remote.origin.url

# Should be: https://user:pass@host/repo.git
# Not: https://host/repo.git or git@host:repo.git
```

## See Also

- `.claude/scripts/sync.sh` — The main sync script this skill extends
- `.claude/CLAUDE_EXTENDED.md` — Full ClaudeTools manual
- `.gitmodules` — Submodule configuration
- `wiki/systems/gitea.md` — Gitea server documentation (if exists)