feat: Multi-platform package distribution with cross-architecture binary support (#21)

* feat: add multi-platform build support with Docker and improved distribution

- Add Linux x64/ARM64 builds via Docker containers
- Add Windows build system using AWS CodeBuild
- Create distribute command for secure package sharing via S3 presigned URLs
- Create builds command for monitoring CodeBuild status
- Improve package command with platform-specific builds
- Add Intel Mac build attempts (challenging due to architecture differences)
- Update documentation for all new platform support
- Fix monitoring token authentication bypass for OTEL telemetry

This commit represents a working state with Nuitka before switching to PyInstaller
for better cross-architecture support on macOS.

* fix: resolve package distribution and Linux compatibility issues

- Always create Claude Code settings.json for Bedrock configuration (not just monitoring)
- Fix Windows paths in settings.json using forward slashes for compatibility
- Fix package command to continue when Windows builds run in CodeBuild
- Fix nested directory issue in Windows PowerShell extraction instructions
- Fix Linux GLIBC compatibility by using Ubuntu 20.04 base (GLIBC 2.31)
- Fix six.moves import errors with six==1.16.0 and proper hidden imports
- Add Docker-based Linux testing infrastructure
- Improve distribution command with progress tracking and better error handling
- Update documentation for clarity and accuracy

* chore: remove Nuitka migration documentation

These intermediary development documents are not needed in the final solution.
The project uses PyInstaller for all cross-platform binary builds.

Author: schuettc

README.md

@@ -12,6 +12,7 @@ This guidance enables organizations to provide secure, centralized access to Cla
 - **Comprehensive Audit Trail**: Full CloudTrail logging of all Bedrock access
 - **Usage Monitoring**: Optional CloudWatch dashboards for tracking usage and costs
 - **Multi-Region Support**: Configure which AWS regions users can access Bedrock in
+- **Multi-Platform Support**: Windows, macOS (ARM & Intel), and Linux distributions
 
 ### For End Users
 
@@ -20,6 +21,7 @@ This guidance enables organizations to provide secure, centralized access to Cla
 - **AWS CLI/SDK Integration**: Works with any AWS tool or SDK
 - **Secure Credential Storage**: Choice of OS keyring or session-based storage
 - **Multi-Profile Support**: Manage multiple authentication profiles
+- **Cross-Platform**: Works on Windows, macOS, and Linux
 
 ## Table of Contents
 
@@ -58,18 +60,31 @@ poetry run ccwb init
 # Deploy infrastructure
 poetry run ccwb deploy
 
-# Create distribution package for users
-poetry run ccwb package
+# Create distribution package for users (all platforms)
+poetry run ccwb package --target-platform=all
+
+# Create and distribute package via secure URL (Optional)
+poetry run ccwb distribute
 ```
 
 2. Test package locally to verify end-user installation and access to Amazon Bedrock.
 
-```
+```bash
 # Test package locally
 poetry run ccwb test
 ```
 
-3. [Distribute](#end-user-experience) package to end-users.
+3. Distribute package to end-users (optional).
+
+```bash
+# Generate secure distribution URL (expires in 48 hours)
+poetry run ccwb distribute
+
+# Or specify custom expiration
+poetry run ccwb distribute --expires-hours=72
+```
+
+4. Share the generated URL with developers - no AWS credentials required for download.
 
 ### Cleanup
 
@@ -117,7 +132,7 @@ _You are responsible for the cost of the AWS services used while running this gu
 
 ### Sample Cost Table
 
-The following table provides a sample cost breakdown for deploying this guidance with 5,000 monthly active users in the US East (N. Virginia) Region for one month (monitoring is separate).
+The following table provides a sample cost breakdown for deploying this guidance with 5,000 monthly active users in the US East (N. Virginia) Region for one month (monitoring, analytics, and Windows builds would be separate).
 
 | AWS service            | Dimensions                 | Cost [USD] |
 | ---------------------- | -------------------------- | ---------- |
@@ -142,7 +157,9 @@ Based on AWS Pricing Calculator: [View Detailed Estimate](https://calculator.aws
   - CloudFormation stacks
   - Cognito Identity Pools
   - IAM roles and policies
-  - (Optional) ECS tasks and CloudWatch dashboards
+  - (Optional) Amazon Elastic Container Service (Amazon ECS) tasks and Amazon CloudWatch dashboards
+  - (Optional) Amazon Athena, AWS Glue, AWS Lambda, and Amazon Data Firehose resources
+  - (Optional) AWS CodeBuild
 - Amazon Bedrock activated in target regions
 
 **OIDC Provider Requirements:**
@@ -167,7 +184,9 @@ The guidance can be deployed in any AWS region that supports:
 
 - Amazon Cognito Identity Pools
 - Amazon Bedrock
-- (Optional) Amazon ECS Fargate for monitoring
+- (Optional) Amazon Elastic Container Service (Amazon ECS) tasks and Amazon CloudWatch dashboards
+- (Optional) Amazon Athena, AWS Glue, AWS Lambda, and Amazon Data Firehose resources
+- (Optional) AWS CodeBuild
 
 ### Cross-Region Inference
 
@@ -179,6 +198,35 @@ Claude Code uses Amazon Bedrock's cross-region inference for optimal performance
 
 This automatically routes requests across multiple AWS regions to ensure the best response times and highest availability. Modern Claude models (3.7+) require cross-region inference for access.
 
+### Platform Support
+
+The authentication tools support all major platforms:
+
+| Platform | Architecture          | Build Method                | Installation |
+| -------- | --------------------- | --------------------------- | ------------ |
+| Windows  | x64                   | AWS CodeBuild (Nuitka)      | install.bat  |
+| macOS    | ARM64 (Apple Silicon) | Native (PyInstaller)        | install.sh   |
+| macOS    | Intel (x86_64)        | Cross-compile (PyInstaller) | install.sh   |
+| macOS    | Universal (both)      | Universal2 (PyInstaller)    | install.sh   |
+| Linux    | x86_64                | Docker (PyInstaller)        | install.sh   |
+| Linux    | ARM64                 | Docker (PyInstaller)        | install.sh   |
+
+**Build Requirements:**
+
+- **Windows**: AWS CodeBuild with Nuitka (automated)
+- **macOS**: PyInstaller with architecture-specific builds
+  - ARM64: Native build on Apple Silicon Macs
+  - Intel: Optional - requires x86_64 Python environment on ARM Macs
+  - Universal: Requires both architectures' Python libraries
+- **Linux**: Docker with PyInstaller (for building on non-Linux hosts)
+
+### Optional: Intel Mac Builds
+
+Intel Mac builds require an x86_64 Python environment on Apple Silicon Macs.
+See [CLI Reference](assets/docs/CLI_REFERENCE.md#intel-mac-build-setup-optional) for setup instructions.
+
+If not configured, the package command will skip Intel builds and continue with other platforms.
+
 ## Implementation
 
 ### Step 1: Initialize Configuration
@@ -233,19 +281,37 @@ This creates the following AWS resources:
 Build the package for end users:
 
 ```bash
-poetry run ccwb package
+# Build all platforms (starts Windows build in background)
+poetry run ccwb package --target-platform all
+
+# Check Windows build status (optional)
+poetry run ccwb builds
+
+# When ready, create distribution URL (optional)
+poetry run ccwb distribute
 ```
 
-This creates a `dist/` folder containing:
+**Package Workflow:**
+
+1. **Local builds**: macOS/Linux executables are built locally using PyInstaller
+2. **Windows builds**: Trigger AWS CodeBuild for Windows executables (20+ minutes) - requires enabling CodeBuild during `init`
+3. **Check status**: Monitor build progress with `poetry run ccwb builds`
+4. **Create distribution**: Use `distribute` to upload and generate presigned URLs
+
+> **Note**: Windows builds are optional and require CodeBuild to be enabled during the `init` process. If not enabled, the package command will skip Windows builds and continue with other platforms.
+
+The `dist/` folder will contain:
 
-- `credential-process-macos` - Authentication executable for macOS
-- `credential-process-linux` - Authentication executable for Linux
+- `credential-process-macos-arm64` - Authentication executable for macOS ARM64
+- `credential-process-macos-intel` - Authentication executable for macOS Intel (if built)
+- `credential-process-windows.exe` - Authentication executable for Windows
+- `credential-process-linux` - Authentication executable for Linux (if built on Linux)
 - `config.json` - Embedded configuration
-- `install.sh` - Installation script (auto-detects platform)
+- `install.sh` - Installation script for Unix systems
+- `install.bat` - Installation script for Windows
 - `README.md` - User instructions
 - `.claude/settings.json` - Claude Code telemetry settings (if monitoring enabled)
-- `otel-helper-macos` - OTEL helper executable for macOS (if monitoring enabled)
-- `otel-helper-linux` - OTEL helper executable for Linux (if monitoring enabled)
+- `otel-helper-*` - OTEL helper executables for each platform (if monitoring enabled)
 
 The package builder:
 

assets/docs/CLI_REFERENCE.md

@@ -13,6 +13,8 @@ This document provides a complete reference for all `ccwb` (Claude Code with Bed
     - [`deploy` - Deploy Infrastructure](#deploy---deploy-infrastructure)
     - [`test` - Test Package](#test---test-package)
     - [`package` - Create Distribution](#package---create-distribution)
+    - [`builds` - List and Manage CodeBuild Builds](#builds---list-and-manage-codebuild-builds)
+    - [`distribute` - Create Distribution URLs](#distribute---create-distribution-urls)
     - [`status` - Check Deployment Status](#status---check-deployment-status)
     - [`cleanup` - Remove Installed Components](#cleanup---remove-installed-components)
     - [`destroy` - Remove Infrastructure](#destroy---remove-infrastructure)
@@ -63,6 +65,7 @@ poetry run ccwb init [options]
 - Configures cross-region inference profiles (US, Europe, APAC)
 - Prompts for source region selection for model inference
 - Sets up monitoring options
+- Prompts for Windows build support via AWS CodeBuild (optional)
 - Saves configuration to `.ccwb-config/config.json` in the project directory
 
 **Note:** This command only creates configuration. Use `deploy` to create AWS resources.
@@ -99,6 +102,7 @@ poetry run ccwb deploy [stack] [options]
 3. **monitoring** - OpenTelemetry collector on ECS Fargate (optional)
 4. **dashboard** - CloudWatch dashboard for usage metrics (optional)
 5. **analytics** - Kinesis Firehose and Athena for analytics (optional)
+6. **codebuild** - AWS CodeBuild for Windows binary builds (optional, only if enabled during init)
 
 ### `test` - Test Package
 
@@ -135,35 +139,195 @@ poetry run ccwb package [options]
 
 **Options:**
 
-- `--target-platform <platform>` - Target platform for binary: macos, linux, or all (default: "all")
+- `--target-platform <platform>` - Target platform for binary (default: "all")
+  - `macos` - Build for current macOS architecture
+  - `macos-arm64` - Build for Apple Silicon Macs
+  - `macos-intel` - Build for Intel Macs (uses Rosetta on ARM Macs)
+  - `linux` - Build for Linux (native, current architecture)
+  - `linux-x64` - Build for Linux x64 using Docker
+  - `linux-arm64` - Build for Linux ARM64 using Docker
+  - `windows` - Build for Windows (uses CodeBuild - requires enabling during init)
+  - `all` - Build for all available platforms
+- `--distribute` - Upload package and generate distribution URL
+- `--expires-hours <hours>` - Distribution URL expiration in hours (with --distribute) [default: "48"]
+- `--profile <name>` - Configuration profile to use [default: "default"]
 
 **What it does:**
 
-- Builds PyInstaller executable from authentication code
+- Builds Nuitka executable from authentication code
 - Creates configuration file with:
   - OIDC provider settings
   - Identity Pool ID from deployed stack
   - Credential storage method (keyring or session)
   - Selected Claude model and cross-region profile
   - Source region for model inference
-- Generates installer script
+- Generates installer script (install.sh for Unix, install.bat for Windows)
 - Creates user documentation
+- Optionally uploads to S3 and generates presigned URL (with --distribute)
+
+**Platform Support (Hybrid Build System):**
+
+- **macOS**: Uses PyInstaller with architecture-specific builds
+  - ARM64: Native build on Apple Silicon Macs (works on all Macs)
+  - Intel: **Optional** - requires x86_64 Python environment on ARM Macs
+  - Universal: Requires both architectures' Python libraries (not currently automated)
+- **Linux**: Uses PyInstaller in Docker containers
+  - x64: Uses linux/amd64 Docker platform
+  - ARM64: Uses linux/arm64 Docker platform
+  - Docker Desktop handles architecture emulation automatically
+- **Windows**: Uses Nuitka via AWS CodeBuild (if enabled during init)
+  - Automated builds take 12-15 minutes
+  - Requires CodeBuild to be enabled during `init`
+  - Will be skipped if CodeBuild is not enabled
+
+**Intel Mac Build Setup (Optional):**
+
+To enable Intel builds on Apple Silicon Macs (optional):
+
+```bash
+# Step 1: Install x86_64 Homebrew (if not already installed)
+arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Step 2: Install x86_64 Python
+arch -x86_64 /usr/local/bin/brew install [email protected]
+
+# Step 3: Create x86_64 virtual environment
+arch -x86_64 /usr/local/bin/python3.12 -m venv ~/venv-x86
+
+# Step 4: Install required packages
+arch -x86_64 ~/venv-x86/bin/pip install pyinstaller boto3 keyring
+```
+
+**Behavior when Intel environment is not set up:**
+
+- For `--target-platform=all`: Skips Intel builds with a note, builds all other platforms
+- For `--target-platform=macos-intel`: Shows instructions for optional setup, skips the build
+- The package process continues successfully without Intel binaries
+- ARM64 binaries can be distributed to all Mac users (Intel and Apple Silicon)
+
+**Graceful Fallback Behavior:**
+
+The package command is designed to handle missing optional components gracefully:
+
+- **Intel Mac builds**: Skipped if x86_64 Python environment is not available on ARM Macs
+- **Windows builds**: Skipped if CodeBuild was not enabled during `init`
+- **Linux builds**: Skipped if Docker is not available
+- **At least one platform must build successfully** for the package command to succeed
+
+This ensures that packaging always works, even if some optional platforms are not available.
+
+**Output files:**
+
+- `credential-process-<platform>` - Authentication executable
+  - `credential-process-macos-arm64` - macOS Apple Silicon
+  - `credential-process-macos-intel` - macOS Intel
+  - `credential-process-linux-x64` - Linux x64
+  - `credential-process-linux-arm64` - Linux ARM64
+  - `credential-process-windows.exe` - Windows x64
+- `otel-helper-<platform>` - OTEL helper (if monitoring enabled)
+- `config.json` - Configuration
+- `install.sh` - Unix installer script (auto-detects architecture)
+- `install.bat` - Windows installer script
+- `README.md` - Installation instructions
 - Includes Claude Code telemetry settings (if monitoring enabled)
 - Configures environment variables for model selection (ANTHROPIC_MODEL, ANTHROPIC_SMALL_FAST_MODEL)
 
 **Output structure:**
 
 ```
 dist/
-├── credential-process-macos    # macOS authentication executable
-├── credential-process-linux    # Linux authentication executable
-├── otel-helper-macos          # macOS OTEL helper (if monitoring enabled)
-├── otel-helper-linux          # Linux OTEL helper (if monitoring enabled)
-├── config.json                # Configuration
-├── install.sh                 # Installation script (auto-detects platform)
-├── README.md                  # User instructions
+├── credential-process-macos-arm64     # macOS ARM64 executable
+├── credential-process-macos-intel     # macOS Intel executable
+├── credential-process-linux-x64       # Linux x64 executable
+├── credential-process-linux-arm64     # Linux ARM64 executable
+├── credential-process-windows.exe     # Windows x64 executable
+├── otel-helper-macos-arm64           # macOS ARM64 OTEL helper
+├── otel-helper-macos-intel           # macOS Intel OTEL helper
+├── otel-helper-linux-x64             # Linux x64 OTEL helper
+├── otel-helper-linux-arm64           # Linux ARM64 OTEL helper
+├── otel-helper-windows.exe           # Windows OTEL helper
+├── config.json                       # Configuration
+├── install.sh                        # Unix installer (auto-detects architecture)
+├── install.bat                       # Windows installer
+├── README.md                         # User instructions
 └── .claude/
-    └── settings.json          # Telemetry settings (optional)
+    └── settings.json                 # Telemetry settings (optional)
+```
+
+### `builds` - List and Manage CodeBuild Builds
+
+Shows recent Windows binary builds and their status.
+
+```bash
+poetry run ccwb builds [options]
+```
+
+**Options:**
+
+- `--limit <n>` - Number of builds to show (default: "10")
+- `--project <name>` - CodeBuild project name (default: auto-detect)
+- `--status <id>` - Check status of a specific build by ID
+
+**What it does:**
+
+- Lists recent CodeBuild builds for Windows binaries
+- Shows build status, duration, and completion time
+- Provides console links to view full build logs
+- Monitors in-progress builds
+
+**Note:** This command requires CodeBuild to be enabled during the `init` process. If CodeBuild was not enabled, you'll need to re-run `init` and enable Windows build support.
+
+**Example output:**
+
+```
+Recent Windows Builds
+
+| Build ID | Status | Started | Duration |
+|----------|--------|---------|----------|
+| project:abc123 | SUCCEEDED | 2024-08-26 10:15 | 12m 34s |
+| project:def456 | IN_PROGRESS | 2024-08-26 10:30 | - |
+```
+
+### `distribute` - Create Distribution URLs
+
+Creates secure presigned URLs for package distribution.
+
+```bash
+poetry run ccwb distribute [options]
+```
+
+**Options:**
+
+- `--expires-hours <hours>` - URL expiration time in hours (1-168) [default: "48"]
+- `--get-latest` - Retrieve the latest distribution URL
+- `--profile <name>` - Configuration profile to use [default: "default"]
+
+**What it does:**
+
+- Uploads built packages to S3
+- Generates presigned URLs for secure distribution
+- Stores URLs in Parameter Store for team access
+- No AWS credentials required for end users
+
+**Distribution workflow:**
+
+1. Build packages: `poetry run ccwb package --target-platform=all`
+2. Create distribution: `poetry run ccwb distribute`
+3. Share the generated URL with developers
+4. Developers download and run installer without AWS access
+
+**Example:**
+
+```bash
+# Build and distribute
+poetry run ccwb package --target-platform=all --distribute
+
+# Or separately
+poetry run ccwb package --target-platform=all
+poetry run ccwb distribute --expires-hours=72
+
+# Get existing URL
+poetry run ccwb distribute --get-latest
 ```
 
 ### `status` - Check Deployment Status