yamine 0.3.0 → 0.5.0

checksums.yaml

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

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.5.0] — Unreleased
+
+Per-worktree databases: every worktree directory gets its own database
+so concurrent agents never share tables.
+
+### Added
+
+- `Yamine::Database`: `<sanitized-dir-basename>_<env>` naming
+  (`/code/myapp-fix` → `myapp_fix_development`; main keeps the bare
+  name), 63-byte Postgres cap with hash-suffix truncation, collision
+  guard via state map (silent sharing would be the bug this kills).
+- Boot resolves the DB once, creates it (`createdb`/`mysqladmin`,
+  never raises — warns and shares template on failure), runs the app's
+  schema-load (`db.schema_load` in config, Rails default, else nothing),
+  and injects `DATABASE_URL` into every process. SQLite left alone.
+- `yamine db list|create|drop` and `yamine worktree list|clean`
+  (orphan reaping for deleted worktrees). Branch plays no part —
+  directories are stable, branches hop.
+
 ## [0.3.0] — Unreleased
 
 Renamed from `ask-local` to **`yamine`** (يمين, "right hand" — the local

data/lib/yamine/agent.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Yamine
+  # Agent identity for multi-agent codebases.
+  #
+  # Every route records which agent booted it so concurrent agents can
+  # coexist: list shows owners, conflicts name the other agent, quotas
+  # are enforced per agent, and stop/prune can target one agent without
+  # touching another's live backends. Identity comes from YAMINE_AGENT
+  # (set by the harness per session); without it we fall back to
+  # USER@HOST so humans sharing a machine still get distinct owners.
+  module Agent
+    module_function
+
+    def name
+      env = ENV["YAMINE_AGENT"]
+      return env.strip unless env.nil? || env.strip.empty?
+
+      user = ENV["USER"] || ENV["LOGNAME"] || "unknown"
+      host = begin
+        require "socket"
+        Socket.gethostname
+      rescue StandardError
+        "localhost"
+      end
+      "#{user}@#{host}"
+    end
+
+    # Default per-agent route cap. Generous: N agents x M services must
+    # fit in the ephemeral port range with headroom. Overridable via
+    # YAMINE_MAX_ROUTES (0 disables the cap).
+    DEFAULT_MAX_ROUTES = 32
+
+    def max_routes
+      raw = ENV["YAMINE_MAX_ROUTES"]
+      return DEFAULT_MAX_ROUTES if raw.nil? || raw.strip.empty?
+
+      Integer(raw)
+    rescue ArgumentError
+      DEFAULT_MAX_ROUTES
+    end
+  end
+end

data/lib/yamine/cli/boot.rb

@@ -18,6 +18,9 @@ module Yamine
         variant = ENV["YAMINE_VARIANT"]
         opts = ctx.parse_flags(args, %i[variant tld force])
         resolved = resolve!(ctx, variant: opts[:variant] || variant, tld: opts[:tld])
+        # Ownership gate before any side effects: no proxy spawn, no
+        # port allocation when we'd refuse anyway.
+        check_worktree_ownership!(ctx, resolved, force: opts[:force])
         ensure_proxy!(ctx)
         boot_all(ctx, resolved, opts)
       end
@@ -59,10 +62,23 @@ module Yamine
         puts "yamine (#{service})"
         puts "--"
 
-        processes.each do |proc_name, entry|
-          next if entry["proxy"] == false
+        # Per-worktree database: one database per directory so concurrent
+        # agents never share tables. Resolved once, injected into every
+        # process as DATABASE_URL, created on demand with the app's own
+        # schema-load command. SQLite needs nothing (relative paths
+        # already isolate); the branch plays no part (dirs are stable,
+        # branches hop).
+        db_name = Database.name_for(Dir.pwd, env: rails_env,
+          state_dir: ctx.store.dir)
+        db_url = setup_database(ctx, resolved, db_name)
+        puts "  [db] #{db_name}" if db_url
 
+        processes.each do |proc_name, entry|
           hostname = Resolver.hostname_for(resolved, proc_name)
+          if entry["proxy"] == false
+            boot_background(ctx, runner, resolved, proc_name, entry, opts, children, db_url)
+            next
+          end
           next unless hostname
 
           url = Hostname.url(hostname, port: ctx.proxy_port, tls: ctx.proxy_tls)
@@ -82,9 +98,11 @@ module Yamine
           shell_cmd = ["sh", "-c", cmd]
           # Always allow the proxied hostname in Rails dev (Rails ignores
           # this env var when not a Rails app — safe for every framework).
+          # DATABASE_URL points at this worktree's own database; non-Ruby
+          # frameworks that honor it get isolation for free, others ignore it.
           app = runner.boot_run(name: proc_name, hostname: hostname, url: url,
             dir: Dir.pwd, command: shell_cmd, port: port, force: opts[:force],
-            rails_dev_host: hostname)
+            rails_dev_host: hostname, database_url: db_url)
           register_all(ctx, hostnames, app, force: opts[:force],
             spec: { "dir" => File.expand_path(Dir.pwd), "proc" => proc_name })
           routes_registered << { hostnames: hostnames, app: app }
@@ -101,9 +119,50 @@ module Yamine
         ctx.report_unresolved(routes_registered.flat_map { |r| r[:hostnames] })
 
         # Supervisor: exit when ANY child dies (loud cleanup).
-        all_pids = routes_registered.map { |r| r[:app].pid }
-        trap_cleanup(ctx, routes_registered.flat_map { |r| r[:hostnames] }, all_pids)
-        supervise_tree(ctx, routes_registered.flat_map { |r| r[:hostnames] }, all_pids)
+        all_pids = routes_registered.map { |r| r[:app].pid } + children.map { |c| c[:pid] }
+        all_hostnames = routes_registered.flat_map { |r| r[:hostnames] }
+        trap_cleanup(ctx, all_hostnames, all_pids)
+        supervise_tree(ctx, all_hostnames, all_pids)
+      end
+
+      # A background process (proxy: false) is spawned, logged, and
+      # supervised exactly like an HTTP one — it just gets no route.
+      def boot_background(ctx, runner, resolved, proc_name, entry, opts, children, db_url)
+        cmd = entry["cmd"].to_s
+        if cmd.match?(Yamine::Procfile::COMPOUND)
+          $stderr.puts "  [#{proc_name}] ERROR: compound line (&&, ||, |, ;) — run explicitly: yamine run -- #{cmd}"
+          return
+        end
+        port = opts[:app_port] || Ports.find_free
+        url = "background://#{resolved.app}/#{proc_name}"
+        app = runner.boot_run(name: proc_name, hostname: "#{resolved.app}.#{proc_name}.internal",
+          url: url, dir: Dir.pwd, command: ["sh", "-c", cmd], port: port,
+          force: opts[:force], rails_dev_host: nil, register: false,
+          database_url: db_url)
+        children << { name: proc_name, pid: app.pid }
+        puts "  [#{proc_name}] background (pid #{app.pid})"
+      end
+
+      # Refuse to boot over another agent's live routes unless forced.
+      # Compares our worktree dir (spec.dir) against the owner's: same
+      # dir + same agent is a restart, anything else names the owner.
+      def check_worktree_ownership!(ctx, resolved, force:)
+        mine = Agent.name
+        here = File.expand_path(Dir.pwd)
+        Resolver.hostnames(resolved).each do |hostname|
+          entry = ctx.store.find(hostname)
+          next unless entry
+          next unless entry["pid"] != 0 && ProxyControl.pid_alive?(entry["pid"])
+          next if entry["agent"] == mine && entry.dig("spec", "dir") == here
+          next if force
+
+          owner = entry["agent"] && !entry["agent"].empty? ? "agent #{entry["agent"].inspect}" : "PID #{entry["pid"]}"
+          dir = entry.dig("spec", "dir")
+          $stderr.puts "Error: #{hostname} is live and owned by #{owner}#{dir ? " (#{dir})" : ""}."
+          $stderr.puts "  Work in your own worktree (each branch gets its own URL), or take over explicitly:"
+          $stderr.puts "    yamine start --force"
+          exit 1
+        end
       end
 
       def build_env(ctx, resolved, entry)
@@ -121,6 +180,64 @@ module Yamine
         env
       end
 
+      # Rails env for database naming: RAILS_ENV when set, else development.
+      # Non-Rails apps ignore it (their DATABASE_URL template decides).
+      def rails_env
+        ENV.fetch("RAILS_ENV", "development")
+      end
+
+      # Resolve this worktree's database, create it if missing, and run
+      # the app's schema-load command on first creation. Returns the
+      # DATABASE_URL for injection, or nil when there's nothing to do
+      # (no template URL, sqlite, or the app opted out via db: false).
+      def setup_database(ctx, resolved, db_name)
+        return nil if resolved.processes["db"] == false
+
+        template = ENV["DATABASE_URL"] || database_template_from_config(resolved)
+        return nil if template.nil? || template.strip.empty?
+
+        url = Database.url_for(db_name, template)
+        return nil unless url
+
+        if Database.ensure_exists(db_name, template)
+          puts "  [db] created #{db_name}" unless database_exists?(db_name, template)
+          run_schema_load(resolved, url)
+        else
+          $stderr.puts "  [db] WARNING: could not create #{db_name} — processes share the template database."
+          return nil
+        end
+        url
+      end
+
+      def database_exists?(name, template)
+        # ensure_exists is idempotent; this second call is cheap (psql -lqt)
+        # and tells us whether to print "created" vs nothing.
+        Database.ensure_exists(name, template)
+      end
+
+      def database_template_from_config(resolved)
+        env = resolved.processes.values.map { |e| e["env"] || {} }
+        clear = env.map { |e| e["clear"] || {} }.reduce({}, :merge)
+        clear["DATABASE_URL"]
+      end
+
+      # Schema-load on first boot uses the app's own command when declared
+      # (db.schema_load in config/local.yml), else a Rails default when a
+      # Rails app is detected, else nothing (frameworks without a
+      # schema concept need no step).
+      def run_schema_load(resolved, url)
+        cmd = resolved.processes.dig("db", "schema_load") ||
+          ("bin/rails db:schema:load" if rails_app?)
+        return unless cmd
+
+        system({ "DATABASE_URL" => url, "RAILS_ENV" => rails_env },
+          "sh", "-c", cmd, chdir: Dir.pwd, out: File::NULL, err: File::NULL)
+      end
+
+      def rails_app?
+        File.file?(File.join(Dir.pwd, "config", "application.rb"))
+      end
+
       def supervise_tree(ctx, hostnames, pids)
         loop do
           sleep 0.5

data/lib/yamine/cli/routes.rb

@@ -8,12 +8,16 @@ module Yamine
       module_function
 
       # yamine get <name> [--service x] [--variant y] [--tld z]
+      # yamine get --all [--json]
       #
       # Variant and TLDs are inherited from the CURRENT directory's
       # context (worktree branch, YAMINE_* env, config) so cross-service
       # wiring works inside a variant: from a fix-ui worktree,
       # `get backend` -> https://fix-ui.backend.localhost.
       def get(ctx, args)
+        if args.delete("--all")
+          return registry(ctx, args)
+        end
         name = args.first
         raise Error, "Usage: yamine get <name> [--service s] [--variant v] [--tld t]" unless name
 
@@ -36,7 +40,8 @@ module Yamine
           { hostname: r["hostname"],
             url: Hostname.url(r["hostname"], port: port, tls: tls),
             target: r["target"], kind: r["kind"],
-            pid: r["pid"], supervised: !r["spec"].nil?,
+            pid: r["pid"], agent: r["agent"],
+            supervised: !r["spec"].nil?,
             alive: alive_state(ctx, r) }
         end
         if json
@@ -56,6 +61,34 @@ module Yamine
         puts
       end
 
+      # Shared discovery: `get --all` lists every live route (any owner)
+      # with its URL and agent, so one agent can find another's services
+      # without coupling. `--json` emits the same stable keys as list.
+      def registry(ctx, args)
+        json = args.delete("--json")
+        routes = ctx.store.load_routes
+        port = ctx.proxy_port
+        tls = ctx.proxy_tls
+        entries = routes.map do |r|
+          { hostname: r["hostname"],
+            url: Hostname.url(r["hostname"], port: port, tls: tls),
+            agent: r["agent"], alive: alive_state(ctx, r) }
+        end
+        if json
+          require "json"
+          puts JSON.generate({ routes: entries })
+          return
+        end
+        if entries.empty?
+          puts "No active routes."
+          return
+        end
+        entries.each do |e|
+          owner = e[:agent] ? " (#{e[:agent]})" : ""
+          puts "  #{e[:url]}#{owner}"
+        end
+      end
+
       def alive_state(ctx, route)
         if route["pid"] == 0
           ctx.backend_alive?(route) ? "reachable" : "unreachable"
@@ -69,10 +102,11 @@ module Yamine
       end
 
       def label_for(entry)
+        owner = entry[:agent] ? " #{entry[:agent]}" : ""
         if entry[:pid] == 0
-          "(alias, #{entry[:alive]})"
+          "(alias, #{entry[:alive]}#{owner})"
         else
-          "(pid #{entry[:pid]}, #{entry[:alive]})"
+          "(pid #{entry[:pid]}, #{entry[:alive]}#{owner})"
         end
       end
 
@@ -84,7 +118,19 @@ module Yamine
         label_for(entry)
       end
 
-      def prune(ctx, _args)
+      def prune(ctx, args)
+        if (i = args.index("--agent"))
+          agent = args.fetch(i + 1, nil)
+          raise Error, "Usage: yamine prune --agent NAME" if agent.nil? || agent.empty?
+
+          stale = ctx.store.prune_stale(agent: agent)
+          if stale.empty?
+            puts "No stale routes for agent #{agent.inspect}."
+          else
+            stale.each { |r| puts "Removed stale route #{r["hostname"]}." }
+          end
+          return
+        end
         stale = ctx.store.prune_stale
         if stale.empty?
           puts "No stale routes."
@@ -124,15 +170,31 @@ module Yamine
       # Stop the app in the current directory (route + backend).
       # Exit codes are machine-readable for agents: 0 stopped something,
       # 2 no route here, 3 route existed but the backend was already gone.
-      def stop(ctx, _args, out: $stdout)
+      # Only our own agent's routes are touched: a foreign-owned live
+      # route is reported, never killed (shared backends survive one
+      # agent's cleanup). --force overrides and names the previous owner.
+      def stop(ctx, args, out: $stdout)
+        force = args.delete("--force")
         resolved = Resolver.resolve(Dir.pwd)
         hostnames = Resolver.hostnames(resolved)
+        mine = Agent.name
         stopped = []
         gone = []
+        foreign = []
         hostnames.each do |hostname|
           entry = ctx.store.find(hostname)
           next unless entry
 
+          if entry["pid"] != 0 && entry["agent"] && entry["agent"] != mine &&
+              ProxyControl.pid_alive?(entry["pid"])
+            unless force
+              owner = entry["agent"].empty? ? "PID #{entry["pid"]}" : "agent #{entry["agent"].inspect}"
+              foreign << "#{hostname} (owned by #{owner})"
+              next
+            end
+            out.puts "Taking over #{hostname} from #{entry["agent"].inspect} (--force)."
+          end
+
           backend_pid = ctx.backend_pid_for(entry)
           if backend_pid && ProxyControl.pid_alive?(backend_pid)
             begin
@@ -155,6 +217,11 @@ module Yamine
           stopped.each { |s| out.puts "Stopped #{s}." }
           return 0
         end
+        if foreign.any?
+          out.puts "Skipped live routes owned by other agents: #{foreign.join(", ")}."
+          out.puts "Take over explicitly with `yamine stop --force`."
+          return 4
+        end
         if gone.any?
           out.puts "Route existed but the backend was already gone: #{gone.join(", ")}."
           return 3

data/lib/yamine/cli/system.rb

@@ -763,6 +763,134 @@ module Yamine
         puts "    - #{app}-#{slug}.#{domain}"
         puts "  # Prefer Kamal multi-host for production; single-host preview above is fine for ephemeral branches."
       end
+
+      # Per-worktree databases: list/create/drop, plus orphan cleanup.
+      # `db list` shows every claimed database with its worktree dir.
+      # `db create` resolves this worktree's name and creates it.
+      # `db drop <name>` drops one database (refuses without --force
+      # when its worktree still exists).
+      def db(ctx, args)
+        sub = args.first
+        case sub
+        when "list", nil then db_list(ctx)
+        when "create" then db_create(ctx)
+        when "drop" then db_drop(ctx, args[1..] || [])
+        else raise Error, "Usage: yamine db [list|create|drop <name> [--force]]"
+        end
+      end
+
+      def db_list(ctx)
+        map = Database.load_map(ctx.store.dir)
+        if map.empty?
+          puts "No worktree databases claimed yet."
+          puts "Boot an app with a DATABASE_URL template to create one."
+          return
+        end
+        map.each do |name, info|
+          alive = File.directory?(info["dir"]) ? "" : " (worktree gone)"
+          puts "  #{name}  ->  #{info["dir"]}#{alive}"
+        end
+      end
+
+      def db_create(ctx)
+        resolved = Resolver.resolve(Dir.pwd)
+        name = Database.name_for(Dir.pwd, env: boot_env_name,
+          state_dir: ctx.store.dir)
+        template = ENV["DATABASE_URL"]
+        unless template && !template.strip.empty?
+          $stderr.puts "Error: set DATABASE_URL (template with host/user; database segment is replaced)."
+          exit 1
+        end
+        if Database.ensure_exists(name, template)
+          puts "Database #{name} ready."
+        else
+          $stderr.puts "Error: could not create #{name}. Check the database server is running."
+          exit 1
+        end
+      end
+
+      def db_drop(ctx, args)
+        force = args.delete("--force")
+        name = args.first
+        raise Error, "Usage: yamine db drop <name> [--force]" unless name
+
+        map = Database.load_map(ctx.store.dir)
+        info = map[name]
+        if info && File.directory?(info["dir"]) && !force
+          $stderr.puts "Error: worktree #{info["dir"]} still exists. Use --force to drop #{name} anyway."
+          exit 1
+        end
+        if drop_database(ctx, name)
+          map.delete(name)
+          Database.save_map(ctx.store.dir, map)
+          puts "Dropped #{name}."
+        else
+          $stderr.puts "Error: could not drop #{name}."
+          exit 1
+        end
+      end
+
+      def drop_database(_ctx, name)
+        template = ENV["DATABASE_URL"]
+        return false unless template && !template.strip.empty?
+
+        case Database.adapter_for(template)
+        when :postgres
+          uri = URI.parse(template)
+          _out, status = Open3.capture2("dropdb", name, env: Database.pg_env(uri))
+          status.success?
+        when :mysql
+          uri = URI.parse(template)
+          args = ["-h", uri.host || "127.0.0.1", "-u",
+                  URI.decode_www_form_component(uri.user || "root")]
+          _out, status = Open3.capture2("mysqladmin", *args, "drop", name, "-f")
+          status.success?
+        else
+          false
+        end
+      rescue SystemCallError
+        false
+      end
+
+      def boot_env_name
+        ENV.fetch("RAILS_ENV", "development")
+      end
+
+      # Worktree helpers: list claimed databases with liveness, clean
+      # drops databases whose worktree dirs are gone.
+      def worktree(ctx, args)
+        sub = args.first
+        case sub
+        when "list", nil
+          map = Database.load_map(ctx.store.dir)
+          if map.empty?
+            puts "No worktree databases claimed yet."
+            return
+          end
+          map.each do |name, info|
+            alive = File.directory?(info["dir"]) ? "alive" : "gone"
+            puts "  #{name}  #{info["dir"]}  (#{alive})"
+          end
+        when "clean"
+          orphaned = Database.orphaned(ctx.store.dir)
+          if orphaned.empty?
+            puts "No orphaned worktree databases."
+            return
+          end
+          orphaned.each do |name, _info|
+            if drop_database(ctx, name)
+              puts "Dropped orphaned #{name}."
+            else
+              $stderr.puts "Could not drop #{name} — remove manually."
+            end
+          end
+          map = Database.load_map(ctx.store.dir)
+          orphaned.each_key { |name| map.delete(name) }
+          Database.save_map(ctx.store.dir, map)
+        else
+          raise Error, "Usage: yamine worktree [list|clean]"
+        end
+      end
     end
   end
 end

data/lib/yamine/cli.rb

@@ -10,7 +10,7 @@ module Yamine
   # In non-interactive environments (no TTY or CI=1) we fail early with
   # a clear message instead of prompting (portless lesson).
   class CLI
-    SUBCOMMANDS = %w[run get alias hosts list doctor trust clean prune proxy service sudoers kamal stop restart log status open setup start init].freeze
+    SUBCOMMANDS = %w[run get alias hosts list doctor trust clean prune proxy service sudoers kamal stop restart log status open setup start init db worktree].freeze
 
     def self.run(argv)
       new.run(argv)
@@ -47,6 +47,8 @@ module Yamine
       when "setup" then SystemCommand.setup(ctx, args)
       when "init" then SystemCommand.init(ctx, args)
       when "start" then SystemCommand.start(ctx, args)
+      when "db" then SystemCommand.db(ctx, args)
+      when "worktree" then SystemCommand.worktree(ctx, args)
       when "kamal" then SystemCommand.kamal(ctx, args)
       when "stop"
         exit RoutesCommand.stop(ctx, args)
@@ -81,6 +83,8 @@ module Yamine
           yamine trust                  Add local CA to trust store
           yamine clean                  Remove state and hosts entries
           yamine prune                  Remove stale routes
+          yamine db list|create|drop      Per-worktree databases
+          yamine worktree list|clean     Worktree databases + orphan cleanup
           yamine proxy start|stop       Control the proxy
           yamine service install|status|uninstall   OS startup service
           yamine sudoers                Print scoped passwordless-sudo rules for port 443

data/lib/yamine/database.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "open3"
+
+module Yamine
+  # Per-worktree databases. Every worktree directory gets its own database
+  # so concurrent agents never share tables: no migration races, no seed
+  # pollution, no schema drift between branches.
+  #
+  # Naming: <sanitized-dir-basename>_<env> — e.g. /Users/kaka/code/myapp-fix
+  # becomes myapp_fix_development. The branch a worktree has checked out is
+  # irrelevant and mutable, so it plays no part; the directory is stable.
+  # The main checkout keeps the bare <basename>_<env> name. Postgres
+  # identifiers cap at 63 bytes; overlong names truncate with a hash
+  # suffix (same rule as hostname labels).
+  #
+  # Collision guard: two directories can sanitize identically
+  # (myapp-fix vs myapp_fix). A state file records which directory
+  # claimed which name first; on collision the newcomer gets a short
+  # hash suffix. Silent sharing would be exactly the bug this exists to
+  # kill, so the check is mandatory, not best-effort.
+  #
+  # Framework-agnostic: yamine injects DATABASE_URL and never touches
+  # framework files. SQLite needs nothing (relative paths already isolate
+  # per worktree). Creation runs the app's own schema-load command from
+  # config/local.yml — never assumed.
+  module Database
+    module_function
+
+    MAX_IDENTIFIER_BYTES = 63
+    STATE_FILE = "databases.json"
+
+    # Database name for a worktree dir + env (development/test).
+    # Main checkout (no worktree marker) keeps the bare name.
+    def name_for(dir, env: "development", state_dir: nil)
+      base = sanitize(File.basename(File.expand_path(dir)))
+      name = "#{base}_#{env}"
+      name = truncate(name)
+      claimed = claim(name, dir, state_dir: state_dir)
+      claimed || "#{truncate("#{base}_#{short_hash(dir)}")}_#{env}"
+    end
+
+    # The main checkout is the one whose .git is a directory (linked
+    # worktrees have a .git FILE pointing into /worktrees/). Main keeps
+    # the bare name; only linked worktrees get suffixed names... in
+    # practice every dir gets the mapping, but main's mapping is itself.
+    def main_checkout?(dir)
+      File.directory?(File.join(File.expand_path(dir), ".git"))
+    end
+
+    def sanitize(name)
+      name.downcase.gsub(/[^a-z0-9_]/, "_").gsub(/_+/, "_").gsub(/\A_+|_+\z/, "")
+    end
+
+    def truncate(name)
+      return name if name.bytesize <= MAX_IDENTIFIER_BYTES
+
+      hash = Digest::SHA256.hexdigest(name)[0, 6]
+      prefix = name.byteslice(0, MAX_IDENTIFIER_BYTES - 7).gsub(/_+\z/, "")
+      "#{prefix}_#{hash}"
+    end
+
+    def short_hash(dir)
+      Digest::SHA256.hexdigest(File.expand_path(dir))[0, 6]
+    end
+
+    # Record dir -> name claim; returns the name if ours (or unclaimed),
+    # nil if another dir claimed it first (caller must suffix).
+    def claim(name, dir, state_dir: nil)
+      return name unless state_dir
+
+      dir = File.expand_path(dir)
+      map = load_map(state_dir)
+      if map.key?(name) && map[name]["dir"] != dir
+        return nil
+      end
+      map[name] = { "dir" => dir, "claimed_at" => Time.now.utc.iso8601 }
+      save_map(state_dir, map)
+      name
+    rescue SystemCallError
+      name
+    end
+
+    def load_map(state_dir)
+      path = File.join(state_dir, STATE_FILE)
+      return {} unless File.file?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError, SystemCallError
+      {}
+    end
+
+    def save_map(state_dir, map)
+      FileUtils.mkdir_p(state_dir)
+      File.write(File.join(state_dir, STATE_FILE), JSON.pretty_generate(map))
+    rescue SystemCallError
+      nil
+    end
+
+    # Databases whose worktree dirs no longer exist (for `worktree clean`).
+    def orphaned(state_dir)
+      load_map(state_dir).select { |_, v| !File.directory?(v["dir"]) }
+    end
+
+    # Adapter detection from DATABASE_URL scheme. Returns :postgres,
+    # :mysql, :sqlite, or :unknown. Only postgres/mysql get create +
+    # DATABASE_URL treatment; sqlite is left alone (relative paths
+    # already isolate per worktree).
+    def adapter_for(database_url)
+      str = database_url.to_s.strip
+      return :sqlite if str.empty?
+
+      scheme = str[/\A[a-z0-9+]+/i].to_s.downcase
+      case scheme
+      when "postgres", "postgresql" then :postgres
+      when "mysql", "mysql2" then :mysql
+      when "sqlite", "sqlite3" then :sqlite
+      else :unknown
+      end
+    end
+
+    # Build a DATABASE_URL for name from a template URL (host, port, user
+    # preserved; database segment replaced). Returns nil when the template
+    # is absent or sqlite.
+    def url_for(name, template_url)
+      return nil if template_url.nil? || template_url.strip.empty?
+      return nil if adapter_for(template_url) == :sqlite
+
+      uri = URI.parse(template_url)
+      uri.path = "/#{name}"
+      uri.to_s
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    # Create the database if missing. Uses createdb/mysqladmin when
+    # available; returns true/false, never raises (boot reports, not dies).
+    def ensure_exists(name, database_url)
+      case adapter_for(database_url)
+      when :postgres then ensure_postgres(name, database_url)
+      when :mysql then ensure_mysql(name, database_url)
+      else false
+      end
+    end
+
+    def ensure_postgres(name, database_url)
+      uri = URI.parse(database_url)
+      env = pg_env(uri)
+      _out, status = Open3.capture2(env, "psql", "-lqt")
+      return false unless status.success?
+
+      exists = Open3.capture2(env, "psql", "-lqt")[0].split("\n").any? do |line|
+        line.split("|").first.to_s.strip == name
+      end
+      return true if exists
+
+      _out, status = Open3.capture2(env, "createdb", name)
+      status.success?
+    rescue SystemCallError
+      false
+    end
+
+    def ensure_mysql(name, database_url)
+      uri = URI.parse(database_url)
+      args = ["-h", uri.host || "127.0.0.1", "-P", (uri.port || 3306).to_s,
+              "-u", URI.decode_www_form_component(uri.user || "root")]
+      args += ["-p#{URI.decode_www_form_component(uri.password)}"] if uri.password
+      _out, status = Open3.capture2("mysqladmin", *args, "create", name)
+      status.success? || already_exists_mysql(args, name)
+    rescue SystemCallError
+      false
+    end
+
+    def already_exists_mysql(args, name)
+      out, status = Open3.capture2("mysql", *args, "-e", "SHOW DATABASES;")
+      status.success? && out.split("\n").include?(name)
+    rescue SystemCallError
+      false
+    end
+
+    def pg_env(uri)
+      {
+        "PGHOST" => uri.host || "127.0.0.1",
+        "PGPORT" => (uri.port || 5432).to_s,
+        "PGUSER" => URI.decode_www_form_component(uri.user || ENV["USER"].to_s),
+        "PGPASSWORD" => uri.password ? URI.decode_www_form_component(uri.password) : nil
+      }.compact
+    end
+  end
+end

data/lib/yamine/errors.rb

@@ -4,13 +4,32 @@ module Yamine
   class Error < StandardError; end
   class ConfigError < Error; end
   class RouteConflictError < Error
-    attr_reader :hostname, :existing_pid
+    attr_reader :hostname, :existing_pid, :existing_agent, :existing_dir
 
-    def initialize(hostname, existing_pid)
+    def initialize(hostname, existing_pid, existing_agent: nil, existing_dir: nil)
       @hostname = hostname
       @existing_pid = existing_pid
-      super("\"#{hostname}\" is already registered by a running process " \
-            "(PID #{existing_pid}). Use --force to override.")
+      @existing_agent = existing_agent
+      @existing_dir = existing_dir
+      owner = if existing_agent && !existing_agent.empty?
+                "agent #{existing_agent.inspect}#{existing_dir ? " (#{existing_dir})" : ""}"
+              else
+                "PID #{existing_pid}"
+              end
+      super("\"#{hostname}\" is already registered by a running #{owner}. " \
+            "Use --force to override.")
+    end
+  end
+  class QuotaExceededError < Error
+    attr_reader :agent, :limit, :count
+
+    def initialize(agent, limit, count)
+      @agent = agent
+      @limit = limit
+      @count = count
+      super("Agent #{agent.inspect} already owns #{count} routes (limit #{limit}). " \
+            "Stop something first: `yamine stop`, or prune one agent's orphans " \
+            "with `yamine prune --agent NAME`.")
     end
   end
   class ProxyNotRunningError < Error; end

data/lib/yamine/proxy_control.rb

@@ -16,11 +16,11 @@ module Yamine
     module_function
 
     # Path to the yamine executable relative to this file
-    # (lib/ask/local -> gem root/bin). Used for daemon spawn and
+    # (lib/yamine -> gem root/bin). Used for daemon spawn and
     # service install; both must resolve identically in dev checkouts
     # and installed gems.
     def bin_path
-      File.expand_path("../../../bin/yamine", __dir__)
+      File.expand_path("../../bin/yamine", __dir__)
     end
 
     def root?

data/lib/yamine/route_store.rb

@@ -4,12 +4,14 @@ require "fileutils"
 require "json"
 
 module Yamine
-  # Persistent hostname -> backend mapping in ~/.yamine/routes.json.
-  #
-  # Entries: {hostname, target, kind, pid} where target is a unix socket
-  # path (kind "socket") or "127.0.0.1:PORT" (kind "tcp"), and pid 0
-  # marks a static alias. Guarded by flock; stale PIDs pruned on read.
-  # Modeled on portless RouteStore and puma-dev's AppPool registry.
+    # Persistent hostname -> backend mapping in ~/.yamine/routes.json.
+    #
+    # Entries: {hostname, target, kind, pid, agent} where target is a unix
+    # socket path (kind "socket") or "127.0.0.1:PORT" (kind "tcp"), pid 0
+    # marks a static alias, and agent names the owner (YAMINE_AGENT or
+    # USER@HOST fallback) so concurrent agents can coexist. Guarded by
+    # flock; stale PIDs pruned on read.
+    # Modeled on portless RouteStore and puma-dev's AppPool registry.
   class RouteStore
     FILE_MODE = 0o644
     DIR_MODE = 0o755
@@ -71,13 +73,22 @@ module Yamine
     # Returns killed pid when force takes over a live route.
     # `spec` marks daemon-supervised managed apps ({dir: ...}); the
     # proxy supervisor may idle-kill and boot-on-request those backends.
-    def add_route(hostname, target, pid, kind:, force: false, spec: nil)
+    # `agent` records the owner (defaults to Agent.name); foreign-owned
+    # live routes can only be taken with force: true, and the conflict
+    # error names the other agent plus its worktree dir.
+    def add_route(hostname, target, pid, kind:, force: false, spec: nil, agent: nil)
+      agent ||= Agent.name
       killed = nil
       with_lock do
         routes = load_routes(prune: true)
+        enforce_quota!(routes, agent, hostname)
         existing = routes.find { |r| r["hostname"] == hostname }
         if existing && existing["pid"] != pid && alive?(existing["pid"])
-          raise RouteConflictError.new(hostname, existing["pid"]) unless force
+          unless force
+            raise RouteConflictError.new(hostname, existing["pid"],
+              existing_agent: existing["agent"],
+              existing_dir: existing.dig("spec", "dir"))
+          end
 
           begin
             Process.kill("TERM", existing["pid"])
@@ -87,7 +98,8 @@ module Yamine
           end
         end
         routes.reject! { |r| r["hostname"] == hostname }
-        entry = { "hostname" => hostname, "target" => target, "kind" => kind, "pid" => pid }
+        entry = { "hostname" => hostname, "target" => target, "kind" => kind,
+                  "pid" => pid, "agent" => agent }
         entry["spec"] = spec if spec
         routes << entry
         save_routes(routes)
@@ -95,33 +107,52 @@ module Yamine
       killed
     end
 
-    def remove_route(hostname, owner_pid: nil)
-      with_lock do
-        routes = load_routes(prune: true)
-        routes.reject! do |r|
-          r["hostname"] == hostname && (owner_pid.nil? || r["pid"] == owner_pid)
-        end
-        save_routes(routes)
-      end
+    # Live routes owned by one agent (for quotas, targeted prune/stop).
+    def routes_for(agent)
+      load_routes.select { |r| r["agent"] == agent }
     end
 
-    def prune_stale
+    # Remove stale entries belonging to one agent only; other agents'
+    # routes are untouched even when their owners are dead.
+    def prune_stale(agent: nil)
       stale = []
       with_lock do
         all = load_routes_raw
         alive, dead = all.partition { |r| r["pid"] == 0 || alive?(r["pid"]) }
-        stale = dead
-        save_routes(alive) unless dead.empty?
+        stale = agent ? dead.select { |r| r["agent"] == agent } : dead
+        save_routes(alive + (dead - stale)) unless stale.empty?
       end
       stale
     end
 
+    def remove_route(hostname, owner_pid: nil)
+      with_lock do
+        routes = load_routes(prune: true)
+        routes.reject! do |r|
+          r["hostname"] == hostname && (owner_pid.nil? || r["pid"] == owner_pid)
+        end
+        save_routes(routes)
+      end
+    end
+
     def find(hostname)
       load_routes.find { |r| r["hostname"] == hostname }
     end
 
     private
 
+    # Per-agent route cap. Counts the agent's live routes (excluding the
+    # hostname being (re)registered, so restarts never trip the quota).
+    # Limit 0 disables the cap. Raises QuotaExceededError naming the
+    # agent, the count, and the fix.
+    def enforce_quota!(routes, agent, hostname)
+      limit = Agent.max_routes
+      return if limit.zero?
+
+      count = routes.count { |r| r["agent"] == agent && r["hostname"] != hostname }
+      raise QuotaExceededError.new(agent, limit, count) if count >= limit
+    end
+
     def valid_route?(value)
       value.is_a?(Hash) &&
         value["hostname"].is_a?(String) &&

data/lib/yamine/runner.rb

@@ -90,20 +90,24 @@ module Yamine
     end
 
     # Run an arbitrary command with PORT + YAMINE_URL. Returns App.
+    # register: false spawns without a route (background processes).
     def boot_run(name:, hostname:, url:, dir:, command:, port: nil, force: false,
-      rails_dev_host: nil)
+      rails_dev_host: nil, register: true, database_url: nil)
       port ||= Ports.find_free
-      env = child_env(dir, url: url, port: port, rails_dev_host: rails_dev_host)
+      env = child_env(dir, url: url, port: port, rails_dev_host: rails_dev_host,
+        database_url: database_url)
       pid = with_clean_env { spawn(env, *command, chdir: dir) }
       Process.detach(pid)
       target = "127.0.0.1:#{port}"
-      @store.add_route(hostname, target, Process.pid, kind: "tcp", force: force)
-      write_backend_pid(hostname, pid)
+      if register
+        @store.add_route(hostname, target, Process.pid, kind: "tcp", force: force)
+        write_backend_pid(hostname, pid)
+      end
       App.new(name: name, hostname: hostname, url: url, pid: pid,
         target: target, kind: "tcp", command: command)
     end
 
-    def child_env(dir, url:, port:, rails_dev_host: nil)
+    def child_env(dir, url:, port:, rails_dev_host: nil, database_url: nil)
       env = { "YAMINE_URL" => url }
       env["PORT"] = port.to_s if port
       env["HOST"] = "127.0.0.1"
@@ -113,6 +117,10 @@ module Yamine
       # proxied hostname so Rails apps boot behind yamine with zero
       # config — this replaces the yamine-rails hosts patch.
       env["RAILS_DEVELOPMENT_HOSTS"] = rails_dev_host if rails_dev_host
+      # Per-worktree database: every process in this worktree shares one
+      # isolated database. Frameworks that honor DATABASE_URL (Rails,
+      # Django, most Node) get isolation for free; others ignore it.
+      env["DATABASE_URL"] = database_url if database_url
       env
     end
 

data/lib/yamine/version.rb

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

data/lib/yamine.rb

@@ -2,6 +2,8 @@
 
 require_relative "yamine/version"
 require_relative "yamine/errors"
+require_relative "yamine/agent"
+require_relative "yamine/database"
 require_relative "yamine/sanitize"
 require_relative "yamine/hostname"
 require_relative "yamine/inference"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yamine
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -82,6 +82,7 @@ files:
 - bin/yamine
 - lib/ask/skills/yamine/SKILL.md
 - lib/yamine.rb
+- lib/yamine/agent.rb
 - lib/yamine/certs.rb
 - lib/yamine/cli.rb
 - lib/yamine/cli/boot.rb
@@ -90,6 +91,7 @@ files:
 - lib/yamine/cli/system.rb
 - lib/yamine/command.rb
 - lib/yamine/config.rb
+- lib/yamine/database.rb
 - lib/yamine/doctor.rb
 - lib/yamine/errors.rb
 - lib/yamine/framework.rb