Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Plan the configurator CLI

Damian Legawiec97adb8bc106d
diff --git a/docs/plans/6.0-cli-configurator.md b/docs/plans/6.0-cli-configurator.md
new file mode 100644
index 0000000000..70377f4075
--- /dev/null
+++ b/docs/plans/6.0-cli-configurator.md
@@ -0,0 +1,249 @@
+# Spree CLI configurator: declarative store configuration
+
+**Status:** Design finalized — nothing built; open questions settled 2026-09-14
+**Target:** Spree 6.0
+**Depends on:** `5.5-admin-api-cli.md` (credential resolution, Admin SDK transport), `6.0-admin-api.md` (conventions, natural-key filters), `6.0-store-context-and-first-run-setup.md` (what bootstrap owns), `5.6-admin-spa-csv-import.md` (natural-key upsert precedent)
+**Author:** Damian Legawiec (`[email protected]`)
+**Last updated:** 2026-09-14
+**Tracking:** Linear V-3633 · GitHub spree/spree#14641
+
+## Summary
+
+Add a command group to `@spree/cli` that treats a YAML file as the desired configuration of a store and reconciles a live instance against it through the Admin API: `diff` shows what would change, `deploy` applies it, `introspect` writes the live configuration back out as YAML. Records are matched on natural keys (slug, code, SKU, name), never on prefixed IDs, so the same file provisions a fresh local project, a staging environment and a hosted production store. Today the only way to shape an environment is Ruby: `db:seed`, `spree:load_sample_data`, and sixty lines of Ruby embedded as strings in the dashboard's Playwright global setup. A declarative file is reviewable in a pull request, runs from CI against any instance, and needs no Ruby on the caller's machine, which matters because the default install is an API-only Docker app and headless teams often never open the Rails side. Every project scaffolded by `create-spree-app` ships a `spree.config.yml` describing the store, its default channel and its default market, and `spree init` deploys it during setup. The dashboard e2e suite is the first consumer, so the tool is exercised on every CI run before a single spec starts.
+
+## Key Decisions (do not deviate without discussion)
+
+- **Built on the Admin API, run from the CLI, never in-process Ruby.** An in-process `rake spree:config:apply` would be faster and could call workflows directly, but it only works where you can run Rails, cannot target a hosted instance, and would not exercise the API. The whole point is a file that works from outside the app. The existing `spree api` transport (credential layers, `@spree/admin-sdk`, retries, idempotency keys, `X-Spree-Store-Id`) is reused unchanged.
+- **YAML is the canonical format; JSON is accepted for free.** YAML carries comments and block text and diffs cleanly, which a hand-edited, reviewed file needs. YAML is a superset of JSON, so a generated file may be JSON with no second code path. The CLI already depends on the `yaml` package. No `spree.config.ts` with a `defineConfig()` helper: that reintroduces configuration as code that needs a runtime, which is what this removes. Teams that want loops generate YAML and commit the output.
+- **A published JSON Schema makes the file self-describing.** Every section is validated with Zod before any network call, and the same schemas emit a JSON Schema shipped with the CLI. `introspect` writes a `# yaml-language-server: $schema=` header so editors autocomplete and flag mistakes inline.
+- **Records match on natural keys, never prefixed IDs.** IDs differ per environment; a slug or code does not. References between records (a product's category, a delivery method's zone) are written as the target's natural key and resolved by the CLI. The key table below is part of the contract; a resource without a stable, unique, human-readable key cannot be managed until it gets one.
+- **Bootstrap stays in Ruby seeds; the configurator starts after it.** The store row, the immutable admin role, the first admin user and the first API key have no API by design (`6.0-store-context-and-first-run-setup.md`), and a Rails app must seed without Node. `Spree::Seeds::All` does not shrink. The configurator assumes a bootstrapped store and a secret key with write scopes, which `spree init` and the e2e global setup already provide.
+- **Reconciliation is client-side in the first release.** For each section the CLI lists live records filtered on the natural key, then creates, updates or skips. This needs no new endpoints beyond gaps the key audit finds (a missing Ransack allowlist entry, a missing key attribute). Server-side bulk upserts by natural key are a later optimisation for hot sections, added to the API only once the client-side path shows where they pay off. `prices/bulk_upsert` and `stock_levels/bulk_upsert` are used where they already exist.
+- **Transaction data is out of scope permanently.** Orders, payments, fulfillments, returns, seller payouts and transfers are history, not configuration. They stay in Ruby sample data and in the e2e Ruby bootstrap. Customers are the one exception (see Design Details): they are reference data for promotions and groups, the CSV import already upserts them on email, and the e2e suite needs one.
+- **The engine is a library first and a command second, and it lives in `@spree/cli` (decided 2026-09-14).** The reconciliation code sits under `packages/cli/src/config/` and is exported as `@spree/cli/config`; the commands in `packages/cli/src/commands/config.ts` are a thin layer over it. The dashboard e2e global setup imports the library rather than shelling out to `spree`, so the suite does not depend on a built CLI binary. A separate `@spree/configurator` package was rejected for now as one more package to version and release for a single consumer; putting it in `@spree/admin-sdk` was rejected because the SDK stays a thin client and must not pull `yaml` and `zod` into every consumer's bundle. Accepted trade-off: the dashboard e2e suite gains a workspace dependency on `@spree/cli`. If a third consumer appears, split the engine out then.
+- **Deletes are opt-in per section (decided 2026-09-14).** `deploy` only creates and updates; live records missing from the file are deleted only in sections named in `--prune <sections>`, and `--fail-on-delete` refuses any plan containing a delete. Full sync with a guard flag, as Saleor does, was rejected because a file that declares only delivery zones would then wipe every other section unless the operator remembered the flag. Accepted trade-off: a stale record can linger in staging unnoticed; `diff` reports live records absent from the file as "not managed" so they are visible.
+- **The first release covers configuration, catalog and customers (decided 2026-09-14).** Products with variants, prices and stock, and customers, are in scope from the start, because the dashboard e2e bootstrap needs them and dogfooding without them is theatre. Configuration-only was rejected as leaving most of the Ruby bootstrap in place. Accepted trade-off: products are the largest section and most of the implementation effort.
+- **Every new project ships with a config file, and project setup deploys it (decided 2026-09-14).** `create-spree-app` writes `spree.config.yml` at the project root with the store, its default channel and its default market filled in from the answers given at scaffold time, plus commented skeletons of the other sections. `spree init` runs `spree config deploy` against it right after seeding, non-interactively, so a fresh project's shape is in a file from day one and the same file is what CI later deploys to staging. Deploy needs write scopes, and the project's auto-minted key is `read_all` by design (`5.5-admin-api-cli.md`), so `spree init` mints a short-lived secret key with the scopes the file needs, deploys, and revokes it. Accepted trade-off: project setup now has an HTTP step against the freshly booted container and fails loudly if the API is not up, where before it only ran rake tasks.
+- **The command noun is `config` (decided 2026-09-14).** `spree config validate | diff | deploy | introspect`, beside `spree api` and `spree auth`. Top-level verbs were rejected because `spree deploy` next to `spree dev`, `spree build` and `spree init` reads as deploying the application; `spree store` was rejected because it names one section of the file.
+
+## Design Details
+
+### Command surface
+
+```bash
+spree config diff --config store.yml # dry run, exit 0 when nothing would change
+spree config deploy --config store.yml # diff, confirm, apply; non-TTY skips the prompt
+spree config deploy --config store.yml --prune products,categories # allow deletes in these sections
+spree config deploy --config store.yml --fail-on-delete # CI guard: refuse if the plan contains any delete
+spree config introspect --out store.yml --include channels,delivery # live instance to YAML
+spree config validate --config store.yml # schema check only, no network
+```
+
+Credentials resolve exactly as for `spree api` (flags, then env, then project auto-mint, then profiles). A deploy needs write scopes for every section present in the file; the plan step checks the key's scopes first and names the missing ones with the `spree api-key create --scopes ...` remediation, before touching anything.
+
+### File format
+
+```yaml
+# yaml-language-server: $schema=https://spreecommerce.org/schemas/config/6.0.json
+version: 1
+
+store:
+ name: Acme Wholesale
+ default_currency: USD
+ supported_currencies: [USD, EUR]
+
+channels:
+ - code: retail
+ name: Retail
+ - code: wholesale
+ name: Wholesale
+ customer_groups: [wholesale]
+
+customer_groups:
+ - name: Wholesale
+
+tax_categories:
+ - name: Default
+ default: true
+ - name: Non-taxable
+
+delivery_zones:
+ - name: Europe
+ countries: [DE, FR, NL, PL]
+
+delivery_methods:
+ - name: Standard EU
+ delivery_zone: Europe
+ calculator:
+ type: flat_rate
+ preferences: { amount: 9.90, currency: EUR }
+
+product_types:
+ - name: Apparel
+ option_types: [size, color]
+
+option_types:
+ - name: size
+ label: Size
+ values: [S, M, L, XL]
+ - name: color
+ label: Color
+ values: [Red, Blue, Black]
+
+categories:
+ - permalink: clothing
+ name: Clothing
+ children:
+ - permalink: clothing/t-shirts
+ name: T-Shirts
+
+products:
+ - slug: classic-tee
+ name: Classic Tee
+ product_type: Apparel
+ categories: [clothing/t-shirts]
+ channels: [retail, wholesale]
+ status: active
+ variants:
+ - sku: TEE-S-RED
+ options: { size: S, color: Red }
+ prices: { USD: 29.99, EUR: 27.90 }
+ stock: { Warehouse: 100 }
+```
+
+Only sections present in the file are reconciled. A file with just `delivery_zones` and `delivery_methods` touches nothing else. Inside a present section, records absent from the file are left alone unless that section is listed in `--prune`.
+
+### Natural keys
+
+| Section | Key | Notes |
+|---|---|---|
+| `store` | singleton | update only; the row is bootstrap |
+| `channels` | `code` | unique per store today |
+| `markets` | `name` | unique per store today; a `code` column would be better and is part of the audit |
+| `customer_groups` | `name` | unique per store (soft-delete aware) |
+| `tax_categories`, `tax_rates` | `name` | |
+| `delivery_zones`, `delivery_profiles`, `delivery_methods` | `name` | |
+| `payment_methods` | `name` | credentials are never written from the file; see Secrets below |
+| `stock_locations` | `name` | |
+| `product_types` | `name` | unique per store, case-insensitive |
+| `option_types` | `name` | values keyed on `name` within the type |
+| `categories` | `permalink` | full path, so nesting is implied |
+| `collections` | `permalink` | |
+| `products` | `slug` | same key the CSV import uses |
+| `variants` | `sku` | nested under the product; same key the CSV import uses |
+| `prices` | `(sku, currency)` | via `prices/bulk_upsert` |
+| `stock_levels` | `(sku, stock location)` | via `stock_levels/bulk_upsert` |
+| `price_lists` | `name` | rows keyed on `sku` |
+| `custom_field_definitions` | `(resource_type, namespace, key)` | |
+| `roles` | `name` | the immutable admin role is skipped |
+| `customers` | `email` | same key the CSV import uses |
+| `allowed_origins` | `origin` | |
+| `webhook_endpoints` | `url` | |
+| `api_keys` | `name` | create only; the token is printed once and never written back |
+| `integrations` | `type` | one per store per type by validation |
+| `commission_rates` | `code` | |
+| `seller_requirements` | `type` (or `name` for multi types) | |
+| `return_reasons`, `claim_reasons`, `refund_reasons`, `order_cancellation_reasons` | `name` | |
+| `sellers` | `slug` | |
+
+Where a key is not yet unique in the database, the audit adds the index and validation as part of this plan rather than letting the configurator pick the first match. Every key column must also be on the model's Ransack allowlist, since the client-side plan step filters on it.
+
+### Reconciliation
+
+1. **Load and validate.** Parse YAML, validate against the section schemas, resolve every reference to a key that exists either in the file or on the live instance. A dangling reference fails here, with the YAML path, before any write.
+2. **Plan.** For each present section, in dependency order, list live records filtered on the natural key and classify every file entry as create, update or unchanged. Update compares only the attributes the file sets. Live records not in the file become deletes only when the section is in `--prune`.
+3. **Show the diff.** Grouped by section, one line per record, attribute-level detail for updates. Machine-readable with `--format json` so CI can post it.
+4. **Confirm and apply.** Interactive TTY asks once; non-TTY proceeds unless `--fail-on-delete` trips. Writes go through the Admin SDK with idempotency keys, sequentially across sections and in small parallel batches within a section. A 422 is reported against the YAML path of the offending entry with the API's own messages, and the run continues with the remaining entries so one bad row does not hide the rest.
+5. **Report.** Counts per section and per outcome; non-zero exit if anything failed.
+
+Section order follows the reference graph: store, channels, customer groups, tax, delivery zones and profiles, delivery methods, payment methods, stock locations, option types, product types, categories, collections, products (with variants, prices, stock), price lists, custom field definitions, roles, customers, origins, webhooks, integrations, marketplace sections, api keys. Prune runs in reverse order.
+
+### Introspect
+
+Reads every list endpoint of the requested sections, strips IDs, timestamps and computed fields, writes references as natural keys, and emits the file with the `$schema` header. Secrets never come back: payment method credentials, integration credentials and API key tokens are written as `# managed outside this file`. `--include` limits sections; the default is everything but products, since a large catalog belongs in the CSV import and export pipeline, not a hand-edited file.
+
+### Secrets
+
+The file is meant to be committed. Provider credentials (payment gateway keys, integration tokens) are set by the file only through `${ENV_VAR}` placeholders, which the CLI substitutes at deploy time and `introspect` never emits. A literal value in a credential attribute is rejected by validation.
+
+### Schemas
+
+Section schemas are hand-written Zod in the engine package. They reuse the Admin SDK's generated attribute types where a section mirrors an API resource, and describe the file shape (nested variants, references by key, the `${ENV}` placeholder) where it does not. `zod-to-json-schema` emits the published JSON Schema at build time. `@spree/admin-sdk` has no Zod today and gains none from this plan.
+
+### Dashboard e2e as the first consumer
+
+`packages/dashboard/e2e/global-setup.ts` keeps two Ruby statements: `Spree::Seeds::All.call` and the admin user. Everything else in `BOOTSTRAP_RUBY` moves to `packages/dashboard/e2e/fixtures/*.yml`, applied through the library entry against the test server once it is up, with prune on. Products, the second channel, categories, the promo customer and group, stock locations and levels, and the supplier all fit the sections above. The ledger seller's payouts and transfers are transaction data and stay Ruby, in a much smaller block. Spec-level helpers that already seed through the Admin API (`seedCatalogPickerProducts`) are unchanged. The gain is twofold: the fixtures become readable, and every CI run exercises the Admin API write paths before the suite starts.
+
+The seller panel has no e2e suite yet; when it gets one it starts from a YAML fixture, not another Ruby block. Core seeds, the worktree template and `spree:load_sample_data` do not change in this plan.
+
+### The project config file
+
+`create-spree-app` writes `spree.config.yml` next to `docker-compose.yml`:
+
+```yaml
+# yaml-language-server: $schema=https://spreecommerce.org/schemas/config/6.0.json
+version: 1
+
+store:
+ name: My Store # from the scaffold prompt
+ default_currency: USD
+ default_locale: en
+ default_country: US
+
+channels:
+ - code: online
+ name: Online Store
+
+markets:
+ - name: United States
+ countries: [US]
+ currency: USD
+ default: true
+
+# delivery_zones:
+# - name: Domestic
+# countries: [US]
+# delivery_methods:
+# - name: Standard
+# delivery_zone: Domestic
+# calculator: { type: flat_rate, preferences: { amount: 5.00, currency: USD } }
+```
+
+`spree init` runs, in order: `db:seed`, `spree:cli:ensure_api_key`, then `spree config deploy --config spree.config.yml` with a secret key minted for that run and revoked afterwards. `spree config deploy` with no `--config` defaults to `spree.config.yml` in the project directory, so day-to-day use is `spree config diff` and `spree config deploy` with nothing else. The `store` section updates the seeded store rather than creating one; `channels` and `markets` are additive, so the wholesale channel that seeds create is left alone. The file is committed with the project, and the CLI quickstart teaches deploying it to a remote instance with a profile.
+
+### Recipes
+
+`spree config recipe <name>` (a starter file for a wholesale store, a marketplace, an EU multi-currency setup) is a follow-up once the format has settled. The first release ships an `examples/` directory in the CLI package and the e2e fixtures as living examples.
+
+### Documentation
+
+A new `docs/developer/cli/configurator.mdx` covers the file format, the commands, the natural-key table, secrets, and CI usage, linked from the CLI quickstart and the Admin API page. The JSON Schema is published with the docs.
+
+## Migration Path
+
+1. **Natural key audit.** For every section in the table: confirm the key is unique per store at the database level, on the Ransack allowlist, and writable through the Admin API. Fix the gaps in `spree/core` and `spree/api` first, as their own small pull requests.
+2. **Engine and schemas.** Section schemas, reference resolution, plan and apply, diff rendering. Unit tests with MSW against recorded Admin API shapes, plus one integration run against the API dummy app the way `packages/sdk/tests/integration` does.
+3. **Commands.** `validate`, `diff`, `deploy`, `introspect` in `@spree/cli`, sharing credential resolution with `spree api`.
+4. **Dashboard e2e.** Move the bootstrap fixtures to YAML; the suite must stay green shard by shard.
+5. **Project scaffold.** `create-spree-app` writes `spree.config.yml` from its prompts; `spree init` deploys it with a per-run secret key. `spree config deploy` defaults to that file inside a project.
+6. **Docs and schema publication.**
+7. **Later, outside this plan:** server-side bulk upserts by natural key for products and categories, `recipe`, an MCP wrapper once `spree mcp` exists.
+
+## Constraints on Current Work
+
+- A new admin-manageable resource must have a stable, unique, human-readable key (code, slug or name, unique per store, enforced by an index) and that key must be on its Ransack allowlist. Without it the resource cannot be declared in a config file.
+- New dashboard e2e fixtures go into the YAML fixtures once step 4 lands; until then, keep additions to `BOOTSTRAP_RUBY` to what has no Admin API, so they move cleanly.
+- Do not add a Ruby-side YAML loader to core or the CLI's rake tasks; the configurator's contract is the Admin API.
+- Credential attributes on payment methods and integrations must never be readable back through the Admin API in plain text; `introspect` relies on that.
+
+## Open Questions
+
+None deferred. The four design questions (deletion policy, first-release scope, package placement, command noun) were settled on 2026-09-14 and are recorded under Key Decisions. The natural-key audit in Migration Path step 1 may surface resources whose key needs a schema change; those get decided in the audit pull requests, not here.
+
+## References
+
+- Saleor Configurator: https://saleor.io/blog/configurator and https://github.com/saleor/configurator
+- `docs/plans/5.5-admin-api-cli.md`, `docs/plans/6.0-admin-api.md`, `docs/plans/6.0-store-context-and-first-run-setup.md`, `docs/plans/5.6-admin-spa-csv-import.md`
+- `packages/cli/src/commands/api.ts`, `packages/cli/src/config.ts`
+- `packages/dashboard/e2e/global-setup.ts`
+- `spree/core/app/services/spree/seeds/all.rb`, `spree/core/app/services/spree/sample_data/loader.rb`
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 79b380607e..19820bde69 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -5518,3 +5518,38 @@ links out to the customer profile for edits — the list never writes, so the
per-currency `meta.totals` render as **one summary card per currency above the
table**, showing outstanding, issued and used; a single line or a footer row
cannot carry three figures per currency once a store trades in more than one.
+
+
+## 2026-09-14 — Store configuration is a file deployed through the Admin API, not Ruby seeds
+
+Plan: `6.0-cli-configurator.md`.
+
+Shaping an environment (channels, markets, tax, delivery, payment methods,
+catalog, customer groups, roles, origins, webhooks) was only possible from
+Ruby: `db:seed`, `spree:load_sample_data`, or Ruby embedded in the
+dashboard's e2e global setup. None of that works against a hosted instance,
+none of it is reviewable as a change, and headless teams on the API-only
+install may never open the Rails side.
+
+**Decision.** `spree config diff | deploy | introspect | validate` in
+`@spree/cli` reconciles a YAML file against a live store through the Admin
+API. YAML is canonical (comments, block text, clean diffs); JSON is accepted
+because YAML is its superset; no `defineConfig()` TypeScript form. Records are
+matched on natural keys, never prefixed IDs. Deploy is additive: deletes
+happen only in sections named in `--prune`, and `--fail-on-delete` refuses any
+plan with a delete. The engine lives inside `@spree/cli` as an exported
+library entry so the dashboard e2e setup imports it. Every project scaffolded
+by `create-spree-app` ships a `spree.config.yml` with the store, its default
+channel and default market, and `spree init` deploys it.
+
+**Bootstrap stays in Ruby.** The store row, the immutable admin role, the
+first admin user and the first API key have no API by design and a Rails app
+must seed without Node, so `Spree::Seeds::All` does not shrink. Transaction
+data (orders, payments, fulfillments, payouts) is never configuration.
+
+**Consequences for other work.** A new admin-manageable resource needs a
+stable, unique, human-readable key (code, slug or name, unique per store,
+backed by an index) and that key on its Ransack allowlist, or it cannot be
+declared in a config file. Credential attributes on payment methods and
+integrations must never read back in plain text through the Admin API;
+`introspect` relies on that. Do not add a Ruby-side YAML loader to core.