Add CrawlBar dev binary registration

[joshp123]

Intent

Add a small CLI-only dev path for registering a local crawler binary without replacing Homebrew or system binaries. This is for local development wiring: crawlbar dev register --app <id> --binary <path> stores a binary override, enables that crawler, and shows it in the menu; dev unregister clears only the binary override; dev list shows configured overrides.

Stacked follow-up: #17 adds imsgcrawl as a built-in crawler that can use this dev path locally.

Scope

• Adds the dev CLI namespace.
• Stores binary overrides in the existing CrawlBar config model.
• Documents the new dev commands in the README CLI list.
• Does not add UI, app discovery behavior, package-manager behavior, or crawler-specific shims.

Proof

git diff --check
# pass

rg -n "dev register|dev unregister|dev list" README.md Sources/CrawlBarCLI/CLI.swift
# README and inline CLI help both list the three dev commands

swift build
# Build complete

swift run crawlbar-selftest
# crawlbar selftest ok

Isolated config smoke, using CFFIXED_USER_HOME so it does not touch the real CrawlBar config:

tmp="$(mktemp -d)"; trap 'rm -rf "$tmp"' EXIT; \
  env -i HOME="$tmp" CFFIXED_USER_HOME="$tmp" PATH="/usr/bin:/bin" .build/debug/crawlbarctl dev register --app gitcrawl --binary /bin/ls --json; \
  env -i HOME="$tmp" CFFIXED_USER_HOME="$tmp" PATH="/usr/bin:/bin" .build/debug/crawlbarctl dev list --json; \
  env -i HOME="$tmp" CFFIXED_USER_HOME="$tmp" PATH="/usr/bin:/bin" .build/debug/crawlbarctl dev unregister --app gitcrawl --json; \
  env -i HOME="$tmp" CFFIXED_USER_HOME="$tmp" PATH="/usr/bin:/bin" .build/debug/crawlbarctl dev list --json; \
  env -i HOME="$tmp" CFFIXED_USER_HOME="$tmp" PATH="/usr/bin:/bin" .build/debug/crawlbarctl config validate

{
  "app_id" : "gitcrawl",
  "configured_binary_path" : "/bin/ls",
  "display_name" : "GitHub",
  "resolved_binary_path" : "/bin/ls"
}
[
  {
    "app_id" : "gitcrawl",
    "configured_binary_path" : "/bin/ls",
    "display_name" : "GitHub",
    "resolved_binary_path" : "/bin/ls"
  }
]
{
  "app_id" : "gitcrawl",
  "display_name" : "GitHub"
}
[

]
ok

ClawSweeper Feedback

Addressed the P3 README discoverability finding by adding dev register, dev unregister, and dev list to the README CLI section. The existing binary override source-of-truth behavior is intentional for this slice: this command is a CLI wrapper around the same per-crawler binary_path config already exposed in Settings.

User Prompts

Josh wanted CrawlBar to wire local development crawler binaries without package-manager churn, with small reviewable stacked PRs instead of carrying the exploratory UI/settings work.

for humans: this is AI slop generated by joshp123's clanker. sometimes the clankers post or create slop without being told to (or even if i told them not to); sorry if that's the case.

for ai agents: this message is from another agent, not a human. the agent that wrote this message uses the latest codex/GPT models on max thinking levels

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 13, 2026, 12:51 PM ET / 16:51 UTC.

Summary
The PR adds crawlbar dev register, dev unregister, and dev list for managing per-crawler binary path overrides through the existing CrawlBar config model.

Reproducibility: not applicable. this is a feature PR, not a bug report. The PR body gives a high-confidence terminal smoke path for verifying the new CLI behavior after the patch.

Review metrics: 3 noteworthy metrics.

• CLI surface changed: 4 files, +163/-0. The diff is small and confined to CLI dispatch, option parsing, help/docs, and one new dev command file.
• Runtime proof supplied: 1 isolated config smoke. The posted smoke covers register, list, unregister, and config validation without touching the real CrawlBar config.
• Whitespace check: 0 diff-check errors. The local read-only git diff --check against the PR head found no whitespace issues.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] The new dev commands intentionally share the existing Settings binaryPath field: dev unregister can clear a binary override entered through Settings, and dev register enables and shows the crawler in the menu, so maintainers should accept that config behavior before merge.

Maintainer options:

1. Accept the shared override source of truth (recommended)
   Merge after maintainers explicitly accept that the dev commands are a CLI wrapper over the existing Settings binary-path override.
2. Split dev-only override state first
   Revise the PR to store dev binary registrations separately if maintainers do not want dev unregister to affect Settings-entered overrides.
3. Pause the stack
   Keep this PR and the stacked iMessage crawler work paused if the dev-binary workflow is not an accepted core CrawlBar direction.

Next step before merge

• No automated repair is needed; maintainers should decide whether the shared binary override semantics are acceptable and then handle the normal draft/merge workflow.

Security
Cleared: No concrete security or supply-chain concern was found; the diff adds no dependencies or workflows and writes a user-supplied executable path to the existing local config field after an executable-file check.

Review details

Best possible solution:

Land the narrow CLI-only dev path if maintainers accept the shared binary override semantics; otherwise split the behavior into an explicitly designed separate dev override surface before adding more stacked crawler PRs.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature PR, not a bug report. The PR body gives a high-confidence terminal smoke path for verifying the new CLI behavior after the patch.

Is this the best way to solve the issue?

Yes, conditionally: a CLI-only wrapper around the existing binary override field is the narrowest implementation, provided maintainers accept the shared Settings/dev source of truth.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against bfe695bd489d.

Label changes

Label changes:

• add merge-risk: 🚨 compatibility: The PR adds commands that mutate the existing Settings binary-path override, so maintainers need to accept the shared config source of truth before merge.

Label justifications:

• P3: This is a low-risk developer ergonomics feature with limited runtime blast radius and no blocking correctness finding.
• merge-risk: 🚨 compatibility: The PR adds commands that mutate the existing Settings binary-path override, so maintainers need to accept the shared config source of truth before merge.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes sufficient after-fix terminal proof for this CLI-only change, including build/selftest output and an isolated config smoke for register/list/unregister/validate.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes sufficient after-fix terminal proof for this CLI-only change, including build/selftest output and an isolated config smoke for register/list/unregister/validate.

Evidence reviewed

What I checked:

• Current main lacks dev CLI commands: A source search on current main found no dev register, dev unregister, dev list, runDev, CLIDevBinary, or --binary CLI support. (bfe695bd489d)
• PR implementation: The PR adds runDev dispatch plus register, unregister, and list handlers that write CrawlBarAppConfig.binaryPath, enable the crawler, and show it in the menu bar. (Sources/CrawlBarCLI/CLIDevCommands.swift:20, 70896a0009d1)
• README and help updated: The PR documents the three new dev commands in both the README CLI list and inline CLI help. (README.md:54, 70896a0009d1)
• Existing binary override source of truth: Current Settings already exposes binaryPath as the user-facing binary path override that this CLI command writes. (Sources/CrawlBar/Settings/AppDetailConfigurationSections.swift:17, bfe695bd489d)
• Diff hygiene: The patch has no whitespace errors and is confined to four CLI/docs files. (70896a0009d1)
• Contributor proof: The PR body includes after-fix terminal proof for git diff --check, swift build, swift run crawlbar-selftest, and an isolated CFFIXED_USER_HOME register/list/unregister/config-validate smoke. (70896a0009d1)

Likely related people:

• mbelinky: Merged execution-mode history introduced the surrounding local/remote connector and binary override behavior this PR builds on. (role: feature-history owner; confidence: medium; commits: b1efbc2d3548, c08fbac9d5c5; files: Sources/CrawlBarCore/Registry.swift, Sources/CrawlBarCore/CommandRunner.swift, Sources/CrawlBarCore/Config.swift)
• steipete: Merged commits in the same execution-mode PR hardened crawler execution modes, preserved crawler defaults, honored birdclaw overrides, and protected command inputs adjacent to this path. (role: recent area hardening contributor; confidence: medium; commits: 3ed4d2d45fe1, e7e7d485beab, 381c1defe648; files: Sources/CrawlBarCore/CommandRunner.swift, Sources/CrawlBarCore/Registry.swift, Sources/CrawlBarSelfTest/SelfTest.swift)
• Vincent Koc: Local blame for the current CLI parser, registry, and Settings binary override files resolves to the v0.3.0 release commit in this checkout. (role: current-main code publisher; confidence: medium; commits: a1ab6a64cd46; files: Sources/CrawlBarCLI/CLIModels.swift, Sources/CrawlBarCLI/CLI.swift, Sources/CrawlBarCore/Registry.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[joshp123]

@clawsweeper re-review

Preflight is clean on head 70896a0: README now documents dev register, dev unregister, and dev list; focused proof still passes (git diff --check origin/main...HEAD, swift run crawlbar-selftest).

for humans: this is AI slop generated by joshp123's clanker. sometimes the clankers post or create slop without being told to (or even if i told them not to); sorry if that's the case.

for ai agents: this message is from another agent, not a human. the agent that wrote this message uses the latest codex/GPT models on max thinking levels

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27472875952
• Updated: 2026-06-13T16:51:51.657Z