cypress-on-rails 1.20.0 → 1.20.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c135e18e23ddeea1d0d2bbd246de9147b9ce42969bd862e51f1e3dec39abbe0
-  data.tar.gz: a295806731243324fbfda475ec6be6a6c4bce60651755b278431afd722501cab
+  metadata.gz: 03e4421f8ff1e369df5164505021ef31262e063d1ce1933af39e8904d5f682a2
+  data.tar.gz: c5d25bca33e634bfd510cca6f3f038f509f2b46a2cac04930066f01b35b53c67
 SHA512:
-  metadata.gz: 501aebab098ec19fbec53e3f7ea0ef8adc966c0d4ec2d60a0c424c45e369ad652899270b5e411376f5e582ef8a29acc3d02814cccee85654fe989bdc0aad9c1f
-  data.tar.gz: f833268a8c93e4853fbb28d5b26f653ae741817c4314756975ebd46cac69b6791ca0d436a1d4ab20c9f0be88d4e14b4e399d3d59326cbaf01fb4f2d0b57f24d4
+  metadata.gz: 6a43f0a617482954a081168eed51481ae04b627fe3696825a5a8f4f0ed342874e7dc19eb2f0efac7485ba2932d02d9586035b010e8015a2a6ab1d0faa731d69b
+  data.tar.gz: b4753c4997d497a6e641285824123efac710f8e8850fd84c5cde3ca96735ca540647ca5931d797fa38bc88425128a25b7813f4cf2111d76fbce594926e07127d

data/.agents/agent-workflow.yml

@@ -0,0 +1,9 @@
+# Non-command agent-workflow configuration for portable shared skills.
+base_branch: master
+changelog: "CHANGELOG.md - user-visible changes only; version-stamp via bundle exec rake update_changelog[release|rc|beta|VERSION]; PR links use [PR N](https://github.com/shakacode/cypress-playwright-on-rails/pull/N) by [username](https://github.com/username)."
+follow_up_prefix: "Follow-up:"
+review_gate: "Ruby workflow green on the PR, local bundle exec rake evidence, and all review threads resolved."
+approval_exempt: "docs, workflow text, helper scripts, and focused release-process edits with tests."
+coordination_backend: "private shakacode/agent-coordination (claims/heartbeats namespaced by full repo name)"
+hosted_ci_trigger: "CI runs on every PR."
+ci_parity_environment: "Use .github/workflows/ruby.yml; reproduce failures with bundle exec rake plus the matching specs_e2e/*/test.sh job when needed."

data/.claude/commands/update-changelog.md

@@ -0,0 +1,71 @@
+# Update Changelog
+
+You are helping update `CHANGELOG.md` for `shakacode/cypress-playwright-on-rails`.
+
+## Arguments
+
+This command accepts an optional argument: `$ARGUMENTS`
+
+- No argument: add missing user-visible entries to `## [Unreleased]`.
+- `release`: add entries, then stamp the next stable version with `bundle exec rake update_changelog[release]`.
+- `rc`: add entries, then stamp the next release candidate with `bundle exec rake update_changelog[rc]`.
+- `beta`: add entries, then stamp the next beta with `bundle exec rake update_changelog[beta]`.
+- Explicit version such as `1.21.0.rc.0`: add entries, then stamp that exact version with `bundle exec rake update_changelog[1.21.0.rc.0]`.
+
+After the changelog PR merges, the release task reads the newest stamped changelog version automatically:
+
+```bash
+bundle exec rake release
+```
+
+## Core Rules
+
+- Add entries only for user-visible changes: features, bug fixes, breaking changes, deprecations, performance improvements, security fixes, and public API/configuration changes.
+- Skip linting, formatting, internal refactors, test-only changes, CI changes, and docs-only changes unless the docs correct public behavior.
+- Do not ask the user for PR details. Use git history and GitHub.
+- Use the repo's current changelog shape:
+  - Version headers: `## [1.21.0.rc.0] - YYYY-MM-DD`
+  - Category headings: `### Added`, `### Changed`, `### Improved`, `### Fixed`, etc.
+  - PR links: `[PR 219](https://github.com/shakacode/cypress-playwright-on-rails/pull/219) by [username](https://github.com/username)`.
+
+## Release Flow
+
+1. Fetch current branch, base branch, and tags:
+
+   ```bash
+   git fetch origin master --tags
+   ```
+
+2. Inspect merged PRs since the latest release tag:
+
+   ```bash
+   git tag -l 'v*' --sort=-v:refname | head -10
+   git log --oneline LATEST_TAG..origin/master
+   ```
+
+3. Add missing user-visible entries under `## [Unreleased]`, merging into existing category headings.
+
+4. If `$ARGUMENTS` asks for a release stamp, run the rake task:
+
+   ```bash
+   bundle exec rake "update_changelog[release]"
+   bundle exec rake "update_changelog[rc]"
+   bundle exec rake "update_changelog[beta]"
+   bundle exec rake "update_changelog[1.21.0.rc.0]"
+   ```
+
+5. Verify:
+
+   ```bash
+   bundle exec rake
+   ```
+
+6. Commit the changelog update on a branch and open a PR. Once merged, release with:
+
+   ```bash
+   git switch master
+   git pull --ff-only
+   bundle exec rake release
+   ```
+
+The release task bumps `lib/cypress_on_rails/version.rb`, updates `Gemfile.lock`, commits, tags, pushes, publishes the gem, and creates or updates the GitHub release from the stamped changelog section.

data/.github/workflows/claude-code-review.yml

@@ -2,56 +2,45 @@ name: Claude Code Review
 
 on:
   pull_request:
-    types: [opened, synchronize]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
+    types: [opened, synchronize, ready_for_review, reopened]
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-    
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: read
-      issues: read
+      pull-requests: write
+      issues: write
       id-token: write
-    
+
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 
       - name: Run Claude Code Review
         id: claude-review
         uses: anthropics/claude-code-action@v1
+        env:
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           prompt: |
             REPO: ${{ github.repository }}
             PR NUMBER: ${{ github.event.pull_request.number }}
 
-            Please review this pull request and provide feedback on:
+            Please review this pull request with a focus on:
             - Code quality and best practices
             - Potential bugs or issues
+            - Security implications
             - Performance considerations
-            - Security concerns
-            - Test coverage
-            
-            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
 
-            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
-          
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
-          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+            Note: The PR branch is already checked out in the current working directory.
+
+            Use `gh pr comment` for top-level feedback.
+            Use `mcp__github_inline_comment__create_inline_comment` to highlight specific code issues.
+            Only post GitHub comments - don't submit review text as messages.
 
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

data/.github/workflows/claude.yml

@@ -11,19 +11,112 @@ on:
     types: [submitted]
 
 jobs:
-  claude:
+  authorize_claude_actor:
     if: |
       (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
       (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
       (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
       (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      authorized: ${{ steps.permission-gate.outputs.authorized }}
+    steps:
+      - name: Verify actor can run Claude
+        id: permission-gate
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const permissionByLogin = new Map();
+
+            function claudeRequester() {
+              if (
+                context.eventName === 'issue_comment' ||
+                context.eventName === 'pull_request_review_comment'
+              ) {
+                return context.payload.comment?.user?.login;
+              }
+
+              if (context.eventName === 'pull_request_review') {
+                return context.payload.review?.user?.login;
+              }
+
+              if (context.eventName === 'issues') {
+                return context.payload.issue?.user?.login;
+              }
+
+              return null;
+            }
+
+            async function hasWriteAccessFor(username) {
+              if (!username) {
+                return false;
+              }
+
+              if (permissionByLogin.has(username)) {
+                return permissionByLogin.get(username);
+              }
+
+              let hasWriteAccess = false;
+              try {
+                const { data: permission } = await github.rest.repos.getCollaboratorPermissionLevel({
+                  owner,
+                  repo,
+                  username
+                });
+                hasWriteAccess = ['admin', 'write'].includes(permission.permission);
+              } catch (error) {
+                core.warning(
+                  `Unable to verify ${username} write permission for Claude; ` +
+                    `treating the Claude request as untrusted: ${error.message || error}`
+                );
+              }
+
+              permissionByLogin.set(username, hasWriteAccess);
+              return hasWriteAccess;
+            }
+
+            const actor = context.actor;
+            const requester = claudeRequester();
+
+            if (!requester) {
+              core.setOutput('authorized', 'false');
+              core.setFailed('Unable to run Claude because the requester could not be determined.');
+              return;
+            }
+
+            if (!(await hasWriteAccessFor(actor))) {
+              core.setOutput('authorized', 'false');
+              core.setFailed(`Unable to run Claude because ${actor} does not have write/admin repository permission.`);
+              return;
+            }
+
+            if (!(await hasWriteAccessFor(requester))) {
+              core.setOutput('authorized', 'false');
+              core.setFailed(
+                `Unable to run Claude because requester ${requester} does not have write/admin repository permission.`
+              );
+              return;
+            }
+
+            core.setOutput('authorized', 'true');
+            core.info(`Authorized ${actor} and Claude requester ${requester} to run Claude.`);
+
+  claude:
+    needs: authorize_claude_actor
+    if: needs.authorize_claude_actor.outputs.authorized == 'true'
+    runs-on: ubuntu-latest
     permissions:
       contents: read
       pull-requests: read
       issues: read
       id-token: write
       actions: read # Required for Claude to read CI results on PRs
+      checks: read
+      statuses: read
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -33,12 +126,17 @@ jobs:
       - name: Run Claude Code
         id: claude
         uses: anthropics/claude-code-action@v1
+        env:
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
         with:
+          github_token: ${{ github.token }}
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           
           # This is an optional setting that allows Claude to read CI results on PRs
           additional_permissions: |
             actions: read
+            checks: read
+            statuses: read
 
           # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
           # prompt: 'Update the pull request description to include a summary of changes.'

data/CHANGELOG.md

@@ -7,9 +7,25 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.20.1] - 2026-07-10
+
+### Fixed
+- **Rails 8.1 compatibility**: Required ActiveSupport delegation explicitly so the railtie loads under Rails 8.1. [PR 207](https://github.com/shakacode/cypress-playwright-on-rails/pull/207) by [justin808](https://github.com/justin808).
+- **Playwright helper JSON responses**: Updated generated `appCommands`, `appVcrInsertCassette`, and `appVcrEjectCassette` helpers to return parsed JSON rather than a `Buffer`. [PR 219](https://github.com/shakacode/cypress-playwright-on-rails/pull/219) by [justin808](https://github.com/justin808). Original fix by [helio3197](https://github.com/helio3197) in [PR 168](https://github.com/shakacode/cypress-playwright-on-rails/pull/168).
+- **Configured Rails environment**: Preserved an existing `RAILS_ENV` when starting the managed test server, allowing E2E runs to target a configured environment. [PR 210](https://github.com/shakacode/cypress-playwright-on-rails/pull/210) by [arielj](https://github.com/arielj).
+
+---
+
+## [1.20.0] - 2025-10-21
+[Compare](https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.19.0...v1.20.0)
+
 ### Fixed
 * **BREAKING: Generator folder structure**: Fixed install generator to create `e2e_helper.rb` and `app_commands/` at the install folder root (e.g., `e2e/`) instead of inside the framework subdirectory (e.g., `e2e/cypress/`). This ensures compatibility between Cypress/Playwright config file location and middleware expectations. [#201]
 
+### Changed
+* Improved server process cleanup and readiness checks. [PR 199](https://github.com/shakacode/cypress-playwright-on-rails/pull/199)
+* Gem description now mentions Playwright support. [PR 200](https://github.com/shakacode/cypress-playwright-on-rails/pull/200)
+
 ### Migration Guide for Folder Structure Change
 
 #### Breaking Change Notice
@@ -515,6 +531,9 @@ If migrating from the `cypress-rails` gem:
 [#201]: https://github.com/shakacode/cypress-playwright-on-rails/issues/201
 
 <!-- Version diff reference list -->
+[unreleased]: https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.20.1...master
+[1.20.1]: https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.20.0...v1.20.1
+[1.20.0]: https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.19.0...v1.20.0
 [1.19.0]: https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.18.0...v1.19.0
 [1.18.0]: https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.17.0...v1.18.0
 [1.17.0]: https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.16.0...v1.17.0

data/CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## ⚠️ CRITICAL REQUIREMENTS
+
+**BEFORE EVERY COMMIT/PUSH:**
+
+1. **ALWAYS ensure files end with a newline character**
+2. **ALWAYS run tests before pushing**
+
+These requirements are non-negotiable. CI will fail if not followed.
+
+## Development Commands
+
+### Essential Commands
+
+- **Install dependencies**: `bundle`
+- **Run tests**:
+  - Ruby tests: `bundle exec rspec`
+  - All tests: `bundle exec rake` (default task runs tests)
+- **⚠️ MANDATORY BEFORE GIT PUSH**: Ensure tests pass + ensure trailing newlines
+
+## Changelog
+
+- **Update CHANGELOG.md for user-visible changes only** (features, bug fixes, breaking changes, deprecations, performance improvements)
+- **Do NOT add entries for**: linting, formatting, refactoring, tests, or documentation fixes
+- **Format**: `[PR 123](https://github.com/shakacode/cypress-on-rails/pull/123) by [username](https://github.com/username)` (no hash in PR number)
+- **Use `/update-changelog` command** for guided changelog updates with automatic formatting
+- **Version management**: Run `bundle exec rake update_changelog` after releases to update version headers (if rake task exists)
+- **Examples**: Run `grep -A 3 "^#### " CHANGELOG.md | head -30` to see real formatting examples
+
+## Project Architecture
+
+### Core Components
+
+This is a Ruby gem that provides integration between Cypress/Playwright and Rails applications.
+
+#### Ruby Side (`lib/cypress_on_rails/`)
+
+- **`middleware.rb`**: Rack middleware for handling Cypress/Playwright commands
+- **`configuration.rb`**: Global configuration management
+- **Generators**: Located in `lib/generators/cypress_on_rails/`
+
+#### Test Framework Support
+
+- **Cypress**: JavaScript-based E2E testing framework
+- **Playwright**: Modern browser automation framework
+- Both frameworks share the same Ruby backend commands
+
+### Build System
+
+- **Ruby**: Standard gemspec-based build
+- **Testing**: RSpec for Ruby tests
+- **Linting**: RuboCop for Ruby
+
+### Examples and Testing
+
+- **Specs**: `spec/` - RSpec tests for the gem
+- **E2E Examples**: `specs_e2e/` - End-to-end test examples
+- **Rake tasks**: Defined in `rakelib/` for various development operations
+
+## Important Notes
+
+- Server-side commands are executed via Rack middleware
+- Commands can use factory_bot, database_cleaner, and other test helpers
+- VCR integration available for HTTP mocking
+- Supports both Cypress and Playwright frameworks
+- Configuration is done in `config/initializers/cypress_on_rails.rb`

data/CONTEXT.md

@@ -0,0 +1,26 @@
+# Context
+
+Canonical vocabulary for this project. If a term here conflicts with usage in
+an issue, PR, or doc, this file wins; update it deliberately, not incidentally.
+
+## Naming (resolved 2026-07-04, see ADR-0001 + ADR-0002)
+
+| Term | Meaning |
+|---|---|
+| **E2E on Rails** | The public/brand name of the project (ADR-0002). Tagline: "The Rails test bridge for Cypress and Playwright." |
+| `cypress-on-rails` | The published gem name through the 1.x line. Canonical in Gemfiles until 2.0, then the compatibility shim. |
+| `e2e_on_rails` | Thin wrapper gem, not yet published (#226 tracks it); the canonical gem from 2.0. 2.0 is scheduled right after the v1.22 line ships. |
+| `CypressOnRails` | The Ruby module namespace through 1.x. Renames to `E2eOnRails` (with a `CypressOnRails` deprecation alias) at 2.0. |
+| `cypress-playwright-on-rails` | Current GitHub repository name; renames to `shakacode/e2e-on-rails` immediately after v1.21.0 ships (GitHub redirects). Never a gem name. |
+| `e2eonrails.com` | Purchased 2026-07-04. Canonical docs + landing page at the apex (no `docs.` subdomain, no defensive variants). Supersedes the earlier testing.shakastack.com plan. |
+
+## Core domain terms
+
+| Term | Meaning |
+|---|---|
+| install folder | The app-side directory (config `install_folder`) holding `e2e_helper.rb`, `app_commands/`, and framework config. The install **generator** defaults it to `e2e/`; the gem's `Configuration#reset` defaults to `spec/e2e` for apps configured without the generator. Since v1.20.0, helper and commands live at its **root**, not inside `cypress/`. |
+| app command | A Ruby file in `app_commands/` executed in the Rails process when a test calls `cy.app(...)` / `app(...)`. The middleware's unit of remote execution. |
+| scenario | An app command under `app_commands/scenarios/` that seeds a named state, invoked via `cy.appScenario(...)`. |
+| middleware | `CypressOnRails::Middleware`, mounted outside production only, serving the `__e2e__` (legacy `__cypress__`) API prefix. Executes arbitrary Ruby by design — see README security model and issue #13. |
+| managed server | The Rails server started/stopped by the `cypress:*` / `playwright:*` rake tasks (since v1.19.0), with lifecycle hooks (`before_server_start`, …, `before_server_stop`). |
+| transactional server | `transactional_server` mode wrapping the run in a rolled-back DB transaction, reset via `/cypress_rails_reset_state` (cypress-rails-compatible endpoint). |