yamine 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03b07451fa5f83423efb747feb496c8617bef2fde5b4f4bf0d595d759efd1083
+  data.tar.gz: 64fd53920c5f4740402982dc9f56f07a835c83fb5c2a7eb741c636573b69cfad
+SHA512:
+  metadata.gz: 73b3fbdd108a91942ba53c29a41cd73825d3f3ea11a24ebc60c42786a792dc74553fe67938b28b2d4787011b021542bf17a633713d1178caa231a359bdd344a9
+  data.tar.gz: 315127dad685afebc614c3c76d8e8ecda53413aef997cea0e82730f8a169cbb066a4bcedb25c78cf502631062751b9911f8986842beac14440c4a9f25d4c5e9c

data/CHANGELOG.md

@@ -0,0 +1,243 @@
+# Changelog
+
+## [0.3.0] — Unreleased
+
+Renamed from `ask-local` to **`yamine`** (يمين, "right hand" — the local
+half of the Kamal pair; see README for the full story). Fresh gem, new
+history: starts at 0.3.0 to honor the 0.2.x ask-local lineage without
+claiming continuity. `Ask::Local` → `Yamine`, `ask-local`/`askl` binaries
+→ `yamine`, `ASK_LOCAL_*` env → `YAMINE_*`, state dir `~/.ask-local` →
+`~/.yamine`, skill `ask-local` → `yamine`, health headers
+`x-ask-local*` → `x-yamine*`. No migration path — no existing users.
+
+## [0.2.1] — 2026-09-08
+
+Patch release focused on making `yamine setup` dependable end-to-end:
+it now installs the 443 service and *finishes* (hosts + doctor), works
+passwordless for agents, survives first-run edge cases, and shows what it
+is doing while it works.
+
+### Fixed
+
+- **`setup` no longer stops after installing the service.** The elevated
+  install used to `exit` mid-flow, so `/etc/hosts` was never synced and
+  `doctor` never ran despite the "setup complete" promise. Install and
+  uninstall now return booleans and the CLI owns the exit codes, so
+  `setup` always reaches the hosts and doctor steps. (`service uninstall`
+  also crashed outright — it called its handler without the required
+  context argument.)
+- **A stale user-owned plist is healed on install.** `File.write` keeps
+  an existing file's owner, so a leftover plist from an older version
+  stayed user-owned and launchd refused it forever with "Bootstrap
+  failed: 5". Install now chowns the plist to root explicitly (launchd
+  and systemd).
+- **The TLS proxy survives plaintext probes.** The health probe sends
+  plain HTTP before TLS; an unhandled `SSL_accept` error used to kill
+  the acceptor thread, and with both acceptors gone the daemon exited
+  before the readiness probe ever succeeded. A plaintext connection is
+  now just one dropped connection.
+- `clean` referenced the CA common name unqualified (NameError) — fixed.
+- `setup --no-service` printed a duplicate "2/3" step — numbered 1/4–4/4.
+
+### Added
+
+- `yamine sudoers` — prints the scoped NOPASSWD rules so agents and
+  CI can install and run the 443 service without a TTY. Non-interactive
+  elevation uses `sudo -n` (never prompts) and points at the grant when
+  it is missing; interactive failures just say re-run.
+- The root install syncs `/etc/hosts` under elevation, so Safari works
+  the moment setup finishes. `setup`'s hosts step verifies the block is
+  already present instead of failing unprivileged on re-runs, and
+  `yamine hosts sync` re-runs itself elevated when the direct write
+  needs root.
+- The CA is trusted into the System keychain silently while elevated
+  (all users, no GUI popup); unprivileged trust keeps the login
+  keychain.
+- Progress UX: the root half of the install prints stage lines as it
+  works, and the proxy-start wait shows a rotating spinner on a terminal
+  (dots elsewhere), resolving to a clean "proxy is up" line.
+
+### Changed
+
+- launchctl uses the modern system-domain verbs
+  (`bootstrap`/`bootout`/`enable`/`kickstart` — the puma-dev/portless
+  pattern); the legacy `load`/`unload` are rejected by current macOS.
+  The best-effort pre-install bootout is silenced — its "Boot-out
+  failed: 5" noise on a first install looked like a failure.
+- Every privileged execution path (sudo re-exec, launchctl, systemctl,
+  `security`) flows through one injectable `Command` seam, so the test
+  suite never shells out to real privileged commands.
+
+### Tests
+
+- Hermetic and CI-safe suite: no real sudo/security/launchctl in tests;
+  exact-argument expectations on the `Command` seam, source-pinned
+  regressions for the launchctl verbs, root-owned plist and stage
+  progress.
+- New coverage: setup runs the real elevation path to "Setup complete"
+  (regression for the mid-flow exit), hosts-step write/verify/skip
+  behavior, `Hosts.synced?`, terminal spinner vs. off-tty dots, e2e
+  proof that a TLS daemon survives the plaintext probe, and both
+  elevation-failure hint paths. 182 unit + 23 e2e, all green.
+
+
+## [0.2.0] — 2026-09-07
+
+### Changed
+
+- `cli.rb` (757 lines) split into command objects behind a shared
+  Context: `cli/boot.rb` (run/boot/supervision), `cli/routes.rb`
+  (get/alias/list/prune/stop/restart/log/status/open),
+  `cli/system.rb` (proxy/service/hosts/trust/clean/doctor/kamal).
+- Default `rake test` runs the fast unit suite (~6s); `rake test:e2e`
+  runs daemon/TLS/live-boot tests; `rake test:all` runs everything.
+
+### Added
+
+- Daemon-owned supervision (puma-dev model): managed apps idle-stop
+  after 15 minutes (`YAMINE_IDLE_TIMEOUT`), stop when tmp/restart.txt
+  changes, and boot transparently on the next request.
+- `yamine stop` (exit 0 stopped / 2 no route / 3 backend already
+  gone), `restart`, `log [-f] [n]`, `status` (effective naming context),
+  `open [name]` (browser). `list` shows backend liveness per route.
+- Root-owned `service install` (launchd/systemd) binding 80/443 at boot
+  with the invoking user's state dir; sudo re-exec when needed.
+- All root write paths chown state back to the invoking user; `doctor`
+  reports an unwritable state dir plainly. The privileged auto-start
+  re-execs under `sudo` with the correct state dir.
+- Bounded proxy concurrency (`YAMINE_MAX_CONNECTIONS`, 503 past the
+  cap), mtime-based route cache (no TTL race for boot-then-curl), IPv4+IPv6
+  loopback listeners, dual-stack `ours?` health check.
+- `get` inherits variant/TLD context from the current directory
+  (`get backend` in a fix-ui worktree -> fix-ui.backend.localhost);
+  `--service/--variant/--tld` overrides.
+- `alias` accepts full hostnames on any TLD and honors YAMINE_TLD.
+- `kamal` snippet resolves the app from the directory; `--app/--domain`
+  flags and YAMINE_KAMAL_DOMAIN.
+- `clean` untrusts the CA from the OS trust store.
+- `--proc <name>` picks a specific Procfile process.
+- Ships the `yamine` agent skill (ask/skills/yamine/SKILL.md).
+- `test:e2e` / `test:all` rake tasks; CI matrix (3.2/3.3/3.4/4.0),
+  macOS e2e leg, fixture-sweep job.
+- Ownership module, framework fixtures (sinatra-modular,
+  foreman-`$PORT`, hanami2 slice layout, jekyll livereload), SKILL.md
+  "when NOT to use" section, README non-goals, vite/Shakapacker recipe.
+- Host authorization patterns default TLDs from `YAMINE_TLD`.
+- WebSocket Upgrade end-to-end test (RFC 6455 handshake + frame echo),
+  hop-loop 508 rejection, chunked framing, and spinning-loop fix.
+
+### Fixed
+
+- Daemon spawn and service install resolved the yamine binary one
+  directory too high — `proxy start` failed outright; failures now
+  include the proxy log tail.
+- Keep-alive connections now rewrite headers (X-Forwarded-Proto) on
+  every request, not just the first — request 2+ previously reached the
+  backend unrewritten, breaking ssl detection and OmniAuth callbacks.
+- Ctrl+C / TERM stops the backend process (no orphans); the CLI exits
+  when the backend dies, cleaning up routes.
+- SNI certificate minting is arity-agnostic across ruby-openssl versions
+  (callback args differ; a raise surfaced as an unrecognized-name alert).
+- Proxy honors HTTP/1.1 framing per request: Content-Length bodies are
+  forwarded exactly; chunked bodies and responses close-delimit.
+- Bidirectional streaming terminates promptly on `Connection: close`
+  (each pump direction closes its peer on EOF).
+- `alias --remove` now appends the default TLD.
+- Install generator `source_root` pointed at a doubled path; generator
+  file checks now resolve against `destination_root`.
+- Port-flag injection no longer double-sets an explicit `$PORT`.
+
+
+## [0.1.1] — 2026-09-06
+
+Patch release focused on workstation setup, URL correctness, and proxy reliability.
+
+### Added — `yamine setup` & `yamine start`
+
+- `yamine setup` — one-shot workstation setup for clean
+  `https://<app>.localhost` URLs: trust the local CA, serve port 443
+  (root launchd/systemd service when possible, sudo daemon otherwise),
+  sync `/etc/hosts`, and verify with `doctor`. Each step reports
+  `==>` / `ok` and the first failure aborts with the specific fix.
+- `yamine start` — one-setup-and-go entry point: an idempotent
+  workstation-check-then-boot (`yamine setup` if needed, then the
+  app). `yamine` bare is an alias for it; `yamine setup` stays for
+  explicit re-setup.
+- `askl` — shell-friendly alias binary (`bin/askl`, same entry point as
+  `bin/yamine`). Keep `yamine` in logs and docs so `grep` stays
+  useful.
+
+### Added — DNS-rebinding & log hygiene
+
+- DNS-rebinding boundary: foreign `Host` headers get a bare 404 naming
+  nothing; only hosts under our own configured TLDs see the route-listing
+  404. The proxy takes `--tld` (persisted to `proxy.tlds`) so the boundary
+  follows custom domains. The `X-Ask-Local: 1` health header marks our
+  proxy responses (including 404s) for the `ours?` probe.
+- Log rotation — `proxy.log` and per-app backend logs rotate at 5MB
+  (`YAMINE_LOG_MAX_BYTES`, one generation) before each write. A new
+  `doctor` disk-usage check warns past 100MB of state.
+
+### Fixed
+
+- **Silent `:1355` URL fallback removed.** Privileged-port (443) bind
+  failure is now a hard error pointing at `yamine setup`, never a
+  booted app on `https://app.localhost:1355` that silently corrupts
+  downstream consumers of `YAMINE_URL`. The only port-suffixed URLs
+  are the ones you explicitly ask for (`proxy start -p 1355`).
+- **Health probe `130+?` hang fixed.** The TLS probe's `connect` sat
+  outside the timeout: a TLS handshake against a foreign plain-HTTP
+  server blocked in `connect` for 60s+. Connect is now inside the
+  timeout, plain HTTP is tried first (our proxy answers plain HTTP via
+  byte-peeking even on the TLS port), and any HTTP response without our
+  header short-circuits as foreign — only silent servers wait for the
+  timeout.
+- `start` dispatch was missing from the dispatcher despite being in
+  `SUBCOMMANDS`, so `yamine start` fell through to `run_named` with
+  "start" as an app name. The kamal-help append drifted to a 6-space
+  indent. Both are fixed and pinned by tests.
+- `base64` declared as a runtime dependency (it left the default gems in
+  Ruby 3.4).
+- Missing `require "optparse"` lost in the CLI split.
+
+### Tests — new coverage for this patch
+
+- `start_test.rb` — help, fast-path vs. needs-setup branching, and the
+  non-interactive hard-error message.
+- `setup_test.rb` — four-step orchestration (all-steps-stubbed), first-failure
+  abort with fix text, `--no-service` flag, and the three `ensure_proxy!`
+  hard-error paths (non-interactive, foreign port, spawn failure) plus
+  explicit-port URL honesty and responding-foreign-server fast classification.
+- Pinned under `bundle exec rake test` (fast unit suite); no `test:e2e`
+  needed for these.
+
+
+## [0.1.0]
+
+### Added
+
+- Initial release: explicit-run reverse proxy giving every Ruby app a
+  stable `https://<app>.localhost` URL.
+- Zero-flag name inference (Rails module, gemspec, package.json, git
+  root, directory) with `yamine.json` overrides.
+- `{variant}.{service}.{app}.{tld}` hostname composition; linked-worktree
+  branch prefixes; custom `--tld` including owned domains.
+- Managed Rack boot on unix sockets (rackup/TCP fallback); run mode with
+  `PORT`/`YAMINE_URL` injection; `Procfile.dev` and static-site
+  framework detection.
+- Local CA + per-host SNI certs (in-memory LRU), `trust`, `hosts sync`,
+  `doctor`, `prune`, `alias`, `get`, `kamal` snippet.
+- Explicit `--port/--host` injection for port-ignoring CLIs (Jekyll,
+  Middleman, Bridgetown), skipped when the user already set a port.
+
+### Changed
+
+- Rails module inference kebab-cases CamelCase and digit runs:
+  `Rails8Min` → `rails-8-min` (was `rails8min`).
+- Monorepo `yamine.json` with an `apps:` map is discovered by walking
+  up from the package directory.
+- `service: web` produces the bare `app.tld` (all other services prefix).
+- Puma 8 command shape (positional `config.ru`; `--rackup` was removed
+  upstream) and spawned backends run unbundled so system/bundle puma is
+  reachable regardless of the invoking bundle.
+- Boot failures include the backend log tail in the error message.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,294 @@
+# yamine
+
+[![Gem Version](https://badge.fury.io/rb/yamine.svg)](https://badge.fury.io/rb/yamine)
+
+Stable named `.localhost` URLs for Ruby development. Gives every Ruby app
+a stable `https://<app>.localhost` URL instead of a memorized port.
+Zero runtime dependencies — Ruby stdlib only (`openssl`, `socket`).
+
+```bash
+gem install yamine
+yamine start          # setup + boot in one go (or plain `yamine`)
+yamine setup          # once per machine: CA trust + port 443 + hosts + verify
+cd ~/code/myapp && yamine
+# -> https://myapp.localhost
+```
+
+
+## Why "yamine"?
+
+**Yamine** (يمين, *yamīn*) is Arabic for "right hand" — the side of blessing
+and good fortune, the hand you keep things close with. It sits next to
+**Kamal** (كمال, *kamāl*, "completeness, perfection"): Kamal completes the
+deploy, Yamine keeps the app at your right hand — local, close, yours.
+
+And yes, if you follow football: *Yamine Kamal* is Lamine Yamal with the
+names flipped. I'm a fan — the kid who nutmegs entire defenses at sixteen
+is exactly the energy local dev should have. The local half of the game,
+played the same way: fast, fearless, and fun to watch.
+
+(For the curious: `yamine` is pronounced "ya-MEEN".)
+
+## The no-fallback promise
+
+yamine never silently degrades to a `:<port>` URL. Clean
+`https://<app>.localhost` requires the proxy on port 443; if 443
+cannot be bound, you get a hard error pointing at `yamine setup`
+— never a booted app on `https://app.localhost:1355` that silently
+poisons OAuth callbacks, mailer hosts, and webhooks downstream.
+
+The only port-suffixed URLs are the ones you explicitly ask for:
+`yamine proxy start -p 1355` (CI/sandboxes where 443 is impossible).
+There the suffix is honest, and `YAMINE_URL` carries it faithfully.
+
+## Port 443: one-time setup, then never again
+
+Binding 443 is privileged, so yamine installs a **root-owned launchd
+service** (macOS) or systemd unit (Linux) that binds 443 at boot — the
+same model as puma-dev and portless. Installing it needs sudo **once per
+machine**; after that, every `yamine` run in any project gets a clean
+`https://<app>.localhost` with no elevation and no prompt.
+
+**Human (interactive):** run setup once — it trusts the CA, installs the
+service, syncs hosts, and verifies:
+
+```bash
+yamine setup
+```
+
+**Agent / CI (no TTY):** the same commands fail fast with guidance,
+because sudo needs a terminal. To pre-provision a machine or image so
+agents can install the service without a prompt, install the scoped
+passwordless-sudo rules once (as an admin):
+
+```bash
+yamine sudoers > /tmp/yamine.sudoers
+sudo install -o root -g wheel -m 440 /tmp/yamine.sudoers /etc/sudoers.d/yamine   # macOS
+sudo install -o root -g root -m 440 /tmp/yamine.sudoers /etc/sudoers.d/yamine   # Linux
+```
+
+`yamine sudoers` prints rules scoped to yamine's own service
+re-exec — the gem's exact ruby + bin path with the `service install
+--internal` / `service uninstall --internal` subcommands — never a bare
+interpreter. Re-run it after upgrading the gem if the install path
+changes. To undo: `sudo rm /etc/sudoers.d/yamine`.
+
+## The one-file model
+
+Every app declares `config/local.yml` (Kamal-style) — the single source
+of truth for service name, proxy TLD/host, processes, and env:
+
+```yaml
+service: myapp
+proxy:
+  tld: localhost
+processes:
+  web:
+    cmd: bundle exec puma -b tcp://127.0.0.1:$PORT config.ru
+    proxy: true
+  worker:
+    cmd: bundle exec sidekiq
+    proxy: false
+```
+
+`yamine init` creates the file (migrating an existing Procfile);
+Rails apps need no extra gem — yamine injects `RAILS_DEVELOPMENT_HOSTS`
+so the proxied hostname is allowed automatically. `yamine`
+then boots every process, assigns each a `$PORT`, injects
+`YAMINE_URL`, registers routes for HTTP processes, supervises the
+whole tree, and cleans up when one exits.
+
+Variants are file overlays: `config/local.<variant>.yml` deep-merges on
+top of `config/local.yml`, selected by `YAMINE_VARIANT` (Kamal's
+destination pattern).
+
+`.localhost` resolves to loopback natively in Chrome, Firefox, and Edge —
+no DNS server, no `/etc/resolver`. Safari may need `yamine hosts sync`.
+
+## Hostname shape
+
+```
+{variant}.{service}.{app}.{tld}
+```
+
+| Axis | Example | Source |
+|---|---|---|
+| app | `myapp` | inferred, `--name`, `yamine.json`, `YAMINE_NAME` |
+| service | `api.myapp` | `--service`, `YAMINE_SERVICE` (`web` stays bare) |
+| variant | `fix-ui.myapp` | `--variant`, `YAMINE_VARIANT`, linked worktree branch |
+| tld | `myapp.preview.example.com` | `--tld` (default `localhost`) |
+
+Linked git worktrees get a branch prefix automatically
+(`fix-ui.myapp.localhost`); the main checkout keeps the bare name.
+Pass `--branch` (or `YAMINE_BRANCH=1`) to prefix by current branch
+outside worktrees. `main`/`master`/detached HEAD never prefix.
+
+```bash
+yamine                                          # -> https://myapp.localhost
+yamine --service api                            # -> https://api.myapp.localhost
+yamine --variant demo                           # -> https://demo.myapp.localhost
+yamine --tld preview.example.com                # your own domain (OAuth parity)
+```
+
+## Commands
+
+```bash
+yamine                        # infer name, boot app
+yamine run -- <cmd>           # run explicit command through proxy
+yamine <name> <cmd>           # explicit app name
+yamine get <name>             # print URL for cross-service wiring
+yamine alias <name> <port>    # static route (e.g. Docker)
+yamine list [--json]          # show active routes (+ backend liveness)
+yamine status [--json]        # show effective naming context here
+yamine doctor [--json]        # machine-readable health checks
+yamine open [name]            # open the app URL in a browser
+yamine doctor                 # read-only health check (state, proxy, routes, DNS, CA)
+yamine trust                  # add local CA to system trust store
+yamine clean                  # remove state and hosts entries
+yamine prune                  # remove stale routes
+yamine stop                   # stop this app's backend + routes
+yamine restart                # touch tmp/restart.txt (managed apps reboot)
+yamine log [-f] [n]           # tail (or follow) this app's backend log
+yamine proxy start|stop       # control the proxy
+yamine service install|status|uninstall   # root-owned OS startup service
+yamine hosts sync|clean       # manage /etc/hosts entries
+yamine kamal <variant>        # preview-deploy snippet for Kamal
+```
+
+Child processes receive `YAMINE_URL` (the stable URL — use it for
+OAuth callbacks, mailer hosts, webhook URLs), `PORT`, and `HOST`.
+
+## Frameworks
+
+Rails and bare Rack (`config.ru`) boot managed on a unix socket (Puma
+when available; `rackup` on TCP otherwise). `Procfile.dev`/`bin/dev`,
+Jekyll, Bridgetown, and Middleman run in run mode with `PORT` injected
+(port-ignoring CLIs get explicit `--port/--host` flags). Anything else:
+`yamine run -- <cmd>`.
+
+```bash
+yamine --proc web             # boot a specific Procfile process
+yamine --proc worker          # (first line is the default)
+```
+
+Procfile lines that are compound (`&&`, `||`, `|`, `;`) are refused with
+guidance rather than silently mis-injected.
+
+For Rails integration (hosts, Action Cable origins, Procfile rewrite,
+generators) — deprecated; core covers Rails now.
+
+## WebSockets
+
+Action Cable and any Rack hijack-based WebSocket server work through the
+proxy: HTTP/1.1 `Upgrade` requests are byte-forwarded to the backend
+after header rewriting, and the tunnel stays raw for the life of the
+connection (verified end-to-end: RFC 6455 handshake + frame echo).
+
+## Machine-readable output
+
+`list`, `status`, and `doctor` accept `--json` with stable keys for
+agents and scripts (`DevUrl` in ask-ruby-harness consumes the same data
+in-process). Hostnames that fall outside the configured TLDs get a bare
+404 naming nothing — route names never leak to foreign hosts
+(DNS-rebinding boundary).
+
+## Log rotation
+
+`proxy.log` and per-app backend logs rotate at 5MB
+(`YAMINE_LOG_MAX_BYTES`), keeping one generation. `doctor` warns
+when the state dir passes 100MB.
+
+## Supervision
+
+Managed apps are supervised by the proxy daemon, not the CLI:
+
+- idle backends stop after 15 minutes (`YAMINE_IDLE_TIMEOUT`
+  seconds; `0` disables) and boot transparently on the next request
+- touching `tmp/restart.txt` stops the backend; next request reboots it
+- crashed backends are detected and rebooted on the next request
+- daemon shutdown stops every supervised backend (no orphans)
+
+Run-mode (TCP) routes and static aliases are never supervised.
+
+## Ask ecosystem integration
+
+| Gem | How yamine helps |
+|---|---|
+| `ask-rails` | yamine core injects `RAILS_DEVELOPMENT_HOSTS`; Cable origins + helpers live in the deprecated yamine-rails |
+| `ask-rails-harness` | Its 9 Rails tools (routes, models, DB, logs) run against the app the proxy serves; `DevUrl` gives the agent the stable URL instead of a guessed port |
+| `ask-app-server` | The JSON-RPC/stdio session host sits behind `https://api.<app>.localhost`; editor/IDE clients use `yamine get` output |
+| `ask-mcp` | MCP servers get named URLs per service (`mcp.<app>.localhost`), no port coordination across servers |
+| `ask-skills` | Ships the `yamine` skill (auto-discovered): boot via `yamine`, wire via `get`, callbacks from `YAMINE_URL` |
+| `ask-ruby-harness` | `DevUrl` tool: structured `list`/`get` for agents, audit-logged like every other tool |
+
+What we do differently from Kamal for local dev: Kamal + kamal-proxy
+own production (Let's Encrypt, zero-downtime deploys, multi-host).
+yamine never serves prod — but the variant slug is shared, so
+`fix-ui.myapp.localhost` locally and `myapp-fix-ui.preview.example.com`
+in staging (via `yamine kamal fix-ui`) are the same branch everywhere.
+
+## Prior art
+
+Same problem, three generations — yamine borrows from all of them:
+
+- **Pow** (2011–2017, macOS-only Rack): the ergonomics — zero-config
+  names, `tmp/restart.txt`, `.powrc` env loading. Left behind: Nack
+  workers, firewall forwarding, HTTP-only, unmaintained.
+- **puma-dev** (Go, macOS/Linux): the engine semantics — Puma on unix
+  sockets, lazy boot, idle kill, restart.txt watching, in-memory dynamic
+  TLS, per-route status. Kept as behavior, reimplemented in Ruby.
+- **portless** (Node 24, any stack): the agent interface — explicit run
+  ownership, `PORTLESS_URL`-style env contract, `get/doctor/prune`,
+  worktree prefixes, custom-TLD OAuth parity, SKILL.md pattern.
+
+Build vs borrow decision: yamine is pure Ruby (stdlib + base64),
+not a wrapper around puma-dev's Go core. Rationale: zero-toolchain
+distribution (`gem install`, no Go/Node), the ask-core zero-dependency
+philosophy, and full control over the agent surface (route store,
+supervision, skills). puma-dev's semantics were ported, not its binary.
+
+## Non-goals (deliberate)
+
+- **HTTP/2.** Ruby dev servers serve a handful of requests, not Vite's
+  hundreds of unbundled files — the multiplexing win doesn't apply, and
+  ALPN/HPACK/stream state would triple the proxy's auditable surface.
+  Revisit only on benchmarked HMR latency. (Consequence: no HTTP/2
+  extended-CONNECT bridging; browsers never negotiate h2 here, so plain
+  Upgrade tunneling covers Action Cable fully.)
+- **LAN/mDNS and Tailscale/ngrok tunnels.** mDNS behaves differently on
+  every network; tunnels need third-party CLIs, auth state, and accounts.
+  The 95% "show this branch to someone" case is covered by the `kamal`
+  preview-deploy snippet on real infrastructure instead of a laptop
+  tunnel. Kamal owns remote access; yamine owns local naming.
+- **Production serving.** The proxy binds loopback only, the CA is
+  self-signed, and there is no request buffering, rate limiting, or
+  access control. Anything real goes through Kamal + kamal-proxy.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## Non-goals (deliberate)
+
+- **HTTP/2.** Ruby dev servers serve a handful of requests, not Vite's
+  hundreds of unbundled files — the multiplexing win doesn't apply, and
+  ALPN/HPACK/stream state would triple the proxy's auditable surface.
+- **LAN/mDNS or tunneled sharing.** mDNS behaves differently on every
+  network; third-party tunnels need CLIs, auth state, and accounts.
+  The `kamal` preview-deploy snippet covers "show this branch to
+  someone" on real infrastructure instead.
+- **Production serving.** The proxy binds loopback only, the CA is
+  self-signed, and there is no buffering or rate limiting.
+
+
+The `yamine-apps` fixture fleet (sibling checkout) exercises
+detection, inference, and boot across Rails variants, Roda, Sinatra,
+bare Rack, Jekyll, compound Procfiles, and a monorepo. CI runs the
+fixture sweep automatically.
+
+## License
+
+MIT

data/bin/yamine

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/yamine"
+
+exit Yamine::CLI.run(ARGV)