@vitrine-kit/vitrine 0.3.1 → 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)
@@ -121,25 +137,37 @@ function loadProject(root) {
 }
 
 // src/registry.ts
-import { existsSync as existsSync4 } from "fs";
-import { dirname as dirname3, join as join4, resolve as resolve4 } from "path";
+import { existsSync as existsSync5 } from "fs";
+import { dirname as dirname4, join as join5, resolve as resolve4 } from "path";
 import { featureManifestSchema } from "@vitrine-kit/contracts";
 
+// src/bundled-kit.ts
+import { existsSync as existsSync3 } from "fs";
+import { dirname as dirname3, join as join3 } from "path";
+import { fileURLToPath } from "url";
+function bundledKitRoot() {
+  const distDir = dirname3(fileURLToPath(import.meta.url));
+  const candidate = join3(distDir, "..", "kit");
+  if (existsSync3(join3(candidate, "registry", "_index.json"))) return candidate;
+  return null;
+}
+
 // src/cache.ts
-import { cpSync, existsSync as existsSync3, rmSync } from "fs";
-import { join as join3, resolve as resolve3 } from "path";
+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;
   if (!home) throw new Error("[vitrine] could not determine the home directory (HOME/USERPROFILE)");
-  return join3(home, ".vitrine");
+  return join4(home, ".vitrine");
 }
 function cachePaths(home = vitrineHome()) {
   return {
     root: home,
-    registry: join3(home, "registry"),
-    templates: join3(home, "templates"),
-    meta: join3(home, "kit.json")
+    registry: join4(home, "registry"),
+    templates: join4(home, "templates"),
+    meta: join4(home, "kit.json")
   };
 }
 function readKitMeta(home = vitrineHome()) {
@@ -151,7 +179,7 @@ function writeKitMeta(home, meta) {
 `);
 }
 function readIndex(registryRoot) {
-  const file = join3(registryRoot, "_index.json");
+  const file = join4(registryRoot, "_index.json");
   return exists(file) ? readJson(file) : null;
 }
 function computeChangelog(oldIndex, newIndex) {
@@ -180,18 +208,29 @@ function formatChangelog(entries) {
 }
 function populateCache(fromDir, opts = {}) {
   const home = opts.home ?? vitrineHome();
-  const srcRegistry = join3(fromDir, "registry");
-  const srcTemplates = join3(fromDir, "templates");
-  if (!existsSync3(join3(srcRegistry, "_index.json"))) {
+  const srcRegistry = join4(fromDir, "registry");
+  const srcTemplates = join4(fromDir, "templates");
+  if (!existsSync4(join4(srcRegistry, "_index.json"))) {
     throw new Error(`[vitrine] "${fromDir}" has no registry/_index.json \u2014 not a kit tree`);
   }
   const paths = cachePaths(home);
   const oldIndex = readIndex(paths.registry);
-  rmSync(paths.registry, { recursive: true, force: true });
-  cpSync(srcRegistry, paths.registry, { recursive: true });
-  if (existsSync3(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";
@@ -207,9 +246,9 @@ function populateCache(fromDir, opts = {}) {
 function findUpRegistry(start) {
   let dir = resolve4(start);
   for (; ; ) {
-    const candidate = join4(dir, "registry");
-    if (existsSync4(join4(candidate, "_index.json"))) return candidate;
-    const parent = dirname3(dir);
+    const candidate = join5(dir, "registry");
+    if (existsSync5(join5(candidate, "_index.json"))) return candidate;
+    const parent = dirname4(dir);
     if (parent === dir) return null;
     dir = parent;
   }
@@ -224,60 +263,69 @@ function resolveRegistryRoot(explicit) {
     home = null;
   }
   if (home) {
-    const cache = join4(home, "registry");
-    if (existsSync4(join4(cache, "_index.json"))) return cache;
+    const cache = join5(home, "registry");
+    if (existsSync5(join5(cache, "_index.json"))) return cache;
   }
   const dev = findUpRegistry(process.cwd());
   if (dev) return dev;
+  const bundled = bundledKitRoot();
+  if (bundled) return join5(bundled, "registry");
   throw new Error('[vitrine] registry not found. Run "vitrine kit update" or pass --registry.');
 }
 function createRegistrySource(explicitRoot) {
   const root = resolveRegistryRoot(explicitRoot);
   const cache = /* @__PURE__ */ new Map();
-  const featureDir = (name) => join4(root, name);
-  const hasFeature = (name) => existsSync4(join4(featureDir(name), "feature.json"));
+  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);
     if (cached) return cached;
-    const file = join4(featureDir(name), "feature.json");
-    if (!existsSync4(file)) throw new Error(`[vitrine] feature "${name}" not found in the registry`);
+    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;
   };
   const listFeatures2 = () => {
-    const index = JSON.parse(readText(join4(root, "_index.json")));
+    const index = JSON.parse(readText(join5(root, "_index.json")));
     return Object.keys(index.features ?? {});
   };
   return { root, featureDir, hasFeature, loadManifest, listFeatures: listFeatures2 };
 }
 
 // src/install.ts
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/transaction.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname4 } from "path";
+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 = [];
   snapshot(path) {
     if (this.backups.some((b) => b.path === path)) return;
-    if (existsSync5(path)) this.backups.push({ path, existed: true, prev: readFileSync2(path, "utf8") });
+    if (existsSync6(path)) this.backups.push({ path, existed: true, prev: readFileSync2(path, "utf8") });
     else this.backups.push({ path, existed: false });
   }
   write(path, content) {
     this.snapshot(path);
-    mkdirSync2(dirname4(path), { recursive: true });
-    writeFileSync2(path, content, "utf8");
+    mkdirSync3(dirname5(path), { recursive: true });
+    writeFileSync2(path, normalizeEol(content), "utf8");
   }
   remove(path) {
     this.snapshot(path);
-    if (existsSync5(path)) rmSync2(path);
+    if (existsSync6(path)) rmSync2(path);
   }
   rollback() {
     for (const b of [...this.backups].reverse()) {
       if (b.existed) writeFileSync2(b.path, b.prev, "utf8");
-      else if (existsSync5(b.path)) rmSync2(b.path);
+      else if (existsSync6(b.path)) rmSync2(b.path);
     }
     this.backups = [];
   }
@@ -340,9 +388,11 @@ function renderSlotsFile(features) {
   const calls = withSlots.map((f) => `  register${pascalCase(f.name)}Slots();`);
   return [
     "// vitrine:generated \u2014 slot registration for installed features. Do not edit by hand.",
+    "import { slotRegistry } from '@vitrine-kit/core';",
     ...imports,
     "",
     "export function registerSlots(): void {",
+    "  slotRegistry.clear();",
     ...calls.length ? calls : ["  // no slot features"],
     "}",
     ""
@@ -357,9 +407,11 @@ function renderPaymentsFile(features) {
   const calls = withPayment.map((f) => `  register${pascalCase(f.name)}Provider();`);
   return [
     "// vitrine:generated \u2014 payment-provider registration for installed features. Do not edit by hand.",
+    "import { payments } from '@vitrine-kit/core';",
     ...imports,
     "",
     "export function registerPayments(): void {",
+    "  payments.clear();",
     ...calls.length ? calls : ["  // no payment features"],
     "}",
     ""
@@ -448,14 +500,14 @@ function renderNeutralTheme() {
 }
 
 // src/feature-files.ts
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 function* eachFeatureFile(featDir, map) {
-  const src = join5(featDir, map.from);
+  const src = safeJoin(featDir, map.from);
   if (!exists(src)) return;
   const rels = isDir(src) ? walkRelFiles(src) : [""];
   for (const rel of rels) {
-    const srcAbs = rel ? join5(src, rel) : src;
-    const repoRel = rel ? join5(map.to, rel) : map.to;
+    const srcAbs = rel ? join6(src, rel) : src;
+    const repoRel = rel ? join6(map.to, rel) : map.to;
     yield { srcAbs, repoRel, toRel: toPosix(repoRel) };
   }
 }
@@ -464,38 +516,41 @@ 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}"`);
     }
   }
 }
 function copyFeatureFiles(project, name, manifest, registry, tx) {
   const featDir = registry.featureDir(name);
-  const originalsBase = join6(projectPaths(project.root).originals, `${name}@${manifest.kitVersion}`);
+  const originalsBase = join7(projectPaths(project.root).originals, `${name}@${manifest.kitVersion}`);
   for (const map of manifest.files) {
-    if (!exists(join6(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);
@@ -557,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 };
     }
@@ -593,7 +658,7 @@ function removeFeature(project, name, registry) {
       throw new Error(`[vitrine] cannot remove "${name}": "${other}" depends on it`);
     }
   }
-  const originalsDir = join6(projectPaths(project.root).originals, `${name}@${removed.version}`);
+  const originalsDir = join7(projectPaths(project.root).originals, `${name}@${removed.version}`);
   const featDir = registry.featureDir(name);
   const targets = /* @__PURE__ */ new Set();
   if (isDir(originalsDir)) for (const rel of walkRelFiles(originalsDir)) targets.add(rel);
@@ -606,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();
@@ -616,21 +695,22 @@ function removeFeature(project, name, registry) {
 
 // src/design.ts
 import { spawnSync } from "child_process";
-import { existsSync as existsSync6, readdirSync as readdirSync2 } from "fs";
-import { delimiter, join as join7 } from "path";
+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) {
-    if (existsSync6(pinned)) return pinned;
+    if (existsSync7(pinned)) return pinned;
     throw new Error(`[vitrine] Claude Code not found at path "${pinned}"`);
   }
   const names = process.platform === "win32" ? ["claude.cmd", "claude.exe", "claude.ps1", "claude"] : ["claude"];
   for (const dir of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
     for (const name of names) {
-      const full = join7(dir, name);
-      if (existsSync6(full)) return full;
+      const full = join8(dir, name);
+      if (existsSync7(full)) return full;
     }
   }
   throw new Error(
@@ -638,8 +718,8 @@ function findClaudeBin(explicit) {
   );
 }
 function designHasInput(root) {
-  const dir = join7(root, "design");
-  if (!existsSync6(dir)) return false;
+  const dir = join8(root, "design");
+  if (!existsSync7(dir)) return false;
   return readdirSync2(dir).some((entry) => !/^readme\.md$/i.test(entry));
 }
 function extractDesignInstruction(claudeMd) {
@@ -649,8 +729,12 @@ function extractDesignInstruction(claudeMd) {
   return claudeMd.slice(start, next === -1 ? void 0 : next).trim();
 }
 function buildDesignPrompt(project) {
-  const claudeMd = existsSync6(join7(project.root, "CLAUDE.md")) ? readText(join7(project.root, "CLAUDE.md")) : "";
-  const instruction = extractDesignInstruction(claudeMd) ?? DESIGN_HEADING;
+  const claudeMd = existsSync7(join8(project.root, "CLAUDE.md")) ? readText(join8(project.root, "CLAUDE.md")) : "";
+  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,
@@ -670,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);
@@ -687,11 +784,13 @@ 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 { join as join8 } from "path";
+import { readdirSync as readdirSync3 } from "fs";
+import { join as join9 } from "path";
 function runDoctor(project, registry) {
   const paths = projectPaths(project.root);
   const issues = [];
@@ -702,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",
@@ -715,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)) {
@@ -733,7 +877,7 @@ function runDoctor(project, registry) {
     const featDir = registry.featureDir(name);
     for (const map of manifest.files) {
       for (const file of eachFeatureFile(featDir, map)) {
-        if (!exists(join8(project.root, file.repoRel))) {
+        if (!exists(join9(project.root, file.repoRel))) {
           add({
             severity: "error",
             scope,
@@ -783,7 +927,7 @@ function runDoctor(project, registry) {
 
 // src/update.ts
 import { rmSync as rmSync3 } from "fs";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 
 // src/merge.ts
 function splitLines(s) {
@@ -927,15 +1071,15 @@ function planUpdate(project, name, registry) {
   const fromVersion = pin.version;
   const toVersion = manifest.kitVersion;
   const featDir = registry.featureDir(name);
-  const originalsBase = join9(projectPaths(project.root).originals, `${name}@${fromVersion}`);
+  const originalsBase = join10(projectPaths(project.root).originals, `${name}@${fromVersion}`);
   const files = [];
   for (const map of manifest.files) {
     for (const file of eachFeatureFile(featDir, map)) {
-      const theirs = readText(file.srcAbs);
-      const oursPath = join9(project.root, file.repoRel);
-      const basePath = join9(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) {
@@ -961,8 +1105,8 @@ function applyUpdate(project, plan, registry) {
   const manifest = registry.loadManifest(plan.feature);
   const featDir = registry.featureDir(plan.feature);
   const paths = projectPaths(project.root);
-  const newOriginals = join9(paths.originals, `${plan.feature}@${plan.toVersion}`);
-  const oldOriginals = join9(paths.originals, `${plan.feature}@${plan.fromVersion}`);
+  const newOriginals = join10(paths.originals, `${plan.feature}@${plan.toVersion}`);
+  const oldOriginals = join10(paths.originals, `${plan.feature}@${plan.fromVersion}`);
   const tx = new FsTransaction();
   try {
     for (const f of plan.files) {
@@ -978,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) {
@@ -994,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) => {
@@ -1031,38 +1183,40 @@ 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 join11 } from "path";
+import { readdirSync as readdirSync4 } from "fs";
+import { join as join13 } from "path";
 
-// src/kit.ts
-var KIT_VERSION = "0.0.0";
+// src/kit-versions.generated.ts
+var KIT_VERSION = "0.4.1";
 var CONTRACTS_VERSION = "1.0.0";
 var CONTRACTS_RANGE = "^1.0.0";
-var CORE_RANGE = "^0.1.0";
-var BLUEPRINT_RANGE = "^0.1.0";
+var CORE_RANGE = "^0.2.0";
+var BLUEPRINT_RANGE = "^0.2.0";
+
+// src/kit.ts
 var REACT_RANGE = "^18.3.1";
 var CLIENT_REACT_RANGE = "^19.0.0";
 var NEXT_RANGE = "^15.1.0";
 var PAYLOAD_RANGE = "^3.0.0";
 
 // src/templates.ts
-import { existsSync as existsSync7 } from "fs";
-import { dirname as dirname5, join as join10 } from "path";
+import { existsSync as existsSync8 } from "fs";
+import { dirname as dirname6, join as join12 } from "path";
 function templatesRoot(registryRoot) {
-  return join10(dirname5(registryRoot), "templates");
+  return join12(dirname6(registryRoot), "templates");
 }
 function hasTemplate(root, name) {
-  return existsSync7(join10(root, name, "files"));
+  return existsSync8(join12(root, name, "files"));
 }
 function copyTemplate(root, name, destRoot) {
-  const filesDir = join10(root, name, "files");
+  const filesDir = join12(root, name, "files");
   const rels = walkRelFiles(filesDir);
-  for (const rel of rels) writeText(join10(destRoot, rel), readText(join10(filesDir, rel)));
+  for (const rel of rels) writeText(join12(destRoot, rel), readText(join12(filesDir, rel)));
   return rels;
 }
 
@@ -1077,7 +1231,7 @@ var PAYMENT_PROVIDER_FEATURES = [
 ];
 function suggestFeatures(tier, registry, backend = defaultBackend(tier)) {
   const core = ["catalog", "product-page", "seo"];
-  const shop = backend === "vendure" ? ["cart"] : ["cart", "checkout-stripe", "reviews"];
+  const shop = backend === "vendure" ? ["cart"] : ["cart", "checkout-stripe"];
   const desired = tier === "catalog" ? core : [...core, ...shop];
   return desired.filter((name) => registry.hasFeature(name));
 }
@@ -1165,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",
       "",
@@ -1187,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=",
     "",
@@ -1254,8 +1414,8 @@ ${run}
 
 \`\`\`bash
 vitrine list             # installed + available
-vitrine add reviews      # copy a feature: flag, slots, blueprint, env
-vitrine remove reviews   # remove (if the feature is removable)
+vitrine add cart         # copy a feature: flag, slots, blueprint, env
+vitrine remove cart      # remove (if the feature is removable)
 vitrine design apply     # style the new feature
 \`\`\`
 
@@ -1294,10 +1454,10 @@ function scaffoldBase(opts) {
   const backendTemplate = `backend-${backend}`;
   if (hasTemplate(tRoot, backendTemplate)) copyTemplate(tRoot, backendTemplate, root);
   if (!baseCopied) {
-    writeText(join11(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(
-    join11(root, "vitrine.json"),
+    join13(root, "vitrine.json"),
     `${JSON.stringify(
       { kitVersion: KIT_VERSION, contracts: CONTRACTS_VERSION, backend, tier, features: {} },
       null,
@@ -1306,7 +1466,7 @@ function scaffoldBase(opts) {
 `
   );
   writeText(
-    join11(root, "site.config.ts"),
+    join13(root, "site.config.ts"),
     `import type { SiteConfig } from '@vitrine-kit/contracts';
 
 export const siteConfig: SiteConfig = {
@@ -1327,7 +1487,7 @@ export default siteConfig;
 `
   );
   writeText(
-    join11(root, "CLAUDE.md"),
+    join13(root, "CLAUDE.md"),
     `# ${name}
 
 A Vitrine project. Backend: \`${backend}\`, tier: \`${tier}\`.
@@ -1393,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(join11(root, "README.md"), clientReadme(name, backend, tier));
-  writeText(join11(root, "lib", "slots.ts"), renderSlotsFile([]));
-  writeText(join11(root, "lib", "blueprint.ts"), renderBlueprintFile([]));
-  writeText(join11(root, "theme", "client.css"), renderNeutralTheme());
-  writeText(join11(root, ".env.example"), clientEnvExample(backend));
-  writeText(join11(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);
@@ -1412,22 +1572,21 @@ function initProject(opts) {
 
 // src/kit-update.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync8, 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 join12, 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(join12(tmpdir(), "vitrine-kit-"));
   const dl = spawnSync2(
     "gh",
     ["release", "download", ...version ? [version] : [], "--repo", REPO, "--archive=tar.gz", "--dir", tmp, "--clobber"],
@@ -1436,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", join12(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) => join12(tmp, f)).find((p2) => statSync2(p2).isDirectory() && existsSync8(join12(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 = join12(cachePaths(home).registry, "_index.json");
+  const idxFile = join14(cachePaths(home).registry, "_index.json");
   const idx = exists(idxFile) ? readJson(idxFile) : null;
   return {
     cached: meta !== null,
@@ -1477,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));
@@ -1498,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)");
@@ -1530,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;
@@ -1595,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"}`);