biscuit-rails 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ccf326f39e2cdccc7cb9991e0f9ad738b97ff3d1ca1837ea0793907e1cf07e72
-  data.tar.gz: f94e5fec99ef45102ac05d9523d68b1db95c2a61a13a331553419de7feb2dc46
+  metadata.gz: a99734c304d99da013a29fd797e8d8d9461bdea8811bb87997bddc4a0b1cd100
+  data.tar.gz: b93c476239e0e9ee02f5466596b1de11dc3f24fcb3794c7b99497a66073efaf4
 SHA512:
-  metadata.gz: 37b281be185c6e46f19ada084760ec585ff2e144dd15c532a5d94188610809488fbafe6d7fcfb64881bcc87f54b5ee22876ac7f7809079197cbee408e999ca61
-  data.tar.gz: 32d9e8d34b824c355a190041c58d5fc6b33ad436ae9100b4babec40fb8585ca2031d0cc683d369590ca9fea6f9afe9972650a74a474448a06332df2def4e710e
+  metadata.gz: 695482883b254ce859513919089eaa30f80947d792f9755cba738db35aff1bfde4bf6472cdbde5860b4e300acf05dda113ba595f26a422f2d6d60ef1833975d1
+  data.tar.gz: 197a2f37232f33b7b179fef7418497eaed80a3630016175e75709315e01778b273fdc0fa8347371b07c84884b0d78b0e696b9d6f0093eb930f779d8bc4ed0c6b

data/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-03-31
+
+### Added
+
+- `rails generate biscuit:install` generator — installs a Claude Code skill
+  into `.claude/skills/biscuit-install/` for AI-assisted setup
+- `biscuit-install` Claude Code skill — guides developers through compatibility
+  checks, engine mounting, Stimulus registration, initializer configuration,
+  cookie and tracking script audit, integration tests, and optional commit
+- README section documenting the AI-assisted setup workflow
+
+---
+
 ## [0.1.4] - 2026-03-29
 
 ### Fixed

data/README.md

@@ -21,7 +21,39 @@ default).
 
 ---
 
-## Installation
+## AI-assisted setup (Claude Code)
+
+If you use [Claude Code](https://claude.ai/code), the quickest way to install
+and configure biscuit is via the built-in setup skill.
+
+After adding the gem to your Gemfile and running `bundle install`, run the
+generator to install the skill:
+
+```sh
+rails generate biscuit:install
+```
+
+Then open Claude Code in your project and run:
+
+```
+/biscuit-install
+```
+
+The skill will:
+
+- Check your app is compatible (Ruby, Rails, Propshaft, Stimulus)
+- Mount the engine and register the Stimulus controller
+- Ask about banner position, cookie categories, and other preferences
+- Generate `config/initializers/biscuit.rb` from your answers
+- Scan your codebase for existing cookies and third-party tracking scripts
+  (Google Analytics, GTM, Meta Pixel, etc.) and help you wrap them with
+  `biscuit_allowed?` guards
+- Add integration tests and run them
+- Optionally commit everything
+
+---
+
+## Manual installation
 
 Add to your `Gemfile`:
 

data/lib/biscuit/version.rb

@@ -1,3 +1,3 @@
 module Biscuit
-  VERSION = "0.1.4"
+  VERSION = "0.2.0"
 end

data/lib/generators/biscuit/install/install_generator.rb

@@ -0,0 +1,26 @@
+require "rails/generators"
+
+module Biscuit
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs the biscuit-rails Claude Code setup skill into .claude/skills/biscuit-install/"
+
+      def copy_claude_skill
+        empty_directory ".claude/skills/biscuit-install"
+        copy_file "SKILL.md", ".claude/skills/biscuit-install/SKILL.md"
+
+        say ""
+        say "  Claude Code skill installed at .claude/skills/biscuit-install/SKILL.md", :green
+        say ""
+        say "  Open Claude Code in this project and run:", :cyan
+        say "    /biscuit-install", :cyan
+        say ""
+        say "  The skill will check compatibility, configure the gem, audit your existing", :cyan
+        say "  cookies and tracking scripts, add tests, and optionally commit.", :cyan
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/biscuit/install/templates/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: biscuit-install
+description: Install and configure the biscuit-rails GDPR cookie consent gem. Checks compatibility, installs the gem, configures categories and position, audits existing cookies and tracking scripts, adds integration tests, and optionally commits.
+disable-model-invocation: true
+---
+
+# biscuit-install
+
+Complete installation and setup of biscuit-rails in this Rails app. Work through each step in order, confirming with the user before making any changes.
+
+---
+
+## Step 1 — Compatibility check
+
+Read `Gemfile`, `Gemfile.lock`, and `.ruby-version` (if present) to check:
+
+- **Ruby >= 3.2** — stop with a clear error if not met
+- **Rails >= 8.0** — check `Gemfile.lock` for the rails version; stop if not met
+- **Asset pipeline** — check Gemfile for `propshaft`. If absent, warn that `stylesheet_link_tag "biscuit/biscuit"` may need adjustment
+- **JS setup** — check for `importmap-rails` vs `jsbundling-rails`/`vite_rails`. Note the difference for Step 5
+- **Stimulus** — check for `stimulus-rails` or `hotwire-rails`. Warn if absent — Stimulus must be installed for the banner to work
+- **Conflicts** — check for other cookie consent gems (`eu_cookie_law`, `cookieconsent`, `cookie_law`). Warn if found
+
+Report findings before proceeding.
+
+---
+
+## Step 2 — Add gem to Gemfile
+
+Check if `biscuit-rails` already appears in the Gemfile. If not:
+
+- Add `gem "biscuit-rails"` to the Gemfile
+- Run `bundle install`
+
+If already present, skip this step.
+
+---
+
+## Step 3 — Mount the engine
+
+Check `config/routes.rb` for an existing `mount Biscuit::Engine` line. If absent, add it inside the `routes.draw` block:
+
+```ruby
+mount Biscuit::Engine, at: "/biscuit"
+```
+
+---
+
+## Step 4 — Configure the initializer
+
+Ask the user the following questions before writing anything:
+
+1. **Banner position** — top or bottom? (default: `bottom`)
+2. **Cookie categories** — which categories beyond `necessary` are needed? Options: `analytics`, `marketing`, `preferences`, or custom names. (default: `analytics` and `marketing`)
+3. **Reload on consent** — should the page reload after the user saves consent, so conditionally-loaded scripts activate immediately? (default: `false`)
+4. **Privacy policy URL** — where does your privacy policy live? (default: `"/privacy"`)
+5. **Cookie lifetime** — how many days should consent last? (default: `365`)
+
+Then create `config/initializers/biscuit.rb` based on their answers. Example output:
+
+```ruby
+Biscuit.configure do |config|
+  config.position            = :bottom
+  config.privacy_policy_url  = "/privacy"
+  config.cookie_expires_days = 365
+
+  config.categories = {
+    necessary:  { required: true },
+    analytics:  { required: false },
+    marketing:  { required: false }
+  }
+end
+```
+
+If `config/initializers/biscuit.rb` already exists, show the current content and ask before overwriting.
+
+If custom category names are used, remind the user to add matching i18n keys to their locale files — for example:
+
+```yaml
+en:
+  biscuit:
+    categories:
+      my_category:
+        name: "My Category"
+        description: "Used for..."
+```
+
+---
+
+## Step 5 — Register the Stimulus controller
+
+### If using importmap
+
+Check `app/javascript/controllers/index.js`. If `biscuit/biscuit_controller` is not already imported, add:
+
+```javascript
+import BiscuitController from "biscuit/biscuit_controller"
+application.register("biscuit", BiscuitController)
+```
+
+Ensure `application` is already imported at the top of that file (it will be in the standard Rails 8 scaffold).
+
+### If using esbuild / jsbundling
+
+The same import and register lines apply, but inform the user that `@hotwired/stimulus` must be marked as external in their esbuild config so it is not bundled twice:
+
+```js
+// esbuild.config.js
+external: ["@hotwired/stimulus"]
+```
+
+---
+
+## Step 6 — Add stylesheet and banner to layout
+
+Check `app/views/layouts/application.html.erb`:
+
+- Add `<%= stylesheet_link_tag "biscuit/biscuit" %>` inside `<head>` if not already present
+- Add `<%= biscuit_banner %>` as the first child of `<body>` if not already present
+
+If the layout file doesn't exist at that path, ask the user which layout file to modify.
+
+If the app uses `reload_on_consent: true` (from Step 4), use:
+
+```erb
+<%= biscuit_banner(reload_on_consent: true) %>
+```
+
+---
+
+## Step 7 — Cookie and tracking script audit
+
+Scan the codebase for existing cookie and tracking usage that should be gated behind consent. Report all findings before making any changes — let the user decide what to wrap.
+
+### Server-side cookies (Ruby)
+
+Search `app/` for:
+- `cookies[`, `cookies.permanent[`, `cookies.signed[`, `cookies.encrypted[`
+
+For each result, determine whether it is a functional/necessary cookie (session, CSRF, etc.) or a tracking cookie. Non-necessary cookies should be wrapped in the relevant controller:
+
+```ruby
+if Biscuit::Consent.new(cookies).allowed?(:analytics)
+  cookies[:my_tracking_cookie] = { value: "...", expires: 1.year }
+end
+```
+
+### Client-side storage (JavaScript)
+
+Search `app/assets/` and `app/javascript/` for:
+- `document.cookie`
+- `localStorage.setItem`
+- `sessionStorage.setItem`
+
+Non-necessary writes should check the `biscuit_consent` cookie before setting.
+
+### Third-party scripts (layout/views)
+
+Search `app/views/layouts/` and `app/views/` for known analytics and marketing patterns:
+
+| Pattern | Category |
+|---|---|
+| `gtag(`, `googletagmanager.com`, `_gaq`, `ga(` | analytics |
+| `GTM-` | analytics |
+| `fbq(`, `connect.facebook.net` | marketing |
+| `intercomSettings`, `widget.intercom.io` | marketing |
+| `hj(`, `static.hotjar.com` | analytics |
+| `hs-script-loader` | marketing |
+| `_linkedin_data_partner_id` | marketing |
+
+For each match, show the file, line number, and suggested wrapping:
+
+```erb
+<% if biscuit_allowed?(:analytics) %>
+  <!-- existing script -->
+<% end %>
+```
+
+Ask the user to confirm each wrapping before applying it.
+
+---
+
+## Step 8 — Add integration tests
+
+Check whether the app uses Minitest (`test/`) or RSpec (`spec/`).
+
+### Minitest
+
+If `test/integration/biscuit_consent_test.rb` does not exist, create it:
+
+```ruby
+require "test_helper"
+
+class BiscuitConsentTest < ActionDispatch::IntegrationTest
+  test "banner is shown on first visit" do
+    get "/"
+    assert_response :success
+    assert_select "[data-controller='biscuit']"
+  end
+
+  test "biscuit_allowed? returns false before consent" do
+    get "/"
+    assert_equal false, Biscuit::Consent.new(cookies).allowed?(:analytics)
+  end
+
+  test "biscuit_allowed? for necessary always returns true" do
+    get "/"
+    assert_equal true, Biscuit::Consent.new(cookies).allowed?(:necessary)
+  end
+
+  test "accept all sets consent cookie" do
+    post "/biscuit/consent", params: {},
+      headers: { "Content-Type" => "application/json" },
+      as: :json,
+      body: { categories: { analytics: true, marketing: true } }.to_json
+    assert_response :success
+    assert Biscuit::Consent.new(cookies).given?
+    assert Biscuit::Consent.new(cookies).allowed?(:analytics)
+  end
+
+  test "reject all sets non-required categories to false" do
+    post "/biscuit/consent", params: {},
+      headers: { "Content-Type" => "application/json" },
+      as: :json,
+      body: { categories: { analytics: false, marketing: false } }.to_json
+    assert_response :success
+    assert Biscuit::Consent.new(cookies).given?
+    assert_equal false, Biscuit::Consent.new(cookies).allowed?(:analytics)
+  end
+end
+```
+
+Adjust category names to match the categories configured in Step 4.
+
+### RSpec
+
+If `spec/requests/biscuit_consent_spec.rb` does not exist, create an equivalent using RSpec/Rails request spec syntax.
+
+Run the new tests and confirm they pass before continuing.
+
+---
+
+## Step 9 — Optional commit
+
+Ask the user: "Would you like to commit these changes?"
+
+If yes, stage only the files that were created or modified during this setup and commit:
+
+```
+git add config/routes.rb config/initializers/biscuit.rb \
+        app/views/layouts/application.html.erb \
+        app/javascript/controllers/index.js \
+        test/integration/biscuit_consent_test.rb
+git commit -m "Install biscuit-rails cookie consent"
+```
+
+Do not use `git add -A` — only stage biscuit-related files.
+
+---
+
+## Summary
+
+After all steps complete, print a summary of:
+- What was installed and configured
+- Which tracking scripts were wrapped (if any)
+- Any manual steps remaining (custom i18n keys, esbuild config, layouts other than `application.html.erb`)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: biscuit-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Gareth James
 bindir: bin
 cert_chain: []
-date: 2026-03-29 00:00:00.000000000 Z
+date: 2026-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -51,6 +51,8 @@ files:
 - lib/biscuit/engine.rb
 - lib/biscuit/rails.rb
 - lib/biscuit/version.rb
+- lib/generators/biscuit/install/install_generator.rb
+- lib/generators/biscuit/install/templates/SKILL.md
 homepage: https://github.com/garethfr/biscuit-rails
 licenses:
 - MIT