@vitrine-kit/vitrine 0.3.1 → 0.4.1

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

@@ -0,0 +1,56 @@
+// Vendure server config. DB: Postgres (DATABASE_URL) or the embedded better-sqlite3
+// in dev (zero-config, §18 equivalent). Superadmin — from env (change it for prod).
+// The Stripe plugin is wired in at tier=full with payments.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DefaultJobQueuePlugin, DefaultSearchPlugin, type VendureConfig } from '@vendure/core';
+import { AssetServerPlugin } from '@vendure/asset-server-plugin';
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+const IS_DEV = process.env.NODE_ENV !== 'production';
+
+function dbConnectionOptions(): VendureConfig['dbConnectionOptions'] {
+  const url = process.env.DATABASE_URL;
+  if (url) {
+    return { type: 'postgres', url, synchronize: IS_DEV } as VendureConfig['dbConnectionOptions'];
+  }
+  if (!IS_DEV) {
+    // In production there's no silent fallback to SQLite (§18).
+    throw new Error('[vitrine] DATABASE_URL is required in production');
+  }
+  // dev zero-config: embedded SQLite (no DB server).
+  return {
+    type: 'better-sqlite3',
+    database: path.join(dirname, '.vitrine', 'vendure.sqlite'),
+    synchronize: true,
+  } as VendureConfig['dbConnectionOptions'];
+}
+
+export const config: VendureConfig = {
+  apiOptions: {
+    port: Number(process.env.VENDURE_PORT ?? 3001),
+    adminApiPath: 'admin-api',
+    shopApiPath: 'shop-api',
+  },
+  authOptions: {
+    tokenMethod: ['bearer', 'cookie'],
+    superadminCredentials: {
+      identifier: process.env.VENDURE_SUPERADMIN_USERNAME ?? 'superadmin',
+      // dev default; for prod you must set VENDURE_SUPERADMIN_PASSWORD.
+      password: process.env.VENDURE_SUPERADMIN_PASSWORD ?? 'superadmin',
+    },
+    cookieOptions: { secret: process.env.VENDURE_COOKIE_SECRET ?? 'dev-cookie-secret' },
+  },
+  dbConnectionOptions: dbConnectionOptions(),
+  paymentOptions: {
+    paymentMethodHandlers: [
+      // + StripePlugin handler (env STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET) for tier=full with payments.
+    ],
+  },
+  plugins: [
+    DefaultJobQueuePlugin.init({}),
+    DefaultSearchPlugin.init({ bufferUpdates: false }),
+    AssetServerPlugin.init({ route: 'assets', assetUploadDir: path.join(dirname, 'static', 'assets') }),
+    // StripePlugin.init({ storeCustomersInStripe: true }),
+  ],
+};

package/kit/templates/base/files/.claude/commands/add-feature.md

@@ -0,0 +1,18 @@
+---
+description: Add a feature from the Vitrine registry and style it
+argument-hint: <feature>
+---
+
+Add the `$ARGUMENTS` feature to the project:
+
+1. `vitrine list` — check that the feature is available and not yet installed (show the list).
+2. `vitrine add $ARGUMENTS` — copies files, registers slots/blueprint, merges in
+   env and dependencies, updates `site.config.ts`, `vitrine.json`, and the table in `CLAUDE.md`.
+   The feature's dependencies are pulled in automatically.
+3. If the feature added keys to `.env.example` — suggest filling them in `.env`.
+4. `vitrine design apply` — style the new feature for the current brand (only if `/design`
+   has an export; otherwise skip).
+5. `pnpm typecheck` (or `pnpm build`) — make sure the build is green.
+6. Don't edit generated files by hand. Remind the user to commit the changes.
+
+To remove a feature — `vitrine remove <feature>` (only for `removable` ones).

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

@@ -0,0 +1,14 @@
+---
+description: Apply the design from /design to the tokens (vitrine design apply)
+---
+
+Apply the client design:
+
+1. Check that the `/design` folder has a brand export (something besides `README.md`: tokens,
+   screenshots, assets). If it's empty — ask the user to add the export and stop.
+2. `vitrine design apply` — a wrapper over Claude Code: it sets ONLY the CSS variable values
+   in `theme/client.css`, without touching logic/data/routing/structure. The token set is closed.
+3. Show the `theme/client.css` diff and briefly describe the palette/typography/spacing changes.
+4. The step is idempotent — re-running converges. Run it again if needed.
+
+If Claude Code isn't found in PATH — point to it via `--bin` or `VITRINE_CLAUDE_BIN`.

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

@@ -0,0 +1,15 @@
+---
+description: Check project consistency and fix discrepancies
+---
+
+Check the project's health:
+
+1. `vitrine doctor` — reconciles `vitrine.json` ↔ files ↔ packages (`package.json`) ↔ env (`.env.example`).
+2. Work through the output. Each issue has a suggested fix:
+   - missing file/slot/provider/dependency → `vitrine add <feature>` (reinstalls and regenerates);
+   - version in the repo ≠ registry → `vitrine update <feature>`;
+   - feature not found in the registry → `vitrine kit update`;
+   - missing env key → add it to `.env.example`/`.env`;
+   - no design-instruction block in `CLAUDE.md` → refresh it (`kit update` brings it).
+3. Apply the fixes (prefer CLI commands over hand edits), then re-run `vitrine doctor`
+   until it's green. Report anything left that needs a user decision (e.g. secrets).

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

@@ -0,0 +1,15 @@
+---
+description: First-time project setup — dependencies, env, start the dev server
+---
+
+Bring this Vitrine project up locally. Work step by step, stop on errors:
+
+1. Check Node >= 20 (`node -v`). If lower, ask to upgrade (Node 20 LTS).
+2. `pnpm install` (the `@vitrine-kit/*` packages are public on npm — no token needed).
+3. If there's no `.env` — `cp .env.example .env`. Go through the keys and suggest what to fill in
+   (production requires a real `DATABASE_URL`; dev has a SQLite fallback).
+4. Start the dev server; see `README.md` for backend specifics:
+   - Payload: `pnpm dev` → storefront `http://localhost:3000`, admin `/admin`.
+   - Vendure: `pnpm vendure` (Shop API on :3001, separate terminal) + `pnpm dev` (:3000).
+5. Make sure the page opens. Briefly report the status and the next step
+   (`/design` for branding or `/add-feature` for features).

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

@@ -0,0 +1,16 @@
+---
+description: Update Vitrine features (kit update → diff → update → doctor)
+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
+   (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).
+4. `vitrine update $ARGUMENTS` — 3-way merge (base = your snapshot in `.vitrine/originals/`).
+   Without an argument it updates all features.
+5. If the merge produced conflicts — open the files with git markers (`<<<<<<<` / `=======` / `>>>>>>>`),
+   resolve them by hand, keeping both the client's edit and the new version from the registry.
+6. `vitrine doctor` — check consistency. Run `pnpm build` and report the result.

package/kit/templates/base/files/.gitattributes

@@ -0,0 +1,12 @@
+# Normalize line endings to LF — keeps `vitrine update` 3-way merges clean on Windows
+# (.vitrine/originals and the registry are LF; a CRLF working tree would look all-changed).
+* text=auto eol=lf
+
+# Binary assets — no normalization.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary

package/kit/templates/base/files/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+This project is a storefront built on **Vitrine** (an agentic starter kit). The canonical guide for
+the AI agent and the full CLI command reference live in [`CLAUDE.md`](./CLAUDE.md). Read it
+before working.
+
+In short:
+
+- All starter-kit operations go through the `vitrine` CLI (`add` / `remove` / `list` /
+  `update` / `diff` / `doctor` / `kit update` / `design apply`), not manual edits.
+  The full command table is in `CLAUDE.md`.
+- **Don't edit generated/managed files** (`lib/slots.ts`, `lib/payments.ts`,
+  `lib/blueprint.ts`, the managed regions of `site.config.ts`, `vitrine.json`, the feature table in
+  `CLAUDE.md`, `.env*`) — the CLI overwrites them from state.
+- **Design = token values only** in `theme/client.css` (via `vitrine design apply`):
+  don't touch logic/data/routing/component structure.
+- **The user makes commits** — don't commit without an explicit request.
+
+Ready-made flows for Claude Code are the slash commands in [`.claude/commands/`](./.claude/commands)
+(`/setup`, `/add-feature`, `/design`, `/update`, `/doctor`).

package/kit/templates/base/files/app/(frontend)/categories/[slug]/page.tsx

@@ -0,0 +1,28 @@
+// Category listing. Filtered by category slug via the CatalogSource contract.
+import { notFound } from 'next/navigation';
+import { Slot } from '@vitrine-kit/core/react';
+import { getCatalogSource } from '@/lib/adapter';
+import { loadCategories, loadProducts } from '@/lib/catalog/data';
+import { ProductGrid } from '@/components/catalog/ProductGrid';
+
+interface PageProps {
+  params: Promise<{ slug: string }>;
+}
+
+export default async function CategoryPage({ params }: PageProps) {
+  const { slug } = await params;
+  const source = await getCatalogSource();
+  const category = (await loadCategories(source)).find((c) => c.slug === slug);
+  if (!category) notFound();
+
+  const products = await loadProducts(source, { category: slug });
+
+  return (
+    <div className="flex flex-col gap-section">
+      <Slot name="category.header" category={category} />
+      <h1 className="font-heading text-fg">{category.title}</h1>
+      <ProductGrid products={products} />
+      <Slot name="category.below-products" />
+    </div>
+  );
+}

package/kit/templates/base/files/app/(frontend)/layout.tsx

@@ -0,0 +1,32 @@
+// Root storefront layout (route group (frontend)). The Payload admin lives in
+// its own route group (payload) with its own layout — so there's no root app/layout,
+// and each group renders its own <html> (the Payload 3 + Next pattern).
+import type { ReactNode } from 'react';
+import type { Metadata } from 'next';
+import '../globals.css';
+import { siteConfig } from '@/site.config';
+import { registerSlots } from '@/lib/slots';
+import { Slot } from '@vitrine-kit/core/react';
+import { SiteHeader } from '@/components/layout/SiteHeader';
+import { SiteFooter } from '@/components/layout/SiteFooter';
+
+// Register installed features' slots (lib/slots.ts is generated by the CLI).
+registerSlots();
+
+export const metadata: Metadata = {
+  title: { default: 'Vitrine', template: '%s · Vitrine' },
+};
+
+export default function FrontendLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang={siteConfig.i18n.defaultLocale}>
+      <body className="min-h-screen bg-bg font-sans text-fg antialiased">
+        <Slot name="global.banner-top" />
+        <SiteHeader />
+        <main className="mx-auto w-full max-w-container px-gutter py-section">{children}</main>
+        <SiteFooter />
+        <Slot name="global.body-end" />
+      </body>
+    </html>
+  );
+}

package/kit/templates/base/files/app/(frontend)/page.tsx

@@ -0,0 +1,27 @@
+// Storefront home: catalog listing. Data via the CatalogSource contract
+// (backend-agnostic); the grid is the catalog feature's component.
+import { Slot } from '@vitrine-kit/core/react';
+import { getCatalogSource } from '@/lib/adapter';
+import { loadProducts } from '@/lib/catalog/data';
+import { ProductGrid } from '@/components/catalog/ProductGrid';
+
+export default async function HomePage() {
+  const source = await getCatalogSource();
+  const products = await loadProducts(source, { perPage: 12 });
+
+  return (
+    <div className="flex flex-col gap-section">
+      <Slot name="home.hero" />
+      <section aria-labelledby="catalog-heading" className="flex flex-col gap-gutter">
+        <h1 id="catalog-heading" className="font-heading text-fg">
+          Catalog
+        </h1>
+        <Slot name="catalog.grid-top" />
+        <ProductGrid products={products} />
+        <Slot name="catalog.grid-bottom" />
+      </section>
+      <Slot name="home.sections" />
+      <Slot name="home.bottom" />
+    </div>
+  );
+}

package/kit/templates/base/files/app/(frontend)/products/[slug]/page.tsx

@@ -0,0 +1,43 @@
+// Product page. ProductView (the product-page feature) hosts the product.* slots.
+// Metadata and JSON-LD come from the seo feature.
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { getCatalogSource } from '@/lib/adapter';
+import { loadProduct } from '@/lib/catalog/data';
+import { ProductView } from '@/components/product/ProductView';
+import { buildProductMetadata } from '@/lib/seo/metadata';
+import { productJsonLd } from '@/lib/seo/jsonld';
+import { JsonLd } from '@/components/seo/JsonLd';
+import { baseUrl } from '@/lib/site';
+
+interface PageProps {
+  params: Promise<{ slug: string }>;
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { slug } = await params;
+  const source = await getCatalogSource();
+  const product = await loadProduct(source, slug);
+  if (!product) return {};
+  const meta = buildProductMetadata(product, { baseUrl });
+  return {
+    title: meta.title,
+    description: meta.description,
+    alternates: meta.canonical ? { canonical: meta.canonical } : undefined,
+    openGraph: meta.openGraph,
+  };
+}
+
+export default async function ProductPage({ params }: PageProps) {
+  const { slug } = await params;
+  const source = await getCatalogSource();
+  const product = await loadProduct(source, slug);
+  if (!product) notFound();
+
+  return (
+    <>
+      <JsonLd data={productJsonLd(product, { baseUrl })} />
+      <ProductView product={product} />
+    </>
+  );
+}

package/kit/templates/base/files/app/globals.css

@@ -0,0 +1,6 @@
+/* The client's token values are set by the design step (vitrine design apply). */
+@import '../theme/client.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

package/kit/templates/base/files/components/layout/SiteFooter.tsx

@@ -0,0 +1,15 @@
+// Storefront footer. Hosts the global.footer slot.
+import { Slot } from '@vitrine-kit/core/react';
+
+export function SiteFooter() {
+  return (
+    <footer className="mt-section border-t border-border">
+      <div className="mx-auto max-w-container px-gutter py-section text-muted-fg">
+        <Slot
+          name="global.footer"
+          fallback={<p>© {new Date().getFullYear()}</p>}
+        />
+      </div>
+    </footer>
+  );
+}

package/kit/templates/base/files/components/layout/SiteHeader.tsx

@@ -0,0 +1,23 @@
+// Storefront header. Hosts the global.header-nav slot (where the catalog feature's
+// CategoryNav mounts) and passes it categories from the active CatalogSource.
+import { Slot } from '@vitrine-kit/core/react';
+import { getCatalogSource } from '@/lib/adapter';
+
+export async function SiteHeader() {
+  const source = await getCatalogSource();
+  const categories = await source.listCategories();
+
+  return (
+    <header className="border-b border-border">
+      <div className="mx-auto flex max-w-container items-center justify-between gap-gutter px-gutter py-unit">
+        <a href="/" className="font-heading text-fg">
+          <Slot name="global.header-start" fallback={<span>Vitrine</span>} />
+        </a>
+        <Slot name="global.header-nav" categories={categories} />
+        <div className="flex items-center gap-unit">
+          <Slot name="global.header-actions" />
+        </div>
+      </div>
+    </header>
+  );
+}

package/kit/templates/base/files/design/README.md

@@ -0,0 +1,9 @@
+# /design — export from Claude Design
+
+Drop your design export here (React/HTML/CSS, tokens, screenshots) and run
+`vitrine design apply`. The AI step reads this folder and the instruction from `CLAUDE.md`,
+then sets **only the token values** in `theme/client.css` (palette, typography, spacing, radii,
+shadows).
+
+This folder is isolated from behavior: its contents don't affect logic, data, routing, or a11y —
+only the look, via tokens. Re-running the design step is safe.

package/kit/templates/base/files/lib/site.ts

@@ -0,0 +1,10 @@
+// Aggregated site parameters from site.config + env. Safe to import on both
+// the server and the client (public values only).
+import { siteConfig } from '@/site.config';
+
+/** Base URL for canonical/OG. Overridden by NEXT_PUBLIC_SITE_URL. */
+export const baseUrl = process.env.NEXT_PUBLIC_SITE_URL ?? 'http://localhost:3000';
+
+export const currency = siteConfig.i18n.currency;
+export const defaultLocale = siteConfig.i18n.defaultLocale;
+export const locales = siteConfig.i18n.locales;

package/kit/templates/base/files/next.config.mjs

@@ -0,0 +1,7 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  output: 'standalone',
+};
+
+// backend-payload overwrites this file (wraps it in withPayload).
+export default nextConfig;

package/kit/templates/base/files/postcss.config.mjs

@@ -0,0 +1,7 @@
+/** @type {import('postcss-load-config').Config} */
+export default {
+  plugins: {
+    'tailwindcss': {},
+    'autoprefixer': {},
+  },
+};

package/kit/templates/base/files/tailwind.config.ts

@@ -0,0 +1,13 @@
+// The client's Tailwind: the Vitrine preset maps classes to the token contract's
+// CSS variables (--vt-*). The variable values live in theme/client.css (design step).
+import type { Config } from 'tailwindcss';
+import { vitrinePreset } from '@vitrine-kit/contracts';
+
+export default {
+  presets: [vitrinePreset as Partial<Config>],
+  content: [
+    './app/**/*.{ts,tsx}',
+    './components/**/*.{ts,tsx}',
+    './lib/**/*.{ts,tsx}',
+  ],
+} satisfies Config;

package/kit/templates/base/files/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "strict": true,
+    "noEmit": true,
+    "allowJs": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "incremental": true,
+    "baseUrl": ".",
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"],
+      "@payload-config": ["./payload.config.ts"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules", ".vitrine"]
+}

package/kit/templates/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "//": "We typecheck only the pure template files (contracts + node) — the zero-config critical logic and the mappers. Files that import Next/Payload are checked when the client is instantiated (the stack is installed there).",
+  "include": [
+    "backend-payload/files/lib/adapter/db-decision.ts",
+    "backend-payload/files/lib/adapter/db-ping.ts",
+    "backend-payload/files/lib/adapter/payload-types.ts",
+    "backend-payload/files/lib/adapter/map.ts",
+    "backend-payload/files/lib/seed/demo.ts",
+    "backend-payload/files/lib/seed/guards.ts",
+    "backend-vendure/files/lib/adapter/vendure-types.ts",
+    "backend-vendure/files/lib/adapter/map.ts"
+  ]
+}

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@vitrine-kit/vitrine",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Vitrine CLI — feature install primitive, init (wizard), add, update, doctor, design apply.",
   "license": "MIT",
   "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
   "bin": {
     "vitrine": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "kit"
   ],
   "publishConfig": {
     "access": "public"
@@ -21,11 +25,11 @@
   "dependencies": {
     "@clack/prompts": "^0.8.2",
     "commander": "^12.1.0",
-    "@vitrine-kit/contracts": "1.2.0"
+    "@vitrine-kit/contracts": "1.2.1"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --clean",
-    "typecheck": "tsc --noEmit",
+    "build": "node scripts/generate-kit-versions.mjs && tsup src/index.ts --format esm --clean && node scripts/copy-kit.mjs",
+    "typecheck": "node scripts/generate-kit-versions.mjs && tsc --noEmit",
     "test": "vitest run --passWithNoTests"
   }
 }