Ajay Krishnan
9b0c4cd3cd
opencode-rails — production-grade Rails integration for OpenCode. Rails companion to opencode-ruby. ActiveRecord-aware session lifecycle (idempotent ensure!/recreate!/abort! with row-level locks), a Turn orchestrator driving the Reply state machine and recovering from session-not-found, an artifact pipeline backed by ActiveStorage, sandbox seeding, and tool-display value objects for Turbo Stream broadcasts. Drop into any Rails 7.1+ app that wants production-grade OpenCode streaming without rolling boilerplate. What this version ships: - Opencode::Session (AR-coupled lifecycle, row-level locks) - Opencode::Turn (Reply state machine, session-not-found recovery) - Opencode::Exchange (one turn = one request/response unit) - Opencode::Impostor (deterministic mock for tests) - Opencode::Sandbox / SandboxFile (per-session FS scratch space) - Opencode::Transform (host-rendered artifact pipeline) - Opencode::Artifact / MessageArtifacts (ActiveStorage-backed) - Opencode::UploadedFilesPrompt (system-prompt builder) - Opencode::ToolDisplay (Turbo Stream value objects) - Opencode::ErrorReporter (pluggable adapter — Honeybadger/Sentry/etc.) - examples/rails_integration.rb — canonical wiring blueprint 53 smoke tests. CI on Ruby 3.2/3.3/3.4. Ruby >= 3.2. Runtime deps: opencode-ruby = 0.0.1.alpha2, activerecord/activestorage/activesupport >= 7.1, < 9.0. See CHANGELOG.md for the alpha1 -> alpha2 delta.
74 lines
2.4 KiB
Markdown
74 lines
2.4 KiB
Markdown
# Contributing to opencode-rails
|
|
|
|
## Running the test suite
|
|
|
|
```bash
|
|
bundle install
|
|
bundle exec rake test
|
|
```
|
|
|
|
The smoke tests live in `test/opencode/`. They prove that:
|
|
|
|
- Every gem-provided constant resolves
|
|
- The opencode-ruby umbrella loads transitively
|
|
- Source locations point at the right gem
|
|
- The version constant is not under an `Opencode::Rails` module
|
|
(that would shadow `::Rails` in host apps; see comment in
|
|
`lib/opencode/rails_version.rb`)
|
|
- Public API contracts on the AR-coupled classes hold (Session, Turn,
|
|
MessageArtifacts) — verified via `Method#parameters`, not behavior
|
|
- Value objects (Artifact, SandboxFile, Transform, Impostor) round-trip
|
|
through their public interfaces
|
|
|
|
Behavioral tests for AR + ActiveStorage paths live in the host app
|
|
that produced this code. Same pattern as opencode-ruby — gem-side
|
|
smokes prove load correctness; host-side tests prove integration
|
|
correctness.
|
|
|
|
## Working on opencode-rails together with opencode-ruby
|
|
|
|
opencode-rails depends on opencode-ruby. During development of either
|
|
gem you frequently need changes in opencode-ruby to be picked up by
|
|
opencode-rails without going through a release cycle.
|
|
|
|
**Use Bundler's `local` config — not Gemfile conditionals.** Bundler
|
|
behavior must never depend on filesystem state inside the Gemfile.
|
|
|
|
```bash
|
|
# Once per dev machine. Replace the path with wherever you have
|
|
# opencode-ruby checked out.
|
|
bundle config local.opencode-ruby /path/to/opencode-ruby
|
|
|
|
# Then bundle install/update against the local copy:
|
|
bundle install
|
|
```
|
|
|
|
To switch back to the released version:
|
|
|
|
```bash
|
|
bundle config --delete local.opencode-ruby
|
|
bundle install
|
|
```
|
|
|
|
See [Bundler's documentation on local git overrides](https://bundler.io/v2.5/git.html#local).
|
|
|
|
## Releasing
|
|
|
|
This gem is in alpha. Versions ship as `0.0.x.alphaN` until the public
|
|
API stabilizes.
|
|
|
|
Coordinated releases with opencode-ruby:
|
|
|
|
1. In opencode-ruby: bump `Opencode::VERSION`, tag, push.
|
|
2. In opencode-rails: bump `Opencode::RAILS_VERSION`, update the
|
|
`add_runtime_dependency "opencode-ruby", "= X.Y.Z"` line in the
|
|
gemspec to match the new opencode-ruby version (alpha discipline:
|
|
pin exactly, not pessimistically). Tag, push.
|
|
3. In any consumer app: bump both `tag:` lines (or version pins) in
|
|
the Gemfile to the new versions; `bundle update opencode-ruby
|
|
opencode-rails`.
|
|
|
|
## Reporting issues
|
|
|
|
File at <https://github.com/ajaynomics/opencode-rails/issues>.
|