all_in_ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e016ce2d0604883066cae2f675273dc7a239291bcd591324e15eafcc3a2ced8
-  data.tar.gz: ed253dfd0c43ee7ee7e2c40546639500b50b2aa3bf97c548d5788386adddcc0a
+  metadata.gz: 6930c270ee263f4f0479be9854cf03b7af4db01e88e6ffa3ee585a2dad0f152b
+  data.tar.gz: f0491de4a159d7e327d6e6f270146ec5546213b82d6ed68dc5cbd1e3f1cd610a
 SHA512:
-  metadata.gz: 46e170a80461bbcdde8c26c73e81e479954199fe2332937f1a5aff96a76de3f33e9db9104440576ec23945a3cef658b018ee5b642a9bb55cd478fad7d3056144
-  data.tar.gz: 73e95dfb8c32a8ac29e5fa839d0deac2728d57f4d04ed15087f27df3878a371561cd9f55368a37c99f24dd6371a7e38950c7c9b0bed4cda9ebedafe3bbffa9b3
+  metadata.gz: d771a3ce9f1669f73d1bb441dfaaae80b180570ddcce09d6ea38f1c709fee3d9a8df778b6a8e72aa7b213591777066e51f06f5f016c892a1f3a4ab8b46993311
+  data.tar.gz: 66e7bffbd34e3f45f1bd8366e8cbd12f068f93de6f89e3ea6cf5424772e8cdd0224b360174d8b617cd4e09a48334fe1b123b6f84f051432b32d5a1179463de73

data/AGENTS.md

@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`all_in_ruby` is a zero-dependency CLI gem that adds (or removes) a single "write throwaway scripts in Ruby" instruction block to AI-agent instruction files — `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex/OpenCode/Cursor — either in the current repo (`local`) or in home-directory config (`global`). The core contract is: **additive and idempotent**. Existing file content is preserved verbatim; the block lives inside marker comments so it can be found and removed cleanly.
+
+## Commands
+
+The project uses `.ruby-version` (3.4.7) with **chruby**. Prefix Ruby commands with the activation, e.g.:
+`source /opt/homebrew/share/chruby/chruby.sh && chruby ruby-3.4.7 && <cmd>`
+
+- Install deps: `bundle install`
+- Run all tests: `bundle exec rake test` (Minitest; `rake` default task is `test`)
+- Run one test file: `bundle exec rake test TEST=test/installer_test.rb`
+- Run one test by name: `bundle exec ruby -Itest test/installer_test.rb -n test_install_is_idempotent`
+- Run the CLI from source (bypasses installed gem): `bundle exec exe/all-in-ruby install --dry-run`
+- Build gem: `bundle exec rake build` — Release: `bundle exec rake release` (both from `bundler/gem_tasks`)
+
+There is no linter configured. `--dry-run` (`-n`) is the safest way to exercise real behavior without touching disk.
+
+## Architecture
+
+Four collaborating layers under `lib/all_in_ruby/`, loaded by `lib/all_in_ruby.rb`:
+
+- **`CLI`** (`cli.rb`) — parses argv with `OptionParser`, resolves defaults, calls the installer, formats output. It owns two label maps, `STATUS_LABELS` and `DRY_RUN_LABELS`, that translate the installer's status *symbols* into user-facing strings. The CLI never touches the filesystem itself.
+- **`Installer`** (`installer.rb`) — the orchestrator. `path_for(agent, scope)` is the single source of truth mapping an `(agent, scope)` pair to a file path (or `nil`). `install`/`uninstall`/`status` each iterate targets via `each_target` and return an array of `Result` structs `(agent, path, status, diff, backup)`.
+- **`Instruction`** (`instruction.rb`) — owns the block text and the marker comments (`<!-- BEGIN all_in_ruby -->` / `<!-- END all_in_ruby -->`). `installed?` detects the block; `remove` strips it with a regex. Change the wording here in exactly one place.
+- **`Diff`** (`diff.rb`) — pure-function unified-diff generator for dry-run previews. It assumes a single contiguous edit per file (that assumption is what makes the common-prefix/suffix approach valid), and handles the "no newline at end of file" case.
+
+Data flows one direction: `CLI → Installer → (Instruction, Diff)`. `Result` is the boundary object between the installer and the CLI.
+
+### Non-obvious behaviors to preserve
+
+These are the invariants that most of the code exists to protect — read `installer.rb` and the shared-file tests before changing any of them:
+
+- **Multiple agents share one file.** Locally, `codex`, `opencode`, and `cursor` all map to `AGENTS.md`. So installing several agents in one run produces e.g. `[:created, :already_installed, :already_installed]` — not three creates. Tests assert this exact sequence.
+- **Dry run simulates writes in memory.** The `planned` hash (`installer.rb:82-97`) holds what each file *would* contain, so later same-file agents in a dry run report the same statuses (and the diff is emitted only once) a real run would. Don't "simplify" this away — it's load-bearing.
+- **`Cursor` + `global` is `:manual`** — `path_for` returns `nil` because Cursor has no global rules file. The installer yields `:manual` and writes nothing; the CLI prints the instruction body to paste into Cursor Settings > Rules. This only happens for `install`, not `status`.
+- **Backups before overwriting.** `install`/`uninstall` copy an existing file to a timestamped `<path>.YYYYMMDD-HHMMSS.bak` before writing — but never on `:created`, since a brand-new file has nothing to preserve. The clock is injected (`Installer.new(clock:)`) so tests can assert the exact name. `apply` returns `[status, diff, backup]` and the CLI lists the backups at the end of the run. `--no-backup` skips it; a dry run names the backup it *would* make without creating it.
+- **`CODEX_HOME` overrides `~/.codex`** for the codex global path (empty string is ignored), matching Codex's own resolution.
+- **Scope defaults differ by command** (`cli.rb:scopes_for`): `status` with no scope flag reports *both* local and global (it's read-only); `install`/`uninstall` stay `local` unless `--global` is given. Scope and agent flags both *combine* rather than last-wins.
+- **Separator logic** (`separator_for`): when appending to an existing file, the installer inserts the right number of newlines so the block is separated by exactly one blank line, whether or not the file ended with a trailing newline.
+
+## Testing conventions
+
+Everything is dependency-injected for isolation — no mocking, no global state:
+- `Installer.new(root:, home:, env:, clock:)` runs against `Dir.mktmpdir` temp roots; tests assert on real files. Inject `clock:` (a `-> { Time }` lambda) to make timestamped backup names deterministic.
+- `CLI.new(stdout:, stderr:, installer:)` captures output in `StringIO` and receives an installer wired to temp dirs.
+
+When adding a feature, cover both the installer level (file effects, status symbols) and the CLI level (exit code, printed labels, diffs). The shared-`AGENTS.md` and dry-run-simulation cases are the ones most likely to break — mirror the existing tests for them.

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.0 (2026-08-03)
+
+- `install` and `uninstall` now back up any existing file before modifying it, writing a timestamped copy (`CLAUDE.md.20260802-153000.bak`) next to the original and listing the backups created at the end of the run. New files are not backed up. Pass `--no-backup` to skip, or `--dry-run` to preview which backups would be made
+- Add `--dry-run` (`-n`) to `install` and `uninstall`: prints a unified diff per file showing the exact lines that would be added or removed, without writing anything. Dry runs simulate writes in memory, so agents sharing `AGENTS.md` report the same statuses a real run would
+- `status` with no scope flag now reports both local and global scopes (previously it silently checked only local)
+- Add `--local` flag; scope flags combine, so `install --local --global` targets both scopes in one run
+
+## 0.1.1 (2026-07-22)
+
+- Support OpenCode: local `AGENTS.md` (shared with Codex) and global `~/.config/opencode/AGENTS.md`
+- Support Cursor: local `AGENTS.md` (shared with Codex); `--global` prints the instruction to paste into Cursor Settings > Rules, since Cursor has no global rules file
+- Agent flags now combine (`--claude --codex` targets both) instead of last-flag-wins
+
 ## 0.1.0 (2026-07-20)
 
 - First release

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/README.md

@@ -2,7 +2,7 @@
 
 Tell your AI coding agents to write scripts in Ruby.
 
-Adds a "write throwaway and utility scripts in Ruby" instruction to agent instruction files - `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex. Additive and idempotent: your existing instructions are never modified.
+Adds a "write throwaway and utility scripts in Ruby" instruction to agent instruction files - `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex, OpenCode, and Cursor. Additive and idempotent: your existing instructions are never modified.
 
 ## Installation
 
@@ -24,29 +24,119 @@ Or add it globally, for every project:
 all-in-ruby install --global
 ```
 
-This writes to `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`. If `CODEX_HOME` is set, it is used instead of `~/.codex`, matching Codex's own resolution.
+This writes to `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, and `~/.config/opencode/AGENTS.md`. If `CODEX_HOME` is set, it is used instead of `~/.codex`, matching Codex's own resolution.
+
+Cursor has no global rules file — its global "User Rules" live only in the app settings. For `--global`, the instruction text is printed so you can paste it into Cursor Settings > Rules.
 
 ## Usage
 
-Target a single agent:
+Target one or more agents:
 
 ```sh
 all-in-ruby install --claude
-all-in-ruby install --codex
+all-in-ruby install --codex --opencode
+all-in-ruby install --cursor
 ```
 
-Check where the instruction is installed:
+Codex, OpenCode, and Cursor all read `AGENTS.md` from the project root, so locally they share one file: installing for any of them covers all three, and uninstalling removes the block for all three.
+
+Check where the instruction is installed. With no scope flag, `status` reports both the current repo and the global files:
 
 ```sh
 all-in-ruby status
 ```
 
+```text
+local:
+  claude   /path/to/repo/CLAUDE.md: installed
+  codex    /path/to/repo/AGENTS.md: not installed
+  ...
+global:
+  claude   ~/.claude/CLAUDE.md: not installed
+  codex    ~/.codex/AGENTS.md: installed
+  ...
+```
+
+Pass `--local` or `--global` to check a single scope.
+
 Remove it:
 
 ```sh
 all-in-ruby uninstall
 ```
 
+### Backups
+
+Before `install` or `uninstall` modifies a file that already exists, it writes a timestamped copy next to the original and lists the backups at the end of the run:
+
+```text
+claude   /path/to/repo/CLAUDE.md: instructions added
+
+Backups created:
+  /path/to/repo/CLAUDE.md.20260802-153000.bak
+```
+
+Only existing files are backed up — creating a brand-new `CLAUDE.md` or `AGENTS.md` makes no backup, since there is nothing to preserve. Each run uses a fresh timestamp, so an earlier backup is never overwritten. Pass `--no-backup` to skip them, or `--dry-run` to see which backups would be made without writing anything.
+
+### Dry run
+
+Preview what `install` or `uninstall` would change without writing anything:
+
+```sh
+all-in-ruby install --dry-run
+all-in-ruby uninstall -n
+```
+
+For each file, dry run prints the status a real run would produce, followed by a unified diff showing the exact location of the change:
+
+```text
+claude   /path/to/repo/CLAUDE.md: instructions would be added
+codex    /path/to/repo/AGENTS.md: would be created
+opencode /path/to/repo/AGENTS.md: would already be covered, no change
+cursor   /path/to/repo/AGENTS.md: would already be covered, no change
+
+--- /path/to/repo/CLAUDE.md
++++ /path/to/repo/CLAUDE.md
+@@ -1,3 +1,19 @@
+ # My project
+ 
+ Always use tabs.
++
++<!-- BEGIN all_in_ruby -->
++## Scripts
++
++Write throwaway and utility scripts (data munging, one-off migrations,
+...
++<!-- END all_in_ruby -->
+
+--- /dev/null
++++ /path/to/repo/AGENTS.md
+@@ -0,0 +1,15 @@
++<!-- BEGIN all_in_ruby -->
++## Scripts
+...
+```
+
+A dry run simulates its own writes, so the statuses match what a real run would report - above, creating `AGENTS.md` for Codex also covers OpenCode and Cursor, so only one diff is shown for it. New files appear as `--- /dev/null`.
+
+The diffs are standard unified format: pipe the output to `delta` or `bat -l diff` for coloring, or apply it with `patch -p0`.
+
+### Options
+
+```text
+--local         Target the current repo (default for install/uninstall)
+--global        Target global files instead of the current repo
+--claude        Claude Code (CLAUDE.md)
+--codex         Codex (AGENTS.md)
+--opencode      OpenCode (AGENTS.md)
+--cursor        Cursor (AGENTS.md; no global file)
+-n, --dry-run   Preview changes as diffs without writing any file
+--no-backup     Skip backing up existing files before modifying them
+-v, --version   Print version
+```
+
+With no agent flags, all agents are targeted. Scope flags combine too: `install --local --global` installs in both places. Without a scope flag, `install` and `uninstall` stay local, while `status` reports both scopes.
+
 ## How It Works
 
 The instruction is appended inside marker comments:

data/exe/all-in-ruby

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require "all_in_ruby"
 

data/lib/all_in_ruby/cli.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 require "optparse"
 
 module AllInRuby
   class CLI
-    COMMANDS = ["install", "uninstall", "status"].freeze
+    COMMANDS = %w[install uninstall status].freeze
 
     STATUS_LABELS = {
       created: "created",
@@ -10,9 +12,18 @@ module AllInRuby
       already_installed: "already installed, left untouched",
       removed: "instructions removed",
       not_installed: "not installed",
-      installed: "installed"
+      installed: "installed",
+      manual: "no global rules file; use Cursor Settings > Rules"
     }.freeze
 
+    DRY_RUN_LABELS = STATUS_LABELS.merge(
+      created: "would be created",
+      updated: "instructions would be added",
+      already_installed: "would already be covered, no change",
+      removed: "instructions would be removed",
+      not_installed: "not installed, nothing to remove"
+    ).freeze
+
     def initialize(stdout: $stdout, stderr: $stderr, installer: Installer.new)
       @stdout = stdout
       @stderr = stderr
@@ -20,7 +31,7 @@ module AllInRuby
     end
 
     def run(argv)
-      options = {agents: Installer::AGENTS.dup, scope: "local"}
+      options = { agents: [], scopes: [], dry_run: false, backup: true }
       parser = build_parser(options)
       parser.parse!(argv)
 
@@ -30,9 +41,38 @@ module AllInRuby
         return 1
       end
 
-      results = @installer.public_send(command, agents: options[:agents], scope: options[:scope])
+      agents = options[:agents].empty? ? Installer::AGENTS.dup : options[:agents]
+      scopes = scopes_for(command, options[:scopes])
+      dry_run = options[:dry_run] && command != "status"
+
+      scope_results = scopes.map do |scope|
+        results =
+          if command == "status"
+            @installer.status(agents: agents, scope: scope)
+          else
+            @installer.public_send(command, agents: agents, scope: scope, dry_run: dry_run, backup: options[:backup])
+          end
+        [scope, results]
+      end
+
+      print_statuses(scope_results, dry_run ? DRY_RUN_LABELS : STATUS_LABELS)
+
+      results = scope_results.flat_map { |_scope, scope_result| scope_result }
       results.each do |result|
-        @stdout.puts "#{result.agent.ljust(6)} #{result.path}: #{STATUS_LABELS.fetch(result.status)}"
+        next unless result.diff
+
+        @stdout.puts
+        @stdout.puts result.diff
+      end
+
+      print_backups(results, dry_run)
+
+      if command == "install" && results.any? { |result| result.status == :manual }
+        @stdout.puts
+        @stdout.puts "Cursor has no global rules file. To apply the instruction globally,"
+        @stdout.puts "paste this into Cursor Settings > Rules:"
+        @stdout.puts
+        @stdout.puts Instruction.body
       end
       0
     rescue OptionParser::ParseError => e
@@ -42,31 +82,76 @@ module AllInRuby
 
     private
 
+    # status is read-only, so with no scope flag it reports both scopes;
+    # install/uninstall write files, so they stay local unless asked.
+    def scopes_for(command, requested)
+      return requested.uniq unless requested.empty?
+
+      command == "status" ? Installer::SCOPES.dup : ["local"]
+    end
+
+    def print_backups(results, dry_run)
+      backups = results.filter_map(&:backup)
+      return if backups.empty?
+
+      @stdout.puts
+      @stdout.puts(dry_run ? "Backups that would be created:" : "Backups created:")
+      backups.each { |backup| @stdout.puts "  #{backup}" }
+    end
+
+    def print_statuses(scope_results, labels)
+      show_headers = scope_results.length > 1
+      indent = show_headers ? "  " : ""
+      scope_results.each do |scope, results|
+        @stdout.puts "#{scope}:" if show_headers
+        results.each do |result|
+          location = result.path || "(none)"
+          @stdout.puts "#{indent}#{result.agent.ljust(8)} #{location}: #{labels.fetch(result.status)}"
+        end
+      end
+    end
+
     def build_parser(options)
       OptionParser.new do |opts|
         opts.banner = <<~BANNER
           Usage: all-in-ruby COMMAND [options]
 
           Adds a "write scripts in Ruby" instruction to AI agent instruction
-          files (CLAUDE.md for Claude Code, AGENTS.md for Codex). Additive and
-          idempotent: existing content is never modified.
+          files: CLAUDE.md for Claude Code, AGENTS.md for Codex, OpenCode, and
+          Cursor. Additive and idempotent: existing content is never modified.
 
           Commands:
               install      add the instruction block
               uninstall    remove the instruction block
-              status       show where the block is installed
+              status       show where the block is installed (both scopes unless one is given)
 
           Options:
         BANNER
 
-        opts.on("--global", "Target global files (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md)") do
-          options[:scope] = "global"
+        opts.on("--local", "Target the current repo (default for install/uninstall)") do
+          options[:scopes] << "local"
+        end
+        opts.on("--global",
+                "Target global files (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.config/opencode/AGENTS.md)") do
+          options[:scopes] << "global"
+        end
+        opts.on("--claude", "Claude Code (CLAUDE.md)") do
+          options[:agents] << "claude"
+        end
+        opts.on("--codex", "Codex (AGENTS.md)") do
+          options[:agents] << "codex"
+        end
+        opts.on("--opencode", "OpenCode (AGENTS.md)") do
+          options[:agents] << "opencode"
+        end
+        opts.on("--cursor", "Cursor (AGENTS.md; no global file)") do
+          options[:agents] << "cursor"
         end
-        opts.on("--claude", "Only Claude Code (CLAUDE.md)") do
-          options[:agents] = ["claude"]
+        opts.on("-n", "--dry-run", "Preview changes as diffs without writing any file") do
+          options[:dry_run] = true
         end
-        opts.on("--codex", "Only Codex (AGENTS.md)") do
-          options[:agents] = ["codex"]
+        opts.on("--no-backup", "Skip backing up existing files before modifying them") do
+          options[:backup] = false
         end
         opts.on("-v", "--version", "Print version") do
           @stdout.puts VERSION

data/lib/all_in_ruby/diff.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module AllInRuby
+  # Builds unified diffs for dry-run previews. The installer only ever makes
+  # one contiguous edit per file (appending or removing a single block), so a
+  # common prefix/suffix comparison finds the exact changed region.
+  module Diff
+    CONTEXT_LINES = 3
+    NO_NEWLINE_MARKER = "\"
+
+    def self.unified(old_content, new_content, path)
+      old_lines = (old_content || "").lines
+      new_lines = new_content.lines
+
+      prefix = common_prefix_length(old_lines, new_lines)
+      suffix = common_suffix_length(old_lines, new_lines, prefix)
+
+      removed = old_lines[prefix...(old_lines.length - suffix)]
+      added = new_lines[prefix...(new_lines.length - suffix)]
+      lead = [prefix, CONTEXT_LINES].min
+      trail = [suffix, CONTEXT_LINES].min
+
+      output = []
+      output << "--- #{old_content ? path : File::NULL}"
+      output << "+++ #{path}"
+      output << hunk_header(prefix, lead, trail, removed.length, added.length)
+      old_lines[prefix - lead, lead].each { |line| append(output, " ", line) }
+      removed.each { |line| append(output, "-", line) }
+      added.each { |line| append(output, "+", line) }
+      old_lines[old_lines.length - suffix, trail].each { |line| append(output, " ", line) }
+      "#{output.join("\n")}\n"
+    end
+
+    def self.common_prefix_length(old_lines, new_lines)
+      limit = [old_lines.length, new_lines.length].min
+      count = 0
+      count += 1 while count < limit && old_lines[count] == new_lines[count]
+      count
+    end
+
+    def self.common_suffix_length(old_lines, new_lines, prefix)
+      limit = [old_lines.length, new_lines.length].min - prefix
+      count = 0
+      count += 1 while count < limit && old_lines[-1 - count] == new_lines[-1 - count]
+      count
+    end
+
+    def self.hunk_header(prefix, lead, trail, removed_count, added_count)
+      old_range = range(prefix - lead, lead + removed_count + trail)
+      new_range = range(prefix - lead, lead + added_count + trail)
+      "@@ -#{old_range} +#{new_range} @@"
+    end
+
+    def self.range(start_index, count)
+      count.zero? ? "#{start_index},0" : "#{start_index + 1},#{count}"
+    end
+
+    def self.append(output, sign, line)
+      output << "#{sign}#{line.chomp}"
+      output << NO_NEWLINE_MARKER unless line.end_with?("\n")
+    end
+
+    private_class_method :common_prefix_length, :common_suffix_length,
+                         :hunk_header, :range, :append
+  end
+end

data/lib/all_in_ruby/installer.rb

@@ -1,54 +1,60 @@
+# frozen_string_literal: true
+
 require "fileutils"
 
 module AllInRuby
   class Installer
-    AGENTS = ["claude", "codex"].freeze
-    SCOPES = ["local", "global"].freeze
+    AGENTS = %w[claude codex opencode cursor].freeze
+    SCOPES = %w[local global].freeze
 
-    Result = Struct.new(:agent, :path, :status)
+    Result = Struct.new(:agent, :path, :status, :diff, :backup)
 
-    def initialize(root: Dir.pwd, home: Dir.home, env: ENV)
+    def initialize(root: Dir.pwd, home: Dir.home, env: ENV, clock: -> { Time.now })
       @root = root
       @home = home
       @env = env
+      @clock = clock
     end
 
     def path_for(agent, scope)
       case [agent, scope]
-      when ["claude", "local"] then File.join(@root, "CLAUDE.md")
-      when ["claude", "global"] then File.join(@home, ".claude", "CLAUDE.md")
-      when ["codex", "local"] then File.join(@root, "AGENTS.md")
-      when ["codex", "global"] then File.join(codex_home, "AGENTS.md")
+      when %w[claude local] then File.join(@root, "CLAUDE.md")
+      when %w[claude global] then File.join(@home, ".claude", "CLAUDE.md")
+      when %w[codex local] then File.join(@root, "AGENTS.md")
+      when %w[codex global] then File.join(codex_home, "AGENTS.md")
+      when %w[opencode local] then File.join(@root, "AGENTS.md")
+      when %w[opencode global] then File.join(@home, ".config", "opencode", "AGENTS.md")
+      when %w[cursor local] then File.join(@root, "AGENTS.md")
+      # Cursor has no documented global rules file; User Rules live in the app settings
+      when %w[cursor global] then nil
       else
         raise ArgumentError, "unknown agent or scope: #{agent}, #{scope}"
       end
     end
 
-    def install(agents:, scope:)
+    def install(agents:, scope:, dry_run: false, backup: true)
+      planned = {}
       each_target(agents, scope) do |path|
-        content = File.exist?(path) ? File.read(path) : nil
+        content = current_content(path, planned)
 
         if content && Instruction.installed?(content)
           :already_installed
         elsif content
-          separator = content.empty? || content.end_with?("\n\n") ? "" : (content.end_with?("\n") ? "\n" : "\n\n")
-          File.write(path, content + separator + Instruction.block)
-          :updated
+          new_content = content + separator_for(content) + Instruction.block
+          apply(path, content, new_content, :updated, dry_run, backup, planned)
         else
-          FileUtils.mkdir_p(File.dirname(path))
-          File.write(path, Instruction.block)
-          :created
+          apply(path, nil, Instruction.block, :created, dry_run, backup, planned)
         end
       end
     end
 
-    def uninstall(agents:, scope:)
+    def uninstall(agents:, scope:, dry_run: false, backup: true)
+      planned = {}
       each_target(agents, scope) do |path|
-        content = File.exist?(path) ? File.read(path) : nil
+        content = current_content(path, planned)
 
         if content && Instruction.installed?(content)
-          File.write(path, Instruction.remove(content))
-          :removed
+          apply(path, content, Instruction.remove(content), :removed, dry_run, backup, planned)
         else
           :not_installed
         end
@@ -70,10 +76,44 @@ module AllInRuby
       codex_home && !codex_home.empty? ? codex_home : File.join(@home, ".codex")
     end
 
+    def separator_for(content)
+      return "" if content.empty? || content.end_with?("\n\n")
+
+      content.end_with?("\n") ? "\n" : "\n\n"
+    end
+
+    # Planned holds the content a dry run would have written, so later agents
+    # sharing the same file (codex/opencode/cursor all use AGENTS.md locally)
+    # report the same statuses a real run would produce.
+    def current_content(path, planned)
+      planned.fetch(path) { File.exist?(path) ? File.read(path) : nil }
+    end
+
+    # Returns [status, diff, backup]. A backup is made only when an existing
+    # file is modified (never on create); a dry run computes the name it would
+    # use so the preview can report it, but writes nothing.
+    def apply(path, old_content, new_content, status, dry_run, backup, planned)
+      backup_path = backup && old_content ? backup_path_for(path) : nil
+      if dry_run
+        planned[path] = new_content
+        [status, Diff.unified(old_content, new_content, path), backup_path]
+      else
+        FileUtils.cp(path, backup_path) if backup_path
+        FileUtils.mkdir_p(File.dirname(path)) unless old_content
+        File.write(path, new_content)
+        [status, nil, backup_path]
+      end
+    end
+
+    def backup_path_for(path)
+      "#{path}.#{@clock.call.strftime("%Y%m%d-%H%M%S")}.bak"
+    end
+
     def each_target(agents, scope)
       agents.map do |agent|
         path = path_for(agent, scope)
-        Result.new(agent, path, yield(path))
+        status, diff, backup = path ? yield(path) : :manual
+        Result.new(agent, path, status, diff, backup)
       end
     end
   end

data/lib/all_in_ruby/instruction.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 module AllInRuby
   module Instruction
-    BEGIN_MARKER = "<!-- BEGIN all_in_ruby -->".freeze
-    END_MARKER = "<!-- END all_in_ruby -->".freeze
+    BEGIN_MARKER = "<!-- BEGIN all_in_ruby -->"
+    END_MARKER = "<!-- END all_in_ruby -->"
 
-    BODY = <<~MARKDOWN.freeze
+    BODY = <<~MARKDOWN
       ## Scripts
 
       Write throwaway and utility scripts (data munging, one-off migrations,
@@ -25,6 +27,10 @@ module AllInRuby
       BLOCK
     end
 
+    def self.body
+      BODY
+    end
+
     def self.installed?(content)
       content.include?(BEGIN_MARKER)
     end

data/lib/all_in_ruby/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module AllInRuby
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/all_in_ruby.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 require_relative "all_in_ruby/version"
 require_relative "all_in_ruby/instruction"
+require_relative "all_in_ruby/diff"
 require_relative "all_in_ruby/installer"
 require_relative "all_in_ruby/cli"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: all_in_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Lucian Ghinda
@@ -18,12 +18,15 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - exe/all-in-ruby
 - lib/all_in_ruby.rb
 - lib/all_in_ruby/cli.rb
+- lib/all_in_ruby/diff.rb
 - lib/all_in_ruby/installer.rb
 - lib/all_in_ruby/instruction.rb
 - lib/all_in_ruby/version.rb