env-agent 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f061d96c573ec1c540732024985a8fa07db34750841268950285b2690c68c02
+  data.tar.gz: 8e0deaee7c6f4bbefbffa1302f721e992d3c0a7028cd1536f838deb33fac85de
+SHA512:
+  metadata.gz: b3273b86ebfae5e5d26057f858db35fae16ea875d9c712823edb2262fd058c9dc12527882f6e4f4b73577e1c918ea4446a53954a46cbd49bc94b78e740363c14
+  data.tar.gz: c6cd1d208d7a19f25f1b21281b577a05bd2ea042406ae6f981f4bf1df1d2226083ac0fb32e566e10ed536d1302faf9b08ea30aa4d9f26f3143eae70f5c35a3eb

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Panos Dalitsouris
+
+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,207 @@
+# env-agent
+
+Your project's docs, skills and agent instructions sometimes need files from
+**another repo** — a design-system demo, a vendored theme, a sibling service.
+That repo is cloned somewhere on each developer's machine, but everyone puts
+it somewhere different, and every git worktree is in yet another place.
+
+env-agent gives that other repo **one fixed path inside your project**, the
+same on every machine and in every worktree:
+
+```
+.env-agent/design-system/docs/index.html
+```
+
+`.env-agent/design-system` is a link to wherever *your* clone happens to be. Docs
+and AI agents use the link, so nobody hardcodes `/Users/someone/Code/...`, and
+nobody's home directory ends up in a transcript, a log or a commit.
+
+It comes in two parts:
+
+- **The `env-agent` command** finds each clone and creates the links. It never
+  asks questions, never clones anything, and never prints a path.
+- **The `env-agent` agent** (for Claude Code) does the parts that need a human:
+  it asks where your clone is, or whether to clone it, and then runs the command.
+
+Works on macOS and Linux, in any git repository, with any Ruby 3.3 or newer.
+No other dependencies. Windows is not supported.
+
+## Install
+
+env-agent is not published to RubyGems yet. Install it from a clone:
+
+```sh
+git clone <this repo> env-agent
+cd env-agent
+gem build env-agent.gemspec
+gem install ./env-agent-0.1.0.gem
+```
+
+Then, once per machine, install the agent for Claude Code:
+
+```sh
+env-agent install-agent      # writes ~/.claude/agents/env-agent.md
+```
+
+## Quick start
+
+### Setting up a clone
+
+From anywhere in the project (main checkout or any worktree), tell env-agent
+where your clone is. It asks for the directory without showing what you type:
+
+```sh
+env-agent set design-system
+```
+
+Or give the directory directly: `env-agent set design-system ~/Code/design-system`.
+
+The name (`design-system`) is yours to choose; it becomes the link
+`.env-agent/design-system`. It may contain letters, digits, `_`, `.` and `-`.
+
+You only do this once per machine. Every worktree of the project picks up the
+same setting; a new worktree just needs `env-agent link`.
+
+In Claude Code you can also just ask: *"use the env-agent agent to set up the
+external repos"*.
+
+### Adding the agent to a project
+
+```sh
+env-agent init
+```
+
+This creates:
+
+| File | What it is | Commit it? |
+|---|---|---|
+| `.AGENT/agents/env-agent.md` | The project's copy of the agent | Yes |
+| `.claude/agents/env-agent.md` | A link to the copy above, where Claude Code looks for it | Yes |
+
+Then point your docs at the link, e.g. *"copy markup from
+`.env-agent/design-system/docs/`; if the link is missing, run `env-agent link`"*.
+
+There is no per-project config file. A project only commits the agent and
+mentions the link names in its docs; the paths live on each machine.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `env-agent set NAME [DIR]` | Saves where your clone is, then links it. Without DIR it asks, hiding your input |
+| `env-agent link [NAME]` | Creates or refreshes `.env-agent/NAME` (every saved name if NAME is omitted) |
+| `env-agent check [NAME]` | Shows where each name was found, or why not. Changes nothing |
+| `env-agent unset NAME` | Forgets the saved location and removes the link |
+| `env-agent init` | Adds the agent to the current project (see above) |
+| `env-agent install-agent` | Installs the agent for your user in `~/.claude/agents/` |
+| `env-agent help`, `version` | Usage and version |
+
+Exit status: `0` everything resolved, `1` something did not, `2` a wrong
+command, argument or name, or not inside a git checkout.
+
+Example `check` output:
+
+```
+design-system: ok (main checkout .env.agents)
+  main checkout .env.agents: ok
+  link .env-agent/design-system: ok
+```
+
+In a linked worktree, `check` also lists `worktree .env.agents` first.
+
+## How a directory is found
+
+For each name, env-agent tries these places in order and uses the first one
+whose directory exists:
+
+1. **This worktree's `.env.agents`**: only when you are in a linked worktree.
+   Lets one worktree use a different clone.
+2. **The main checkout's `.env.agents`**: where `env-agent set` saves things.
+   Found from any worktree, which is why one setting covers all of them.
+
+If neither has a directory that exists, the name is reported as not found and
+its link is removed. A saved location that no longer exists is skipped, not
+trusted.
+
+`.env.agents` is a plain `NAME=value` file:
+
+```sh
+design-system=/Users/you/Code/design-system
+```
+
+Use `env-agent set` / `unset` rather than editing it by hand; `set` checks the
+directory before saving it. Values with spaces or quotes are quoted for you.
+
+Environment variables are deliberately **not** read. A `design-system`
+variable exported in your shell never changes where a link points; only
+`.env.agents` does.
+
+## Keeping paths private
+
+env-agent never prints a resolved path: not in `link`, `check`, `set`, or any
+error. It names the *source* instead ("main checkout .env.agents") and the
+outcome ("ok", "not set", "directory missing").
+
+That keeps your home directory and folder layout out of AI agent transcripts,
+CI logs, screen shares and commits. It is not a secret store: the path is in
+`.env.agents` on your disk, and `ls -l .env-agent/` shows where a link points.
+
+To keep the path out of an agent conversation entirely, run `set` yourself
+without a directory. In Claude Code, type `! env-agent set design-system`; the
+prompt hides your input.
+
+## Nothing to add to `.gitignore`
+
+The first time `set`, `link` or `init` runs in a project, env-agent adds
+`/.env.agents` and `/.env-agent/` to the repository's `.git/info/exclude`. That
+file is local to your machine and shared by all worktrees, so the project's
+`.gitignore` never needs to change.
+
+## The agent
+
+The agent is a short Claude Code instruction file. It:
+
+1. runs `env-agent link`;
+2. for each name that is missing, asks where that directory is on your
+   machine, and offers the private `! env-agent set` route;
+3. otherwise runs `env-agent set NAME DIR` with the directory you give;
+4. runs `env-agent check` and reports it.
+
+It only runs commands; it never reads or edits `.env.agents`, never guesses a
+directory and never repeats a path back to you.
+
+There can be two copies, and both come from the same template inside the gem:
+
+- **Project copy** (`env-agent init`): committed, so everyone who clones the
+  project has it. Claude Code prefers it when present.
+- **User copy** (`env-agent install-agent`): used in projects that have no
+  copy of their own.
+
+The template has a version number. When a project's copy is older than your
+installed env-agent, `env-agent check` prints a warning; run `env-agent init`
+to update it.
+
+## Notes
+
+- **Docker:** run env-agent on your machine, not inside a container. The
+  external clones live on the host.
+- **Git:** needs git 2.31 or newer (for `rev-parse --path-format`).
+
+## For other tools
+
+The lookup order and the `.env.agents` format above are the whole contract.
+Any tool, in any language, can implement them and produce the same result;
+this gem is one implementation.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake        # RuboCop + specs
+```
+
+The specs run the CLI against throwaway repositories with real git worktrees,
+and check that no output ever contains a path.
+
+[AGENTS.md](AGENTS.md) has the code map, the rules every change must keep, and
+how to add a command. It is written for AI agents and people alike.

data/exe/env-agent

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative '../lib/env_agent'
+
+exit EnvAgent::CLI.start(ARGV)

data/lib/env_agent/agent.rb

@@ -0,0 +1,93 @@
+require 'fileutils'
+
+# The env-agent Claude Code agent: one bundled template, written into a repo and into the user's config.
+class EnvAgent::Agent
+  TEMPLATE = File.expand_path('../../templates/agent.md', __dir__)
+  REPO_COPY = '.AGENT/agents/env-agent.md'.freeze
+  CLAUDE_COPY = '.claude/agents/env-agent.md'.freeze
+  CLAUDE_LINK_TARGET = '../../.AGENT/agents/env-agent.md'.freeze
+
+  # @return [String]
+  def self.template
+    File.read(TEMPLATE)
+  end
+
+  # @param [String] text agent markdown
+  #
+  # @return [Integer, nil] the frontmatter version
+  def self.version_of(text)
+    text[/^version:\s*(\d+)\s*$/, 1]&.to_i
+  end
+
+  # @param [EnvAgent::Checkout] checkout
+  #
+  # @raise [EnvAgent::Error] when a link is on the way to either copy
+  #
+  # @return [Array<String>] what changed, in repo-relative terms
+  def write_repo!(checkout)
+    repo_copy = checkout.own_path!(REPO_COPY)
+    claude_copy = File.join(checkout.own_path!(File.dirname(CLAUDE_COPY)), File.basename(CLAUDE_COPY))
+    actions = []
+    actions << "wrote #{REPO_COPY}" if write_if_changed(repo_copy)
+    actions << "linked #{CLAUDE_COPY} -> #{REPO_COPY}" if link_claude_copy(claude_copy)
+    actions
+  end
+
+  # @param [String] home the user's home directory
+  #
+  # @return [TrueClass, FalseClass] whether the copy changed
+  def write_user!(home)
+    write_if_changed(File.join(home, CLAUDE_COPY))
+  end
+
+  # @param [String] root checkout root
+  #
+  # @return [Integer, nil] version of the repo's committed copy, nil when it has none
+  def repo_version(root)
+    copy = [REPO_COPY, CLAUDE_COPY].map { |relative| File.join(root, relative) }.find { |path| File.file?(path) }
+    copy && self.class.version_of(File.read(copy))
+  end
+
+  private
+
+  # @param [String] path
+  #
+  # @return [TrueClass, FalseClass]
+  def write_if_changed(path)
+    return false if File.file?(path) && File.read(path) == self.class.template
+
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, self.class.template)
+    true
+  end
+
+  # @param [String] link
+  #
+  # @return [TrueClass, FalseClass] whether the link changed
+  def link_claude_copy(link)
+    return false if File.symlink?(link) && File.readlink(link) == CLAUDE_LINK_TARGET
+
+    clear(link)
+    FileUtils.mkdir_p(File.dirname(link))
+    File.symlink(CLAUDE_LINK_TARGET, link)
+    true
+  end
+
+  # @param [String] link
+  #
+  # @raise [EnvAgent::Error] when an unrelated file is in the way
+  def clear(link)
+    return File.unlink(link) if File.symlink?(link)
+    return unless File.exist?(link)
+    raise EnvAgent::Error, "#{CLAUDE_COPY} exists and is not the env-agent agent; leaving it" unless agent_file?(link)
+
+    File.unlink(link)
+  end
+
+  # @param [String] path
+  #
+  # @return [TrueClass, FalseClass]
+  def agent_file?(path)
+    File.read(path).match?(/^name:\s*env-agent\s*$/)
+  end
+end

data/lib/env_agent/checkout.rb

@@ -0,0 +1,104 @@
+require 'open3'
+require 'pathname'
+
+# The git checkout env-agent runs in: the current worktree and the main checkout behind it.
+class EnvAgent::Checkout
+  # @param [String] dir any directory inside the checkout
+  def initialize(dir = Dir.pwd)
+    @dir = dir
+  end
+
+  # @return [String] root of the current worktree, or of the main checkout when run there
+  def root
+    @root ||= File.realpath(git('rev-parse', '--show-toplevel'))
+  end
+
+  # @return [String] the git directory shared by the main checkout and every worktree
+  def common_dir
+    @common_dir ||= File.realpath(git('rev-parse', '--path-format=absolute', '--git-common-dir'))
+  end
+
+  # @return [String] root of the main checkout
+  def main_root
+    @main_root ||= File.dirname(common_dir)
+  end
+
+  # @return [TrueClass, FalseClass] whether the current checkout is the main one
+  def main?
+    root == main_root
+  end
+
+  # @raise [EnvAgent::Error] when git tracks the file
+  #
+  # @return [EnvAgent::Dotenv] the main checkout's .env.agents
+  def main_dotenv
+    @main_dotenv ||= untracked_dotenv(main_root, 'the main checkout')
+  end
+
+  # @raise [EnvAgent::Error] when git tracks the file
+  #
+  # @return [EnvAgent::Dotenv] this worktree's .env.agents
+  def worktree_dotenv
+    @worktree_dotenv ||= untracked_dotenv(root, 'this worktree')
+  end
+
+  # @param [String] relative path inside the current worktree that env-agent writes to
+  #
+  # @raise [EnvAgent::Error] when the path, or a directory on the way to it, is a link
+  #
+  # @return [String] the absolute path
+  def own_path!(relative)
+    Pathname(relative).descend do |part|
+      raise EnvAgent::Error, "#{part} is a link; move it away first" if File.symlink?(File.join(root, part))
+    end
+    File.join(root, relative)
+  end
+
+  private
+
+  attr_reader :dir
+
+  # @param [String] checkout_root
+  # @param [String] where
+  #
+  # @raise [EnvAgent::Error] when git tracks the file
+  #
+  # @return [EnvAgent::Dotenv]
+  def untracked_dotenv(checkout_root, where)
+    file = EnvAgent::Dotenv::FILE
+
+    if tracked?(checkout_root, file)
+      raise EnvAgent::Error, "#{file} is committed in #{where}, so env-agent will not use it. " \
+                             "Keep it on this machine only: git rm --cached #{file}"
+    end
+
+    EnvAgent::Dotenv.new(checkout_root)
+  end
+
+  # @param [String] checkout_root
+  # @param [String] relative
+  #
+  # @return [TrueClass, FalseClass] false also when checkout_root is not a checkout
+  def tracked?(checkout_root, relative)
+    out, status = capture(checkout_root, 'ls-files', '-z', '--', relative)
+    status.success? && !out.empty?
+  end
+
+  # @param [Array<String>] args
+  #
+  # @return [String]
+  def git(*args)
+    out, status = capture(dir, *args)
+    raise EnvAgent::UsageError, 'not inside a git checkout' unless status.success?
+
+    out.strip
+  end
+
+  # @param [String] chdir
+  # @param [Array<String>] args
+  #
+  # @return [Array(String, Process::Status)]
+  def capture(chdir, *args)
+    Open3.capture2('git', *args, chdir: chdir, err: File::NULL)
+  end
+end

data/lib/env_agent/cli.rb

@@ -0,0 +1,296 @@
+require 'io/console'
+
+# Command-line entry point: runs one command and maps failures to exit statuses. Never prints a saved path.
+class EnvAgent::CLI
+  USAGE = <<~TEXT.freeze
+    Usage: env-agent <command> [arguments]
+
+      set NAME [DIR]   Save DIR as NAME and link it at .env-agent/NAME; asks for DIR, hidden, when omitted
+      link [NAME]      Recreate .env-agent/NAME (every saved name when NAME is omitted)
+      check [NAME]     Show where each name resolves from, changing nothing
+      unset NAME       Forget NAME and remove its link
+      init             Add the env-agent agent to this repo
+      install-agent    Install the env-agent agent for your user (~/.claude/agents)
+      help             Show this message
+      version          Show the version
+
+    env-agent never prints a saved path. See the README for details.
+  TEXT
+
+  LINK_STATES = {
+    ok: 'ok',
+    missing: 'missing (run `env-agent link`)',
+    stale: 'stale (run `env-agent link`)'
+  }.freeze
+
+  # @param [Array<String>] argv
+  # @param [IO] stdin
+  # @param [IO] stdout
+  # @param [IO] stderr
+  #
+  # @return [Integer] exit status
+  def self.start(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr)
+    new(stdin: stdin, stdout: stdout, stderr: stderr).run(argv)
+  end
+
+  # @param [IO] stdin
+  # @param [IO] stdout
+  # @param [IO] stderr
+  def initialize(stdin:, stdout:, stderr:)
+    @stdin = stdin
+    @stdout = stdout
+    @stderr = stderr
+  end
+
+  # @param [Array<String>] argv
+  #
+  # @return [Integer] exit status
+  def run(argv)
+    command, *args = argv
+    dispatch(command, args)
+  rescue EnvAgent::UsageError => e
+    stderr.puts("env-agent: #{e.message}")
+    stderr.puts('Run `env-agent help` for usage.')
+    2
+  rescue EnvAgent::Error => e
+    stderr.puts("env-agent: #{e.message}")
+    1
+  rescue SystemCallError => e
+    stderr.puts("env-agent: #{SystemCallError.new(e.errno).message}")
+    1
+  rescue StandardError => e
+    stderr.puts("env-agent: unexpected #{e.class}; details withheld so no path is printed")
+    1
+  end
+
+  private
+
+  attr_reader :stdin, :stdout, :stderr
+
+  # @param [String, nil] command
+  # @param [Array<String>] args
+  #
+  # @return [Integer]
+  def dispatch(command, args)
+    case command
+    when 'set' then set(*arity!(args, 1, 2))
+    when 'link' then link(arity!(args, 0, 1).first)
+    when 'check' then check(arity!(args, 0, 1).first)
+    when 'unset' then unset(arity!(args, 1, 1).first)
+    when 'init' then arity!(args, 0, 0) && init
+    when 'install-agent' then arity!(args, 0, 0) && install_agent
+    when nil, 'help', '-h', '--help' then say(USAGE)
+    when 'version', '-v', '--version' then say(EnvAgent::VERSION)
+    else raise EnvAgent::UsageError, "unknown command '#{command}'"
+    end
+  end
+
+  # @param [String] name
+  # @param [String, nil] dir
+  #
+  # @return [Integer]
+  def set(name, dir = nil)
+    validate_name!(name)
+    path = EnvAgent::Dotenv.absolute(dir || ask_for_dir(name))
+    raise EnvAgent::Error, "#{name}: that directory does not exist. Nothing saved." unless File.directory?(path)
+
+    excluder.apply!
+    checkout.main_dotenv.set(name, path)
+    winner = resolver(name).resolve
+    linker(name).link!(winner.path)
+    stdout.puts("#{name}: set, linked (#{winner.label})")
+    stdout.puts("  note: this worktree's #{EnvAgent::Dotenv::FILE} overrides it here") if winner.source == :worktree
+    0
+  end
+
+  # @param [String, nil] name
+  #
+  # @return [Integer]
+  def link(name)
+    excluder.apply!
+    linked = names(name).map { |each_name| link_name(each_name) }
+    linked.all? ? 0 : 1
+  end
+
+  # @param [String, nil] name
+  #
+  # @return [Integer]
+  def check(name)
+    resolved = names(name).map { |each_name| check_name(each_name) }
+    warn_outdated_agent
+    resolved.all? ? 0 : 1
+  end
+
+  # @param [String] name
+  #
+  # @return [Integer]
+  def unset(name)
+    validate_name!(name)
+    removed = checkout.main_dotenv.delete(name)
+    linker(name).remove!
+    say("#{name}: #{removed ? 'unset' : 'was not set'}, link removed")
+  end
+
+  # @return [Integer]
+  def init
+    excluder.apply!
+    actions = agent.write_repo!(checkout)
+    say(actions.empty? ? 'already up to date' : actions)
+  end
+
+  # @return [Integer]
+  def install_agent
+    changed = agent.write_user!(Dir.home)
+    say(changed ? "installed ~/#{EnvAgent::Agent::CLAUDE_COPY}" : 'already up to date')
+  end
+
+  # @param [String] name
+  #
+  # @return [TrueClass, FalseClass] whether it resolved
+  def link_name(name)
+    winner = resolver(name).resolve
+    return not_found(name) unless winner
+
+    linker(name).link!(winner.path)
+    stdout.puts("#{name}: linked (#{winner.label})")
+    true
+  end
+
+  # @param [String] name
+  #
+  # @return [FalseClass]
+  def not_found(name)
+    linker(name).remove!
+    stderr.puts("#{name}: not linked (#{summary(name)}).")
+    stderr.puts(not_found_hint(name))
+    false
+  end
+
+  # @param [String] name
+  #
+  # @return [TrueClass, FalseClass] whether it resolved
+  def check_name(name)
+    winner = resolver(name).resolve
+    stdout.puts("#{name}: #{winner ? "ok (#{winner.label})" : 'not found'}")
+    resolver(name).candidates.each { |candidate| stdout.puts("  #{candidate}") }
+    stdout.puts("  link #{linker(name).relative_path}: #{LINK_STATES.fetch(linker(name).state(winner&.path))}")
+    stdout.puts(not_found_hint(name)) unless winner
+    !winner.nil?
+  end
+
+  # @param [String] name
+  #
+  # @return [String]
+  def summary(name)
+    resolver(name).candidates.join(', ')
+  end
+
+  # @param [String] name
+  #
+  # @return [String]
+  def not_found_hint(name)
+    "  Run `env-agent set #{name}` (it asks for the directory), or ask the env-agent agent to set it up."
+  end
+
+  # @param [String] name
+  #
+  # @raise [EnvAgent::UsageError] when nothing was typed
+  #
+  # @return [String]
+  def ask_for_dir(name)
+    stderr.print("Directory for #{name} (input hidden): ")
+    line = stdin.tty? ? stdin.noecho(&:gets) : stdin.gets
+    stderr.puts
+    dir = line.to_s.strip
+    raise EnvAgent::UsageError, 'no directory given' if dir.empty?
+
+    dir
+  end
+
+  def warn_outdated_agent
+    version = agent.repo_version(checkout.root)
+    latest = EnvAgent::Agent.version_of(EnvAgent::Agent.template)
+    return unless version && version < latest
+
+    stderr.puts("warning: this repo's env-agent agent is version #{version}; this CLI ships version #{latest}. " \
+                'Run `env-agent init` to refresh it.')
+  end
+
+  # @param [String, nil] name
+  #
+  # @return [Array<String>] the given name, or every name saved in either .env.agents
+  def names(name)
+    return [validate_name!(name)] if name
+
+    list = (worktree_dotenv_names + checkout.main_dotenv.names).uniq.sort
+    stdout.puts("nothing set in #{EnvAgent::Dotenv::FILE} (use `env-agent set NAME DIR`)") if list.empty?
+    list
+  end
+
+  # @return [Array<String>]
+  def worktree_dotenv_names
+    checkout.main? ? [] : checkout.worktree_dotenv.names
+  end
+
+  # @param [String] name
+  #
+  # @raise [EnvAgent::UsageError] when the name cannot be stored or linked
+  #
+  # @return [String]
+  def validate_name!(name)
+    return name if EnvAgent::Dotenv.valid_name?(name)
+
+    raise EnvAgent::UsageError, "'#{name}' is not a valid name (letters, digits, '_', '.' and '-')"
+  end
+
+  # @param [Array<String>] args
+  # @param [Integer] min
+  # @param [Integer] max
+  #
+  # @raise [EnvAgent::UsageError] when the count is outside min..max
+  #
+  # @return [Array<String>]
+  def arity!(args, min, max)
+    raise EnvAgent::UsageError, 'wrong number of arguments' unless (min..max).cover?(args.size)
+
+    args
+  end
+
+  # @param [String, Array<String>] text
+  #
+  # @return [Integer]
+  def say(text)
+    stdout.puts(text)
+    0
+  end
+
+  # @return [EnvAgent::Checkout]
+  def checkout
+    @checkout ||= EnvAgent::Checkout.new
+  end
+
+  # @return [EnvAgent::Excluder]
+  def excluder
+    @excluder ||= EnvAgent::Excluder.new(checkout.common_dir)
+  end
+
+  # @return [EnvAgent::Agent]
+  def agent
+    @agent ||= EnvAgent::Agent.new
+  end
+
+  # @param [String] name
+  #
+  # @return [EnvAgent::Resolver]
+  def resolver(name)
+    @resolvers ||= {}
+    @resolvers[name] ||= EnvAgent::Resolver.new(name, checkout)
+  end
+
+  # @param [String] name
+  #
+  # @return [EnvAgent::Linker]
+  def linker(name)
+    EnvAgent::Linker.new(checkout, name)
+  end
+end

data/lib/env_agent/dotenv.rb

@@ -0,0 +1,124 @@
+require 'fileutils'
+
+# A .env.agents file: NAME=directory lines, optional quotes and # comments, no interpolation.
+class EnvAgent::Dotenv
+  FILE = '.env.agents'.freeze
+  NAME = /[A-Za-z0-9_][A-Za-z0-9_.-]*/
+  LINE = /\A\s*(?:export\s+)?(#{NAME})\s*=\s*(.*)\z/
+
+  # @param [String] name
+  #
+  # @return [TrueClass, FalseClass] whether the name can be stored and used as a link name
+  def self.valid_name?(name)
+    name.match?(/\A#{NAME}\z/)
+  end
+
+  # @param [String] value a directory as typed or saved
+  # @param [String] base directory a relative value is resolved against
+  #
+  # @return [String] the absolute path; a ~name that names no account stays literal, as in a shell
+  def self.absolute(value, base = Dir.pwd)
+    File.expand_path(value, base)
+  rescue ArgumentError
+    File.expand_path("./#{value}", base)
+  end
+
+  # @param [String] dir directory holding the .env.agents file
+  def initialize(dir)
+    @path = File.join(dir, FILE)
+  end
+
+  # @return [Array<String>] every name with a value
+  def names
+    values.reject { |_name, value| value.empty? }.keys
+  end
+
+  # @param [String] key
+  #
+  # @return [String, nil] the value as an absolute path, relative values resolved against the file's directory
+  def [](key)
+    value = values[key]
+    return if value.nil? || value.empty?
+
+    self.class.absolute(value, File.dirname(path))
+  end
+
+  # @param [String] key
+  # @param [String] value
+  def set(key, value)
+    replaced = false
+    kept = lines.each_with_object([]) do |line, out|
+      next out << line unless key_of(line) == key
+      next if replaced
+
+      out << "#{key}=#{quote(value)}"
+      replaced = true
+    end
+    kept << "#{key}=#{quote(value)}" unless replaced
+    write(kept)
+  end
+
+  # @param [String] key
+  #
+  # @return [TrueClass, FalseClass] whether the key was present
+  def delete(key)
+    kept = lines.reject { |line| key_of(line) == key }
+    return false if kept.size == lines.size
+
+    write(kept)
+    true
+  end
+
+  private
+
+  attr_reader :path
+
+  # @return [Array<String>]
+  def lines
+    File.exist?(path) ? File.read(path).split(/\r?\n/) : []
+  end
+
+  # @return [Hash{String => String}]
+  def values
+    lines.each_with_object({}) do |line, out|
+      match = LINE.match(line)
+      out[match[1]] = unquote(match[2]) if match
+    end
+  end
+
+  # @param [String] line
+  #
+  # @return [String, nil]
+  def key_of(line)
+    LINE.match(line)&.[](1)
+  end
+
+  # @param [String] raw
+  #
+  # @return [String]
+  def unquote(raw)
+    raw[/\A"([^"]*)"\s*(?:#.*)?\z/, 1] || raw[/\A'([^']*)'\s*(?:#.*)?\z/, 1] || raw.sub(/\s+#.*\z/, '').strip
+  end
+
+  # @param [String] value
+  #
+  # @raise [EnvAgent::Error] when the value cannot be stored safely
+  #
+  # @return [String]
+  def quote(value)
+    raise EnvAgent::Error, 'a directory name with a line break cannot be stored' if value.match?(/[\r\n]/)
+    return value unless value.match?(/[\s#'"]/)
+    return "\"#{value}\"" unless value.include?('"')
+    return "'#{value}'" unless value.include?("'")
+
+    raise EnvAgent::Error, 'a directory name with both kinds of quotes cannot be stored'
+  end
+
+  # @param [Array<String>] new_lines
+  def write(new_lines)
+    FileUtils.mkdir_p(File.dirname(path))
+    tmp = "#{path}.tmp-#{Process.pid}"
+    File.write(tmp, new_lines.empty? ? '' : "#{new_lines.join("\n")}\n")
+    File.rename(tmp, path)
+  end
+end

data/lib/env_agent/excluder.rb

@@ -0,0 +1,25 @@
+require 'fileutils'
+
+# Keeps env-agent's own files untracked through the shared info/exclude, so no repo edits .gitignore.
+class EnvAgent::Excluder
+  PATTERNS = ["/#{EnvAgent::Dotenv::FILE}", "/#{EnvAgent::Linker::DIR}/"].freeze
+
+  # @param [String] common_dir the git directory shared by every worktree
+  def initialize(common_dir)
+    @path = File.join(common_dir, 'info', 'exclude')
+  end
+
+  def apply!
+    content = File.exist?(path) ? File.read(path) : ''
+    missing = PATTERNS - content.split(/\r?\n/)
+    return if missing.empty?
+
+    content += "\n" unless content.empty? || content.end_with?("\n")
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, "#{content}#{missing.join("\n")}\n")
+  end
+
+  private
+
+  attr_reader :path
+end

data/lib/env_agent/linker.rb

@@ -0,0 +1,63 @@
+require 'fileutils'
+
+# The .env-agent/NAME symlink inside a checkout.
+class EnvAgent::Linker
+  DIR = '.env-agent'.freeze
+
+  # @param [EnvAgent::Checkout] checkout the checkout the link lives in
+  # @param [String] name registry name
+  def initialize(checkout, name)
+    @checkout = checkout
+    @name = name
+  end
+
+  # @return [String] the link as consumers reference it
+  def relative_path
+    "#{DIR}/#{name}"
+  end
+
+  # @param [String] target directory the link should point at
+  #
+  # @raise [EnvAgent::Error] when something other than a link is in the way, or .env-agent is a link
+  def link!(target)
+    remove!
+    raise EnvAgent::Error, "#{relative_path} exists and is not a link; move it away first" if File.exist?(path)
+
+    FileUtils.mkdir_p(own_dir!)
+    File.symlink(target, path)
+  end
+
+  # @raise [EnvAgent::Error] when .env-agent is a link
+  def remove!
+    own_dir!
+    File.unlink(path) if File.symlink?(path)
+  end
+
+  # @param [String, nil] target where the link should point, nil when nothing resolved
+  #
+  # @return [Symbol] :ok, :missing or :stale
+  def state(target)
+    return :missing unless File.symlink?(path) || File.exist?(path)
+    return :stale if target.nil?
+
+    File.realpath(path) == File.realpath(target) ? :ok : :stale
+  rescue Errno::ENOENT
+    :stale
+  end
+
+  private
+
+  attr_reader :checkout, :name
+
+  # @return [String]
+  def path
+    File.join(checkout.root, DIR, name)
+  end
+
+  # @raise [EnvAgent::Error] when .env-agent is a link
+  #
+  # @return [String]
+  def own_dir!
+    checkout.own_path!(DIR)
+  end
+end

data/lib/env_agent/resolver.rb

@@ -0,0 +1,67 @@
+# Finds the directory saved for a name, trying this worktree's .env.agents, then the main checkout's.
+class EnvAgent::Resolver
+  LABELS = {
+    worktree: 'worktree .env.agents',
+    main: 'main checkout .env.agents'
+  }.freeze
+
+  OUTCOMES = {
+    ok: 'ok',
+    unset: 'not set',
+    missing: 'directory missing'
+  }.freeze
+
+  Candidate = Struct.new(:source, :path, :outcome) do
+    # @return [String]
+    def label
+      LABELS.fetch(source)
+    end
+
+    # @return [String]
+    def outcome_text
+      OUTCOMES.fetch(outcome)
+    end
+
+    # @return [String]
+    def to_s
+      "#{label}: #{outcome_text}"
+    end
+  end
+
+  # @param [String] name
+  # @param [EnvAgent::Checkout] checkout
+  def initialize(name, checkout)
+    @name = name
+    @checkout = checkout
+  end
+
+  # @return [Array<EnvAgent::Resolver::Candidate>] every source, in lookup order
+  def candidates
+    @candidates ||= sources.map { |source, path| Candidate.new(source, path, outcome_of(path)) }
+  end
+
+  # @return [EnvAgent::Resolver::Candidate, nil] the first candidate whose directory exists
+  def resolve
+    candidates.find { |candidate| candidate.outcome == :ok }
+  end
+
+  private
+
+  attr_reader :name, :checkout
+
+  # @return [Array<Array(Symbol, String)>]
+  def sources
+    list = []
+    list << [:worktree, checkout.worktree_dotenv[name]] unless checkout.main?
+    list << [:main, checkout.main_dotenv[name]]
+  end
+
+  # @param [String, nil] path
+  #
+  # @return [Symbol]
+  def outcome_of(path)
+    return :unset if path.nil?
+
+    File.directory?(path) ? :ok : :missing
+  end
+end

data/lib/env_agent/version.rb

@@ -0,0 +1,3 @@
+module EnvAgent
+  VERSION = '0.1.1'.freeze
+end

data/lib/env_agent.rb

@@ -0,0 +1,15 @@
+require_relative 'env_agent/version'
+
+# A failure the user can fix; exits with status 1.
+class EnvAgent::Error < StandardError; end
+
+# A wrong command, argument or registry; exits with status 2.
+class EnvAgent::UsageError < EnvAgent::Error; end
+
+require_relative 'env_agent/checkout'
+require_relative 'env_agent/dotenv'
+require_relative 'env_agent/resolver'
+require_relative 'env_agent/linker'
+require_relative 'env_agent/excluder'
+require_relative 'env_agent/agent'
+require_relative 'env_agent/cli'

data/templates/agent.md

@@ -0,0 +1,34 @@
+---
+name: env-agent
+version: 1
+description: Set up the local directories this repo's skills and docs reach through .env-agent/<name> links. Use when such a link is missing or stale, or when `env-agent check` or `env-agent link` fails.
+tools: Bash
+---
+
+Some directories this repository's docs and skills need live outside it, in a
+different place on every machine. Each one is reached through a link at
+`.env-agent/<name>`, and the `env-agent` command manages those links.
+
+Run every command on the host, from inside this repository. Never inside Docker.
+
+## Rules
+
+- Never print, echo or repeat an absolute path. Not from `.env.agents`, not
+  from `readlink`, not one the user typed. Refer to a directory by its name
+  ("your design-system directory").
+- Never read or edit `.env.agents` yourself. Only `env-agent set` and
+  `env-agent unset` change it.
+- Never guess or choose a directory. The user decides.
+
+## Steps
+
+1. Run `env-agent link`. If every name links, report its output and stop.
+2. For each name that is missing, ask the user where that directory is on
+   their machine. The docs or skill that sent you here may say what it should
+   contain or where to get it; pass that on.
+3. Offer the private option first: the user can run `! env-agent set <name>`
+   themselves. It asks for the directory without showing it, so the path never
+   enters this conversation. If they do, skip to step 5.
+4. Run `env-agent set <name> <directory>`. If it says the directory does not
+   exist, tell the user and ask again; do not retry with a guess.
+5. Run `env-agent check` and report its output.

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: env-agent
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Panos Dalitsouris
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: env-agent resolves the external repos a project depends on from per-machine
+  .env.agents files and links them into every worktree, plus a Claude Code agent that
+  sets them up.
+executables:
+- env-agent
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/env-agent
+- lib/env_agent.rb
+- lib/env_agent/agent.rb
+- lib/env_agent/checkout.rb
+- lib/env_agent/cli.rb
+- lib/env_agent/dotenv.rb
+- lib/env_agent/excluder.rb
+- lib/env_agent/linker.rb
+- lib/env_agent/resolver.rb
+- lib/env_agent/version.rb
+- templates/agent.md
+homepage: https://github.com/PanosCodes/env-agent
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/PanosCodes/env-agent
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Link repos cloned outside a git checkout into it, from any worktree, without
+  printing paths.
+test_files: []