Add agent-friendly Beeper install script; fix README platform support

[Miyamura80]

What

Adds scripts/install-beeper.sh, a one-command installer that wires Beeper into the Edison Watch MCP gateway, and corrects a stale "macOS only" claim in the README.

The install script

Thin orchestrator over the beeper and edison-stdiod CLIs plus two REST calls. install runs the full flow idempotently:

deps -> headless Beeper Server -> stdiod login+install -> register beeper child -> bind token -> print MCP URL

End-to-end path it sets up:

AI client --MCP--> Edison Gateway --WS tunnel--> edison-stdiod --stdio--> npx @beeper/desktop-mcp --HTTP :23373--> Beeper Server --> WhatsApp / Telegram / LinkedIn

Built to be driven by an agent or a human:

• Non-interactive by default; every input is a flag or an UPPER_SNAKE env var. Prompts only run behind --interactive.
• --dry-run, --yes, --json, --verbose, --install-deps.
• resource+verb subcommands: install, doctor, status, network add|list, mcp-url, uninstall.
• Every --help carries runnable examples; missing inputs fail fast with the exact fix.
• Returns data on success (mcp_url, auth header, ready-to-paste claude mcp add ...).

Example:

./scripts/install-beeper.sh install --install-deps --yes \
  --ew-api-key ew_live_abc --beeper-token bpr_xyz \
  --networks whatsapp,telegram,linkedin

Validated by actually running it

Exercised on Linux against the real edison-stdiod binary (built from this checkout) plus a stubbed beeper. Confirmed every flag the script calls matches the binary's --help (login, install, server add/list/remove), and that login writes a correct config.toml. Running it surfaced and fixed several defects: an IFS leak that mangled dry-run logging, a token-bind curl printing http 000000 with no timeout, a dry-run abort when no token was supplied, and a raw daemon backtrace plus mid-flow set -e abort on install failure (now a clean actionable message).

Known seams (need a live backend / Mac to verify)

Three integration points are wrapped defensively and marked, not faked:

1. Headless Beeper token minting (documented path is the GUI; --beeper-token overrides).
2. Edison Watch account bootstrap (currently requires --ew-api-key).
3. The token-to-child bind route POST /api/v1/servers/<name>/env is a best guess (overridable via EW_SERVER_ENV_PATH); non-fatal with a manual fallback if it 404s. The clean alternative is a small edison-stdiod server env subcommand.

README fix

The WARNING claimed the daemon is "macOS only," but src/platform/ implements supervisor integration for macOS (LaunchAgent), Linux (systemd --user), and Windows (Scheduled Task); only other OSes hit the runtime stub. Updated the WARNING, the quickstart install comment, and the CLI table to match the code, while noting macOS is the most exercised target.

Test plan

• bash -n + repo AI-writing hook pass
• edison-stdiod builds; script flags match its --help
• dry-run, --json, fail-fast, and clean-failure paths exercised on Linux
• End-to-end on macOS with the real beeper CLI and a live Edison backend

🤖 Generated with Claude Code

---

Generated by Claude Code

---

Summary by cubic

Adds a one-command, agent-friendly installer to wire Beeper into the Edison Watch MCP gateway, and updates the README for macOS, Linux, and Windows support. Headless setup reuses the Beeper CLI token, validates the Desktop API, and cleanly handles conflicts and step-up reauth when registering the tunnel child.

• New Features

  • scripts/install-beeper.sh: installs deps, starts headless beeper, logs in and installs edison-stdiod, registers npx @beeper/desktop-mcp (uses --arg=-y), binds the Beeper token, and prints the MCP URL or --json.
  • Headless token reuse: pulls accessToken from ~/.beeper/targets/*.json, small JSON files, and macOS Keychain; validates via the local OAuth userinfo; probes 127.0.0.1, [::1], and localhost on ports 23373–23378; adds a token subcommand.
  • Agent-friendly and idempotent: flags/env for all inputs; --dry-run, --yes, --json, --verbose, --install-deps; subcommands: install, doctor, status, network add|list, mcp-url, token, uninstall; TTY-aware colors auto-disable; Linux allowed with a warning.
  • README: fixes platform note to macOS (LaunchAgent), Linux (systemd --user), and Windows (Scheduled Task).

• Bug Fixes

  • Reliable Beeper detection via a real Desktop API probe (handles IPv6-only binds).
  • Dependency installs: require consent + confirm; validate installer presence and that tools land on PATH; quiet Homebrew with HOMEBREW_NO_AUTO_UPDATE=1, HOMEBREW_NO_ENV_HINTS=1, --quiet.
  • Early Edison key check: validates GET /api/v1/servers; clear 401/403 and demo-backend hint; warns on unreachable backends.
  • server add hardening: use --arg=-y; don’t abort on non-zero so conflict handler runs; self-heal 409 by remove+re-add; detect and explain STEP_UP_REQUIRED with dashboard unblock guidance; suppress Rust backtraces on failure.
  • Token bind: confirmed POST /api/v1/servers/{name}/env, 30s timeout; clear 401/403 vs 000; non-fatal with dashboard fallback; passes BEEPER_API_URL/BEEPER_DESKTOP_BASE_URL.
  • Runtime: fix IFS leak in network adds; honor --dry-run in probes and token step.

^{Written for commit 97cb8ff. Summary will update on new commits.}

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[cubic-dev-ai]

3 issues found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="README.md">

<violation number="1" location="README.md:116">
P3: The README now advertises Linux and Windows supervisors, but `edison-stdiod install --help` still describes `install` as a macOS LaunchAgent command. Updating the CLI help with this documentation change would keep the advertised interface and the runnable help output consistent.</violation>
</file>

<file name="scripts/install-beeper.sh">

<violation number="1" location="scripts/install-beeper.sh:84">
P2: `uninstall --dry-run` fails with the non-interactive confirmation error instead of previewing the uninstall. Treating dry-run as an automatic confirmation would preserve the documented “change nothing” preview behavior.</violation>

<violation number="2" location="scripts/install-beeper.sh:289">
P2: `install --networks ...` can block in the default agent/non-interactive mode because `beeper accounts add` is invoked without checking `--interactive`. Gating this flow behind `--interactive` or wiring the documented non-browser auth flow would prevent an unattended installer from hanging.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: install --networks ... can block in the default agent/non-interactive mode because beeper accounts add is invoked without checking --interactive. Gating this flow behind --interactive or wiring the documented non-browser auth flow would prevent an unattended installer from hanging.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/install-beeper.sh, line 289:

<comment>`install --networks ...` can block in the default agent/non-interactive mode because `beeper accounts add` is invoked without checking `--interactive`. Gating this flow behind `--interactive` or wiring the documented non-browser auth flow would prevent an unattended installer from hanging.</comment>

<file context>
@@ -0,0 +1,452 @@
+  for net in $nets; do
+    [ -z "$net" ] && continue
+    log "network: adding '$net' (follow the QR / code prompt in this terminal)"
+    run beeper accounts add "$net"
+  done
+}
</file context>

[cubic-dev-ai]

P2: uninstall --dry-run fails with the non-interactive confirmation error instead of previewing the uninstall. Treating dry-run as an automatic confirmation would preserve the documented “change nothing” preview behavior.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/install-beeper.sh, line 84:

<comment>`uninstall --dry-run` fails with the non-interactive confirmation error instead of previewing the uninstall. Treating dry-run as an automatic confirmation would preserve the documented “change nothing” preview behavior.</comment>

<file context>
@@ -0,0 +1,452 @@
+
+confirm() {
+  [ "$ASSUME_YES" -eq 1 ] && return 0
+  [ "$INTERACTIVE" -eq 0 ] && die "refusing to run a confirming action non-interactively: $1" \
+    "pass --yes to proceed, or --dry-run to preview"
+  printf '%s [y/N] ' "$1" >&2; read -r ans; [ "$ans" = "y" ] || [ "$ans" = "Y" ]
</file context>

[cubic-dev-ai]

P3: The README now advertises Linux and Windows supervisors, but edison-stdiod install --help still describes install as a macOS LaunchAgent command. Updating the CLI help with this documentation change would keep the advertised interface and the runnable help output consistent.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At README.md, line 116:

<comment>The README now advertises Linux and Windows supervisors, but `edison-stdiod install --help` still describes `install` as a macOS LaunchAgent command. Updating the CLI help with this documentation change would keep the advertised interface and the runnable help output consistent.</comment>

<file context>
@@ -112,7 +113,7 @@ TLDR: `edison-stdiod --help` (and `edison-stdiod <command> --help` for any subco
 | --- | --- |
 | `login` | Persist credentials + backend URL to `~/.config/edison-stdiod/config.toml` (mode `0600`). Merges on re-run, so you can rotate the API key without re-supplying the backend URL. |
-| `install` | Register the OS supervisor unit (macOS LaunchAgent) so the daemon starts at login and restarts on crash. Requires `login` first. |
+| `install` | Register the OS supervisor unit (LaunchAgent on macOS, systemd `--user` unit on Linux, Scheduled Task on Windows) so the daemon starts at login and restarts on crash. Requires `login` first. |
 | `uninstall` | Stop and remove the supervisor unit. Pass `--purge` to also delete the persisted config and logs. |
 | `run` | Run the daemon in the foreground (normally invoked by the service unit). Reads config or accepts `--backend` / `--api-key` / `--device-id` / `--label` flags (also via `EDISON_*` env vars). |
</file context>

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/install-beeper.sh">

<violation number="1" location="scripts/install-beeper.sh:281">
P2: Token discovery exits silently when a config directory has no token-shaped strings, so the intended Keychain and manual-token fallbacks never run. Make the candidate-extraction pipeline non-fatal when it finds no matches.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Token discovery exits silently when a config directory has no token-shaped strings, so the intended Keychain and manual-token fallbacks never run. Make the candidate-extraction pipeline non-fatal when it finds no matches.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/install-beeper.sh, line 281:

<comment>Token discovery exits silently when a config directory has no token-shaped strings, so the intended Keychain and manual-token fallbacks never run. Make the candidate-extraction pipeline non-fatal when it finds no matches.</comment>

<file context>
@@ -246,19 +246,40 @@ mask_token() {
+  for d in $dirs; do
+    [ -d "$d" ] || continue
+    cands="$cands
+$(find "$d" -type f -exec cat {} + 2>/dev/null | grep -oE '[A-Za-z0-9._-]{24,}' | sort -u | head -n 80)"
+  done
   if command -v security >/dev/null 2>&1; then
</file context>

Suggested change

	$(find "$d" -type f -exec cat {} + 2>/dev/null | grep -oE '[A-Za-z0-9._-]{24,}' | sort -u | head -n 80)"
	$(find "$d" -type f -exec cat {} + 2>/dev/null | grep -oE '[A-Za-z0-9._-]{24,}' | sort -u | head -n 80 || true)"

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/install-beeper.sh">

<violation number="1" location="scripts/install-beeper.sh:227">
P2: A non-Beeper HTTP listener is treated as a running Desktop API, so install can skip server setup and fail later during token discovery. Require successful OAuth metadata (for example HTTP 200) in both probe branches rather than accepting every non-`000` response.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: A non-Beeper HTTP listener is treated as a running Desktop API, so install can skip server setup and fail later during token discovery. Require successful OAuth metadata (for example HTTP 200) in both probe branches rather than accepting every non-000 response.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/install-beeper.sh, line 227:

<comment>A non-Beeper HTTP listener is treated as a running Desktop API, so install can skip server setup and fail later during token discovery. Require successful OAuth metadata (for example HTTP 200) in both probe branches rather than accepting every non-`000` response.</comment>

<file context>
@@ -217,15 +217,47 @@ ensure_deps() {
+  local wk="/.well-known/oauth-authorization-server" code h p url
+  if [ -n "${BEEPER_API_URL:-}" ]; then
+    code="$(curl -s -m 3 -o /dev/null -w '%{http_code}' "${BEEPER_API_URL}${wk}" 2>/dev/null || true)"
+    [ -n "$code" ] && [ "$code" != "000" ] && { printf '%s' "$BEEPER_API_URL"; return 0; }
+  fi
+  for h in 127.0.0.1 localhost "[::1]"; do
</file context>

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>