yamine 0.15.2 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0fb00156c920d8b49a4116be04c671904877e26cb75816d3f7d05d899f413be
-  data.tar.gz: 28c31ed6f7e03fd453b9fa00c1372c36701b675b015c9de906223934b3ade84f
+  metadata.gz: 3987eef1f0bc39291b8d264fd4b569fcb54106c23e78150594f62d86ca2d0351
+  data.tar.gz: e98404e9655e78861c289cb320bf544564e07e65e06fe32a496d5a3ff4ee52b9
 SHA512:
-  metadata.gz: 69ce5134433ef830e42ba29420ab0ab17a6f39ec39cb885e534cbdae485cc6360270ad45b6e31b99191988a0f2d3fd6d20b5a0073df9469478ebeddc0f092c03
-  data.tar.gz: 037bc4d5fd9ac1767304c1a6bee32572bc28a95cd64fde42414c6ff38624dd74c3a0be05966bd2d32a91e5c3664ba99ac1a5fac50fcd81b1a673a48e75b990b6
+  metadata.gz: 20018aea0d2229ab0c6c814d15deaeb176649fcdaa81937eb2c6f223607e50f2c34256ed078aca6ef0bb0a114cbd865bd6187dd2f74a1b981d2dbd7c8d7e141d
+  data.tar.gz: 808f2b4151de99fa3fe71ba8bbbfce6eb7dbe63298bea1da3c4fd05a5baea9da7f5d797ae792057f8ddd2f5500b19da47fd97af1641481764eb8f051605a0c0f

data/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.17.0] — 2026-09-23
+
+### Added
+
+- **Per-worktree `.env` files — hand-run isolation without touching the
+  app's config.** `worktree add` writes `.env` and `.env.development`
+  (the whole development set: `DATABASE_URL` + one `NAME_DATABASE_URL`
+  per configuration) and `.env.test` (`PRIMARY_DATABASE_URL` — the key
+  Rails checks *before* `DATABASE_URL` for a flat test config, so the
+  test URL wins no matter what order a loader reads the files in).
+  Any dotenv loader picks them up — hand-run `rails console`,
+  `rails test`, and `db:migrate` land on the worktree's databases with
+  zero yamine-specific code in `database.yml`. Mode 0600, git-excluded
+  automatically, removed with the worktree.
+
+### Changed
+
+- **`.yamine-db-suffix` (0.16.0) is replaced by the `.env` files above.**
+  The database.yml suffix hook is no longer needed — apps keep a plain
+  boring config. Legacy marker files are deleted on sight.
+- **The conformance check now diagnoses precisely.** `worktree add`
+  re-probes after writing `.env` and distinguishes the two ways an app
+  can fail to isolate hand-run commands: no dotenv loader loaded the
+  file (fix: one Gemfile line), vs `database.yml` supplies `url:` keys,
+  which Rails gives *precedence over the entire environment* —
+  `merge_db_environment_variables` skips URL-shaped configs, so neither
+  injected env nor `.env` can ever redirect them (fix: component form —
+  `database:`, `host:`, `username:` — for development/test).
+- **Worktrees copy only the credential keys their own environments
+  need**: `config/master.key`, `config/credentials/development.key`,
+  `config/credentials/test.key`. Production and staging keys no longer
+  travel into throwaway directories.
+
+### Fixed
+
+- **`worktree add` could purge the MAIN checkout's test database.**
+  The per-worktree test schema preparation ran under
+  `RAILS_ENV=development`, where the flat test config resolves to the
+  BASE name (the environment-override merge only applies to the current
+  environment's configs) — so `db:test:prepare` purged and reloaded
+  *main's* `myrr_markdown_test` during a worktree add, observed live.
+  It now runs under `RAILS_ENV=test`, where dotenv loads `.env.test`
+  and the override lands on the worktree's own test database; a
+  regression test pins the environment.
+
+## [0.16.0] — 2026-09-23
+
+### Added
+
+- **Multi-database worktrees — the whole set, asked not guessed.**
+  `worktree add` now probes the app itself (`bin/rails runner` resolves
+  database.yml + credentials inside the app process; yamine never parses
+  config or touches a key) and provisions every database it declares:
+  each name gains a collision-guarded per-worktree suffix, the claim
+  records all names plus the server coordinates, schemas load once, and
+  `remove`/`clean` drop the entire set as a unit — orphaned worktrees
+  drop from the claim alone, without the app even booting. Boot injects
+  `DATABASE_URL` plus `NAME_DATABASE_URL` per configuration (Rails' own
+  convention), so supervised processes are isolated even in apps that
+  never heard of yamine. New surface: `yamine db describe` prints what
+  the app actually resolves (passwords masked), `db list` and
+  `worktree list` show every database under a claim, and `db create`
+  re-probes — run it after the app grows a database to self-heal every
+  worktree.
+- **`.yamine-db-suffix` — hand-run commands isolate too.** `add` writes
+  a token file (git-excluded automatically); a four-line suffix hook at
+  the top of `config/local.yml`'s sibling `database.yml` (see README)
+  makes a hand-run `rails console`, `rails test`, or `db:migrate` in
+  the worktree resolve to the worktree's databases — env injection only
+  ever reaches processes yamine spawns. Conformance is proven at
+  creation ("database.yml reads .yamine-db-suffix"); an app without the
+  hook still gets fully isolated boots via env, and gets told exactly
+  what the gap is at that moment.
+- **The test database joins the claim.** It is probed and suffixed like
+  the rest, schema-prepared on first creation (`db:test:prepare` — Rails
+  will not load schema into an empty test database by itself), and
+  dropped at teardown — a fresh worktree runs `rails test` as-is, and
+  no suffixed test database is ever left behind.
+- **Credential keys travel to worktrees.** `add` now copies
+  `config/master.key` and `config/credentials/*.key` (mode 0600) with
+  the rest of the per-checkout config — a credentials app could not
+  even boot in a fresh worktree before, let alone resolve its
+  databases.
+
+### Changed
+
+- **The main checkout of a Rails app boots in silence.** The
+  "app looks database-backed but no DATABASE_URL template found"
+  warning no longer fires on a main checkout — the app's own databases
+  ARE its databases; isolation is a worktree concern, and worktrees
+  get it from the probe.
+- **`clean` no longer gets stuck forever on unresolvable legacy
+  claims.** A pre-multi-database claim whose app declares no template
+  (credentials apps never did) could never be resolved by any future
+  command, so every `worktree clean` anywhere failed on it until it was
+  removed by hand. Such claims are now forgotten with a warning that
+  names the database, so a real leftover stays droppable by hand while
+  `clean` moves on.
+- The claims file (`databases.json`) is written mode 0600 —
+  multi-database claims carry the app's resolved connection URLs.
+
+### Fixed
+
+- **Every real Postgres drop has always crashed.** `pg_drop` passed
+  the environment as a keyword to `Open3.capture2` (spawn takes it
+  positionally), so the moment a `dropdb` was actually attempted —
+  `worktree remove`, `worktree clean`, any teardown against a reachable
+  server — it raised `ArgumentError` mid-teardown, after routes were
+  already stopped. Unit tests never saw it (an unreachable server
+  returns before the spawn). Drops now run, verified against a real
+  five-database app end to end.
+- **Boots of dependency-less Node stubs failed forever.** A committed
+  `package.json` with no dependencies (`{}`) demanded a `node_modules`
+  directory that `npm install` itself will never create — every fresh
+  clone and worktree of such an app failed its pre-flight. The check
+  now fires only when the manifest actually declares dependencies (an
+  unparseable manifest keeps the old conservative behavior).
+- **A hostname with no route answers 503, not 404.** The proxy was
+  answering 404 for "no app registered for this hostname" — the same status
+  an app gives for a path it does not have. A machine client (a health
+  check, an API client, an agent) that trusts the status concluded the app
+  had answered and went looking for a bug in the app's routes, when the app
+  was not running at all. It now answers 503 Service Unavailable with the
+  same helpful page (parent app, its directory, `yamine start`), so the
+  status alone says the app is not there — matching the 502 a registered
+  route with a dead backend already gets. Foreign hosts keep their bare 404
+  that names nothing.
+
 ## [0.15.1] — 2026-09-22
 
 ### Fixed

data/README.md

@@ -170,9 +170,11 @@ yamine worktree clean                # tear down everything already merged
 ```
 
 `add` lands the worktree beside the repo, copies the gitignored
-per-checkout config (`config/local.yml`, `config/local.secrets`) the
-branch needs, runs `bundle install`, and pre-creates the per-worktree
-database with schema — the next step is just `yamine start` in it.
+per-checkout config (`config/local.yml`, `config/local.secrets`,
+`config/master.key`, and the development/test credential keys) the branch needs, runs
+`bundle install`, asks the app what databases it has, and provisions
+the whole set with schema — the next step is just `yamine start` in
+it.
 
 `clean` is the done-and-merged sweep: it tears down every worktree
 whose branch is merged (stop, drop database, remove worktree, delete
@@ -190,6 +192,93 @@ yamine --variant demo                           # -> https://demo.myapp.localhos
 yamine --tld preview.example.com                # your own domain (OAuth parity)
 ```
 
+### Multi-database apps
+
+A Rails multi-database app (five databases is normal: primary, cache,
+queue, cable, errors) gets **the whole set** per worktree — asked, not
+guessed. `worktree add` boots `bin/rails runner` once inside the app so
+database.yml and credentials resolve exactly as the app would resolve
+them (yamine never parses config or touches a key), suffixes every
+database name with a collision-guarded per-worktree token, creates and
+schema-loads them, prepares the test database, and records names plus
+server coordinates in the claim. Boot injects `DATABASE_URL` and one
+`NAME_DATABASE_URL` per configuration (Rails' own convention).
+`remove`/`clean` drop the entire set as a unit — including from an
+orphaned claim whose directory is already gone, without the app
+booting.
+
+```bash
+yamine db describe          # what THIS checkout resolves to (passwords masked)
+yamine db list              # every claim, every database under it
+yamine db create            # re-probe + provision (run after the app grows a database)
+```
+
+**Two one-time app requirements, both boring:**
+
+1. *Component-form development/test config.* Environment overrides —
+   injected `DATABASE_URL`/`NAME_DATABASE_URL` and the per-worktree
+   `.env` — only apply to component keys (`database:`, `host:`). A
+   `url:` key (the usual credentials-driven style) takes precedence
+   over the *entire* environment: Rails skips URL-shaped configs when
+   merging environment variables, so nothing injected or loaded can
+   redirect them. Development and test should read like a plain Rails
+   file:
+
+   ```yaml
+   default: &default
+     adapter: postgresql
+     encoding: unicode
+     host: <%= ENV.fetch("DB_HOST", "localhost") %>
+     username: postgres
+
+   development:
+     primary:
+       <<: *default
+       database: myapp_development
+     cache:
+       <<: *default
+       database: myapp_development_cache
+       migrations_paths: db/cache_migrate
+
+   staging:
+     primary: &primary_staging
+       <<: *default
+       url: <%= Rails.application.credentials.dig(:database, :primary, :url) %>
+   ```
+
+   Staging/production keep doing whatever they do — yamine only ever
+   redirects development and test.
+
+2. *A dotenv loader* — `gem "dotenv-rails", groups: [:development, :test]`
+   (any dotenv loader works). That is what reads the files
+   `worktree add` writes into the worktree:
+
+   - `.env` / `.env.development` — the whole development set
+     (`DATABASE_URL` plus one `NAME_DATABASE_URL` per configuration),
+   - `.env.test` — the test URL under `PRIMARY_DATABASE_URL`, the key
+     Rails checks *before* `DATABASE_URL` for a flat test config, so it
+     wins regardless of the order a loader reads the files in.
+
+   Mode 0600, git-excluded automatically, removed with the worktree.
+   A hand-run `rails console`, `rails test`, or `db:migrate` in the
+   worktree therefore lands on the worktree's own databases — with
+   **zero yamine-specific code in `database.yml`, ever**.
+
+`worktree add` proves both after writing the files: you will see
+`.env loaded — hand-run commands are isolated too`. A warning instead
+names which requirement is missing — no loader ran, or the config is
+`url:`-shaped — and the exact fix. Supervised boots are isolated via
+injected env either way (component form permitting).
+
+Credential keys travel too: `config/master.key`,
+`config/credentials/development.key`, and
+`config/credentials/test.key` are copied at mode 0600. Production and
+staging keys stay in the main checkout where they belong.
+
+The main checkout never gets `.env` files or a suffix: its databases
+are its databases, untouched.
+
+
 ## Subdomains are opt-in
 
 A route answers its exact hostname. `*.myapp.localhost` reaches
@@ -207,8 +296,9 @@ yamine alias tenant1 4001 --wildcard   # one route, its subdomains
 Off is the useful default. An unregistered label under a live app is far
 more likely to be a worktree whose stack is stopped than a tenant, and
 handing that label to the parent app means HTTP 200 with the wrong code.
-Instead the request 404s and names the parent app, its directory, and how
-to start it. `yamine status` reports which mode an app is in.
+Instead the request fails with 503 and names the parent app, its directory,
+and how to start it — the app is not there, which is not the same statement
+as the app answering 404. `yamine status` reports which mode an app is in.
 
 ## Commands
 
@@ -225,7 +315,7 @@ yamine open [name]            # open the app URL in a browser
 yamine trust                  # add local CA to system trust store
 yamine clean                  # remove state and hosts entries
 yamine prune                  # remove stale routes
-yamine db list|create|drop    # per-worktree databases
+yamine db list|create|drop|describe    # per-worktree databases (multi-database aware)
 yamine worktree list|add|remove|clean   # worktree lifecycle
 yamine stop                   # stop this app's backend + routes
 yamine restart                # touch tmp/restart.txt (managed apps reboot)

data/lib/ask/skills/yamine/SKILL.md

@@ -108,15 +108,40 @@ yamine worktree clean [--dry-run]
 ```
 
 `add` creates the git worktree beside the repo, copies the gitignored
-per-checkout config (`config/local.yml`, `config/local.secrets`), runs
-`bundle install`, and pre-creates the per-worktree database — then boot
-with `yamine start` inside it. `clean` tears down every worktree whose
-branch is merged (stops backends, drops the database, removes the
-worktree, deletes the branch) and forgets claims of directories that
-vanished. It never touches uncommitted work; unmerged branches survive
-everything except `remove --force`. Prefer `clean --dry-run` first, and
-`clean` over `rm -rf` — a removed worktree leaves no routes, database,
-or stale hosts entries behind.
+per-checkout config (`config/local.yml`, `config/local.secrets`,
+`config/master.key`, and the development/test credential keys — never
+production/staging keys), runs `bundle install`, **asks the app what
+databases it has** (one `bin/rails runner` probe — database.yml and
+credentials resolve inside the app; yamine never parses them), and
+provisions the whole set with schema — every database of a
+multi-database app gets a per-worktree suffix, the test database
+included and schema-prepared, so `rails test` runs as-is. It writes
+`.env` / `.env.development` (the development set) and `.env.test`
+(`PRIMARY_DATABASE_URL` — the key Rails checks first for a flat test
+config) into the worktree, git-excluded automatically. Then boot with
+`yamine start` inside it. `remove` and `clean` drop the entire set as
+a unit — including from an orphaned claim whose directory is gone,
+without booting the app — and `clean` never touches uncommitted work;
+unmerged branches survive everything except `remove --force`. Prefer
+`clean --dry-run` first, and `clean` over `rm -rf` — a removed
+worktree leaves no routes, databases, or stale hosts entries behind.
+
+`yamine db describe` shows what the current checkout resolves to
+(passwords masked); `yamine db list` shows every database under every
+claim; `yamine db create` re-probes and self-heals (run it in each
+worktree after the app grows a database).
+
+Isolation reaches two places: supervised boots via injected
+`DATABASE_URL` / `NAME_DATABASE_URL` env vars, and hand-run commands
+(`rails console`, `rails test`, `db:migrate`) via the `.env` files —
+which require a dotenv loader in the app (`gem "dotenv-rails",
+groups: [:development, :test]`) and **component-form development/test
+config** (`database:` keys, never `url:` — a `url:` key takes
+precedence over the entire environment, so nothing injected or loaded
+can redirect it; staging/production URLs are fine, yamine never
+touches those envs). `worktree add` verifies both and prints
+`.env loaded — hand-run commands are isolated too`; its warning names
+exactly which requirement is missing and the fix.
 
 ## Subdomains are opt-in
 
@@ -124,10 +149,12 @@ A route answers its exact hostname. `*.myapp.localhost` reaches the app
 only if it asked (`proxy.subdomains: true` in `config/local.yml`, or
 `yamine alias <name> <port> --wildcard` for one route).
 
-So a worktree whose stack is not running gets a 404 that names the parent
-app, its directory, and `yamine start` — not the parent app's code. If
-you hit a `.localhost` URL that loads but looks wrong, check you started
-the worktree you think you did; `yamine status` in it prints the URL.
+So a worktree whose stack is not running gets a 503 that names the parent
+app, its directory, and `yamine start` — not the parent app's code. The
+status says the app is not there, so a script can tell "not running" from
+"the app answered 404". If you hit a `.localhost` URL that loads but looks
+wrong, check you started the worktree you think you did; `yamine status` in
+it prints the URL.
 
 ## First time on a machine