Skip to content

migration-to-native-binary.md

Latest commit

 

History

History
242 lines (194 loc) · 9.69 KB

migration-to-native-binary.md

File metadata and controls

242 lines (194 loc) · 9.69 KB

Migration to Native Binary

This document tracks the migration from shell scripts (.sh/.ps1) to a .NET Native AOT binary for the copilot_here CLI tool.

Migration Status

Core Execution Features

Feature Status Notes
Docker container execution ✅ Done Full docker run with all args
Image selection (latest, dotnet, playwright, etc.) ✅ Done All variants supported
YOLO mode (--allow-all-tools --allow-all-paths) ✅ Done Passed via --yolo flag
Safe mode (default) ✅ Done Default behavior
Mount current directory ✅ Done
Container work directory mapping ✅ Done Maps ~/... to /home/appuser/...
GitHub token injection ✅ Done Via gh auth token
User/Group ID mapping (PUID/PGID) ✅ Done Uses id -u and id -g
Terminal title setting ✅ Done With emoji for mode indicator
Interactive mode with banner ✅ Done Auto-adds --banner when no args

Image Management

Feature Status Notes
--dotnet / -d ✅ Done
--dotnet8 / -d8 ✅ Done
--dotnet9 / -d9 ✅ Done
--dotnet10 / -d10 ✅ Done
--playwright / -pw ✅ Done
--dotnet-playwright / -dp ✅ Done
--rust / -rs ✅ Done
--dotnet-rust / -dr ✅ Done
--list-images ✅ Done Lists all available tags
--show-image ✅ Done Shows active/local/global config
--set-image <tag> ✅ Done Local config
--set-image-global <tag> ✅ Done Global config
--clear-image ✅ Done
--clear-image-global ✅ Done
Default image from config ✅ Done Priority: local > global > latest
Image cleanup (7+ days old) ✅ Done Skips currently used image
Image pull with spinner ✅ Done

Mount Management

Feature Status Notes
--mount <path> (read-only) ✅ Done
--mount-rw <path> (read-write) ✅ Done
--list-mounts ✅ Done Shows global/local mounts
--save-mount <path> ✅ Done Local config
--save-mount-global <path> ✅ Done Global config
--remove-mount <path> ✅ Done Removes from both configs
Load mounts from local config ✅ Done .copilot_here/mounts.conf
Load mounts from global config ✅ Done ~/.config/copilot_here/mounts.conf
Symlink following for configs ✅ Done Uses FileInfo.LinkTarget
Path normalization (tilde, relative) ✅ Done Tilde expansion, relative paths
Sensitive path warnings ✅ Done /, /etc, /root, ~/.ssh - prompts for confirmation
Mount priority (CLI > local > global) ✅ Done Runtime merge logic
Mount display with icons ✅ Done 📁, 🌍, 📍, 🔧

Airlock (Network Proxy)

Feature Status Notes
--enable-airlock ✅ Done Local config
--enable-global-airlock ✅ Done Global config
--disable-airlock ✅ Done
--disable-global-airlock ✅ Done
--show-airlock-rules ✅ Done Shows enabled status and rules content
--edit-airlock-rules ✅ Done Opens in $EDITOR
--edit-global-airlock-rules ✅ Done Opens in $EDITOR
Docker Compose generation ✅ Done Generate from template
Proxy container management ✅ Done Start proxy, run app, cleanup
Network config placeholder replacement ✅ Done {{GITHUB_OWNER}}, {{GITHUB_REPO}}
Orphaned network cleanup ✅ Done Find and remove stale networks/containers
Logs directory setup ✅ Done Create .copilot_here/logs with gitignore
Monitor vs enforce mode ✅ Done Reads from config
Session ID generation ✅ Done SHA256 hash of PID+timestamp
Template download ✅ Done Download compose template if missing

Security

Feature Status Notes
Token scope validation ✅ Done Require copilot, read:packages
Privileged scope warning ✅ Done Warn+confirm on admin:*, write:*, manage_*, delete_*
Test mode bypass ✅ Done COPILOT_HERE_TEST_MODE env var

CLI Infrastructure

Feature Status Notes
-h / --help ✅ Done System.CommandLine auto-generated
--help2 ✅ Done Shows native copilot --help
--no-cleanup ✅ Done
--no-pull / --skip-pull ✅ Done
--update / -u ✅ Done Checks GitHub releases for updates
Version check and update prompt ✅ Done Shows download instructions
Passthrough args to copilot ✅ Done -p, --model, --continue, --resume, --
Emoji support detection ✅ Done

Self-Update

Feature Status Notes
Check for updates on GitHub ✅ Done Uses releases API
Download instructions ✅ Done Platform-specific curl/PowerShell commands
Version comparison ✅ Done Semver comparison
Runtime identifier detection ✅ Done Auto-detects OS and architecture

GitHub Integration

Feature Status Notes
Get owner/repo from git remote ✅ Done For placeholder replacement
Parse SSH and HTTPS remote URLs ✅ Done Handles all GitHub URL formats

Config File Locations

Config Path Purpose
Local mounts .copilot_here/mounts.conf Project-specific mounts
Global mounts ~/.config/copilot_here/mounts.conf User-wide mounts
Local image .copilot_here/image.conf Project-specific default image
Global image ~/.config/copilot_here/image.conf User-wide default image
Local airlock .copilot_here/airlock.enabled Project-specific airlock flag
Global airlock ~/.config/copilot_here/airlock.enabled User-wide airlock flag
Local network rules .copilot_here/network.json Project-specific airlock rules
Global network rules ~/.config/copilot_here/network.json User-wide airlock rules
Default airlock rules ~/.config/copilot_here/default-airlock-rules.json Base rules
Compose template ~/.config/copilot_here/docker-compose.airlock.yml.template Docker compose template
Copilot config ~/.config/copilot-cli-docker Copilot CLI persistence

Architecture Notes

AOT Compatibility Requirements

  1. No reflection-based serialization - Use source generators for JSON
  2. No dynamic code generation - All types must be known at compile time
  3. Avoid System.Text.Json without source generators - Use [JsonSerializable] attributes
  4. No dynamic keyword usage
  5. Prefer struct over class for small data types - Reduces heap allocations
  6. Use spans and stackalloc where possible - Avoid allocations in hot paths

Binary Size Optimization

Current project settings:

  • TrimMode=full - Aggressive dead code elimination
  • InvariantGlobalization=true - No ICU data
  • StackTraceSupport=false - Smaller binaries
  • OptimizationPreference=Size - Prefer size over speed

Dependencies

  • System.CommandLine (2.0.0) - AOT-compatible argument parsing

Testing Requirements

All features must have corresponding tests:

  • Unit tests for config parsing
  • Unit tests for path resolution
  • Integration tests for Docker command generation
  • Integration tests for config file reading/writing

Migration Priority

  1. High Priority (Core functionality) - ✅ Complete

    • Security checks (token validation)
    • All image variants
    • Mount config loading
    • Help text

  2. Medium Priority (User experience) - ✅ Complete

    • Terminal title
    • Progress spinners
    • Emoji detection
    • Update checking

  3. Low Priority (Advanced features) - ✅ Complete

    • Airlock proxy mode (Docker Compose)
    • Self-update mechanism

Distribution Strategy

Binary Distribution

Native AOT binaries are built for multiple platforms:

Platform Runtime Identifier Binary Name
Linux x64 linux-x64 copilot_here
Linux ARM64 linux-arm64 copilot_here
macOS x64 osx-x64 copilot_here
macOS ARM64 osx-arm64 copilot_here
Windows x64 win-x64 copilot_here.exe
Windows ARM64 win-arm64 copilot_here.exe

Installation Flow

  1. Initial Installation (via shell script download):

    # Linux/macOS
curl -fsSL https://raw.githubusercontent.com/GordonBeeming/copilot_here/main/copilot_here.sh -o ~/.copilot_here.sh
source ~/.copilot_here.sh

# PowerShell
irm https://raw.githubusercontent.com/GordonBeeming/copilot_here/main/copilot_here.ps1 | iex

  2. First Run - Shell wrapper:

    • Checks for binary at ~/.local/bin/copilot_here[.exe]
    • If missing, downloads from GitHub releases
    • Passes all arguments to binary
    • Adds --yolo flag when called as copilot_yolo

  3. Updates - Via the binary itself:

    • copilot_here --update checks GitHub releases
    • Downloads new binary if available
    • Replaces existing binary

Shell Wrapper Responsibilities

The thin shell wrappers (copilot_here.sh / copilot_here.ps1) handle:

  • Binary location and download
  • Mode detection (copilot_here vs copilot_yolo)
  • Platform/architecture detection for correct binary
  • First-time setup messaging

GitHub Actions Workflow

The publish.yml workflow builds:

  1. Docker images (existing functionality)
  2. Native AOT binaries for all platforms (new)
    • Published as release artifacts
    • Tagged with commit SHA

Version Management

  • Binary version comes from CopilotHere.csproj <Version> property
  • Shell wrapper version in header comment for backward compatibility
  • Binary self-update checks GitHub releases API