@numueg/theme-cli 0.1.0 → 0.2.0

package/dist/index.js

@@ -591,13 +591,154 @@ var init_manifest_required_fields = __esm({
   }
 });
 
+// src/lint/rules/contrast-hint.ts
+var contrast_hint_exports = {};
+__export(contrast_hint_exports, {
+  default: () => contrast_hint_default
+});
+function hexToRgb(hex) {
+  let h = hex.replace("#", "").trim();
+  if (h.length === 3) {
+    h = h.split("").map((c) => c + c).join("");
+  }
+  if (h.length !== 6 || /[^0-9a-fA-F]/.test(h)) return null;
+  const n = parseInt(h, 16);
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+function relativeLuminance([r, g, b]) {
+  const a = [r, g, b].map((v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * a[0] + 0.7152 * a[1] + 0.0722 * a[2];
+}
+function contrastRatio(c1, c2) {
+  const l1 = relativeLuminance(c1);
+  const l2 = relativeLuminance(c2);
+  const hi = Math.max(l1, l2);
+  const lo = Math.min(l1, l2);
+  return (hi + 0.05) / (lo + 0.05);
+}
+var rule11, contrast_hint_default;
+var init_contrast_hint = __esm({
+  "src/lint/rules/contrast-hint.ts"() {
+    "use strict";
+    rule11 = {
+      id: "contrast-hint",
+      description: "Co-located color/background hex pairs should meet WCAG 4.5:1 contrast",
+      check(ctx) {
+        const issues = [];
+        const css = ctx.styles;
+        if (!css) return issues;
+        const blockRe = /([^{}]*)\{([^{}]*)\}/g;
+        let m;
+        while ((m = blockRe.exec(css)) !== null) {
+          const rawSelector = m[1].trim().split("\n").pop()?.trim() || m[1].trim();
+          const body = m[2];
+          const colorM = body.match(/(?:^|[;{\s])color:\s*(#[0-9a-fA-F]{3,6})\b/);
+          const bgM = body.match(
+            /background(?:-color)?:\s*(#[0-9a-fA-F]{3,6})\b/
+          );
+          if (!colorM || !bgM) continue;
+          const fg = hexToRgb(colorM[1]);
+          const bg = hexToRgb(bgM[1]);
+          if (!fg || !bg) continue;
+          const ratio = contrastRatio(fg, bg);
+          if (ratio < 4.5) {
+            const line = css.slice(0, m.index).split("\n").length;
+            issues.push({
+              rule: rule11.id,
+              severity: "warning",
+              file: "styles.css",
+              line,
+              message: `Low contrast ${ratio.toFixed(2)}:1 for "${rawSelector}" (${colorM[1]} on ${bgM[1]}).`,
+              suggestion: ratio >= 3 ? `Meets 3:1 (OK for large text \u226524px/19px-bold) but not the 4.5:1 body-text minimum.` : `Below WCAG 4.5:1 \u2014 darken/lighten one color, or drive both from a color_scheme so merchants control contrast.`
+            });
+          }
+        }
+        return issues;
+      }
+    };
+    contrast_hint_default = rule11;
+  }
+});
+
+// src/lint/rules/touch-target.ts
+var touch_target_exports = {};
+__export(touch_target_exports, {
+  default: () => touch_target_default
+});
+var INTERACTIVE, DIM_PROPS, rule12, touch_target_default;
+var init_touch_target = __esm({
+  "src/lint/rules/touch-target.ts"() {
+    "use strict";
+    INTERACTIVE = /(^|[\s,>+~])(button|a|\.btn\b|\[role=["']?button["']?\]|input\[type=["']?(?:button|submit|reset)["']?\])/i;
+    DIM_PROPS = ["width", "height", "min-width", "min-height"];
+    rule12 = {
+      id: "touch-target",
+      description: "Interactive targets should be \u2265 24\xD724px (WCAG 2.5.8)",
+      check(ctx) {
+        const issues = [];
+        const css = ctx.styles;
+        if (!css) return issues;
+        const blockRe = /([^{}]*)\{([^{}]*)\}/g;
+        let m;
+        while ((m = blockRe.exec(css)) !== null) {
+          const rawSelector = m[1].trim().split("\n").pop()?.trim() || m[1].trim();
+          if (rawSelector.includes("::")) continue;
+          if (!INTERACTIVE.test(rawSelector)) continue;
+          const body = m[2];
+          for (const prop of DIM_PROPS) {
+            const pm = body.match(
+              new RegExp(`(?:^|[;{\\s])${prop}:\\s*([0-9.]+)px\\b`)
+            );
+            if (!pm) continue;
+            const px = parseFloat(pm[1]);
+            if (px > 0 && px < 24) {
+              const line = css.slice(0, m.index).split("\n").length;
+              issues.push({
+                rule: rule12.id,
+                severity: "warning",
+                file: "styles.css",
+                line,
+                message: `Interactive "${rawSelector}" sets ${prop}: ${px}px (< 24px touch target).`,
+                suggestion: `Give clickable elements a \u226524\xD724px hit area (min-width/min-height: 24px or adequate padding).`
+              });
+              break;
+            }
+          }
+        }
+        return issues;
+      }
+    };
+    touch_target_default = rule12;
+  }
+});
+
 // src/index.ts
-var import_commander16 = require("commander");
+var import_commander17 = require("commander");
 
 // src/commands/init.ts
 var import_commander = require("commander");
+var import_child_process = require("child_process");
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
+function detectAuthor() {
+  const git = (args) => {
+    try {
+      return (0, import_child_process.execSync)(`git config ${args}`, {
+        stdio: ["ignore", "pipe", "ignore"]
+      }).toString().trim();
+    } catch {
+      return "";
+    }
+  };
+  const name = git("user.name");
+  const email = git("user.email");
+  if (name && email) return `${name} <${email}>`;
+  if (name) return name;
+  return "Theme Author";
+}
 var initCommand = new import_commander.Command("init").description("Scaffold a new NUMU theme project").argument("<name>", "Theme name").option("--template <template>", "Starter template", "basic").action(async (name, _options) => {
   const dir = path.resolve(process.cwd(), name);
   if (fs.existsSync(dir)) {
@@ -620,7 +761,7 @@ var initCommand = new import_commander.Command("init").description("Scaffold a n
       {
         id: name.toLowerCase().replace(/[^a-z0-9-]/g, "-"),
         name,
-        author: "",
+        author: detectAuthor(),
         version: "0.1.0",
         layout: "single-column",
         description: `${name} NUMU theme`,
@@ -1020,10 +1161,10 @@ export default defineConfig({
           build: "numu-theme build",
           check: "numu-theme check"
         },
-        dependencies: { "@numueg/theme-sdk": "^0.1.0" },
+        dependencies: { "@numueg/theme-sdk": "^0.2.0" },
         devDependencies: {
-          "@numueg/theme-cli": "^0.1.0",
-          "@numueg/theme-plugin": "^0.1.0",
+          "@numueg/theme-cli": "^0.2.0",
+          "@numueg/theme-plugin": "^0.2.0",
           "@vitejs/plugin-react": "^4.3.0",
           vite: "^6.0.0",
           typescript: "^5.8.0",
@@ -1056,20 +1197,27 @@ Next steps:
 
 // src/commands/dev.ts
 var import_commander2 = require("commander");
-var import_child_process = require("child_process");
+var import_child_process2 = require("child_process");
 
 // src/utils/config.ts
 var fs2 = __toESM(require("fs"));
 var path2 = __toESM(require("path"));
 var os = __toESM(require("os"));
-var RC_FILE = path2.join(os.homedir(), ".numurc");
+function configHome() {
+  const override = process.env.NUMU_HOME;
+  if (override && override.length > 0) return override;
+  return os.homedir();
+}
+function rcFile() {
+  return path2.join(configHome(), ".numurc");
+}
 function loadConfig() {
   const config = {
     api_url: process.env.NUMU_API_URL || "https://api.numu.io/api/v1"
   };
-  if (fs2.existsSync(RC_FILE)) {
+  if (fs2.existsSync(rcFile())) {
     try {
-      const rc = JSON.parse(fs2.readFileSync(RC_FILE, "utf-8"));
+      const rc = JSON.parse(fs2.readFileSync(rcFile(), "utf-8"));
       if (rc.token) config.token = rc.token;
       if (rc.api_url) config.api_url = rc.api_url;
       if (rc.store_id) config.store_id = rc.store_id;
@@ -1082,16 +1230,16 @@ function loadConfig() {
 }
 function saveConfig(updates) {
   let existing = {};
-  if (fs2.existsSync(RC_FILE)) {
+  if (fs2.existsSync(rcFile())) {
     try {
-      existing = JSON.parse(fs2.readFileSync(RC_FILE, "utf-8"));
+      existing = JSON.parse(fs2.readFileSync(rcFile(), "utf-8"));
     } catch {
     }
   }
   const merged = { ...existing, ...updates };
-  fs2.writeFileSync(RC_FILE, JSON.stringify(merged, null, 2), { mode: 384 });
+  fs2.writeFileSync(rcFile(), JSON.stringify(merged, null, 2), { mode: 384 });
   try {
-    fs2.chmodSync(RC_FILE, 384);
+    fs2.chmodSync(rcFile(), 384);
   } catch {
   }
 }
@@ -1126,12 +1274,12 @@ function assertHttpsOrLocalhost(urlStr) {
   }
   throw new Error(`Unsupported protocol: ${url.protocol}`);
 }
-async function apiRequest(method, path14, body) {
+async function apiRequest(method, path15, body) {
   const config = loadConfig();
-  const url = assertHttpsOrLocalhost(`${config.api_url}${path14}`);
+  const url = assertHttpsOrLocalhost(`${config.api_url}${path15}`);
   const isHttps = url.protocol === "https:";
   const transport = isHttps ? https : http;
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve9, reject) => {
     const headers = {};
     if (config.token) headers["Authorization"] = `Bearer ${config.token}`;
     let postData;
@@ -1153,7 +1301,7 @@ async function apiRequest(method, path14, body) {
         res.on("data", (chunk) => data += chunk);
         res.on("end", () => {
           const { unwrapped, raw } = parseBody(data);
-          resolve7({
+          resolve9({
             status: res.statusCode ?? 0,
             data: unwrapped,
             raw
@@ -1186,7 +1334,7 @@ Content-Type: application/zip\r
   const fullBody = Buffer.concat([head, fileBuffer, tail]);
   const isHttps = url.protocol === "https:";
   const transport = isHttps ? https : http;
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve9, reject) => {
     const headers = {
       "Content-Type": `multipart/form-data; boundary=${boundary}`,
       "Content-Length": String(fullBody.byteLength)
@@ -1209,7 +1357,7 @@ Content-Type: application/zip\r
         res.on("data", (chunk) => data += chunk);
         res.on("end", () => {
           const { unwrapped, raw } = parseBody(data);
-          resolve7({
+          resolve9({
             status: res.statusCode ?? 0,
             data: unwrapped,
             raw
@@ -1265,11 +1413,11 @@ var devCommand = new import_commander2.Command("dev").description("Start local d
     console.log(
       `Starting Vite on ${options.expose ? "0.0.0.0" : "localhost"}:${options.port}...`
     );
-    const child = (0, import_child_process.spawn)("npx", args, { stdio: "inherit", shell: true });
+    const child = (0, import_child_process2.spawn)("npx", args, { stdio: "inherit", shell: true });
     let watcher = null;
     if (options.watch) {
       console.log("Starting bundle watcher (vite build --watch)...");
-      watcher = (0, import_child_process.spawn)(
+      watcher = (0, import_child_process2.spawn)(
         "npx",
         ["vite", "build", "--watch", "--mode", "development"],
         { stdio: "inherit", shell: true }
@@ -1295,6 +1443,7 @@ var devCommand = new import_commander2.Command("dev").description("Start local d
 
 // src/commands/check.ts
 var import_commander3 = require("commander");
+var import_child_process3 = require("child_process");
 
 // src/utils/validator.ts
 var fs4 = __toESM(require("fs"));
@@ -1387,23 +1536,88 @@ function validateTheme(themeDir) {
 }
 
 // src/commands/check.ts
-var checkCommand = new import_commander3.Command("check").description("Validate theme schemas and structure").option("-d, --dir <directory>", "Theme directory", ".").action(async (options) => {
-  console.log("Validating theme...");
-  const result = validateTheme(options.dir);
-  if (result.warnings.length > 0) {
-    console.log("\nWarnings:");
-    result.warnings.forEach((w) => console.log(`  \u26A0 ${w}`));
-  }
-  if (result.errors.length > 0) {
-    console.log("\nErrors:");
-    result.errors.forEach((e) => console.log(`  \u2717 ${e}`));
-    console.log(`
+var checkCommand = new import_commander3.Command("check").description("Validate theme schemas and structure").option("-d, --dir <directory>", "Theme directory", ".").option(
+  "--lighthouse",
+  "Run a Lighthouse audit (performance + accessibility) \u2014 needs --url"
+).option(
+  "--url <url>",
+  "URL of the built theme on a seeded store to audit (e.g. http://localhost:3100/<store>)"
+).option("--perf <score>", "Minimum Lighthouse performance score (0-100)", "60").option(
+  "--a11y <score>",
+  "Minimum Lighthouse accessibility score (0-100)",
+  "90"
+).option(
+  "--strict",
+  "Exit non-zero when below thresholds (default: soft gate \u2014 report only)"
+).action(
+  async (options) => {
+    console.log("Validating theme...");
+    const result = validateTheme(options.dir);
+    if (result.warnings.length > 0) {
+      console.log("\nWarnings:");
+      result.warnings.forEach((w) => console.log(`  \u26A0 ${w}`));
+    }
+    if (result.errors.length > 0) {
+      console.log("\nErrors:");
+      result.errors.forEach((e) => console.log(`  \u2717 ${e}`));
+      console.log(`
 Validation failed with ${result.errors.length} error(s)`);
+      process.exit(1);
+    }
+    console.log(`
+\u2713 Theme is valid (${result.warnings.length} warning(s))`);
+    if (options.lighthouse) {
+      runLighthouse(options);
+    }
+  }
+);
+function runLighthouse(options) {
+  if (!options.url) {
+    console.error(
+      "\n\u2718 --lighthouse requires --url <url> (a built theme on a seeded store)."
+    );
     process.exit(1);
   }
+  const perfMin = parseFloat(options.perf);
+  const a11yMin = parseFloat(options.a11y);
   console.log(`
-\u2713 Theme is valid (${result.warnings.length} warning(s))`);
-});
+Running Lighthouse against ${options.url} ...`);
+  let raw;
+  try {
+    raw = (0, import_child_process3.execSync)(
+      `npx --yes lighthouse "${options.url}" --output=json --output-path=stdout --only-categories=performance,accessibility --chrome-flags="--headless=new --no-sandbox --disable-gpu" --quiet --no-enable-error-reporting`,
+      { encoding: "utf-8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] }
+    );
+  } catch (e) {
+    console.warn(
+      "\n\u26A0 Could not run Lighthouse (install it: `npm i -g lighthouse`, and ensure Chrome is available). Soft-skipping."
+    );
+    console.warn(`   ${String(e.message).split("\n")[0]}`);
+    return;
+  }
+  let report;
+  try {
+    report = JSON.parse(raw);
+  } catch {
+    console.warn("\n\u26A0 Lighthouse output was not parseable JSON; skipping gate.");
+    return;
+  }
+  const perf = Math.round((report.categories?.performance?.score ?? 0) * 100);
+  const a11y = Math.round((report.categories?.accessibility?.score ?? 0) * 100);
+  console.log(`  Performance:   ${perf}  (min ${perfMin})`);
+  console.log(`  Accessibility: ${a11y}  (min ${a11yMin})`);
+  const failed = perf < perfMin || a11y < a11yMin;
+  if (!failed) {
+    console.log("\u2713 Lighthouse thresholds met.");
+    return;
+  }
+  const msg = `Lighthouse below threshold (Perf ${perf}/${perfMin}, A11y ${a11y}/${a11yMin}).`;
+  if (options.strict) {
+    console.error(`\u2718 ${msg}`);
+    process.exit(1);
+  }
+  console.warn(`\u26A0 ${msg}  (soft gate \u2014 pass --strict to enforce.)`);
+}
 
 // src/commands/lint.ts
 var import_commander4 = require("commander");
@@ -1425,7 +1639,9 @@ async function runAllRules(themeDir, options) {
     () => Promise.resolve().then(() => (init_inline_color_literal(), inline_color_literal_exports)),
     () => Promise.resolve().then(() => (init_forbidden_script_tag(), forbidden_script_tag_exports)),
     () => Promise.resolve().then(() => (init_use_app_no_availability_check(), use_app_no_availability_check_exports)),
-    () => Promise.resolve().then(() => (init_manifest_required_fields(), manifest_required_fields_exports))
+    () => Promise.resolve().then(() => (init_manifest_required_fields(), manifest_required_fields_exports)),
+    () => Promise.resolve().then(() => (init_contrast_hint(), contrast_hint_exports)),
+    () => Promise.resolve().then(() => (init_touch_target(), touch_target_exports))
   ];
   const issues = [];
   for (const load of ruleLoaders) {
@@ -1440,14 +1656,14 @@ async function runAllRules(themeDir, options) {
       });
       continue;
     }
-    const rule11 = mod.default;
-    if (options.enabledRules && !options.enabledRules.has(rule11.id)) continue;
+    const rule13 = mod.default;
+    if (options.enabledRules && !options.enabledRules.has(rule13.id)) continue;
     try {
-      const ruleIssues = await rule11.check(ctx);
+      const ruleIssues = await rule13.check(ctx);
       for (const issue of ruleIssues) issues.push(issue);
     } catch (e) {
       issues.push({
-        rule: rule11.id,
+        rule: rule13.id,
         severity: "warning",
         message: `Rule crashed: ${e.message}`
       });
@@ -1467,6 +1683,7 @@ function buildContext(themeDir) {
   const blockSchemas = readSchemaDir(path4.join(themeDir, "schemas", "blocks"));
   const locales = readLocales(path4.join(themeDir, "locales"));
   const sources = readSources(themeDir);
+  const styles = readText(path4.join(themeDir, "styles.css"));
   return {
     themeDir,
     manifest,
@@ -1474,7 +1691,8 @@ function buildContext(themeDir) {
     sectionSchemas,
     blockSchemas,
     locales,
-    sources
+    sources,
+    styles
   };
 }
 function readJson(filePath, fallback) {
@@ -1485,6 +1703,14 @@ function readJson(filePath, fallback) {
     return fallback;
   }
 }
+function readText(filePath) {
+  if (!fs5.existsSync(filePath)) return "";
+  try {
+    return fs5.readFileSync(filePath, "utf-8");
+  } catch {
+    return "";
+  }
+}
 function readSchemaDir(dir) {
   const out = {};
   if (!fs5.existsSync(dir)) return out;
@@ -1592,41 +1818,79 @@ function groupByFile(issues) {
 
 // src/commands/build.ts
 var import_commander5 = require("commander");
-var import_child_process2 = require("child_process");
+var import_child_process4 = require("child_process");
 var fs7 = __toESM(require("fs"));
 var path6 = __toESM(require("path"));
-var buildCommand = new import_commander5.Command("build").description("Build the theme for production").option("-d, --dir <directory>", "Theme directory", ".").action(async (options) => {
-  console.log("Validating before build...");
-  const result = validateTheme(options.dir);
-  if (!result.valid) {
-    console.error("Validation failed. Fix errors before building.");
-    result.errors.forEach((e) => console.error(`  \u2717 ${e}`));
-    process.exit(1);
-  }
-  console.log("Building theme...");
-  try {
-    (0, import_child_process2.execSync)("npx vite build", { cwd: options.dir, stdio: "inherit" });
-  } catch {
-    console.error("Build failed");
-    process.exit(1);
-  }
-  const distDir = path6.join(options.dir, "dist");
-  if (fs7.existsSync(distDir)) {
-    let totalSize = 0;
-    const files = fs7.readdirSync(distDir, { recursive: true });
-    for (const file of files) {
-      const filePath = path6.join(distDir, file);
-      if (fs7.statSync(filePath).isFile()) totalSize += fs7.statSync(filePath).size;
+var buildCommand = new import_commander5.Command("build").description("Build the theme for production").option("-d, --dir <directory>", "Theme directory", ".").option(
+  "--strict",
+  "Treat lint warnings as errors (Shopify-style a11y/quality gate)"
+).option("--no-lint", "Skip the lint gate (not recommended)").action(
+  async (options) => {
+    console.log("Validating before build...");
+    const result = validateTheme(options.dir);
+    if (!result.valid) {
+      console.error("Validation failed. Fix errors before building.");
+      result.errors.forEach((e) => console.error(`  \u2717 ${e}`));
+      process.exit(1);
     }
-    const sizeMB = (totalSize / 1024 / 1024).toFixed(2);
-    console.log(`
+    if (options.lint !== false) {
+      const issues = await runAllRules(
+        path6.resolve(process.cwd(), options.dir),
+        { enabledRules: null }
+      );
+      const errors = issues.filter((i) => i.severity === "error");
+      const warnings = issues.filter((i) => i.severity === "warning");
+      if (issues.length > 0) {
+        console.log("\nLint:");
+        for (const i of issues) {
+          const marker = i.severity === "error" ? "\u2718" : "\u26A0";
+          const loc = i.file ? ` ${i.file}${i.line ? ":" + i.line : ""}` : "";
+          console.log(`  ${marker} ${i.rule}${loc} \u2014 ${i.message}`);
+        }
+      }
+      const blocked = errors.length > 0 || options.strict && warnings.length > 0;
+      if (blocked) {
+        console.error(
+          `
+Lint gate failed: ${errors.length} error(s), ${warnings.length} warning(s)${options.strict ? " (--strict treats warnings as errors)" : ""}.`
+        );
+        process.exit(1);
+      }
+      if (warnings.length > 0) {
+        console.log(
+          `
+\u26A0 ${warnings.length} lint warning(s) \u2014 run \`numu-theme lint\` for detail, or \`--strict\` to enforce.`
+        );
+      }
+    }
+    console.log("Building theme...");
+    try {
+      (0, import_child_process4.execSync)("npx vite build", { cwd: options.dir, stdio: "inherit" });
+    } catch {
+      console.error("Build failed");
+      process.exit(1);
+    }
+    const distDir = path6.join(options.dir, "dist");
+    if (fs7.existsSync(distDir)) {
+      let totalSize = 0;
+      const files = fs7.readdirSync(distDir, { recursive: true });
+      for (const file of files) {
+        const filePath = path6.join(distDir, file);
+        if (fs7.statSync(filePath).isFile())
+          totalSize += fs7.statSync(filePath).size;
+      }
+      const sizeMB = (totalSize / 1024 / 1024).toFixed(2);
+      console.log(`
 Bundle size: ${sizeMB} MB`);
-    if (totalSize > 5 * 1024 * 1024) {
-      console.warn("\u26A0 Bundle exceeds 5MB limit \u2014 optimize before submitting to marketplace");
+      if (totalSize > 5 * 1024 * 1024) {
+        console.warn(
+          "\u26A0 Bundle exceeds 5MB limit \u2014 optimize before submitting to marketplace"
+        );
+      }
     }
+    console.log("\n\u2713 Build complete");
   }
-  console.log("\n\u2713 Build complete");
-});
+);
 
 // src/commands/push.ts
 var import_commander6 = require("commander");
@@ -1638,10 +1902,10 @@ var fs8 = __toESM(require("fs"));
 var import_archiver = __toESM(require("archiver"));
 async function zipDirectory(sourceDir, outputPath, optsOrLegacyExcludes = {}) {
   const opts = Array.isArray(optsOrLegacyExcludes) ? { excludePatterns: optsOrLegacyExcludes } : optsOrLegacyExcludes;
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve9, reject) => {
     const output = fs8.createWriteStream(outputPath);
     const archive = (0, import_archiver.default)("zip", { zlib: { level: 9 } });
-    output.on("close", () => resolve7(outputPath));
+    output.on("close", () => resolve9(outputPath));
     archive.on("error", reject);
     archive.pipe(output);
     const defaultExcludes = [
@@ -1792,7 +2056,7 @@ Submission failed (${submitRes.status}): ${JSON.stringify(submitRes.data)}`
 
 // src/commands/install.ts
 var import_commander8 = require("commander");
-var import_child_process3 = require("child_process");
+var import_child_process5 = require("child_process");
 var path9 = __toESM(require("path"));
 var os4 = __toESM(require("os"));
 var fs10 = __toESM(require("fs"));
@@ -1853,7 +2117,7 @@ var installCommand = new import_commander8.Command("install").description(
     console.log(`  install tag:  ${version}`);
     console.log("Building locally (so worker can skip npm install)...");
     try {
-      (0, import_child_process3.execSync)("npm run build", {
+      (0, import_child_process5.execSync)("npm run build", {
         cwd: options.dir,
         stdio: "inherit",
         env: { ...process.env, NODE_ENV: "production" }
@@ -3704,11 +3968,11 @@ var path13 = __toESM(require("path"));
 var https2 = __toESM(require("https"));
 var http2 = __toESM(require("http"));
 async function downloadToFile(url, dest) {
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve9, reject) => {
     const client = url.startsWith("https:") ? https2 : http2;
     const req = client.get(url, (res) => {
       if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        downloadToFile(res.headers.location, dest).then(resolve7, reject);
+        downloadToFile(res.headers.location, dest).then(resolve9, reject);
         return;
       }
       if (res.statusCode !== 200) {
@@ -3717,7 +3981,7 @@ async function downloadToFile(url, dest) {
       }
       const out = fs14.createWriteStream(dest);
       res.pipe(out);
-      out.on("finish", () => out.close(() => resolve7()));
+      out.on("finish", () => out.close(() => resolve9()));
       out.on("error", reject);
     });
     req.on("error", reject);
@@ -3822,10 +4086,10 @@ async function confirm(prompt) {
     input: process.stdin,
     output: process.stdout
   });
-  return new Promise((resolve7) => {
+  return new Promise((resolve9) => {
     rl.question(`${prompt} [y/N] `, (answer) => {
       rl.close();
-      resolve7(/^y(es)?$/i.test(answer.trim()));
+      resolve9(/^y(es)?$/i.test(answer.trim()));
     });
   });
 }
@@ -3842,8 +4106,8 @@ var deleteCommand = new import_commander15.Command("delete").description("Delete
         return;
       }
     }
-    const path14 = isVersion ? `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}/versions/${encodeURIComponent(options.version)}` : `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}`;
-    const res = await apiRequest("DELETE", path14);
+    const path15 = isVersion ? `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}/versions/${encodeURIComponent(options.version)}` : `/api/v1/marketplace/themes/${encodeURIComponent(themeId)}`;
+    const res = await apiRequest("DELETE", path15);
     if (res.status === 200 || res.status === 204) {
       console.log(`\u2714 Deleted ${scope}.`);
       return;
@@ -3861,8 +4125,773 @@ var deleteCommand = new import_commander15.Command("delete").description("Delete
   }
 );
 
+// src/commands/migrate.ts
+var import_commander16 = require("commander");
+var fs15 = __toESM(require("fs"));
+var path14 = __toESM(require("path"));
+var import_chalk = __toESM(require("chalk"));
+var V2_HOOK_PATTERNS = [
+  {
+    pattern: /from\s+["']@\/contexts\/StoreContext["']/,
+    v2: "useStore (bazaar)",
+    v3: "useShop() from @numueg/theme-sdk",
+    note: "Returns Store directly; bazaar's useStore returns { store, themeSettings, ... } \u2014 destructure differently."
+  },
+  {
+    pattern: /useProductsContext|from\s+["']@\/contexts\/ProductsContext["']/,
+    v2: "useProductsContext (bazaar)",
+    v3: "useProducts() from @numueg/theme-sdk",
+    note: "V3 hook is paginated + has loading state. Shape: { items, loading, error, hasMore, loadMore }. V2 returned flat array."
+  },
+  {
+    pattern: /useCart\s*\(\s*\)/,
+    v2: "useCart (bazaar)",
+    v3: "useCart() from @numueg/theme-sdk",
+    note: "Same name but different shape \u2014 SDK returns { cart, addItem, removeItem, ... } with async actions. Bazaar's was sync."
+  },
+  {
+    pattern: /useAuth\s*\(\s*\)/,
+    v2: "useAuth (bazaar)",
+    v3: "useCustomer() + useCustomerActions() from @numueg/theme-sdk",
+    note: "Customer state is split from action handlers in V3 to avoid render-on-every-action."
+  },
+  {
+    pattern: /useTheme\s*\(\s*\)|from\s+["']@\/contexts\/ThemeContext["']/,
+    v2: "useTheme (bazaar)",
+    v3: "useThemeSettings() from @numueg/theme-sdk",
+    note: "Returns ThemeSettingsV3; access settings via .global_settings or .templates[<page>].sections[<id>].settings."
+  },
+  {
+    pattern: /useLanguage\s*\(/,
+    v2: "useLanguage (bazaar)",
+    v3: "useLocalization() / useDirection() from @numueg/theme-sdk",
+    note: "Returns { locale, direction, translations, ... }. Use useTranslation() for resolving message keys."
+  },
+  {
+    pattern: /editable\.section\s*\(/,
+    v2: "editable.section() helper",
+    v3: "<EditableText> / <EditableImage> from @numueg/theme-sdk",
+    note: "V3 marks editable nodes via dedicated components instead of spread props."
+  }
+];
+function migrationNotesFor(source) {
+  const notes = [];
+  const lines = source.split("\n");
+  for (const { pattern, v2, v3, note } of V2_HOOK_PATTERNS) {
+    for (let i = 0; i < lines.length; i++) {
+      if (pattern.test(lines[i])) {
+        notes.push({ v2, v3, note, lineHint: i + 1 });
+        break;
+      }
+    }
+  }
+  return notes;
+}
+function adapterCommentBlock(notes, v2RelativePath) {
+  const lines = [
+    "/**",
+    " * \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
+    " *  V3 PORT \u2014 ADAPTER NOTES",
+    " * \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
+    " *",
+    ` *  Source: ${v2RelativePath}`,
+    " *",
+    " *  Generated by `numu-theme migrate`. Review and rewrite using V3",
+    " *  SDK hooks before publishing. The list below was inferred from",
+    " *  static analysis \u2014 there may be other V2 idioms not detected.",
+    " *"
+  ];
+  if (notes.length === 0) {
+    lines.push(" *  No V2-specific hooks detected. You may only need to:");
+    lines.push(" *    1. Replace any bazaar-specific imports with @numueg/theme-sdk equivalents.");
+    lines.push(" *    2. Wrap your section's root element with <Section id={...} type={...}> from the SDK.");
+    lines.push(" *    3. Read settings from `props.instance.settings` (V3 SectionInstance shape).");
+  } else {
+    lines.push(" *  Required swaps:");
+    lines.push(" *");
+    for (const n of notes) {
+      const where = n.lineHint ? ` (line ${n.lineHint})` : "";
+      lines.push(` *    \u2022 ${n.v2}${where}`);
+      lines.push(` *      \u2192 ${n.v3}`);
+      lines.push(` *      ${n.note}`);
+      lines.push(" *");
+    }
+  }
+  lines.push(" *  When done, remove this block.");
+  lines.push(" * \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+  lines.push(" */");
+  return lines.join("\n");
+}
+function findSectionFiles(dir) {
+  if (!fs15.existsSync(dir)) return [];
+  const out = [];
+  for (const entry of fs15.readdirSync(dir, { withFileTypes: true })) {
+    const full = path14.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...findSectionFiles(full));
+    else if (entry.isFile() && /\.(tsx|ts)$/.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+function sectionTypeFromFilename(filename) {
+  const base = path14.basename(filename).replace(/\.(tsx|ts)$/, "");
+  return base.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[^a-zA-Z0-9-]+/g, "-").toLowerCase();
+}
+function makeV2Bridge() {
+  return `/**
+ * v2-bridge \u2014 per-theme compat shim for V2 sections ported via
+ * \`numu-theme migrate\`. DELETE this file once each section has been
+ * rewritten to use idiomatic V3 SDK hooks + components.
+ */
+
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import {
+  useV2Products,
+  useV2Categories,
+  useV2Auth,
+  useV2Language,
+  useV2Theme,
+} from "@numueg/theme-sdk/v2-compat";
+import { ProductCard, useThemeSettings } from "@numueg/theme-sdk";
+import type { SectionInstance } from "@numueg/theme-sdk";
+
+// \u2500\u2500 Re-shaped V3 hooks under V2 names \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+/** V2's \`useProducts\` returned \`{ products, loading }\`. Same shape. */
+export function useProducts() {
+  return useV2Products();
+}
+
+/** V2's \`useCategories\` returned \`{ categories, loading }\`. Same shape. */
+export function useCategories() {
+  return useV2Categories();
+}
+
+/** V2's \`useAuth\` returned \`{ user, isAuthenticated }\`. */
+export function useAuth() {
+  return useV2Auth();
+}
+
+/** V2's \`useLanguage\` returned \`{ language, direction, setLanguage, t }\`. */
+export function useLanguage() {
+  return useV2Language();
+}
+
+/** V2's \`useStore\` returned the full store config; here we expose
+ *  only the parts ported sections use (themeSettings nested). */
+export function useStore() {
+  return useV2Theme();
+}
+
+// \u2500\u2500 V2 type re-shaping \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+/**
+ * V2 sections expected this prop shape:
+ *
+ *   interface SectionComponentProps {
+ *     section: { id: string; type: string; settings: Record<string, any>; ... };
+ *     ...
+ *   }
+ *
+ * V3 mount passes \`{ instance: SectionInstance }\`. We re-export a
+ * compatible interface so existing destructure patterns like
+ * \`const { section } = props\` keep compiling \u2014 the wrapper below
+ * coerces \`instance\` \u2192 \`section\` at render time.
+ */
+export interface SectionComponentProps {
+  section: SectionInstance & { id?: string };
+}
+
+/**
+ * Section adapter. Migrate-generated sections still expect to be
+ * called with \`{ section }\`; the V3 \`SECTION_REGISTRY\` calls them
+ * with \`{ instance }\`. Wrap each export:
+ *
+ *   export default v2Section(YourComponent);
+ */
+export function v2Section<P extends SectionComponentProps>(
+  Component: (props: P) => ReactNode,
+): (props: { instance: SectionInstance }) => ReactNode {
+  return function V2SectionAdapter({ instance }) {
+    const props = { section: instance } as unknown as P;
+    return Component(props);
+  };
+}
+
+// \u2500\u2500 editable.section() compat \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+/**
+ * V2's editable helper spread DOM props on individual nodes so the
+ * old V2 customizer could click-select them. V3 uses \`<EditableText>\`
+ * / \`<EditableImage>\` for the same job. Returning an empty object
+ * here means the spread is a no-op \u2014 the section still renders, just
+ * without the inline click-to-edit affordance. Replace with the V3
+ * components when polishing the port.
+ */
+export const editable = {
+  section: (_sectionId: string, _key: string) => ({}),
+  block: (_blockId: string, _key: string) => ({}),
+};
+
+// \u2500\u2500 Misc re-exports the V2 sections often imported \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+export { ProductCard, useThemeSettings };
+
+/**
+ * V2's \`<Link to="/...">\` came from react-router-dom. The V3 storefront
+ * is Next.js, where \`<a href="/...">\` works (Next intercepts internal
+ * navigation). We expose a polyfill so existing JSX renders without
+ * react-router-dom installed. Pass-through any extra props.
+ */
+export function Link({
+  to,
+  children,
+  ...rest
+}: { to: string; children: ReactNode } & Omit<
+  ComponentPropsWithoutRef<"a">,
+  "href"
+>) {
+  return (
+    <a href={to} {...rest}>
+      {children}
+    </a>
+  );
+}
+
+/** V2's image placeholder constant. */
+export const PLACEHOLDER_HERO =
+  "https://images.unsplash.com/photo-1483985988355-763728e1935b?auto=format&fit=crop&w=1200&q=60";
+`;
+}
+function rewriteV2Imports(source) {
+  const PATH_REWRITES = [
+    // The most-common bazaar context imports.
+    [/@\/contexts\/ProductsContext/g, "../v2-bridge"],
+    [/@\/contexts\/AuthContext/g, "../v2-bridge"],
+    [/@\/contexts\/LanguageContext/g, "../v2-bridge"],
+    [/@\/contexts\/StoreContext/g, "../v2-bridge"],
+    [/@\/contexts\/ThemeContext/g, "../v2-bridge"],
+    // V2 engine types + editable helper.
+    [/@\/themes\/engine\/types/g, "../v2-bridge"],
+    [/@\/themes\/engine\/editable/g, "../v2-bridge"],
+    // bazaar's shared ProductCard component.
+    [/@\/components\/store\/ProductCard/g, "../v2-bridge"],
+    // The image placeholder constant.
+    [/@\/lib\/imagePlaceholders/g, "../v2-bridge"],
+    // react-router-dom → bridge (Link polyfill). Only the named
+    // imports we know about; the bridge exports `Link`. Sections that
+    // need other react-router-dom APIs will fail at build time, which
+    // is the right outcome — they need manual conversion.
+    [/(['"])react-router-dom\1/g, '"../v2-bridge"']
+  ];
+  let out = source;
+  for (const [pattern, replacement] of PATH_REWRITES) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
+function makeThemeJson(themeId, displayName, sectionTypes) {
+  return {
+    id: themeId,
+    name: displayName,
+    author: "",
+    version: "0.1.0",
+    layout: "single-column",
+    description: `${displayName} \u2014 migrated from V2.`,
+    error_template: "templates/error.html",
+    loading_template: "templates/loading.html",
+    presets: {
+      templates: {
+        home: {
+          name: "Home",
+          sections: sectionTypes.map((type) => ({
+            type,
+            settings: {}
+          }))
+        }
+      }
+    }
+  };
+}
+function makeSettingsSchema() {
+  return [
+    {
+      name: "Brand",
+      settings: [
+        {
+          type: "color",
+          id: "primary_color",
+          label: "Primary color",
+          default: "#111111"
+        },
+        {
+          type: "color",
+          id: "accent_color",
+          label: "Accent color",
+          default: "#d4af37"
+        }
+      ]
+    }
+  ];
+}
+function makeMainTsx(themeId, displayName, sectionTypes) {
+  const registryEntries = sectionTypes.map((type) => `  "${type}": lazy(() => import("./sections/${type}")),`).join("\n");
+  return `/**
+ * ${displayName} (V3) \u2014 entry point.
+ *
+ * Generated by \`numu-theme migrate\`. Section components live in
+ * src/sections/<type>.tsx and are lazy-loaded so only sections the
+ * merchant actually uses pay the bundle cost.
+ */
+
+import {
+  StrictMode,
+  lazy,
+  Suspense,
+  useImperativeHandle,
+  useRef,
+  useState,
+  forwardRef,
+} from "react";
+import { createRoot, type Root } from "react-dom/client";
+import {
+  NuMuProvider,
+  Section,
+  useThemeSettings,
+  type ThemeSettingsV3,
+  type Store,
+  type Cart,
+  type Customer,
+  type SectionInstance,
+  type MountResult,
+} from "@numueg/theme-sdk";
+import themeManifest from "../theme.json";
+
+const SECTION_REGISTRY: Record<string, ReturnType<typeof lazy>> = {
+${registryEntries}
+};
+
+function UnknownSection({ type }: { type: string }) {
+  return (
+    <section style={{ padding: "1rem", border: "1px dashed #fb923c" }}>
+      Unknown section: <strong>{type}</strong>
+    </section>
+  );
+}
+
+interface ResolvedSection {
+  id: string;
+  instance: SectionInstance;
+}
+
+interface MaybeOrdered {
+  sections?: Record<string, SectionInstance> | SectionInstance[];
+  order?: string[];
+}
+
+function resolveSections(group: MaybeOrdered | undefined): ResolvedSection[] {
+  if (!group) return [];
+  if (Array.isArray(group.sections)) {
+    return group.sections.map((instance, idx) => ({
+      id: \`\${instance.type}-\${idx}\`,
+      instance,
+    }));
+  }
+  const map = (group.sections ?? {}) as Record<string, SectionInstance>;
+  const order = group.order ?? Object.keys(map);
+  return order
+    .map((id): ResolvedSection | null => {
+      const instance = map[id];
+      if (!instance) return null;
+      return { id, instance };
+    })
+    .filter((x): x is ResolvedSection => Boolean(x));
+}
+
+const BUILTIN_HOME = (themeManifest as unknown as { presets?: { templates?: { home?: MaybeOrdered } } })
+  .presets?.templates?.home;
+
+function RenderSection({
+  instance,
+  sectionId,
+  groupId,
+}: {
+  instance: SectionInstance;
+  sectionId: string;
+  groupId?: string;
+}) {
+  const Component = SECTION_REGISTRY[instance.type];
+  if (!Component) {
+    return (
+      <Section id={sectionId} type={instance.type} groupId={groupId}>
+        <UnknownSection type={instance.type} />
+      </Section>
+    );
+  }
+  return (
+    <Section id={sectionId} type={instance.type} groupId={groupId}>
+      <Suspense fallback={<div style={{ minHeight: "20vh" }} />}>
+        <Component instance={instance} />
+      </Suspense>
+    </Section>
+  );
+}
+
+function ThemeApp() {
+  const settings = useThemeSettings();
+  const hostHome = settings.templates?.home as MaybeOrdered | undefined;
+  const sections = resolveSections(hostHome ?? BUILTIN_HOME);
+  return (
+    <div data-${themeId}-app>
+      {sections.map(({ id, instance }) => (
+        <RenderSection key={id} sectionId={id} instance={instance} />
+      ))}
+    </div>
+  );
+}
+
+// \u2500\u2500 Host contract: mount(el, ctx) returns a MountResult \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+export interface MountContext {
+  store: Store;
+  themeSettings: ThemeSettingsV3;
+  initialCart?: Cart;
+  customer?: Customer | null;
+  locale?: string;
+  translations?: Record<string, string>;
+  [extra: string]: unknown;
+}
+
+interface DraftHandle {
+  applyDraft: (next: ThemeSettingsV3) => void;
+}
+
+const ThemeSettingsBridge = forwardRef<DraftHandle, { ctx: MountContext }>(
+  function ThemeSettingsBridge({ ctx }, ref) {
+    const [themeSettings, setThemeSettings] = useState<ThemeSettingsV3>(
+      ctx.themeSettings,
+    );
+    useImperativeHandle(
+      ref,
+      () => ({
+        applyDraft: (next) => setThemeSettings((prev) => (prev === next ? prev : next)),
+      }),
+      [],
+    );
+    return (
+      <NuMuProvider
+        store={ctx.store}
+        themeSettings={themeSettings}
+        initialCart={ctx.initialCart}
+        customer={ctx.customer}
+        locale={ctx.locale}
+        translations={ctx.translations}
+      >
+        <ThemeApp />
+      </NuMuProvider>
+    );
+  },
+);
+
+let currentRoot: Root | null = null;
+
+export function mount(el: HTMLElement, ctx: MountContext): MountResult {
+  if (currentRoot) {
+    currentRoot.unmount();
+    currentRoot = null;
+  }
+  const root = createRoot(el);
+  currentRoot = root;
+  const handleRef = { current: null as DraftHandle | null };
+  root.render(
+    <StrictMode>
+      <ThemeSettingsBridge
+        ctx={ctx}
+        ref={(h) => {
+          handleRef.current = h;
+        }}
+      />
+    </StrictMode>,
+  );
+  return {
+    applyDraft: (next) => handleRef.current?.applyDraft(next),
+    cleanup: () => {
+      root.unmount();
+      if (currentRoot === root) currentRoot = null;
+      handleRef.current = null;
+    },
+  };
+}
+
+const v3Handle = {
+  kind: "v3-mount" as const,
+  numu_theme_version: 3 as const,
+  mount_returns: "MountResult" as const,
+  manifest: { id: "${themeId}", name: "${displayName}", version: "0.1.0" },
+  mount,
+};
+export default v3Handle;
+`;
+}
+function makeViteConfig() {
+  return `import { defineConfig, type PluginOption } from "vite";
+import react from "@vitejs/plugin-react";
+import { numuTheme } from "@numueg/theme-plugin";
+
+export default defineConfig({
+  plugins: [react(), numuTheme({ federate: false }) as unknown as PluginOption],
+  server: { port: 5173 },
+});
+`;
+}
+function makePackageJson(themeId, displayName) {
+  return {
+    name: themeId,
+    version: "0.1.0",
+    private: true,
+    description: `${displayName} (V3 port)`,
+    type: "module",
+    scripts: {
+      dev: "vite",
+      build: "vite build",
+      preview: "vite preview --port 5173"
+    },
+    dependencies: {
+      react: "^18.3.1",
+      "react-dom": "^18.3.1",
+      "@numueg/theme-sdk": "^0.1.0",
+      // V2 sections commonly import these — including them in deps so
+      // `npm install` works without manual edits. The bundle externalises
+      // react/react-dom/@numueg/theme-sdk via federation; framer-motion
+      // and lucide-react ship as part of the theme bundle (~30-40 KB
+      // gzip combined). Themes that prove they don't need them can
+      // remove these after polishing.
+      "framer-motion": "^11.11.0",
+      "lucide-react": "^0.454.0"
+    },
+    devDependencies: {
+      "@numueg/theme-plugin": "^0.1.0",
+      "@types/react": "^18.3.0",
+      "@types/react-dom": "^18.3.0",
+      "@vitejs/plugin-react": "^4.3.0",
+      typescript: "^5.5.0",
+      vite: "^6.0.0"
+    }
+  };
+}
+function makeTsConfig() {
+  return {
+    compilerOptions: {
+      target: "ES2022",
+      lib: ["ES2022", "DOM", "DOM.Iterable"],
+      module: "ESNext",
+      moduleResolution: "Bundler",
+      jsx: "react-jsx",
+      strict: true,
+      noImplicitAny: true,
+      strictNullChecks: true,
+      esModuleInterop: true,
+      resolveJsonModule: true,
+      skipLibCheck: true,
+      isolatedModules: true,
+      allowSyntheticDefaultImports: true,
+      forceConsistentCasingInFileNames: true
+    },
+    include: ["src", "theme.json"]
+  };
+}
+function makeIndexHtml(displayName) {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${displayName} \u2014 dev preview</title>
+    <link rel="stylesheet" href="/styles.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`;
+}
+function makeTemplates() {
+  return {
+    error: `<!-- Static BYOT error template -->
+<main role="alert" style="min-height:100vh;display:flex;align-items:center;justify-content:center;padding:1rem;font-family:system-ui">
+  <div style="text-align:center;max-width:28rem">
+    <h1 style="font-size:1.5rem;font-weight:700;color:#b91c1c">Something went wrong</h1>
+    <p style="color:#374151;margin-top:.5rem">Please try again in a moment.</p>
+    <button data-numu-reset type="button" style="margin-top:1.5rem;padding:.5rem 1rem;background:#1d4ed8;color:white;border-radius:.375rem;border:0;cursor:pointer">Try again</button>
+  </div>
+</main>
+`,
+    loading: `<!-- Static BYOT loading skeleton -->
+<div role="status" aria-live="polite" aria-label="Loading" style="min-height:100vh;display:flex;align-items:center;justify-content:center;padding:1rem;font-family:system-ui">
+  <span style="font-size:.875rem;font-weight:500;color:#4b5563">Loading\u2026</span>
+</div>
+`
+  };
+}
+var migrateCommand = new import_commander16.Command("migrate").description("Scaffold a V3 theme project from a V2 theme directory").argument(
+  "<v2-path>",
+  "Path to the V2 theme directory (e.g. ../numu-egyptian-bazaar/src/themes/empire)"
+).option(
+  "--out <dir>",
+  "Output directory (default: ./<v2-id>-engine-V3)"
+).option(
+  "--name <displayName>",
+  "Override the display name (default: title-cased v2 id)"
+).action(
+  async (v2Path, options) => {
+    const absV2Path = path14.resolve(process.cwd(), v2Path);
+    if (!fs15.existsSync(absV2Path) || !fs15.statSync(absV2Path).isDirectory()) {
+      console.error(import_chalk.default.red(`V2 path does not exist or is not a directory: ${absV2Path}`));
+      process.exit(1);
+    }
+    const v2Id = path14.basename(absV2Path).toLowerCase().replace(/[^a-z0-9-]/g, "-");
+    const themeId = `${v2Id}-v3`;
+    const displayName = options.name ?? v2Id.charAt(0).toUpperCase() + v2Id.slice(1).replace(/-/g, " ") + " (V3)";
+    const outDir = path14.resolve(
+      process.cwd(),
+      options.out ?? `${v2Id}-engine-V3`
+    );
+    if (fs15.existsSync(outDir)) {
+      console.error(import_chalk.default.red(`Output directory already exists: ${outDir}`));
+      console.error(import_chalk.default.dim("Remove it first, or pass --out to a fresh location."));
+      process.exit(1);
+    }
+    console.log(import_chalk.default.bold(`
+Migrating V2 \u2192 V3:`));
+    console.log(`  ${import_chalk.default.dim("from")} ${absV2Path}`);
+    console.log(`  ${import_chalk.default.dim("  to")} ${outDir}
+`);
+    for (const d of [
+      "src/sections",
+      "src/v2-bridge",
+      "schemas/sections",
+      "schemas/blocks",
+      "templates"
+    ]) {
+      fs15.mkdirSync(path14.join(outDir, d), { recursive: true });
+    }
+    fs15.writeFileSync(
+      path14.join(outDir, "src/v2-bridge", "index.tsx"),
+      makeV2Bridge()
+    );
+    const v2Styles = path14.join(absV2Path, "styles.css");
+    if (fs15.existsSync(v2Styles)) {
+      fs15.copyFileSync(v2Styles, path14.join(outDir, "styles.css"));
+      console.log(import_chalk.default.green("  \u2713 Copied styles.css"));
+    } else {
+      fs15.writeFileSync(
+        path14.join(outDir, "styles.css"),
+        `/* ${displayName} styles */
+`
+      );
+      console.log(import_chalk.default.yellow("  \u26A0 No styles.css found \u2014 created an empty one"));
+    }
+    const v2SectionsDir = path14.join(absV2Path, "sections");
+    const sectionFiles = fs15.existsSync(v2SectionsDir) ? findSectionFiles(v2SectionsDir) : [];
+    const sectionTypes = [];
+    const allNotes = [];
+    for (const file of sectionFiles) {
+      if (!file.endsWith(".tsx")) continue;
+      const type = sectionTypeFromFilename(file);
+      sectionTypes.push(type);
+      const v2Source = fs15.readFileSync(file, "utf-8");
+      const notes = migrationNotesFor(v2Source);
+      allNotes.push({ file, type, notes });
+      const relativeV2 = path14.relative(process.cwd(), file);
+      const header = adapterCommentBlock(notes, relativeV2);
+      const rewritten = rewriteV2Imports(v2Source);
+      const ported = `${header}
+
+${rewritten}`;
+      fs15.writeFileSync(
+        path14.join(outDir, "src/sections", `${type}.tsx`),
+        ported
+      );
+      fs15.writeFileSync(
+        path14.join(outDir, "schemas/sections", `${type}.json`),
+        JSON.stringify(
+          {
+            type,
+            name: type.split("-").map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join(" "),
+            settings: []
+          },
+          null,
+          2
+        )
+      );
+    }
+    console.log(import_chalk.default.green(`  \u2713 Ported ${sectionTypes.length} section file(s)`));
+    fs15.writeFileSync(
+      path14.join(outDir, "theme.json"),
+      JSON.stringify(makeThemeJson(themeId, displayName, sectionTypes), null, 2)
+    );
+    fs15.writeFileSync(
+      path14.join(outDir, "settings_schema.json"),
+      JSON.stringify(makeSettingsSchema(), null, 2)
+    );
+    fs15.writeFileSync(
+      path14.join(outDir, "src/main.tsx"),
+      makeMainTsx(themeId, displayName, sectionTypes)
+    );
+    fs15.writeFileSync(
+      path14.join(outDir, "vite.config.ts"),
+      makeViteConfig()
+    );
+    fs15.writeFileSync(
+      path14.join(outDir, "package.json"),
+      JSON.stringify(makePackageJson(themeId, displayName), null, 2)
+    );
+    fs15.writeFileSync(
+      path14.join(outDir, "tsconfig.json"),
+      JSON.stringify(makeTsConfig(), null, 2)
+    );
+    fs15.writeFileSync(
+      path14.join(outDir, "index.html"),
+      makeIndexHtml(displayName)
+    );
+    const tpl = makeTemplates();
+    fs15.writeFileSync(path14.join(outDir, "templates/error.html"), tpl.error);
+    fs15.writeFileSync(path14.join(outDir, "templates/loading.html"), tpl.loading);
+    fs15.writeFileSync(
+      path14.join(outDir, ".gitignore"),
+      "node_modules/\ndist/\n.DS_Store\n"
+    );
+    console.log(import_chalk.default.green("  \u2713 Wrote scaffold files\n"));
+    const filesWithNotes = allNotes.filter((n) => n.notes.length > 0);
+    if (filesWithNotes.length > 0) {
+      console.log(import_chalk.default.bold.yellow("Sections that need manual review:"));
+      for (const { type, notes } of filesWithNotes) {
+        console.log(
+          `
+  ${import_chalk.default.cyan(type)} ${import_chalk.default.dim(`(${notes.length} V2 hooks to swap)`)}`
+        );
+        for (const n of notes) {
+          console.log(
+            `    \u2022 ${import_chalk.default.dim(`L${n.lineHint ?? "?"}`)} ${n.v2} \u2192 ${import_chalk.default.green(n.v3)}`
+          );
+        }
+      }
+      console.log();
+    }
+    console.log(import_chalk.default.bold("\nNext steps:"));
+    console.log(`  ${import_chalk.default.cyan("cd")} ${path14.relative(process.cwd(), outDir)}`);
+    console.log(`  ${import_chalk.default.cyan("npm install")}`);
+    console.log(`  ${import_chalk.default.cyan("npm run dev")}                ${import_chalk.default.dim("# dev preview on :5173")}`);
+    console.log(`  ${import_chalk.default.cyan("npx numu-theme build")}       ${import_chalk.default.dim("# validate + build")}`);
+    console.log(
+      `
+${import_chalk.default.dim("Open each src/sections/*.tsx and follow the ADAPTER NOTES at the top.")}`
+    );
+  }
+);
+
 // src/index.ts
-var program = new import_commander16.Command();
+var program = new import_commander17.Command();
 program.name("numu-theme").description("CLI for developing, validating, building, and publishing NUMU themes").version("0.1.0");
 program.addCommand(initCommand);
 program.addCommand(devCommand);
@@ -3879,4 +4908,5 @@ program.addCommand(addSectionCommand);
 program.addCommand(addBlockCommand);
 program.addCommand(pullCommand);
 program.addCommand(deleteCommand);
+program.addCommand(migrateCommand);
 program.parse();