Add macOS app and Finder badges for workspace status

.claude/CLAUDE.md

@@ -7,35 +7,45 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Build & Test Commands
 
 ```bash
-cargo build                        # Debug build
-cargo build --release              # Optimized release build (LTO, stripped)
-cargo test --all-features -- --test-threads=1 # Run CI-equivalent tests
-cargo test <test_name>             # Run a single test by name
-cargo test --test integration_test # Run only integration tests
-cargo fmt --all -- --check         # Check formatting
-cargo clippy --all-targets --all-features -- -D warnings # Lint (zero warnings enforced)
+cargo build --workspace                                # Debug build
+cargo build --release --workspace                      # Optimized release (LTO, stripped)
+cargo test --workspace                                 # Run all tests
+cargo test -p git-same-core                            # Tests for the engine crate only
+cargo test -p git-same                                 # Tests for the CLI crate only
+cargo test --workspace <test_name>                     # Run a single test by name
+cargo test -p git-same --test integration_test         # Run only integration tests
+cargo fmt --all -- --check                             # Check formatting
+cargo clippy --workspace --all-targets --all-features -- -D warnings   # Lint
 ```
 
-Logging is controlled via `GISA_LOG` env var (e.g., `GISA_LOG=debug cargo run -- sync`).
+Logging is controlled via `GISA_LOG` env var (e.g., `GISA_LOG=debug cargo run -p git-same -- sync`).
 
 ## Architecture
 
 Git-Same is a Rust CLI + TUI tool that discovers GitHub org/repo structures and mirrors them locally with parallel cloning and syncing.
 
-**Binary aliases:** Cargo defines the primary `git-same` binary at `src/main.rs`. Installers create `gitsame`, `gitsa`, and `gisa` symlinks from `toolkit/packaging/binary-aliases.txt`.
+**Workspace layout:** the project is a Cargo workspace with two member crates:
+
+- `git-same-core` (`crates/git-same-core/`) — the engine library. No UI dependencies (no clap, ratatui, crossterm). Holds discovery, clone/sync, IPC, status scanning, and shared types.
+- `git-same` (lives at `crates/git-same-cli/` on disk; the directory name and package name intentionally diverge so `cargo install git-same` keeps working as it has since pre-3.x) — the CLI binary + TUI. Depends on `git-same-core`. Owns clap parsing, the TUI screens, the setup wizard, and command handlers. The produced binary is named `git-same` (per `[[bin]]` name) so installer aliases (`gisa`, `gitsa`, `gitsame`) and `target/release/git-same` are unchanged from the pre-split layout.
+
+**Binary aliases:** `git-same`, `gitsame`, `gitsa`, `gisa` — all resolve to the binary built from `crates/git-same-cli/src/main.rs`.
 
 **Dual mode:** Running with a subcommand (`gisa sync`) uses the CLI path. Running without a subcommand (`gisa`) launches the interactive TUI.
 
-**CLI flow:** CLI parsing (`src/cli.rs`) → `main.rs` routes to command handler → handler orchestrates modules.
+**macOS host strategy:** Two macOS host apps coexist. The Tauri host (`crates/git-same-app/`, Svelte + TypeScript + Vite) is the primary GUI shipped via the cask. The SwiftUI host (`macos/GitSameSwiftApp/`) is intentionally kept as a fallback per the Phase C plan's "perfect macOS feel" escape hatch (`.context/plans/phase-c-tauri-app.md` §2). **Do not delete `macos/GitSameSwiftApp/` without explicit approval** — this overrides the migration plan's earlier "delete in Phase C" instruction.
 
-**Commands:** `init`, `setup`, `sync`, `status`, `scan`, `workspace {list,default}`, `reset`.
+**CLI flow:** CLI parsing (`crates/git-same-cli/src/cli.rs`) → `main.rs` routes to command handler → handler orchestrates engine modules from `git-same-core`.
 
-### Core modules
+**Commands:** `init`, `setup`, `sync`, `status`, `scan`, `workspace {list,default}`, `reset`, `monitor` (alias: `daemon`), `refresh`.
+
+**Why `monitor` is a CLI subcommand and not solely a Tauri-host responsibility:** the LaunchAgent invokes `gisa monitor --foreground`, non-cask installs (`cargo install`, the homebrew formula) ship only the binary, `--status` / `--stop` are the supported debugging surface, and a future Linux file-manager extension would talk to the same `gisa monitor` over the same Unix socket. The CLI handler is a thin shim (~140 lines); the loop itself lives in `git-same-core::monitor`.
+
+### Engine modules (`crates/git-same-core/src/`)
 
-- **`app/`** — Top-level entry points: `app/cli/` runs the CLI subcommand path, `app/tui/` boots the interactive TUI. `main.rs` dispatches to one or the other based on whether a subcommand was given
-- **`commands/`** — Per-subcommand handlers (`init`, `setup`, `sync_cmd`, `status`, `scan`, `reset`, `workspace`) plus shared `support/` helpers
-- **`workflows/`** — Cross-cutting orchestration shared by CLI and TUI: `sync_workspace` (discover + clone + fetch/pull) and `status_scan` (walk local repos, collect git status)
 - **`auth/`** — `gh_cli.rs` obtains GitHub API tokens via `gh auth token`. `ssh.rs` exposes low-level SSH probing primitives (`SshProbeResult`, `parse_ssh_probe_output`) used by clone-time diagnostics
+- **`workflows/`** — Cross-cutting orchestration: `sync_workspace` (discover + clone + fetch/pull) and `status_scan` (walk local repos, collect git status)
+- **`monitor/`**: Long-running monitor loop (periodic scan + Unix-socket server) used by `gisa monitor` and reusable by host apps like the Tauri GUI
 - **`config/`** — TOML config parser. Default: `~/.config/git-same/config.toml`. Top-level keys: `workspaces`, `default_workspace`, plus `[clone]` and `[filters]` sections
 - **`discovery.rs`** — `DiscoveryOrchestrator` coordinates repo discovery via providers, applies filters, builds `ActionPlan` (what to clone vs sync)
 - **`operations/clone.rs`** — `CloneManager` handles concurrent cloning (configurable 1–32, default 4)
@@ -45,14 +55,24 @@ Git-Same is a Rust CLI + TUI tool that discovers GitHub org/repo structures and
 - **`cache/`** — `discovery.rs` provides `DiscoveryCache` (TTL-based validity, persisted at `<workspace-root>/.git-same/cache.json`); `sync_history.rs` records sync runs at `<workspace-root>/.git-same/sync-history.json`
 - **`domain/`** — Domain primitives, currently `repo_path_template.rs` for resolving `{org}/{repo}` style structures
 - **`infra/storage/`** — Storage abstractions for workspace-local persistence
-- **`setup/`** — Setup wizard state machine, shared between the CLI `setup` command and the TUI workspace-setup screen
+- **`ipc/`** — Monitor ↔ Finder-extension interface (`status_file.rs`, `unix_socket.rs`)
+- **`api/`** — Higher-level service helpers built on top of git/provider/config (e.g. `RepoScanService`)
 - **`errors/`** — Custom error hierarchy: `AppError`, `GitError`, `ProviderError` with `suggested_action()` methods
 - **`output/`** — `printer.rs` for verbosity-aware text output; `progress/` holds the `indicatif` progress bars (`CloneProgressBar`, `SyncProgressBar`, `DiscoveryProgressBar`)
-- **`types/repo.rs`** — Core data types: `Repo`, `Org`, `ActionPlan`, `OpResult`, `OpSummary`
+- **`types/`** — Core data types: `Repo`, `Org`, `ActionPlan`, `OpResult`, `OpSummary`, plus `RepoEntry`/`SyncHistoryEntry` (lifted out of the TUI in B0.1)
 - **`checks.rs`** — System/runtime checks (presence of `git`, `gh`, auth status, SSH access via `check_ssh_github_access`)
+
+### CLI / TUI modules (`crates/git-same-cli/src/`)
+
+- **`app/`** — Top-level entry points: `app/cli/` runs the CLI subcommand path, `app/tui/` boots the interactive TUI. `main.rs` dispatches to one or the other based on whether a subcommand was given
+- **`commands/`** — Per-subcommand handlers (`init`, `setup`, `sync_cmd`, `status`, `scan`, `reset`, `workspace`, `monitor`, `refresh`) plus shared `support/` helpers
+- **`setup/`** — Setup wizard state machine + ratatui rendering, shared between the CLI `setup` command and the TUI workspace-setup screen (gated by the `tui` feature)
+- **`tui/`** — Ratatui-based TUI (gated by the `tui` feature)
+- **`cli.rs`** — clap derive types
 - **`banner.rs`** — CLI banner rendering
+- **`bin/gen_completions.rs`, `bin/gen_manpage.rs`** — Release-only helpers gated by the `release-tools` feature
 
-### TUI module (`src/tui/`, feature-gated behind `tui`)
+### TUI module (`crates/git-same-cli/src/tui/`, feature-gated behind `tui`)
 
 Elm architecture: `app.rs` = Model, `screens/` = View, `handler.rs` = Update.
 
@@ -71,6 +91,26 @@ Elm architecture: `app.rs` = Model, `screens/` = View, `handler.rs` = Update.
 - **Channel-based TUI updates:** Backend operations send `BackendMessage` through `mpsc::UnboundedSender<AppEvent>`, processed by the TUI event loop
 - **Arrow-only navigation:** All directional movement uses arrow keys only (`←` `↑` `↓` `→`). No vim-style `j`/`k`/`h`/`l` letter navigation. Display hints use `[←] [↑] [↓] [→] Move`.
 
+## FinderSync extension gotchas (macOS)
+
+Three non-obvious traps in `macos/GitSameBadges/`. Each one silently breaks badges with no error log — the extension self-check still shows green.
+
+1. **Boot-volume alias paths.** macOS auto-creates `/Volumes/<boot-volume-name>` as a symlink to `/`. Finder presents home-folder URLs with that prefix (`/Volumes/Manuel-SSD-4TB/Users/m/...`) and gates `requestBadgeIdentifier` on the URL matching an entry in `directoryURLs`. `Principal.updateMonitoredDirectories()` must register both the canonical and the alias-prefixed form of every watched root, otherwise the callback fires for nothing.
+
+2. **macOS 26.4 sandbox rendering regression.** Both `NSImage.lockFocus()` and `NSImage(size:flipped:drawingHandler:)` produce empty/invalid pixel data when called inside a sandboxed FinderSync extension on 26.4. Symptom: Finder reserves the badge slot (folder icons shift) but no glyph renders. Workaround: build badges from SF Symbols (`NSImage(systemSymbolName:)` with palette `SymbolConfiguration`). SF Symbols are pre-rendered by macOS, no per-process drawing context required. Apple's own `r.circle.fill`/`o.circle.fill`/`u.circle.fill` are what `BadgeManager.symbolBadge` uses.
+
+3. **Google Drive's FinderSync poisons the badge-rendering pipeline.** When `com.google.drivefs.finderhelper.findersync` is enabled, peer FinderSync extensions render no badge image even after Finder calls `setBadgeIdentifier`. Confirmed in this environment: badges only began appearing after the user disabled Google Drive in System Settings → Login Items & Extensions. Other peers (Keka, Synology, Dropbox) coexist fine. There is no code fix; document the workaround and surface it in the in-app self-check if you can.
+
+`scan_roots` and `show_ambient`: defaults are `["~"]` / `false`. Never re-enable `show_ambient = true` with `~` in `scan_roots` — Finder refuses to call `requestBadgeIdentifier` on extensions whose `directoryURLs` contain the home folder (separate issue from the three above).
+
+## Workspace folder branding (macOS)
+
+The host paints a custom icon onto every workspace root via `NSWorkspace.setIcon` (wrapped in `crates/git-same-core/src/macos/folder_icon.rs`) so Finder shows it in the sidebar, column, list, icon, and Get Info views. A FinderSync extension can never replicate this — it only exposes corner badges. The icon is `crates/git-same-core/assets/workspace-folder.icns`, embedded via `include_bytes!` and regenerable via `bash toolkit/icons/build-workspace-folder-icns.sh`.
+
+Lifecycle: painted by `core::setup::save_workspace` and `app::commands::save_workspace`, reapplied by the monitor (`monitor::run::reapply_workspace_folder_icons`) on every full scan if the `Icon\r` is missing, and stripped by `cli::commands::reset` and `app::commands::delete_workspace`. Opt out globally with `[ui] custom_folder_icon = false`.
+
+**Finder Sidebar snapshot caveat.** `LSSharedFileList` captures a per-item icon bitmap into `~/Library/Application Support/com.apple.sharedfilelist/com.apple.LSSharedFileList.FavoriteItems.sfl3` at the moment the user drags a folder into Favorites. That snapshot is frozen — repainting the folder's `Icon\r` does **not** update the sidebar. The only refresh path is manual: right-click the stale sidebar item → Remove from Sidebar, then drag the folder back from a Finder window into Favorites. Don't waste time looking for a programmatic refresh API; the framework doesn't expose one, and the recommended workaround used by Synology / Dropbox is the same drag-and-drop.
+
 ## Formatting
 
 `rustfmt.toml`: `max_width = 100`, `tab_spaces = 4`, edition 2021.
@@ -90,20 +130,22 @@ The test file contains `use super::*;` and all `#[test]` / `#[tokio::test]` func
 
 **Do not** write inline `#[cfg(test)] mod tests { ... }` blocks — always use separate `_tests.rs` files.
 
-**Integration tests** remain in `tests/integration_test.rs`.
+**Integration tests** live in `crates/git-same-cli/tests/integration_test.rs`. They spawn the binary via `env!("CARGO_BIN_EXE_git-same")` (compile-time path), so they always run against the freshly built CLI binary at the workspace `target/`.
+
+**Cross-crate test helpers:** `Repo::test()` in `git-same-core` is gated on `cfg(any(test, feature = "test-utils"))`. The CLI crate enables the `test-utils` feature in its `[dev-dependencies]` so its tests can call the helper without exposing it in production builds.
 
 ## CI/CD Workflows
 
 All workflows are `workflow_dispatch` (manual trigger) in `.github/workflows/`:
 
 | Workflow | Purpose | Trigger |
 |----------|---------|---------|
-| `S1-Test-CI.yml` | fmt, clippy, tests, release build dry-run, coverage, alias drift, workflow secret-safety, audit | Manual dispatch |
-| `S2-Release-GitHub.yml` | Gated GitHub release assets for targets in `toolkit/packaging/targets.txt` (currently 4 targets) | Manual dispatch (select tag) |
-| `S3-Publish-Homebrew.yml` | Publish Homebrew cask + formula-cli | Manual dispatch (select tag) |
-| `S4-Publish-Crates.yml` | Publish crates.io package | Manual dispatch (select tag) |
+| `S1-Test-CI.yml` | fmt, clippy, test, build dry-run, coverage, audit | Manual dispatch |
+| `S2-Release-GitHub.yml` | Full CI + cross-compile 4 targets (per `toolkit/packaging/targets.txt`) + GitHub Release | Manual dispatch (select tag) |
+| `S3-Publish-Homebrew.yml` | Download release tarballs and render `git-same-cli` formula + `git-same` cask templates into `zaai-com/homebrew-tap` | Manual dispatch (select tag) |
+| `S4-Publish-Crates.yml` | Two-stage publish to crates.io: `git-same-core` → poll until indexed → `git-same` | Manual dispatch (select tag) |
 
-S2 gates release asset builds on tests, coverage, alias drift, audit, and workflow secret-safety checks.
+S2 runs all S1 jobs (test, coverage, audit) as gates before building release artifacts.
 
 ## Specs & Docs
 

.github/workflows/S1-Test-CI.yml

@@ -43,10 +43,10 @@ jobs:
         run: cargo +${{ matrix.rust }} fmt --all -- --check
 
       - name: Clippy
-        run: cargo +${{ matrix.rust }} clippy --all-targets --all-features -- -D warnings
+        run: cargo +${{ matrix.rust }} clippy --workspace --all-targets --all-features -- -D warnings
 
       - name: Run tests
-        run: cargo +${{ matrix.rust }} test --all-features -- --test-threads=1
+        run: cargo +${{ matrix.rust }} test --workspace --all-features -- --test-threads=1
 
   build:
     name: Build (${{ matrix.target }})
@@ -81,7 +81,43 @@ jobs:
           prefix-key: v1-rust-no-bin
 
       - name: Build release
-        run: cargo +stable build --release --target ${{ matrix.target }}
+        run: cargo +stable build --release -p git-same --target ${{ matrix.target }}
+
+  tauri-debug-build:
+    name: Tauri App Debug Build
+    needs: [test]
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Install Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Enable pnpm
+        run: corepack enable pnpm
+
+      - name: Verify entitlements parity
+        run: bash toolkit/packaging/macos/check-entitlements-parity.sh
+
+      - name: Install frontend dependencies
+        run: pnpm --dir crates/git-same-app/ui install --frozen-lockfile
+
+      - name: Build frontend
+        run: pnpm --dir crates/git-same-app/ui build
+
+      - name: Build Tauri app binary
+        run: |
+          cd crates/git-same-app
+          ui/node_modules/.bin/tauri build --debug --no-bundle
 
   coverage:
     name: Code Coverage
@@ -114,7 +150,7 @@ jobs:
         run: cargo +stable tarpaulin --all-features --workspace --timeout 120 --out xml --engine llvm
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@v7
         with:
           use_oidc: true
           fail_ci_if_error: false
@@ -161,7 +197,7 @@ jobs:
             }
             in_bin && /^[[:space:]]*required-features[[:space:]]*=/ { has_req=1 }
             END { flush(); print default_count, default_name }
-          ' Cargo.toml)"
+          ' crates/git-same-cli/Cargo.toml)"
           if [ "${DEFAULT_COUNT:-0}" -ne 1 ]; then
             echo "ERROR: Cargo.toml has ${DEFAULT_COUNT:-0} default [[bin]] entries, expected 1"; exit 1
           fi

.github/workflows/S2-Release-GitHub.yml

@@ -40,10 +40,10 @@ jobs:
         run: cargo +${{ matrix.rust }} fmt --all -- --check
 
       - name: Clippy
-        run: cargo +${{ matrix.rust }} clippy --all-targets --all-features -- -D warnings
+        run: cargo +${{ matrix.rust }} clippy --workspace --all-targets --all-features -- -D warnings
 
       - name: Run tests
-        run: cargo +${{ matrix.rust }} test --all-features -- --test-threads=1
+        run: cargo +${{ matrix.rust }} test --workspace --all-features -- --test-threads=1
 
   coverage:
     name: Code Coverage
@@ -76,7 +76,7 @@ jobs:
         run: cargo +stable tarpaulin --all-features --workspace --timeout 120 --out xml --engine llvm
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@v7
         with:
           use_oidc: true
           fail_ci_if_error: false
@@ -115,7 +115,7 @@ jobs:
             }
             in_bin && /^[[:space:]]*required-features[[:space:]]*=/ { has_req=1 }
             END { flush(); print default_count, default_name }
-          ' Cargo.toml)"
+          ' crates/git-same-cli/Cargo.toml)"
           if [ "${DEFAULT_COUNT:-0}" -ne 1 ]; then
             echo "ERROR: Cargo.toml has ${DEFAULT_COUNT:-0} default [[bin]] entries, expected 1"; exit 1
           fi
@@ -267,7 +267,7 @@ jobs:
           prefix-key: v1-rust-no-bin
 
       - name: Build
-        run: cargo +stable build --release --target ${{ matrix.target }}
+        run: cargo +stable build --release -p git-same --target ${{ matrix.target }}
 
       - name: Resolve version from tag
         if: startsWith(github.ref, 'refs/tags/')
@@ -388,7 +388,7 @@ jobs:
           find artifacts -type f -exec cp {} release-assets/ \;
 
       - name: Create/update release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2.6.2
         with:
           files: release-assets/*
         env: