@vitrine-kit/vitrine 0.4.0 → 0.4.1

package/dist/index.js

@@ -2,10 +2,13 @@
 
 // src/index.ts
 import { readFileSync as readFileSync3 } from "fs";
-import { resolve as resolve6 } from "path";
+import { resolve as resolve7 } from "path";
 import { Command } from "commander";
 import * as p from "@clack/prompts";
 
+// src/commands.ts
+import { join as join11, resolve as resolve5 } from "path";
+
 // src/project.ts
 import { existsSync as existsSync2 } from "fs";
 import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
@@ -34,9 +37,12 @@ function readText(p2) {
 function readJson(p2) {
   return JSON.parse(readText(p2));
 }
+function normalizeEol(s) {
+  return s.includes("\r") ? s.replace(/\r\n/g, "\n") : s;
+}
 function writeText(p2, content) {
   mkdirSync(dirname(p2), { recursive: true });
-  writeFileSync(p2, content, "utf8");
+  writeFileSync(p2, normalizeEol(content), "utf8");
 }
 function toPosix(p2) {
   return p2.split("\\").join("/");
@@ -50,6 +56,16 @@ function safeJoin(root, ...segs) {
   }
   return target;
 }
+function assertFeatureName(name) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+    throw new Error(`[vitrine] invalid feature name "${name}"`);
+  }
+}
+function assertSafeRel(p2, what) {
+  if (isAbsolute(p2) || p2.split(/[\\/]/).some((seg) => seg === "..")) {
+    throw new Error(`[vitrine] ${what} "${p2}" must be a relative path without ".."`);
+  }
+}
 function parseEnvKeys(text2) {
   return new Set(
     text2.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#") && l.includes("=")).map((l) => l.split("=")[0]?.trim() ?? "").filter(Boolean)
@@ -137,8 +153,9 @@ function bundledKitRoot() {
 }
 
 // src/cache.ts
-import { cpSync, existsSync as existsSync4, rmSync } from "fs";
+import { cpSync, existsSync as existsSync4, mkdirSync as mkdirSync2, renameSync, rmSync } from "fs";
 import { join as join4, resolve as resolve3 } from "path";
+import { registryIndexSchema } from "@vitrine-kit/contracts";
 function vitrineHome() {
   if (process.env.VITRINE_HOME) return resolve3(process.env.VITRINE_HOME);
   const home = process.env.USERPROFILE ?? process.env.HOME;
@@ -198,11 +215,22 @@ function populateCache(fromDir, opts = {}) {
   }
   const paths = cachePaths(home);
   const oldIndex = readIndex(paths.registry);
-  rmSync(paths.registry, { recursive: true, force: true });
-  cpSync(srcRegistry, paths.registry, { recursive: true });
-  if (existsSync4(srcTemplates)) {
-    rmSync(paths.templates, { recursive: true, force: true });
-    cpSync(srcTemplates, paths.templates, { recursive: true });
+  const staging = join4(home, `.staging-${process.pid}`);
+  try {
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync2(staging, { recursive: true });
+    cpSync(srcRegistry, join4(staging, "registry"), { recursive: true });
+    registryIndexSchema.parse(readJson(join4(staging, "registry", "_index.json")));
+    const hasTemplates = existsSync4(srcTemplates);
+    if (hasTemplates) cpSync(srcTemplates, join4(staging, "templates"), { recursive: true });
+    rmSync(paths.registry, { recursive: true, force: true });
+    renameSync(join4(staging, "registry"), paths.registry);
+    if (hasTemplates) {
+      rmSync(paths.templates, { recursive: true, force: true });
+      renameSync(join4(staging, "templates"), paths.templates);
+    }
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
   }
   const newIndex = readIndex(paths.registry);
   const kitVersion = newIndex?.kitVersion ?? "0.0.0";
@@ -247,7 +275,10 @@ function resolveRegistryRoot(explicit) {
 function createRegistrySource(explicitRoot) {
   const root = resolveRegistryRoot(explicitRoot);
   const cache = /* @__PURE__ */ new Map();
-  const featureDir = (name) => join5(root, name);
+  const featureDir = (name) => {
+    assertFeatureName(name);
+    return join5(root, name);
+  };
   const hasFeature = (name) => existsSync5(join5(featureDir(name), "feature.json"));
   const loadManifest = (name) => {
     const cached = cache.get(name);
@@ -255,6 +286,10 @@ function createRegistrySource(explicitRoot) {
     const file = join5(featureDir(name), "feature.json");
     if (!existsSync5(file)) throw new Error(`[vitrine] feature "${name}" not found in the registry`);
     const manifest = featureManifestSchema.parse(JSON.parse(readText(file)));
+    for (const map of manifest.files) {
+      assertSafeRel(map.from, `feature "${name}": files.from`);
+      assertSafeRel(map.to, `feature "${name}": files.to`);
+    }
     cache.set(name, manifest);
     return manifest;
   };
@@ -269,7 +304,7 @@ function createRegistrySource(explicitRoot) {
 import { join as join7 } from "path";
 
 // src/transaction.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
 import { dirname as dirname5 } from "path";
 var FsTransaction = class {
   backups = [];
@@ -280,8 +315,8 @@ var FsTransaction = class {
   }
   write(path, content) {
     this.snapshot(path);
-    mkdirSync2(dirname5(path), { recursive: true });
-    writeFileSync2(path, content, "utf8");
+    mkdirSync3(dirname5(path), { recursive: true });
+    writeFileSync2(path, normalizeEol(content), "utf8");
   }
   remove(path) {
     this.snapshot(path);
@@ -467,7 +502,7 @@ function renderNeutralTheme() {
 // src/feature-files.ts
 import { join as join6 } from "path";
 function* eachFeatureFile(featDir, map) {
-  const src = join6(featDir, map.from);
+  const src = safeJoin(featDir, map.from);
   if (!exists(src)) return;
   const rels = isDir(src) ? walkRelFiles(src) : [""];
   for (const rel of rels) {
@@ -481,27 +516,33 @@ function* eachFeatureFile(featDir, map) {
 function resolveOrder(names, registry) {
   const order = [];
   const seen = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
   const visit = (name) => {
     if (seen.has(name)) return;
+    if (visiting.has(name)) {
+      throw new Error(`[vitrine] circular registryDependencies involving "${name}"`);
+    }
     if (!registry.hasFeature(name)) {
       throw new Error(`[vitrine] feature "${name}" not found in the registry`);
     }
-    seen.add(name);
+    visiting.add(name);
     const manifest = registry.loadManifest(name);
     for (const dep of manifest.registryDependencies ?? []) visit(dep);
+    visiting.delete(name);
+    seen.add(name);
     order.push(name);
   };
   for (const name of names) visit(name);
   return order;
 }
-function validate(name, manifest, project) {
+function validate(name, manifest, project, present) {
   if (!manifest.tier.includes(project.lock.tier)) {
     throw new Error(
       `[vitrine] feature "${name}" does not support tier "${project.lock.tier}" (only ${manifest.tier.join(", ")})`
     );
   }
   for (const conflict of manifest.conflicts ?? []) {
-    if (project.lock.features[conflict]) {
+    if (present.has(conflict)) {
       throw new Error(`[vitrine] conflict: "${name}" is incompatible with the installed "${conflict}"`);
     }
   }
@@ -510,9 +551,6 @@ function copyFeatureFiles(project, name, manifest, registry, tx) {
   const featDir = registry.featureDir(name);
   const originalsBase = join7(projectPaths(project.root).originals, `${name}@${manifest.kitVersion}`);
   for (const map of manifest.files) {
-    if (!exists(join7(featDir, map.from))) {
-      throw new Error(`[vitrine] feature "${name}": no source "${map.from}"`);
-    }
     for (const file of eachFeatureFile(featDir, map)) {
       const content = readText(file.srcAbs);
       tx.write(safeJoin(project.root, file.repoRel), content);
@@ -574,11 +612,21 @@ function installFeatures(project, names, registry) {
   if (toInstall.length === 0) {
     return { installed: [], skipped: order };
   }
+  const present = new Set(installedNames);
+  for (const name of toInstall) {
+    const manifest = registry.loadManifest(name);
+    validate(name, manifest, project, present);
+    present.add(name);
+    for (const map of manifest.files) {
+      if (!exists(join7(registry.featureDir(name), map.from))) {
+        throw new Error(`[vitrine] feature "${name}": no source "${map.from}"`);
+      }
+    }
+  }
   const tx = new FsTransaction();
   try {
     for (const name of toInstall) {
       const manifest = registry.loadManifest(name);
-      validate(name, manifest, project);
       copyFeatureFiles(project, name, manifest, registry, tx);
       project.lock.features[name] = { version: manifest.kitVersion };
     }
@@ -623,6 +671,20 @@ function removeFeature(project, name, registry) {
     }
     delete project.lock.features[name];
     regenerateDerived(project, registry, tx);
+    const keptKeys = new Set(
+      Object.keys(project.lock.features).flatMap(
+        (other) => (registry.loadManifest(other).env ?? []).map((e) => e.key)
+      )
+    );
+    const stale = (manifest.env ?? []).map((e) => e.key).filter((k) => !keptKeys.has(k));
+    const envPath = projectPaths(project.root).env;
+    if (stale.length > 0 && exists(envPath)) {
+      const lines = readText(envPath).split("\n").filter((l) => {
+        const key = l.includes("=") ? l.split("=")[0]?.trim() : void 0;
+        return !(key && stale.includes(key));
+      });
+      tx.write(envPath, lines.join("\n"));
+    }
     tx.commit();
   } catch (error) {
     tx.rollback();
@@ -637,6 +699,7 @@ import { existsSync as existsSync7, readdirSync as readdirSync2 } from "fs";
 import { delimiter, join as join8 } from "path";
 import { TOKEN_CSS_VARS as TOKEN_CSS_VARS2 } from "@vitrine-kit/contracts";
 var DESIGN_HEADING = "## INSTRUCTION: apply the design from /design";
+var MAX_INSTRUCTION_CHARS = 4e3;
 function findClaudeBin(explicit) {
   const pinned = explicit ?? process.env.VITRINE_CLAUDE_BIN;
   if (pinned) {
@@ -667,7 +730,11 @@ function extractDesignInstruction(claudeMd) {
 }
 function buildDesignPrompt(project) {
   const claudeMd = existsSync7(join8(project.root, "CLAUDE.md")) ? readText(join8(project.root, "CLAUDE.md")) : "";
-  const instruction = extractDesignInstruction(claudeMd) ?? DESIGN_HEADING;
+  let instruction = extractDesignInstruction(claudeMd) ?? DESIGN_HEADING;
+  if (instruction.length > MAX_INSTRUCTION_CHARS) {
+    instruction = `${instruction.slice(0, MAX_INSTRUCTION_CHARS)}
+[\u2026truncated by vitrine: the design instruction exceeds ${MAX_INSTRUCTION_CHARS} chars]`;
+  }
   const tokens = TOKEN_CSS_VARS2.map((v) => `  ${v}`).join("\n");
   return [
     instruction,
@@ -687,6 +754,19 @@ var defaultRunner = ({ bin, args, cwd }) => {
   if (res.error) throw res.error;
   return res.status ?? 0;
 };
+function preflightClaude(bin) {
+  const res = spawnSync(bin, ["--version"], {
+    stdio: "ignore",
+    // .cmd/.bat shims cannot be spawned directly on modern Node — safe here since
+    // the args carry no user input.
+    shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(bin)
+  });
+  if (res.error || res.status !== 0) {
+    throw new Error(
+      `[vitrine] "${bin}" did not answer --version \u2014 Claude Code missing or broken? Reinstall it (npm i -g @anthropic-ai/claude-code) or pass another --bin.`
+    );
+  }
+}
 function planDesignApply(project, opts = {}) {
   const bin = findClaudeBin(opts.bin);
   const prompt = buildDesignPrompt(project);
@@ -704,10 +784,12 @@ function designApply(project, opts = {}, runner = defaultRunner) {
     console.log(`[vitrine] dry-run: ${cmd.bin} -p <prompt ${cmd.prompt.length} chars> --permission-mode acceptEdits`);
     return 0;
   }
+  if (runner === defaultRunner) preflightClaude(cmd.bin);
   return runner(cmd);
 }
 
 // src/doctor.ts
+import { readdirSync as readdirSync3 } from "fs";
 import { join as join9 } from "path";
 function runDoctor(project, registry) {
   const paths = projectPaths(project.root);
@@ -719,12 +801,13 @@ function runDoctor(project, registry) {
   const configText = exists(paths.config) ? readText(paths.config) : "";
   const slotsText = exists(paths.slots) ? readText(paths.slots) : "";
   const paymentsText = exists(paths.payments) ? readText(paths.payments) : "";
+  const claudeText = exists(paths.claude) ? readText(paths.claude) : "";
   for (const core of ["@vitrine-kit/contracts", "@vitrine-kit/core"]) {
     if (!deps[core]) {
       add({ severity: "error", scope: "packages", message: `missing dependency ${core}`, fix: "add it to package.json" });
     }
   }
-  if (exists(paths.claude) && !readText(paths.claude).includes("INSTRUCTION: apply the design")) {
+  if (exists(paths.claude) && !claudeText.includes("INSTRUCTION: apply the design")) {
     add({
       severity: "warn",
       scope: "design",
@@ -732,6 +815,50 @@ function runDoctor(project, registry) {
       fix: "update CLAUDE.md (kit update brings a fresh instruction)"
     });
   }
+  const markerPairs = [
+    { file: "site.config.ts", text: configText, start: "// vitrine:features:start", end: "// vitrine:features:end" },
+    { file: "site.config.ts", text: configText, start: "// vitrine:integrations:start", end: "// vitrine:integrations:end" },
+    ...exists(paths.claude) ? [{ file: "CLAUDE.md", text: claudeText, start: "<!-- vitrine:features:start -->", end: "<!-- vitrine:features:end -->" }] : []
+  ];
+  for (const m of markerPairs) {
+    const si = m.text.indexOf(m.start);
+    const ei = m.text.indexOf(m.end);
+    if (si === -1 || ei === -1 || ei < si) {
+      add({
+        severity: "error",
+        scope: "markers",
+        message: `${m.file}: managed markers "${m.start}" / "${m.end}" are missing or unpaired`,
+        fix: "restore the marker lines \u2014 add/update/remove cannot regenerate without them"
+      });
+    }
+  }
+  if (exists(join9(project.root, ".env"))) {
+    const gi = exists(join9(project.root, ".gitignore")) ? readText(join9(project.root, ".gitignore")) : "";
+    const covered = gi.split("\n").some((l) => /^\.env(\*)?$/.test(l.trim()));
+    if (!covered) {
+      add({
+        severity: "warn",
+        scope: "env",
+        message: '.env exists but .gitignore has no ".env" entry',
+        fix: 'add ".env" to .gitignore \u2014 secrets must not be committed'
+      });
+    }
+  }
+  if (isDir(paths.originals)) {
+    for (const entry of readdirSync3(paths.originals)) {
+      const at = entry.lastIndexOf("@");
+      const name = at > 0 ? entry.slice(0, at) : entry;
+      const version = at > 0 ? entry.slice(at + 1) : "";
+      if (project.lock.features[name]?.version !== version) {
+        add({
+          severity: "warn",
+          scope: "originals",
+          message: `orphaned snapshot "${entry}" (no installed feature@version matches)`,
+          fix: `delete .vitrine/originals/${entry}`
+        });
+      }
+    }
+  }
   for (const [name, pin] of Object.entries(project.lock.features)) {
     const scope = `feature:${name}`;
     if (!registry.hasFeature(name)) {
@@ -948,11 +1075,11 @@ function planUpdate(project, name, registry) {
   const files = [];
   for (const map of manifest.files) {
     for (const file of eachFeatureFile(featDir, map)) {
-      const theirs = readText(file.srcAbs);
-      const oursPath = join10(project.root, file.repoRel);
-      const basePath = join10(originalsBase, file.repoRel);
-      const ours = exists(oursPath) ? readText(oursPath) : null;
-      const base = exists(basePath) ? readText(basePath) : null;
+      const theirs = normalizeEol(readText(file.srcAbs));
+      const oursPath = safeJoin(project.root, file.repoRel);
+      const basePath = safeJoin(originalsBase, file.repoRel);
+      const ours = exists(oursPath) ? normalizeEol(readText(oursPath)) : null;
+      const base = exists(basePath) ? normalizeEol(readText(basePath)) : null;
       if (ours === null) {
         files.push({ to: file.toRel, status: "new", merged: theirs, conflicts: 0 });
       } else if (theirs === base || theirs === ours) {
@@ -995,6 +1122,7 @@ function applyUpdate(project, plan, registry) {
     tx.commit();
   } catch (error) {
     tx.rollback();
+    project.lock.features[plan.feature] = { version: plan.fromVersion };
     throw error;
   }
   if (plan.fromVersion !== plan.toVersion) {
@@ -1011,34 +1139,41 @@ function renderPlan(plan) {
 }
 
 // src/commands.ts
-function requireProject() {
+function requireProject(explicitRoot) {
+  if (explicitRoot) {
+    const root2 = resolve5(explicitRoot);
+    if (!exists(join11(root2, "vitrine.json"))) {
+      throw new Error(`[vitrine] no vitrine.json in "${root2}" (--project must point at a client repo root)`);
+    }
+    return loadProject(root2);
+  }
   const root = findProjectRoot();
   if (!root) {
     throw new Error("[vitrine] vitrine.json not found \u2014 not a Vitrine client repository");
   }
   return loadProject(root);
 }
-function addFeatures(names, registryRoot) {
-  return installFeatures(requireProject(), names, createRegistrySource(registryRoot));
+function addFeatures(names, registryRoot, projectRoot) {
+  return installFeatures(requireProject(projectRoot), names, createRegistrySource(registryRoot));
 }
-function removeFeatureCmd(name, registryRoot) {
-  removeFeature(requireProject(), name, createRegistrySource(registryRoot));
+function removeFeatureCmd(name, registryRoot, projectRoot) {
+  removeFeature(requireProject(projectRoot), name, createRegistrySource(registryRoot));
 }
-function listFeatures(registryRoot) {
-  const project = requireProject();
+function listFeatures(registryRoot, projectRoot) {
+  const project = requireProject(projectRoot);
   const registry = createRegistrySource(registryRoot);
   const installed = Object.keys(project.lock.features);
   const available = registry.listFeatures().filter((name) => !installed.includes(name));
   return { installed, available };
 }
 function designApplyCmd(opts = {}) {
-  return designApply(requireProject(), { bin: opts.bin, dryRun: opts.dryRun });
+  return designApply(requireProject(opts.projectRoot), { bin: opts.bin, dryRun: opts.dryRun });
 }
-function doctorCmd(registryRoot) {
-  return runDoctor(requireProject(), createRegistrySource(registryRoot));
+function doctorCmd(registryRoot, projectRoot) {
+  return runDoctor(requireProject(projectRoot), createRegistrySource(registryRoot));
 }
 function updateFeaturesCmd(names, registryRoot, opts = {}) {
-  const project = requireProject();
+  const project = requireProject(opts.projectRoot);
   const registry = createRegistrySource(registryRoot);
   const targets = names.length > 0 ? names : Object.keys(project.lock.features);
   return targets.map((name) => {
@@ -1048,16 +1183,16 @@ function updateFeaturesCmd(names, registryRoot, opts = {}) {
     return { plan, applied };
   });
 }
-function diffFeatureCmd(name, registryRoot) {
-  return planUpdate(requireProject(), name, createRegistrySource(registryRoot));
+function diffFeatureCmd(name, registryRoot, projectRoot) {
+  return planUpdate(requireProject(projectRoot), name, createRegistrySource(registryRoot));
 }
 
 // src/init.ts
-import { readdirSync as readdirSync3 } from "fs";
-import { join as join12 } from "path";
+import { readdirSync as readdirSync4 } from "fs";
+import { join as join13 } from "path";
 
 // src/kit-versions.generated.ts
-var KIT_VERSION = "0.4.0";
+var KIT_VERSION = "0.4.1";
 var CONTRACTS_VERSION = "1.0.0";
 var CONTRACTS_RANGE = "^1.0.0";
 var CORE_RANGE = "^0.2.0";
@@ -1071,17 +1206,17 @@ var PAYLOAD_RANGE = "^3.0.0";
 
 // src/templates.ts
 import { existsSync as existsSync8 } from "fs";
-import { dirname as dirname6, join as join11 } from "path";
+import { dirname as dirname6, join as join12 } from "path";
 function templatesRoot(registryRoot) {
-  return join11(dirname6(registryRoot), "templates");
+  return join12(dirname6(registryRoot), "templates");
 }
 function hasTemplate(root, name) {
-  return existsSync8(join11(root, name, "files"));
+  return existsSync8(join12(root, name, "files"));
 }
 function copyTemplate(root, name, destRoot) {
-  const filesDir = join11(root, name, "files");
+  const filesDir = join12(root, name, "files");
   const rels = walkRelFiles(filesDir);
-  for (const rel of rels) writeText(join11(destRoot, rel), readText(join11(filesDir, rel)));
+  for (const rel of rels) writeText(join12(destRoot, rel), readText(join12(filesDir, rel)));
   return rels;
 }
 
@@ -1184,6 +1319,9 @@ function clientEnvExample(backend) {
       "# DB. Empty in dev \u2014 built-in SQLite (.vitrine/vendure.sqlite).",
       "DATABASE_URL=",
       "",
+      "# Postgres password for docker compose (db service; compose default: vitrine).",
+      "POSTGRES_PASSWORD=",
+      "",
       "# Vendure Shop API (storefront \u2192 server).",
       "VENDURE_SHOP_API_URL=http://localhost:3001/shop-api",
       "",
@@ -1206,6 +1344,9 @@ function clientEnvExample(backend) {
     "# DB. For local dev you can leave it empty \u2014 a SQLite fallback is used (.vitrine/dev.sqlite).",
     "DATABASE_URL=",
     "",
+    "# Postgres password for docker compose (db service; compose default: vitrine).",
+    "POSTGRES_PASSWORD=",
+    "",
     "# Payload secret (required; generate a random one for prod).",
     "PAYLOAD_SECRET=",
     "",
@@ -1313,10 +1454,10 @@ function scaffoldBase(opts) {
   const backendTemplate = `backend-${backend}`;
   if (hasTemplate(tRoot, backendTemplate)) copyTemplate(tRoot, backendTemplate, root);
   if (!baseCopied) {
-    writeText(join12(root, ".gitignore"), "node_modules/\n.next/\ndist/\n.env\n.env.local\n.vitrine/\n");
+    writeText(join13(root, ".gitignore"), "node_modules/\n.next/\ndist/\n.env\n.env.local\n.vitrine/\n");
   }
   writeText(
-    join12(root, "vitrine.json"),
+    join13(root, "vitrine.json"),
     `${JSON.stringify(
       { kitVersion: KIT_VERSION, contracts: CONTRACTS_VERSION, backend, tier, features: {} },
       null,
@@ -1325,7 +1466,7 @@ function scaffoldBase(opts) {
 `
   );
   writeText(
-    join12(root, "site.config.ts"),
+    join13(root, "site.config.ts"),
     `import type { SiteConfig } from '@vitrine-kit/contracts';
 
 export const siteConfig: SiteConfig = {
@@ -1346,7 +1487,7 @@ export default siteConfig;
 `
   );
   writeText(
-    join12(root, "CLAUDE.md"),
+    join13(root, "CLAUDE.md"),
     `# ${name}
 
 A Vitrine project. Backend: \`${backend}\`, tier: \`${tier}\`.
@@ -1412,16 +1553,16 @@ The step is idempotent: re-running converges and doesn't accumulate cruft.
 - **The user makes commits** \u2014 don't run \`git commit\`/\`git push\` without an explicit request.
 `
   );
-  writeText(join12(root, "README.md"), clientReadme(name, backend, tier));
-  writeText(join12(root, "lib", "slots.ts"), renderSlotsFile([]));
-  writeText(join12(root, "lib", "blueprint.ts"), renderBlueprintFile([]));
-  writeText(join12(root, "theme", "client.css"), renderNeutralTheme());
-  writeText(join12(root, ".env.example"), clientEnvExample(backend));
-  writeText(join12(root, "package.json"), `${JSON.stringify(clientPackageJson(name, backend), null, 2)}
+  writeText(join13(root, "README.md"), clientReadme(name, backend, tier));
+  writeText(join13(root, "lib", "slots.ts"), renderSlotsFile([]));
+  writeText(join13(root, "lib", "blueprint.ts"), renderBlueprintFile([]));
+  writeText(join13(root, "theme", "client.css"), renderNeutralTheme());
+  writeText(join13(root, ".env.example"), clientEnvExample(backend));
+  writeText(join13(root, "package.json"), `${JSON.stringify(clientPackageJson(name, backend), null, 2)}
 `);
 }
 function initProject(opts) {
-  if (exists(opts.root) && readdirSync3(opts.root).length > 0) {
+  if (exists(opts.root) && readdirSync4(opts.root).length > 0) {
     throw new Error(`[vitrine] directory "${opts.root}" is not empty`);
   }
   scaffoldBase(opts);
@@ -1431,22 +1572,21 @@ function initProject(opts) {
 
 // src/kit-update.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync9, mkdtempSync, readdirSync as readdirSync4, statSync as statSync2 } from "fs";
+import { existsSync as existsSync9, mkdtempSync, readdirSync as readdirSync5, rmSync as rmSync4, statSync as statSync2 } from "fs";
 import { tmpdir } from "os";
-import { join as join13, resolve as resolve5 } from "path";
+import { join as join14, resolve as resolve6 } from "path";
 var REPO = "vitrine-kit/vitrine";
 function hasBin(bin) {
   const probe = process.platform === "win32" ? "where" : "which";
   return spawnSync2(probe, [bin], { stdio: "ignore" }).status === 0;
 }
-function acquireFromGh(version) {
+function acquireFromGh(tmp, version) {
   if (!hasBin("gh")) {
     throw new Error("[vitrine] network update needs gh (GitHub CLI), or pass --from <dir>");
   }
   if (!hasBin("tar")) {
     throw new Error("[vitrine] unpacking needs tar, or pass --from <dir>");
   }
-  const tmp = mkdtempSync(join13(tmpdir(), "vitrine-kit-"));
   const dl = spawnSync2(
     "gh",
     ["release", "download", ...version ? [version] : [], "--repo", REPO, "--archive=tar.gz", "--dir", tmp, "--clobber"],
@@ -1455,22 +1595,41 @@ function acquireFromGh(version) {
   if (dl.status !== 0) {
     throw new Error("[vitrine] gh release download failed (check access/auth: gh auth status, and gh auth login if needed)");
   }
-  const tarball = readdirSync4(tmp).find((f) => f.endsWith(".tar.gz"));
+  const tarball = readdirSync5(tmp).find((f) => f.endsWith(".tar.gz"));
   if (!tarball) throw new Error("[vitrine] release tarball not found after download");
-  if (spawnSync2("tar", ["-xzf", join13(tmp, tarball), "-C", tmp], { stdio: "inherit" }).status !== 0) {
+  if (spawnSync2("tar", ["-xzf", join14(tmp, tarball), "-C", tmp], { stdio: "inherit" }).status !== 0) {
     throw new Error("[vitrine] tarball extraction failed");
   }
-  const root = readdirSync4(tmp).map((f) => join13(tmp, f)).find((p2) => statSync2(p2).isDirectory() && existsSync9(join13(p2, "registry", "_index.json")));
+  const root = readdirSync5(tmp).map((f) => join14(tmp, f)).find((p2) => statSync2(p2).isDirectory() && existsSync9(join14(p2, "registry", "_index.json")));
   if (!root) throw new Error("[vitrine] the unpacked tarball has no registry/_index.json");
   return root;
 }
+function warnOnVersionMismatch(root, requested) {
+  if (!requested) return;
+  const tagSemver = requested.match(/^@vitrine-kit\/vitrine@(.+)$/)?.[1] ?? requested.match(/^v?(\d+\.\d+\.\d+\S*)$/)?.[1];
+  const pkgFile = join14(root, "packages", "cli", "package.json");
+  if (!tagSemver || !exists(pkgFile)) return;
+  const version = readJson(pkgFile).version;
+  if (version && version !== tagSemver) {
+    console.warn(`[vitrine] requested "${requested}" but the downloaded kit is @vitrine-kit/vitrine@${version}`);
+  }
+}
 function kitUpdate(opts = {}) {
-  const source = opts.from ? resolve5(opts.from) : acquireFromGh(opts.version);
-  return populateCache(source, { home: opts.home, channel: opts.channel ?? "stable" });
+  if (opts.from) {
+    return populateCache(resolve6(opts.from), { home: opts.home, channel: opts.channel ?? "stable" });
+  }
+  const tmp = mkdtempSync(join14(tmpdir(), "vitrine-kit-"));
+  try {
+    const source = acquireFromGh(tmp, opts.version);
+    warnOnVersionMismatch(source, opts.version);
+    return populateCache(source, { home: opts.home, channel: opts.channel ?? "stable" });
+  } finally {
+    rmSync4(tmp, { recursive: true, force: true });
+  }
 }
 function kitStatus(home = vitrineHome()) {
   const meta = readKitMeta(home);
-  const idxFile = join13(cachePaths(home).registry, "_index.json");
+  const idxFile = join14(cachePaths(home).registry, "_index.json");
   const idx = exists(idxFile) ? readJson(idxFile) : null;
   return {
     cached: meta !== null,
@@ -1496,16 +1655,16 @@ function selfUpdate(opts = {}) {
 var pkg = JSON.parse(readFileSync3(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command();
 program.name("vitrine").description("Vitrine CLI").version(pkg.version);
-program.command("add").description("Add feature(s) to the current repository").argument("<features...>", "feature names").option("--registry <path>", "path to the registry").action((features, opts) => {
-  const res = addFeatures(features, opts.registry);
+program.command("add").description("Add feature(s) to the current repository").argument("<features...>", "feature names").option("--registry <path>", "path to the registry").option("--project <path>", "client repo root (default: walk up from cwd)").action((features, opts) => {
+  const res = addFeatures(features, opts.registry, opts.project);
   console.log(res.installed.length ? `Installed: ${res.installed.join(", ")}` : "Already installed \u2014 no changes.");
 });
-program.command("remove").description("Remove a feature (if removable)").argument("<feature>", "feature name").option("--registry <path>", "path to the registry").action((feature, opts) => {
-  removeFeatureCmd(feature, opts.registry);
+program.command("remove").description("Remove a feature (if removable)").argument("<feature>", "feature name").option("--registry <path>", "path to the registry").option("--project <path>", "client repo root (default: walk up from cwd)").action((feature, opts) => {
+  removeFeatureCmd(feature, opts.registry, opts.project);
   console.log(`Removed: ${feature}`);
 });
-program.command("update").description("Update an installed feature (3-way merge); all if no arguments").argument("[features...]", "feature names").option("--registry <path>", "path to the registry").option("--dry-run", "show the plan without writing").action((features, opts) => {
-  const outcomes = updateFeaturesCmd(features, opts.registry, { dryRun: opts.dryRun });
+program.command("update").description("Update an installed feature (3-way merge); all if no arguments").argument("[features...]", "feature names").option("--registry <path>", "path to the registry").option("--dry-run", "show the plan without writing").option("--project <path>", "client repo root (default: walk up from cwd)").action((features, opts) => {
+  const outcomes = updateFeaturesCmd(features, opts.registry, { dryRun: opts.dryRun, projectRoot: opts.project });
   let conflicts = 0;
   for (const { plan, applied } of outcomes) {
     console.log(renderPlan(plan));
@@ -1517,17 +1676,17 @@ program.command("update").description("Update an installed feature (3-way merge)
 \u26A0 conflicts: ${conflicts}. Resolve the git markers (<<<<<<< / >>>>>>>) by hand.`);
   }
 });
-program.command("diff").description("Preview update changes (without writing)").argument("<feature>", "feature name").option("--registry <path>", "path to the registry").action((feature, opts) => {
-  console.log(renderPlan(diffFeatureCmd(feature, opts.registry)));
+program.command("diff").description("Preview update changes (without writing)").argument("<feature>", "feature name").option("--registry <path>", "path to the registry").option("--project <path>", "client repo root (default: walk up from cwd)").action((feature, opts) => {
+  console.log(renderPlan(diffFeatureCmd(feature, opts.registry, opts.project)));
 });
-program.command("list").description("Installed and available features").option("--registry <path>", "path to the registry").action((opts) => {
-  const { installed, available } = listFeatures(opts.registry);
+program.command("list").description("Installed and available features").option("--registry <path>", "path to the registry").option("--project <path>", "client repo root (default: walk up from cwd)").action((opts) => {
+  const { installed, available } = listFeatures(opts.registry, opts.project);
   console.log("Installed:", installed.join(", ") || "\u2014");
   console.log("Available:", available.join(", ") || "\u2014");
 });
 var design = program.command("design").description("AI design step (wrapper over Claude Code)");
-design.command("apply").description("Apply the design from /design to the tokens (via Claude Code)").option("--bin <path>", "path to Claude Code (otherwise VITRINE_CLAUDE_BIN / PATH)").option("--dry-run", "show the command without running").action((opts) => {
-  const code = designApplyCmd({ bin: opts.bin, dryRun: opts.dryRun });
+design.command("apply").description("Apply the design from /design to the tokens (via Claude Code)").option("--bin <path>", "path to Claude Code (otherwise VITRINE_CLAUDE_BIN / PATH)").option("--dry-run", "show the command without running").option("--project <path>", "client repo root (default: walk up from cwd)").action((opts) => {
+  const code = designApplyCmd({ bin: opts.bin, dryRun: opts.dryRun, projectRoot: opts.project });
   if (code !== 0) process.exit(code);
 });
 var kit = program.command("kit").description("Local tooling (the ~/.vitrine registry cache)");
@@ -1549,8 +1708,8 @@ program.command("self-update").description("Update the CLI itself (@vitrine-kit/
   const code = selfUpdate({ dryRun: opts.dryRun });
   if (code !== 0) process.exit(code);
 });
-program.command("doctor").description("Check consistency: vitrine.json \u2194 files \u2194 packages \u2194 env").option("--registry <path>", "path to the registry").action((opts) => {
-  const report = doctorCmd(opts.registry);
+program.command("doctor").description("Check consistency: vitrine.json \u2194 files \u2194 packages \u2194 env").option("--registry <path>", "path to the registry").option("--project <path>", "client repo root (default: walk up from cwd)").action((opts) => {
+  const report = doctorCmd(opts.registry, opts.project);
   if (report.issues.length === 0) {
     console.log("\u2713 No issues found.");
     return;
@@ -1614,7 +1773,7 @@ program.command("init").description("Create a new client repository").argument("
   const finalTier = tier ?? "catalog";
   const backend = opts.backend ?? defaultBackend(finalTier);
   const finalFeatures = features ?? suggestFeatures(finalTier, registry, backend);
-  const root = resolve6(String(opts.dir ?? process.cwd()), name);
+  const root = resolve7(String(opts.dir ?? process.cwd()), name);
   const res = initProject({ root, name, backend, tier: finalTier, features: finalFeatures, registry });
   console.log(`Created project "${name}" \u2192 ${root}`);
   console.log(`Installed: ${res.installed.join(", ") || "\u2014"}`);

package/kit/registry/_index.json

@@ -1,11 +1,11 @@
 {
   "$schema": "../schemas/registry-index.schema.json",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.1",
   "contracts": "1.0.0",
   "features": {
     "catalog": {
       "title": "Product catalog",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.1",
       "tier": [
         "catalog",
         "simple-store",
@@ -14,7 +14,7 @@
     },
     "product-page": {
       "title": "Product page",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.1",
       "tier": [
         "catalog",
         "simple-store",
@@ -23,7 +23,7 @@
     },
     "seo": {
       "title": "SEO — metadata and JSON-LD",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.1",
       "tier": [
         "catalog",
         "simple-store",
@@ -32,7 +32,7 @@
     },
     "cart": {
       "title": "Cart",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.1",
       "tier": [
         "simple-store",
         "full-store"
@@ -40,7 +40,7 @@
     },
     "checkout": {
       "title": "Checkout",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.1",
       "tier": [
         "simple-store",
         "full-store"
@@ -48,7 +48,7 @@
     },
     "checkout-stripe": {
       "title": "Payment — Stripe",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.1",
       "tier": [
         "simple-store",
         "full-store"
@@ -56,7 +56,7 @@
     },
     "checkout-paddle": {
       "title": "Payment — Paddle",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.1",
       "tier": [
         "simple-store",
         "full-store"
@@ -64,7 +64,7 @@
     },
     "checkout-yookassa": {
       "title": "Payment — YooKassa",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.1",
       "tier": [
         "simple-store",
         "full-store"

package/kit/registry/cart/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "cart",
   "title": "Cart",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.1",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

package/kit/registry/catalog/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "catalog",
   "title": "Product catalog",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.1",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "catalog",

package/kit/registry/checkout/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout",
   "title": "Checkout",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.1",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

package/kit/registry/checkout/files/components/checkout/CheckoutButton.tsx

@@ -6,26 +6,41 @@ import { useState } from 'react';
 
 export function CheckoutButton() {
   const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
 
   async function checkout(): Promise<void> {
     setPending(true);
+    setError(null);
     try {
       const res = await fetch('/api/checkout', { method: 'POST' });
-      const data = (await res.json()) as { url?: string; error?: string };
-      if (data.url) location.assign(data.url);
+      const data = (await res.json().catch(() => ({}))) as { url?: string; error?: string };
+      if (!res.ok || !data.url) {
+        setError(data.error ?? 'Checkout is unavailable — try again later.');
+        return;
+      }
+      location.assign(data.url);
+    } catch {
+      setError('Checkout is unavailable — try again later.');
     } finally {
       setPending(false);
     }
   }
 
   return (
-    <button
-      type="button"
-      onClick={checkout}
-      disabled={pending}
-      className="vt-checkout-button rounded-md bg-primary px-gutter py-unit text-primary-fg transition hover:opacity-90 disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 ring-ring"
-    >
-      {pending ? 'Redirecting to payment…' : 'Checkout'}
-    </button>
+    <>
+      <button
+        type="button"
+        onClick={checkout}
+        disabled={pending}
+        className="vt-checkout-button rounded-md bg-primary px-gutter py-unit text-primary-fg transition hover:opacity-90 disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 ring-ring"
+      >
+        {pending ? 'Redirecting to payment…' : 'Checkout'}
+      </button>
+      {error ? (
+        <p role="alert" className="vt-checkout-error text-danger">
+          {error}
+        </p>
+      ) : null}
+    </>
   );
 }

package/kit/registry/checkout-paddle/docs/checkout-paddle.md

@@ -8,12 +8,15 @@ in `@vitrine-kit/core`.
 - **Provider:** `lib/checkout-paddle/provider.ts` → `paddleProvider`
   (`PaymentProvider`): `createCheckout` creates a Paddle transaction with non-catalog
   line items (prices from the cart, `customData.cartId`); `verifyWebhook` verifies the
-  `Paddle-Signature` via `@paddle/paddle-node-sdk`.
+  `Paddle-Signature` via `@paddle/paddle-node-sdk`. The notification carries no email, so
+  the provider does a best-effort `customers.get(customerId)` lookup for the order's
+  `email` — a lookup failure does not fail fulfillment.
 - **Registration:** `registerCheckoutPaddleProvider()` (from `lib/payments.ts`), sets
   `integrations.payments: "paddle"`.
 - **API (Next glue):** `POST /api/webhooks/paddle` → `handlePaymentWebhook` →
   `fulfillOrderFromEvent` (on `transaction.completed`/`transaction.paid`).
-- **env:** `PADDLE_API_KEY`, `PADDLE_WEBHOOK_SECRET` (required);
+- **env:** `PADDLE_API_KEY`, `PADDLE_WEBHOOK_SECRET` (required — read at call time, a
+  missing key throws `[vitrine] <KEY> is not set …`; webhook route → 400);
   `PADDLE_ENVIRONMENT` (`sandbox`|`production`, default `sandbox`),
   `PADDLE_CHECKOUT_URL` (override the hosted checkout, otherwise a default payment link
   in the Paddle dashboard is required) — optional.

package/kit/registry/checkout-paddle/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout-paddle",
   "title": "Payment — Paddle",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.1",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

package/kit/registry/checkout-paddle/files/lib/checkout-paddle/provider.ts

@@ -9,8 +9,15 @@
 import { Environment, Paddle, type EventEntity } from '@paddle/paddle-node-sdk';
 import type { CreateCheckoutArgs, NormalizedPaymentEvent, PaymentProvider, PaymentWebhookRequest } from '@vitrine-kit/core';
 
+/** Required env, read at call time — `next build` must not need secrets. */
+function requiredEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) throw new Error(`[vitrine] ${key} is not set — add it to .env (see .env.example)`);
+  return value;
+}
+
 function client(): Paddle {
-  return new Paddle(process.env.PADDLE_API_KEY ?? '', {
+  return new Paddle(requiredEnv('PADDLE_API_KEY'), {
     environment:
       process.env.PADDLE_ENVIRONMENT === 'production' ? Environment.production : Environment.sandbox,
   });
@@ -40,16 +47,30 @@ export const paddleProvider: PaymentProvider = {
 
   async verifyWebhook(req: PaymentWebhookRequest): Promise<NormalizedPaymentEvent> {
     const paddle = client();
-    const secret = process.env.PADDLE_WEBHOOK_SECRET ?? '';
+    const secret = requiredEnv('PADDLE_WEBHOOK_SECRET');
     const signature = req.headers['paddle-signature'] ?? '';
     // Throws on an invalid signature — handlePaymentWebhook returns a 400.
     const event = (await paddle.webhooks.unmarshal(req.rawBody, secret, signature)) as EventEntity | null;
     if (!event) return { kind: 'unknown', raw: req.rawBody };
 
     if (event.eventType === 'transaction.completed' || event.eventType === 'transaction.paid') {
-      const data = event.data as { id?: string; customData?: { cartId?: string } | null };
+      const data = event.data as {
+        id?: string;
+        customData?: { cartId?: string } | null;
+        customerId?: string | null;
+      };
       const cartId = (data.customData ?? undefined)?.cartId;
-      return { kind: 'checkout_completed', cartId, providerRef: data.id, raw: event };
+      // The notification carries no email — best-effort lookup on the Customer entity.
+      // A lookup failure must not fail fulfillment: email is optional on the event.
+      let email: string | undefined;
+      if (data.customerId) {
+        try {
+          email = (await paddle.customers.get(data.customerId)).email ?? undefined;
+        } catch {
+          // keep email undefined — the order is still created
+        }
+      }
+      return { kind: 'checkout_completed', cartId, providerRef: data.id, email, raw: event };
     }
     if (event.eventType === 'transaction.payment_failed') {
       return { kind: 'payment_failed', raw: event };

package/kit/registry/checkout-stripe/docs/checkout-stripe.md

@@ -11,7 +11,9 @@ logic (webhook dispatcher, order from cart) lives in `@vitrine-kit/core`.
   sets `integrations.payments: "stripe"` in `site.config`.
 - **API (Next glue):** `POST /api/webhooks/stripe` → `handlePaymentWebhook` →
   `fulfillOrderFromEvent` (the `checkout` feature's shared code).
-- **env:** `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET` (required).
+- **env:** `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET` (required). Read at call time
+  (`next build` needs no secrets); a missing key throws `[vitrine] <KEY> is not set …` —
+  in the webhook route this surfaces as a 400, in `POST /api/checkout` as a 500.
 
 Flow: cart → `Checkout` → redirect to Stripe → webhook
 `checkout.session.completed` → order in the admin, cart `converted`.

package/kit/registry/checkout-stripe/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout-stripe",
   "title": "Payment — Stripe",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.1",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

package/kit/registry/checkout-stripe/files/lib/checkout-stripe/provider.ts

@@ -10,6 +10,13 @@ import type {
   PaymentWebhookRequest,
 } from '@vitrine-kit/core';
 
+/** Required env, read at call time — `next build` must not need secrets. */
+function requiredEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) throw new Error(`[vitrine] ${key} is not set — add it to .env (see .env.example)`);
+  return value;
+}
+
 interface StripeLineItem {
   quantity: number;
   price_data: { currency: string; unit_amount: number; product_data: { name: string } };
@@ -32,7 +39,7 @@ export const stripeProvider: PaymentProvider = {
   async createCheckout(args: CreateCheckoutArgs): Promise<{ redirectUrl: string }> {
     const { cart, baseUrl, successPath = '/order/success', cancelPath = '/cart' } = args;
     const { default: Stripe } = await import('stripe');
-    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY ?? '');
+    const stripe = new Stripe(requiredEnv('STRIPE_SECRET_KEY'));
     const session = await stripe.checkout.sessions.create({
       mode: 'payment',
       line_items: cartToStripeLineItems(cart),
@@ -45,8 +52,8 @@ export const stripeProvider: PaymentProvider = {
 
   async verifyWebhook(req: PaymentWebhookRequest): Promise<NormalizedPaymentEvent> {
     const { default: Stripe } = await import('stripe');
-    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY ?? '');
-    const secret = process.env.STRIPE_WEBHOOK_SECRET ?? '';
+    const stripe = new Stripe(requiredEnv('STRIPE_SECRET_KEY'));
+    const secret = requiredEnv('STRIPE_WEBHOOK_SECRET');
     const signature = req.headers['stripe-signature'] ?? '';
     // Throws on an invalid signature — handlePaymentWebhook surfaces it as a 400.
     const event = stripe.webhooks.constructEvent(req.rawBody, signature, secret);

package/kit/registry/checkout-yookassa/docs/checkout-yookassa.md

@@ -11,10 +11,13 @@ A YooKassa (yookassa.ru) provider — Russian acquiring: cards, SBP, wallets. Fo
   sets `integrations.payments: "yookassa"`.
 - **API (Next glue):** `POST /api/webhooks/yookassa` → `handlePaymentWebhook` →
   `fulfillOrderFromEvent`.
-- **env:** `YOOKASSA_SHOP_ID`, `YOOKASSA_SECRET_KEY` (required).
+- **env:** `YOOKASSA_SHOP_ID`, `YOOKASSA_SECRET_KEY` (required — read at call time, a
+  missing key throws `[vitrine] <KEY> is not set …`; webhook route → 400).
 
 **Security:** YooKassa notifications are **not signed** — the provider re-verifies the
-payment via `GET /v3/payments/{id}` and trusts only `status: "succeeded"`.
+payment via `GET /v3/payments/{id}` and trusts only `status: "succeeded"`. A 404 on that
+check (forged/foreign payment id) is acked as `kind: "unknown"`; other API failures throw,
+so the non-200 response makes YooKassa redeliver the notification.
 
 **Money:** YooKassa expects a decimal string (`"1990.00"`); `Money` is in minor
 units, so we divide by 100 (RUB and most currencies have 2 decimal places).

package/kit/registry/checkout-yookassa/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout-yookassa",
   "title": "Payment — YooKassa",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.1",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

package/kit/registry/checkout-yookassa/files/lib/checkout-yookassa/provider.ts

@@ -18,9 +18,16 @@ function minorToDecimalString(amount: number, currency: string): string {
   return ZERO_DECIMAL.has(currency.toUpperCase()) ? String(amount) : (amount / 100).toFixed(2);
 }
 
+/** Required env, read at call time — `next build` must not need secrets. */
+function requiredEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) throw new Error(`[vitrine] ${key} is not set — add it to .env (see .env.example)`);
+  return value;
+}
+
 function authHeader(): string {
-  const shopId = process.env.YOOKASSA_SHOP_ID ?? '';
-  const secret = process.env.YOOKASSA_SECRET_KEY ?? '';
+  const shopId = requiredEnv('YOOKASSA_SHOP_ID');
+  const secret = requiredEnv('YOOKASSA_SECRET_KEY');
   return `Basic ${Buffer.from(`${shopId}:${secret}`).toString('base64')}`;
 }
 
@@ -57,9 +64,12 @@ export const yookassaProvider: PaymentProvider = {
     const paymentId = body.object?.id;
     if (!paymentId) return { kind: 'unknown', raw: body };
 
-    // The notification is unsigned — re-check the payment via the API.
+    // The notification is unsigned — re-check the payment via the API. 404 = no such
+    // payment for this shop (forged/foreign notification) → ack as 'unknown'; any other
+    // failure is transient → throw (a non-200 response makes YooKassa redeliver later).
     const res = await fetch(`${API}/${paymentId}`, { headers: { Authorization: authHeader() } });
-    if (!res.ok) throw new Error(`[vitrine] YooKassa verify: ${res.status}`);
+    if (res.status === 404) return { kind: 'unknown', raw: body };
+    if (!res.ok) throw new Error(`[vitrine] YooKassa verify: ${res.status} (transient — expecting a redelivery)`);
     const payment = (await res.json()) as {
       id?: string;
       status?: string;

package/kit/registry/product-page/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "product-page",
   "title": "Product page",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.1",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "catalog",

package/kit/registry/seo/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "seo",
   "title": "SEO — metadata and JSON-LD",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.1",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "catalog",

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/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@vitrine-kit/vitrine",
-  "version": "0.4.0",
+  "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"
   },
@@ -22,7 +25,7 @@
   "dependencies": {
     "@clack/prompts": "^0.8.2",
     "commander": "^12.1.0",
-    "@vitrine-kit/contracts": "1.2.0"
+    "@vitrine-kit/contracts": "1.2.1"
   },
   "scripts": {
     "build": "node scripts/generate-kit-versions.mjs && tsup src/index.ts --format esm --clean && node scripts/copy-kit.mjs",