feat: CLI polish, static client assets, config system, and test infrastructure

[jesse23]

Summary

• CLI UX polish — webtty help as canonical entry, all-caps headings, frequency-ordered commands, at/ls/rm/mv with 2-char names and full aliases (attach, list, remove, rename), stop/start server lifecycle, webtty no-arg opens main session
• Static client assets — browser TS extracted to src/client/index.ts, compiled by Bun.build, served as /dist/client-browser.js; zero inline scripts, script-src 'self' CSP-safe; GET /api/config endpoint replaces server-side template injection
• Config system improvements — copyOnSelect, rightClickBehavior, logs config keys; $VISUAL→$EDITOR→vi/notepad editor resolution; isServerRunning() validates JSON array to reject non-webtty processes; stop server when last session exits or is removed
• Test infrastructure — isolated HOME dirs for all subprocess tests (no more config file clobbering); shared test utilities in src/utils.test.ts; pty/index.test.ts with real PTY integration tests; src/server/static.test.ts covering findGhosttyWeb/serveFile; 110 tests, 100% coverage on all unit-testable files
• ADR 012 — documents static asset build architecture and CSP rationale
• Docs — coverage scope documented in development.md; specs and ADRs updated throughout

ADRs

• ADR 011 — amended: CLI UX polish, command renames, at/mv, stop-on-last-rm, copy config
• ADR 012 — new: static asset build, GET /api/config, CSP rationale

[Copilot]

Pull request overview

This PR modernizes webtty’s UX and architecture by moving the browser client to CSP-safe static assets, expanding the config surface (including clipboard/logging behavior), tightening server/CLI lifecycle behavior, and improving the test harness to be more isolated and integration-focused.

Changes:

• Extract browser client into src/client/*, build it via scripts/build.ts, and serve it as static assets; add GET /api/config for runtime client config.
• Polish CLI command surface and help output (at/ls/rm/mv, no-arg default behavior, config/help commands), plus server lifecycle tweaks (stop when last session exits / last rm in CLI).
• Improve test infrastructure (isolated HOME dirs, shared helpers, new unit + integration tests for static serving and PTY).

Reviewed changes

Copilot reviewed 33 out of 34 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tsconfig.json	Include scripts/ in TS project for typechecking/build tooling.
src/utils.ts	Remove shared MIME/static helpers (moved server-side).
src/utils.test.ts	Repurpose into shared test utilities (ports, temp HOME, server wait helpers).
src/server/websocket.ts	Add “last session closed” hook to enable auto-shutdown on final PTY exit.
src/server/websocket.test.ts	Use shared test helpers + add test for shutdown on last session exit.
src/server/static.ts	Move MIME + ghostty-web path helpers into server static module.
src/server/static.test.ts	Add unit tests for findGhosttyWeb, mimeType, serveFile.
src/server/routes.ts	Add GET /api/config, serve static client.html, and serve /dist/* from webtty dist first.
src/server/routes.test.ts	Update expectations for static HTML shell + add /api/config test.
src/server/index.ts	Wire clientDistPath into routes and install last-session-closed shutdown handler.
src/server/client.ts	Remove server-side HTML rendering template.
src/server/client.test.ts	Remove tests for deleted server-side client renderer.
src/pty/index.test.ts	Add PTY integration tests.
src/config.ts	Add copyOnSelect/rightClickBehavior/logs, and allow HOME override for config path.
src/config.test.ts	Switch to HOME override (no os.homedir spying) + add tests for new config keys.
src/client/index.ts	New browser TS entry: fetch config, init terminal, WS reconnect, copy behaviors.
src/client/index.html	New static HTML shell referencing built JS/CSS.
src/client/index.css	New extracted client CSS styles.
src/cli/index.ts	Custom help formatting and no-arg default behavior.
src/cli/http.ts	Harden isServerRunning + implement optional server logging to file.
src/cli/http.test.ts	Add coverage for logging + refactor platform stubbing.
src/cli/commands.ts	Rename/polish commands, add config/help, stop-on-last-rm behavior.
src/cli/commands.test.ts	Update CLI tests for new commands, add no-arg/help/config coverage.
scripts/build.ts	Build server + browser bundles, copy static HTML/CSS into dist/.
docs/specs/webtty.md	Update spec text and API details (notably delete header semantics).
docs/specs/config.md	Document new config keys and reload behavior.
docs/specs/client.md	Document static asset architecture and /api/config endpoint.
docs/specs/cli.md	Update CLI spec for new command surface and UX changes.
docs/adrs/012.client.static-assets.md	New ADR documenting static client build + CSP rationale.
docs/adrs/011.cli.default-and-help.md	Remove superseded ADR.
docs/adrs/011.cli.config-and-help.md	New ADR for CLI polish, config/help, command changes.
docs/adrs/002.cli.start-stop.md	Clarify rationale for HTTP lifecycle approach.
docs/adrs/001.webtty.bootstrap.md	Add single-port and ws rationale notes.
README.md	Update quickstart commands to match new CLI behavior.

Comments suppressed due to low confidence (1)

src/cli/index.ts:85

• program.parseAsync(process.argv) is called without being awaited/returned. Since unresolved Promises don’t keep the event loop alive, the process can exit before async command actions complete (depending on timing), and any rejection becomes unhandled. Prefer top-level await program.parseAsync(process.argv) (ESM supports it) or return the promise from the entrypoint.

program.action(async () => {
  await program.parseAsync(['at', 'main'], { from: 'user' });
});

program.parseAsync(process.argv);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jesse23]

All 7 Copilot comments addressed in e200a52:

• #1 helpOption(false) removed — --help works again; custom formatHelp already omits the Options section so help output is unchanged
• #2/#3 cli.md updated: start/stop lifecycle wording, stale down alias mention removed
• #4 clientDistPath now derived from __dirname (server entry location) — robust regardless of node_modules layout; also falls back to src/client/ when dist/ not built
• #5 logPath() now uses exported configDir() from config.ts which respects process.env.HOME
• #6 Log fd closed in parent process immediately after child.unref()
• #7 webtty config uses configDir(), creates dir and empty config file if missing before opening editor