rails-hyperdrive 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2a834f37a237a640a01631dc04ab991791e87535b90cb5fc7e44f69e24dccd0
-  data.tar.gz: 03dd055200f9407f86719da8a221207b1b0a5987e12657284399ce5d8fae2840
+  metadata.gz: 8d3970fe19124e7d291ca3ae41b4b97b3ca9b2fe4634d2f4806b58142a01ec87
+  data.tar.gz: 0d8b0cc84e29b59e917a1b7a1c1fb92d8b5a54560ab47294d906f56fb4bcaa3f
 SHA512:
-  metadata.gz: cc5dcb6940b29b6bf182e704f9419d336616fe999dc214325697d3b6a9aa4673fca9b003ba4a621eb348ea0be34dc892f648a1e6882add7cf261b7710a29d597
-  data.tar.gz: b810742750f5bd8a747a1c27fee799d80164bb306ad69ad4ff0445a8a6deefdde1171922058ee325d55b8df2a1b187a2e0e3fb2ab2ec41a204ccbce50bdca228
+  metadata.gz: 14031a19b195ee3802a88bbe54af5851495463e079b45fda9d9747fda7c9606d512eee8eb376fb191b21cb1e5db586a7b32bb15bc9181251032cf60c6d91a4f6
+  data.tar.gz: 9ef4f32b7b801102e4348a2a4297cf502b7185ce0ec2af0984d9782ed4cd6a33208adb7287a9ee2e3b719d41ac23d2281f8b9769f9800ff499a84bda47b2e3c8

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-09-06
+
+### Fixed
+
+- **`hyperdrive:sync --resolve` no longer deletes a sidecar on a bare exit 0.**
+  The command must also have changed `$MERGED`, matching `git mergetool`'s
+  default of not trusting the exit code alone. Exit 0 with the live file
+  untouched is reported as unresolved — `command exited 0 but wrote nothing`
+  (`command exited 0 but $MERGED is missing` when the command deleted it) — and
+  leaves the live file, the sidecar, and the lockfile exactly as they were, so
+  an agent that was denied every write no longer loses the pending upstream
+  delivery.
+
+### Changed
+
+- **The suggested Claude Code resolver command is now `claude -p $PROMPT
+  --allowedTools Read,Edit,Write`.** `--permission-mode acceptEdits` denies
+  writes under `.claude/`, where every hyperdrive artifact lives, and cannot read
+  `$BASE`, which sits outside the app.
+
 ## [0.9.0] - 2026-09-05
 
 ### Added
@@ -813,7 +833,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `hyperdrive:init` generator that installs architecture skills and auto-discovers
   per-gem skills.
 
-[Unreleased]: https://github.com/rails-hyperdrive/rails-hyperdrive/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/rails-hyperdrive/rails-hyperdrive/compare/v0.9.1...HEAD
+[0.9.1]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.9.1
 [0.9.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.9.0
 [0.8.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.8.0
 [0.7.0]: https://github.com/rails-hyperdrive/rails-hyperdrive/releases/tag/v0.7.0

data/README.md

@@ -119,7 +119,7 @@ With no companion gems, `hyperdrive:init` sets up just the plumbing (`.mcp.json`
 | `--merge` | Rewritten with a git three-way merge (base = the gem version you last installed, ours = your file, theirs = the new upstream) when it applies cleanly | Kept | `--sidecar`, whenever git cannot produce a clean result |
 | `--sidecar` | Untouched; the new upstream body is written next to it as `<file>.new` | Kept, byte-for-byte | — |
 | `--overwrite` | Restored to the gem-shipped content | Discarded | — |
-| `--resolve` | Delivers as `--sidecar` (or as `--merge`, when both are given), then hands each unresolved `<file>.new` to a command you configure; exit 0 deletes the sidecar | Up to your command | — |
+| `--resolve` | Delivers as `--sidecar` (or as `--merge`, when both are given), then hands each unresolved `<file>.new` to a command you configure; exit 0 after the command changed the file deletes the sidecar | Up to your command | — |
 
 `--merge`, `--sidecar`, and `--overwrite` are mutually exclusive. `--resolve` stacks on top: alone it means "sidecar, then resolve", `--merge --resolve` means "git merges what it can, your command takes the rest", and `--overwrite --resolve` is rejected because an overwrite leaves nothing to resolve. Every combination accepts `--dry-run`, which prints the plan and writes nothing.
 
@@ -129,12 +129,12 @@ A sidecar is inert (Claude Code loads only `SKILL.md` and the `index.md` `@`-lin
 
 The sidecar pair is also how an AI coding agent reconciles for you, with no extra machinery: run `bin/rails hyperdrive:sync --sidecar`, have the agent merge the live/`.new` pair semantically (it has both full texts), then delete the sidecar.
 
-**`--resolve`: hand the sidecars to a tool.** `--resolve` automates that last step, `git mergetool` style. After delivery it hands every unresolved `<file>.new` — from this run or left over from an earlier one — to the command named in `.hyperdrive/config.yml`, and deletes the sidecar when that command exits 0. The gem ships no command of its own, so nothing runs that you did not name:
+**`--resolve`: hand the sidecars to a tool.** `--resolve` automates that last step, `git mergetool` style. After delivery it hands every unresolved `<file>.new` — from this run or left over from an earlier one — to the command named in `.hyperdrive/config.yml`, and deletes the sidecar when that command exits 0 having changed the file. The gem ships no command of its own, so nothing runs that you did not name:
 
 ```yaml
 # .hyperdrive/config.yml
 resolve:
-  command: claude -p --permission-mode acceptEdits $PROMPT
+  command: claude -p $PROMPT --allowedTools Read,Edit,Write
 ```
 
 ```sh
@@ -143,6 +143,8 @@ bin/rails hyperdrive:sync --merge --resolve   # git merges what it can, your too
 git diff                                      # then you review
 ```
 
+That form grants the tools rather than setting `--permission-mode acceptEdits`, because `acceptEdits` denies writes under `.claude/`, where every artifact lives, and cannot read `$BASE`, which is outside the app; `$PROMPT` comes first because `--allowedTools` takes every following argument.
+
 The command is split with shell word rules and run with no shell, from the app root. Each argument gets these placeholders substituted, and every one is also exported as an environment variable (`$LOCAL` → `HYPERDRIVE_LOCAL`, and so on), so a wrapper script needs no argument parsing:
 
 | Placeholder | Value |
@@ -156,19 +158,9 @@ The command is split with shell word rules and run with no shell, from the app r
 | `$KIND` | `skill`, `guideline`, `agent`, `command`, or `skill_support` |
 | `$PROMPT` | Ready-made instructions for an agent, naming the paths above |
 
-`$BASE` is a temporary file outside the app, removed as soon as the command returns, so a tool that is confined to the project directory needs it granted explicitly:
-
-```sh
-#!/usr/bin/env bash
-# bin/hyperdrive-resolve, used as `command: bin/hyperdrive-resolve`
-args=(-p --permission-mode acceptEdits)
-[ -n "$HYPERDRIVE_BASE" ] && args+=(--add-dir "$(dirname "$HYPERDRIVE_BASE")")
-exec claude "${args[@]}" "$HYPERDRIVE_PROMPT"
-```
-
 Replace the shipped prompt with your own ERB template — same placeholders, as lower-case locals (`local`, `remote`, `base`, `merged`, `source`, `previous_source`, `kind`) — with `resolve.prompt: .hyperdrive/resolve-prompt.md.erb`.
 
-Exit 0 is a promise: the sidecar is deleted on the strength of it, whether or not `$MERGED` was written. Any other exit — including a command that is not on your PATH — leaves the live file, the sidecar, and the lockfile exactly as they were, with the reason printed, so a failed resolve is just an ordinary unresolved sidecar. `--resolve` runs only on an explicit `hyperdrive:sync`, never during `bundle install`. `--dry-run` prints what it would hand off and runs nothing. A sidecar you edited yourself is never handed to the command.
+Exit 0 is honored only when the command changed `$MERGED` — git's own `mergetool` default (`trustExitCode = false`). Exit 0 with the file untouched is reported as `command exited 0 but wrote nothing` and, like any other exit — including a command that is not on your PATH — leaves the live file, the sidecar, and the lockfile exactly as they were, with the reason printed, so a failed resolve is just an ordinary unresolved sidecar. `--resolve` runs only on an explicit `hyperdrive:sync`, never during `bundle install`. `--dry-run` prints what it would hand off and runs nothing. A sidecar you edited yourself is never handed to the command.
 
 **`bin/rails hyperdrive:discover`: find what you're missing.** Queries rubygems for companion gems published for your stack that you haven't installed yet, and prints the `bundle add` lines to run. It is read-only, caches results for 24h (`--refresh` re-queries), and never touches your Gemfile or makes network calls unless you invoke it.
 

data/lib/generators/hyperdrive/install/install_generator.rb

@@ -40,10 +40,10 @@ module Rails
           #   must write), $SOURCE, $PREVIOUS_SOURCE, $KIND, and $PROMPT (the
           #   instructions to give an agent) are substituted per argument, and each
           #   is also exported as HYPERDRIVE_LOCAL, HYPERDRIVE_REMOTE, and so on.
-          #   Exit 0 means resolved and the sidecar is deleted; any other exit
-          #   leaves the file, the sidecar, and the lock untouched. prompt: names
-          #   your own ERB template, relative to the app root, replacing the
-          #   built-in one.
+          #   Exit 0 marks the sidecar resolved only when the command changed the
+          #   file; exit 0 with the file untouched, or any other exit, leaves the
+          #   file, the sidecar, and the lock untouched. prompt: names your own
+          #   ERB template, relative to the app root, replacing the built-in one.
           disabled:
             skills: []
             guidelines: []
@@ -53,6 +53,12 @@ module Rails
           # resolve:
           #   command: <your tool> $PROMPT
           #   prompt: .hyperdrive/resolve-prompt.md.erb
+          #
+          # For Claude Code:
+          #   command: claude -p $PROMPT --allowedTools Read,Edit,Write
+          # Grant the tools rather than --permission-mode acceptEdits, which
+          # refuses writes under .claude/ and cannot read $BASE; $PROMPT comes
+          # first because --allowedTools takes every following argument.
         YAML
 
         # No templates are rendered; source_root exists so Rails resolves the

data/lib/generators/hyperdrive/sync/USAGE

@@ -30,10 +30,12 @@ Description:
 
     --resolve does that step for you, git-mergetool style: after delivery it
     hands every unresolved <file>.new to the command in resolve.command in
-    .hyperdrive/config.yml and deletes the sidecar when that command exits 0.
-    On its own it delivers to sidecars; with --merge, git merges first and the
-    command takes the rest. With no command configured it stops before syncing
-    anything. A sidecar you edited yourself is never handed off.
+    .hyperdrive/config.yml and deletes the sidecar when that command exits 0
+    after changing the file; exit 0 with the file untouched, or any other exit,
+    leaves everything in place. On its own it delivers to sidecars; with
+    --merge, git merges first and the command takes the rest. With no command
+    configured it stops before syncing anything. A sidecar you edited yourself
+    is never handed off.
 
     Touches no bootstrap artifact: .mcp.json, the engine mount, the Gemfile
     plugin directive, .gitignore, and .hyperdrive/config.yml belong to

data/lib/generators/hyperdrive/sync_runner.rb

@@ -22,7 +22,8 @@ module Rails
               command: <your tool> $PROMPT
 
           Placeholders: $LOCAL $REMOTE $BASE $MERGED $SOURCE $PREVIOUS_SOURCE $KIND $PROMPT
-          (also exported as HYPERDRIVE_* environment variables). Exit 0 marks the sidecar resolved.
+          (also exported as HYPERDRIVE_* environment variables). Exit 0 marks the sidecar resolved
+          only when the command changed $MERGED.
         MSG
 
         def initialize(shell:, root: nil)

data/lib/rails/hyperdrive/resolve/prompt.md.erb

@@ -41,7 +41,7 @@ Rules:
 - Keep the YAML frontmatter valid, and leave the `name:` line exactly as REMOTE
   has it.
 <% end -%>
-- If you are not confident the result is correct, change nothing and exit with a
-  non-zero status.
+- If you are not confident the result is correct, leave MERGED untouched; an
+  unchanged MERGED is treated as unresolved.
 
-Exit 0 only when MERGED holds the reconciled file.
+The file counts as resolved only if MERGED changes.

data/lib/rails/hyperdrive/sidecar_resolver.rb

@@ -9,8 +9,9 @@ require "rails/hyperdrive/resolve_prompt"
 module Rails
   module Hyperdrive
     # Hands each unresolved <dest>.new sidecar to the user's resolver command,
-    # git-mergetool style, and deletes the sidecar when it exits 0. Nothing here
-    # writes the lock: the sidecar's absence is the whole resolution signal.
+    # git-mergetool style, and deletes the sidecar when it exits 0 and changed
+    # the file. Nothing here writes the lock: the sidecar's absence is the whole
+    # resolution signal.
     class SidecarResolver
       TOKENS = %w[LOCAL REMOTE BASE MERGED SOURCE PREVIOUS_SOURCE KIND PROMPT].freeze
       TOKEN_PATTERN = /\$(#{TOKENS.sort_by { |t| -t.length }.join("|")})\b/
@@ -105,11 +106,10 @@ module Rails
           values = values_for(candidate, base: base)
           argv = substitute(tokens, values, base: base)
           @shell.say_status :resolve, "#{candidate.dest} via #{argv.first}", :blue
+          before = merged_bytes(candidate)
           _out, err, status = Open3.capture3(env_for(values), *argv, chdir: @root)
           if status.success?
-            # Exit 0 is the tool's assertion that the file is resolved, so the
-            # sidecar goes even if the tool never wrote $MERGED.
-            resolved(candidate)
+            verify(candidate, before)
           else
             unresolved(candidate, "exit #{status.exitstatus}#{detail(err)}")
           end
@@ -118,6 +118,24 @@ module Rails
         unresolved(candidate, first_line(e.message))
       end
 
+      # An exit status is not proof: a tool can be denied every write and still
+      # exit 0, so the file itself has to show the resolution.
+      def verify(candidate, before)
+        after = merged_bytes(candidate)
+        if after.nil?
+          unresolved(candidate, "command exited 0 but $MERGED is missing")
+        elsif after == before
+          unresolved(candidate, "command exited 0 but wrote nothing")
+        else
+          resolved(candidate)
+        end
+      end
+
+      def merged_bytes(candidate)
+        path = abs(candidate.dest)
+        File.file?(path) ? File.binread(path) : nil
+      end
+
       def resolved(candidate)
         @shell.remove_file candidate.sidecar
         @outcome.resolved << candidate.dest

data/lib/rails/hyperdrive/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Hyperdrive
-    VERSION = "0.9.0"
+    VERSION = "0.9.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-hyperdrive
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Bakaface