tf_code/docs/build-release.md

# tfcode Build & Release Guide

This document explains how to build and release tfcode to match opencode's distribution model.

## Distribution Channels

tfcode can be installed via:

1. **curl** - `curl -fsSL https://toothfairyai.com/install/tfcode | bash`
2. **npm** - `npm install -g @toothfairyai/tfcode`
3. **bun** - `bun install -g @toothfairyai/tfcode`
4. **brew** - `brew install toothfairyai/tap/tfcode`

## How It Works

### Architecture

```
┌──────────────────────────────────────────────────────────────┐
│                      Gitea Releases                          │
│  (gitea.toothfairyai.com/ToothFairyAI/tfcode/releases)      │
│                                                              │
│  - tfcode-darwin-arm64.zip                                   │
│  - tfcode-darwin-x64.zip                                     │
│  - tfcode-linux-arm64.tar.gz                                 │
│  - tfcode-linux-x64.tar.gz                                   │
│  - tfcode-windows-x64.zip                                    │
│  - ...                                                       │
└──────────────────────────────────────────────────────────────┘
                           ▲
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
    ┌────┴────┐      ┌─────┴─────┐    ┌────┴────┐
    │   npm   │      │   curl    │    │  brew   │
    │         │      │           │    │         │
    │Downloads│      │ Downloads │    │Downloads│
    │ binary  │      │  binary   │    │ binary  │
    └─────────┘      └───────────┘    └─────────┘
```

### npm Package Structure

```
@toothfairyai/tfcode (main package)
├── bin/tfcode (wrapper script)
├── postinstall.mjs (downloads correct binary)
└── optionalDependencies:
    ├── @toothfairyai/tfcode-darwin-arm64
    ├── @toothfairyai/tfcode-darwin-x64
    ├── @toothfairyai/tfcode-linux-arm64
    ├── @toothfairyai/tfcode-linux-x64
    ├── @toothfairyai/tfcode-windows-arm64
    └── @toothfairyai/tfcode-windows-x64
```

## Build Process

### Prerequisites

1. **bun** installed
2. **Gitea token** with release permissions
3. **npm token** for publishing

### Step 1: Build Binaries

```bash
# Build all platform binaries
cd packages/tfcode
bun run build

# Or build just for current platform (faster for testing)
bun run build:single
```

This creates:
- `dist/tfcode-darwin-arm64/bin/tfcode`
- `dist/tfcode-darwin-x64/bin/tfcode`
- `dist/tfcode-linux-arm64/bin/tfcode`
- etc.

### Step 2: Package for Release

```bash
# Set environment
export GITEA_TOKEN="your-token"
export GITEA_HOST="gitea.toothfairyai.com"
export GITEA_REPO="ToothFairyAI/tfcode"

# Upload to Gitea release
bun run publish:upload

# Publish to npm
bun run publish:npm

# Create Homebrew formula
bun run publish:brew

# Or do all at once
bun run publish:all
```

## Release Checklist

### Before Release

1. Update version in `packages/tfcode/package.json`
2. Update `CHANGELOG.md` with changes
3. Test build locally: `bun run build:single`
4. Test the binary: `./dist/tfcode-darwin-arm64/bin/tfcode --version`

### During Release

```bash
# 1. Build all binaries
bun run build

# 2. Upload to Gitea
bun run publish:upload

# 3. Publish to npm
npm login --scope=@toothfairyai
bun run publish:npm

# 4. Update Homebrew tap
# (Manual: copy dist/tfcode.rb to homebrew-tap repo)
```

### After Release

1. Verify curl install works:
   ```bash
   curl -fsSL https://toothfairyai.com/install/tfcode | bash
   tfcode --version
   ```

2. Verify npm install works:
   ```bash
   npm install -g @toothfairyai/tfcode
   tfcode --version
   ```

3. Verify brew install works:
   ```bash
   brew install toothfairyai/tap/tfcode
   tfcode --version
   ```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `GITEA_HOST` | Gitea server | `gitea.toothfairyai.com` |
| `GITEA_REPO` | Gitea repository | `ToothFairyAI/tfcode` |
| `GITEA_TOKEN` | Gitea API token | (required for upload) |
| `TFCODE_VERSION` | Override version | (from package.json) |

## Platform Support

| Platform | Arch | Variants |
|----------|------|----------|
| macOS | arm64 | - |
| macOS | x64 | baseline |
| Linux | arm64 | musl |
| Linux | x64 | baseline, musl |
| Windows | arm64 | - |
| Windows | x64 | baseline |

### Binary Variants

- **baseline**: For older CPUs without AVX2 support
- **musl**: For Alpine Linux and other musl-based distros

## Troubleshooting

### Build Fails

```bash
# Try installing dependencies first
bun install

# Then rebuild
bun run build:single
```

### Upload Fails

```bash
# Check token permissions
curl -H "Authorization: token $GITEA_TOKEN" \
  https://$GITEA_HOST/api/v1/user/repos
```

### npm Publish Fails

```bash
# Login to npm
npm login --scope=@toothfairyai

# Check you're logged in
npm whoami
```

## Files Reference

| File | Purpose |
|------|---------|
| `script/build-tfcode.ts` | Build all platform binaries |
| `script/publish-tfcode.ts` | Upload to Gitea, publish npm, create brew formula |
| `script/postinstall-tfcode.mjs` | npm postinstall - downloads binary |
| `scripts/install-tfcode.sh` | curl install script |
| `bin/tfcode` | Wrapper script (source repo) |
| `bin/tfcode.js` | Minimal CLI (npm package) |

## Comparison with OpenCode

| Aspect | OpenCode | tfcode |
|--------|----------|--------|
| Release hosting | GitHub Releases | Gitea Releases |
| npm package | `opencode-ai/opencode` | `@toothfairyai/tfcode` |
| Binary packages | `opencode-*` | `tfcode-*` |
| Install script | `opencode.ai/install` | `toothfairyai.com/install/tfcode` |
| Brew tap | `anomalyco/homebrew-tap` | `toothfairyai/homebrew-tap` |

## Next Steps

1. **Set up CI/CD** - Automate builds on tag push
2. **Create Homebrew tap repo** - `github.com/toothfairyai/homebrew-tap`
3. **Set up install website** - `toothfairyai.com/install/tfcode`
4. **Add auto-update** - Check for updates on launch