Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Update MCP plans and decisions
Damian Legawiec7cd9d9c73010
diff --git a/docs/plans/6.0-action-actors.md b/docs/plans/6.0-action-actors.mdindex 0a4a88b7b8..b03880c849 100644--- a/docs/plans/6.0-action-actors.md+++ b/docs/plans/6.0-action-actors.md@@ -1,10 +1,10 @@# Action Actors-**Status:** In Review (PR #14659) — the 6.0 cut is built: `Spree::Actor`, `acted_by`, `Spree.actor_classes`, the 8 order-operation associations, the migration and backfill, `current_actor` and the call-site sweep, serializer fields, dashboard labels and docs. 6.1 still owes the remaining 13 associations and the removal of the transitional reader.+**Status:** Implemented — merged to main 2026-09-16 (PR #14659): `Spree::Actor`, `acted_by`, `Spree.actor_classes`, the 8 order-operation associations, the migration and backfill, `current_actor` and the call-site sweep, serializer fields, dashboard labels and docs. Explicitly 6.1: the remaining 13 associations and removal of the transitional reader (Migration Path step 6).**Target:** Spree 6.0 — before `6.0-mcp-server.md`, which depends on it**Depends on:** `5.5-admin-api-key-scopes.md` (shipped — the API key is the second kind of actor), `6.0-service-workflows.md` (workflows already take the actor as a keyword), `6.0-platform-auth.md` (the admin user class the columns point at today)**Author:** Damian Legawiec (design driven with Claude)-**Last updated:** 2026-09-16+**Last updated:** 2026-09-16 (implemented)**Tracking:** Linear V-3646 · GitHub spree/spree#14658## Summary@@ -228,16 +228,16 @@ Event payloads carrying actor ids already use prefixed ids, so an## Migration Path-1. **Core:** `Spree::Actor`, `Spree::ActedBy`, `Spree.actor_classes`, the- macro applied to the 8 order-operation associations, the migration, the- backfill task,- model specs for the type validation and the transitional reader.-2. **API:** `current_actor`, the ten call-site changes, `<name>_type` on the- serializers, regenerated types and OpenAPI, controller specs asserting a- key-authenticated cancel records the key.-3. **Dashboard:** actor labels where actors are shown.-4. **Docs:** the 6.0 upgrade guide gains the backfill step; the Admin API- docs note that `*_id` actors may be keys and what `*_type` says.+1. **Core** — ✅ shipped (PR #14659): `Spree::Actor`, `Spree::ActedBy`,+ `Spree.actor_classes`, the macro applied to the 8 order-operation+ associations, the migration, the backfill task, model specs for the type+ validation and the transitional reader.+2. **API** — ✅ shipped: `current_actor`, the call-site changes, `<name>_type`+ on the serializers, regenerated types and OpenAPI, controller specs+ asserting a key-authenticated cancel records the key.+3. **Dashboard** — ✅ shipped: actor labels where actors are shown.+4. **Docs** — ✅ shipped: the 6.0 upgrade guide gains the backfill step; the+ Admin API docs note that `*_id` actors may be keys and what `*_type` says.5. `6.0-mcp-server.md` then injects `context.actor` (user or key) intoworkflow principal parameters with no further change.6. **6.1:** the macro on the remaining 13 associations, one migration, thediff --git a/docs/plans/6.0-mcp-server.md b/docs/plans/6.0-mcp-server.mdindex 83c0c9273e..0483c37a3d 100644--- a/docs/plans/6.0-mcp-server.md+++ b/docs/plans/6.0-mcp-server.md@@ -2,7 +2,7 @@**Status:** Draft — design finalized 2026-09-16, nothing built**Target:** Spree 6.0-**Depends on:** `6.0-action-actors.md` (ships first — the API key becomes a valid actor, so a workflow run over MCP records who did it), `5.5-admin-api-cli.md` (shipped — the CLI-first precondition this plan waited on), `5.5-admin-api-key-scopes.md` (shipped — secret keys + scopes are the credential), `6.0-admin-rbac.md` (the permission catalog gates every tool), `6.0-analytics-semantic-layer.md` (the reporting registry feeds the reporting tools), `6.0-service-workflows.md` (writes execute through workflows), `6.0-dashboard-assistant.md` (moves onto the registry defined here)+**Depends on:** `6.0-action-actors.md` (shipped 2026-09-16 — the API key is a valid actor, so a workflow run over MCP records who did it), `5.5-admin-api-cli.md` (shipped — the CLI-first precondition this plan waited on), `5.5-admin-api-key-scopes.md` (shipped — secret keys + scopes are the credential), `6.0-admin-rbac.md` (the permission catalog gates every tool), `6.0-analytics-semantic-layer.md` (the reporting registry feeds the reporting tools), `6.0-service-workflows.md` (writes execute through workflows), `6.0-dashboard-assistant.md` (moves onto the registry defined here)**Author:** Damian Legawiec (design driven with Claude)**Last updated:** 2026-09-16**Tracking:** Linear V-3645 · GitHub spree/spree#14656@@ -540,8 +540,8 @@ gem, so `pnpm test:changed` picks its specs up.## Migration Path-0. **`6.0-action-actors.md` lands first** (schema change; the context's- `actor` and the injection rule below rely on it).+0. **`6.0-action-actors.md` lands first** — ✅ merged 2026-09-16 (PR #14659);+ `current_actor` and the polymorphic order-operation actors are on main.1. **Registry into core** (`spree_core`): move the tool base class, registry,context, resource map and record summary from the assistant branch, renamedas above, with the principal abstraction. Derive the resource map from thediff --git a/docs/plans/6.0-telemetry-and-update-check.md b/docs/plans/6.0-telemetry-and-update-check.mdnew file mode 100644index 0000000000..57c9e95597--- /dev/null+++ b/docs/plans/6.0-telemetry-and-update-check.md@@ -0,0 +1,319 @@+# Telemetry and Update Check++**Status:** Design finalized — nothing built yet+**Target:** Spree 6.0+**Depends on:** `6.0-admin-spa.md` (the banner lives in the dashboard shell), `6.0-beta-release.md` (one version line per surface)+**Author:** Damian Legawiec (design driven with Claude)+**Last updated:** 2026-09-16+**Tracking:** Linear V-3650 · GitHub spree/spree#14660++## Summary++Spree 5.x told admins when a newer release existed: `Spree::Admin::Updater`+asked spreecloud.io once a day, and the Rails admin showed a banner. That+class left with the `spree_admin` engine, and nothing in 6.0 replaces it —+the Admin API, the React dashboard and the CLI neither check for updates nor+report anything about the installations they run on. This plan brings the+update check back as an Admin API endpoint the dashboard renders a banner+from, and turns the same daily request into an anonymous usage heartbeat+(which Spree gems and versions are in use, on what stack, at what rough+size). A second, independent channel reports CLI command usage from+`@spree/cli` and `create-spree-app`, the way Mercur, Next.js and Gatsby do.+Both channels honour one opt-out, send nothing that identifies a person, and+are documented field by field.++The spreecloud.io backend is ours. It keeps answering the 5.x query string+unchanged and grows to store the new fields, so a 5.6 install and a 6.0+install can hit the same endpoint.++## Key Decisions (do not deviate without discussion)++- **The update check is the heartbeat.** One daily request per installation+ carries the running version and the usage fields, and its response is the+ list of newer releases. There is no separate "phone home" from the server.+ Rationale: 5.x already worked this way (version, environment, storefront+ URL and `install_id` on the query string), so the backend and the privacy+ story already exist; a second channel would double the surface to document+ and to opt out of.+- **The four 5.x query keys are frozen: `version`, `environment`, `url`,+ `install_id`.** New fields are added beside them, never renamed, so+ payloads from 5.x installs keep working against the same backend+ (2026-09-16, backend owner).+- **The check runs server-side and never inside an admin request.** The+ Admin API endpoint reads a cached result; a cache miss enqueues+ `Spree::UpdateCheckJob` and answers "not checked yet". The 5.x class did+ the HTTP call inline with one-second timeouts, which made the first admin+ page after cache expiry hang for up to two seconds on every worker.+- **The Spree version reaches only signed-in admins who can manage the+ store.** The Admin API deliberately does not expose the running version+ anywhere else (see `Admin::ImportsController#example`: it would fingerprint+ deployments for anyone matching CVEs). The endpoint is JWT-only — a secret+ API key gets a 404, like `GET /admin/me` — and requires `manage` on the+ store, matching the 5.x `can?(:manage, current_store)` gate.+- **The dashboard owns the banner, `dashboard-core` owns the hook.** The+ seller panel mounts the same `AppShell` but has no updates endpoint, so the+ banner is passed into the shell by the dashboard, never rendered by the+ shell itself.+- **Two switches, both environment variables, both honoured by Rails and+ the CLI.** `SPREE_TELEMETRY_DISABLED=1` (or the cross-tool+ `DO_NOT_TRACK=1`) strips the heartbeat down to `version` alone and turns+ CLI events off; `SPREE_UPDATE_CHECK_DISABLED=1` stops the daily request+ entirely and hides the banner. An operator who wants to know about+ releases but share nothing has a way to say so. The Ruby equivalents are+ `Spree::Config.telemetry_enabled` and `Spree::Config.update_check_enabled`.+- **Nothing that identifies a person.** No emails, no admin names, no IP+ retention beyond the request log, no store names, no product or order+ counts — only order-of-magnitude buckets. The CLI hashes the git remote+ for its project id and never sends error messages, only exit codes.+- **On by default, for both channels (2026-09-16).** The heartbeat and the+ CLI events run unless the operator opts out, as the 5.x updater did and as+ Mercur, Next.js and Gatsby do. Accepted trade-off: some operators object+ to any default reporting, so the opt-out has to be one line, documented+ on the deployment pages and printed by the CLI on first run — this is not+ optional polish.+- **Stack fields plus size buckets, never exact counts (2026-09-16).** The+ heartbeat carries Ruby, Rails, database, installed Spree gems, whether a+ dashboard is mounted, and order-of-magnitude buckets for stores, products,+ completed orders and sellers. Exact counts were rejected: paired with the+ storefront URL they are business data and hard to defend under GDPR+ questions from enterprise buyers. Stack-only was rejected because it+ cannot tell a hobby install from a large merchant.+- **A dedicated `GET /api/v3/admin/updates` (2026-09-16).** Folding the+ status into `GET /admin/me` was rejected: `/me` is fetched by every admin,+ so the version would reach admins who cannot manage the store, and the+ seller panel's `/me` would have to diverge. Accepted trade-off: one more+ request on dashboard boot, cached for an hour.+- **Both `@spree/cli` and `create-spree-app` send events (2026-09-16).**+ The scaffold-to-first-`spree dev` funnel is where new users are lost, and+ `create-spree-app` failures are invisible otherwise. Accepted trade-off:+ the telemetry module is copied into `create-spree-app`, which deliberately+ has no dependency on `@spree/cli`; the two copies must stay identical and+ a Vitest fixture shared through the workspace asserts it.+- **Mobile-app and headless installs count.** The heartbeat runs from Rails+ whether or not a dashboard is mounted, so an installation with no admin UI+ still reports and still gets the release list (readable through the API).++## Design Details++### Server heartbeat (`spree_core`)++`Spree::UpdateCheck` replaces `Spree::Admin::Updater`. It lives in+`spree/core/app/services/spree/update_check.rb` and keeps the 5.x public+shape:++```ruby+Spree::UpdateCheck.update_available? # => true+Spree::UpdateCheck.latest_release # => { "tag_name" => "v6.0.1", "url" => ..., "published_at" => ... }+Spree::UpdateCheck.newer_releases # newest first, [] when unknown or disabled+Spree::UpdateCheck.checked_at # Time or nil+Spree::UpdateCheck.enabled? # false under SPREE_UPDATE_CHECK_DISABLED+```++The result is cached under `spree/update_check/<version>` for one day.+Reads never perform HTTP. `Spree::UpdateCheck.refresh` does the request+(1 s open, 2 s read timeouts) and writes the cache; a failure caches an empty+list with `checked_at` so an unreachable endpoint costs one timed-out request+per day. `Spree::UpdateCheckJob` calls `refresh` and is enqueued by the+endpoint on a cache miss and by `Spree::UpdateCheck.enqueue_if_stale`, which+the engine calls once per boot in production (`after_initialize`, guarded so+console and rake processes do not enqueue).++The request stays a `GET https://spreecloud.io/updates.json` with a query+string. Legacy keys are sent exactly as 5.x sent them; new keys sit beside+them:++| Key | 5.x | 6.0 | Value |+| --- | --- | --- | --- |+| `version` | ✓ | ✓ | `Spree.version` |+| `environment` | ✓ | ✓ | `Rails.env` |+| `url` | ✓ | ✓ | default store's storefront URL, as 5.x |+| `install_id` | ✓ | ✓ | `Spree.install_id` (UUID, already in core) |+| `ruby` | | new | `RUBY_VERSION` |+| `rails` | | new | `Rails.version` |+| `database` | | new | adapter name (`postgresql`, `mysql2`, `sqlite3`) |+| `gems` | | new | comma-separated installed Spree gems (`spree_api,spree_emails,spree_stripe,…`), from `Gem.loaded_specs` |+| `dashboard` | | new | `true` when `spree_dashboard` serves a built dashboard |+| `stores` | | new | store count bucket |+| `products` | | new | product count bucket |+| `orders` | | new | completed-order count bucket |+| `sellers` | | new | seller count bucket, absent when marketplace is off |++Buckets are `0`, `1-9`, `10-99`, `100-999`, `1k-9k`, `10k-99k`, `100k+`,+computed with `count` on the base scope (no per-store loop). With telemetry+disabled the query string is `version` only — no `install_id`, so the backend+answers the request and stores nothing.++`Spree::Config` gains two preferences with defaults `true`:+`telemetry_enabled` and `update_check_enabled`. The env variables are read by+`Spree::UpdateCheck` itself and cast as booleans — the `env:` option on+`preference` returns the raw string, so `SPREE_TELEMETRY_DISABLED=false`+would otherwise read as truthy. `DO_NOT_TRACK=1` counts as telemetry+disabled, as it does for Homebrew, Gatsby and Next.js.++### Admin API++`GET /api/v3/admin/updates` on `Spree::Api::V3::Admin::UpdatesController`+(a singleton resource; `skip_scope_check!`, JWT only, `authorize! :manage,+current_store`):++```json+{+ "current_version": "6.0.0",+ "update_available": true,+ "latest_release": { "version": "6.0.1", "url": "https://github.com/spree/spree/releases/tag/v6.0.1", "published_at": "2026-10-02T10:51:38Z" },+ "checked_at": "2026-10-03T04:00:00Z",+ "enabled": true+}+```++`checked_at: null` means the job has been enqueued and the client should not+show anything. `enabled: false` (update check switched off) tells the+dashboard to render nothing without polling again. The response is a plain+`Spree::UpdateStatus` value object (`ActiveModel::Model` ++`ActiveModel::Attributes`) rendered by `Admin::UpdateStatusSerializer`, so+Typelizer emits `AdminUpdateStatus` and `@spree/admin-sdk` gets+`adminClient.updates.show()`. An rswag integration spec documents it and+stubs the outbound request.++### Dashboard banner++- `useUpdateStatus()` in `@spree/dashboard-core/hooks` wraps+ `adminClient.updates.show()`, store-scoped query key, `staleTime` of one+ hour, no refetch on focus, disabled unless the current user has `manage`+ on the store (permission keys from `/me`).+- `<UpdateNotice>` in `@spree/dashboard/components/spree/` renders an+ `Alert` above the page content with the two versions, a link to the+ release notes and a dismiss button. Dismissal is per browser and per+ release (`localStorage["spree-update-dismissed"] = "v6.0.1"`), so the+ banner comes back for the next release and never for the same one. The+ 5.x seven-day session dismissal is gone; per-release is what merchants+ asked for.+- `AppShell` gains a `banner?: ReactNode` prop rendered between the mobile+ top bar and the page. The dashboard passes `<UpdateNotice />`; the seller+ panel passes nothing.+- Copy in every locale (`admin.updates.available`, `admin.updates.dismiss`,+ `admin.updates.release_notes`).++Dashboard package versions are not compared in 6.0: the npm surface has its+own 1.x line, and the release list is the gem list. A later release can add+`dashboard_version` to the endpoint response and compare it against the+build-time `@spree/dashboard` version.++### CLI events (`@spree/cli`, `create-spree-app`)++A small shared module (`packages/cli/src/telemetry.ts`, copied verbatim into+`create-spree-app` since that package deliberately has no `@spree/cli`+dependency) sends one `POST https://spreecloud.io/cli-events` per command as+JSON:++```json+{+ "event": "command",+ "command": "dev",+ "status": "ok",+ "exit_code": 0,+ "duration_ms": 8421,+ "cli": "@spree/cli",+ "cli_version": "1.0.0-beta.2",+ "node_version": "24.4.0",+ "package_manager": "pnpm",+ "os": "darwin",+ "arch": "arm64",+ "ci": false,+ "docker": false,+ "machine_id": "3f1c…",+ "project_id": "sha256(git remote url) | null"+}+```++`create-spree-app` sends `event: "create"` with `status` and the chosen+options (`storefront: true`, `package_manager`, `start: true`) and nothing+typed by the person. `machine_id` is a UUID generated once into+`~/.config/spree/config.json`; `project_id` is the SHA-256 of the first git+remote URL, or null outside a repository.++Delivery never blocks or fails a command: `fetch` with a 1.5 s abort+signal, errors swallowed, awaited only at process exit. The first run prints+a one-paragraph notice (what is sent, the docs link, how to opt out) and+records that it was shown, the way Next.js does. `spree telemetry status`,+`spree telemetry disable` and `spree telemetry enable` write+`telemetry: false` into the same config file; `SPREE_TELEMETRY_DISABLED=1`+and `DO_NOT_TRACK=1` win over the file. No CLI event is sent under `CI=true`+either — those runs are not people.++### spreecloud.io (outside this repository)++- `GET /updates.json` keeps its contract: the four 5.x keys, the same+ response array. It stores the new keys when present.+- `POST /cli-events` is new, accepts the JSON above, rejects anything over+ 4 KB.+- The receiving side is designed in the spree_cloud repository,+ `docs/plans/spree-6.0-telemetry.md`: column list, allowlists, rate limits,+ retention and dashboard cards.++### Documentation++- New page `docs/developer/deployment/usage-data.mdx` ("Update checks and+ usage data"): both channels, every field, both switches, what is never+ sent. The old `/developer/deployment/telemetry` path redirects to the+ OpenTelemetry page and stays that way, so this page must not reuse it.+- `docs/developer/cli/` links to the page from the command reference and+ documents `spree telemetry`.+- Upgrade guide entry: `Spree::Admin::Updater` → `Spree::UpdateCheck`,+ `Spree::Admin::RuntimeConfig.admin_updater_enabled` →+ `SPREE_UPDATE_CHECK_DISABLED` / `Spree::Config.update_check_enabled`.++## Migration Path++1. **Core.** `Spree::UpdateCheck`, `Spree::UpdateCheckJob`, the two+ `Spree::Config` preferences, payload buckets, boot-time+ `enqueue_if_stale`. Specs stub the request with WebMock (already in the+ core lock file) and cover: legacy keys unchanged, reduced payload under+ the opt-out, no request under the update-check switch, failure cached+ with `checked_at`.+2. **Admin API.** `UpdatesController`, `Spree::UpdateStatus`, serializer,+ route, controller spec (JWT admin with manage → 200, secret key → 404,+ admin without manage → 403), rswag spec, Typelizer + Zod + OpenAPI+ regeneration, `adminClient.updates` in `@spree/admin-sdk`.+3. **Dashboard.** `useUpdateStatus`, `<UpdateNotice>`, `AppShell` `banner`+ prop, locale keys in all six languages, one Playwright spec that seeds+ the cache with a newer release and asserts the banner and its dismissal.+4. **CLI.** `telemetry.ts` in both packages, the command wrapper that times+ and reports every registered command, `spree telemetry` subcommand,+ first-run notice, Vitest coverage for the opt-out precedence and the+ payload shape.+5. **Docs and backend.** The usage-data page, CLI reference, upgrade guide+ entry; spreecloud.io stores the new keys and gains `POST /cli-events`+ before the 6.0 release so the first 6.0 installs are not dropped on the+ floor.++## Constraints on Current Work++- Do not add a version, gem list or environment field to any Admin API+ serializer or `/me` response; the updates endpoint is the only place the+ running version is exposed, and only to admins who can manage the store.+- Do not rename or drop the four 5.x query keys on the heartbeat, and do not+ send a new key that identifies a person or a store by name.+- A new outbound call from core follows the same shape: cached, run from a+ job, short timeouts, failure cached — never inline in a request.+- An env-backed boolean read through `Spree::Config` must be cast; the+ `env:` option on `preference` returns the raw string.+- The `AppShell` `banner` slot is the only place a cross-page notice goes;+ do not hang another banner off the sidebar or a route layout.++## Open Questions++None left. The four questions the draft raised (default posture, payload+richness, endpoint shape, CLI scope) were settled on 2026-09-16 and moved to+Key Decisions.++## References++- 5.6.1 `Spree::Admin::Updater`:+ https://github.com/spree/spree/blob/v5.6.1/spree/admin/app/models/spree/admin/updater.rb+- Mercur telemetry page (the model for the CLI channel):+ https://docs.mercurjs.com/telemetry+- `Spree.install_id` in `spree/core/lib/spree/core.rb`+- `docs/plans/6.0-opentelemetry.md` — tracing, a different kind of+ telemetry; this plan does not touch it+- `docs/plans/6.0-beta-release.md` — version lines per surfacediff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex a79b709c35..5b25d92f9c 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -5642,6 +5642,7 @@ ownership associations that gate visibility (`Import#user`, `Export#user`,not `try_spree_current_user`, for actor keywords. Workflow principalparameters stay `[Object, nil]` and are assigned, not inspected.+<<<<<<< Updated upstream**Amended the same day, at implementation.** Three points the design leftopen. An expanded actor serializes as `{ id, type, label }` through a new`ActorSerializer`, not through the admin user serializer — the order@@ -5655,3 +5656,34 @@ file alone, which left a 500 waiting for the first key-creates-key call.and overridden in `AdminAuthentication` to prefer `current_api_key`, becausethe post-sale concerns are shared with the JWT-only seller panel while apublishable Store API key must never become an actor.+=======++## 2026-09-16 — Update checks and usage telemetry are one daily heartbeat, on by default++Plan: `6.0-telemetry-and-update-check.md`.++The 5.x update banner went with the `spree_admin` engine, and 6.0 had no+replacement and no usage reporting from servers or the CLI.++**Decision.** `Spree::UpdateCheck` in core asks spreecloud.io once a day+from a job, never inline in a request, and the same request is the usage+heartbeat: the four 5.x query keys (`version`, `environment`, `url`,+`install_id`) stay frozen, and stack fields plus order-of-magnitude size+buckets sit beside them. The dashboard reads `GET /api/v3/admin/updates`+(JWT admins with `manage` on the store only; secret keys get 404) and shows+a banner through an `AppShell` `banner` slot the seller panel leaves empty.+`@spree/cli` and `create-spree-app` send one event per command. Both+channels are on by default; `SPREE_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`+reduces the heartbeat to `version` and silences the CLI,+`SPREE_UPDATE_CHECK_DISABLED=1` stops the request entirely. Rejected: exact+counts (business data next to a store URL), folding the status into `/me`+(reaches admins who cannot manage the store), opt-in by default (no banner+for most installs, 5.x regression).++**Consequences for other work.** The running Spree version, gem list or+environment must not appear in any other Admin API response. A new outbound+call from core is cached, run from a job, short-timeout, failure-cached.+Env-backed booleans read through `Spree::Config` must be cast: the `env:`+option on `preference` returns the raw string. Cross-page notices go through+the `AppShell` `banner` slot, nowhere else.+>>>>>>> Stashed changes