Upgrade checkout action to v7

docs: make alpha7 Rails quickstart executable

.github/workflows/release.yml

@@ -7,17 +7,18 @@ on:
 
 jobs:
   push:
+    if: ${{ github.server_url == 'https://github.com' }}
     runs-on: ubuntu-latest
     permissions:
       contents: write
       id-token: write
     environment: release
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
-      - uses: ruby/setup-ruby@v1
+      - uses: ruby/setup-ruby@003a5c4d8d6321bd302e38f6f0ec593f77f06600 # v1.319.0
         with:
-          ruby-version: ruby
+          ruby-version: "4.0"
           bundler-cache: true
-      - uses: rubygems/release-gem@v1
+      - uses: rubygems/release-gem@052cc82692552de3ef2b81fd670e41d13cba8092 # v1.4.0

.github/workflows/test.yml

@@ -12,12 +12,12 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ["3.2", "3.3", "3.4"]
+        ruby: ["3.2", "3.3", "3.4", "4.0"]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Ruby ${{ matrix.ruby }}
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@003a5c4d8d6321bd302e38f6f0ec593f77f06600 # v1.319.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true

README.md

@@ -19,8 +19,13 @@ Production-grade [OpenCode](https://opencode.ai) integration for Rails apps. Lay
 
 ```ruby
 # Gemfile
-gem "opencode-ruby"   # wire client + Reply state machine
+gem "opencode-ruby", "= 0.0.1.alpha7" # wire client + Reply state machine
-gem "opencode-rails"  # AR-coupled session/turn/artifact stack
+
+# v0.0.1.alpha7 is a GitHub source release, not a RubyGems release. Pin the
+# peeled release commit so a moved tag cannot change the code Bundler installs.
+gem "opencode-rails",
+  git: "https://github.com/ajaynomics/opencode-rails.git",
+  ref: "2a391ccad1d098e4bb51eb19b6ca52adaa79e5cb"
 ```
 
 ```bash
@@ -33,9 +38,12 @@ During the alpha series both gems are pinned in lockstep. Version 0.0.1.alpha7
 uses a subscribe-ready-before-prompt transport contract and reconnects an
 accepted turn without posting its prompt again.
 
-Releases use RubyGems trusted publishing. Register `release.yml` as the gem's
+`opencode-rails` 0.0.1.alpha7 is available as a GitHub source release but has
-trusted publisher (using the `release` environment); after that, a `v*` tag
+not been published to RubyGems. The `release.yml` workflow is prepared for
-publishes without a long-lived RubyGems API key.
+RubyGems trusted publishing, but the gem's trusted publisher still has to be
+registered for that workflow and its `release` environment. Until then, pushing
+a `v*` tag does not make the gem installable from RubyGems; use the exact Git
+commit above. Trusted publishing does not require a long-lived RubyGems API key.
 
 ## Quickstart
 
@@ -49,13 +57,29 @@ Opencode::ErrorReporter.adapter = ->(error, **opts) {
 }
 ```
 
+```ruby
+# app/services/noop_reply_observer.rb
+#
+# Turn requires an observer factory even when the app does not need live
+# partial rendering. For a streaming UI, replace this with an observer that
+# persists/broadcasts selected ReplyObserver callbacks (and throttle writes).
+class NoopReplyObserver
+  include Opencode::ReplyObserver
+
+  def watch(reply)
+    reply.add_observer(self)
+    self
+  end
+end
+```
+
 ```ruby
 # app/jobs/generate_response_job.rb
 class GenerateResponseJob < ApplicationJob
   def perform(assistant_message)
     conversation = assistant_message.conversation
     user_message = conversation.messages.where(role: :user).last
-    client       = Opencode::Client.new(base_url: ENV["OPENCODE_URL"])
+    client       = Opencode::Client.new(base_url: ENV.fetch("OPENCODE_URL"))
 
     session = Opencode::Session.new(
       conversation,
@@ -68,9 +92,15 @@ class GenerateResponseJob < ApplicationJob
       subject:        conversation,
       query_text:     user_message.content,
       client:         client,
-      session:        session,
+      session_for:    session,
+      observer_factory: ->(_message) { NoopReplyObserver.new },
+      system_context: ->(record) { "You are assisting with #{record.title}." },
+      agent_name:     ->(_record) { ENV.fetch("OPENCODE_AGENT", "build") },
+      tracer:         ->(name, **payload) {
+        ActiveSupport::Notifications.instrument("assistant.#{name}", payload)
+      },
       on_turn_finished: ->(result) {
-        # result.status   #=> :completed | :error | :cancelled
+        # result.status   #=> :completed | :cancelled | :error | :failed
         # result.message  #=> the AR row (reloaded)
         # result.duration_ms
       }
@@ -87,7 +117,16 @@ class GenerateResponseJob < ApplicationJob
 end
 ```
 
-The host's record (here `conversation`) must respond to `#title`, `#opencode_session_id`, `#opencode_session_id=`, `#with_lock(&block)`, `#update!`, `#reload`, `#id`. The host's message record (here `assistant_message`) must respond to `#error!(content)`, `#update_columns(...)`, `#with_lock(&block)`, `#reload`, `#pending?`.
+The host record (here `conversation`) must respond to `#title`,
+`#opencode_session_id`, `#opencode_session_id=`, `#with_lock(&block)`,
+`#update!`, `#reload`, and `#id`. The assistant message must respond to `#id`,
+`#reload`, `#cancelled?`, `#finalize!(**attrs)`, `#update!(**attrs)`, and
+`#error!(content)`. A non-no-op observer may impose additional record methods
+for its own live snapshots.
+
+`Opencode::Turn` is an internal, alpha-stage composition seam. Its keyword
+constructor is intentionally explicit and may change before 1.0, so keep this
+wiring in one host service/job and keep the gem source pinned exactly.
 
 ## What you get
 

test/readme_test.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "ripper"
+
+class ReadmeTest < Minitest::Test
+  README_PATH = File.expand_path("../README.md", __dir__)
+
+  def setup
+    @readme = File.read(README_PATH)
+    @quickstart = @readme[/^## Quickstart\n(?<body>.*?)(?=^## )/m, :body]
+    refute_nil @quickstart, "README must retain a Quickstart section"
+  end
+
+  def test_quickstart_turn_call_documents_every_required_keyword
+    turn_call = @quickstart[/Opencode::Turn\.new\((?<args>.*?)^\s*\)\.call/m, :args]
+    refute_nil turn_call, "Quickstart must contain an Opencode::Turn.new(...).call example"
+
+    documented = turn_call.scan(/^\s*([a-z_]+):/).flatten.map(&:to_sym)
+    parameters = Opencode::Turn.instance_method(:initialize).parameters
+    required = parameters.filter_map { |kind, name| name if kind == :keyreq }
+    accepted = parameters.filter_map { |kind, name| name if %i[keyreq key].include?(kind) }
+
+    assert_empty required - documented,
+      "Quickstart is missing required Turn keywords: #{(required - documented).join(", ")}"
+    assert_empty documented - accepted,
+      "Quickstart uses unsupported Turn keywords: #{(documented - accepted).join(", ")}"
+    refute_includes documented, :session
+  end
+
+  def test_readme_ruby_fences_parse
+    ruby_fences = @readme.scan(/```ruby\n(.*?)```/m).flatten
+    refute_empty ruby_fences
+
+    ruby_fences.each_with_index do |source, index|
+      assert Ripper.sexp(source), "README Ruby fence #{index + 1} has invalid syntax"
+    end
+  end
+end

test/release_workflow_test.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "yaml"
+
+class ReleaseWorkflowTest < Minitest::Test
+  ROOT = File.expand_path("..", __dir__)
+  WORKFLOW_PATH = File.join(ROOT, ".github", "workflows", "release.yml")
+  SETUP_RUBY_ACTION = "ruby/setup-ruby@003a5c4d8d6321bd302e38f6f0ec593f77f06600"
+  RELEASE_GEM_ACTION = "rubygems/release-gem@052cc82692552de3ef2b81fd670e41d13cba8092"
+
+  def workflow
+    @workflow ||= YAML.safe_load(File.read(WORKFLOW_PATH), aliases: false)
+  end
+
+  def push_job
+    workflow.fetch("jobs").fetch("push")
+  end
+
+  def test_release_job_is_inert_on_non_github_runners
+    assert_equal "${{ github.server_url == 'https://github.com' }}", push_job.fetch("if")
+  end
+
+  def test_release_job_keeps_the_trusted_publisher_boundary
+    assert_equal "release", push_job.fetch("environment")
+    assert_equal(
+      { "contents" => "write", "id-token" => "write" },
+      push_job.fetch("permissions")
+    )
+
+    steps = push_job.fetch("steps")
+    setup_ruby = steps.find { |step| step["uses"] == SETUP_RUBY_ACTION }
+
+    assert_equal "4.0", setup_ruby.dig("with", "ruby-version")
+    assert_equal 1, steps.count { |step| step["uses"] == RELEASE_GEM_ACTION }
+    refute steps.any? { |step| step.fetch("run", "").match?(/\bgem\s+push\b/) }
+  end
+end

test/workflow_contract_test.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "yaml"
+
+class WorkflowContractTest < Minitest::Test
+  ROOT = File.expand_path("..", __dir__)
+  WORKFLOW_DIRECTORY = File.join(ROOT, ".github", "workflows")
+  TEST_WORKFLOW_PATH = File.join(WORKFLOW_DIRECTORY, "test.yml")
+  ACTION_PINS = {
+    "actions/checkout" => "9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0",
+    "ruby/setup-ruby" => "003a5c4d8d6321bd302e38f6f0ec593f77f06600",
+    "rubygems/release-gem" => "052cc82692552de3ef2b81fd670e41d13cba8092"
+  }.freeze
+
+  def test_matrix_covers_every_supported_ruby
+    workflow = YAML.safe_load(File.read(TEST_WORKFLOW_PATH), aliases: false)
+    versions = workflow.dig("jobs", "test", "strategy", "matrix", "ruby")
+
+    assert_equal %w[3.2 3.3 3.4 4.0], versions
+  end
+
+  def test_every_third_party_action_uses_its_reviewed_commit
+    action_uses = Dir[File.join(WORKFLOW_DIRECTORY, "*.{yml,yaml}")].sort.flat_map do |path|
+      workflow = YAML.safe_load(File.read(path), aliases: false)
+
+      workflow_uses(workflow)
+    end
+
+    assert_equal 5, action_uses.length
+    action_uses.each do |action_use|
+      action, separator, revision = action_use.rpartition("@")
+
+      assert_equal "@", separator
+      assert_equal ACTION_PINS.fetch(action), revision
+      assert_match(/\A[0-9a-f]{40}\z/, revision)
+    end
+  end
+
+  def test_action_discovery_only_reads_workflow_action_locations
+    workflow = YAML.safe_load(<<~YAML, aliases: false)
+      jobs:
+        reusable:
+          uses: "owner/workflow@revision"
+          with:
+            uses: ordinary-job-input
+        test:
+          steps:
+            - uses: "owner/action@revision"
+              with:
+                uses: ordinary-step-input
+    YAML
+
+    assert_equal %w[owner/workflow@revision owner/action@revision], workflow_uses(workflow)
+  end
+
+  private
+
+  def workflow_uses(node)
+    node.fetch("jobs").values.flat_map do |job|
+      action_uses = job.key?("uses") ? [job.fetch("uses")] : []
+      step_uses = job.fetch("steps", []).filter_map { |step| step["uses"] }
+
+      action_uses.concat(step_uses)
+    end
+  end
+end