openui-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5365a84ab993b7d1d7efd392753a9699f28cbe17acd8482d517e0e529150a6c
+  data.tar.gz: d071e4fbd4f29fefd7a074f411b30cdd0b453bc5532410bbcb7af3333184f340
+SHA512:
+  metadata.gz: cd3efcb1e979ac3c63892e83a68fcd1b62db7d44297763e2fdc451251220c823efa2f27afc25d340902e5f56e0c8b7c53afd952df115eda9e78c95a143b8bb0f
+  data.tar.gz: e8a972cb1ef2663d0247263984d06e82e24cfcf1e4e972788c3dc917a111c5ea88e8cd782191f7baf19d2804660ed93bd6c8241a58074010f112b22686ce6a55

data/AUDIT.md

@@ -0,0 +1,102 @@
+# Pre-publication audit: 2026-10-18
+
+## Outcome
+
+The audit found real defects despite the original green test suite. The fixes
+below have regression coverage. The owner authorized publication of `0.1.0`
+on 2026-10-18. Publication still requires the selected tag's complete CI to
+pass and the protected publishing workflow to succeed. This audit establishes
+the specific behaviors below, not the absence of all bugs.
+
+## Confirmed defects corrected
+
+| Area | Defect | Correction and evidence |
+| --- | --- | --- |
+| Identity isolation | A client idempotency key could replay another actor's result or a different action's result. | Actor/tenant-scoped keys; request digest binds action, surface, revision, args, and confirmation. Cross-actor/action/surface/tenant regression tests. |
+| Canonical input | Symbol-keyed and nested arguments had incorrect digests; mutable input could change after validation. | Deep canonical JSON copies and immutable data. Mutation and nested-digest tests. |
+| Claim state | A completed `nil` looked pending; an expired writer could overwrite a newer claim. | Explicit pending/replay states and per-claim tokens. Nil/false, expiry, and concurrent-claim tests. |
+| Host authentication | Engine controllers bypassed the host ApplicationController; documented default actor resolution was absent. | Host controller inheritance, explicit CSRF protection, current-user fallback, and tenant-swap tests. |
+| Action responses | Authentication redirects, malformed JSON, or unrelated result objects could appear successful. | Reject redirects and non-JSON/malformed/mismatched responses; browser regression tests. |
+| Stream ordering | Completion skipped missing deltas; stale snapshots rewound state; a gap did not pause later deltas. | Sequence gates for terminal frames and snapshots; Ruby/browser regressions. |
+| Terminal writers | Duplicate finishes and writes after errors emitted more frames. | One terminal state. Consumer/transport failures propagate instead of being relabelled provider failures. |
+| Browser lifecycle | Pre-load frames could render without a runtime; reconnect/cache restoration lost source or sequence state. | Deferred rendering, connection tokens, state preservation, real Turbo visit/back tests. |
+| OpenUI actions | The stub used `{action,args}`, but the real runtime emits `{type,params}`. | Official event normalization, verified with a real component and keyboard activation. |
+| Browser tools | The proxy looked like an MCP client and returned the endpoint wrapper instead of the handler value. | Reserved-property handling, stable provider identity, raw tool values. Real Query and Mutation tests. |
+| Renderer errors | The official renderer calls `onError([])` after successful parsing. | Empty error arrays are ignored; actual error arrays become structured renderer errors. |
+| Library identity | A fingerprint existed, but the runtime library was not checked. | Server rejects persisted mismatches; browser hashes `toSpec()` before mounting. Real-bundle and negative tests. |
+| Runtime supply | Fetch chose the largest JS file, ran without checksum verification, and CSS was not integrated. | Exact file allowlist, committed archive/file hashes, npm scripts disabled, no archive path extraction, stylesheet helper. Real fetch and SRI-backed browser tests. |
+| RubyLLM | `Chat#complete(question)` does not exist in RubyLLM 2.1.1. | Add the user message, then call block-only complete; verify both strategies through real provider SSE parsing with mocked HTTP. |
+| Message framing | CRLF, malformed markers, post-end text, and multi-line raw context differed from lang-core. | Align framing with pinned lang-core 1.0.1 and extend regression cases. No Ruby DSL parser added. |
+| Packaging | Standalone require needed Rails preloaded; previous smoke checks only installed the gem. | Explicit framework loading; a fresh host uses the extracted built artifact, generator, eager load, and an HTTP render. |
+| Configuration readiness | A configured filename could pass validation without an actual valid manifest or prompt file. | Explicit readiness validation reads the files and clears stale derived state. Missing-file regression tests. |
+| Release workflow | A tag could publish without running tests; the supposed draft was public; environment protection was only a comment. | Reusable full CI gate, explicit manual publish, artifact handoff, real draft flag, and documented reviewer setup. |
+
+## Verification evidence
+
+Local environment: Ruby 3.3.5, Rails 8.1.4, Chrome through Selenium.
+
+- Unit/integration: `209 runs, 542 assertions`, no failures or errors.
+- Deterministic browser suite: `32 runs, 104 assertions`, no failures or errors.
+- Real `@openuidev/browser-bundle` 0.2.1: `5 runs, 30 assertions`, no failures or errors.
+  Includes matching runtime/spec identity, rendering, keyboard action, Query,
+  click-triggered Mutation, and unknown-component rejection.
+- Real Turbo Streams broadcast over Action Cable, plus Turbo visit/back restoration.
+- RubyLLM 2.1.1 with real OpenAI chat-completions SSE parsing and mocked HTTP:
+  `1 run, 7 assertions`, no failures or errors. The deterministic test made no
+  paid provider calls.
+- Live-provider smoke (2026-10-18): one synthetic prompt streamed through the
+  gem adapter with RubyLLM 2.1.1, OpenRouter, `openai/gpt-4.1-mini`, and the
+  `:complete` strategy. A 16-token output cap was set. The first sandboxed
+  attempt returned `stream_failed` with no delta; the network-enabled retry
+  emitted one 2-byte delta and a completed frame. The account's usage ledger
+  and exact charge were not checked. Evidence is limited to this OpenRouter
+  path/model; direct OpenAI and other provider/model paths remain unverified.
+- Checksum-locked npm runtime fetch, including CSS and upstream license: passed.
+- Built artifact in a fresh generated Rails host: generator, eager load, and HTTP render passed.
+- RuboCop: clean. JS syntax checks: passed.
+- GitHub workflows: actionlint 1.7.12 passed. External actions are pinned to
+  verified full commit SHAs, not mutable major-version tags.
+- `bundler-audit check --update`: no known Ruby vulnerabilities at advisory DB
+  commit `fa2295251efb3b0d1a300e5ce8ad700ff1f1b485` (updated 2026-10-17).
+- CI additionally checks Ruby 3.2/3.3/3.4 with Rails 8.0/8.1. Consult the
+  linked repository workflow for the result of the latest audit commit.
+
+Tests establish these specific behaviors, not universal provider compatibility,
+complete accessibility, legal clearance, or an absence of future vulnerabilities.
+
+## Release setup on 2026-10-18
+
+- The owner explicitly authorized publication, public repository visibility,
+  and RubyGems OIDC trust for `yorzi/openui-rails`, `release.yml`, environment
+  `release`.
+- The repository is public. Security reports go to the address in `SECURITY.md`;
+  public support uses GitHub Issues.
+- RubyGems has a pending Trusted Publisher for the exact workflow and
+  environment. The first successful publication activates the gem's publisher.
+- The GitHub `release` environment requires approval by `yorzi`, allows the
+  `main` branch only, and disallows administrator bypass. Self-review remains
+  available for the single maintainer.
+- Dated `0.1.0` notes are in `CHANGELOG.md`. Gem and documentation versions
+  are checked together before packaging.
+- The built gem excludes the upstream browser bundle. A host that redistributes
+  the fetched bundle must review its transitive notices, including ISC-licensed
+  `lucide-react`. The gem's fetch task retains upstream legal comments and the
+  upstream license file. This is not a legal-clearance claim.
+
+## Boundaries hosts must enforce
+
+- Shared atomic idempotency storage for multiple processes. TTL expiry, crashes,
+  and irreversible effects still need database constraints or transactions.
+- Trusted confirmation UI and, where needed, signed server approvals. A client
+  boolean is not proof of human intent.
+- Authorized stream subscriptions, scoped surface lookup, and authoritative
+  snapshot persistence/recovery. The gem supplies no snapshot server.
+- Request/body/rate limits and provider token/time budgets.
+- A compatible prompt/spec/runtime library. The default bundle contains only
+  the chat library; custom libraries require a matching runtime.
+- CSP validation for the upstream renderer's inline styles. No strict-style-CSP
+  support is claimed. No human screen-reader certification is claimed.
+- API-only Rails authentication/CSRF integration is not covered by this release.
+
+The owner's publication authorization is not an independent legal, security,
+or accessibility certification. Follow [RELEASING.md](RELEASING.md) for each release.

data/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to `openui-rails` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-18
+
+### Fixed
+
+- Scope idempotency to server actor/tenant identity and bind replay digests to
+  the full request. Distinguish pending claims from completed nil results and
+  fence expired writers with claim tokens.
+- Preserve host authentication filters and default current-user resolution.
+- Reject authentication redirects and malformed or mismatched action responses
+  instead of reporting a false success.
+- Canonicalize and copy JSON input before validation/fingerprinting; prevent
+  mutable submissions, envelopes, surfaces, and manifests.
+- Make explicit configuration readiness validation read the actual manifest
+  and prompt files instead of accepting filenames alone.
+- Enforce stream terminal states, completion ordering, snapshot watermarks,
+  browser byte limits, and Turbo cache restoration.
+- Use the real OpenUI `{type, params}` action contract, avoid false MCP-client
+  detection, return raw tool values, and ignore empty renderer-error arrays.
+- Verify configured library fingerprints against the actual runtime `toSpec()`.
+- Fetch exact checksum-locked JS/CSS/license files without npm lifecycle scripts.
+  Add `openui_stylesheet_tag` and default integrity pins.
+- Correct RubyLLM's block-only `complete` call and verify 2.1.1 with real SSE parsing.
+- Align message framing edge cases with lang-core 1.0.1.
+- Require full CI and explicit manual approval before publication; create a
+  genuine draft GitHub release. See `UPGRADING.md` for pre-release changes.
+
+### Added
+
+- Mountable Rails engine under the `OpenUI::Rails` namespace with the
+  `openui/rails` require path.
+- Configuration object with validated transport, runtime-asset strategy,
+  library/prompt paths, stream limits and action hooks.
+- Versioned component-library manifest with a canonical SHA-256 fingerprint.
+- Prompt builder tying the model system instruction to the exact library
+  revision and stamping a combined prompt fingerprint.
+- Ruby implementation of the upstream OpenUI message protocol
+  (`build`/`parse`/`strip`).
+- Ordered stream envelopes (`openui.delta/snapshot/completed/error`), a
+  sequence accumulator and a coalescing stream bridge/writer.
+- Server-authoritative action loop: allowlist registry, arg schema,
+  confirmation, stale-surface check, required authorizer and idempotency.
+- `openui_surface` view helper and the `OpenUI::Rails::ActionsController`
+  endpoint.
+- Optional RubyLLM adapter (no hard dependency).
+- Stimulus mount controller and pinned runtime-asset resolution.
+- `openui:install` generator and the `openui:runtime:fetch` task.
+- Transport broadcasters (`ActionCable`, `TurboStreams`, `Memory`) behind
+  `Stream::Broadcaster`, and the `openui-envelope` Stimulus controller that
+  turns a Turbo Stream append into an `openui:envelope` event without inline
+  script.
+- Browser (system) test suite: lifecycle, stream ordering/duplicate/gap,
+  snapshot recovery, completion/error, action/tool round-trips, destructive
+  confirmation, and mount accessibility (`aria-busy` lifecycle, named region).
+- `aria-busy` on the mount element tracks the streaming state, and an optional
+  `label:` exposes the mount as a named `region` landmark.
+- Tag-driven release workflow and `RELEASING.md`.
+- Versioned guides and an RDoc API reference at
+  `https://openui-rails.wangyaodi.com`, deployed with GitHub Pages.
+- Gem-scoped RubyGems Trusted Publishing through GitHub OIDC, with a protected
+  release environment and verified artifact handoff.
+
+[Unreleased]: https://github.com/yorzi/openui-rails/compare/v0.1.0...main
+[0.1.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include
+showing empathy and kindness, respecting differing opinions, giving and
+gracefully accepting constructive feedback, and focusing on what is best for
+the community.
+
+Examples of unacceptable behavior include sexualized language or imagery,
+trolling or insulting comments, public or private harassment, and publishing
+others' private information without permission.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at **wangyaodi@gmail.com**. All complaints will be
+reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1,
+available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct/.

data/CONFIGURATION.md

@@ -0,0 +1,79 @@
+# Configuration
+
+Configure the bridge in `config/initializers/openui.rb`. Rails owns identity,
+authorization, stream subscriptions, persistence, and snapshot recovery.
+
+| Setting | Default | Contract |
+| --- | --- | --- |
+| `transport` | `:turbo` | Factory preference: `:turbo`, `:action_cable`, or `:none`. Pass it explicitly to `Transports.build`; it does not create a subscription. |
+| `library_spec_path` | `nil` | JSON manifest from the exact runtime library. Enables server and browser fingerprint checks. |
+| `prompt_path` | `nil` | Prompt generated from that same library. |
+| `runtime_assets` | `:self_hosted` | Use `:external` only with explicit exact-version URLs. |
+| `local_runtime_path` | `"/openui"` | Public URL directory for self-hosted assets. |
+| `runtime_version` | pinned `0.2.1` | The fetch task accepts only the checksum-locked version. Other versions are unverified. |
+| `runtime_url` | derived self-hosted JS URL | Explicit override for a host-built or external runtime. |
+| `runtime_integrity` | pinned hash for the default runtime | Override for another JS asset. No default hash is assumed for custom URLs. |
+| `runtime_stylesheet_url` | derived self-hosted CSS URL | Required when using `:external` and `openui_stylesheet_tag`. |
+| `runtime_stylesheet_integrity` | pinned hash for the default runtime | Override for another CSS asset. |
+| `actions_endpoint` | `"/openui-rails/actions"` | Must match the host engine mount. |
+| `stream_byte_limit` | `1_048_576` | Positive integer; enforced by server writer and browser. |
+| `pending_byte_limit` | `32_768` | Positive byte-based flush threshold, at most the stream limit. Lower it for smaller, more frequent updates. There is no timer-based flush. |
+| `idempotency_ttl` | `900` seconds | Finite positive number. Replays are protected only within the store's lifetime and TTL. |
+| `idempotency_store` | process-local `MemoryStore` | Use a shared atomic store for multiple processes. See the contract below. |
+| `idempotency_scope` | derived actor/tenant identity | Optional callable receiving `Invocation`; return a stable, JSON-serializable namespace for custom identity types. |
+| `actor_resolver` | host `current_user`, if available | Callable receiving the engine controller. Host authentication filters are inherited. |
+| `surface_resolver` | `nil` | Callable `(surface_id, actor:, context:)`; return the scoped surface, or `nil` to deny. Without it, the authorizer owns resource/version checks. |
+| `authorize_action` | `nil` | Global authorizer receiving `Invocation`. Missing authorization denies the action. Per-action `authorize:` takes precedence. |
+| `on_error` | `nil` | Server stream-error hook `(error, message_id:)`. Do not log credentials or unredacted provider requests. |
+| `action_registry` | lazy `Actions::Registry` | Allowlisted action definitions. |
+
+`library_name` and `surface_id_param` are legacy metadata settings. They do not
+select a runtime library or change the endpoint's `surface_id` wire key.
+
+After you create the library files, call
+`OpenUI::Rails.configuration.validate!` to check required configuration and
+read the actual manifest and configured prompt files.
+Boot does not call it automatically, so setup tasks can run before files exist.
+
+## Shared idempotency store
+
+The dispatcher supplies a SHA-256 key scoped to server actor and tenant identity.
+It supplies a digest of the entire validated request separately.
+
+```ruby
+claim(key, ttl:, digest:)
+# => [:claimed, nil, digest, claim_token]       # this request owns execution
+# => [:pending, nil, stored_digest, token]     # execution is in progress
+# => [:replay, result, stored_digest, token]   # completed, including nil/false
+
+record(key, result, claim_token: token)
+```
+
+Implement `claim` atomically. Make `claim_token` unique for every new claim.
+Ignore a `record` call whose token no longer owns the key. Preserve completed
+`nil` and `false` results instead of treating them as pending.
+
+The default identity is `[class, id]` for records and `[class, value]` for scalar
+identities. Unsupported identity objects need `idempotency_scope`. Scope must
+come from trusted server state, not a client-supplied user or tenant ID.
+
+A failed handler leaves a pending claim until expiry because its side effects
+may already have happened. A handler that outlives the TTL can overlap a later
+claim. Choose a suitable TTL and enforce business-level uniqueness or
+transactions for irreversible operations. Process-local memory does not survive
+restarts and cannot coordinate separate workers.
+
+## Browser errors and recovery
+
+Listen for `openui:error` to show a host-owned error or fallback. Listen for
+`openui:snapshot-required` to fetch an authorized, authoritative snapshot.
+The bridge emits these events; it does not implement the host's fallback UI,
+snapshot endpoint, reconnection policy, or persistence.
+
+The action bridge rejects authentication redirects and non-JSON, malformed, or
+mismatched results. An expired-session redirect emits `unauthorized`; a broken
+response contract emits `invalid_response`. Host callbacks may still redirect
+HTTP requests, but a redirect is never a successful JSON action result.
+
+Configure a matching manifest in production. Without one, the bridge cannot
+verify that the model prompt, stored output, and runtime library agree.

data/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing to openui-rails
+
+Thanks for helping. This is an unofficial Rails integration for Thesys OpenUI
+Lang; it does not reimplement the OpenUI parser or renderer.
+
+## Getting set up
+
+```bash
+git clone https://github.com/yorzi/openui-rails
+cd openui-rails
+bundle install
+bundle exec bin/rails db:test:prepare
+```
+
+## Before you open a pull request
+
+```bash
+bundle exec bin/rails test        # unit + integration tests
+bundle exec bin/rails test:system # browser (system) tests, needs Chrome
+bundle exec rubocop               # style (rubocop-rails-omakase)
+bundle exec gem build openui-rails.gemspec
+bundle exec ruby bin/smoke-package openui-rails-0.1.0.gem
+bundle exec bundler-audit check --update
+bundle exec ruby -Itest test/compatibility/ruby_llm_smoke.rb
+```
+
+The browser tests run against `test/dummy` with headless Chrome and a
+deterministic stub of the OpenUI runtime
+(`test/dummy/public/openui/openui-browser-bundle-0.2.1.js`), so they need no
+network or real bundle.
+
+CI also runs the real checksum-locked browser bundle. To run that probe locally:
+
+```bash
+bundle exec rake "app:openui:runtime:fetch[$PWD/tmp/real-runtime]"
+OPENUI_REAL_RUNTIME_DIR="$PWD/tmp/real-runtime" \
+  bundle exec ruby -Itest test/compatibility/runtime_smoke.rb
+```
+
+The first command needs npm and network access. The browser probe uses local
+assets afterward. The RubyLLM probe uses the real 2.1.1 client and SSE parser,
+with WebMock and a dummy API key. It never calls a paid provider.
+
+Keep the test suite green and add negative/security tests alongside any new
+behavior. Changes to the action path or the stream protocol are expected to
+include unauthorized, wrong-tenant, replay, stale-version and malformed-payload
+cases.
+
+## Guidelines
+
+- Prefer the official OpenUI runtime over any hand-rolled parser. Model output
+  is untrusted UI DSL, never executable code.
+- Keep `ruby_llm` optional and isolated under `OpenUI::Rails::Adapters`; do not
+  reference a `RubyLLM` constant outside a guarded adapter.
+- Inside `module OpenUI`, write `::Rails` for the framework.
+- Do not introduce floating dependency ranges for the OpenUI JS runtime or the
+  prompt CLI; pin exact versions.
+- Write commit messages that explain the *why*.
+
+## Reporting security issues
+
+Please do not open a public issue for a security problem. See `SECURITY.md`.
+
+## Code of Conduct
+
+By participating you agree to `CODE_OF_CONDUCT.md`.

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Andy Wang and openui-rails contributors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.