@spree/cli 3.0.0 → 3.0.2

package/dist/templates/dashboard-starter/AGENTS.md

@@ -0,0 +1,71 @@
+# Agent Instructions
+
+This is the Spree admin dashboard for this project — a Vite + React app. The
+shell (routes, chrome, resource pages) ships in `@spree/dashboard`; this
+project holds your customizations.
+
+Full docs: https://spreecommerce.org/docs/developer/dashboard/overview
+
+## Imports
+
+Import from `@spree/dashboard` — it re-exports the framework and the design
+system, so there is no need to work out which package an export lives in.
+
+```ts
+import { defineDashboardPlugin, useStore, Button, ResourceTable } from '@spree/dashboard'
+```
+
+`@spree/dashboard-core` and `@spree/dashboard-ui` stay importable for the few
+components that exist in both: the design system's takes data as props, the
+framework's fetches its own. The facade gives you the framework's.
+
+## Where code goes
+
+Organized by kind, one file per resource — the same layout `@spree/dashboard`
+uses internally.
+
+| Directory | Holds | Naming |
+|---|---|---|
+| `src/plugins.ts` | Registrations only: nav, routes, slots, tables | one file |
+| `src/pages/` | One screen each | `brands.tsx` |
+| `src/hooks/` | Admin API wrappers | `use-brands.ts` |
+| `src/tables/` | `defineTable` calls | `brands.tsx` |
+| `src/schemas/` | Zod schema + `FormValues` | `brand.ts` |
+| `src/slots/` | Widgets injected into built-in pages | `product-brand-card.tsx` |
+| `src/locales/` | Your `admin.*` translation keys | `en.json` |
+
+Adding a resource touches one file in each directory. Keep `plugins.ts` a map
+of what exists, not an implementation.
+
+## Rules
+
+- **The Admin API is the only data source.** Never reach into the Rails app or
+  import server-rendered HTML. A missing endpoint is added to the API first.
+- **Wrap API calls in a hook.** Components never call `adminClient` directly.
+- **Query keys are store-scoped.** Build them with `useResourceKey`; a bare
+  `['brands']` key leaks one store's data into another after a store switch.
+- **Writes go through `useResourceMutation`**, which maps 422 responses onto
+  form fields instead of firing a toast.
+- **Every visible string goes through i18next** — page titles, column labels,
+  buttons, empty states, toasts. Never hardcode English in JSX or in a table
+  definition. Add each new key to every locale file the project ships.
+- **Schemas hold canonical values, never labels.** Build `{ value, label }`
+  pairs at render time so labels stay translatable.
+- **Never embed an SDK entity type in a form-values type.** React Hook Form
+  walks every nested key and the SDK's object graph overflows the TypeScript
+  compiler.
+- **A sortable or filterable column must be allowlisted for Ransack** on the
+  model, or the request fails at runtime.
+- **Destructive actions that fire straight from a click need a confirm** —
+  `useConfirm()` with `variant: 'destructive'`.
+
+## Checks
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm test        # unit tests (Vitest, Node environment)
+pnpm build
+```
+
+Test the logic between the UI and the API — query keys, payload mapping, permission predicates. Do not write tests that render a component to assert its markup; that tests React. Use `pnpm test:e2e` when a browser is genuinely needed.

package/dist/templates/dashboard-starter/README.md

@@ -12,7 +12,7 @@ cp .env.example .env.local   # optional — VITE_API_PROXY_TARGET if your API is
 pnpm dev                     # http://localhost:5173
 ```
 
-The dev server proxies `/api` to your Rails backend so the SPA stays same-origin — don't set `VITE_SPREE_API_URL` in dev (it switches the SDK to absolute cross-origin URLs, which breaks on CORS and the auth cookie).
+The dev server proxies `/api` to your server API so the SPA stays same-origin — don't set `VITE_SPREE_API_URL` in dev (it switches the SDK to absolute cross-origin URLs, which breaks on CORS and the auth cookie).
 
 Sign in with an admin account — authentication is interactive (JWT + refresh cookie). No API keys belong in `.env.local`: every `VITE_`-prefixed value is compiled into the client bundle.
 
@@ -29,8 +29,119 @@ That's the whole install. `spreeDashboardPlugin()` (see `vite.config.ts`) discov
 
 `src/plugins.ts` is yours — register nav entries, routes, slot widgets, and table columns with `defineDashboardPlugin` from `@spree/dashboard-core`. Same API the distributed plugins use; see the [customization quickstart](https://spreecommerce.org/docs/developer/dashboard/customization/quickstart).
 
+**Import everything from `@spree/dashboard`.** It re-exports the framework
+(registries, providers, hooks, the Admin API client) and the design system, so
+you never have to remember which package a given export lives in:
+
+```ts
+import { defineDashboardPlugin, useStore, Button, ResourceTable } from '@spree/dashboard'
+```
+
+`@spree/dashboard-core` and `@spree/dashboard-ui` remain installed and
+importable when you want them directly — a handful of components exist in
+both, where the design system's version takes its data as props and the
+framework's fetches its own. The facade gives you the framework's.
+
+Brands will not be your only customization, so this starter ships the same layout `@spree/dashboard` uses internally: organized by kind, one file per resource.
+
+```
+src/
+├── plugins.ts     registrations only — the map of what you added
+├── pages/         one file per screen        brands.tsx, brand-detail.tsx
+├── hooks/         one file per resource      use-brands.ts
+├── tables/        one file per resource      brands.tsx
+├── schemas/       one file per resource      brand.ts
+├── slots/         widgets injected into      product-brand-card.tsx
+│                  built-in pages
+└── locales/       your translations          en.json
+```
+
+Adding a resource touches one file in each directory, which is why the split
+is by kind rather than by feature — you always know where a thing lives.
+
+**`pages/`** — a screen composes `ResourceLayout` with a `PageHeader` and
+renders a `ResourceTable` or a form. It does not fetch data itself. Register
+it as a route in `plugins.ts`:
+
+```tsx
+import { BrandsPage } from './pages/brands'
+
+defineDashboardPlugin({
+  routes: [{ key: 'brands', path: '/brands', component: BrandsPage }],
+})
+```
+
+**`hooks/`** — named `use-<resource>.ts`, each wrapping the Admin API so
+components never call `adminClient` directly. Build query keys with
+`useResourceKey`, which scopes them to the current store; a bare `['brands']`
+key leaks one store's data into another after a store switch. Use
+`useResourceMutation` for writes — it maps 422 responses onto form fields
+instead of firing a toast.
+
+```ts
+import { adminClient, useResourceKey } from '@spree/dashboard-core'
+import { useQuery } from '@tanstack/react-query'
+
+export function useBrands() {
+  return useQuery({
+    queryKey: useResourceKey('brands'),
+    queryFn: () => adminClient.request('GET', '/brands'),
+  })
+}
+```
+
+**`tables/`** — one `defineTable` call per resource, at module load, imported
+from `plugins.ts` so it registers before the router mounts. Column changes to
+built-in tables (products, orders, customers) live here too. A column marked
+`sortable` or `filterable` must be allowlisted for Ransack on the model, or
+the request fails.
+
+**`schemas/`** — the Zod schema, its inferred `FormValues` type and defaults.
+Hold canonical values only, never label strings: build `{ value, label }`
+pairs at render time so labels stay translatable. Never embed an SDK entity
+type (`Product`, `Order`) in a form-values type — React Hook Form walks every
+nested key and the SDK's object graph overflows the TypeScript compiler.
+Inline a short single-file schema instead.
+
+**`slots/`** — components you inject into pages the dashboard already
+renders, one file per widget. A slot widget takes its data from the slot's
+context and, on a page with a host form, binds its inputs to that form with
+`useHostForm()` rather than saving anything itself.
+
+**`locales/`** — every visible string goes through i18next, including column
+labels and button text. Keys live under a top-level `admin` object. Load the
+bundle once at the top of `plugins.ts`:
+
+```ts
+import { i18n } from '@spree/dashboard-core'
+import en from './locales/en.json'
+
+i18n.addResourceBundle('en', 'translation', en, true, true)
+```
+
+## Test
+
+Vitest and Playwright are configured. Playwright needs its browser once:
+
+```bash
+pnpm exec playwright install chromium
+```
+
+```bash
+pnpm test        # unit tests: src/**/*.test.ts
+pnpm test:e2e    # end-to-end, through a browser
+```
+
+Unit tests run in Node rather than a DOM, because what is worth testing here is the logic between your UI and the API: query keys, payload mapping, permission predicates. Rendering a component to assert its markup tests React, not your feature — use an end-to-end test when you need a browser.
+
+`pnpm test:e2e` starts the dashboard itself and reuses one you already have running, but expects your API to be up (`spree dev`). Point it elsewhere with `E2E_BASE_URL`.
+
 ## Build & deploy
 
+The app root `Dockerfile` already builds this package and bakes it into the production image, available at `https://yourstore.com/dashboard` URL.
+
+If you want to host it elsewhere, eg. on CDN you can build it manually.
+
 ```bash
 pnpm build    # static assets in dist/
 ```

package/dist/templates/dashboard-starter/package.json

@@ -8,13 +8,18 @@
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --fix ."
   },
   "dependencies": {
-    "@spree/admin-sdk": "^1.0.0-beta.1",
-    "@spree/dashboard": "^1.0.0-beta.1",
+    "@spree/admin-sdk": "^1.0.0-beta.2",
+    "@spree/dashboard": "^1.0.0-beta.3",
+    "@spree/dashboard-core": "^1.0.0-beta.3",
+    "@spree/dashboard-ui": "^1.0.0-beta.3",
     "@tanstack/react-query": "^5.100.9",
     "@tanstack/react-router": "^1.169.2",
     "react": "^19.2.6",
@@ -22,11 +27,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
+    "@playwright/test": "^1.59.1",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "typescript": "~6.0.3",
-    "vite": "^8.0.16"
+    "vite": "^8.0.16",
+    "vitest": "^4.1.5"
   },
   "packageManager": "pnpm@11.13.1"
 }

package/dist/templates/dashboard-starter/playwright.config.ts

@@ -0,0 +1,37 @@
+import { defineConfig, devices } from '@playwright/test'
+
+// End-to-end tests run against your own stack: `spree dev` for the API, and
+// the dev server Playwright starts below. Point them somewhere else with
+// E2E_BASE_URL — a preview build, or a deployed environment.
+const BASE_URL = process.env.E2E_BASE_URL || 'http://localhost:5173'
+
+export default defineConfig({
+  testDir: './e2e',
+  // One worker: specs share a database, so parallel runs interfere unless
+  // every spec creates its own records under a unique name.
+  fullyParallel: false,
+  workers: 1,
+  retries: process.env.CI ? 2 : 0,
+  timeout: 30_000,
+  expect: { timeout: 10_000 },
+  reporter: process.env.CI ? [['github'], ['html', { open: 'never' }]] : 'list',
+
+  use: {
+    baseURL: BASE_URL,
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+
+  // Starts the dashboard for the run and reuses one you already have open.
+  // The API is expected to be running separately (`spree dev`).
+  webServer: process.env.E2E_BASE_URL
+    ? undefined
+    : {
+        command: 'pnpm dev --port 5173 --strictPort',
+        url: BASE_URL,
+        reuseExistingServer: true,
+        timeout: 60_000,
+      },
+})

package/dist/templates/dashboard-starter/src/locales/en.json

@@ -0,0 +1,3 @@
+{
+  "admin": {}
+}

package/dist/templates/dashboard-starter/src/plugins.ts

@@ -4,20 +4,30 @@
 // shared registries — the same API distributed plugins use. Imported once
 // from main.tsx, before the dashboard renders.
 //
+// Keep this file a map of what you added: the registrations live here, the
+// implementations live in pages/, hooks/, tables/ and schemas/. See the
+// README for what belongs where.
+//
 // Example:
 //
 //   import { defineDashboardPlugin } from '@spree/dashboard'
 //   import { AnalyticsPage } from './pages/analytics'
 //
 //   defineDashboardPlugin({
-//     nav: [{ key: 'analytics', label: 'Analytics', path: '/analytics', position: 60 }],
+//     nav: [{
+//       key: 'analytics',
+//       label: i18n.t('admin.analytics.nav'),
+//       path: '/analytics',
+//       position: 650,
+//     }],
 //     routes: [{ key: 'analytics', path: '/analytics', component: AnalyticsPage }],
 //   })
 //
-// Building custom pages? Add the framework and design-system packages first —
-// `pnpm add @spree/dashboard-core @spree/dashboard-ui` — then import hooks,
-// providers, and UI primitives from those.
-//
 // Docs: https://spreecommerce.org/docs/developer/dashboard/customization/quickstart
 
-export {}
+import { i18n } from '@spree/dashboard'
+import en from './locales/en.json'
+
+// Merges your `admin.*` keys into the dashboard's namespace without dropping
+// its own. Add a bundle per locale you ship.
+i18n.addResourceBundle('en', 'translation', en, true, true)

package/dist/templates/dashboard-starter/tsconfig.json

@@ -8,6 +8,7 @@
     "types": ["vite/client"],
     "skipLibCheck": true,
     "moduleResolution": "bundler",
+    "resolveJsonModule": true,
     "verbatimModuleSyntax": true,
     "moduleDetection": "force",
     "noEmit": true,

package/dist/templates/dashboard-starter/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    // Node, not jsdom: what is worth unit-testing here is the logic between
+    // your UI and the API — query keys, payload mapping, permission
+    // predicates. Rendering a component to assert its markup tests React.
+    // Reach for a browser through Playwright instead (`pnpm test:e2e`).
+    environment: 'node',
+    include: ['src/**/*.{test,spec}.{ts,tsx}'],
+    exclude: ['node_modules/**', 'e2e/**', 'dist/**'],
+  },
+})

package/dist/templates/seller-dashboard-starter/AGENTS.md

@@ -0,0 +1,75 @@
+# Agent Instructions
+
+This is the Spree seller panel for this marketplace — a Vite + React app. The
+shell ships in `@spree/seller-dashboard`; this project holds your
+customizations. Sellers manage their own catalog and orders here.
+
+Full docs: https://spreecommerce.org/docs/developer/dashboard/overview
+
+The admin dashboard is the reference implementation: when a component is
+useful to both, extract it rather than copying it.
+
+## Imports
+
+Import from `@spree/seller-dashboard` — it re-exports the framework and the design
+system, so there is no need to work out which package an export lives in.
+
+```ts
+import { defineDashboardPlugin, useStore, Button, ResourceTable } from '@spree/seller-dashboard'
+```
+
+`@spree/dashboard-core` and `@spree/dashboard-ui` stay importable for the few
+components that exist in both: the design system's takes data as props, the
+framework's fetches its own. The facade gives you the framework's.
+
+## Where code goes
+
+Organized by kind, one file per resource — the same layout the panel
+uses internally.
+
+| Directory | Holds | Naming |
+|---|---|---|
+| `src/plugins.ts` | Registrations only: nav, slots, tables | one file |
+| `src/pages/` | One screen each | `brands.tsx` |
+| `src/hooks/` | Admin API wrappers | `use-brands.ts` |
+| `src/tables/` | `defineTable` calls | `brands.tsx` |
+| `src/schemas/` | Zod schema + `FormValues` | `brand.ts` |
+| `src/slots/` | Widgets injected into built-in pages | `seller-payout-card.tsx` |
+| `src/locales/` | Your `admin.*` translation keys | `en.json` |
+
+Adding a resource touches one file in each directory. Keep `plugins.ts` a map
+of what exists, not an implementation.
+
+## Rules
+
+- **The Admin API is the only data source.** Never reach into the Rails app or
+  import server-rendered HTML. Seller endpoints are scoped to the signed-in
+  seller by the server, never by the client. A missing endpoint is added to the API first.
+- **Wrap API calls in a hook.** Components never call `adminClient` directly.
+- **Query keys are store-scoped.** Build them with `useResourceKey`; a bare
+  `['brands']` key leaks one store's data into another after a store switch.
+- **Writes go through `useResourceMutation`**, which maps 422 responses onto
+  form fields instead of firing a toast.
+- **Every visible string goes through i18next** — page titles, column labels,
+  buttons, empty states, toasts. Never hardcode English in JSX or in a table
+  definition. Add each new key to every locale file the project ships.
+- **Schemas hold canonical values, never labels.** Build `{ value, label }`
+  pairs at render time so labels stay translatable.
+- **Never embed an SDK entity type in a form-values type.** React Hook Form
+  walks every nested key and the SDK's object graph overflows the TypeScript
+  compiler.
+- **A sortable or filterable column must be allowlisted for Ransack** on the
+  model, or the request fails at runtime.
+- **Destructive actions that fire straight from a click need a confirm** —
+  `useConfirm()` with `variant: 'destructive'`.
+
+## Checks
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm test        # unit tests (Vitest, Node environment)
+pnpm build
+```
+
+Test the logic between the UI and the API — query keys, payload mapping, permission predicates. Do not write tests that render a component to assert its markup; that tests React. Use `pnpm test:e2e` when a browser is genuinely needed.

package/dist/templates/seller-dashboard-starter/package.json

@@ -8,13 +8,18 @@
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --fix ."
   },
   "dependencies": {
-    "@spree/seller-dashboard": "^1.0.0-beta.1",
-    "@spree/seller-sdk": "^1.0.0-beta.1",
+    "@spree/seller-dashboard": "^1.0.0-beta.3",
+    "@spree/dashboard-core": "^1.0.0-beta.3",
+    "@spree/dashboard-ui": "^1.0.0-beta.3",
+    "@spree/seller-sdk": "^1.0.0-beta.2",
     "@tanstack/react-query": "^5.100.9",
     "@tanstack/react-router": "^1.169.2",
     "react": "^19.2.6",
@@ -22,11 +27,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
+    "@playwright/test": "^1.59.1",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "typescript": "~6.0.3",
-    "vite": "^8.0.16"
+    "vite": "^8.0.16",
+    "vitest": "^4.1.5"
   },
   "packageManager": "pnpm@11.13.1"
 }

package/dist/templates/seller-dashboard-starter/playwright.config.ts

@@ -0,0 +1,37 @@
+import { defineConfig, devices } from '@playwright/test'
+
+// End-to-end tests run against your own stack: `spree dev` for the API, and
+// the dev server Playwright starts below. Point them somewhere else with
+// E2E_BASE_URL — a preview build, or a deployed environment.
+const BASE_URL = process.env.E2E_BASE_URL || 'http://localhost:5174'
+
+export default defineConfig({
+  testDir: './e2e',
+  // One worker: specs share a database, so parallel runs interfere unless
+  // every spec creates its own records under a unique name.
+  fullyParallel: false,
+  workers: 1,
+  retries: process.env.CI ? 2 : 0,
+  timeout: 30_000,
+  expect: { timeout: 10_000 },
+  reporter: process.env.CI ? [['github'], ['html', { open: 'never' }]] : 'list',
+
+  use: {
+    baseURL: BASE_URL,
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+
+  // Starts the dashboard for the run and reuses one you already have open.
+  // The API is expected to be running separately (`spree dev`).
+  webServer: process.env.E2E_BASE_URL
+    ? undefined
+    : {
+        command: 'pnpm dev --port 5174 --strictPort',
+        url: BASE_URL,
+        reuseExistingServer: true,
+        timeout: 60_000,
+      },
+})

package/dist/templates/seller-dashboard-starter/src/locales/en.json

@@ -0,0 +1,3 @@
+{
+  "admin": {}
+}

package/dist/templates/seller-dashboard-starter/src/plugins.ts

@@ -6,6 +6,11 @@
 // here, the same API distributed plugins use. Imported once from main.tsx,
 // before the panel renders.
 //
+// Keep this file a map of what you added: the registrations live here, the
+// implementations live in pages/, hooks/, tables/ and schemas/ — one file per
+// resource, the same layout the seller panel uses internally. Translations go
+// in locales/ and merge in with `i18n.addResourceBundle`.
+//
 // Example — add a payouts page and drop the built-in team screen:
 //
 //   import { defineDashboardPlugin } from '@spree/seller-dashboard'
@@ -23,8 +28,7 @@
 //
 // Slots the built-in screens expose: `seller.team.actions`, `seller.team.after`.
 //
-// Building custom pages? Add the framework and design-system packages first —
-// `pnpm add @spree/dashboard-core @spree/dashboard-ui` — then import hooks,
-// providers, and UI primitives from those.
+// `@spree/dashboard-core` and `@spree/dashboard-ui` are already installed —
+// import hooks, providers and UI primitives straight from them.
 
 export {}

package/dist/templates/seller-dashboard-starter/tsconfig.json

@@ -8,6 +8,7 @@
     "types": ["vite/client"],
     "skipLibCheck": true,
     "moduleResolution": "bundler",
+    "resolveJsonModule": true,
     "allowImportingTsExtensions": true,
     "verbatimModuleSyntax": true,
     "moduleDetection": "force",

package/dist/templates/seller-dashboard-starter/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    // Node, not jsdom: what is worth unit-testing here is the logic between
+    // your UI and the API — query keys, payload mapping, permission
+    // predicates. Rendering a component to assert its markup tests React.
+    // Reach for a browser through Playwright instead (`pnpm test:e2e`).
+    environment: 'node',
+    include: ['src/**/*.{test,spec}.{ts,tsx}'],
+    exclude: ['node_modules/**', 'e2e/**', 'dist/**'],
+  },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/cli",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "CLI for managing Spree Commerce projects",
   "type": "module",
   "bin": {
@@ -45,7 +45,7 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
     "yaml": "^2.8.4",
-    "@spree/admin-sdk": "^1.0.0-beta.1"
+    "@spree/admin-sdk": "^1.0.0-beta.2"
   },
   "engines": {
     "node": ">=20"