product_tours 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f48e747fd564905f78ca0c5f2609c0a2cef62352e8789ec4ce0fc8e9fb632dd0
-  data.tar.gz: 4dea4cbd842d0e1c3acafc5abe71719d4b882ae20750bc7441294d52e6ad7e10
+  metadata.gz: fd91edac94c4a143630f7ba27c3892e750fbce4ea6f4c59490389ceae46a3e63
+  data.tar.gz: ab9eac5f0d14a4548bd49b89ccb7ad195031db2967123be5637953f318a439b3
 SHA512:
-  metadata.gz: ca825401c59636fb1ca6f4ad5f243344e8ff83e976d2357c5b0b536336a824464c98bde51f61773d679935cb3ebe23b80cc6c22b13a6af202a19e261630e3fc5
-  data.tar.gz: ccff1b7cefeed57de45b8581c4ecd31c73a6a14d1983333dbb13bb39ee07f2c07244dff11166220d2390afa32da8b7889f2bfc0eb5b6b4feda79f2019c457f98
+  metadata.gz: b92ad9c92502b29411417e0c98764068df9dc1b9f6cd73c6751887d263124beee0261f1deddb4ed75bac5ae0b09b137cf20ae6e00eb83cda1f0d790979b0987a
+  data.tar.gz: 835576cf29da8b9210d42565494a3595fa6d76c7816b7e0aaef05be5a2cb2574324a5cd1e3524879998896d56a4b6bc63e66e48de2458986c538eee3671b360e

data/AGENTS.md

@@ -0,0 +1,149 @@
+# AGENTS.md
+
+Instructions for coding agents. Two audiences:
+
+- **[Installing product_tours into a Rails app](#installing-into-a-rails-app)** — you are working in a host app and were asked to add product tours, onboarding guides, or video tutorials.
+- **[Working on the gem itself](#working-on-the-gem-itself)** — you are working in this repository.
+
+Requirements: Ruby >= 3.2, Rails >= 7.1. Active Storage only for uploaded videos, Action Text only for rich descriptions — both optional and both degrade rather than raise.
+
+If you are in a host app and this file is not in front of you, it ships inside the gem: `cat "$(bundle show product_tours)/AGENTS.md"`.
+
+---
+
+## Installing into a Rails app
+
+### 1. Install
+
+```bash
+bundle add product_tours
+bin/rails generate product_tours:install
+bin/rails db:migrate
+```
+
+The generator writes `config/initializers/product_tours.rb`, one migration (`product_tours_posts`), and `mount_product_tours at: "/product_tours"` into `config/routes.rb`. **In development the migration also inserts working demo tutorials**, so the modal has something to open before anyone has written content. Read the initializer it wrote — it is the source of truth over any summary of it, including this file.
+
+### 2. Wire the three things the generator cannot
+
+**a. The widget tag**, once, in the layout:
+
+```erb
+<%# app/views/layouts/application.html.erb, before </body> %>
+<%= product_tours_tag %>
+```
+
+The helper is injected into ActionView by the engine — no include, no import, no asset pipeline entry.
+
+**b. A trigger**, wherever the tutorial is useful. This is the part that makes it different from a SaaS tour builder: nothing auto-attaches to DOM nodes, you put the button where it belongs.
+
+```erb
+<button data-product-tour="billing_setup">Watch the billing guide</button>
+```
+
+The value is a tutorial **key**, and the key must exist and be **published** or the trigger does nothing.
+
+**c. `authorize_admin` — do this before deploying.** The dashboard at `/product_tours` defaults to **development only**. It fails closed, so shipping without this is not an open dashboard — it is a 403 reading "Forbidden. Set ProductTours.config.authorize_admin to grant access."
+
+```ruby
+config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+```
+
+> **`enabled` and `authorize_admin` receive the raw `request`, not a controller.** Writing `->(request) { current_user }` is the most common mistake here — that method does not exist in this scope. Resolve the user *from the request*: Warden env, a signed cookie, `Current.user` if middleware already set it.
+
+```ruby
+# Rails 8 built-in auth
+config.authorize_admin = lambda do |request|
+  token = request.cookies["session_token"]
+  Session.find_signed(token)&.user&.admin? || false
+end
+```
+
+### 3. Verify
+
+```bash
+bin/rails routes | grep product_tours     # engine mounted
+bin/rails product_tours:seed_demo         # refresh demo tutorials in every locale
+```
+
+Then in the running app: open `/product_tours`, confirm the demo tutorials are listed, and click a `data-product-tour` button on one of your own pages.
+
+### Tutorials are content, not code
+
+A tutorial is a row in `product_tours_posts`, written and published in the mounted dashboard. **Do not create tutorials from host-app migrations, seeds, or fixtures** — that is not how this gem is meant to be used, and it puts editorial content in schema history. If the app needs sample content, `bin/rails product_tours:seed_demo` is the supported path.
+
+What a tutorial carries: a `key`, a title, an optional rich description, an optional video, and at most one primary action (a URL, or the key of the next tutorial — that link is what makes a walkthrough). Keys must match `/\A[a-z0-9]+(?:[._-][a-z0-9]+)*\z/` — lowercase, digits, and `. _ -` as separators. `Billing Setup` and `billingSetup` are invalid; `billing_setup` and `billing.step-1` are fine. `status` is `draft` or `published`, and the key is unique **per locale**, which is how translations work: one row per language for the same key, with locale fallback at resolve time.
+
+### Video providers
+
+YouTube, Vimeo, Loom, Tella, Voomly, a direct MP4/WebM URL, or an uploaded file (needs Active Storage). Uploaded videos stream through the engine at `/product_tours/media/:id` — not a public blob URL. Do not build your own blob links.
+
+**The engine edits the app's Content Security Policy.** It appends the providers' embed hosts to `frame-src` (or to `default-src` when `frame-src` is unset) in an initializer that runs after the host's own. That is deliberate — an embed silently blocked by CSP is a bad first five minutes — but know it happens, and do not hand-add those `frame-src` entries yourself. If the app sets its CSP somewhere unusual (a middleware, a per-controller override), that is where a blocked embed will come from.
+
+### Lifecycle events
+
+Subscribe in an initializer; there is no callback config to set.
+
+```ruby
+ActiveSupport::Notifications.subscribe("product_tours.completed") do |*, payload|
+  # payload has the tutorial key and request context
+end
+```
+
+Names: `product_tours.viewed`, `product_tours.dismissed`, `product_tours.completed`, and `product_tours.unresolved_trigger` — the last one fires when a `data-product-tour` button names a key that does not resolve. Subscribe to it in development; it turns "my button does nothing" into a log line naming the key.
+
+### Do not
+
+- **Do not copy the widget JavaScript into `app/javascript`, or add a `<script>` tag for it.** `product_tours_tag` renders what is needed and the engine serves the code. There is no build step and nothing for esbuild/importmap/Tailwind to know about.
+- **Do not create or edit tutorials in code** (see above).
+- **Do not add provider hosts to `frame-src` by hand** — the engine already does it.
+- **Do not serve uploaded videos by blob URL** — the gated media route exists so a leaked signed URL cannot hand over your content.
+- **Do not install Active Storage or Action Text "to make it work"** unless the app actually wants uploads or rich text. Both are optional; the gem checks for them (`Post.video_upload_supported?`, `Post.description_supported?`) and simply offers less.
+
+### Configuration
+
+There are five options. That is the whole surface.
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `authorize_admin` | development only | **Who can read and edit tutorials. Set before deploying.** |
+| `enabled` | everyone | Per-request gate for the widget and its endpoints |
+| `admin_layout` | `product_tours/application` | Render the dashboard inside your admin shell |
+| `mount_path` | `"/product_tours"` | Keep in sync with `mount_product_tours at:` |
+| `storage_service` | app default | Active Storage service for uploaded video (a `storage.yml` key) |
+
+26 locales ship with the gem, RTL included.
+
+### Common failure modes
+
+| Symptom | Cause |
+| --- | --- |
+| The trigger button does nothing | No tutorial with that key, or it is still a draft, or `product_tours_tag` is missing from the layout. Subscribe to `product_tours.unresolved_trigger` to see which |
+| `/product_tours` returns 403 "Set ProductTours.config.authorize_admin to grant access" | Exactly what it says: still at the development-only default |
+| Key rejected on save | It must match `/\A[a-z0-9]+(?:[._-][a-z0-9]+)*\z/` — no capitals, no spaces |
+| Video area blank for an embed | CSP. The engine appends provider hosts to `frame-src`; a policy set outside `config.content_security_policy` will not have them |
+| No upload option on the form | Active Storage not installed |
+| No rich-text editor for the description | Action Text not installed |
+| Duplicate-key error when adding a translation | The key is unique per locale — add the translation from the tutorial page rather than creating a second record by hand |
+
+---
+
+## Working on the gem itself
+
+```bash
+bundle exec rake test            # minitest, dummy app under test/dummy
+bundle exec rubocop              # must be clean
+BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle exec rake test   # 7.1, 7.2, 8.0, 8.1 in gemfiles/
+```
+
+Layout: `app/` controllers, `Post`, dashboard views · `lib/product_tours/` config, widget JS, seeds, engine, CSP patch · `lib/generators/product_tours/install/` the one generator · `config/locales/` 26 locales · `test/` minitest with `test/dummy` as the host app.
+
+Conventions this codebase holds to — follow them rather than the first thing that works:
+
+- **Optional dependencies are checked, never assumed.** `has_rich_text` is declared only `if respond_to?`, `has_one_attached` only `if defined?(::ActiveStorage)`, and the model exposes `description_supported?` / `video_upload_supported?` so views can offer less instead of raising. An app with neither gem must boot and work.
+- **Triggers are explicit.** The gem never guesses at DOM nodes or auto-starts a tour; a host puts `data-product-tour="key"` where it wants it. A trigger naming a key that does not resolve is instrumented, not silently swallowed.
+- **The widget is plain JS served by the engine** — no build step, no framework, no CDN.
+- **Uploaded media streams through the engine's gate**, never a public blob URL.
+- **The CSP patch is additive.** It appends to existing sources and drops `'none'` rather than replacing a host's policy — do not let it start overwriting directives.
+- **The dummy app pins `config.active_job.queue_adapter = :test`.** Do not remove it or let it drift back to the `:async` default. Attaching a video enqueues Active Storage's analysis job, and `:async` runs it on a background thread that checks out its own connection — writes no test transaction covers, landing in the middle of whatever runs next. That is a suite that fails order-dependently in a test which never created a row, and it is miserable to trace back.
+- Every user-facing change bumps `lib/product_tours/version.rb` and adds a `CHANGELOG.md` entry (Keep a Changelog format) that says what it costs, not only what it adds.
+- Commit messages are prose that explains the tradeoff — read `git log` before writing one.

data/CHANGELOG.md

@@ -1,7 +1,57 @@
 # Changelog
 
+## 0.2.0
+
+- **`config.admin_layout` now works on its own.** The dashboard's stylesheet and
+  script were declared in the gem's layout, so replacing that layout dropped
+  both and the dashboard rendered unstyled with its client-side behaviour dead.
+  They move into the views, so every layout gets them with nothing asked of the
+  host.
+- **The dashboard stylesheet no longer claims selectors it does not own.** It
+  styled bare `*`, `html`, `body` and `a`, and its `.container`, `.card` and
+  `.tabs` are names other frameworks use too, so a host that did load it had its
+  own chrome restyled. Component rules now nest inside a `.pt-dashboard` wrapper
+  the views render, and every custom property is `--pt-` prefixed so it can
+  neither overwrite a host's nor be overwritten. The page-frame rules stay keyed
+  to the body classes only the gem's own layout sets.
+- **Added `config.base_controller_class`.** Name the controller your own admin
+  inherits from and the dashboard adopts its layout, helpers, authentication and
+  request context — the things `admin_layout` cannot give you. It reparents the
+  dashboard only; the widget, tour-resolution and media endpoints stay on the
+  engine's public controller, so it can never demand a staff session from a
+  visitor. Default is unchanged.
+- **Migrations follow the host's `primary_key_type`,** the same
+  `Rails.configuration.generators` lookup Rails' own Active Storage, Action Text
+  and Action Mailbox migrations do. A uuid-keyed app has a uuid
+  `active_storage_attachments.record_id`, so a bigint table here could never
+  hold a video: `attach` raised `NotNullViolation`. A host that set nothing gets
+  an identical migration to before.
+- **Dropped the `id: /\d+/` constraint on the media route,** which was what
+  forced the table to be bigint. It was never load-bearing: every fixed-name
+  route is declared first.
+- **Dropped the redundant `(locale)` index.** A B-tree serves any leftmost
+  prefix, so `(locale, key)` already covered it; it only cost write time and
+  disk. Existing installs keep theirs until they drop it:
+  `remove_index :product_tours_posts, :locale`.
+- A `BackboneTest` now fails the build on any of the above regressing.
+
 ## [Unreleased]
 
+## [0.1.2] - 2026-08-04
+
+- Added `AGENTS.md`: install and integration instructions written for coding
+  agents — that tutorials are content managed in the dashboard rather than
+  created from migrations, the key format, the request-shaped config lambdas,
+  that the engine appends provider hosts to the app's `frame-src`, and the
+  `product_tours.unresolved_trigger` notification that turns "my button does
+  nothing" into a log line. It ships inside the gem, so
+  `cat "$(bundle show product_tours)/AGENTS.md"` works from a host app.
+- The dummy app pins `queue_adapter = :test` for the test suite. Attaching a
+  video enqueues Active Storage's analysis job, and the default `:async` adapter
+  runs it on a background thread with its own database connection — writes no
+  test transaction covers, which is how a suite starts failing order-dependently
+  in a test that never created a row. No effect on the gem itself.
+
 ## [0.1.1] - 2026-08-04
 
 - Reworked the README into an installation-first, skimmable product guide that

data/README.md

@@ -54,6 +54,11 @@ small set of working tutorials so you can try the modal immediately.
 Ruby >= 3.2 · Rails >= 7.1 · Active Storage only for uploaded videos · Action
 Text only for rich descriptions.
 
+Installing with a coding agent? Point it at [AGENTS.md](AGENTS.md) — the same
+steps in the order an agent needs them, plus the gates it tends to get wrong and
+the things it should not do. It ships inside the gem, so
+`cat "$(bundle show product_tours)/AGENTS.md"` works from any app that bundles it.
+
 ## What you get
 
 | | |
@@ -221,7 +226,8 @@ Everything is optional — a development install works with zero config. In
 | --- | --- | --- |
 | `enabled` | everyone | Who can resolve and open published tutorials |
 | `authorize_admin` | development only | **Who can manage content at the mount path** |
-| `admin_layout` | gem layout | Render the dashboard inside your admin shell |
+| `base_controller_class` | `ActionController::Base` | Controller the dashboard inherits — name your admin's and it adopts its layout, helpers and auth |
+| `admin_layout` | gem layout | Just the shell, if you don't want the whole controller |
 | `storage_service` | app default | Named Active Storage service for uploaded videos |
 | `mount_path` | `/product_tours` | Keep in sync only when mounting the engine manually |
 

data/app/controllers/concerns/product_tours/request_context.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module ProductTours
+  # Who is asking, which locale they are in, and the gates that answer both.
+  #
+  # A concern rather than inherited behaviour because the engine has two
+  # controller roots: the public endpoints hang off ActionController::Base, and
+  # the dashboard hangs off whatever the host set as `base_controller_class`.
+  module RequestContext
+    extend ActiveSupport::Concern
+
+    private
+
+    def product_tours_admin_layout
+      ProductTours.config.admin_layout
+    end
+
+    def require_admin
+      return if ProductTours.admin?(request)
+
+      render plain: 'Forbidden. Set ProductTours.config.authorize_admin to grant access.', status: :forbidden
+    end
+
+    def current_product_tours_locale
+      requested_locale = params[:locale].to_s
+      return requested_locale if I18n.available_locales.map(&:to_s).include?(requested_locale)
+
+      ProductTours.locale(request)
+    end
+
+    def find_post_by_locale(scope, key)
+      locales = [current_product_tours_locale, I18n.default_locale.to_s].uniq
+      posts = scope.where(locale: locales, key: key).index_by(&:locale)
+      locales.filter_map { |locale| posts[locale] }.first
+    end
+
+    def clean_page_url(value)
+      uri = URI.parse(value.to_s)
+      return unless uri.is_a?(URI::HTTP) && uri.host.present?
+
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def unresolved_payload(key, reason)
+      {
+        key: key.to_s,
+        locale: current_product_tours_locale,
+        reason: reason.to_s,
+        page_url: clean_page_url(params[:page_url])
+      }
+    end
+
+    def handle_unresolved_trigger(key, reason)
+      payload = unresolved_payload(key, reason)
+      error = ProductTours::UnresolvedTriggerError.new(payload)
+      raise error if Rails.env.development? || Rails.env.test?
+
+      if defined?(Rails.error) && Rails.error.respond_to?(:report)
+        Rails.error.report(error, handled: true, context: payload)
+      else
+        Rails.logger.error("product_tours: #{error.message} #{payload.inspect}")
+      end
+      ActiveSupport::Notifications.instrument('product_tours.unresolved_trigger', payload)
+      render json: { error: 'unresolved_trigger', reason: reason.to_s }, status: :not_found
+    end
+  end
+end

data/app/controllers/product_tours/application_controller.rb

@@ -1,68 +1,16 @@
 # frozen_string_literal: true
 
-require 'uri'
-
 module ProductTours
+  # Root of the engine's PUBLIC surface: widget.js, tour resolution, signals and
+  # media. These stay on a plain ActionController::Base deliberately — a visitor
+  # loading a tour must not be routed through a host's admin controller, which
+  # would demand a staff session for the widget.
+  #
+  # The dashboard's root is DashboardController, and that is where
+  # `config.base_controller_class` applies.
   class ApplicationController < ActionController::Base
-    protect_from_forgery with: :exception
-
-    private
-
-    def product_tours_admin_layout
-      ProductTours.config.admin_layout
-    end
-
-    def require_admin
-      return if ProductTours.admin?(request)
-
-      render plain: 'Forbidden. Set ProductTours.config.authorize_admin to grant access.', status: :forbidden
-    end
-
-    def current_product_tours_locale
-      requested_locale = params[:locale].to_s
-      return requested_locale if I18n.available_locales.map(&:to_s).include?(requested_locale)
+    include RequestContext
 
-      ProductTours.locale(request)
-    end
-
-    def find_post_by_locale(scope, key)
-      locales = [current_product_tours_locale, I18n.default_locale.to_s].uniq
-      posts = scope.where(locale: locales, key: key).index_by(&:locale)
-      locales.filter_map { |locale| posts[locale] }.first
-    end
-
-    def clean_page_url(value)
-      uri = URI.parse(value.to_s)
-      return unless uri.is_a?(URI::HTTP) && uri.host.present?
-
-      uri.query = nil
-      uri.fragment = nil
-      uri.to_s
-    rescue URI::InvalidURIError
-      nil
-    end
-
-    def unresolved_payload(key, reason)
-      {
-        key: key.to_s,
-        locale: current_product_tours_locale,
-        reason: reason.to_s,
-        page_url: clean_page_url(params[:page_url])
-      }
-    end
-
-    def handle_unresolved_trigger(key, reason)
-      payload = unresolved_payload(key, reason)
-      error = ProductTours::UnresolvedTriggerError.new(payload)
-      raise error if Rails.env.development? || Rails.env.test?
-
-      if defined?(Rails.error) && Rails.error.respond_to?(:report)
-        Rails.error.report(error, handled: true, context: payload)
-      else
-        Rails.logger.error("product_tours: #{error.message} #{payload.inspect}")
-      end
-      ActiveSupport::Notifications.instrument('product_tours.unresolved_trigger', payload)
-      render json: { error: 'unresolved_trigger', reason: reason.to_s }, status: :not_found
-    end
+    protect_from_forgery with: :exception
   end
 end

data/app/controllers/product_tours/dashboard_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ProductTours
+  # Root of the STAFF surface: the post editor and its list.
+  #
+  # Inherits from `config.base_controller_class` — by default a plain
+  # ActionController::Base, which is why `authorize_admin` exists. Point it at
+  # the controller your own admin already inherits from and the dashboard picks
+  # up that stack wholesale: your layout, your helpers, your authentication, and
+  # whatever request context your before_actions establish. `config.admin_layout`
+  # only ever solved the first of those.
+  #
+  # Only the dashboard hangs off it. The widget's endpoints stay on
+  # ApplicationController, so wiring an admin base controller here can never
+  # demand a staff session from a visitor being shown a tour.
+  class DashboardController < ProductTours.base_controller
+    include RequestContext
+
+    # A host base controller brings its own layout, and declaring one here would
+    # override it. So the gem only claims the layout when it owns the decision:
+    # no host base controller, or a host that named an `admin_layout` explicitly.
+    layout :product_tours_admin_layout unless superclass != ActionController::Base &&
+                                              ProductTours.config.admin_layout ==
+                                              Configuration::DEFAULT_ADMIN_LAYOUT
+
+    before_action :require_admin
+
+    # A host base controller has configured CSRF already; declaring it twice
+    # would run the check twice.
+    protect_from_forgery with: :exception if superclass == ActionController::Base
+  end
+end

data/app/controllers/product_tours/posts_controller.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
 module ProductTours
-  class PostsController < ApplicationController
+  class PostsController < DashboardController
     PER_PAGE = 50
 
-    layout :product_tours_admin_layout
-    before_action :require_admin
     before_action :set_post,
                   only: %i[show edit update destroy refresh_video_metadata add_translation publish unpublish]
     before_action :load_linkable_posts, only: %i[new create edit update]

data/app/views/layouts/product_tours/application.html.erb

@@ -5,16 +5,17 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <%= csrf_meta_tags %>
   <%= csp_meta_tag %>
-  <%= stylesheet_link_tag "#{dashboard_stylesheet_path}?v=#{ProductTours::Widget.dashboard_stylesheet_fingerprint}",
-                          "data-turbo-track": "reload" %>
-  <%= javascript_include_tag "#{dashboard_script_path}?v=#{ProductTours::Widget.dashboard_fingerprint}",
-                             "data-turbo-track": "reload", defer: true, nonce: true %>
+  <%# The dashboard's stylesheet and script are declared by the views
+      (product_tours/shared/_dashboard), not here, so they survive a host
+      replacing this layout via config.admin_layout. %>
 </head>
-<body class="<%= content_for?(:body_class) ? yield(:body_class) : '' %>">
-  <div class="container">
-    <% if notice.present? %><div class="flash notice"><%= notice %></div><% end %>
-    <% if alert.present? %><div class="flash alert"><%= alert %></div><% end %>
-    <%= yield %>
+<body class="pt-page <%= content_for?(:body_class) ? yield(:body_class) : '' %>">
+  <div class="pt-dashboard">
+    <div class="container">
+      <% if notice.present? %><div class="flash notice"><%= notice %></div><% end %>
+      <% if alert.present? %><div class="flash alert"><%= alert %></div><% end %>
+      <%= yield %>
+    </div>
   </div>
 </body>
 </html>

data/app/views/product_tours/posts/edit.html.erb

@@ -1,5 +1,7 @@
 <% content_for :body_class, "pt-form-page" %>
 
-<div class="breadcrumb"><%= link_to t("product_tours.dashboard.title", default: "Product tours"), posts_path %> / <%= link_to @post.title, post_path(@post) %> / <%= t("product_tours.dashboard.edit", default: "Edit") %></div>
-<h1><%= t("product_tours.dashboard.edit_post", default: "Edit tutorial") %></h1>
-<%= render "form", post: @post %>
+<%= render layout: 'product_tours/shared/dashboard' do %>
+  <div class="breadcrumb"><%= link_to t("product_tours.dashboard.title", default: "Product tours"), posts_path %> / <%= link_to @post.title, post_path(@post) %> / <%= t("product_tours.dashboard.edit", default: "Edit") %></div>
+  <h1><%= t("product_tours.dashboard.edit_post", default: "Edit tutorial") %></h1>
+  <%= render "form", post: @post %>
+<% end %>