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

# 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

# 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

# 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:

   curl -fsSL https://toothfairyai.com/install/tfcode | bash
   tfcode --version
   

2. Verify npm install works:

   npm install -g @toothfairyai/tfcode
   tfcode --version
   

3. Verify brew install works:

   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

# Try installing dependencies first
bun install

# Then rebuild
bun run build:single

Upload Fails

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

npm Publish Fails

# 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