yamine 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66abd82532420b13b18597a4d71b51485f06b09c14d5b0d4c3e777d8056e7145
-  data.tar.gz: be3bcb4b88ba0eeb444ed33d10c14c217cf145073f2f8cce78e62e4dc138bffd
+  metadata.gz: 3987eef1f0bc39291b8d264fd4b569fcb54106c23e78150594f62d86ca2d0351
+  data.tar.gz: e98404e9655e78861c289cb320bf544564e07e65e06fe32a496d5a3ff4ee52b9
 SHA512:
-  metadata.gz: e03ba4c4510f03424190fdf58f0c5f6db6183425b75c31628df99724bf592edc068ab13cd6bf7abd28b04c577025b4ec913eb87d892b78524aab7aee35e83dbd
-  data.tar.gz: 9eaa287f5ee45e231cd82f29c8dbf0bf0f3e197cc825dfeccccb4f39ff02c826167d32516c23fef7c2a39804d662a69b417e082b1b9d2e6f1b562ce63597a95e
+  metadata.gz: 20018aea0d2229ab0c6c814d15deaeb176649fcdaa81937eb2c6f223607e50f2c34256ed078aca6ef0bb0a114cbd865bd6187dd2f74a1b981d2dbd7c8d7e141d
+  data.tar.gz: 808f2b4151de99fa3fe71ba8bbbfce6eb7dbe63298bea1da3c4fd05a5baea9da7f5d797ae792057f8ddd2f5500b19da47fd97af1641481764eb8f051605a0c0f

data/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 ## [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

data/README.md

@@ -171,7 +171,7 @@ 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`,
-`config/master.key`, `config/credentials/*.key`) the branch needs, runs
+`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.
@@ -200,12 +200,12 @@ 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, and records names plus server coordinates in the
-claim. Boot injects `DATABASE_URL` and one `NAME_DATABASE_URL` per
-configuration (Rails' own convention), so supervised processes are
-isolated even in an app that never heard of yamine. `remove`/`clean`
-drop the entire set as a unit — including from an orphaned claim whose
-directory is already gone, without the app booting.
+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)
@@ -213,54 +213,71 @@ yamine db list              # every claim, every database under it
 yamine db create            # re-probe + provision (run after the app grows a database)
 ```
 
-**Hand-run commands.** Env injection only reaches processes yamine
-spawns; a `rails console`, `rails test`, or `db:migrate` you run by
-hand reads the environment you gave it. For those, opt the app in with
-the suffix hook — a one-time addition at the top of
-`config/database.yml`:
-
-```erb
-<%
-  yamine_suffix = begin
-    f = Rails.root.join(".yamine-db-suffix")
-    f.exist? ? f.read.strip : ""
-  rescue StandardError
-    ""
-  end
-  yamine_db_url = lambda do |url|
-    next url if yamine_suffix.empty? || url.nil? || url.to_s.empty?
-    require "uri"
-    begin
-      uri = URI.parse(url.to_s)
-      uri.path = "#{uri.path}_#{yamine_suffix}" if uri.path && uri.path != "/"
-      uri.to_s
-    rescue URI::InvalidURIError
-      url
-    end
-  end
-%>
-```
-
-Then wrap each database URL (and a bare test database name) with it:
-
-```yaml
-development:
-  primary:
-    url: <%= yamine_db_url.call(Rails.application.credentials.dig(:database, :primary, :url)) %>
-test:
-  database: <%= ENV.fetch("TEST_DATABASE_NAME") { "myapp_test#{yamine_suffix.empty? ? "" : "_#{yamine_suffix}"}" } %>
-```
-
-`worktree add` writes the `.yamine-db-suffix` token (git-excluded
-automatically) and then *proves* the hook works — you'll see
-`database.yml reads .yamine-db-suffix — hand-run commands are isolated
-too`. Without the hook, supervised boots are still fully isolated via
-env; `add` says exactly what the hand-run gap is. The test database is
-part of the claim too: created and schema-prepared on first add (so
-`rails test` runs as-is), dropped at teardown — never left behind.
+**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.
 
-The main checkout has no marker file, so nothing changes there: its
-databases are its databases.
 
 ## Subdomains are opt-in
 

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

@@ -109,33 +109,39 @@ 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`,
-credential 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. 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.
+`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).
 
-Supervised boots are isolated via injected `DATABASE_URL` /
-`NAME_DATABASE_URL` env vars. **Hand-run commands are not** — unless
-the app carries the `.yamine-db-suffix` hook from the yamine README at
-the top of `config/database.yml`. `worktree add` writes that token
-file and prints `database.yml reads .yamine-db-suffix` when the hook
-is in place; if instead you see a warning that database.yml does not
-read it, hand-run `rails console` / `rails test` / `db:migrate` in
-that worktree would use the main checkout's databases — add the hook
-from the README, then `yamine db create`.
+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
 

data/lib/yamine/cli/boot.rb

@@ -586,26 +586,25 @@ module Yamine
       # Worktree-add (and `yamine db create` in a worktree): turn a
       # probe of the app's real databases into a provisioned,
       # self-describing claim. Names come from the app, the suffix
-      # from the directory; claim + marker are written BEFORE any
+      # from the directory; claim + .env files are written BEFORE any
       # database is created, so a failure mid-way leaves a state the
       # next `yamine db create` or boot can finish from — never a
       # half-named set with no record of it.
       #
       # Returns the final names; raises Error only for conditions the
-      # user must fix (name budget, server down, app broken by its own
-      # suffix hook) — those keep the worktree and the claim.
+      # user must fix (name budget, server down, .env breaking the
+      # app's boot) — those keep the worktree and the claim.
       def provision_multidb(ctx, dir, claim_key, rows)
         env_name = rails_env
-        # A marker from a previous run means the probe answered with
-        # names the app already suffixed — strip that suffix before
-        # fitting, or this pass would double it and yamine would
-        # provision a set the app never connects to.
-        marker = Database.read_marker(dir)
-        if marker && !marker.empty?
-          rows = strip_marker_suffix(rows, marker)
-        end
+        # Re-provisioning a worktree whose .env exists: the app (via
+        # dotenv) resolves SUFFIXED names — strip the claim's stored
+        # suffix before fitting, or this pass would double it and
+        # yamine would provision a set the app never connects to.
+        prior = Database.load_map(ctx.store.dir)[claim_key]
+        prior_suffix = prior.is_a?(Hash) ? prior["suffix"] : nil
+        rows = strip_suffix(rows, prior_suffix)
         # The test environment's database joins the claim: worktree
-        # tests run against it (the same marker suffixes it), and
+        # tests run against it (.env.test carries its URL), and
         # teardown must drop it — a leaked test database per worktree
         # is exactly the leftover this exists to prevent. Test configs
         # are flat (implicitly named "primary"), so the claim key is
@@ -613,7 +612,7 @@ module Yamine
         # A test env the app cannot answer (missing test credentials,
         # say) degrades to a dev-only claim; `yamine db create` heals.
         test_rows = Probe.rails_databases(dir, env: "test")
-        test_rows = strip_marker_suffix(test_rows, marker) if test_rows && marker && !marker.empty?
+        test_rows = strip_suffix(test_rows, prior_suffix)
         test_pairs = (test_rows && Probe.server_backed(test_rows) || [])
           .map { |r| [env_namespaced_key(r["name"], "test"), r] }
 
@@ -638,8 +637,14 @@ module Yamine
           "claimed_at" => Time.now.utc.iso8601,
           "suffix" => fitted, "names" => names, "bases" => bases)
         Database.save_map(ctx.store.dir, map)
-        Database.write_marker(dir, fitted)
-        Database.exclude_marker(dir)
+        # The environment files: what hand-run commands read. Written
+        # before creation so the verify probe below can see them.
+        dev_env = db_env_for(
+          names.reject { |cfg, _| cfg == "test" || cfg.start_with?("test_") }, bases)
+        test_url = names["test"] &&
+          Database.url_for(names["test"], base_for(bases, "test"))
+        Database.write_env_files(dir, dev_env, test_url: test_url)
+        Database.exclude_files(dir, Database::ENV_FILES)
 
         # An empty test database is worse than none: Rails won't
         # auto-load schema into it (verified — first `rails test`
@@ -659,8 +664,14 @@ module Yamine
         end
 
         if test_needs_schema
+          # RAILS_ENV=test, not development: dotenv must load .env.test
+          # (PRIMARY_DATABASE_URL = this worktree's test URL) AND the
+          # environment-override merge only applies to the CURRENT
+          # env's configs — under development the flat test config
+          # would resolve to the base name and purge+load the MAIN
+          # checkout's test database instead of this worktree's.
           prepared = Dir.chdir(dir) do
-            system({ "RAILS_ENV" => rails_env }, "sh", "-c", "bin/rails db:test:prepare",
+            system({ "RAILS_ENV" => "test" }, "sh", "-c", "bin/rails db:test:prepare",
               out: File::NULL, err: File::NULL)
           end
           if prepared
@@ -670,16 +681,16 @@ module Yamine
           end
         end
 
-        verify_marker_conformance(dir, names)
+        verify_env_loading(dir, names)
         names
       end
 
-      def strip_marker_suffix(rows, marker)
-        return rows if marker.nil? || marker.empty?
+      def strip_suffix(rows, suffix)
+        return rows if rows.nil? || suffix.nil? || suffix.empty?
 
         rows.map do |r|
-          if r["database"].end_with?("_#{marker}")
-            r.merge("database" => r["database"].delete_suffix("_#{marker}"))
+          if r["database"].end_with?("_#{suffix}")
+            r.merge("database" => r["database"].delete_suffix("_#{suffix}"))
           else
             r
           end
@@ -692,20 +703,21 @@ module Yamine
         cfg_name == "primary" ? env : "#{env}_#{cfg_name}"
       end
 
-      # The proof, not the promise: re-probe now that the marker file
-      # is in place. Matching names mean database.yml reads it —
-      # hand-run console/test/migrate commands are isolated too.
-      # Mismatch is not fatal (supervised boots still isolate via
-      # env), but it is the one gap worth shouting about at the exact
-      # moment of creation. A probe that cannot run at all after
-      # writing the marker IS fatal: the app no longer boots, and the
-      # marker's own authorship is the likely reason.
-      def verify_marker_conformance(dir, names)
+      # The proof, not the promise: re-probe now that .env exists.
+      # Matching names mean something inside the app loads .env
+      # (dotenv-rails or any dotenv loader) — hand-run console/test/
+      # migrate commands are isolated too. Mismatch is not fatal
+      # (supervised boots isolate via injected env regardless), but
+      # it is the one gap worth shouting about at the exact moment of
+      # creation. A probe that cannot run at all after writing .env
+      # IS fatal: the app no longer boots, and .env's own authorship
+      # is the likely reason.
+      def verify_env_loading(dir, names)
         rows = Probe.rails_databases(dir)
         unless rows
           raise Error,
-            "the app no longer boots after writing #{Database::MARKER_FILE} — " \
-            "check the suffix hook at the top of config/database.yml"
+            "the app no longer boots after writing .env — " \
+            "check the generated .env files in #{dir}"
         end
 
         actual = rows.to_h { |r| [r["name"], r["database"]] }
@@ -714,20 +726,37 @@ module Yamine
         # for them either way; skip, don't flag.
         mismatched = names.reject { |cfg, want| !actual.key?(cfg) || actual[cfg] == want }
         if mismatched.empty?
-          puts "  database.yml reads #{Database::MARKER_FILE} — hand-run commands are isolated too"
+          puts "  .env loaded — hand-run commands are isolated too"
         else
           cfg, want = mismatched.first
-          warn "  WARNING: config/database.yml does not read #{Database::MARKER_FILE} " \
-               "(#{cfg} resolves to #{actual[cfg].inspect}, expected #{want.inspect})."
-          warn "    Supervised boots are still isolated via env, but `rails console`, " \
-               "`rails test`, and `db:migrate` run by hand in this worktree would use the main checkout's databases."
-          warn "    Add the suffix hook from the yamine README to database.yml, then re-run `yamine db create`."
+          env_url = rows.first["env_database_url"]
+          if env_url && !env_url.empty?
+            # The loader DID run — DATABASE_URL reached the app — yet
+            # resolution ignored it. database.yml supplies `url:` keys
+            # (credentials-style), and for those Rails gives the FILE
+            # precedence: merge_db_environment_variables skips configs
+            # that are already URL-shaped. No environment channel,
+            # spawned or loaded, can redirect this app in that form.
+            warn "  WARNING: #{cfg} resolves to #{actual[cfg].inspect} even though " \
+                 "DATABASE_URL says #{env_url.split("/").last.inspect}."
+            warn "    database.yml's `url:` keys take precedence over the environment in this configuration —"
+            warn "    neither injected env nor .env can redirect them. Switch development/test to"
+            warn "    component form (database:, host:, username:) so DATABASE_URL and .env apply —"
+            warn "    see the yamine README's multi-database section."
+          else
+            warn "  WARNING: this app does not load .env " \
+                 "(#{cfg} resolves to #{actual[cfg].inspect}, expected #{want.inspect})."
+            warn "    Supervised boots are still isolated via injected env, but `rails console`, " \
+                 "`rails test`, and `db:migrate` run by hand in this worktree would use the main checkout's databases."
+            warn "    Fix once: add `gem \"dotenv-rails\", groups: [:development, :test]` to the Gemfile — " \
+                 "any dotenv loader works."
+          end
         end
       rescue StandardError => e
         raise Error, e.message if e.is_a?(Error)
 
         raise Error,
-          "the app no longer boots after writing #{Database::MARKER_FILE}: #{e.message}"
+          "the app no longer boots after writing .env: #{e.message}"
       end
 
       # Top-level `db: false` opts out of per-worktree databases.

data/lib/yamine/cli/system.rb

@@ -930,7 +930,7 @@ module Yamine
       end
 
       # Main checkout: the databases ARE the app's own — no suffix, no
-      # marker, no claim names. Just make sure they exist.
+      # .env files, no claim names. Just make sure they exist.
       def db_create_main(rows)
         missing = rows.reject { |r| Database.exists?(r["database"], r["url"]) }
         failed = missing.filter_map do |r|

data/lib/yamine/cli/worktree.rb

@@ -29,19 +29,23 @@ module Yamine
       # credentials apps) no decryption key, which stops Rails before it
       # can even read database.yml. The single largest follow-up cost of
       # a new worktree, now carried automatically.
-      LOCAL_CONFIG_FILES = %w[config/local.yml config/local.secrets config/master.key].freeze
-      # Rails 7.1+ per-env credentials: development.key & co are
-      # gitignored exactly like master.key and equally fatal without.
-      CREDENTIALS_KEY_GLOB = "config/credentials/*.key"
-
-      # The static list plus whatever key files this checkout has, plus
-      # the worktree marker: everything yamine writes or copies that
-      # must never read as uncommitted work.
-      def local_config_files(dir)
-        keys = Dir.glob(File.join(dir, CREDENTIALS_KEY_GLOB)).map do |path|
-          path.sub(%r{\A#{Regexp.escape(dir.chomp("/"))}/?}, "")
-        end
-        LOCAL_CONFIG_FILES + keys + [Database::MARKER_FILE]
+      LOCAL_CONFIG_FILES = %w[config/local.yml config/local.secrets].freeze
+      # Only the credential keys the worktree's own environments need:
+      # master (multi-env credentials), development (boots + probe),
+      # test (test runs). Production and staging keys have no business
+      # sitting in a throwaway worktree directory.
+      CREDENTIAL_KEY_FILES = %w[
+        config/master.key
+        config/credentials/development.key
+        config/credentials/test.key
+      ].freeze
+
+      # Everything yamine copies or writes that must never read as
+      # uncommitted work: the per-checkout config, the three allowed
+      # keys, and the generated environment files.
+      def local_config_files(_dir)
+        LOCAL_CONFIG_FILES + CREDENTIAL_KEY_FILES + Database::ENV_FILES +
+          [Database::LEGACY_MARKER_FILE]
       end
 
       def run(ctx, args)
@@ -198,7 +202,7 @@ module Yamine
       # app's schema) so server problems surface at creation time, not
       # at first boot. Rails apps are ASKED what they have (the probe
       # resolves database.yml + credentials inside the app itself) and
-      # get the whole suffixed set — claim, marker file, databases,
+      # get the whole suffixed set — claim, .env files, databases,
       # schema. Boot reuses an existing set idempotently, so this is
       # never wasted work. SQLite and non-Rails apps fall through to
       # the single-database path, which setup_database narrates.

data/lib/yamine/database.rb

@@ -32,12 +32,17 @@ module Yamine
 
     MAX_IDENTIFIER_BYTES = 63
     STATE_FILE = "databases.json"
-    # Written into a worktree at add time; the app's database.yml
-    # reads it and suffixes every database URL, so hand-run commands
-    # (console, test, db:migrate) land on the worktree's own
-    # databases too — env injection only ever reaches processes
-    # yamine spawns.
-    MARKER_FILE = ".yamine-db-suffix"
+    # The per-worktree environment files yamine writes: `.env` carries
+    # the development set for ANY dotenv-style loader (framework-agnostic),
+    # `.env.test` carries PRIMARY_DATABASE_URL — the key Rails checks
+    # *before* DATABASE_URL for a flat test config, so the test URL wins
+    # no matter which order a loader reads the two files in. Hand-run
+    # commands (`rails console`, `rails test`, `db:migrate`) pick these
+    # up; env injection still covers processes yamine spawns itself.
+    ENV_FILES = %w[.env .env.development .env.test].freeze
+    # 0.16.0's marker file — removed in favor of .env; deleted on sight
+    # so upgraded worktrees don't accumulate dead files.
+    LEGACY_MARKER_FILE = ".yamine-db-suffix"
 
     # Database name for a worktree dir + env (development/test).
     # Main checkout (no worktree marker) keeps the bare name.
@@ -171,28 +176,63 @@ module Yamine
       name
     end
 
-    def write_marker(dir, suffix)
-      File.write(File.join(dir, MARKER_FILE), "#{suffix}\n")
+    # Write the worktree's environment files: `.env` with the whole
+    # development set (dotenv-compatible — any framework or plain Ruby
+    # app that loads .env gets hand-run isolation for free) and
+    # `.env.test` with the test URL under PRIMARY_DATABASE_URL.
+    # Private (URLs carry whatever the app's config carries), and the
+    # 0.16.0 marker file is removed on the way past.
+    def write_env_files(dir, dev_env, test_url: nil)
+      FileUtils.rm_f(File.join(dir, LEGACY_MARKER_FILE))
+      return if dev_env.nil? && test_url.nil?
+
+      unless dev_env.nil? || dev_env.empty?
+        body = dotenv_body(dev_env.reject { |k, _v| k == "PRIMARY_DATABASE_URL" })
+        write_env_file(File.join(dir, ".env"), body)
+        # Same content under the env-specific name: a loader that
+        # prefers .env.development over .env finds identical values.
+        write_env_file(File.join(dir, ".env.development"), body)
+      end
+      return if test_url.nil? || test_url.to_s.empty?
+
+      write_env_file(File.join(dir, ".env.test"),
+        dotenv_body({ "PRIMARY_DATABASE_URL" => test_url }))
+    end
+
+    def write_env_file(path, body)
+      File.write(path, body)
+      File.chmod(0o600, path)
     end
 
-    def read_marker(dir)
-      path = File.join(dir, MARKER_FILE)
-      File.file?(path) ? File.read(path).strip : nil
+    # dotenv format: single-quoted values (literal — no interpolation
+    # of a password's `$` or `#`), with the two escapes the dotenv
+    # grammar allows inside them.
+    def dotenv_body(env)
+      header = "# Per-worktree databases, written by yamine (worktree add).\n" \
+              "# Loaded by dotenv-rails / any dotenv loader; removed with this worktree.\n"
+      lines = env.map { |k, v| "#{k}='#{dotenv_escape(v.to_s)}'" }
+      "#{header}#{lines.join("\n")}\n"
     end
 
-    # Keep the marker out of `git status` without touching the
-    # committed .gitignore: git's exclude file lives in the shared
-    # git dir, so one entry covers every worktree of the repo.
-    def exclude_marker(dir)
+    def dotenv_escape(value)
+      value.gsub("\\") { "\\\\" }.gsub("'") { "\\'" }
+    end
+
+    # Keep files out of `git status` without touching the committed
+    # .gitignore: git's exclude file lives in the shared git dir, so
+    # entries cover every worktree of the repo. Idempotent per line.
+    def exclude_files(dir, names)
       out, status = Open3.capture2("git", "-C", dir, "rev-parse", "--git-path", "info/exclude")
       return unless status.success?
 
       path = out.strip
       path = File.expand_path(path, dir) unless path.start_with?("/")
-      return if File.file?(path) && File.read(path).lines.any? { |l| l.strip == MARKER_FILE }
-
       FileUtils.mkdir_p(File.dirname(path))
-      File.open(path, "a") { |f| f.puts MARKER_FILE }
+      existing = File.file?(path) ? File.read(path).lines.map(&:strip) : []
+      additions = Array(names).reject { |n| existing.include?(n) }
+      return if additions.empty?
+
+      File.open(path, "a") { |f| additions.each { |n| f.puts n } }
     rescue SystemCallError, IOError
       nil
     end

data/lib/yamine/probe.rb

@@ -65,7 +65,11 @@ module Yamine
               url = "#{h[:adapter]}:#{db}"
             end
           end
-          { "name" => c.name, "database" => db, "url" => url }
+          { "name" => c.name, "database" => db, "url" => url,
+            # What DATABASE_URL held INSIDE the app — the discriminator
+            # between "no .env loader ran" (nil) and "loader ran but
+            # database.yml's url: keys took precedence over it".
+            "env_database_url" => ENV["DATABASE_URL"] }
         end
       puts "YAMINE_DBS=#{JSON.generate(rows)}"
     RUBY

data/lib/yamine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Yamine
-  VERSION = "0.16.0"
+  VERSION = "0.17.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yamine
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Kaka Ruto