@vitrine-kit/vitrine 0.4.3 → 0.5.0

package/kit/templates/backend-payload/files/lib/adapter/product-query.ts

@@ -0,0 +1,126 @@
+// Pure ProductQuery helpers — filter/sort in memory after the adapter loads products.
+// Price lives on variants, so Payload cannot ORDER BY price in SQL without a denormalized
+// field; this keeps the contract honest for catalog-sized datasets.
+import type { Product, ProductQuery, ProductSort } from '@vitrine-kit/contracts';
+
+export function parseProductSort(value: string | undefined | null): ProductSort | undefined {
+  if (value === 'newest' || value === 'price-asc' || value === 'price-desc' || value === 'relevance') {
+    return value;
+  }
+  return undefined;
+}
+
+/** Parse `?size=S&size=L&color=Black` style params into ProductQuery.filters. */
+export function parseProductFilters(
+  params: Record<string, string | string[] | undefined>,
+  facetKeys: string[] = ['size', 'color'],
+): Record<string, string[]> | undefined {
+  const filters: Record<string, string[]> = {};
+  for (const key of facetKeys) {
+    const raw = params[key];
+    if (raw == null) continue;
+    const values = (Array.isArray(raw) ? raw : [raw])
+      .flatMap((v) => String(v).split(','))
+      .map((v) => v.trim())
+      .filter(Boolean);
+    if (values.length) filters[key] = [...new Set(values)];
+  }
+  return Object.keys(filters).length ? filters : undefined;
+}
+
+export function parsePriceBound(
+  value: string | string[] | undefined | null,
+): number | undefined {
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (raw == null || raw === '') return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return undefined;
+  // URL values are major currency units ($); ProductQuery uses minor units.
+  return Math.round(n * 100);
+}
+
+/** Aggregate option values present on the given products (for toolbar facets). */
+export function collectOptionFacets(products: Product[]): Record<string, string[]> {
+  const buckets = new Map<string, Set<string>>();
+  for (const p of products) {
+    for (const v of p.variants) {
+      if (!v.options) continue;
+      for (const [key, val] of Object.entries(v.options)) {
+        if (!val) continue;
+        let set = buckets.get(key);
+        if (!set) {
+          set = new Set();
+          buckets.set(key, set);
+        }
+        set.add(val);
+      }
+    }
+  }
+  const out: Record<string, string[]> = {};
+  for (const [key, set] of [...buckets.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    out[key] = [...set].sort((a, b) => a.localeCompare(b));
+  }
+  return out;
+}
+
+function matchesFilters(product: Product, filters: Record<string, string[]>): boolean {
+  for (const [key, wanted] of Object.entries(filters)) {
+    if (!wanted.length) continue;
+    const has = product.variants.some((v) => {
+      const actual = v.options?.[key];
+      return actual != null && wanted.includes(actual);
+    });
+    if (!has) return false;
+  }
+  return true;
+}
+
+function matchesSearch(product: Product, term: string): boolean {
+  const q = term.trim().toLowerCase();
+  if (!q) return true;
+  const hay = `${product.title} ${product.description ?? ''} ${product.slug}`.toLowerCase();
+  return hay.includes(q);
+}
+
+function priceOf(product: Product): number {
+  return product.priceRange?.min ?? product.variants[0]?.price ?? Number.POSITIVE_INFINITY;
+}
+
+function matchesPrice(product: Product, priceMin?: number, priceMax?: number): boolean {
+  if (priceMin == null && priceMax == null) return true;
+  // A product matches if any variant price falls in range (merchandising expectation).
+  return product.variants.some((v) => {
+    if (priceMin != null && v.price < priceMin) return false;
+    if (priceMax != null && v.price > priceMax) return false;
+    return true;
+  });
+}
+
+/** Apply search / filters / sort that the DB layer cannot express cheaply. */
+export function applyProductQuery(products: Product[], query: ProductQuery = {}): Product[] {
+  let out = products;
+  if (query.search?.trim()) {
+    out = out.filter((p) => matchesSearch(p, query.search!));
+  }
+  if (query.filters && Object.keys(query.filters).length > 0) {
+    out = out.filter((p) => matchesFilters(p, query.filters!));
+  }
+  if (query.priceMin != null || query.priceMax != null) {
+    out = out.filter((p) => matchesPrice(p, query.priceMin, query.priceMax));
+  }
+  const sort = query.sort ?? 'newest';
+  if (sort === 'price-asc') {
+    out = [...out].sort((a, b) => priceOf(a) - priceOf(b));
+  } else if (sort === 'price-desc') {
+    out = [...out].sort((a, b) => priceOf(b) - priceOf(a));
+  } else if (sort === 'relevance' && query.search?.trim()) {
+    const q = query.search.trim().toLowerCase();
+    out = [...out].sort((a, b) => {
+      const aTitle = a.title.toLowerCase().startsWith(q) ? 0 : a.title.toLowerCase().includes(q) ? 1 : 2;
+      const bTitle = b.title.toLowerCase().startsWith(q) ? 0 : b.title.toLowerCase().includes(q) ? 1 : 2;
+      return aTitle - bTitle || a.title.localeCompare(b.title);
+    });
+  }
+  // newest: keep adapter order (typically -createdAt)
+  return out;
+}

package/kit/templates/backend-payload/files/lib/seed/admin.ts

@@ -3,7 +3,7 @@
 // to the console once.
 import { randomBytes } from 'node:crypto';
 import type { Payload } from 'payload';
-import { shouldRunDevTask } from './guards.js';
+import { seedOnBootEnabled, shouldRunDevTask } from './guards.js';
 
 function randomPassword(length = 16): string {
   return randomBytes(length).toString('base64url').slice(0, length);
@@ -12,7 +12,9 @@ function randomPassword(length = 16): string {
 export async function ensureDevAdmin(payload: Payload): Promise<void> {
   const isProd = process.env.NODE_ENV === 'production';
   const { totalDocs } = await payload.count({ collection: 'users' });
-  if (!shouldRunDevTask({ isProd, existingCount: totalDocs })) return;
+  if (!shouldRunDevTask({ isProd, existingCount: totalDocs, seedOnBoot: seedOnBootEnabled() })) {
+    return;
+  }
 
   // `.env.example` ships `DEV_ADMIN_EMAIL=` / `DEV_ADMIN_PASSWORD=` — empty strings must
   // not win over defaults (`??` only treats null/undefined).
@@ -24,6 +26,8 @@ export async function ensureDevAdmin(payload: Payload): Promise<void> {
     overrideAccess: true,
   });
   payload.logger.warn(
-    `[vitrine] DEV ADMIN ${email} / ${password} — development only, change before deploying`,
+    isProd
+      ? `[vitrine] BOOTSTRAP ADMIN ${email} / ${password} — change immediately (SEED_ON_BOOT)`
+      : `[vitrine] DEV ADMIN ${email} / ${password} — development only, change before deploying`,
   );
 }

package/kit/templates/backend-payload/files/lib/seed/guards.ts

@@ -1,5 +1,18 @@
-// Pure guards for zero-config dev procedures (§18). The seed and dev admin run
-// ONLY in dev AND when the collection is empty — idempotent and never in prod.
-export function shouldRunDevTask(opts: { isProd: boolean; existingCount: number }): boolean {
-  return !opts.isProd && opts.existingCount === 0;
+// Pure guards for zero-config bootstrap (§18). Seed and dev admin run when the
+// collection is empty — in development always, and in production only when
+// SEED_ON_BOOT=1 (docker compose demos / first boot).
+export function shouldRunDevTask(opts: {
+  isProd: boolean;
+  existingCount: number;
+  /** When true, allow empty-collection bootstrap even in production. */
+  seedOnBoot?: boolean;
+}): boolean {
+  if (opts.existingCount !== 0) return false;
+  if (!opts.isProd) return true;
+  return Boolean(opts.seedOnBoot);
+}
+
+export function seedOnBootEnabled(): boolean {
+  const v = process.env.SEED_ON_BOOT?.trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes';
 }

package/kit/templates/backend-payload/files/lib/seed/locales.ts

@@ -0,0 +1,53 @@
+// Optional non-default locale copy for the demo seed when Payload localization is enabled.
+// Slugs stay shared; only human-readable fields differ.
+
+export const demoLocales = {
+  categories: {
+    apparel: {
+      ru: {
+        title: 'Одежда',
+        description: 'Повседневные слои — футболки, худи и носки с выбором размера.',
+      },
+    },
+    accessories: {
+      ru: {
+        title: 'Аксессуары',
+        description: 'Кепки и сумки, которые дополняют простой мерч-ассортимент.',
+      },
+    },
+  },
+  products: {
+    'classic-tee': {
+      ru: {
+        title: 'Классическая футболка',
+        description:
+          'Прямой крой из хлопка средней плотности на каждый день. Мягкая фактура, усиленные плечевые швы. Выберите размер ниже и добавьте в корзину.',
+        seo: {
+          title: 'Классическая футболка — хлопок',
+          description: 'Демо-товар одежды с несколькими размерами.',
+        },
+      },
+    },
+    'zip-hoodie': {
+      ru: {
+        title: 'Худи на молнии',
+        description:
+          'Флисовое худи на молнии с объёмным капюшоном. Носите поверх футболки или застёгнутым в прохладный вечер.',
+        seo: {
+          title: 'Худи на молнии — флис',
+          description: 'Демо-худи с размерами и галереей.',
+        },
+      },
+    },
+    'logo-cap': {
+      ru: {
+        title: 'Кепка с логотипом',
+        description: 'Структурированная кепка с регулируемой застёжкой. Выберите цвет и добавьте в корзину.',
+        seo: {
+          title: 'Кепка с логотипом',
+          description: 'Демо-аксессуар с цветовыми вариантами.',
+        },
+      },
+    },
+  },
+} as const;

package/kit/templates/backend-payload/files/lib/seed/run.ts

@@ -1,28 +1,61 @@
-// Demo seed (§18.2): runs from Payload's onInit. Idempotent (guarded by
-// shouldRunDevTask: dev only + empty collection). Images are local
-// placeholders from seed-assets/ (no network).
+// Demo seed (§18.2): runs from Payload's onInit. Idempotent (empty collection +
+// dev, or SEED_ON_BOOT=1 in production). Images are local placeholders from
+// seed-assets/ (no network). Optional RU copy is applied when localization is on.
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { Payload } from 'payload';
 import { demoCategories, demoProducts } from './demo.js';
-import { shouldRunDevTask } from './guards.js';
+import { seedOnBootEnabled, shouldRunDevTask } from './guards.js';
+import { demoLocales } from './locales.js';
 import { plainToRichText } from './richtext.js';
 
-const seedAssets = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../seed-assets');
+// Prefer cwd/seed-assets so Docker runtime (standalone) can ship the folder next to server.js.
+const seedAssets = [
+  path.resolve(process.cwd(), 'seed-assets'),
+  path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../seed-assets'),
+].find((p) => existsSync(p));
 
 export async function seedDemo(payload: Payload): Promise<void> {
   const isProd = process.env.NODE_ENV === 'production';
   const { totalDocs } = await payload.count({ collection: 'products' });
-  if (!shouldRunDevTask({ isProd, existingCount: totalDocs })) return;
+  if (!shouldRunDevTask({ isProd, existingCount: totalDocs, seedOnBoot: seedOnBootEnabled() })) {
+    return;
+  }
+  if (!seedAssets) {
+    payload.logger.warn('[vitrine] demo seed skipped — seed-assets/ not found');
+    return;
+  }
+
+  const localization = payload.config.localization;
+  const defaultLocale = localization?.defaultLocale ?? 'en';
+  const enabledLocales = new Set(
+    (localization?.locales ?? []).map((l) => (typeof l === 'string' ? l : l.code)),
+  );
+  const createOpts = localization ? { locale: defaultLocale as 'en' } : {};
 
   const categoryId = new Map<string, string | number>();
   for (const c of demoCategories) {
     const doc = await payload.create({
       collection: 'categories',
       data: { slug: c.slug, title: c.title, description: c.description },
+      ...createOpts,
       overrideAccess: true,
     });
     categoryId.set(c.slug, doc.id);
+    const localized = demoLocales.categories[c.slug];
+    if (localized && localization) {
+      for (const [locale, copy] of Object.entries(localized)) {
+        if (locale === defaultLocale || !enabledLocales.has(locale)) continue;
+        await payload.update({
+          collection: 'categories',
+          id: doc.id,
+          data: { title: copy.title, description: copy.description },
+          locale: locale as 'en',
+          overrideAccess: true,
+        });
+      }
+    }
   }
 
   for (const p of demoProducts) {
@@ -52,8 +85,26 @@ export async function seedDemo(payload: Payload): Promise<void> {
           image: coverId,
         },
       },
+      ...createOpts,
       overrideAccess: true,
     });
+    const localized = demoLocales.products[p.slug];
+    if (localized && localization) {
+      for (const [locale, copy] of Object.entries(localized)) {
+        if (locale === defaultLocale || !enabledLocales.has(locale)) continue;
+        await payload.update({
+          collection: 'products',
+          id: product.id,
+          data: {
+            title: copy.title,
+            description: plainToRichText(copy.description),
+            seo: { title: copy.seo.title, description: copy.seo.description },
+          },
+          locale: locale as 'en',
+          overrideAccess: true,
+        });
+      }
+    }
     for (const v of p.variants) {
       await payload.create({
         collection: 'variants',

package/kit/templates/backend-payload/files/next.config.mjs

@@ -5,6 +5,13 @@ import { withPayload } from '@payloadcms/next/withPayload';
 // Baseline security headers (OWASP A05: Security Misconfiguration) applied to every route.
 // The CSP below is a conservative starting point — payment providers with client-side widgets
 // (e.g. embedded Stripe Elements) may need their domains added to script-src/connect-src/frame-src.
+// Next.js `pnpm dev` (webpack eval source maps / Fast Refresh) needs 'unsafe-eval'; omit it in
+// production builds so the shipped CSP stays tighter.
+const isDev = process.env.NODE_ENV !== 'production';
+const scriptSrc = isDev
+  ? "script-src 'self' 'unsafe-inline' 'unsafe-eval'"
+  : "script-src 'self' 'unsafe-inline'";
+
 const securityHeaders = [
   { key: 'X-Content-Type-Options', value: 'nosniff' },
   { key: 'X-Frame-Options', value: 'DENY' },
@@ -13,8 +20,7 @@ const securityHeaders = [
   { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
   {
     key: 'Content-Security-Policy',
-    value:
-      "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https:; frame-ancestors 'none';",
+    value: `default-src 'self'; ${scriptSrc}; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https:; frame-ancestors 'none';`,
   },
 ];
 

package/kit/templates/backend-payload/files/payload.config.ts

@@ -1,25 +1,47 @@
 // The client's Payload 3 config. Collections are assembled by the blueprint (base +
 // additive feature extensions, lib/blueprint.ts — generated by the CLI). The DB is
-// chosen zero-config (db.ts → §18.1). onInit runs the demo seed and dev admin (dev only).
+// chosen zero-config (db.ts → §18.1). onInit runs the demo seed and boot admin.
+// Email adapter is optional — present when the `email` feature is installed.
+// Localization mirrors site.config i18n when more than one locale is configured.
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { buildConfig } from 'payload';
 import type { CollectionConfig } from 'payload';
+import { buildConfig } from 'payload';
 import { lexicalEditor } from '@payloadcms/richtext-lexical';
 import sharp from 'sharp';
 import { collections } from './lib/blueprint.js';
 import { resolveDbAdapter } from './lib/adapter/db.js';
 import { seedDemo } from './lib/seed/run.js';
 import { ensureDevAdmin } from './lib/seed/admin.js';
+import { siteConfig } from './site.config.js';
 
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 
-const payloadSecret = process.env.PAYLOAD_SECRET;
+// Empty string from `cp .env.example .env` must not count as set (?? only skips null/undefined).
+const payloadSecret = process.env.PAYLOAD_SECRET?.trim() || undefined;
 if (!payloadSecret && process.env.NODE_ENV === 'production') {
   // No silent fallback to the dev secret in production (mirrors the Vendure DATABASE_URL guard).
   throw new Error('[vitrine] PAYLOAD_SECRET is required in production');
 }
 
+async function loadEmailAdapter(): Promise<unknown> {
+  try {
+    const mod = await import('./lib/email/adapter.js');
+    return await mod.resolveEmailAdapter();
+  } catch {
+    return undefined;
+  }
+}
+
+const email = await loadEmailAdapter();
+
+const locales = siteConfig.i18n.locales.filter(Boolean);
+const localization = {
+  locales: locales.length > 0 ? locales : ['en'],
+  defaultLocale: siteConfig.i18n.defaultLocale || locales[0] || 'en',
+  fallback: true,
+};
+
 export default buildConfig({
   admin: {
     user: 'users',
@@ -30,6 +52,8 @@ export default buildConfig({
   secret: payloadSecret ?? 'dev-secret-change-me',
   db: await resolveDbAdapter(),
   sharp,
+  localization,
+  ...(email ? { email: email as never } : {}),
   typescript: { outputFile: path.resolve(dirname, 'payload-types.ts') },
   async onInit(payload) {
     await seedDemo(payload);

package/kit/templates/backend-vendure/files/Dockerfile

@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1
 # Vitrine client image on Vendure. One image, two commands (compose): the Vendure server
-# (`node dist/index.js`) and the Next storefront (`next start`). Target — VPS.
+# (`pnpm exec tsx src/index.ts`) and the Next storefront (`pnpm start`). Target — VPS.
 FROM node:20-alpine AS base
 RUN corepack enable && corepack prepare pnpm@9.15.0 --activate
 WORKDIR /app

package/kit/templates/backend-vendure/files/docker-compose.yml

@@ -20,7 +20,8 @@ services:
     build:
       context: .
     restart: unless-stopped
-    command: ['node', 'dist/index.js']
+    # tsx is available from the full build image; avoids a separate server compile step.
+    command: ['pnpm', 'exec', 'tsx', 'src/index.ts']
     environment:
       NODE_ENV: production
       DATABASE_URL: postgres://vitrine:${POSTGRES_PASSWORD:-vitrine}@db:5432/vitrine

package/kit/templates/backend-vendure/files/lib/adapter/product-query.ts

@@ -0,0 +1,126 @@
+// Pure ProductQuery helpers — filter/sort in memory after the adapter loads products.
+// Price lives on variants, so Payload cannot ORDER BY price in SQL without a denormalized
+// field; this keeps the contract honest for catalog-sized datasets.
+import type { Product, ProductQuery, ProductSort } from '@vitrine-kit/contracts';
+
+export function parseProductSort(value: string | undefined | null): ProductSort | undefined {
+  if (value === 'newest' || value === 'price-asc' || value === 'price-desc' || value === 'relevance') {
+    return value;
+  }
+  return undefined;
+}
+
+/** Parse `?size=S&size=L&color=Black` style params into ProductQuery.filters. */
+export function parseProductFilters(
+  params: Record<string, string | string[] | undefined>,
+  facetKeys: string[] = ['size', 'color'],
+): Record<string, string[]> | undefined {
+  const filters: Record<string, string[]> = {};
+  for (const key of facetKeys) {
+    const raw = params[key];
+    if (raw == null) continue;
+    const values = (Array.isArray(raw) ? raw : [raw])
+      .flatMap((v) => String(v).split(','))
+      .map((v) => v.trim())
+      .filter(Boolean);
+    if (values.length) filters[key] = [...new Set(values)];
+  }
+  return Object.keys(filters).length ? filters : undefined;
+}
+
+export function parsePriceBound(
+  value: string | string[] | undefined | null,
+): number | undefined {
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (raw == null || raw === '') return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return undefined;
+  // URL values are major currency units ($); ProductQuery uses minor units.
+  return Math.round(n * 100);
+}
+
+/** Aggregate option values present on the given products (for toolbar facets). */
+export function collectOptionFacets(products: Product[]): Record<string, string[]> {
+  const buckets = new Map<string, Set<string>>();
+  for (const p of products) {
+    for (const v of p.variants) {
+      if (!v.options) continue;
+      for (const [key, val] of Object.entries(v.options)) {
+        if (!val) continue;
+        let set = buckets.get(key);
+        if (!set) {
+          set = new Set();
+          buckets.set(key, set);
+        }
+        set.add(val);
+      }
+    }
+  }
+  const out: Record<string, string[]> = {};
+  for (const [key, set] of [...buckets.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    out[key] = [...set].sort((a, b) => a.localeCompare(b));
+  }
+  return out;
+}
+
+function matchesFilters(product: Product, filters: Record<string, string[]>): boolean {
+  for (const [key, wanted] of Object.entries(filters)) {
+    if (!wanted.length) continue;
+    const has = product.variants.some((v) => {
+      const actual = v.options?.[key];
+      return actual != null && wanted.includes(actual);
+    });
+    if (!has) return false;
+  }
+  return true;
+}
+
+function matchesSearch(product: Product, term: string): boolean {
+  const q = term.trim().toLowerCase();
+  if (!q) return true;
+  const hay = `${product.title} ${product.description ?? ''} ${product.slug}`.toLowerCase();
+  return hay.includes(q);
+}
+
+function priceOf(product: Product): number {
+  return product.priceRange?.min ?? product.variants[0]?.price ?? Number.POSITIVE_INFINITY;
+}
+
+function matchesPrice(product: Product, priceMin?: number, priceMax?: number): boolean {
+  if (priceMin == null && priceMax == null) return true;
+  // A product matches if any variant price falls in range (merchandising expectation).
+  return product.variants.some((v) => {
+    if (priceMin != null && v.price < priceMin) return false;
+    if (priceMax != null && v.price > priceMax) return false;
+    return true;
+  });
+}
+
+/** Apply search / filters / sort that the DB layer cannot express cheaply. */
+export function applyProductQuery(products: Product[], query: ProductQuery = {}): Product[] {
+  let out = products;
+  if (query.search?.trim()) {
+    out = out.filter((p) => matchesSearch(p, query.search!));
+  }
+  if (query.filters && Object.keys(query.filters).length > 0) {
+    out = out.filter((p) => matchesFilters(p, query.filters!));
+  }
+  if (query.priceMin != null || query.priceMax != null) {
+    out = out.filter((p) => matchesPrice(p, query.priceMin, query.priceMax));
+  }
+  const sort = query.sort ?? 'newest';
+  if (sort === 'price-asc') {
+    out = [...out].sort((a, b) => priceOf(a) - priceOf(b));
+  } else if (sort === 'price-desc') {
+    out = [...out].sort((a, b) => priceOf(b) - priceOf(a));
+  } else if (sort === 'relevance' && query.search?.trim()) {
+    const q = query.search.trim().toLowerCase();
+    out = [...out].sort((a, b) => {
+      const aTitle = a.title.toLowerCase().startsWith(q) ? 0 : a.title.toLowerCase().includes(q) ? 1 : 2;
+      const bTitle = b.title.toLowerCase().startsWith(q) ? 0 : b.title.toLowerCase().includes(q) ? 1 : 2;
+      return aTitle - bTitle || a.title.localeCompare(b.title);
+    });
+  }
+  // newest: keep adapter order (typically -createdAt)
+  return out;
+}

package/kit/templates/backend-vendure/files/lib/adapter/vendure-catalog.ts

@@ -4,6 +4,7 @@
 import type { CatalogSource, Category, Product, ProductQuery } from '@vitrine-kit/contracts';
 import { shopQuery } from './graphql.js';
 import { mapVendureCollection, mapVendureProduct } from './map.js';
+import { applyProductQuery } from './product-query.js';
 import type { VCollection, VProduct } from './vendure-types.js';
 
 const PRODUCT_FIELDS = `
@@ -19,24 +20,30 @@ export class VendureCatalogSource implements CatalogSource {
     const take = query.perPage ?? 24;
     const skip = ((query.page ?? 1) - 1) * take;
 
-    if (query.category) {
+    let products: Product[];
+    if (query.search?.trim()) {
+      products = await this.search(query.search.trim(), query.locale);
+    } else if (query.category) {
       const { data } = await shopQuery<{ collection: { productVariants: { items: { product: VProduct }[] } } | null }>(
         `query ($slug: String!) { collection(slug: $slug) { productVariants { items { product { ${PRODUCT_FIELDS} } } } } }`,
         { slug: query.category },
       );
       const byId = new Map<string, VProduct>();
       for (const it of data.collection?.productVariants.items ?? []) byId.set(String(it.product.id), it.product);
-      return [...byId.values()].map(mapVendureProduct);
+      products = [...byId.values()].map(mapVendureProduct);
+    } else {
+      const { data } = await shopQuery<{ products: { items: VProduct[] } }>(
+        `query ($take: Int, $skip: Int) { products(options: { take: $take, skip: $skip }) { items { ${PRODUCT_FIELDS} } } }`,
+        { take: Math.max(take, 100), skip: 0 },
+      );
+      products = data.products.items.map(mapVendureProduct);
     }
 
-    const { data } = await shopQuery<{ products: { items: VProduct[] } }>(
-      `query ($take: Int, $skip: Int) { products(options: { take: $take, skip: $skip }) { items { ${PRODUCT_FIELDS} } } }`,
-      { take, skip },
-    );
-    return data.products.items.map(mapVendureProduct);
+    products = applyProductQuery(products, query);
+    return products.slice(skip, skip + take);
   }
 
-  async getProduct(slug: string): Promise<Product | null> {
+  async getProduct(slug: string, _locale?: string): Promise<Product | null> {
     const { data } = await shopQuery<{ product: VProduct | null }>(
       `query ($slug: String!) { product(slug: $slug) { ${PRODUCT_FIELDS} } }`,
       { slug },
@@ -44,19 +51,19 @@ export class VendureCatalogSource implements CatalogSource {
     return data.product ? mapVendureProduct(data.product) : null;
   }
 
-  async listCategories(): Promise<Category[]> {
+  async listCategories(_locale?: string): Promise<Category[]> {
     const { data } = await shopQuery<{ collections: { items: VCollection[] } }>(
       `{ collections { items { id slug name description parent { id } } } }`,
     );
     return data.collections.items.map(mapVendureCollection);
   }
 
-  async search(term: string): Promise<Product[]> {
+  async search(term: string, locale?: string): Promise<Product[]> {
     const { data } = await shopQuery<{ search: { items: { slug: string }[] } }>(
       `query ($term: String!) { search(input: { term: $term, groupByProduct: true }) { items { slug } } }`,
       { term },
     );
-    const products = await Promise.all(data.search.items.map((i) => this.getProduct(i.slug)));
+    const products = await Promise.all(data.search.items.map((i) => this.getProduct(i.slug, locale)));
     return products.filter((p): p is Product => p !== null);
   }
 }

package/kit/templates/base/files/.claude/commands/update.md

@@ -5,7 +5,7 @@ argument-hint: [feature]
 
 Update features from the registry while keeping the client's edits:
 
-1. `vitrine kit update` — refresh the local registry/templates cache from GitHub
+1. `vitrine kit update` — refresh the local registry/templates cache from npm
    (needs `gh` and `tar`; cache in `~/.vitrine`).
 2. `vitrine kit status` — see what's newer than what's installed.
 3. `vitrine diff $ARGUMENTS` — preview changes without writing (for each feature being updated).