opencode-ruby-upgrader 0.1.4 → 0.1.6

package/README.md

@@ -1,6 +1,55 @@
 # opencode-ruby-upgrader
 
-An evidence-driven Ruby and Rails migration agent for [OpenCode](https://opencode.ai). It upgrades a project one Ruby minor series at a time toward a researched latest-stable or explicitly pinned Ruby target, researches compatibility guidance, updates affected code and dependencies, and leaves a reviewable migration trail.
+An evidence-driven Ruby and Rails migration agent for [OpenCode](https://opencode.ai). It upgrades a project one Ruby minor series at a time toward a researched latest-stable or explicitly pinned Ruby target, researches compatibility guidance, updates affected code and dependencies, and leaves a reviewable migration trail. It ships as an OpenCode plugin: register it in your OpenCode config, then drive it with `/ruby-upgrade`.
+
+## Install
+
+### 1. Install OpenCode
+
+This package is a plugin for [OpenCode](https://opencode.ai), an open-source AI coding agent that runs in your terminal. If you don't have it yet:
+
+```bash
+curl -fsSL https://opencode.ai/install | bash
+# or: npm install -g opencode-ai
+# or: brew install anomalyco/tap/opencode
+```
+
+You'll also need an API key for at least one LLM provider — run `/connect` inside OpenCode to sign in or paste a key. The [OpenCode intro](https://opencode.ai/docs/) covers the full first-run setup.
+
+### 2. Register the plugin
+
+Add it to your OpenCode config, either the project config `opencode.json` (or `opencode.jsonc`) beside your project, or the global `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-ruby-upgrader"]
+}
+```
+
+Register it **per project** if you want the agent available only where you're upgrading; register it globally to use it across repositories. A project-scoped config is the tighter default here, because the upgrader additionally refuses to run outside a linked Git worktree you created yourself (see [Safety model](#safety-model)).
+
+While developing a local checkout, point at the directory instead:
+
+```json
+{ "plugin": ["file:///absolute/path/to/opencode-ruby-upgrader"] }
+```
+
+OpenCode installs npm plugins automatically at startup and caches them in `~/.cache/opencode/node_modules/`, so there is no separate install step.
+
+### 3. Restart and confirm
+
+Restart OpenCode, then run `opencode` in the worktree you want to upgrade and type `/ruby-upgrade` — or `@ruby-upgrade` to select the agent directly.
+
+## Requirements
+
+OpenCode with plugin support, Node `>=22.5.0`, and Git `>=2.5` for the linked-worktree safety model. Docker is optional and only needed when your host cannot run the Ruby version being tested (see [Security boundaries](#security-boundaries)).
+
+The automatic validation adapters currently recognize Bundler projects using Rails, RSpec, or Minitest. Other stacks still receive a full inventory and research, but need a user-supplied validation command.
+
+The package also installs an `opencode-ruby-upgrader` command. Most of its subcommands are driven by the agent itself; the two you run directly are `dashboard` and `resume`.
+
+npm `>=11` is recommended for contributors and for publishing: npm 11 added the install-script approval gate this repository's release path relies on. It is not required to install or run the package, which ships no install scripts and no runtime dependencies.
 
 ## Quick start
 
@@ -22,8 +71,6 @@ opencode
 
 Then run `/ruby-upgrade` (or add `--dry-run` to get a no-write assessment first). The agent inventories the project, researches an official-source compatibility ladder, and proposes each validated hop as a local checkpoint commit for your review. See [Safety model](#safety-model) for what it will and will not do automatically.
 
-> Requires Git 2.5+ (linked-worktree safety model) and Docker for the isolated validation container when your host cannot run the Ruby version being tested (see [Security boundaries](#security-boundaries)).
-
 | Step | Who does it | Result |
 |---|---|---|
 | Set up worktree + config | You | Linked worktree, agent-ready |
@@ -33,18 +80,30 @@ Then run `/ruby-upgrade` (or add `--dry-run` to get a no-write assessment first)
 | Repeat | Loop | One minor series per hop |
 | Review & push | **You** | `git log`/dashboard then push the validated branch |
 
-## Proof of work
+## Before you run it
+
+Three flags bound how much a single run can change.
+
+Use `/ruby-upgrade --dry-run` for a no-write inventory and proposed migration assessment; it creates no report, lock, checkpoint, or durable research evidence. Use `/ruby-upgrade --target <version>` (for example `/ruby-upgrade --target 3.4`) to pin an explicit final Ruby version, or `/ruby-upgrade --stop-after-hop` to validate and commit one hop before stopping.
+
+## Validated end-to-end run
 
 The agent has completed a real end-to-end migration against a public fixture: [`ruby2-rails4-bootstrap-heroku`](https://github.com/lilla021/ruby2-rails4-bootstrap-heroku) (BSD-2-Clause) moved from **Ruby 2.4.10 / Rails 4.2.11.3** to **Ruby 3.4.10 / Rails 7.1.6** across 15 receipt-backed hops. Every hop was validated by `bundle exec rspec` in an isolated Docker container, then committed as a local checkpoint before the next hop began.
 
 - [Upgrade pull request](https://github.com/lilla021/ruby2-rails4-bootstrap-heroku/pull/1) — the full migration: 19 commits, one per reviewed step, with lint and spec checks currently passing on GitHub Actions.
-- [Evidence ledger](E2E_EVIDENCE.md) — every hop's validation receipt, commit SHA, and the fixes the migration required.
+- [Evidence ledger](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.6/E2E_EVIDENCE.md) — every hop's validation receipt, commit SHA, and the fixes the migration required.
 
-This proves the workflow works on a genuinely old, real-world Rails stack. It does not claim every upgrade is safe — see [Product limits](#product-limits).
+This proves the workflow works on a genuinely old, real-world Rails stack. It does not claim every upgrade is safe — see [Safety model](#safety-model) for what the agent refuses to do without you, and [Product limits](#product-limits) for what it cannot prove.
 
 ## Safety model
 
-The agent runs durable migrations **only** from a linked Git worktree created by the user. Before starting, explicitly configure the repository default branch with `git config opencode-ruby-upgrader.defaultBranch main` (replace `main` as needed) — see [Quick start](#quick-start) for the three setup commands, which the agent also shows verbatim if you invoke it from a primary checkout. The upgrader fails closed if this configuration is absent and never guesses `main`, `master`, or a remote default. This keeps your normal checkout free for other work. Non-Git projects support dry-run inventory only. The agent never creates, switches, deletes, merges, pushes, or reconfigures branches/remotes. It also never publishes, deploys, or runs destructive database commands.
+The agent runs durable migrations **only** from a linked Git worktree created by the user. Before starting, explicitly configure the repository default branch with `git config opencode-ruby-upgrader.defaultBranch main` (replace `main` as needed) — see [Quick start](#quick-start) for the three setup commands, which the agent also shows verbatim if you invoke it from a primary checkout. The upgrader fails closed if this configuration is absent and never guesses `main`, `master`, or a remote default. This keeps your normal checkout free for other work. Non-Git projects support dry-run inventory only.
+
+The agent never:
+
+- creates, switches, deletes, merges, pushes, or reconfigures branches or remotes
+- publishes or deploys anything
+- runs destructive database commands
 
 After every routine Ruby minor-version hop with passing validation, the agent proposes a **local** checkpoint commit through a guarded commit gate and OpenCode asks for confirmation. The gate verifies the linked worktree and non-default branch, exact expected Git history, an empty initial staging area, a complete passing report iteration, and scans staged content for likely credentials. It cannot push, fetch, alter remotes, switch branches, merge, rebase, reset, or amend history. You can review and push any validated checkpoint; a run becomes `complete` only once it reaches its pinned target.
 
@@ -52,23 +111,17 @@ The agent pauses—not guesses—when a migration involves data changes, authent
 
 Every hop declares its expected changed files before commit. The commit gate blocks undeclared changes, credential-like material, executable Git hooks, non-RubyGems dependency sources, and large lockfile churn unless the user has explicitly reviewed and permitted that specific concern. Any changed lockfile also requires a recorded compatibility and license review. The target Ruby version is pinned with the research timestamp at run start, so a new upstream release cannot silently change the target mid-run. If Git author or commit-signing configuration prevents a commit, the agent reports the exact local setup issue and stops; it never changes Git configuration for you.
 
-## Install
-
-During development:
+## Security boundaries
 
-```json
-{ "plugin": ["file:///absolute/path/to/opencode-ruby-upgrader"] }
-```
+The agent defaults unknown shell commands to an OpenCode confirmation prompt. Git inspection is allowed, while direct Git mutation, GitHub CLI, publishing, and shell chaining/pipes/substitutions are denied. Dependency installation/updates, recognized tests, state writes, `commit-hop`, and `commit-rails-hop` require confirmation. This protects against accidental agent actions, not malicious project code: dependency installation and tests execute project-controlled code with your local user permissions. Use an isolated environment for repositories you do not trust, and review any command OpenCode asks you to approve.
 
-After publishing:
+New reports require `record-executed-iteration --validation <id>` or `record-executed-rails-iteration --validation <test-id>`; asserted results cannot be recorded or committed. The accepted IDs map to fixed no-shell commands: `bundle-rspec`, `bundle-rails-test`, `bundle-rake-test`, `bin-rails-test`, and, for Rails bridges, `rails-app-update`. When the target Ruby is unavailable on your host, the agent runs `prepare-target-runtime --ruby <x.y.z>` after selecting the exact target patch release. One confirmation provisions labeled per-run Ruby and isolated PostgreSQL Docker resources, installs Node, installs Bundler 2.4.22, runs `bundle install`, and, for Rails, creates the isolated test database.
 
-```json
-{ "plugin": ["opencode-ruby-upgrader"] }
-```
+It writes nonsecret `.ruby-upgrades/runtime.json` with only safe preparation digests and the resolved image ID; raw output and `DATABASE_URL` are never persisted. `docker-bundle-rspec` reuses and verifies that manifest, including the exact requested Ruby execution and resolved image ID, before executing the fixed `docker exec --env DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL=true <container> bundle exec rspec`. The safeguard override is scoped to the verified isolated test process; no container name, report path, or environment value is needed from the user.
 
-Restart OpenCode, then run `/ruby-upgrade` or select `@ruby-upgrade`.
+Receipts persist only an output digest and byte count, plus structured test metrics; raw validation output is deliberately not committed. Each receipt also binds to a non-evidence working-tree fingerprint, which the commit gate rechecks after final validation. A checkpoint commit carries the receipt digest.
 
-Git 2.5 or newer is required for the linked-worktree safety model.
+This is tamper-evident provenance for a committed report, not protection against the same local user rewriting both evidence and Git history.
 
 ## Evidence and dashboard
 
@@ -76,7 +129,11 @@ Every run has a generated JSON record and Markdown companion under `.ruby-upgrad
 
 As an example, here is one such run rendered in the dashboard — per-hop summaries, test metrics, and citation links. The full process and per-hop detail live in the run reports themselves:
 
-![Example of the local evidence dashboard](docs/dashboard.png)
+![Example of the local evidence dashboard](https://raw.githubusercontent.com/lilla021/opencode-ruby-upgrader/v0.1.6/docs/dashboard.png)
+
+The same reports open as a vault — each run is a Markdown note paired with its JSON record:
+
+![Example vault view: run reports as paired Markdown and JSON notes](https://raw.githubusercontent.com/lilla021/opencode-ruby-upgrader/v0.1.6/docs/vault.png)
 
 Launch the local-only dashboard from the repository worktree:
 
@@ -88,9 +145,7 @@ It binds exclusively to `127.0.0.1` on an ephemeral port and remains in the fore
 
 The dashboard identifies local checkpoint commits from trailers embedded in those commits. Before the final push, inspect them locally with `git log`, `git show`, and the dashboard; after you push, the same individual commits are available for GitHub review.
 
-## Controls and recovery
-
-Use `/ruby-upgrade --dry-run` for a no-write inventory and proposed migration assessment; it creates no report, lock, checkpoint, or durable research evidence. Use `/ruby-upgrade --target <version>` (for example `/ruby-upgrade --target 3.4`) to pin an explicit final Ruby version, or `/ruby-upgrade --stop-after-hop` to validate and commit one hop before stopping.
+## Recovery
 
 Each active run holds a local lock. To stop for review or manual work, transition it to `paused`; that releases the lock without marking the migration complete. Resume the existing report rather than starting a second migration:
 
@@ -98,26 +153,53 @@ Each active run holds a local lock. To stop for review or manual work, transitio
 opencode-ruby-upgrader resume --report .ruby-upgrades/runs/<run>.json
 ```
 
-`complete`, `blocked`, and `paused` runs release their lock. For other blockers, inspect the report and use the documented transition/resume path. To undo a completed hop, use the reviewable local history: `git revert <hop-sha>`. Do not use reset, rebase, or force-push as routine migration recovery.
+`complete`, `blocked`, and `paused` runs release their lock. For other blockers, inspect the report and use the documented transition/resume path.
 
-If a resolved Rails version blocks the next Ruby hop, record the user-approved bridge, then transition the Ruby run to `blocked`. That Ruby report is terminal: complete the linked Rails lifecycle and start a fresh Ruby run. Every Rails iteration executes `bin/rails app:update` first, records its receipt, reviews that exact working-tree fingerprint, and only then runs final tests. Validate and checkpoint each one with `commit-rails-hop`.
+If a resolved Rails version blocks the next Ruby hop, that Ruby run becomes terminal and a separate Rails-bridge run takes over. See the [Rails bridge lifecycle](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.6/docs/rails-bridge.md) reference.
 
-## Security boundaries
+To undo a completed hop, use the reviewable local history: `git revert <hop-sha>`. Do not use reset, rebase, or force-push as routine migration recovery.
 
-The agent defaults unknown shell commands to an OpenCode confirmation prompt. Git inspection is allowed, while direct Git mutation, GitHub CLI, publishing, and shell chaining/pipes/substitutions are denied. Dependency installation/updates, recognized tests, state writes, `commit-hop`, and `commit-rails-hop` require confirmation. This protects against accidental agent actions, not malicious project code: dependency installation and tests execute project-controlled code with your local user permissions. Use an isolated environment for repositories you do not trust, and review any command OpenCode asks you to approve.
+## Troubleshooting
 
-New reports require `record-executed-iteration --validation <id>` or `record-executed-rails-iteration --validation <test-id>`; asserted results cannot be recorded or committed. The accepted IDs map to fixed no-shell commands: `bundle-rspec`, `bundle-rails-test`, `bundle-rake-test`, `bin-rails-test`, and, for Rails bridges, `rails-app-update`. When the target Ruby is unavailable on your host, the agent runs `prepare-target-runtime --ruby <x.y.z>` after selecting the exact target patch release. One confirmation provisions labeled per-run Ruby and isolated PostgreSQL Docker resources, installs Node, installs Bundler 2.4.22, runs `bundle install`, and, for Rails, creates the isolated test database.
+### If `/ruby-upgrade` isn't offered
+
+The plugin didn't load. Check that your config file still parses — a stray comma breaks the whole file, not just this plugin — and restart OpenCode.
+
+### If you see `EBADENGINE`
+
+`EBADENGINE` is a warning, not a failure: npm still completes the install. It appears when your Node is older than the `>=22.5.0` floor in [Requirements](#requirements), which exists because Node 18 is end-of-life and this agent runs your project's dependency install and test commands.
+
+To clear it, upgrade Node and reinstall:
+
+```bash
+node -v              # confirm >= 22.5.0
+npm i opencode-ruby-upgrader
+```
+
+Upgrading npm alone cannot fix it. Current npm releases require a recent Node themselves, so npm refuses to install over an older Node. If `engine-strict=true` is set in your npm config, the warning becomes a hard error and the install fails until Node is upgraded.
 
-It writes nonsecret `.ruby-upgrades/runtime.json` with only safe preparation digests and the resolved image ID; raw output and `DATABASE_URL` are never persisted. `docker-bundle-rspec` reuses and verifies that manifest, including the exact requested Ruby execution and resolved image ID, before executing the fixed `docker exec --env DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL=true <container> bundle exec rspec`. The safeguard override is scoped to the verified isolated test process; no container name, report path, or environment value is needed from the user. Receipts persist only an output digest and byte count, plus structured test metrics; raw validation output is deliberately not committed. Each receipt also binds to a non-evidence working-tree fingerprint, which the commit gate rechecks after final validation. A checkpoint commit carries the receipt digest. This is tamper-evident provenance for a committed report, not protection against the same local user rewriting both evidence and Git history.
+### Uninstalling
+
+Remove `"opencode-ruby-upgrader"` from your config's `plugin` array and restart OpenCode. Your `.ruby-upgrades/` reports and any checkpoint commits are ordinary local files and Git history — nothing else to clean up.
 
 ## Product limits
 
-The upgrader automates evidence collection and compatibility-oriented edits; it cannot prove production behavior, security correctness, deployment safety, or semantic equivalence. It intentionally pauses instead of modifying database behavior, authorization, payments, secrets, and production configuration without a user decision. Supported automatic adapters currently recognize Bundler projects using Rails, RSpec, or Minitest; other stacks receive an inventory and require a user-supplied validation command.
+The upgrader automates evidence collection and compatibility-oriented edits; it cannot prove production behavior, security correctness, deployment safety, or semantic equivalence. It intentionally pauses instead of modifying database behavior, authorization, payments, secrets, and production configuration without a user decision.
 
 The credential scanner is heuristic: it recognizes common token formats and quoted credential-like assignments, but may miss other forms such as arbitrary unquoted YAML values. Run reports are local mutable JSON evidence, so their integrity is bounded by the user and local filesystem permissions rather than a tamper-proof store. Credential-bearing source URLs are redacted from supply-chain evidence. Gemfile source detection is static and may not resolve dynamically computed sources; review those manually and explicitly approve private sources.
 
+## Privacy
+
+No telemetry, no analytics, and no report uploads. Migration evidence is written only under `.ruby-upgrades/runs/` in the current worktree, and the dashboard binds to `127.0.0.1` only. Reports may contain target versions, branch names, commit SHAs, changed-file names, dependency source origins, citations, and bounded validation metadata — absolute local paths and recognized credentials are redacted, but redaction is best-effort.
+
+Full detail in [PRIVACY.md](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.6/PRIVACY.md). To report a vulnerability, see [SECURITY.md](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.6/SECURITY.md).
+
+## Contributing
+
 Run the self-contained test suite with `npm test`. A CI environment that installs a supported OpenCode CLI can also run `OPENCODE_RUNTIME_E2E=1 npm run test:opencode`; this verifies the installed runtime is available and the plugin registers its agent/command contract before release.
 
+CI runs that suite against Node 22, 24, and 26 so the declared `engines.node` range is exercised rather than assumed. Both workflows pin `npm@11.16.0` so the matrix varies Node rather than npm, because `allowScripts` — npm 11's dependency install-script approval gate, used here to narrowly permit the pinned `opencode-ai` postinstall — and npm trusted publishing both require npm 11 or newer. `RELEASING.md` covers the publish path.
+
 ## Acknowledgments
 
 This agent was built with [opencode-craft](https://github.com/pauloralves/opencode-craft) (MIT, by [Paulo Alves](https://github.com/pauloralves)) — a senior pair-programming, craftsmanship, and knowledge-ledger skill pack for OpenCode. Its review cadence, evidence discipline, and interview-oriented trade-off notes shaped how this project is designed and presented. Thanks also to the community that produces the [official Ruby release](https://www.ruby-lang.org/en/downloads/releases/) and [Rails](https://guides.rubyonrails.org/) documentation this agent cites.

package/RELEASE_CHECKLIST.md

@@ -5,6 +5,7 @@ Complete every item before pushing a `v*` tag. The protected `npm-release` envir
 ## Before every release
 
 - [ ] Bump the version and update [RELEASE_NOTES.md](RELEASE_NOTES.md): scope, supported adapters, known limitations, rollback.
+- [ ] Repoint the README's tag-pinned links to the new version tag: `E2E_EVIDENCE.md`, `PRIVACY.md`, `SECURITY.md`, `docs/rails-bridge.md`, and both screenshot URLs. They are pinned to a tag so the registry page always shows the docs of the installed version rather than whatever `main` currently says; leaving them on the previous tag makes the published page drift behind the release.
 - [ ] Review the package metadata (name, description, keywords, `repository`, `bugs`, `homepage`) and the packed-file list with `npm pack --dry-run`.
 - [ ] Run `npm test`; confirm the release workflow's runtime smoke gate passes with the pinned OpenCode runtime.
 - [ ] Confirm no credentials, personal data, or local paths appear in the packed files, README, SECURITY.md, PRIVACY.md, or release notes.

package/RELEASE_NOTES.md

@@ -1,5 +1,44 @@
 # opencode-ruby-upgrader — release notes
 
+## v0.1.6 — reader path and CI coverage
+
+No runtime change. The agent's commands, permission policy, commit gate, and report format are untouched. This release restructures the public documentation and closes a CI coverage gap.
+
+**Scope**
+
+The README was reordered into a reader-state funnel — install, run it small, does it work, what it refuses, what backs that, what you get, how to recover, what it cannot prove — so each section answers the question a reader has at that point:
+
+- `Install` is now first and reads as three numbered steps. It previously arrived fifth, with nothing earlier stating that this package is an OpenCode plugin.
+- `Security boundaries` now sits directly after `Safety model`. Intent and enforcement are halves of one argument and had been separated by two unrelated sections.
+- The pre-flight flags split out of the recovery material into `Before you run it`, immediately after Quick start where `--dry-run` is first mentioned.
+- A new `Requirements` section carries the Node/Git/Docker floors and moves the supported-adapter qualification from position ten to before a reader creates a worktree.
+- A new `Troubleshooting` section collects the `EBADENGINE` warning, a missing `/ruby-upgrade` command, and uninstall.
+- A new `Privacy` section gives the previously unlinked `PRIVACY.md` and `SECURITY.md` an entry point in the packaged README.
+- `Contributing` is separated from `Product limits`, so maintainer test instructions no longer sit inside an end-user section.
+- Install now covers the OpenCode prerequisite and config registration for readers new to OpenCode, verified against the current plugin documentation.
+- `Proof of work` is renamed `Validated end-to-end run`.
+- Long paragraphs in `Safety model` and `Security boundaries` are split, and the agent's prohibitions are now a list.
+- The Rails-bridge lifecycle moves to a standalone [`docs/rails-bridge.md`](docs/rails-bridge.md) reference, so `Recovery` ends on the `git revert` guidance instead of burying it.
+- README links to companion documents and both screenshots are now pinned to the release tag instead of resolving against `main`. The registry page previously showed whatever `main` happened to contain, which could drift ahead of the installed version. The release gate now repoints them each release.
+
+**CI**
+
+`ci.yml` runs the test suite, pack check, and pinned-runtime smoke test across Node 22, 24, and 26. CI previously exercised Node 22 only while `engines.node` declared `>=22.5.0`, leaving most of the advertised support range untested. Both workflows pin `npm@11.16.0` so the matrix varies Node rather than npm. Publishing remains a single Node 22 job in `release.yml`, since every matrix leg would attempt the same version.
+
+**Supported adapters:** unchanged — Bundler projects using Rails, RSpec, or Minitest; other stacks receive an inventory and require a user-supplied validation command.
+
+**Known limitations:** unchanged. The credential scanner remains heuristic and reports remain local mutable JSON, bounded by the user and local filesystem permissions. See Product limits in the README.
+
+**Rollback:** `npm install opencode-ruby-upgrader@0.1.5`. The command surface and on-disk format are identical across this release, so no report conversion is required.
+
+Published through the same protected-CI gate.
+
+## v0.1.5 — registry visuals
+
+No functional change. The npm package page now renders its README images: the dashboard and vault-view screenshots moved from relative paths to absolute GitHub URLs, so they display on the registry in addition to GitHub.
+
+Published through the same protected-CI gate.
+
 ## v0.1.4 — showcase polish
 
 No functional change. Attribution and presentation updates:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-ruby-upgrader",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A safe, evidence-driven Ruby runtime upgrade agent and local migration dashboard for OpenCode",
   "author": "Priscilla Cournoyer (https://github.com/lilla021)",
   "repository": {