@vitrine-kit/vitrine 0.4.0 → 0.4.3

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,19 +1183,19 @@ 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.3";
 var CONTRACTS_VERSION = "1.0.0";
 var CONTRACTS_RANGE = "^1.0.0";
-var CORE_RANGE = "^0.2.0";
+var CORE_RANGE = "^0.3.0";
 var BLUEPRINT_RANGE = "^0.2.0";
 
 // src/kit.ts
@@ -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=",
     "",
@@ -1244,8 +1385,9 @@ function clientReadme(name, backend, tier) {
     "- Admin: http://localhost:3000/admin",
     "",
     "Without Postgres, dev starts a built-in SQLite (`.vitrine/dev.sqlite`), seeds a",
-    "demo catalog (5 products, 2 categories) and creates a dev admin (login/password printed",
-    "to the console once). Disable the fallback in dev too with `VITRINE_DB_STRICT=1`."
+    "demo catalog (5 products, 2 categories, size/color variants, gallery images) and creates a",
+    "dev admin (login/password printed to the console once). Disable the fallback in",
+    "dev too with `VITRINE_DB_STRICT=1`."
   ].join("\n");
   const deploySecret = backend === "vendure" ? "export VENDURE_COOKIE_SECRET=...  # Vendure cookie secret" : "export PAYLOAD_SECRET=...         # random Payload secret";
   return `# ${name}
@@ -1313,10 +1455,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 +1467,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 +1488,7 @@ export default siteConfig;
 `
   );
   writeText(
-    join12(root, "CLAUDE.md"),
+    join13(root, "CLAUDE.md"),
     `# ${name}
 
 A Vitrine project. Backend: \`${backend}\`, tier: \`${tier}\`.
@@ -1412,16 +1554,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 +1573,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 +1596,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 +1656,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 +1677,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 +1709,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 +1774,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"}`);