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
Add `spree exec`, `rails`, `bundle`, `rake`, `task` passthrough commands
Damian Legawiecbc17231d8321
diff --git a/docs/plans/spree-dev-cli-and-generators.md b/docs/plans/spree-dev-cli-and-generators.mdnew file mode 100644index 0000000000..a4beb88bca--- /dev/null+++ b/docs/plans/spree-dev-cli-and-generators.md@@ -0,0 +1,754 @@+# Spree Dev CLI + Generators — DX for TypeScript developers++**Status:** Spec, not approved.+**Audience:** TS developers who want to customize Spree without learning Docker internals or installing Ruby.+**Owners:** TBD.++## Project structure (what a user actually has)++`create-spree-app` scaffolds:++```+my-spree-app/+├── backend/ # the Rails app (cloned from spree-starter)+│ ├── Dockerfile+│ ├── Gemfile+│ ├── app/, config/, db/ …+│ └── docker-compose{,.dev}.yml (templates — copied up to root during scaffold)+├── apps/storefront/ # Next.js (optional)+├── docker-compose.yml # active compose at project root+├── docker-compose.dev.yml # dev compose at project root+├── .env+└── package.json # has @spree/cli as a dep+```++`create-spree-app/src/scaffold.ts:58–65` copies the compose files from `backend/` up to the project root and rewrites `context: .` → `context: ./backend` so the build context points at the Rails app. Everything in this doc operates against the **project root** compose files and the **`./backend`** Rails app. (The `server/` directory in the `spree/spree` monorepo is the local dev clone of `spree-starter` — irrelevant to user projects.)++## Problem++A TS developer who runs `pnpm dlx create-spree-app` lands in a working prebuilt-image setup. The moment they want to customize the backend — add a `Brand` model, expose an endpoint, write a subscriber — they hit three walls:++1. **`spree eject` means rebuild-on-every-edit.** Today it swaps `docker-compose.yml` for `docker-compose.dev.yml`, which builds from `./backend/Dockerfile`. The Dockerfile `COPY . .`s the source into the image and the compose file mounts only `storage_data:/rails/storage`. There is no source bind-mount, no bundle cache volume, and the env carries `RAILS_ENV=production` + `BUNDLE_DEPLOYMENT=1` + `BUNDLE_WITHOUT=development:test` from the Dockerfile. So every edit needs `docker compose build`; Zeitwerk reloading never engages; dev gems are absent.+2. **The CLI has no escape hatch.** `spree console`, `spree user create`, `spree api-key` each wrap a specific Rails task. There is no `spree exec`, `spree rails`, `spree bundle`, or `spree migrate`. Anything not pre-wrapped requires the developer to know the underlying `docker compose exec web …` incantation — exactly the knowledge the CLI exists to hide.+3. **Generators stop at the model.** `spree:model` (core/lib/generators/spree/model/) emits a model + migration. There is no `spree:api_resource` to scaffold a v3-conformant Store/Admin controller, serializer, route entry, request spec, and OpenAPI fragment. A new resource is hours of conformance work and a likely review back-and-forth on conventions (prefixed IDs, `{ data, meta }` envelope, expand, keyset pagination, Store-vs-Admin exposure split).++The fix is three independent tracks, layered: (1) make the dev container hot-reload, so `eject` stops meaning rebuild-hell; (2) ship a generic CLI passthrough plus a thin set of hot-path wrappers, like Laravel Sail; (3) add `spree:api_resource` so v3-conformance is correct-by-construction. (4) is the MCP/skill layer over the same surface — covered last and deferred to a follow-up.++The deliverables in this doc are concrete diffs against the project-root `docker-compose.dev.yml` (shipped from `spree-starter` and pulled into user projects by `create-spree-app`), `packages/cli/src/`, and the addition of `core/lib/generators/spree/api_resource/`. Devcontainer support is noted as a follow-up; OrbStack/virtiofs is a docs note, not code.++---++## Track 1 — Hot-reload dev container++### Goal++After `spree eject`, the developer edits a file under `./backend/` and the next request reflects the change. No `spree build`, no container restart, no Ruby on the host. Adding a gem stays inside the container (`spree bundle add …`) but does not require a full rebuild — gems land in a persisted volume.++### The four things to change++Each one is needed; cutting any one breaks the loop.++| Change | Why it's required |+|---|---|+| **Bind-mount `./backend:/rails`** | Edits on the host reach the container instantly. Generator output lands on the host. |+| **Named volume on `BUNDLE_PATH` (`/usr/local/bundle`)** | The bind-mount would otherwise shadow the gems baked into the image. The named volume sits over the bundle path so gems persist across `spree bundle add` without a rebuild. |+| **`RAILS_ENV=development`, unset `BUNDLE_DEPLOYMENT`, `BUNDLE_WITHOUT=""`** | The Dockerfile bakes production env. Without overrides the container boots in production mode (no reloading, dev gems absent) even with bind-mounts. |+| **Override entrypoint/command** | The Dockerfile's `ENTRYPOINT bin/docker-entrypoint` runs `db:prepare` and assets precompile every boot — wrong for dev. Use a thin dev command instead. |++### Concrete diff: `docker-compose.dev.yml` (project root; shipped from `spree-starter`'s `backend/` template)++Below is the full proposed file. Anchors and the prod-style `bin/docker-entrypoint` go away; bind-mount + bundle volume + dev env + a node_modules-style listener arrangement come in. Volumes that don't change (postgres, redis, meilisearch, storage) are unchanged.++```yaml+# Development: bind-mounts ./backend into the container. Edits are hot.+# Use `spree dev` (which runs `docker compose up -d` against this file).+#+# Adding a gem: `spree bundle add some_gem` — gems persist in the bundle_cache volume.+# Changing the Dockerfile or .ruby-version: `spree build` to rebuild the image.++x-app: &app+ build:+ context: .+ dockerfile: Dockerfile+ depends_on:+ postgres:+ condition: service_healthy+ redis:+ condition: service_healthy+ meilisearch:+ condition: service_healthy+ env_file: .env+ environment: &app-env+ DATABASE_URL: postgres://postgres@postgres:5432/spree_development+ REDIS_URL: redis://redis:6379/0+ SECRET_KEY_BASE: ${SECRET_KEY_BASE}+ RAILS_FORCE_SSL: "false"+ RAILS_ASSUME_SSL: "false"+ MEILISEARCH_URL: http://meilisearch:7700+ # --- dev overrides on top of the Dockerfile's production defaults ---+ RAILS_ENV: development+ BUNDLE_DEPLOYMENT: "0"+ BUNDLE_WITHOUT: ""+ BUNDLE_PATH: /usr/local/bundle+ BOOTSNAP_CACHE_DIR: /rails/tmp/cache/bootsnap+ volumes:+ # bind-mount the source so host edits are live in the container+ - ./backend:/rails+ # named volume over BUNDLE_PATH so the bind-mount doesn't shadow installed gems,+ # and so `bundle add` persists across container restarts without a rebuild+ - bundle_cache:/usr/local/bundle+ # named volume for storage (uploads, ActiveStorage local disk)+ - storage_data:/rails/storage+ # named volume for tmp so bootsnap + cache don't churn the host+ - tmp_cache:/rails/tmp++services:+ postgres:+ image: postgres:18-alpine+ environment:+ POSTGRES_HOST_AUTH_METHOD: trust+ PGDATA: /var/lib/postgresql/18/docker+ ports:+ # forwarded for native DB clients (TablePlus, DataGrip, psql) — Track 1 add+ - "${SPREE_DB_PORT:-5433}:5432"+ volumes:+ - postgres_data:/var/lib/postgresql+ healthcheck:+ test: pg_isready -U postgres+ interval: 5s+ timeout: 5s+ retries: 5++ redis:+ image: redis:7-alpine+ volumes:+ - redis_data:/data+ healthcheck:+ test: redis-cli ping+ interval: 5s+ timeout: 5s+ retries: 5++ meilisearch:+ image: getmeili/meilisearch:latest+ volumes:+ - meilisearch_data:/meili_data+ ports:+ - "7700:7700"+ healthcheck:+ test: curl -f http://localhost:7700/health || exit 1+ interval: 5s+ timeout: 5s+ retries: 5++ web:+ <<: *app+ # bypass bin/docker-entrypoint (which does db:prepare + assets:precompile —+ # not what we want in dev). Run setup explicitly via `spree init`.+ entrypoint: []+ command: ["bin/rails", "server", "-b", "0.0.0.0", "-p", "3000"]+ ports:+ - "${SPREE_PORT:-3000}:3000"+ healthcheck:+ test: curl -f http://localhost:3000/up || exit 1+ interval: 10s+ timeout: 5s+ retries: 10+ start_period: 30s++ worker:+ <<: *app+ entrypoint: []+ command: ["bundle", "exec", "sidekiq"]+ environment:+ <<: *app-env+ RAILS_MAX_THREADS: ${SIDEKIQ_DB_POOL:-27}++volumes:+ postgres_data:+ redis_data:+ meilisearch_data:+ storage_data:+ bundle_cache:+ tmp_cache:+```++Notes on the diff:++- **`DATABASE_URL` switches `spree_production` → `spree_development`.** This matches `RAILS_ENV=development` (Rails would otherwise look for the wrong DB). `spree init` creates it; `spree migrate` runs against it.+- **The bind-mount + bundle-cache layering is the trick.** Without the named volume on `/usr/local/bundle`, the bind-mount of `./backend → /rails` shadows the gems baked into the image (since the build stage installs to `/usr/local/bundle` and copies them in). The named volume re-overlays gems on top, and persists `bundle add` results across boots.+- **Anchored `volumes:` on `*app`** means `web` and `worker` share the same mount set. Don't define `volumes:` on the service or it'll override the anchor — Compose merges keys, but it replaces lists.+- **`entrypoint: []` is intentional.** `bin/docker-entrypoint` runs `db:prepare` (which would auto-create the DB and silently swallow migration ordering issues) and `bootsnap precompile`. Both are wrong in dev. `spree init` does the explicit equivalent (`db:create`, `db:migrate`, `db:seed`).+- **`SPREE_DB_PORT=5433` default**, not 5432, to avoid colliding with a host-native Postgres if the user has one.++### Adding and updating gems — no image rebuild++The `bundle_cache` named volume is the persistent gem store. The dev image's role is "seed the volume on first creation with a known-good baseline"; after that, the volume is the source of truth.++| Scenario | Command | Image rebuild? |+|---|---|---|+| Add a gem | `spree bundle add foo` | No — installs into `bundle_cache` |+| Update a gem | `spree bundle update <gem>` | No |+| Pull teammate's Gemfile.lock change | `spree bundle install` | No |+| `.ruby-version` bump | `spree build` + see gotcha below | Yes |+| Dockerfile apt package change | `spree build` | Yes |++**Gotcha (documented; not a code change):** Docker initializes a named volume from the image's mount-path contents *only the first time the volume is created*. After `spree build` for a `.ruby-version` bump, the rebuilt image carries gems compiled against the new Ruby, but the existing `bundle_cache` volume still holds gems from the old Ruby — they'll fail to load. Fix: `docker volume rm <project>_bundle_cache` (or, in the CLI: `spree build --reset-bundle` — a small additional flag to wipe the bundle volume in the same operation; trivial to add to the `build` command).++### `eject` semantics post-change++`spree eject` keeps its current job — copy `docker-compose.dev.yml` over `docker-compose.yml` — but the meaning changes: the dev compose is now the live-edit configuration, not a "build from local source" configuration. After `eject`:++- File edits in `./backend/` are live (Zeitwerk).+- `Gemfile` edits use `spree bundle add <gem>` (runs inside the container, persists to `bundle_cache`).+- `Dockerfile` or `.ruby-version` edits require `spree build` (new command, see Track 2).++### Diff: `packages/cli/src/commands/eject.ts`++```diff+- console.log(`\n${pc.bold('Building backend from local source...')}\n`)+- await dockerCompose(['build'], ctx.projectDir, { stdio: 'inherit' })+-+- console.log(`\n${pc.bold('Restarting services...')}\n`)++ console.log(`\n${pc.bold('Switching to dev compose (bind-mounts ./backend)...')}\n`)+ await dockerCompose(['up', '-d'], ctx.projectDir, { stdio: 'inherit' })++ p.note(+ [+- `Backend now builds from ${pc.bold('./backend')}`,++ `Backend is now bind-mounted from ${pc.bold('./backend')} — edits are live.`,+ '',+ 'You can now customize:',+- ` ${pc.dim('backend/Gemfile')} — add gems`,++ ` ${pc.dim('backend/app/')} — models, controllers, services — instant reload`,++ ` ${pc.dim('backend/Gemfile')} — add gems via ${pc.bold('spree bundle add <gem>')}`,+ ` ${pc.dim('backend/app/')} — models, controllers, etc.`,+ ` ${pc.dim('backend/config/')} — Rails configuration`,+ '',+- `Run ${pc.bold('npx spree dev')} to restart with your changes.`,++ `Rebuild only on Dockerfile / .ruby-version changes: ${pc.bold('spree build')}`,+ ].join('\n'),+ 'Ejected!',+ )+```++`spree build` is the new "I actually changed the image" escape hatch — see Track 2.++---++## Track 2 — CLI: passthrough first, then wrappers++### Goal++A TS developer can run any Rails / bundler / shell command inside the dev container without knowing about Docker. Hot-path commands get a short alias; everything else goes through a generic passthrough.++### Design principle: passthrough is the floor++The hot wrappers (`spree generate`, `spree migrate`, `spree bundle`, `spree build`) save keystrokes for the common cases. The generic passthrough (`spree exec`, `spree rails`, `spree bundle`) guarantees nothing is ever blocked on a command we forgot to wrap. **Build passthrough first, wrappers second** — the wrappers can never invalidate the floor.++### New commands++| Command | Maps to | Notes |+|---|---|---|+| `spree exec <cmd…>` | `docker compose exec web <cmd…>` | Generic escape hatch. Anything works. |+| `spree rails <args…>` | `docker compose exec web bin/rails <args…>` | Short for `spree exec bin/rails …` |+| `spree rake <task> [args…]` | `docker compose exec web bin/rake <task> [args…]` | Direct rake passthrough. `spree rake spree:price_history:seed`, `spree rake spree:channels:create_defaults`. Use this for data backfills, upgrade tasks, and anything not wrapped by a higher-level command. Args after `--` are forwarded as rake task args (`spree rake spree:foo -- BAR=baz`). |+| `spree task <name> [args…]` | alias for `spree rake spree:<name>` | Shorter for Spree-namespaced tasks: `spree task price_history:seed` ≡ `spree rake spree:price_history:seed`. |+| `spree bundle <args…>` | `docker compose exec web bundle <args…>` | `spree bundle add stripe`, `spree bundle install`, `spree bundle outdated`. Gems land in `bundle_cache`. |+| `spree generate <name> [args…]` | `docker compose exec web bin/rails g spree:<name> [args…]` | Translates `spree generate model Brand …` into `bin/rails g spree:model Brand …`. Auto-prefixes `spree:`. |+| `spree migrate` | `docker compose exec web bin/rails db:migrate` | Hot path — first thing after every generator. |+| `spree migrate:rollback [STEP=n]` | `docker compose exec web bin/rails db:rollback` | |+| `spree migrate:status` | `docker compose exec web bin/rails db:migrate:status` | |+| `spree db:reset` | `docker compose exec web bin/rails db:drop db:create db:migrate db:seed` | Common nuke-and-pave. Prompts for confirmation. |+| `spree routes [-g pattern]` | `docker compose exec web bin/rails routes [-g …]` | |+| `spree build` | `docker compose exec` not viable — `docker compose build web` | Used after Dockerfile / `.ruby-version` changes. Not after Gemfile changes (use `spree bundle add` for those). |+| `spree db:console` | `docker compose exec postgres psql -U postgres spree_development` | One-liner for psql without remembering credentials. (Native clients use the forwarded `SPREE_DB_PORT`.) |++The existing commands (`spree dev`, `spree init`, `spree stop`, `spree logs`, `spree console`, `spree user`, `spree api-key`, `spree open`, `spree seed`, `spree sample-data`, `spree update`, `spree eject`) stay.++### Implementation sketch++A single new helper, `dockerComposeExec`, generalizes what `railsConsole` does today (`packages/cli/src/docker.ts:33–37`) and accepts arbitrary argv:++```ts+// packages/cli/src/docker.ts — add alongside existing helpers++export async function dockerComposeExec(+ argv: string[],+ projectDir: string,+ options: { service?: string; tty?: boolean; env?: Record<string, string> } = {},+): Promise<void> {+ const { service = 'web', tty = true, env } = options+ const args = ['compose', 'exec']+ if (!tty) args.push('-T')+ if (env) for (const [k, v] of Object.entries(env)) args.push('-e', `${k}=${v}`)+ args.push(service, ...argv)++ await execa('docker', args, { cwd: projectDir, stdio: 'inherit' })+}+```++Then `exec`, `rails`, `bundle`, `migrate`, `generate`, `routes` are each one file in `packages/cli/src/commands/` that calls `dockerComposeExec` with a different prefix. Example:++```ts+// packages/cli/src/commands/generate.ts (new)+import type { Command } from 'commander'+import { detectProject } from '../context.js'+import { dockerComposeExec } from '../docker.js'++export function registerGenerateCommand(program: Command): void {+ program+ .command('generate <name> [args...]')+ .alias('g')+ .description('Run a Spree generator (e.g. `spree generate model Brand name:string`)')+ .allowUnknownOption(true) // pass through `--skip-tests` etc.+ .action(async (name: string, args: string[]) => {+ const ctx = detectProject()+ await dockerComposeExec(+ ['bin/rails', 'g', `spree:${name}`, ...args],+ ctx.projectDir,+ )+ })+}+```++```ts+// packages/cli/src/commands/exec.ts (new) — the universal escape hatch+import type { Command } from 'commander'+import { detectProject } from '../context.js'+import { dockerComposeExec } from '../docker.js'++export function registerExecCommand(program: Command): void {+ program+ .command('exec <command...>')+ .description('Run an arbitrary command inside the web container')+ .allowUnknownOption(true)+ .action(async (command: string[]) => {+ const ctx = detectProject()+ await dockerComposeExec(command, ctx.projectDir)+ })+}+```++`spree rails`, `spree bundle`, `spree migrate`, `spree routes`, `spree db:reset`, `spree db:console` follow the same pattern — ~15 lines each, no shared abstraction needed beyond `dockerComposeExec`.++### `spree console` becomes a thin wrapper++Drop `railsConsole` from `docker.ts` — `registerConsoleCommand` becomes:++```ts+await dockerComposeExec(['bin/rails', 'console'], ctx.projectDir)+```++Same for the other Rails-task-bound commands. `rakeTask` (the non-interactive variant that strips Spree boot noise) stays — `init`, `user create`, `api-key` still use it for parsed output.++### Registration++```diff+ // packages/cli/src/index.ts++import { registerBuildCommand } from './commands/build.js'++import { registerBundleCommand } from './commands/bundle.js'++import { registerDbCommand } from './commands/db.js'++import { registerExecCommand } from './commands/exec.js'++import { registerGenerateCommand } from './commands/generate.js'++import { registerMigrateCommand } from './commands/migrate.js'++import { registerRailsCommand } from './commands/rails.js'++import { registerRoutesCommand } from './commands/routes.js'+ // … existing registrations …++registerExecCommand(program)++registerRailsCommand(program)++registerBundleCommand(program)++registerGenerateCommand(program)++registerMigrateCommand(program)++registerBuildCommand(program)++registerDbCommand(program)++registerRoutesCommand(program)+```++### The Laravel Sail parallel++For reviewers benchmarking against Sail:++| Sail | This proposal |+|---|---|+| `sail artisan make:model Brand` | `spree generate model Brand` |+| `sail artisan migrate` | `spree migrate` |+| `sail composer require stripe/stripe-php` | `spree bundle add stripe` |+| `sail tinker` | `spree console` |+| `sail shell` | `spree exec bash` |+| `sail up -d` | `spree dev` |+| `sail build` | `spree build` |++Same shape: thin shell over `docker compose exec`, predictable verb-noun mapping, generic escape hatch covers the long tail.++---++## Track 2c — `spree upgrade` (scripted guidance, not magic)++### What it is and what it isn't++**Is:** an interactive walkthrough of the steps required to upgrade from your current Spree version to the target version, with the automatable parts (rake data tasks, `db:migrate`) offered as "run now? [Y/n]". Each step is named, ordered, idempotent, and re-runnable. Output mirrors what's in `docs/upgrades/<version>.mdx` so the command and the docs can never drift.++**Isn't:** a magic `spree upgrade && done` button. Upgrades involve `bundle update spree*`, schema migrations, data backfills, occasional config edits, and version-specific manual review steps (e.g. "audit your custom decorators against the renamed class"). A command that owns half the steps and silently hands the rest to the user is worse than no command — users assume it owned the whole thing and skip the manual parts. The framing is "scripted runbook," not "automation."++This is the same shape as Rails' own upgrade flow (`rails app:update` walks you through config diffs interactively) and Spree's existing per-task `desc` strings ("Run the full 5.4 → 5.5 channel upgrade"). It just makes them addressable from one command and sequences them correctly.++### The mapping problem and how it's solved++Today's data tasks are *implicitly* version-scoped — `spree/core/lib/tasks/channels.rake` is the 5.4→5.5 channel upgrade, `price_history.rake:seed` is the 5.4→5.5 EU Omnibus backfill — but only the rake `desc` strings encode that, and only as prose. The version → tasks mapping lives nowhere machine-readable. Adding `spree upgrade` requires a mapping.++The mapping uses **directory convention + tiny per-version manifest**, with the rake tasks themselves unchanged:++```+core/lib/spree/upgrades/+├── 5_4_to_5_5/+│ ├── manifest.yml+│ └── README.md (optional long-form; otherwise docs link)+├── 5_5_to_6_0/+│ ├── manifest.yml+│ └── README.md+└── …+```++`manifest.yml` per version is short and lists each step:++```yaml+# core/lib/spree/upgrades/5_4_to_5_5/manifest.yml+from: "5.4"+to: "5.5"+docs: "https://spreecommerce.org/docs/upgrades/5.5"++steps:+ - id: bundle+ name: "Update Spree gems"+ kind: shell+ command: "bundle update spree spree_api spree_admin"+ automated: true++ - id: migrate+ name: "Run database migrations"+ kind: rails+ command: "db:migrate"+ automated: true++ - id: channels+ name: "Create default channels and backfill product publications"+ kind: rake+ task: "spree:channels:full_upgrade"+ automated: true+ idempotent: true++ - id: price_history+ name: "Seed price history from current base prices (EU Omnibus)"+ kind: rake+ task: "spree:price_history:seed"+ automated: true+ idempotent: true+ skip_if: "non-EU stores can skip"++ - id: review_decorators+ name: "Review custom decorators against renamed Promotion → Discount API surface"+ kind: manual+ docs_anchor: "decorator-review"+ automated: false+```++Why a YAML manifest rather than a Ruby DSL or rake task metadata: the manifest is data the CLI reads — it does not need Rails booted to render the plan, and adding a step does not require touching CLI code. A new upgrade directory + manifest = a new upgrade. That's the whole extension model.++### CLI surface++```+spree upgrade # detect from → to from Gemfile.lock and run the manifest interactively+spree upgrade --to 5.5 # explicit target (when you want to step rather than jump)+spree upgrade --plan # print the plan, don't execute (good for PR description / runbook)+spree upgrade --step price_history # run one step idempotently+spree upgrade --from 5.4 --to 6.0 # multi-hop: walks 5.4→5.5, then 5.5→6.0 in sequence+```++`--from` defaults to the current installed Spree version (read from `Gemfile.lock` inside the container). `--to` defaults to the latest version with an upgrade manifest. The detected version pair selects which manifests to run, in order. For each step:++- `kind: shell` — print the command, ask, run via `dockerComposeExec`.+- `kind: rails` — same, run via `bin/rails <command>`.+- `kind: rake` — same, run via `bin/rake <task>`.+- `kind: manual` — print the description + docs link, wait for "done? [Y/n]" before continuing.++Default mode is interactive (each step asks). `--yes` runs all automated steps without prompting and stops at the first `kind: manual`. `--plan` doesn't execute anything.++### What this implies for rake task organization++The rake tasks themselves don't move. `spree/core/lib/tasks/channels.rake` stays where it is. What changes:++1. **Add per-version aggregator tasks** where they don't already exist. `channels.rake` already has `full_upgrade`; the pattern should be every version-scoped rake file ends with one idempotent aggregator task that runs the whole version's data migration for that domain. Then the manifest references just the aggregator, never the individual tasks.+2. **Tighten idempotency.** Aggregator tasks must be safe to re-run. Some of the existing ones already are (e.g. `create_defaults` uses `ensure_default_channel`); others (`backfill_*`) should be audited and made idempotent (skip rows where the target column is already populated, etc.) before they appear in any manifest.+3. **Manifest references task names, not file paths.** This makes the manifest survive rake task moves between files.++### What `spree upgrade` does NOT solve++- **Decorator and customization review.** A user with custom decorators on `Spree::Promotion` needs to manually audit them when the API surface renames to `Discount`. This is `kind: manual` in the manifest with a link to the upgrade doc. No tool can do this safely.+- **Database-specific gotchas.** `Spree::Current.store` and similar runtime-context migrations. Same answer: `kind: manual`, link to docs.+- **Cross-extension upgrades.** Each Spree extension owns its own upgrade docs and rake tasks. `spree upgrade` only walks core. Extensions can ship their own manifests under `<gem>/lib/spree/upgrades/`; the CLI globs the gem load paths to discover them. Out of scope for v1; document the convention but don't build it.++### Why not "spree upgrade just runs every rake task in a namespace"++The temptation: pattern-match `spree:upgrades:5_5:*` and run them all. Rejected because (a) ordering matters (you can't seed price history before the migration adds the table), (b) some steps aren't rake tasks (`bundle update`, manual reviews), (c) some are conditionally skippable, and (d) prose context per step matters for the user trusting the command. The manifest is the price of doing this honestly.++---++## Track 3 — `spree:api_resource` generator++### Goal++`spree generate api_resource Brand name:string:index slug:string:uniq` produces a complete, idiomatic v3 resource: model, migration, Store controller, Admin controller, two serializers, routes injected, request specs, OpenAPI fragment, and an admin-sdk type entry — all of it conformant with the conventions in `CLAUDE.md` (prefixed IDs, `{ data, meta }` envelope, flat params, Store vs Admin exposure rules).++### Why this lives in Ruby, not in the CLI++The CLI's `spree generate` proxies to `bin/rails g spree:<name>`. The actual scaffolding stays inside `core/lib/generators/spree/api_resource/` for the same reason `spree:model` lives there: generators belong with the framework they generate code for. The CLI's job is environment management; the generator's job is code generation. If we ever ship a non-Docker workflow (mise, native Ruby) the generator works unchanged.++### Generator surface++```+spree:api_resource NAME [field[:type[:index|:uniq|:null|:default=…]]…] [options]+```++**Standard Rails field syntax**, extended with:++- `:uniq` — adds a unique index, validates uniqueness scoped to `spree_base_uniqueness_scope`+- `:index` — adds a non-unique index+- `:null` — marks `null: false` (the inverse of Rails' default; matches CLAUDE.md "always `null: false` on required columns")+- `belongs_to:<Model>` — adds the association + index, **no FK constraint** (per CLAUDE.md migration rules)++**Options:**++- `--id-prefix=brand` — optional, **auto-filled** from the class name when omitted. Default derivation: snake_case the class name and take the whole thing (`Brand → :brand`, `OrderRoutingRule → :order_routing_rule`). The generated `has_prefix_id :<prefix>` line is surfaced in the generator's summary output so the developer sees the chosen prefix and can edit the model file if they want a shorter or curated form. The existing codebase mixes both — some models go long (`:variant`, `:price`, `:invitation`), others go curated (`:ful` for Shipment, `:py` for Payment for Stripe parity, `:cf` for Metafield rename). Auto-fill picks the safe long form; edit afterwards if you want curated.+- `--store` / `--no-store` (default: yes — generate Store controller + serializer)+- `--admin` / `--no-admin` (default: yes)+- `--store-name=Discount` — emit Store controller/serializer/routes under a different external name (handles the Promotions/Discounts split)+- `--writable` (Store API) — opt into create/update/destroy on the Store controller (default: read-only, per CLAUDE.md "read-only by default")+- `--paranoid` — `acts_as_paranoid`, adds `deleted_at` column + `dependent: :destroy_async` on associations+- `--metafields` — include `Spree::Metafields` + `Spree::Metadata`+- `--skip-routes`, `--skip-openapi`, `--skip-specs` — escape hatches++### What it emits++For `spree generate api_resource Brand name:string:uniq active:boolean:default=true`:++```+core/app/models/spree/brand.rb (owned-once)+core/db/migrate/<ts>_create_spree_brands.rb (append-only)++api/app/controllers/spree/api/v3/store/brands_controller.rb (managed)+api/app/controllers/spree/api/v3/admin/brands_controller.rb (managed)+api/app/serializers/spree/api/v3/brand_serializer.rb (managed)+api/app/serializers/spree/api/v3/admin/brand_serializer.rb (managed)+api/spec/integration/api/v3/store/brands_spec.rb (managed)+api/spec/integration/api/v3/admin/brands_spec.rb (managed)+api/config/routes.rb (route injected between markers)+core/lib/spree/testing_support/factories/brand_factory.rb (managed)++docs/api-reference/store.yaml (regenerate from specs)+packages/sdk/src/types/generated/store-brand.d.ts (regenerate via Typelizer)+packages/admin-sdk/src/types/generated/admin-brand.d.ts (regenerate via Typelizer)+```++### Idempotency contract++Re-running the generator on an existing resource — the use case is "I added a field, regenerate" — should leave the model file untouched (it's the developer's now), append a new migration for the schema delta, and rewrite the serializers/controllers/specs/routes in place. The model file gets a header comment marking it as owned-once:++```ruby+# This file was scaffolded by `spree generate api_resource Brand`.+# It's yours now — behavior, validations, scopes, callbacks live here.+# Re-running the generator will NOT overwrite this file.+module Spree+ class Brand < Spree.base_class+ # ...+ end+end+```++The contract from the last-turn writeup (owned-once / managed-forever / append-only) is the whole trick. Hand-edit the model freely; hand-editing the serializer is allowed but means the next generator run will overwrite — which is fine because the conventions (prefixed IDs, typelize, what's Store vs Admin) are exactly what the generator already enforces.++**Route injection** uses Rails-style sentinel markers in `api/config/routes.rb`:++```ruby+namespace :store do+ # BEGIN spree:api_resource managed routes — do not hand-edit+ resources :brands, only: [:index, :show]+ # END spree:api_resource managed routes+end+```++`Thor::Actions#insert_into_file` finds the markers and inserts; if a `resources :brands` line already exists in the block, skip.++### Generated examples (abbreviated)++Model (owned-once, minimal — developer adds behavior). Note the `has_prefix_id :brand` line — prefixed IDs are computed on the fly via `Spree::PrefixedId` (no DB column), but the prefix must be declared per-model. The generator emits it from the `--id-prefix` flag:++```ruby+# backend/app/models/spree/brand.rb+# Owned-once: scaffolded by `spree generate api_resource Brand`.+module Spree+ class Brand < Spree.base_class+ include Spree::Metafields+ include Spree::Metadata++ has_prefix_id :brand # from --id-prefix=brand; auto-derived from class name when flag omitted++ validates :name, presence: true+ validates :slug, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }++ self.whitelisted_ransackable_attributes = %w[name slug active]+ end+end+```++Migration (append-only, conventional Rails):++```ruby+class CreateSpreeBrands < ActiveRecord::Migration[7.2]+ def change+ create_table :spree_brands do |t|+ t.string :name, null: false+ t.string :slug, null: false+ t.boolean :active, null: false, default: true+ t.timestamps+ end++ add_index :spree_brands, :slug, unique: true,+ name: 'index_spree_brands_on_slug'+ end+end+```++Store controller (managed):++```ruby+module Spree::Api::V3::Store+ class BrandsController < ResourceController+ protected++ def model_class+ Spree::Brand+ end++ def serializer_class+ Spree.api.brand_serializer+ end+ end+end+```++Store serializer (managed — no timestamps, customer-facing fields only):++```ruby+module Spree::Api::V3+ class BrandSerializer < BaseSerializer+ typelize active: :boolean+ attributes :id, :name, :slug, :active+ end+end+```++Admin serializer (managed — extends store, adds timestamps + back-office fields):++```ruby+module Spree::Api::V3::Admin+ class BrandSerializer < V3::BrandSerializer+ attributes :created_at, :updated_at+ end+end+```++Admin controller — empty subclass (full CRUD inherited from `Spree::Api::V3::Admin::ResourceController`).++Request spec (managed — single happy-path + a 422 case for OpenAPI examples; matches CLAUDE.md test guidance):++```ruby+# api/spec/integration/api/v3/store/brands_spec.rb+require 'swagger_helper'++RSpec.describe 'Brands API', type: :request do+ path '/api/v3/store/brands' do+ get 'List brands' do+ tags 'Brands'+ produces 'application/json'++ response '200', 'returns brands' do+ let!(:brand) { create(:brand) }+ run_test!+ end+ end+ end+end+```++(Admin spec covers create/update/destroy; same shape.)++### The `--store-name Discount` flag — the naming-split case++Models, tables, and ability checks stay `Brand` / `spree_brands` internally. The Store API surface re-exposes the same controller under a different external name:++```ruby+# api/config/routes.rb (Store namespace)+resources :discounts, controller: 'brands', only: [:index, :show]+```++…and the Store serializer is aliased (in the registry, not duplicated):++```ruby+Spree.api.brand_serializer = 'Spree::Api::V3::DiscountSerializer'+```++Generated `DiscountSerializer` is a one-line subclass of `BrandSerializer`. This is exactly the Promotions/Discounts pattern from the 6.0 plans — one flag, mechanical output, no per-resource thinking.++### Out of scope++- **TS frontend forms / pages.** Per the conversation: backend-only for now. `@spree/dashboard` route scaffolding is a separate generator, deferred.+- **Diffing across regenerations to produce migration deltas.** Migrations are generated once on resource create; field additions/changes are a separate `spree generate migration AddFieldToBrand` step (proxies to `bin/rails g migration`).+- **Decorator-aware generation** (i.e. detecting that the user has decorated `Spree::Brand` elsewhere). Decorators are last-resort per CLAUDE.md; we don't need to be clever about them.++---++## Track 4 — MCP tools + Skill (deferred)++The exact same `dockerComposeExec` + `spree:api_resource` engine surfaces three different ways:++1. **CLI** — what this doc specs.+2. **MCP tools** — `spree_generate_resource(name, fields, options)`, `spree_migrate()`, `spree_run_rails(args)`, etc. Each is a typed wrapper over the same engine. Already partially exists (`mcp__claude_ai_Spree_Commerce_Docs_MCP__*` ships docs search; we'd add an action server).+3. **Skill / `AGENTS.md`** — `docs/agents/spree-customization.md` teaches the agent: "for green-field resources call `spree_generate_resource`; for cross-cutting edits (add a field to an existing serializer, wire a filter into an existing endpoint, write a subscriber) read the file and edit it; the generator output is correct-by-construction so don't second-guess it."++This doc treats those as a follow-up because they all depend on Tracks 1–3 existing first. The shape of (4) doesn't change the design of (1–3) at all — it's pure orchestration over them.++---++## Sequencing++Strict order; each phase unblocks the next.++1. **Track 1 (compose rewrite + eject diff).** Single PR. Without this, every other track's wrappers still trigger rebuilds and the developer story is unchanged.+2. **Track 2a — passthrough (`spree exec`, `spree rails`, `spree bundle`).** Single PR. After this, every Rails command is reachable without docs.+3. **Track 2b — hot-path wrappers (`spree generate`, `spree migrate`, `spree build`, `spree db:console`, `spree rake`, `spree task`).** Single PR. Polishing; users have escape hatch from 2a if a wrapper is missing or buggy.+4. **Track 2c — `spree upgrade` + per-version manifests.** Separate PR. Starts with one manifest (5.4→5.5, since the rake tasks largely exist). Adding manifests for future versions becomes part of the release checklist. Can ship independent of Track 3.+5. **Track 3 — `spree:api_resource` generator.** Larger PR, lives in `core/`. The model + migration paths can ship before the serializer/controller/route paths if needed; the value is cumulative.+6. **Track 4 — MCP / skill.** Follow-up doc + PR. Not in this scope.++Devcontainer and mac perf docs (OrbStack, virtiofs) ride along with Track 1 as a separate `docs/developer/dev-environment.md` page.++---++## Resolved decisions++These were open and now aren't, written down so future-me doesn't reopen them:++1. **Compose profile vs file swap.** Keep the file swap; revisit only if it bites.+2. **`spree generate` does NOT auto-run `spree migrate`.** Two-step, like Rails. Documented in command help.+3. **Prefixed-ID prefix is per-model and auto-filled.** `Spree::PrefixedId` (`spree/core/app/models/concerns/spree/prefixed_id.rb`) computes IDs on the fly via Sqids from the integer PK — no column, no DB change. The prefix is declared per-class via `has_prefix_id :prod`. The generator auto-derives the prefix from the class name (`Brand → :brand`, `OrderRoutingRule → :order_routing_rule`) and emits the line, surfacing the chosen prefix in the summary output so the developer can edit if they want a shorter or curated form (e.g. matching Stripe like `:py`). See Track 3 options for the override flag.+6. **All upgrade rake tasks MUST be idempotent.** This is a hard contract, not a soft preference: a task that fails on re-run cannot ship to a manifest. The pattern is `where.not(<target_col>: nil)` skip-guards on `backfill_*` and `ensure_*`-style guards on `create_*` (as `channels.rake:create_defaults` does today via `ensure_default_channel`). Audit pass on existing tasks is a prerequisite for Track 2c.+7. **Extension manifests deferred.** v1 ships core-only. Extensions invoke their own upgrade rake tasks manually.++## Open questions++1. **~~`db/schema.rb` write permissions from the dev container.~~ Resolved.** Originally framed as a real problem — turns out it isn't. Every CLI command goes through `docker compose exec web …`, which means file writes happen as the container's default user (UID 1000, `rails`). On macOS, Docker Desktop and OrbStack do UID mapping at the VM boundary, so bind-mount writes always appear as the host user regardless of container UID. On Linux, the host user is typically UID 1000 (Ubuntu/Debian/Fedora default), so the UIDs match. The bundle/tmp/storage volumes are docker-managed (not bind-mounted), so the host never touches them — initial UID-1000 ownership inside the container is exactly what's wanted. The compose stays simple: no `user:` override, no init service, no entrypoint chown. The CLI exporting `HOST_UID`/`HOST_GID` is only needed for the Linux multi-user edge case (host user not UID 1000) and is deferred until someone actually hits it.++2. **`spree-starter` PR.** The new compose ships from `spree-starter`'s `backend/` template; the local clone is at `/Users/damian/github/spree-starter`. A sibling PR lands the new `docker-compose.dev.yml` there. (The monorepo `server/` directory is dev-only for the gems and doesn't need separate consideration.)++3. **Idempotency helper for backfill tasks.** The existing `backfill_*` family will get `where.not(<col>: nil)` guards as part of the Track 2c prep audit. Whether to extract a shared helper (`Spree::Upgrades::Idempotent.backfill(scope, &block)`) or keep guards per-task is style preference; lean per-task — explicit skip conditions read better than a clever wrapper for something that runs once per upgrade.diff --git a/packages/cli/src/commands/bundle.ts b/packages/cli/src/commands/bundle.tsnew file mode 100644index 0000000000..2cce6e190a--- /dev/null+++ b/packages/cli/src/commands/bundle.ts@@ -0,0 +1,21 @@+import type { Command } from 'commander'+import { detectProject } from '../context.js'+import { dockerComposeExec } from '../docker.js'++// Run bundler inside the web container. Gems install into the bundle_cache+// volume and persist across container restarts without an image rebuild.+// spree bundle add stripe+// spree bundle update spree spree_api+// spree bundle outdated+export function registerBundleCommand(program: Command): void {+ program+ .command('bundle')+ .description('Run a bundler command (`bundle …`) inside the web container')+ .argument('<args...>', 'arguments to pass to bundle')+ .allowUnknownOption(true)+ .passThroughOptions(true)+ .action(async (args: string[]) => {+ const ctx = detectProject()+ await dockerComposeExec(['bundle', ...args], ctx.projectDir)+ })+}diff --git a/packages/cli/src/commands/console.ts b/packages/cli/src/commands/console.tsindex 06160b699a..9e9b42286d 100644--- a/packages/cli/src/commands/console.ts+++ b/packages/cli/src/commands/console.ts@@ -1,6 +1,6 @@import type { Command } from 'commander'import { detectProject } from '../context.js'-import { railsConsole } from '../docker.js'+import { dockerComposeExec } from '../docker.js'export function registerConsoleCommand(program: Command): void {program@@ -8,6 +8,6 @@ export function registerConsoleCommand(program: Command): void {.description('Open Rails console').action(async () => {const ctx = detectProject()- await railsConsole(ctx.projectDir)+ await dockerComposeExec(['bin/rails', 'console'], ctx.projectDir)})}diff --git a/packages/cli/src/commands/exec.ts b/packages/cli/src/commands/exec.tsnew file mode 100644index 0000000000..74bdcce67b--- /dev/null+++ b/packages/cli/src/commands/exec.ts@@ -0,0 +1,21 @@+import type { Command } from 'commander'+import { detectProject } from '../context.js'+import { dockerComposeExec } from '../docker.js'++// Universal escape hatch: run an arbitrary command inside the web container.+// Anything not pre-wrapped by another `spree` command can be reached via this.+// spree exec ls -la+// spree exec bash+// spree exec env | sort+export function registerExecCommand(program: Command): void {+ program+ .command('exec')+ .description('Run an arbitrary command inside the web container')+ .argument('<command...>', 'command and arguments to run')+ .allowUnknownOption(true)+ .passThroughOptions(true)+ .action(async (command: string[]) => {+ const ctx = detectProject()+ await dockerComposeExec(command, ctx.projectDir)+ })+}diff --git a/packages/cli/src/commands/rails.ts b/packages/cli/src/commands/rails.tsnew file mode 100644index 0000000000..1fb53e3c0c--- /dev/null+++ b/packages/cli/src/commands/rails.ts@@ -0,0 +1,20 @@+import type { Command } from 'commander'+import { detectProject } from '../context.js'+import { dockerComposeExec } from '../docker.js'++// Run any Rails command. Short for `spree exec bin/rails …`.+// spree rails runner 'puts Rails.env'+// spree rails db:migrate+// spree rails routes -g products+export function registerRailsCommand(program: Command): void {+ program+ .command('rails')+ .description('Run a Rails command (`bin/rails …`) inside the web container')+ .argument('<args...>', 'arguments to pass to bin/rails')+ .allowUnknownOption(true)+ .passThroughOptions(true)+ .action(async (args: string[]) => {+ const ctx = detectProject()+ await dockerComposeExec(['bin/rails', ...args], ctx.projectDir)+ })+}diff --git a/packages/cli/src/commands/rake.ts b/packages/cli/src/commands/rake.tsnew file mode 100644index 0000000000..e270156838--- /dev/null+++ b/packages/cli/src/commands/rake.ts@@ -0,0 +1,21 @@+import type { Command } from 'commander'+import { detectProject } from '../context.js'+import { dockerComposeExec } from '../docker.js'++// Run a rake task inside the web container. Variadic: anything after the+// task name is forwarded verbatim, including `KEY=value` rake args and flags.+// spree rake spree:channels:full_upgrade+// spree rake spree:price_history:seed+// spree rake db:rollback STEP=2+export function registerRakeCommand(program: Command): void {+ program+ .command('rake')+ .description('Run a rake task (`bin/rake …`) inside the web container')+ .argument('<args...>', 'task name and arguments')+ .allowUnknownOption(true)+ .passThroughOptions(true)+ .action(async (args: string[]) => {+ const ctx = detectProject()+ await dockerComposeExec(['bin/rake', ...args], ctx.projectDir)+ })+}diff --git a/packages/cli/src/commands/task.ts b/packages/cli/src/commands/task.tsnew file mode 100644index 0000000000..da7add1d39--- /dev/null+++ b/packages/cli/src/commands/task.ts@@ -0,0 +1,22 @@+import type { Command } from 'commander'+import { detectProject } from '../context.js'+import { dockerComposeExec } from '../docker.js'++// Shortcut for `spree rake spree:<name>` — most rake tasks a Spree dev runs+// are in the `spree:` namespace, so this saves the prefix.+// spree task search:reindex → bin/rake spree:search:reindex+// spree task channels:full_upgrade+// spree task price_history:seed+export function registerTaskCommand(program: Command): void {+ program+ .command('task')+ .description('Run a Spree rake task (auto-prefixes `spree:`)')+ .argument('<name>', 'task name (without `spree:` prefix)')+ .argument('[args...]', 'arguments to pass to the task')+ .allowUnknownOption(true)+ .passThroughOptions(true)+ .action(async (name: string, args: string[]) => {+ const ctx = detectProject()+ await dockerComposeExec(['bin/rake', `spree:${name}`, ...args], ctx.projectDir)+ })+}diff --git a/packages/cli/src/docker.ts b/packages/cli/src/docker.tsindex 98be42668a..f4a2f21e53 100644--- a/packages/cli/src/docker.ts+++ b/packages/cli/src/docker.ts@@ -32,11 +32,38 @@ export async function rakeTask(.trim()}-export async function railsConsole(projectDir: string): Promise<void> {- await execa('docker', ['compose', 'exec', 'web', 'bin/rails', 'c'], {- cwd: projectDir,- stdio: 'inherit',- })+export interface DockerComposeExecOptions {+ service?: string+ tty?: boolean+ env?: Record<string, string>+}++// Run a command inside a service container. The foundation for `spree exec`,+// `spree rails`, `spree bundle`, `spree rake`, and `spree console`.+//+// Defaults to the `web` service and an interactive TTY. Pass `tty: false`+// (which adds `-T`) for non-interactive callers that capture stdout — those+// should use `rakeTask` above, which already does this.+//+// stdio is inherited so the command behaves transparently: a Rails console+// stays interactive, a `bundle add` prints progress, an error exits with the+// inner command's exit code.+export async function dockerComposeExec(+ argv: string[],+ projectDir: string,+ options: DockerComposeExecOptions = {},+): Promise<void> {+ const { service = 'web', tty = true, env } = options+ const args = ['compose', 'exec']+ if (!tty) args.push('-T')+ if (env) {+ for (const [key, value] of Object.entries(env)) {+ args.push('-e', `${key}=${value}`)+ }+ }+ args.push(service, ...argv)++ await execa('docker', args, { cwd: projectDir, stdio: 'inherit' })}export async function streamLogs(service: string, projectDir: string): Promise<void> {diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.tsindex 27c47d9fcb..ab1320b7a9 100644--- a/packages/cli/src/index.ts+++ b/packages/cli/src/index.ts@@ -1,15 +1,20 @@import { Command } from 'commander'import pc from 'picocolors'import { registerApiKeyCommand } from './commands/api-key.js'+import { registerBundleCommand } from './commands/bundle.js'import { registerConsoleCommand } from './commands/console.js'import { registerDevCommand } from './commands/dev.js'import { registerEjectCommand } from './commands/eject.js'+import { registerExecCommand } from './commands/exec.js'import { registerInitCommand } from './commands/init.js'import { registerLogsCommand } from './commands/logs.js'import { registerOpenCommand } from './commands/open.js'+import { registerRailsCommand } from './commands/rails.js'+import { registerRakeCommand } from './commands/rake.js'import { registerSampleDataCommand } from './commands/sample-data.js'import { registerSeedCommand } from './commands/seed.js'import { registerStopCommand } from './commands/stop.js'+import { registerTaskCommand } from './commands/task.js'import { registerUpdateCommand } from './commands/update.js'import { registerUserCommand } from './commands/user.js'@@ -17,19 +22,33 @@ const program = new Command().name('spree').description('CLI for managing Spree Commerce projects').version('2.0.0-beta.6')+ // Required by passThroughOptions on subcommands (exec/rails/bundle/rake/task)+ // so flags like `ls -la` or `bin/rails routes -g foo` reach the inner command+ // instead of being parsed as options of the spree subcommand.+ .enablePositionalOptions()+// Lifecycle / setupregisterInitCommand(program)registerDevCommand(program)registerStopCommand(program)registerUpdateCommand(program)registerLogsCommand(program)+registerEjectCommand(program)++// Run things inside the container+registerExecCommand(program)+registerRailsCommand(program)+registerBundleCommand(program)+registerRakeCommand(program)+registerTaskCommand(program)registerConsoleCommand(program)++// Spree-specific helpersregisterUserCommand(program)registerApiKeyCommand(program)registerOpenCommand(program)registerSeedCommand(program)registerSampleDataCommand(program)-registerEjectCommand(program)program.exitOverride()