Merge pull request #443 from aaddrick/refactor/build-split-for-codeowners

refactor: split build.sh by subsystem + add CODEOWNERS

Author: aaddrick

.claude/agents/electron-linux-specialist.md

@@ -72,7 +72,7 @@ The project uses a three-layer interception pattern to fix Electron behavior on
 
 ```
 package.json (main: "frame-fix-entry.js")
-    └── frame-fix-entry.js (generated by build.sh)
+    └── frame-fix-entry.js (generated by scripts/patches/app-asar.sh)
         ├── require('./frame-fix-wrapper.js')   ← Intercepts require('electron')
         └── require('./<original-main>')         ← Loads the real app
 ```
@@ -94,29 +94,42 @@ package.json (main: "frame-fix-entry.js")
 
 ```
 claude-desktop-debian/
-├── build.sh                              # Main build script with all patches
+├── build.sh                              # Build orchestrator (sources scripts/patches/*.sh)
 ├── scripts/
-│   ├── frame-fix-wrapper.js              # BrowserWindow/Menu interceptor
+│   ├── _common.sh                        # Shared shell utilities
+│   ├── setup/                            # Host detection, deps, download
+│   ├── patches/                          # sed/regex patches on minified JS (per-subsystem)
+│   │   ├── _common.sh                    # extract_electron_variable, fix_native_theme_references
+│   │   ├── app-asar.sh                   # Asar repack, frame-fix wrapper injection
+│   │   ├── titlebar.sh
+│   │   ├── tray.sh                       # Tray menu handler + icon selection
+│   │   ├── quick-window.sh
+│   │   ├── claude-code.sh
+│   │   └── cowork.sh                     # Largest — cowork linux patching
+│   ├── staging/                          # Post-patch file staging
+│   ├── packaging/                        # deb/rpm/AppImage scripts
+│   ├── frame-fix-wrapper.js              # BrowserWindow/Menu interceptor (copied in by patches/app-asar.sh)
 │   ├── claude-native-stub.js             # Native module stubs for Linux
-│   └── launcher-common.sh               # Wayland/X11 detection, Electron args
+│   └── launcher-common.sh                # Wayland/X11 detection, Electron args
 ├── .github/workflows/                    # CI/CD pipelines
 └── resources/                            # Desktop entries, icons
-# Note: frame-fix-entry.js is generated by build.sh at build time
+# Note: frame-fix-entry.js is generated by scripts/patches/app-asar.sh at build time
 ```
 
-### Patching Functions in build.sh
-
-| Function | Purpose |
-|----------|---------|
-| `patch_app_asar()` | Orchestrates all patches: frame fix, titlebar, tray, theme, menu |
-| `patch_titlebar_detection()` | Removes `!` from `if(!isWindows && isMainWindow)` to enable titlebar |
-| `extract_electron_variable()` | Finds the minified variable name for `require("electron")` |
-| `fix_native_theme_references()` | Fixes wrong `*.nativeTheme` references to use the correct electron var |
-| `patch_tray_menu_handler()` | Makes tray rebuild async, adds mutex guard, DBus cleanup delay, startup skip |
-| `patch_tray_icon_selection()` | Switches from hardcoded template to theme-aware icon selection |
-| `patch_menu_bar_default()` | Changes `!!menuBarEnabled` to `menuBarEnabled !== false` |
-| `patch_quick_window()` | Adds `blur()` before `hide()` to fix submit issues |
-| `patch_linux_claude_code()` | Adds Linux platform detection for Claude Code binary |
+### Patching Functions (scripts/patches/*.sh)
+
+| Function | File | Purpose |
+|----------|------|---------|
+| `patch_app_asar()` | `scripts/patches/app-asar.sh` | Extracts asar, injects frame-fix wrapper, repacks |
+| `patch_titlebar_detection()` | `scripts/patches/titlebar.sh` | Removes `!` from `if(!isWindows && isMainWindow)` to enable titlebar |
+| `extract_electron_variable()` | `scripts/patches/_common.sh` | Finds the minified variable name for `require("electron")` |
+| `fix_native_theme_references()` | `scripts/patches/_common.sh` | Fixes wrong `*.nativeTheme` references to use the correct electron var |
+| `patch_tray_menu_handler()` | `scripts/patches/tray.sh` | Makes tray rebuild async, adds mutex guard, DBus cleanup delay, startup skip |
+| `patch_tray_icon_selection()` | `scripts/patches/tray.sh` | Switches from hardcoded template to theme-aware icon selection |
+| `patch_menu_bar_default()` | `scripts/patches/tray.sh` | Changes `!!menuBarEnabled` to `menuBarEnabled !== false` |
+| `patch_quick_window()` | `scripts/patches/quick-window.sh` | Adds `blur()` before `hide()` to fix submit issues |
+| `patch_linux_claude_code()` | `scripts/patches/claude-code.sh` | Adds Linux platform detection for Claude Code binary |
+| `patch_cowork_linux()` | `scripts/patches/cowork.sh` | Cowork daemon auto-launch, VM lifecycle, sandbox wiring (largest patch set) |
 
 ### Environment Variables
 
@@ -232,7 +245,7 @@ This agent provides Electron domain expertise; `cdd-code-simplifier` handles she
 
 ### Providing Guidance on Patches
 
-When advising on new patches to minified JavaScript in `build.sh`:
+When advising on new patches to minified JavaScript (in `scripts/patches/*.sh`):
 1. Identify the Electron API or behavior being patched
 2. Explain the expected behavior on Linux vs Windows/macOS
 3. Suggest the regex pattern approach (dynamic extraction, whitespace handling)
@@ -245,7 +258,7 @@ When advising on new patches to minified JavaScript in `build.sh`:
 
 When asked to analyze or fix an Electron/Linux integration issue:
 
-1. **Identify the layer**: Is this a wrapper issue (frame-fix-wrapper.js), a build patch (build.sh sed patterns), a launcher issue (launcher-common.sh), or a native stub issue (claude-native-stub.js)?
+1. **Identify the layer**: Is this a wrapper issue (frame-fix-wrapper.js), a build patch (scripts/patches/*.sh sed patterns), a launcher issue (launcher-common.sh), or a native stub issue (claude-native-stub.js)?
 
 2. **Check platform scope**: Does this affect all Linux, only Wayland, only X11, or specific desktop environments?
 

.claude/agents/issue-triage.md

@@ -48,7 +48,7 @@ Use this when you're not confident enough to triage automatically. Examples: sec
 ## INVESTIGATION RULES
 
 ### All bugs are ours to fix
-This project's goal is to take a working Anthropic product and make it work on Linux. Every bug is something we can investigate and potentially patch. Check `build.sh` patches first for bugs in patched areas (cowork, tray, frame, platform checks, window decorations). Read the relevant `patch_` function and trace what it modifies. If a behavior difference exists between the Windows/macOS app and our Linux build, that's a gap in our patching, not someone else's problem.
+This project's goal is to take a working Anthropic product and make it work on Linux. Every bug is something we can investigate and potentially patch. Check `scripts/patches/*.sh` first for bugs in patched areas (`cowork.sh`, `tray.sh`, `app-asar.sh`, `titlebar.sh`, `quick-window.sh`, `claude-code.sh`). Read the relevant `patch_` function and trace what it modifies. If a behavior difference exists between the Windows/macOS app and our Linux build, that's a gap in our patching, not someone else's problem.
 
 ### Verify before stating
 Only state facts you verified by reading actual code or running commands. Never claim code exists, functions behave a certain way, or patterns match without finding them in the source. If you cannot find evidence, say so explicitly rather than speculating.
@@ -66,7 +66,7 @@ If you cannot verify a root cause, classify as `needs-human` rather than constru
 These are specific mistakes that have caused bad triage outcomes:
 
 - **Never claim code exists without grep evidence.** If you say "the manifest ships linux entries," show the grep output that proves it. (#329: triage claimed linux manifest entries existed when they don't)
-- **Never dismiss a bug as someone else's problem.** Every issue is ours to investigate. Check `build.sh` patches first since our patches are often the cause. (#329: triage blamed CDN when our checksum patch was wrong)
+- **Never dismiss a bug as someone else's problem.** Every issue is ours to investigate. Check `scripts/patches/*.sh` first since our patches are often the cause. (#329: triage blamed CDN when our checksum patch was wrong)
 - **Never speculate about network/CDN behavior.** Use `curl -sI URL | head -5` to check. Don't guess HTTP status codes.
 - **Never propose patches to code paths that aren't reached.** Trace the actual execution flow before suggesting a fix. (#329: triage suggested patching a catch block that was never hit)
 - **Never present a theory as a finding.** Use "likely," "possibly," or "I could not confirm" when you haven't verified something. Reserve declarative statements for verified facts.
@@ -79,15 +79,15 @@ When investigating bugs, search these files based on the issue category:
 
 | Category | Files to check |
 |----------|---------------|
-| Build failures | `build.sh`, `.github/workflows/ci.yml`, `build-amd64.yml`, `build-arm64.yml` |
-| Window/frame issues | `frame-fix-wrapper.js`, `frame-fix-entry.js`, search reference source for `BrowserWindow` |
-| Tray icon issues | `build.sh` (search `patch_tray`), reference source for `Tray`, `StatusNotifier` |
-| Packaging (deb) | `build.sh` (search `build_deb`), `scripts/` directory |
-| Packaging (rpm) | `build.sh` (search `build_rpm`), `scripts/` directory |
-| Packaging (AppImage) | `build.sh` (search `build_appimage`) |
+| Build failures | `build.sh` (orchestrator), `scripts/setup/`, `.github/workflows/ci.yml`, `build-amd64.yml`, `build-arm64.yml` |
+| Window/frame issues | `scripts/frame-fix-wrapper.js`, `scripts/patches/titlebar.sh`, `scripts/patches/app-asar.sh`, reference source for `BrowserWindow` |
+| Tray icon issues | `scripts/patches/tray.sh`, reference source for `Tray`, `StatusNotifier` |
+| Packaging (deb) | `scripts/packaging/deb.sh`, `scripts/launcher-common.sh` |
+| Packaging (rpm) | `scripts/packaging/rpm.sh`, `scripts/launcher-common.sh` |
+| Packaging (AppImage) | `scripts/packaging/appimage.sh`, `scripts/launcher-common.sh` |
 | Packaging (nix) | `nix/` directory, `flake.nix` |
-| Cowork/MCP issues | `cowork-vm-service.js`, `build.sh` (search `patch_cowork`) |
-| Native module issues | `claude-native-stub.js`, `build.sh` (search `native`) |
+| Cowork/MCP issues | `scripts/cowork-vm-service.js`, `scripts/patches/cowork.sh`, `scripts/staging/cowork-resources.sh` |
+| Native module issues | `scripts/claude-native-stub.js`, `scripts/patches/cowork.sh` (node-pty install) |
 | CI/workflow issues | `.github/workflows/` directory |
 
 The **reference source** (`/tmp/ref-source/app-extracted/`) contains the beautified Claude Desktop JavaScript. Use it to understand the original behavior that the build script patches or wraps. Key files:

.github/CODEOWNERS

@@ -0,0 +1,84 @@
+# CODEOWNERS — per-subsystem review ownership
+#
+# Rules match top-to-bottom; the LAST matching rule wins.
+# Layout:
+#   1. Default owner
+#   2. Explicit @aaddrick assignments grouped by logical role
+#      (listed even where redundant, so the intent is visible to
+#      future collaborators scanning the file)
+#   3. Cowork and Nix overrides at the bottom so they stick
+#
+# Each listed user must be a repo collaborator (Settings →
+# Collaborators) with at least read access, or GitHub silently
+# ignores them.
+
+# ---- Default: aaddrick owns anything not explicitly claimed ----
+*                                       @aaddrick
+
+# ---- Build orchestration ----
+# The top-level dispatcher and shared shell utilities.
+/build.sh                               @aaddrick
+/scripts/_common.sh                     @aaddrick
+
+# ---- Setup (host detection, dependencies, upstream download) ----
+/scripts/setup/                         @aaddrick
+
+# ---- Electron patches / minified JS ----
+# The regex-driven patches applied to the unpacked app.asar, plus
+# the frame-fix wrapper and native-binding stubs that ride along.
+/scripts/patches/_common.sh             @aaddrick
+/scripts/patches/app-asar.sh            @aaddrick
+/scripts/patches/titlebar.sh            @aaddrick
+/scripts/patches/claude-code.sh         @aaddrick
+/scripts/frame-fix-wrapper.js           @aaddrick
+/scripts/claude-native-stub.js          @aaddrick
+
+# ---- Linux desktop integration ----
+# Tray, menu bar, and quick-window behavior on Wayland/X11.
+/scripts/patches/tray.sh                @aaddrick
+/scripts/patches/quick-window.sh        @aaddrick
+
+# ---- Staging (non-cowork) ----
+# Electron copy-out, icon processing, locales, SSH helpers.
+/scripts/staging/electron.sh            @aaddrick
+/scripts/staging/icons.sh               @aaddrick
+/scripts/staging/locales.sh             @aaddrick
+/scripts/staging/ssh-helpers.sh         @aaddrick
+
+# ---- Packaging formats (deb, rpm, AppImage) + runtime launcher ----
+/scripts/packaging/                     @aaddrick
+/scripts/launcher-common.sh             @aaddrick
+
+# ---- Distribution & signing ----
+# APT/DNF repo publishing, GPG signing, release automation.
+# Most of this lives in workflows — gh-pages branch content isn't
+# reachable via CODEOWNERS.
+/.github/workflows/                     @aaddrick
+/scripts/resolve-download-url.py        @aaddrick
+
+# ---- CI / other GitHub metadata ----
+/.github/                               @aaddrick
+
+# ---- Docs & style ----
+/README.md                              @aaddrick
+/CLAUDE.md                              @aaddrick
+/STYLEGUIDE.md                          @aaddrick
+/docs/                                  @aaddrick
+
+#===============================================================================
+# Overrides — listed last so their assignments stick against the
+# broad globs above (/docs/, /.github/, etc.)
+#===============================================================================
+
+# ---- Cowork ----
+# Electron-side patching, staging, daemon, and integration tests.
+/scripts/patches/cowork.sh              @RayCharlizard
+/scripts/staging/cowork-resources.sh    @RayCharlizard
+/scripts/cowork-vm-service.js           @RayCharlizard
+/tests/cowork-*.bats                    @RayCharlizard
+/docs/cowork-*.md                       @RayCharlizard
+
+# ---- Nix ----
+/flake.nix                              @typedrat
+/flake.lock                             @typedrat
+/nix/                                   @typedrat

.github/workflows/check-claude-version.yml

@@ -68,13 +68,13 @@ jobs:
           echo "arm64_url=$ARM64_URL" >> $GITHUB_OUTPUT
           echo "claude_version=$CLAUDE_VERSION" >> $GITHUB_OUTPUT
 
-      - name: Get current URLs from build.sh
+      - name: Get current URLs from scripts/setup/detect-host.sh
         id: current_urls
         run: |
-          # Extract current URLs from build.sh
-          # The build.sh case statement uses x86_64/aarch64 patterns with claude_download_url on the next line
-          CURRENT_AMD64_URL=$(grep -E "x86_64\)" -A1 build.sh | grep -oP "claude_download_url='\\K[^']+")
-          CURRENT_ARM64_URL=$(grep -E "aarch64\)" -A1 build.sh | grep -oP "claude_download_url='\\K[^']+")
+          # Extract current URLs from scripts/setup/detect-host.sh
+          # The scripts/setup/detect-host.sh case statement uses x86_64/aarch64 patterns with claude_download_url on the next line
+          CURRENT_AMD64_URL=$(grep -E "x86_64\)" -A1 scripts/setup/detect-host.sh | grep -oP "claude_download_url='\\K[^']+")
+          CURRENT_ARM64_URL=$(grep -E "aarch64\)" -A1 scripts/setup/detect-host.sh | grep -oP "claude_download_url='\\K[^']+")
 
           echo "Current AMD64 URL: $CURRENT_AMD64_URL"
           echo "Current ARM64 URL: $CURRENT_ARM64_URL"
@@ -132,35 +132,35 @@ jobs:
             echo "update_needed=false" >> $GITHUB_OUTPUT
           fi
 
-      - name: Update build.sh with new URLs
+      - name: Update scripts/setup/detect-host.sh with new URLs
         if: steps.check_update.outputs.update_needed == 'true'
         run: |
           NEW_AMD64_URL="${{ steps.resolve_urls.outputs.amd64_url }}"
           NEW_ARM64_URL="${{ steps.resolve_urls.outputs.arm64_url }}"
           CURRENT_AMD64_URL="${{ steps.current_urls.outputs.current_amd64_url }}"
           CURRENT_ARM64_URL="${{ steps.current_urls.outputs.current_arm64_url }}"
 
-          echo "Updating build.sh with new URLs..."
+          echo "Updating scripts/setup/detect-host.sh with new URLs..."
 
           # Update AMD64 URL
           if [ -n "$NEW_AMD64_URL" ] && [ "$NEW_AMD64_URL" != "$CURRENT_AMD64_URL" ]; then
             echo "Updating AMD64 URL..."
             # Escape special characters for sed
             ESCAPED_CURRENT=$(printf '%s\n' "$CURRENT_AMD64_URL" | sed 's/[[\.*^$()+?{|]/\\&/g')
             ESCAPED_NEW=$(printf '%s\n' "$NEW_AMD64_URL" | sed 's/[&/\]/\\&/g')
-            sed -i "s|$ESCAPED_CURRENT|$ESCAPED_NEW|g" build.sh
+            sed -i "s|$ESCAPED_CURRENT|$ESCAPED_NEW|g" scripts/setup/detect-host.sh
           fi
 
           # Update ARM64 URL (if we have a new one)
           if [ -n "$NEW_ARM64_URL" ] && [ "$NEW_ARM64_URL" != "$CURRENT_ARM64_URL" ]; then
             echo "Updating ARM64 URL..."
             ESCAPED_CURRENT=$(printf '%s\n' "$CURRENT_ARM64_URL" | sed 's/[[\.*^$()+?{|]/\\&/g')
             ESCAPED_NEW=$(printf '%s\n' "$NEW_ARM64_URL" | sed 's/[&/\]/\\&/g')
-            sed -i "s|$ESCAPED_CURRENT|$ESCAPED_NEW|g" build.sh
+            sed -i "s|$ESCAPED_CURRENT|$ESCAPED_NEW|g" scripts/setup/detect-host.sh
           fi
 
-          echo "Updated build.sh URLs:"
-          grep "claude_download_url=" build.sh
+          echo "Updated scripts/setup/detect-host.sh URLs:"
+          grep "claude_download_url=" scripts/setup/detect-host.sh
 
       - name: Compute SRI hashes for Nix
         if: steps.check_update.outputs.update_needed == 'true'
@@ -189,30 +189,30 @@ jobs:
             echo "arm64_sha256=$ARM64_HEX" >> $GITHUB_OUTPUT
           fi
 
-      - name: Update build.sh SHA-256 checksums
+      - name: Update scripts/setup/detect-host.sh SHA-256 checksums
         if: steps.check_update.outputs.update_needed == 'true'
         run: |
           AMD64_SHA256="${{ steps.nix_hashes.outputs.amd64_sha256 }}"
           ARM64_SHA256="${{ steps.nix_hashes.outputs.arm64_sha256 }}"
 
-          echo "Updating build.sh SHA-256 checksums..."
+          echo "Updating scripts/setup/detect-host.sh SHA-256 checksums..."
 
           # Update AMD64 hash (in x86_64 case block)
           if [ -n "$AMD64_SHA256" ]; then
             sed -i "/x86_64)/,/;;/{
               s/claude_exe_sha256='[^']*'/claude_exe_sha256='$AMD64_SHA256'/
-            }" build.sh
+            }" scripts/setup/detect-host.sh
           fi
 
           # Update ARM64 hash (in aarch64 case block)
           if [ -n "$ARM64_SHA256" ]; then
             sed -i "/aarch64)/,/;;/{
               s/claude_exe_sha256='[^']*'/claude_exe_sha256='$ARM64_SHA256'/
-            }" build.sh
+            }" scripts/setup/detect-host.sh
           fi
 
-          echo "Updated build.sh checksums:"
-          grep "claude_exe_sha256=" build.sh
+          echo "Updated scripts/setup/detect-host.sh checksums:"
+          grep "claude_exe_sha256=" scripts/setup/detect-host.sh
 
       # VM bundle checksums removed — Patch 4 now injects empty linux
       # file arrays since the VM backend is non-functional on Linux.
@@ -268,10 +268,10 @@ jobs:
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
           # Check if there are changes to commit
-          if git diff --quiet build.sh nix/claude-desktop.nix; then
-            echo "No changes to build.sh or nix/claude-desktop.nix"
+          if git diff --quiet scripts/setup/detect-host.sh nix/claude-desktop.nix; then
+            echo "No changes to scripts/setup/detect-host.sh or nix/claude-desktop.nix"
           else
-            git add build.sh nix/claude-desktop.nix
+            git add scripts/setup/detect-host.sh nix/claude-desktop.nix
             git commit -m "$(cat <<COMMIT_MSG
           Update Claude Desktop download URLs to version $CLAUDE_VERSION