Archived

This repository has been archived on 2026-10-08. You can view files and clone it. You cannot open issues or pull requests or push a commit.

Files

T

naps62-yolo 3b6dd50c1d

ci / rust (push) Successful in 4m36s

Details

fix(maestro): maestro-web is now a proxy, not a local registry (NAP-231)

Earlier today I picked option 1 from NAP-231's open question (run
`maestro-registry` locally on a different port). That was wrong: the
user-facing framing is "local web UI", and option 2 — a thin front-end
that serves the web bundle and reverse-proxies `/api/*` to whatever
registry the daemon is already registered with — is what actually
delivers that.

What the new crate does:

- `crates/maestro-web` ships a single binary `maestro-web`.
- It embeds the web bundle the same way `maestro-registry` does
  (rust-embed against `web/dist/`).
- Mounts the bundle at `/` and a reverse proxy at `/api/*` (catch-all).
- HTTP proxy via `reqwest` — forwards method, headers (minus
  hop-by-hop), body, and passes upstream response headers (including
  `Set-Cookie`) back to the browser.
- WS proxy upgrades both sides and shuttles frames with
  `tokio::select!`. Cookies on the initial `WebSocket` upgrade headers
  are forwarded so the registry sees the same browser session.
- Reads `MAESTRO_REGISTRY` (upstream URL) and `MAESTRO_WEB_BIND_ADDR`
  (default `127.0.0.1:8888`) from env.
- An integration test (`tests/proxy.rs`) stands up a mock upstream,
  proxies an HTTP request with cookies through, and round-trips a text
  WebSocket frame to verify the WS path.

Installer changes:

- Wizard now `cargo install`s `maestro-web` (not `maestro-registry`)
  when the user opts into the web service.
- Unit template switched: `ExecStart=%h/.cargo/bin/maestro-web` plus
  `Environment=MAESTRO_REGISTRY=<upstream>` +
  `Environment=MAESTRO_WEB_BIND_ADDR=<bind>`.
- New `--web-registry <URL>` flag. Default in interactive mode: read
  `registry_url` straight out of `~/.config/maestrod/config.toml`, so
  the proxy lines up with what the daemon is using without further
  prompting. Non-interactive runs without either of those error out
  rather than guess.

Docs:

- `docs/INSTALL.md` updated unit body + flag table.
- `CLAUDE.md` repo-layout block now lists `maestro-web`.

148 tests pass workspace-wide (9 new in maestro-web, including the
proxy integration test; 15 in installer).

2026-05-26 08:59:27 +00:00

2.5 KiB

Raw Blame History

Maestro

A unified terminal-session orchestrator. One place — laptop, desktop, or phone — to see and attach to every interactive shell or agent (Claude Code, opencode, plain bash) running across every machine you care about. tmux for persistence, WebSocket for transport, daemon-per-host federated by a small always-on registry.

Where the spec lives

docs/superpowers/specs/2026-05-24-maestro-design.md is the source of truth for architecture, wire protocol, session model, auth, repo layout, and scope boundary. Read it before writing any code in this repo.

Where the work is

Linear project Maestro under team Naps62. Issues NAP-211..218 cover the prototype; each has blockedBy set so the dependency chain is explicit. NAP-211 is the only unblocked starting point.

.claude/linear.json wires /yolo and /work to this project — they pick from "available now" (status backlog/pending, not blocked).

Repo layout (target)

Cargo workspace, populated incrementally starting with NAP-211:

crates/
├── maestro-protocol/    # shared wire types (NAP-211)
├── maestro-daemon/      # per-host tmux wrapper + WS endpoints (NAP-212, NAP-214)
├── maestro-registry/    # always-on phone book + HTTP API (NAP-213, NAP-215)
├── maestro-cli/         # `maestro list/spawn/attach/kill` (NAP-216)
├── maestro-installer/   # `maestro-install` wizard: cargo install + systemd (NAP-225)
├── maestro-web/         # local web-UI front-end: assets + /api proxy (NAP-231)
└── maestro-e2e/         # cross-process integration tests (NAP-217)
web/                     # browser client (NAP-218, plan 2)

See docs/INSTALL.md for end-user install instructions.

Conventions

TDD by default. Failing test first, then minimal impl. Commit test + impl together.
Frequent commits. One logical unit per commit; don't pile work up.
Conventional commits with maestro scope. Example: feat(maestro): add Hello message round-trip test.
cargo fmt + cargo clippy --all-targets -- -D warnings before every commit. (Add to CI as part of NAP-211.)
Integration tests use real tmux and git. Don't mock them. Isolate via temp $HOME and TMUX_TMPDIR.

Network assumption

Maestro is network-agnostic. The operator chooses bind addresses; the perimeter is whatever VPN (Wireguard, etc.) or private LAN they've set up. Maestro does not terminate TLS itself or police the network. See spec §Auth.

Status

Empty repo. Spec approved and committed. NAP-211 is the natural start.

2.5 KiB Raw Blame History