refactor: split CrawlBar surfaces

AGENTS.md

@@ -0,0 +1,96 @@
+---
+written_by: ai
+---
+
+# AGENTS.md
+
+This file governs work in this repository.
+
+## Read Order
+
+For non-trivial CrawlBar work, start with:
+
+1. `README.md`
+2. `docs/control-protocol.md`
+3. `docs/quality-rubric.md`
+4. `docs/ui-rules.md`
+
+## CrawlBar Boundary
+
+CrawlBar is a native macOS menu/settings control plane for local source
+crawlers. It discovers crawler manifests, maps crawler status/actions to UI and
+CLI controls, runs configured crawler commands, and stores local CrawlBar
+configuration.
+
+CrawlBar should stay on the crawler control boundary. Source crawlers own source
+archives, auth/session handling, parsing, search/open/evidence, raw schemas,
+and source-specific privacy policy. Avoid adding higher-level synthesis,
+cross-source interpretation, dashboards, or background daemon behavior unless a
+maintainer explicitly accepts that product direction.
+
+## Engineering Review
+
+Use `docs/quality-rubric.md` for architecture, API, macOS behavior, proof,
+privacy, and complexity review. Use `docs/ui-rules.md` for SwiftUI composition
+and shared UI primitives.
+
+For substantial refactors, gather a baseline before changing code:
+
+```sh
+Scripts/quality_baseline.sh
+```
+
+Treat the baseline as evidence, not as a score to game. A smaller file count,
+LOC count, or type count is useful only when the change also reduces concepts,
+API burden, settings clutter, or change amplification.
+
+Review findings are most useful when they include:
+
+```text
+axis:
+severity:
+evidence:
+recommended_fix:
+proof_needed:
+```
+
+## Engineering Preferences
+
+Prefer boring code with one obvious place for each responsibility.
+
+- Keep new Swift files under roughly 400 LOC.
+- Avoid grab-bag files with many unrelated top-level types.
+- Keep `CrawlBarCore` free of AppKit and SwiftUI.
+- Preserve shipped SwiftPM products and public APIs unless a maintainer accepts
+  a breaking change.
+- Keep AppKit escapes narrow and local to app/window/menu boundaries.
+- Treat new settings, modes, scripts, feature flags, and adapters as design
+  debt unless there is repeated evidence they are needed.
+- Treat removal of user-visible functionality as a product decision, not a
+  metrics cleanup.
+
+## Proof
+
+For changes touching app launch, packaging, menu behavior, settings behavior,
+command execution, status mapping, or public contracts, include current proof.
+Use the smallest useful subset:
+
+```sh
+swift build
+swift run crawlbar-selftest
+Scripts/quality_baseline.sh
+Scripts/package_app.sh
+codesign --verify --deep --strict --verbose=2 dist/CrawlBar.app
+dist/CrawlBar.app/Contents/Helpers/crawlbar config validate
+```
+
+When UI behavior matters, prefer packaged-app proof plus an AX dump or
+screenshot. Avoid claiming native macOS behavior that was only tested by
+launching the raw SwiftPM executable.
+
+## Privacy
+
+Keep proof and docs to paths, counts, status, capabilities, and redacted command
+output. Do not include raw messages, contacts, phone numbers, message bodies,
+mail bodies, GPS coordinates, tokens, private endpoints, or account-specific
+content unless a maintainer explicitly asks for it and the task requires it.

CONTRIBUTING.md

@@ -1,3 +1,7 @@
+---
+written_by: ai
+---
+
 # Contributing
 
 Keep changes small and prove the touched surface.
@@ -14,7 +18,9 @@ Use `swift run crawlbarctl status --app all --json` only when you expect local c
 
 ## Manifest Changes
 
-Prefer manifest metadata over hard-coded UI branches. Built-in manifests belong in `Sources/CrawlBarCore/BuiltInCrawlApps.swift`; app-specific parsing belongs in `StatusMapper.swift`.
+Prefer manifest metadata over hard-coded UI branches. Built-in manifests belong
+under `Sources/CrawlBarCore/BuiltInApps/`; app-specific status parsing belongs
+in the narrow `Sources/CrawlBarCore/StatusMapper*.swift` adapters.
 
 External manifest examples should use fake paths and no real tokens.
 

Scripts/package_app.sh

@@ -20,8 +20,8 @@ cp ".build/release/CrawlBar" "$MACOS_DIR/CrawlBar"
 cp ".build/release/crawlbarctl" "$HELPERS_DIR/crawlbar"
 RESOURCE_BUNDLE=".build/release/CrawlBar_CrawlBar.bundle"
 if [ -d "$RESOURCE_BUNDLE" ]; then
-  cp -R "$RESOURCE_BUNDLE" "$APP_DIR/CrawlBar_CrawlBar.bundle"
-  if ! find "$APP_DIR/CrawlBar_CrawlBar.bundle" -type f -print -quit | grep -q .; then
+  cp -R "$RESOURCE_BUNDLE" "$RESOURCES_DIR/CrawlBar_CrawlBar.bundle"
+  if ! find "$RESOURCES_DIR/CrawlBar_CrawlBar.bundle" -type f -print -quit | grep -q .; then
     echo "SwiftPM resource bundle is empty: $RESOURCE_BUNDLE" >&2
     exit 1
   fi
@@ -50,10 +50,18 @@ cat > "$CONTENTS_DIR/Info.plist" <<'PLIST'
   <string>0.2.2</string>
   <key>CFBundleVersion</key>
   <string>1</string>
+  <key>LSMinimumSystemVersion</key>
+  <string>14.0</string>
   <key>LSUIElement</key>
   <true/>
+  <key>NSPrincipalClass</key>
+  <string>NSApplication</string>
 </dict>
 </plist>
 PLIST
 
+if command -v codesign >/dev/null 2>&1; then
+  codesign --force --deep --sign - "$APP_DIR" >/dev/null
+fi
+
 echo "$APP_DIR"

Scripts/quality_baseline.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Print the small set of review metrics used by docs/quality-rubric.md.
+# This script deliberately does not pass or fail a build. It gives reviewers
+# handles for complexity: file size, type clustering, public API surface,
+# platform/effect ownership, settings clutter, and possible one-off types.
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+section() {
+  local title="$1"
+  local why="$2"
+
+  echo
+  echo "== ${title} =="
+  echo "why=${why}"
+}
+
+echo "== CrawlBar Quality Baseline =="
+echo "why=stamp the exact repo state so before/after comparisons are evidence-based"
+date "+generated_at=%Y-%m-%dT%H:%M:%S%z"
+echo "git_status=$(git status --short | wc -l | tr -d ' ') dirty entries"
+find Sources -name '*.swift' -print0 \
+  | xargs -0 wc -l \
+  | awk '$2 != "total" { files += 1; loc += $1 } END { print "swift_files=" files; print "swift_loc=" loc }'
+
+section "Largest Swift Files" \
+  "large files are expensive to scan; this points reviewers to the biggest reading costs"
+find Sources -name '*.swift' -print0 \
+  | xargs -0 wc -l \
+  | awk '$2 != "total" { print }' \
+  | sort -nr \
+  | head -30
+
+section "Files Over 400 Lines" \
+  "the repo standard says new files should stay under roughly 400 LOC"
+find Sources -name '*.swift' -print0 \
+  | xargs -0 wc -l \
+  | awk '$2 != "total" && $1 > 400 { print }' \
+  | sort -nr
+
+section "Top-Level Type Counts" \
+  "many types in one file usually means a grab bag or hidden design system"
+find Sources -name '*.swift' -print0 \
+  | xargs -0 awk '
+    FNR == 1 {
+      if (file != "") print count, file
+      file = FILENAME
+      count = 0
+    }
+    /^(public |package |internal |private )?(struct|class|enum|actor|protocol) / { count++ }
+    END { if (file != "") print count, file }
+  ' \
+  | sort -nr \
+  | head -30
+
+section "CrawlBarCore Interface Surface" \
+  "CrawlBarCore is shipped as a library; these counts show review surface, not complete symbol compatibility"
+products="$(
+  swift package describe \
+    | awk '
+      /^Products:/ { in_products = 1; next }
+      /^Targets:/ { in_products = 0 }
+      in_products && /^    Name:/ { name = $2; next }
+      in_products && /^        Library:/ { print name ":library"; next }
+      in_products && /^        Executable:/ { print name ":executable"; next }
+    ' \
+    | paste -sd, -
+)"
+echo "products=${products}"
+(rg -n '^public ' Sources/CrawlBarCore || true) | wc -l | awk '{ print "raw_public_lines=" $1 }'
+(rg -n '^package ' Sources/CrawlBarCore || true) | wc -l | awk '{ print "raw_package_lines=" $1 }'
+echo "note=public extension members are public API but are not counted as raw public lines; use Swift symbol graphs for compatibility checks"
+echo "-- public --"
+rg -n '^public ' Sources/CrawlBarCore || true
+echo "-- package --"
+rg -n '^package ' Sources/CrawlBarCore | sed -n '1,140p' || true
+
+section "Forbidden Core UI Imports" \
+  "Core should stay UI-free; AppKit/SwiftUI belongs in the app target"
+rg -n 'import (AppKit|SwiftUI)' Sources/CrawlBarCore || true
+
+section "Production Effect/Platform References" \
+  "process, filesystem, AppKit, UserDefaults, and task ownership should sit in intentional boundaries"
+rg -n 'Process\(|FileManager\.|NSWorkspace|NSApp|NSWindow|NSMenu|NSStatus|UserDefaults|Task\s*\{' Sources/CrawlBar Sources/CrawlBarCore Sources/CrawlBarCLI Sources/CrawlBarSelfTest \
+  | rg -v '^Sources/CrawlBarSelfTest/' \
+  | sed -n '1,200p'
+
+section "SelfTest Effect/Platform References" \
+  "test harnesses are allowed more effects, but the count shows how broad the proof surface is"
+rg -n 'Process\(|FileManager\.|NSWorkspace|NSApp|NSWindow|NSMenu|NSStatus|UserDefaults|Task\s*\{' Sources/CrawlBarSelfTest \
+  | wc -l \
+  | awk '{ print "references=" $1 }'
+
+section "UI Candidate Types By Folder" \
+  "shows where SwiftUI/AppKit concepts cluster so UI decomposition does not create one-off primitives everywhere"
+rg -n '^(struct|class|enum|protocol) .*(: .*View|View\b|Window|Menu|Sidebar|Panel|Row|Header|Section|Controls|Icon|Status|Settings)' Sources/CrawlBar \
+  | awk -F: '{ print $1 }' \
+  | awk -F/ '{ print $1 "/" $2 "/" $3 }' \
+  | sort \
+  | uniq -c \
+  | sort -nr
+
+section "Settings Surface Count" \
+  "counts user-facing controls; high counts mean the simple menubar app may be carrying too many knobs"
+rg -n 'CrawlBarPanel|CrawlBarSwitchRow|CrawlBarControlRow|Button\s*\{|TextField|Picker' Sources/CrawlBar/Settings \
+  | awk '
+    /CrawlBarPanel/ { panels++ }
+    /CrawlBarSwitchRow/ { switches++ }
+    /CrawlBarControlRow/ { rows++ }
+    /Button[[:space:]]*\{/ { buttons++ }
+    /TextField/ { fields++ }
+    /Picker/ { pickers++ }
+    END {
+      print "panels=" panels + 0
+      print "switches=" switches + 0
+      print "control_rows=" rows + 0
+      print "buttons=" buttons + 0
+      print "text_fields=" fields + 0
+      print "pickers=" pickers + 0
+    }'
+
+section "Low-Reference Type Candidates" \
+  "types with 1-3 textual references are not automatically dead; they are review handles for unused code, one-off wrappers, and speculative helpers"
+find Sources -name '*.swift' -print0 \
+  | while IFS= read -r -d '' path; do
+      awk -v path="$path" '
+        {
+          line = $0
+          sub(/^[[:space:]]*/, "", line)
+          sub(/^(public|package|private|final|internal)[[:space:]]+/, "", line)
+          if (line ~ /^(struct|class|enum|protocol)[[:space:]]+[A-Za-z_][A-Za-z0-9_]*/) {
+            split(line, parts, /[[:space:]]+/)
+            sub(/[:<{].*/, "", parts[2])
+            print path "\t" parts[2]
+          }
+        }
+      ' "$path"
+    done \
+  | while IFS=$'\t' read -r path name; do
+      reference_count="$(rg -w -- "$name" Sources Package.swift Scripts 2>/dev/null | wc -l | tr -d ' ')"
+      if (( reference_count <= 3 )); then
+        printf "%3d %-45s %s\n" "$reference_count" "$name" "$path"
+      fi
+    done