This directory contains automated CI/CD workflows for the Autohand CLI project.

CI and release jobs use Node.js 24 and the Bun version declared in the root package.json (packageManager). Update that declaration to change the compiler for every build platform together. Frozen installs preserve the committed dependency resolutions. Weekly Dependabot updates keep the GitHub Actions versions current.

Triggers:

• Push to main (alpha release)
• Manual workflow dispatch

What it does:

1. Determines version based on the selected release channel

   • Alpha bumps the patch from the latest stable tag and appends the short SHA
   • Stable releases use the current package.json version unless manually overridden

2. Runs fast tests and built terminal tests in separate parallel jobs

3. Checks out the private ahtraces component at the immutable commit in .github/ahtraces-ref, using the read-only AHTRACES_REPO_TOKEN secret

4. Builds Autohand and ahtraces separately for all platforms, publishes checksums for the raw companions used by npm postinstall, then places both sibling executables in each release archive:

   • macOS Apple Silicon (autohand-macos-arm64)
   • macOS Intel (autohand-macos-x64)
   • Linux x64 (autohand-linux-x64)
   • Linux ARM64 (autohand-linux-arm64)
   • Windows x64 (autohand-windows-x64.exe)
   • Windows ARM64 (autohand-windows-arm64.exe)

5. Signs macOS binaries and Autohand Computer Use with Developer ID, submits them to Apple notarization, staples the app ticket, and verifies each transported Actions artifact on a native Apple Silicon or Intel runner before publication

6. Generates release notes from the correct previous release tag

7. Creates GitHub Release with binaries attached

8. Updates the public Homebrew tap from the verified release archives (stable releases only)

9. Publishes to npm

   • Alpha releases use the alpha dist-tag
   • Stable releases use the latest dist-tag

Release Channels:

• main push → v1.2.4-alpha.abc1234 (next patch from the latest stable tag plus short SHA)
• manual release → v1.2.3 (stable)

Triggers:

• Pull requests to main, beta, alpha
• Push to any branch (except main, beta, alpha)

What it does:

1. Type checking
2. Fast test execution
3. Built terminal tests in a separate parallel job
4. Build verification
5. Multi-platform build test

Trigger:

• A repository owner, member, or collaborator opens the Add model catalog entry issue form

What it does:

1. Reads the provider and model ID from the structured issue form
2. Validates the provider against src/providers/models.json
3. Rejects malformed IDs and reports duplicate models without changing the catalog
4. Appends the model while preserving provider defaults and existing model order
5. Pushes an issue-specific automation branch and opens a pull request against the default branch
6. Links the pull request from the issue for normal maintainer review

Optional display name, context-window, and reasoning-effort values produce a structured model entry. Requests without metadata preserve the provider's existing string/object entry style. The workflow never approves or merges its own pull request.

Triggers:

• A model catalog or publication workflow change lands on main
• Four-hour schedule
• Manual workflow dispatch

What it does:

1. Generates the full Pi-compatible catalog from src/providers/models.json
2. Validates provider and model records before any upload
3. Uploads immutable, content-addressed catalog and metadata objects to R2
4. Promotes cli/models.json only after the immutable upload succeeds
5. Writes cli/catalog.json for admin publication status

Trigger:

• The authenticated website admin dispatches a workflow with an immutable R2 draft ID and Git blob SHA

What it does:

1. Verifies that the GitHub source catalog still has the SHA edited by the administrator
2. Downloads the immutable draft from cli/drafts/<id>.json
3. Applies the compact source catalog and generates the full public catalog as validation
4. Creates an automation branch and commit with the required co-author trailer
5. Opens a pull request for maintainer review without approving or merging it

Add these secrets in GitHub Settings → Secrets → Actions:

1. NPM_TOKEN (required for npm publishing)

   # Generate at https://www.npmjs.com/settings/<your-username>/tokens
   # Type: Automation token

2. AHTRACES_REPO_TOKEN (required for release and CI builds)

   • Fine-grained read-only token for the private autohandai/ahtraces repository

3. macOS signing and notarization secrets (required for every alpha and stable release)

   • APPLICATION_CERT_BASE64: base64-encoded Developer ID Application .p12
   • CERT_PASSWORD: password for the signing certificate archive
   • DEVELOPER_NAME: organization name in the Developer ID certificate
   • TEAM_ID: Apple Developer team identifier
   • APPLE_ID: Apple account used by notarytool
   • APP_SPECIFIC_PASSWORD: app-specific password for that Apple account
   • The release fails before upload when signing credentials are missing. This prevents ad hoc app updates from changing the macOS permission identity.

4. MODEL_CATALOG_PR_TOKEN (optional for model catalog pull requests)

   • Fine-grained token with repository Contents, Issues, and Pull requests read/write access
   • When omitted, the workflow uses the repository GITHUB_TOKEN
   • Configure this token when automated pull requests must trigger other GitHub Actions workflows

5. Model catalog R2 credentials (required for publication and admin drafts)

   • R2_ACCOUNT_ID
   • R2_MODELS_BUCKET
   • R2_MODELS_ACCESS_KEY_ID
   • R2_MODELS_SECRET_ACCESS_KEY
   • Scope the access key to the model-catalog bucket with object read/write access

6. TAP_GITHUB_TOKEN (required for stable releases)

   • Fine-grained token with Contents read/write access to autohandai/homebrew-code
   • The tap repository must remain public so Homebrew users can install without GitHub credentials

1. Enable Actions

   • Settings → Actions → General
   • Allow all actions and reusable workflows

2. Workflow Permissions

   • Settings → Actions → General → Workflow permissions
   • ✅ Read and write permissions
   • ✅ Allow GitHub Actions to create pull requests

1. Open Issues → New issue → Add model catalog entry.
2. Select one of the providers currently defined in src/providers/models.json.
3. Enter the provider's exact model card or API model ID.
4. Optionally add a display name, context window, and reasoning effort.
5. Submit the issue from an account associated with the repository as an owner, member, or collaborator.
6. Review and manually merge the pull request linked by the workflow.

The provider dropdown is covered by a repository test so catalog/provider drift fails CI. If the model already exists, the workflow comments on the issue and does not open an empty pull request.

1. Make changes and commit with conventional commits:

   git commit -m "feat: add new feature"
   git commit -m "fix: resolve bug"

2. Merge to appropriate branch:

   # For alpha testing
   git checkout alpha
   git merge feature-branch
   git push
   
   # For beta testing
   git checkout beta
   git merge alpha
   git push
   
   # For stable release
   git checkout main
   git merge beta
   git push

3. GitHub Actions automatically:

   • Determines version
   • Builds binaries
   • Generates release notes
   • Creates release

1. Go to: Actions → Release → Run workflow
2. Choose:
   • Branch: main or another release source branch
   • Version: Leave empty for auto, or specify 1.2.3 or v1.2.3; the workflow normalizes the optional leading v before creating tags, formulas, and packages
   • Channel: alpha/release
3. Click "Run workflow"

Before a stable GitHub Release becomes public, the workflow verifies that the Homebrew tap is public and writable, renders and syntax-checks its formula from the built archive checksums, and builds the npm package. The release workflow does not push version commits back to the protected source branch.

Format: MAJOR.MINOR.PATCH[-prerelease]

• MAJOR: Breaking changes
• MINOR: New features
• PATCH: Bug fixes and small improvements

• Alpha: 1.2.4-alpha.abc1234 (next patch from the latest stable tag plus short SHA)
• Release: 1.2.3 (no suffix)

The workflow automatically generates release notes from commits and attaches them to the GitHub Release. Stable releases compare against the previous stable tag, so a release like v0.9.2 compares against v0.9.1 even if there was a same-commit alpha tag such as v0.9.2-alpha.<sha>. Alpha releases compare against the previous reachable release tag.

Commits are categorized as:

• ⚠️ BREAKING CHANGES: Breaking changes
• ✨ Features: New features
• 🐛 Bug Fixes: Bug fixes
• Updates: User-visible non-conventional commit subjects
• 🔧 Maintenance: Chores and maintenance

Check:

1. All dependencies are in package.json
2. TypeScript compiles without errors (bun run typecheck)
3. Bun version compatibility

Check:

1. The last commit is not a version bump commit (contains chore(release):)
2. Repository has write permissions enabled

Check:

1. NPM_TOKEN secret is set and valid
2. Package name is available on npm
3. Version doesn't already exist on npm

Test the build locally before pushing:

# Build all platforms
bun run compile:all

# Test a specific platform
bun run compile:macos-arm64

# Verify binary
./binaries/autohand-macos-arm64 --help

View workflow runs:

• Repository → Actions tab
• Click on workflow run to see logs
• Download artifacts from completed runs