|
|
|
@@ -0,0 +1,380 @@
|
|
|
|
|
# Installer v2: three questions, then a URL you can open on your phone (Plan)
|
|
|
|
|
|
|
|
|
|
Status: **Phase 1 IMPLEMENTED (2026-09-20)**, phases 2 and 3 open. It builds on
|
|
|
|
|
`docs/tailscale-installer-plan.md` (implemented 2026-08-04), which made Tailscale a
|
|
|
|
|
guided option; this round makes it the thing the install ENDS on, and makes the whole
|
|
|
|
|
installer shorter to sit through. Owner decisions taken before implementation: rename
|
|
|
|
|
is opt-in and **defaults to no everywhere** (the machine name is used for other things);
|
|
|
|
|
the URL keeps the node name unless asked; `codeman-<hostname>` is the suggested name;
|
|
|
|
|
sub-path is the default for an occupied `:443`.
|
|
|
|
|
|
|
|
|
|
Verification record for phase 1 (all on the maintainer's box, 2026-09-20):
|
|
|
|
|
|
|
|
|
|
- `test/install-sh-invariants.test.ts` (28 tests, incl. the new Tailscale safety pins)
|
|
|
|
|
and the detection-parity test pass; `bash -n` passes.
|
|
|
|
|
- Every new decision function driven with stubbed tailscale state under **bash 5.2 and
|
|
|
|
|
bash 3.2** (the `bash:3.2` container CI uses): flags, the launch default, the serve
|
|
|
|
|
shape for free / ours / occupied `:443` (all four answers plus the non-interactive
|
|
|
|
|
default), the three serve commands, the rename question (Enter keeps the name; `--yes`
|
|
|
|
|
and non-interactive never rename; `codeman-*` nodes are skipped; `--name` is
|
|
|
|
|
sanitized), `run_step` success/failure/stdin, the unit round-trip of
|
|
|
|
|
`CODEMAN_BASE_URL`/`CODEMAN_PORT`/an escaped password, and the done screen.
|
|
|
|
|
- A full non-interactive install into a sandboxed `HOME` with `CODEMAN_TAILSCALE=1`:
|
|
|
|
|
preflight summary, kept the existing prod mapping (no serve mutation), clone 2 s,
|
|
|
|
|
`npm install` 18 s, build 23 s, symlink, done screen; `install.sh status` on a pty
|
|
|
|
|
renders the QR code. Nothing on the real system changed.
|
|
|
|
|
- **Sub-path mode end to end over the real tailnet**: an isolated Codeman
|
|
|
|
|
(`CODEMAN_INSTANCE`, port 3999, `--base-url /codeman`) behind
|
|
|
|
|
`tailscale serve --https=8445 --set-path /codeman 3999` answered `/codeman/api/status`,
|
|
|
|
|
`/codeman/` (with `<base href="/codeman/">` and `__CODEMAN_BASE__="/codeman"`), the
|
|
|
|
|
hashed CSS/JS, `/codeman` without a slash, and the SSE stream; mapping and server
|
|
|
|
|
removed afterwards. **Correction to section 2**: serve STRIPS the mount prefix
|
|
|
|
|
before proxying (a direct `/codeman/api/status` on the server is 404 while the same
|
|
|
|
|
path through serve is 200). That is fine because Codeman's ingress tolerates
|
|
|
|
|
unprefixed requests; `--base-url` is needed for the URLs Codeman EMITS, not for
|
|
|
|
|
what it receives.
|
|
|
|
|
- Not yet exercised on a fresh machine (unchanged from the previous plan): Tailscale
|
|
|
|
|
absent / logged out / HTTPS toggle off, the rename against a real node (the
|
|
|
|
|
off-rename-re-add order is implemented but only unit-driven), macOS, uninstall. The
|
|
|
|
|
Mac mini and a throwaway VM are the venues; see section 8.
|
|
|
|
|
- **Review fixes (2026-09-21)**, from the two reviews on PR #460 (DeepSeek Harness, then
|
|
|
|
|
Claude): the done screen's Start line is composed from every non-default value
|
|
|
|
|
(`start_command_hint`, shared with the exec branch as `export_bind_env`), so "do not
|
|
|
|
|
start" under a sub-path or a custom port no longer prints a bare `codeman web`; the
|
|
|
|
|
`--lan`/`--tailscale`/env preset paths keep an existing password instead of rewriting
|
|
|
|
|
the unit open; `--password`/`--port` flip `RECONFIGURE` so they reach the unit;
|
|
|
|
|
`install.sh name` re-syncs the unit's base URL after a rename; the sudo keepalive is
|
|
|
|
|
ended before the `exec` into the foreground server; Ctrl+C in the HTTPS-toggle poll
|
|
|
|
|
skips Tailscale instead of killing the run; `uninstall` asks before removing a
|
|
|
|
|
LaunchDaemon it never wrote; a foreign LaunchDaemon gets a restart hint and the done
|
|
|
|
|
screen stops claiming the new build is running; the preflight summary reads the
|
|
|
|
|
Tailscale state without node; the LAN security notice uses the configured port; a
|
|
|
|
|
bare re-run ends on the done screen; a build failure after a rename names the
|
|
|
|
|
`install.sh tailscale` recovery; `TS_JOINED_HERE` is gone.
|
|
|
|
|
|
|
|
|
|
Goal, in one sentence: a user runs the one-liner, answers at most three questions, walks
|
|
|
|
|
away during the build, and comes back to `https://<name>.<tailnet>.ts.net` printed with a
|
|
|
|
|
QR code, already answering, on every device in their tailnet. That is exactly the
|
|
|
|
|
maintainer's own production setup (`tnode.tailf80371.ts.net` fronting `127.0.0.1:3000`),
|
|
|
|
|
and the installer should produce it without the user knowing what `tailscale serve` is.
|
|
|
|
|
|
|
|
|
|
## 1. Where the installer is today
|
|
|
|
|
|
|
|
|
|
Facts from reading `install.sh` (2886 lines, 19 `prompt_yes_no` sites) and the live
|
|
|
|
|
Tailscale state on the maintainer's box (tailscale 1.102.2, user-owned node, MagicDNS +
|
|
|
|
|
HTTPS certs on, serve mapping `443 -> https+insecure://localhost:3000`).
|
|
|
|
|
|
|
|
|
|
**The order is backwards for a human.** The flow is: detect -> ask about git -> ask about
|
|
|
|
|
node -> ask about tmux -> ask about build tools -> AI CLI menu -> ask about cloudflared ->
|
|
|
|
|
clone -> `npm install` -> build (minutes) -> **then** the network-access question -> the
|
|
|
|
|
Tailscale sub-steps (install? login URL, sudo for operator, admin-console toggle loop) ->
|
|
|
|
|
the launch menu (no default; a bare Enter re-prompts) -> tunnel-service question. A fresh
|
|
|
|
|
Ubuntu server taking the Tailscale route answers roughly ten prompts plus two to four sudo
|
|
|
|
|
password prompts, split around a multi-minute build. The user cannot walk away at any
|
|
|
|
|
point, and the question that matters most (how do I reach it) comes last.
|
|
|
|
|
|
|
|
|
|
**The Tailscale flow works but was never exercised on a fresh machine.** The previous
|
|
|
|
|
plan's manual matrix still lists items 1-4, 7 and 10-12 (Tailscale absent, logged out,
|
|
|
|
|
HTTPS toggle off, port 443 occupied, macOS, uninstall, phone PWA) as untested. The
|
|
|
|
|
maintainer's own verification was the idempotent "kept as-is" path.
|
|
|
|
|
|
|
|
|
|
**The URL is the machine's name, full stop.** `setup_tailscale_serve` derives it from
|
|
|
|
|
`.Self.DNSName`, and nothing lets the user influence it. A second Codeman on the same
|
|
|
|
|
tailnet is `macminis-mac-mini.tailf80371.ts.net`, which tells you nothing about Codeman.
|
|
|
|
|
|
|
|
|
|
**Port 443 taken means give up or clobber.** If another app already owns the root of
|
|
|
|
|
`:443`, the only offer is "replace it?" (default no), and declining falls back to
|
|
|
|
|
local-only. Codeman already supports running under a sub-path (`--base-url`), and
|
|
|
|
|
Tailscale serve supports mounting a path (`--set-path`), so there is a third answer nobody
|
|
|
|
|
is offered.
|
|
|
|
|
|
|
|
|
|
**The result is invisible afterwards.** Once the terminal scrolls away, nothing in the app
|
|
|
|
|
or the CLI tells the user their Tailscale URL again. `codeman doctor` does not probe
|
|
|
|
|
Tailscale; App Settings -> Remote access shows only the Cloudflare tunnel.
|
|
|
|
|
|
|
|
|
|
**Two service writers exist.** `install.sh` carries its own plist/unit generator (~180
|
|
|
|
|
lines) next to `codeman service install` (`src/service-installer.ts`). They agree on the
|
|
|
|
|
job name by design, but the bash copy is the one that writes `CODEMAN_PASSWORD` into the
|
|
|
|
|
unit, so they cannot simply be merged. Left as-is in this plan (see section 9).
|
|
|
|
|
|
|
|
|
|
## 2. What Tailscale makes possible for the name (researched 2026-09-20)
|
|
|
|
|
|
|
|
|
|
| Option | Resulting URL | What it needs | Side effects | Verdict |
|
|
|
|
|
| ------ | ------------- | ------------- | ------------ | ------- |
|
|
|
|
|
| **A. Node name** (today) | `https://tnode.tailf80371.ts.net` | `tailscale serve --bg 3000` | none | **Default.** Zero admin-console work, matches the maintainer's prod. |
|
|
|
|
|
| **B. Rename the node** | `https://codeman-tnode.tailf80371.ts.net` | `tailscale set --hostname codeman-<host>` (operator or root) | Renames the machine tailnet-wide: ssh targets, other serve URLs, the admin console entry. Tailscale de-dups a clash as `-1`. The cert follows the new name. | **Opt-in, default NO everywhere** (owner decision 2026-09-20: the machine is used for other things, so a bare Enter never renames it). The proposal was YES when the installer itself had just joined the tailnet; rejected. |
|
|
|
|
|
| **C. Tailscale Service** | `https://codeman.tailf80371.ts.net` | tailscale >= 1.86 on the host; the host must have a **tag-based identity** ("You cannot use a device authenticated with a user account as a Service host"); the service is defined in the admin console first; the host is then approved there (or via `autoApprovers.services`). Public beta since 2025-10-28, all plans. | Re-authenticating a personal machine as a tagged node changes its identity (SSH ACLs, user attribution). Known daemon quirk: approval is not picked up until `serve clear` + re-advertise (tailscale/tailscale#18821). | **Detect and hint only** in this round. The maintainer's own node has `Self.Tags: null`, so it could not host one without re-tagging. Worth a real flow once someone with a tagged fleet asks. |
|
|
|
|
|
| **D. Sub-path** | `https://tnode.tailf80371.ts.net/codeman` | `tailscale serve --bg --set-path /codeman 3000` plus `--base-url /codeman` on the server | Codeman runs under a prefix. Hooks are unaffected (they hit the raw port with no prefix, which `rewriteUrl` already tolerates). Serve forwards the prefix unchanged, which is exactly the shape `--base-url` was built for. | **The answer when `:443` root is already taken.** Replaces today's replace-or-nothing prompt. |
|
|
|
|
|
| **E. Second port** | `https://tnode.tailf80371.ts.net:8443` | `tailscale serve --bg --https=8443 3000` | Port in the URL; the beta-preview recipe already uses this. | Fallback when the user rejects D. |
|
|
|
|
|
| Funnel (public internet) | `https://tnode.tailf80371.ts.net` from anywhere | `tailscale funnel` | Public exposure; different risk class. | **Out of scope**, as before. Docs only, with the password warning. |
|
|
|
|
|
|
|
|
|
|
Sources: Tailscale Services docs (`tailscale.com/docs/features/tailscale-services`), the
|
|
|
|
|
Services beta announcement (`tailscale.com/blog/services-beta`), machine names
|
|
|
|
|
(`tailscale.com/kb/1098/machine-names`), the serve CLI reference
|
|
|
|
|
(`tailscale.com/docs/reference/tailscale-cli/serve`), the macOS variants page
|
|
|
|
|
(`tailscale.com/docs/concepts/macos-variants`), and `tailscale serve --help` on 1.102.2
|
|
|
|
|
(which lists `--service`, `--set-path`, `--yes`, `advertise`, `get-config`/`set-config`).
|
|
|
|
|
|
|
|
|
|
**Trap for option B (verify on the Mac mini before shipping):** the serve config is keyed
|
|
|
|
|
by `host:port` using the DNS name at configuration time (`"Web": {"tnode.tailf80371.ts.net:443": ...}`
|
|
|
|
|
in `serve status --json`). Renaming a node after serve is configured most likely orphans that
|
|
|
|
|
entry: the handler lookup uses the current name and never matches the old key, and the only
|
|
|
|
|
tool that removes a stale key is `serve reset`, which this installer must never run. So the
|
|
|
|
|
order is **rename first, then configure serve** on a fresh install, and on a retrofit
|
|
|
|
|
(`install.sh name`) **turn our mapping off, rename, wait for `.Self.DNSName` to change,
|
|
|
|
|
re-add**.
|
|
|
|
|
|
|
|
|
|
## 3. Target UX
|
|
|
|
|
|
|
|
|
|
### 3.1 Three questions, then walk away
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Codeman installer
|
|
|
|
|
|
|
|
|
|
Found: git, Node 22.14, tmux 3.4, build tools Missing: nothing
|
|
|
|
|
AI CLIs: Claude Code (~/.local/bin/claude)
|
|
|
|
|
Tailscale: connected as tnode (tailf80371.ts.net)
|
|
|
|
|
Existing: none
|
|
|
|
|
|
|
|
|
|
1/3 How should the dashboard be reachable?
|
|
|
|
|
1) Tailscale https://tnode.tailf80371.ts.net (recommended, already connected)
|
|
|
|
|
2) Any device on your network (0.0.0.0, password required)
|
|
|
|
|
3) This machine only (127.0.0.1)
|
|
|
|
|
Choose [1/2/3] (default 1):
|
|
|
|
|
|
|
|
|
|
2/3 Name this machine "codeman-tnode" on your tailnet? [y/N]
|
|
|
|
|
(only shown for option 1; default no, always)
|
|
|
|
|
|
|
|
|
|
3/3 Run Codeman as a background service that starts on boot? [Y/n]
|
|
|
|
|
|
|
|
|
|
Installing… this takes a few minutes. You can leave this running.
|
|
|
|
|
✓ dependencies ✓ clone ✓ build (2m 41s) ✓ service ✓ tailscale serve
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Rules that make this work:
|
|
|
|
|
|
|
|
|
|
- **Every step that needs a human runs BEFORE the build.** The dependency consent, the
|
|
|
|
|
AI CLI menu, the Tailscale install consent, the `tailscale up` login URL, the operator
|
|
|
|
|
grant, and the tailnet HTTPS toggle all move into the question phase. The build, the
|
|
|
|
|
service, `tailscale serve` and the verification are unattended.
|
|
|
|
|
- **One consent for all missing system packages.** "Install git, Node 22 and build tools
|
|
|
|
|
now? [Y/n]" replaces four separate prompts. Each package still runs its own
|
|
|
|
|
distro-specific installer.
|
|
|
|
|
- **One sudo prompt.** When anything needs root (packages, the Tailscale installer,
|
|
|
|
|
`tailscale up`, the operator grant), the installer says so once, runs `sudo -v`, and keeps
|
|
|
|
|
the timestamp alive in a background loop until it exits. macOS needs no sudo for the
|
|
|
|
|
Tailscale GUI-app CLI and the pattern still holds for Homebrew packages.
|
|
|
|
|
- **Service is the default.** Enter on the last question installs the service; "run in
|
|
|
|
|
this terminal" and "don't start" stay reachable by answering, and by flag.
|
|
|
|
|
- **The cloudflared question is gone from the main flow.** It is optional, defaults to
|
|
|
|
|
no, and has an in-app toggle (App Settings -> Remote access). The done screen mentions it
|
|
|
|
|
only when `cloudflared` is already installed. The Linux tunnel-service prompt goes with it.
|
|
|
|
|
- **The HTTPS-certificates toggle no longer asks "re-check now?"** The installer prints the
|
|
|
|
|
admin URL, opens it in a browser when one is available (`xdg-open` / `open`, never on a
|
|
|
|
|
headless box), and polls `tailscale status --json` every 5 s for up to 5 minutes. Ctrl+C or
|
|
|
|
|
the timeout falls back exactly as today.
|
|
|
|
|
- **Progress, not silence.** `npm install` and `npm run build` run behind one line each
|
|
|
|
|
with elapsed time; their output goes to `~/.codeman/install.log` and is printed only on
|
|
|
|
|
failure, with the exact retry command.
|
|
|
|
|
|
|
|
|
|
### 3.2 The done screen
|
|
|
|
|
|
|
|
|
|
One block, the URL first, a QR code the phone can scan, and nothing the user does not need
|
|
|
|
|
right now.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
✓ Codeman 1.31.0 is running
|
|
|
|
|
|
|
|
|
|
Your tailnet: https://codeman-tnode.tailf80371.ts.net (HTTPS, any of your devices)
|
|
|
|
|
This machine: http://localhost:3000
|
|
|
|
|
|
|
|
|
|
▄▄▄▄▄▄▄ ▄ ▄▄ ▄▄▄▄▄▄▄
|
|
|
|
|
█ ▄▄▄ █ ▄▄▀ ▄ █ ▄▄▄ █ scan with your phone
|
|
|
|
|
█ ███ █ ███▀▀ █ ███ █
|
|
|
|
|
█▄▄▄▄▄█ █ ▄ █ █▄▄▄▄▄█
|
|
|
|
|
|
|
|
|
|
Manage systemctl --user restart codeman-web · journalctl --user -u codeman-web -f
|
|
|
|
|
Update re-run the install line, or App Settings → System → Updates
|
|
|
|
|
Docs https://github.com/Ark0N/Codeman/wiki
|
|
|
|
|
|
|
|
|
|
Security: Codeman binds 127.0.0.1. Tailscale authenticates every device before a
|
|
|
|
|
packet reaches it. Details: docs/security-architecture.md
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The QR comes from the `qrcode` package Codeman already depends on
|
|
|
|
|
(`node -e "require('qrcode').toString(url, {type:'terminal', small:true}, …)"` from
|
|
|
|
|
`$INSTALL_DIR`, verified locally: 17 rows by 45 columns). Skipped when the terminal has no
|
|
|
|
|
color support or fewer than 50 columns. The QR encodes the plain URL, not an auth token:
|
|
|
|
|
the tailnet is the login.
|
|
|
|
|
|
|
|
|
|
### 3.3 Express mode and flags
|
|
|
|
|
|
|
|
|
|
Env vars stay (`CODEMAN_TAILSCALE=1`, `CODEMAN_HOST`, `CODEMAN_PASSWORD`,
|
|
|
|
|
`CODEMAN_NONINTERACTIVE=1`, `CODEMAN_PORT`). Flags are added because they are
|
|
|
|
|
discoverable from the one-liner and pipe through `bash -s --`:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
curl -fsSL https://getcodeman.com/install | bash -s -- --tailscale --service
|
|
|
|
|
curl -fsSL https://getcodeman.com/install | bash -s -- --lan --password 'x' --service
|
|
|
|
|
curl -fsSL https://getcodeman.com/install | bash -s -- --local --run
|
|
|
|
|
curl -fsSL https://getcodeman.com/install | bash -s -- --tailscale --name codeman-build --yes
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
| Flag | Meaning |
|
|
|
|
|
| ---- | ------- |
|
|
|
|
|
| `--tailscale` / `--lan` / `--local` | Answer 1/3 (same semantics as `CODEMAN_TAILSCALE=1`, `CODEMAN_HOST=0.0.0.0`, `CODEMAN_HOST=127.0.0.1`) |
|
|
|
|
|
| `--name <n>` / `--no-rename` | Answer 2/3: rename the node to `<n>`, or never ask |
|
|
|
|
|
| `--service` / `--run` / `--no-start` | Answer 3/3 |
|
|
|
|
|
| `--yes` | Accept every default, still prompt for a login URL (a human must open it) |
|
|
|
|
|
| `--password <p>` | Same as `CODEMAN_PASSWORD` |
|
|
|
|
|
| `--port <n>` | Same as `CODEMAN_PORT`; the serve target follows it |
|
|
|
|
|
|
|
|
|
|
`--yes` differs from `CODEMAN_NONINTERACTIVE=1`: it is the interactive user saying "I trust
|
|
|
|
|
the defaults", so it may install software and may wait on a login URL. Non-interactive stays
|
|
|
|
|
the CI contract and never installs Tailscale.
|
|
|
|
|
|
|
|
|
|
## 4. The Tailscale flow, v2
|
|
|
|
|
|
|
|
|
|
The state machine from the previous plan stays; these are the changes.
|
|
|
|
|
|
|
|
|
|
1. **Preflight, before the build** (`tailscale_preflight`): installed? -> install
|
|
|
|
|
(Linux: official script; macOS: brew cask, else download link and wait). Logged in? ->
|
|
|
|
|
`tailscale up` with the URL printed prominently and a 5-minute poll. Operator (Linux):
|
|
|
|
|
grant once under the single sudo session. HTTPS certs: poll instead of ask (Ctrl+C
|
|
|
|
|
during the poll skips Tailscale for this run rather than ending the installer). The
|
|
|
|
|
rename default does not depend on whether this run performed the login (decided NO
|
|
|
|
|
everywhere), so nothing records it.
|
|
|
|
|
2. **Name** (`tailscale_choose_name`, question 2/3): shown only on the Tailscale route.
|
|
|
|
|
Default `codeman-<oshostname>` sanitized to `[a-z0-9-]`, max 63. Applied with
|
|
|
|
|
`ts_cmd_serve set --hostname`, then poll `.Self.DNSName` until it carries the new name
|
|
|
|
|
(up to 60 s). Order matters: this runs before any serve mutation (section 2 trap).
|
|
|
|
|
Declining keeps the node name. On a re-run against a node already named `codeman-*`,
|
|
|
|
|
the question is skipped.
|
|
|
|
|
3. **Serve, after the service is up** (`setup_tailscale_serve`): unchanged idempotent
|
|
|
|
|
"kept as-is" path first. When `:443` root belongs to another target, the new prompt is:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
tailscale serve already sends https://tnode.tailf80371.ts.net to port 8080.
|
|
|
|
|
1) Add Codeman under a path: https://tnode.tailf80371.ts.net/codeman (default)
|
|
|
|
|
2) Use another port: https://tnode.tailf80371.ts.net:8443
|
|
|
|
|
3) Replace the existing mapping with Codeman
|
|
|
|
|
4) Skip Tailscale for now
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Option 1 writes `--base-url /codeman` into the service unit (it is a `WebLaunchOptions`
|
|
|
|
|
field already, and `buildWebArgs` carries it) and runs
|
|
|
|
|
`tailscale serve --bg --set-path /codeman <port>`. Option 2 runs `--https=8443`.
|
|
|
|
|
`detect_tailscale_serve_url` learns to recognize all three shapes (root, path, port) so
|
|
|
|
|
uninstall, the security notice and the re-run default keep working.
|
|
|
|
|
4. **Warm the certificate.** Right after serve is configured, fire one background
|
|
|
|
|
`curl -sk https://<url>/api/status` so Let's Encrypt issuance overlaps the rest of the
|
|
|
|
|
install instead of adding 30 s to the verify step.
|
|
|
|
|
5. **Verify** as today (200 or 401 on `/api/status`), with the path-aware URL.
|
|
|
|
|
6. **Services hint** (option C): when `.Self.Tags` is non-empty and `serve --help`
|
|
|
|
|
lists `--service`, the done screen adds one line: "This is a tagged node, so it can also
|
|
|
|
|
host `https://codeman.<tailnet>.ts.net` as a Tailscale Service: see Remote Access in the
|
|
|
|
|
wiki." No flow, no prompt.
|
|
|
|
|
7. **macOS**: the App Store and Standalone variants cannot run before login, so a
|
|
|
|
|
LaunchAgent plus serve only comes back after someone logs in. The done screen says so on
|
|
|
|
|
macOS. The Mac mini (`arbbot`, headless, system LaunchDaemon) is the reference for the
|
|
|
|
|
"headless Mac" caveat, and `install.sh` must keep refusing to replace a LaunchDaemon it
|
|
|
|
|
did not write (today it removes one; that is a bug for the Mac mini and is fixed here:
|
|
|
|
|
detect `UserName` in the daemon plist and leave it alone with a message).
|
|
|
|
|
8. **Uninstall** additionally offers to restore the original node name when this installer
|
|
|
|
|
renamed it (the original is recorded in `~/.codeman/install.json`, the one marker file
|
|
|
|
|
this feature adds, because tailscaled does not remember previous names).
|
|
|
|
|
9. **Subcommands**: `install.sh tailscale` (unchanged purpose, now runs the v2 flow),
|
|
|
|
|
`install.sh name [<n>]` (rename with the off/rename/re-add dance), `install.sh status`
|
|
|
|
|
(prints the done screen again, URL and QR included, for the "what was my URL" moment).
|
|
|
|
|
|
|
|
|
|
## 5. In-app: the URL stays discoverable
|
|
|
|
|
|
|
|
|
|
Small, read-only, and the first server-side code this feature has ever needed.
|
|
|
|
|
|
|
|
|
|
- **`GET /api/system/remote-access`** returns
|
|
|
|
|
`{ tailscale: { installed, connected, dnsName, url, mode: 'root'|'path'|'port'|null } }`
|
|
|
|
|
by running `tailscale status --json` and `tailscale serve status --json` through
|
|
|
|
|
`execFile` with the existing exec timeout, cached 30 s, resolved through the same
|
|
|
|
|
`get_tailscale_path` search as the installer (PATH, then the macOS app bundle), and a
|
|
|
|
|
no-op under `VITEST` like every other IO probe. Never mutates serve config.
|
|
|
|
|
- **App Settings -> Remote access** gains a **Tailscale** row above the Cloudflare toggle:
|
|
|
|
|
the URL as a copy chip, a QR button reusing `showTunnelQR`'s modal, and when nothing is
|
|
|
|
|
configured a one-line hint with `bash ~/.codeman/app/install.sh tailscale`. The welcome
|
|
|
|
|
screen's "open on your phone" affordance shows the same QR.
|
|
|
|
|
- **`codeman doctor`** grows a `tailscale` entry under `other` in
|
|
|
|
|
`config/dependency-registry.ts`: installed, connected, serving Codeman (URL). Pure
|
|
|
|
|
engine, injectable probe host, like the existing rows.
|
|
|
|
|
- No new SSE event, no settings key, no state.json change.
|
|
|
|
|
|
|
|
|
|
## 6. Security posture
|
|
|
|
|
|
|
|
|
|
Nothing widens. The bind stays loopback; the tailnet is the authentication boundary;
|
|
|
|
|
`.ts.net` is already in `DEFAULT_TRUSTED_HOST_SUFFIXES`. New surfaces are read-only
|
|
|
|
|
probes. `install.sh` still never runs `tailscale serve reset`, still touches only the
|
|
|
|
|
mapping it created, and gains one more never: it never advertises a Tailscale Service or
|
|
|
|
|
runs `tailscale funnel`. The sudo keep-alive loop is killed by the existing `cleanup` trap.
|
|
|
|
|
The rename records the previous name locally and offers the reversal at uninstall.
|
|
|
|
|
|
|
|
|
|
## 7. Implementation inventory
|
|
|
|
|
|
|
|
|
|
| File | Change |
|
|
|
|
|
| ---- | ------ |
|
|
|
|
|
| `install.sh` | New `parse_flags`, `preflight_summary`, `ask_everything` (the three questions), `sudo_session`, `run_step` (spinner + log), `tailscale_preflight`, `tailscale_choose_name`, `tailscale_rename_node`, `print_done_screen`, `print_qr`, `status` subcommand, `name` subcommand. Modified: `main` (reordered into ask -> work -> done), `choose_network_binding` (question 1/3, same defaults), `setup_tailscale_serve` (path/port options), `detect_tailscale_serve_url` (three shapes), `setup_systemd_service`/`setup_launchd_service` (`--base-url`, LaunchDaemon guard), `uninstall` (rename reversal), header docs (flags). Removed from the main flow: the cloudflared prompt, the tunnel-service prompt. bash 3.2 rules unchanged. |
|
|
|
|
|
| `src/web/routes/system-routes.ts` | `GET /api/system/remote-access` |
|
|
|
|
|
| `src/tailscale-status.ts` (new) | Pure parser for the two JSON shapes + the IO wrapper; unit-tested against captured `serve status --json` fixtures (root, path, port, foreign target, none) |
|
|
|
|
|
| `src/config/dependency-registry.ts`, `src/utils/dependency-checker.ts` | `tailscale` doctor row |
|
|
|
|
|
| `src/web/public/index.html`, `settings-ui.js`, `panels-ui.js` | Tailscale row + QR, welcome-screen QR |
|
|
|
|
|
| `test/install-sh-invariants.test.ts` | Extend: flags documented in the header, no `serve reset`, no `funnel`, no `--service` advertise, every serve mutation goes through `ts_cmd_serve`, rename happens before serve in `main` (static order check) |
|
|
|
|
|
| `.github/workflows/ci.yml` | The bash 3.2 step additionally sources the script with stubbed `ts_cmd`/`ts_cmd_serve`/`read_reply` and drives `ask_everything` through all three answers and the 443-occupied menu |
|
|
|
|
|
| `test/tailscale-status.test.ts`, `test/routes/system-routes-remote-access.test.ts` | Parser + route |
|
|
|
|
|
| Docs | README install + remote-access sections, `docs/wiki/Installation.md`, `Remote-Access.md` (naming options table, Services caveat, path/port variants), `Mobile-Guide.md`, `Running-As-A-Service.md` (macOS login caveat), `FAQ.md`, `docs/security-architecture.md` §A, CLAUDE.md Scripts & Tunnel paragraph, `docs/tailscale-installer-plan.md` gets a pointer here. getcodeman.com copy lives outside the repo (maintainer handbook). |
|
|
|
|
|
|
|
|
|
|
Changeset: `minor` (new flags, new subcommands, new API route).
|
|
|
|
|
|
|
|
|
|
## 8. Test plan
|
|
|
|
|
|
|
|
|
|
Automated (the gate): the static invariants above, the bash 3.2 container drive of the
|
|
|
|
|
question phase, the JSON parser fixtures, the route test.
|
|
|
|
|
|
|
|
|
|
Manual matrix, on a fresh Ubuntu 24 VM and on the Mac mini, since the previous plan's
|
|
|
|
|
items never ran on a fresh machine:
|
|
|
|
|
|
|
|
|
|
1. Tailscale absent, declined -> local-only, done screen shows the retrofit command.
|
|
|
|
|
2. Tailscale absent, accepted -> install, login URL, operator, certs toggle polled, rename
|
|
|
|
|
question shown (default no), service, serve, URL verified, QR scans on a phone, PWA installs.
|
|
|
|
|
3. Tailscale present and logged in on a pre-existing node -> rename default NO, URL is the
|
|
|
|
|
node name, `serve status` gains exactly one entry.
|
|
|
|
|
4. `:443` root occupied -> path option -> `https://<node>/codeman` answers, hooks still
|
|
|
|
|
fire (raw port), `install.sh status` prints the path URL.
|
|
|
|
|
5. Rename on a node that already has our serve mapping (`install.sh name`) -> off, rename,
|
|
|
|
|
re-add, `serve status` has no stale key.
|
|
|
|
|
6. Re-run the one-liner -> quiet update, binding and name preserved, no prompts.
|
|
|
|
|
7. `--yes` end to end; `CODEMAN_NONINTERACTIVE=1` end to end (no software installed).
|
|
|
|
|
8. Uninstall -> mapping removed, other mappings intact, rename reversal offered.
|
|
|
|
|
9. Mac mini: LaunchDaemon left alone with the message; done screen carries the login caveat.
|
|
|
|
|
|
|
|
|
|
## 9. Phasing and open decisions
|
|
|
|
|
|
|
|
|
|
**Phase 1 (this round):** the reorder, the three questions, one consent + one sudo, flags,
|
|
|
|
|
the done screen with QR, Tailscale preflight-before-build, the path/port answer for an
|
|
|
|
|
occupied 443, the rename step, `status` and `name` subcommands, docs.
|
|
|
|
|
|
|
|
|
|
**Phase 2:** the in-app Tailscale row + QR, `codeman doctor` row, the `remote-access`
|
|
|
|
|
route. Independent of phase 1 and useful on its own for existing installs.
|
|
|
|
|
|
|
|
|
|
**Phase 3 (optional):** replace the bash service writers with `codeman service install`
|
|
|
|
|
once that command can carry `CODEMAN_PASSWORD` behind an explicit flag; and a Tailscale
|
|
|
|
|
Services flow if a tagged-fleet user asks for `codeman.<tailnet>.ts.net`.
|
|
|
|
|
|
|
|
|
|
Decisions for the maintainer:
|
|
|
|
|
|
|
|
|
|
1. **Rename default.** Decided 2026-09-20: always NO; the yes answer, `--name` and
|
|
|
|
|
`install.sh name` are the ways in. (The proposal was YES only when this run had joined
|
|
|
|
|
the tailnet, NO otherwise; rejected because the host is used for other things.)
|
|
|
|
|
2. **Name pattern.** `codeman-<hostname>` (proposed; unique per machine, and two Codemans
|
|
|
|
|
on one tailnet stay distinguishable) versus plain `codeman` (nicer once, collides on the
|
|
|
|
|
second install, Tailscale silently appends `-1`).
|
|
|
|
|
3. **Path versus port** as the default answer for an occupied 443. Proposed: path, because
|
|
|
|
|
the URL has no port and `--base-url` already exists for exactly this proxy shape.
|
|
|
|
|
4. **Whether Phase 2 ships in the same release.** It is the part that helps people who
|
|
|
|
|
installed months ago.
|
Codeman maintainer