znode-plugin 0.1.4 → 0.1.5

package/lib/znode-package.mjs

@@ -1,680 +1,873 @@
-#!/usr/bin/env node
-// znode-plugin: build, pack and install Znode runtime packages (themes, plugins, widgets, content).
-//
-//   znode build   <packageDir|manifest.json>    build into <packageDir>/dist
-//   znode pack    <packageDir|manifest.json>    build, then zip it as
-//                                                                    <packageDir>/releases/<name>-<version>.zpkg.zip
-//   znode install <zip|packageDir> [storeDir]   validate and install into the store's plugin
-//                                                                    directory (default: RUNTIME_PLUGINS_DIR);
-//                                                                    the registry entry keeps its settings and stores
-//   znode create  <theme|plugin|widget|content> <name> [dir]
-//                                                                    a starter package that builds as it is
-//                                                                    (default dir ./<name>)
-//   znode check   <packageDir>                  marketplace review: metadata, permissions against
-//                                                                    the code, settings, size, server-render format
-//   znode deploy  <packageDir> [storeDir]       pack, then install into the store's plugin directory
-//   znode dev     <packageDir> [storeDir]       deploy, then again on every change under src/ or to the manifest
-//   znode link-store <storeRepoDir> [dir]       the store's real types: writes tsconfig.store.json (see README)
-//
-// A package is a folder with znode-package.json (README.md shows a whole project, as create-znode-plugin makes it):
-// {
-//   "name": "artifi", "version": "1.0.0", "kind": "plugin" | "theme" | "widget" | "content", "apiVersion": 1,
-//   "label": "...", "publisher": "...", "description": "...", "parent": "<theme>",          (parent: themes only)
-//   "build": { "server": "src/server.ts", "browser": "src/browser.tsx" },                  (TypeScript entry points)
-//   "styles": ["src/styles/*.css"], "assets": ["src/assets/fonts/*.woff2"], "messages": "src/i18n/labels.json",
-//   "pages": { "/": "src/pages/home.json" }, "widgets": ["HeroBanner"],
-//   code imports Next.js as an app does: next/image, next/link, next/navigation, next/font/google, react
-//   (next-imports.mjs: the store's own modules at runtime; Google fonts downloaded into the package when it builds)
-//   "overrides": { "/api/place-order": "place-order" },   (store BFF routes it takes over, by one of its routes)
-//   "serverPages": ["/my-page"],   (whole pages at new URLs, rendered by its server part's serverPages)
-//   "dedupeStyles": true,      (styles: drop the rules the store already has; STORE_URL = a page of a running store)
-//   "settingsSchema": { "websiteId": { "type": "string", "required": true, "browser": true, "label": "..." },
-//                       "banner": { "type": "string", "browser": true, "attribute": "StoreBannerText" } },
-//                       (attribute: the value comes from a Znode global attribute, "Code" for the store's, or
-//                        { "code": "...", "levels": ["store", "account", "user"] }; the most specific level wins)
-//   marketplace: "license", "keywords", "homepage", "compatibility": { "webstore": ">=10.0.0" },
-//   "permissions": ["routes", "cartHooks", "overrides", "znodeApi", "externalNetwork", "uploads"]   (what it does beyond UI;
-//                  "uploads": its routes take files, multipart/form-data up to RUNTIME_PLUGIN_UPLOAD_BYTES)
-//   "sandbox": true   (its server part runs in a separate, permission-limited Node process: routes and overrides only)
-// }
-import fs from "node:fs";
-import path from "node:path";
-import { execFileSync, spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import vm from "node:vm";
-import { TEMPLATES } from "./templates.mjs";
-
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const MANIFEST = "znode-package.json";
-// the build tools (TypeScript, rollup, adm-zip, postcss): this package's own dependencies, wherever npm put them
-// (ZNODE_TOOLS: a node_modules folder to use instead)
-const require = process.env.ZNODE_TOOLS ? createRequire(path.join(process.env.ZNODE_TOOLS, "noop.js")) : createRequire(import.meta.url);
-// a dependency's folder (its package.json's), found from what it resolves to
-function packageDir(name) {
-  for (let dir = path.dirname(require.resolve(name)); dir !== path.dirname(dir); dir = path.dirname(dir)) {
-    const file = path.join(dir, "package.json");
-    if (fs.existsSync(file) && JSON.parse(fs.readFileSync(file, "utf8")).name === name) return dir;
-  }
-  throw new Error(`znode-plugin: ${name} is not installed`);
-}
-const TSC = () => path.join(packageDir("typescript"), "bin", "tsc");
-const ROLLUP = () => path.join(packageDir("rollup"), "dist", "bin", "rollup");
-const AdmZip = require("adm-zip");
-
-const API_VERSION = 1;
-const KINDS = ["theme", "plugin", "widget", "content"];
-const NAME = /^[a-z0-9][a-z0-9-]{1,48}$/;
-const VERSION = /^\d+\.\d+\.\d+(-[0-9a-z.-]+)?$/i;
-const SERVED = new Set([".mjs", ".map", ".css", ".woff2", ".woff", ".ttf", ".otf", ".svg", ".png", ".jpg", ".jpeg", ".webp", ".gif", ".json"]);
-const MAX_BYTES = 10 * 1024 * 1024;
-const SETTING_TYPES = ["string", "number", "boolean", "list", "json", "object", "array"];
-const ATTRIBUTE_LEVELS = ["store", "account", "user"];
-const ATTRIBUTE_CODE = /^[A-Za-z][A-Za-z0-9_]{1,99}$/;
-const PERMISSIONS = ["routes", "cartHooks", "overrides", "znodeApi", "externalNetwork", "uploads"];
-
-const fail = (message) => {
-  console.error(`znode-package: ${message}`);
-  process.exit(1);
-};
-const readJson = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
-const glob = (dir, pattern) => {
-  const folder = path.join(dir, path.dirname(pattern));
-  const re = new RegExp(
-    `^${path
-      .basename(pattern)
-      .replace(/[.+^${}()|[\]\\]/g, "\\$&")
-      .replace(/\*/g, ".*")}$`
-  );
-  return fs.existsSync(folder)
-    ? fs
-        .readdirSync(folder)
-        .filter((name) => re.test(name))
-        .map((name) => path.join(folder, name))
-    : [];
-};
-
-function validateManifest(manifest, where) {
-  if (!NAME.test(manifest.name || "")) fail(`${where}: name must be lowercase letters, digits and dashes`);
-  if (!VERSION.test(manifest.version || "")) fail(`${where}: version must be semver (1.2.3)`);
-  if (!KINDS.includes(manifest.kind)) fail(`${where}: kind must be one of ${KINDS.join(", ")}`);
-  if (manifest.apiVersion !== API_VERSION) fail(`${where}: apiVersion ${manifest.apiVersion} isn't supported (this store runs ${API_VERSION})`);
-  if (manifest.parent && manifest.kind !== "theme") fail(`${where}: only a theme has a parent`);
-  // whole pages its server part renders (IRuntimePlugin.serverPages), at new lowercase URLs the store doesn't use
-  if (manifest.serverPages !== undefined) {
-    if (!Array.isArray(manifest.serverPages)) fail(`${where}: serverPages must be a list of paths ("/my-page")`);
-    // the source manifest names the entry (build.server), the built one the file (files.server)
-    if (manifest.serverPages.length && !manifest.build?.server && !manifest.files?.server) fail(`${where}: serverPages need a server part (build.server)`);
-    for (const page of manifest.serverPages) {
-      if (!/^\/[a-z0-9][a-z0-9-]*(\/[a-z0-9][a-z0-9-]*)*$/.test(String(page))) fail(`${where}: serverPages "${page}" must be a lowercase path like /my-page`);
-      if (/^\/(api|runtime-page|_next|login|signup|account|cart|checkout|search|product|category|404|error|maintenance)(\/|$)/.test(page)) fail(`${where}: serverPages "${page}" is a store route`);
-    }
-  }
-  // store BFF routes the package takes over: "/api/<path>" -> one of its own routes
-  for (const [route, target] of Object.entries(manifest.overrides || {})) {
-    if (!/^\/api\/[A-Za-z0-9/_-]+$/.test(route) || /^\/api\/extensions(\/|$)/.test(route)) fail(`${where}: override "${route}" must be a store route under /api/`);
-    if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(String(target))) fail(`${where}: override "${route}" must name one of the package's routes`);
-  }
-  for (const [key, field] of Object.entries(manifest.settingsSchema || {})) {
-    if (field?.type !== undefined && !SETTING_TYPES.includes(field.type)) fail(`${where}: setting "${key}" has type "${field.type}" (one of ${SETTING_TYPES.join(", ")})`);
-    const attribute = field?.attribute;
-    if (attribute === undefined) continue;
-    const code = typeof attribute === "string" ? attribute : attribute?.code;
-    if (!ATTRIBUTE_CODE.test(String(code || ""))) fail(`${where}: setting "${key}" names attribute "${code}" (letters, digits and _, as Znode attribute codes)`);
-    const levels = typeof attribute === "string" ? ["store"] : attribute.levels || ["store"];
-    if (!Array.isArray(levels) || !levels.length || levels.some((level) => !ATTRIBUTE_LEVELS.includes(level))) {
-      fail(`${where}: setting "${key}" attribute levels must be some of ${ATTRIBUTE_LEVELS.join(", ")}`);
-    }
-  }
-  if (manifest.sandbox !== undefined && typeof manifest.sandbox !== "boolean") fail(`${where}: sandbox must be true or false`);
-  if (manifest.permissions !== undefined && (!Array.isArray(manifest.permissions) || manifest.permissions.some((item) => !PERMISSIONS.includes(item)))) {
-    fail(`${where}: permissions must be some of ${PERMISSIONS.join(", ")}`);
-  }
-}
-
-// ---- build: TypeScript entry points -> one ES module each (tsc + rollup), plus styles, assets, labels, pages ----
-// a package folder (its znode-package.json) or one of several manifests in a folder (<name>.znode-package.json)
-function resolvePackage(target) {
-  const isFile = fs.statSync(target).isFile();
-  const dir = isFile ? path.dirname(target) : target;
-  const manifestFile = isFile ? target : path.join(dir, MANIFEST);
-  return { dir, manifestFile, outName: path.basename(manifestFile) === MANIFEST ? "dist" : `dist-${path.basename(manifestFile, `.${MANIFEST}`)}` };
-}
-
-// The package's tsconfig check. tsc also checks the store files the package imports; their errors are the store's, not
-// the package's: listed as warnings. An error in the package's own files stops the build.
-function typeCheck(dir, tsconfigFile) {
-  let output = "";
-  try {
-    execFileSync(process.execPath, [TSC(), "-p", tsconfigFile, "--noEmit", "--pretty", "false"], {
-      cwd: dir,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    return;
-  } catch (error) {
-    output = `${error.stdout || ""}${error.stderr || ""}`;
-  }
-  // one entry per error: "file(line,col): error TSnnnn: message" and its indented continuation lines
-  const errors = output.split(/\r?\n(?=\S)/).filter((entry) => /^.+?\(\d+,\d+\): error TS\d+:/.test(entry));
-  if (!errors.length) fail(`tsconfig check failed:\n${output}`);
-  const inPackage = (entry) => !path.relative(dir, path.resolve(dir, entry.slice(0, entry.indexOf("(")))).startsWith("..");
-  const own = errors.filter(inPackage);
-  const store = errors.filter((entry) => !inPackage(entry));
-  if (store.length) console.log(`warning ${store.length} type error(s) in store files the package imports (the store's to fix):\n  ${store.join("\n  ")}`);
-  if (own.length) fail(`type errors in the package:\n  ${own.join("\n  ")}`);
-}
-
-// every .ts / .tsx under srcRoot compiled to .js under outRoot, one file at a time and without resolving imports (the
-// tsconfig check has done the types): types removed, JSX as Next.js compiles it (react/jsx-runtime)
-function transpileSources(srcRoot, outRoot) {
-  const ts = require("typescript");
-  const walk = (folder) =>
-    fs.readdirSync(folder, { withFileTypes: true }).flatMap((item) => {
-      const file = path.join(folder, item.name);
-      if (item.isDirectory()) return walk(file);
-      return /\.tsx?$/.test(item.name) && !item.name.endsWith(".d.ts") ? [file] : [];
-    });
-  for (const file of walk(srcRoot)) {
-    const { outputText } = ts.transpileModule(fs.readFileSync(file, "utf8"), {
-      fileName: file,
-      compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ES2022, jsx: ts.JsxEmit.ReactJSX, jsxImportSource: "react" },
-    });
-    const target = path.join(outRoot, path.relative(srcRoot, file)).replace(/\.tsx?$/, ".js");
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(target, outputText);
-  }
-}
-
-function build(target) {
-  const { dir, manifestFile, outName } = resolvePackage(target);
-  const manifest = readJson(manifestFile);
-  validateManifest(manifest, path.basename(manifestFile));
-  const out = path.join(dir, outName);
-  fs.rmSync(out, { recursive: true, force: true });
-  fs.mkdirSync(out, { recursive: true });
-  const tmp = path.join(dir, ".build");
-  const files = {};
-  const prefix = `${manifest.name}-${manifest.version}`;
-  // next/font/google fonts built into the package (next-imports.mjs): their files and @font-face CSS
-  const fonts = [];
-  // A package with its own tsconfig.json (extending the store's tsconfig.base.json) is checked against the store's real
-  // types (every @znode alias, no declarations to write), then compiled file by file without type information, JSX as
-  // Next.js does (react/jsx-runtime: the store's). Without one, the package compiles as before (tsc, JSX factory h).
-  const tsconfigFile = path.join(dir, "tsconfig.json");
-  const projectMode = fs.existsSync(tsconfigFile);
-  if (projectMode && Object.values(manifest.build || {}).length) typeCheck(dir, tsconfigFile);
-
-  for (const part of ["server", "browser"]) {
-    const entry = manifest.build?.[part];
-    if (!entry) continue;
-    fs.rmSync(tmp, { recursive: true, force: true });
-    if (projectMode) transpileSources(path.dirname(path.join(dir, entry)), tmp);
-    else execFileSync(
-      process.execPath,
-      [
-        TSC(),
-        "--target",
-        "es2022",
-        "--module",
-        "es2022",
-        "--moduleResolution",
-        "bundler",
-        "--lib",
-        "es2022,dom",
-        "--skipLibCheck",
-        // import React from "react", as the store's own components do
-        "--allowSyntheticDefaultImports",
-        "--jsx",
-        "react",
-        "--jsxFactory",
-        "h",
-        "--jsxFragmentFactory",
-        "Fragment",
-        "--outDir",
-        tmp,
-        path.join(dir, entry),
-      ],
-      { stdio: "inherit" }
-    );
-    const compiled = path.join(tmp, path.basename(entry).replace(/\.tsx?$/, ".js"));
-    const target = `${prefix}.${part}.mjs`;
-    // rollup with the Next.js imports plugin (next-imports.mjs), from a config file: the plugin downloads fonts, which
-    // is async, in rollup's own process; what it built comes back in fonts.json
-    const config = path.join(tmp, "rollup.config.mjs");
-    const fontsFile = path.join(tmp, "fonts.json");
-    fs.writeFileSync(
-      config,
-      [
-        `import fs from "node:fs";`,
-        `import { znodeNext } from ${JSON.stringify(pathToFileURL(path.join(HERE, "next-imports.mjs")).href)};`,
-        `const fonts = [];`,
-        `export default {`,
-        `  input: ${JSON.stringify(compiled)},`,
-        `  output: { file: ${JSON.stringify(path.join(out, target))}, format: "es", sourcemap: true },`,
-        `  plugins: [`,
-        `    znodeNext({ part: ${JSON.stringify(part)}, prefix: ${JSON.stringify(prefix)}, outDir: ${JSON.stringify(out)}, fonts }),`,
-        `    { name: "fonts-out", writeBundle() { fs.writeFileSync(${JSON.stringify(fontsFile)}, JSON.stringify(fonts)); } },`,
-        `  ],`,
-        `};`,
-      ].join("\n")
-    );
-    execFileSync(process.execPath, [ROLLUP(), "--config", config, "--silent"], { stdio: "inherit" });
-    if (fs.existsSync(fontsFile)) fonts.push(...JSON.parse(fs.readFileSync(fontsFile, "utf8")));
-    files[part] = target;
-  }
-  fs.rmSync(tmp, { recursive: true, force: true });
-
-  // styles: concatenated into one stylesheet, after the fonts next/font/google built; assets (fonts, images) keep their
-  // names, which the stylesheet refers to
-  if (manifest.styles?.length || fonts.length) {
-    const css = [
-      ...fonts.map((font) => font.css),
-      ...(manifest.styles || []).flatMap((pattern) => glob(dir, pattern)).map((file) => fs.readFileSync(file, "utf8")),
-    ].join("\n");
-    files.styles = [`${prefix}.css`];
-    fs.writeFileSync(path.join(out, files.styles[0]), css);
-    // rules the store's own stylesheets already have, loaded again later, would beat its responsive variants
-    if (manifest.dedupeStyles) {
-      const target = path.join(out, files.styles[0]);
-      execFileSync(process.execPath, [path.join(HERE, "css-dedupe.mjs"), target, process.env.STORE_URL || "http://staplespromo.localhost:3000/", target], { stdio: "inherit" });
-    }
-  }
-  files.assets = (manifest.assets || [])
-    .flatMap((pattern) => glob(dir, pattern))
-    .map((file) => {
-      fs.copyFileSync(file, path.join(out, path.basename(file)));
-      return path.basename(file);
-    })
-    // the font files next/font/google downloaded, already in dist
-    .concat(fonts.flatMap((font) => font.files));
-  if (manifest.messages) {
-    files.messages = `${prefix}.labels.json`;
-    fs.copyFileSync(path.join(dir, manifest.messages), path.join(out, files.messages));
-  }
-  if (manifest.pages) {
-    files.pages = Object.fromEntries(
-      Object.entries(manifest.pages).map(([route, file], index) => {
-        const target = `${prefix}.page${index}.json`;
-        fs.copyFileSync(path.join(dir, file), path.join(out, target));
-        return [route, target];
-      })
-    );
-  }
-  const { build: _build, styles: _styles, assets: _assets, dedupeStyles: _dedupe, ...rest } = manifest;
-  fs.writeFileSync(path.join(out, MANIFEST), JSON.stringify({ ...rest, files }, null, 2) + "\n");
-  console.log(`built ${manifest.kind} ${manifest.name}@${manifest.version}: ${fs.readdirSync(out).length} files`);
-  return { manifest, out };
-}
-
-function pack(target) {
-  const { manifest, out } = build(target);
-  const { dir } = resolvePackage(target);
-  const zip = new AdmZip();
-  for (const name of fs.readdirSync(out)) zip.addLocalFile(path.join(out, name));
-  fs.mkdirSync(path.join(dir, "releases"), { recursive: true });
-  const file = path.join(dir, "releases", `${manifest.name}-${manifest.version}.zpkg.zip`);
-  zip.writeZip(file);
-  console.log(`packed ${path.basename(file)} (${fs.statSync(file).size} bytes)`);
-}
-
-// ---- install: validate, copy into the plugin directory, upsert the registry entry -------------------------------
-// Installs into one folder can run at the same time (several pipelines, an admin upload): each takes the folder's lock
-// (an atomic mkdir) for the read-change-write of plugins.json, writes it atomically (a temp file renamed over it, so the
-// running webstore never reads half a file) and keeps the previous registry in .history/ (the last HISTORY_KEEP).
-const LOCK_WAIT_MS = 60000;
-const LOCK_STALE_MS = 120000;
-const HISTORY_KEEP = 50;
-const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-
-function lockRegistry(storeDir) {
-  fs.mkdirSync(storeDir, { recursive: true });
-  const lock = path.join(storeDir, ".plugins.lock");
-  const deadline = Date.now() + LOCK_WAIT_MS;
-  for (;;) {
-    try {
-      fs.mkdirSync(lock);
-      break;
-    } catch (error) {
-      if (error.code !== "EEXIST") throw error;
-      // a lock left by a crashed install
-      try {
-        if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) fs.rmSync(lock, { recursive: true, force: true });
-      } catch {
-        // removed meanwhile
-      }
-      if (Date.now() > deadline) fail(`the registry in ${storeDir} is locked by another install (remove ${lock} if none is running)`);
-      sleep(25 + Math.floor(Math.random() * 50));
-    }
-  }
-  const release = () => fs.rmSync(lock, { recursive: true, force: true });
-  process.on("exit", release);
-  return () => {
-    release();
-    process.off("exit", release);
-  };
-}
-
-function writeRegistry(registryFile, registry) {
-  const dir = path.dirname(registryFile);
-  if (fs.existsSync(registryFile)) {
-    const history = path.join(dir, ".history");
-    fs.mkdirSync(history, { recursive: true });
-    fs.copyFileSync(registryFile, path.join(history, `plugins-${new Date().toISOString().replace(/[:.]/g, "-")}-${process.pid}.json`));
-    const old = fs
-      .readdirSync(history)
-      .filter((name) => name.startsWith("plugins-"))
-      .sort();
-    for (const name of old.slice(0, Math.max(0, old.length - HISTORY_KEEP))) fs.rmSync(path.join(history, name), { force: true });
-  }
-  const temp = `${registryFile}.tmp-${process.pid}`;
-  fs.writeFileSync(temp, JSON.stringify(registry, null, 2) + "\n");
-  fs.renameSync(temp, registryFile);
-}
-const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
-
-// the store's settings over the package defaults; an object setting (labels, panels) keeps the store's values and
-// gains the keys a new version adds
-function mergeSettings(defaults, previous) {
-  const merged = { ...defaults, ...previous };
-  for (const [key, value] of Object.entries(defaults)) {
-    if (isPlainObject(value) && isPlainObject(previous[key])) merged[key] = { ...value, ...previous[key] };
-  }
-  return merged;
-}
-
-function install(source, storeDir) {
-  let entries;
-  if (fs.statSync(source).isDirectory()) {
-    // a package folder's build output (dist; package in packages built before the dist folder)
-    const built = ["dist", "package"].map((name) => path.join(source, name)).find((dir) => fs.existsSync(path.join(dir, MANIFEST)));
-    const dir = built || source;
-    entries = fs.readdirSync(dir).map((name) => ({ name, data: fs.readFileSync(path.join(dir, name)) }));
-  } else {
-    entries = new AdmZip(source)
-      .getEntries()
-      .filter((entry) => !entry.isDirectory)
-      .map((entry) => ({ name: entry.entryName, data: entry.getData() }));
-  }
-  const manifestEntry = entries.find((entry) => entry.name === "znode-package.json");
-  if (!manifestEntry) fail("no znode-package.json in the package");
-  const manifest = JSON.parse(manifestEntry.data.toString("utf8"));
-  validateManifest(manifest, "package");
-
-  const total = entries.reduce((sum, entry) => sum + entry.data.length, 0);
-  if (total > MAX_BYTES) fail(`package is ${total} bytes; the limit is ${MAX_BYTES}`);
-  const files = entries.filter((entry) => entry.name !== "znode-package.json");
-  for (const entry of files) {
-    if (entry.name !== path.basename(entry.name)) fail(`"${entry.name}": a package is flat, no folders`);
-    if (!SERVED.has(path.extname(entry.name).toLowerCase())) fail(`"${entry.name}": file type not allowed`);
-  }
-  const has = (name) => files.some((entry) => entry.name === name);
-  const referenced = [
-    manifest.files?.server,
-    manifest.files?.browser,
-    manifest.files?.messages,
-    ...(manifest.files?.styles || []),
-    ...Object.values(manifest.files?.pages || {}),
-  ].filter(Boolean);
-  for (const name of referenced) if (!has(name)) fail(`znode-package.json names "${name}", which isn't in the package`);
-
-  const registryFile = path.join(storeDir, "plugins.json");
-  const unlock = lockRegistry(storeDir);
-  const registry = fs.existsSync(registryFile) ? readJson(registryFile) : { plugins: [] };
-  // a package never replaces a file another installed package uses
-  const owners = new Map();
-  for (const item of registry.plugins) {
-    if (item.name === manifest.name) continue;
-    for (const name of [item.file, item.browser, item.messages, ...(item.styles || []), ...Object.values(item.pages || {})]) if (name) owners.set(name, item.name);
-  }
-  for (const entry of files) if (owners.has(entry.name)) fail(`"${entry.name}" belongs to package ${owners.get(entry.name)}`);
-
-  fs.mkdirSync(storeDir, { recursive: true });
-  for (const entry of files) fs.writeFileSync(path.join(storeDir, entry.name), entry.data);
-
-  const previous = registry.plugins.find((item) => item.name === manifest.name);
-  const defaults = Object.fromEntries(
-    Object.entries(manifest.settingsSchema || {})
-      .filter(([, field]) => field.default !== undefined)
-      .map(([key, field]) => [key, field.default])
-  );
-  const entry = {
-    name: manifest.name,
-    kind: manifest.kind === "widget" ? "plugin" : manifest.kind,
-    version: manifest.version,
-    label: manifest.label,
-    publisher: manifest.publisher,
-    ...(manifest.parent ? { parent: manifest.parent } : {}),
-    ...(manifest.files?.server ? { file: manifest.files.server } : {}),
-    ...(manifest.files?.browser ? { browser: manifest.files.browser } : {}),
-    ...(manifest.files?.styles?.length ? { styles: manifest.files.styles } : {}),
-    ...(manifest.files?.messages ? { messages: manifest.files.messages } : {}),
-    ...(manifest.files?.pages ? { pages: manifest.files.pages } : {}),
-    ...(manifest.widgets?.length ? { widgets: manifest.widgets } : {}),
-    ...(manifest.overrides ? { overrides: manifest.overrides } : {}),
-    ...(manifest.serverPages?.length ? { serverPages: manifest.serverPages } : {}),
-    ...(manifest.sandbox === true ? { sandbox: true } : {}),
-    // the webstore accepts files (multipart) only for a package that declares them
-    ...((manifest.permissions || []).includes("uploads") ? { uploads: true } : {}),
-    ...(manifest.settingsSchema ? { settingsSchema: manifest.settingsSchema } : {}),
-    // where it runs and its settings are the store owner's: an upgrade keeps them; a new package starts switched off
-    enabled: previous ? previous.enabled : false,
-    stores: previous ? previous.stores : [],
-    settings: mergeSettings(defaults, previous?.settings || {}),
-  };
-  if (previous) registry.plugins[registry.plugins.indexOf(previous)] = entry;
-  else registry.plugins.push(entry);
-  writeRegistry(registryFile, registry);
-  // the replaced version's files (an upgrade's old bundles and stylesheets) leave the plugin directory
-  const kept = new Set(files.map((file) => file.name));
-  for (const name of [previous?.file, previous?.browser, previous?.messages, ...(previous?.styles || []), ...Object.values(previous?.pages || {})]) {
-    if (name && !kept.has(name) && name === path.basename(name)) fs.rmSync(path.join(storeDir, name), { force: true });
-  }
-
-  unlock();
-
-  const missing = Object.entries(manifest.settingsSchema || {}).filter(([key, field]) => field.required && (entry.settings[key] === undefined || entry.settings[key] === ""));
-  console.log(
-    `installed ${manifest.kind} ${manifest.name}@${manifest.version}${previous ? ` (was ${previous.version || "unversioned"})` : ""}: ${files.length} files, ${entry.enabled ? "enabled" : "disabled"} for ${JSON.stringify(entry.stores)}`
-  );
-  if (missing.length) console.log(`  settings to fill in before enabling: ${missing.map(([key]) => key).join(", ")}`);
-}
-
-// ---- create: a starter package of a kind (templates.mjs), with the API typings next to its sources ---------------
-function create(kind, name, dir) {
-  if (!TEMPLATES[kind]) fail(`kind must be one of ${Object.keys(TEMPLATES).join(", ")}`);
-  if (!NAME.test(name || "")) fail("name must be lowercase letters, digits and dashes (2 to 49)");
-  const target = path.resolve(dir || path.join(process.cwd(), name));
-  if (fs.existsSync(target) && fs.readdirSync(target).length) fail(`${target} exists and is not empty`);
-  for (const [file, content] of Object.entries(TEMPLATES[kind](name))) {
-    const full = path.join(target, file);
-    fs.mkdirSync(path.dirname(full), { recursive: true });
-    fs.writeFileSync(full, typeof content === "string" ? content : JSON.stringify(content, null, 2) + "\n");
-  }
-  if (kind !== "content") fs.copyFileSync(path.join(HERE, "..", "types", "extension-api.d.ts"), path.join(target, "src", "extension-api.d.ts"));
-  console.log(`created ${kind} ${name} in ${target}`);
-  console.log("  next: fill in label, publisher and description in znode-package.json, then run its build-and-upload.sh");
-}
-
-// ---- check: what a marketplace review looks at, from the package's own files ------------------------------------
-const HOOK_NAMES = ["onCartChanged", "beforeAddToCart", "afterAddToCart", "mapCartItems"];
-
-// the code an entry pulls in: the entry and the files it imports by relative path, followed (a package's server and
-// browser parts share a folder, so a folder read would mix them); type-only imports are skipped
-function sourceOf(dir, entry) {
-  if (!entry) return "";
-  const seen = new Set();
-  const sources = [];
-  const visit = (file) => {
-    if (seen.has(file) || !fs.existsSync(file)) return;
-    seen.add(file);
-    const code = fs.readFileSync(file, "utf8");
-    sources.push(code);
-    for (const [, typeOnly, spec] of code.matchAll(/\bimport\s+(type\s+)?[^;]*?from\s+["'](\.[^"']+)["']/g)) {
-      if (typeOnly) continue;
-      const base = path.resolve(path.dirname(file), spec).replace(/\.(m?js)$/, "");
-      const found = [".ts", ".tsx", ".js", ".mjs", "/index.ts", "/index.tsx"].map((ext) => base + ext).find((candidate) => fs.existsSync(candidate));
-      if (found) visit(found);
-    }
-  };
-  visit(path.join(dir, entry));
-  return sources.join("\n");
-}
-
-// the server renders a browser bundle in this format from one compiled copy for all stores
-// (packages/extensions/src/server-instances.ts); any other is imported once per store, and Node keeps every copy
-function serverRenderFormat(code) {
-  const match = /\bexport\s*(?:\{\s*([A-Za-z_$][\w$]*)\s+as\s+default\s*,?\s*\}|default\s+([A-Za-z_$][\w$]*))\s*;?\s*(?:\/\/#\s*sourceMappingURL=\S*\s*)?$/.exec(code);
-  if (!match || /(^|[^\w$.])import\s*\(/.test(code.slice(0, match.index))) return false;
-  try {
-    new vm.Script(`(function () {\n"use strict";\n${code.slice(0, match.index)}\nreturn ${match[1] || match[2]};\n})`);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function check(target) {
-  const { dir, manifestFile } = resolvePackage(target);
-  const manifest = readJson(manifestFile);
-  validateManifest(manifest, path.basename(manifestFile));
-  const errors = [];
-  const warnings = [];
-
-  // the listing
-  for (const key of ["label", "publisher", "description"]) if (!String(manifest[key] || "").trim()) errors.push(`"${key}" is missing (the marketplace shows it)`);
-  if (/describe what it does/i.test(manifest.description || "") || manifest.publisher === "Your company") errors.push("the starter's publisher or description is still in place");
-  else if (String(manifest.description || "").length < 30) warnings.push('"description" is short: say what it does for the store');
-  for (const key of ["license", "compatibility"]) if (!manifest[key]) warnings.push(`"${key}" is missing`);
-
-  // permissions against the code
-  const server = sourceOf(dir, manifest.build?.server);
-  const browser = sourceOf(dir, manifest.build?.browser);
-  const used = new Set();
-  if (/\broutes\s*[:=,}]/.test(server)) used.add("routes");
-  if (HOOK_NAMES.some((hook) => new RegExp(`\\b${hook}\\b`).test(server))) used.add("cartHooks");
-  if (Object.keys(manifest.overrides || {}).length) used.add("overrides");
-  if (/\bznode\s*\(/.test(server)) used.add("znodeApi");
-  if (/\bfetch\s*\(|\bhttps?\.request\s*\(/.test(server)) used.add("externalNetwork");
-  if (/\.files\b/.test(server)) used.add("uploads");
-  const declared = new Set(manifest.permissions || []);
-  for (const item of used) if (!declared.has(item)) errors.push(`uses "${item}" without declaring it in "permissions"`);
-  for (const item of declared) if (!used.has(item)) warnings.push(`declares "${item}" but no code uses it (the review asks why)`);
-  if (/\beval\s*\(|new Function\s*\(/.test(server + browser)) errors.push("uses eval or new Function");
-  if (/document\.cookie/.test(browser)) warnings.push("reads cookies in the browser: keep secrets on the server (routes)");
-
-  // settings
-  for (const [key, field] of Object.entries(manifest.settingsSchema || {})) {
-    if (!field.label) warnings.push(`setting "${key}" has no label (the admin shows it)`);
-    if (field.required && field.default !== undefined) warnings.push(`setting "${key}" is required but has a default`);
-    if (field.browser && /secret|password|token|api_?key/i.test(key)) errors.push(`setting "${key}" looks secret but is sent to the browser ("browser": true)`);
-  }
-  if (manifest.kind === "theme" && !Object.values(manifest.settingsSchema || {}).some((field) => field.attribute)) {
-    warnings.push("no setting is bound to a Znode attribute: per-store branding then needs a registry change per store");
-  }
-
-  // the built files (pack first)
-  const out = path.join(dir, "dist");
-  if (fs.existsSync(out)) {
-    let total = 0;
-    for (const name of fs.readdirSync(out)) {
-      const size = fs.statSync(path.join(out, name)).size;
-      total += size;
-      if (name.endsWith(".browser.mjs")) {
-        if (size > 512 * 1024) warnings.push(`${name} is ${Math.round(size / 1024)} KB: every page of the store loads it`);
-        if (!serverRenderFormat(fs.readFileSync(path.join(out, name), "utf8")))
-          warnings.push(`${name} is not in the server-render format (no imports, one default export): the server keeps a copy per store`);
-      }
-      if (name.endsWith(".css") && size > 200 * 1024) warnings.push(`${name} is ${Math.round(size / 1024)} KB`);
-    }
-    if (total > MAX_BYTES) errors.push(`dist is ${Math.round(total / 1048576)} MB (limit 10 MB)`);
-  } else warnings.push("not built yet: pack it to check sizes and the server-render format");
-
-  for (const item of errors) console.log(`error   ${item}`);
-  for (const item of warnings) console.log(`warning ${item}`);
-  console.log(`check ${manifest.name}@${manifest.version}: ${errors.length} errors, ${warnings.length} warnings`);
-  if (errors.length) process.exit(1);
-}
-
-// ---- project commands: deploy, dev, link-store ------------------------------------------------------------------
-
-const needStore = (storeDir) =>
-  storeDir || fail("needs the store's plugin folder: pass it after the package, or set RUNTIME_PLUGINS_DIR");
-
-// pack, then install the zip it made into the store's plugin folder
-function deploy(target, storeDir) {
-  pack(target);
-  const { dir, manifestFile } = resolvePackage(target);
-  const manifest = readJson(manifestFile);
-  install(path.join(dir, "releases", `${manifest.name}-${manifest.version}.zpkg.zip`), storeDir);
-}
-
-// deploy now, then again whenever the package's sources or manifest change; the store picks a new file up on the next
-// request (it reloads a package when its files change), so a page refresh shows the change
-function dev(target, storeDir) {
-  const { dir } = resolvePackage(target);
-  const self = fileURLToPath(import.meta.url);
-  const run = () => spawnSync(process.execPath, [self, "deploy", dir, storeDir], { stdio: "inherit" });
-  run();
-  let timer = null;
-  const changed = (file) => {
-    if (!file || /(^|[\\/])(dist|releases|\.build|node_modules)([\\/]|$)/.test(String(file))) return;
-    clearTimeout(timer);
-    timer = setTimeout(() => {
-      console.log(`znode dev: ${file} changed, deploying`);
-      run();
-    }, 300);
-  };
-  fs.watch(path.join(dir, "src"), { recursive: true }, (_event, file) => changed(file && path.join("src", file)));
-  fs.watch(dir, (_event, file) => file === MANIFEST && changed(file));
-  console.log(`znode dev: watching ${dir} (Ctrl+C to stop)`);
-}
-
-// the store's real types for the editor and the build check: tsconfig.store.json (git-ignored, per machine) is this
-// package's preset plus the store repo's aliases (every @znode path of its tsconfig.base.json, from the store's folder).
-// Only the aliases are taken: the store's own options (its rootDir among them) would refuse a project kept elsewhere.
-function linkStore(storeRepo, project = ".") {
-  const base = path.resolve(storeRepo, "tsconfig.base.json");
-  if (!fs.existsSync(base)) fail(`${base} not found: pass the store repo's folder (the one with tsconfig.base.json)`);
-  const ts = require("typescript");
-  const { config, error } = ts.readConfigFile(base, ts.sys.readFile);
-  if (error) fail(`${base}: ${ts.flattenDiagnosticMessageText(error.messageText, "\n")}`);
-  const options = config.compilerOptions || {};
-  const toSlash = (value) => value.split(path.sep).join("/");
-  const file = path.resolve(project, "tsconfig.store.json");
-  const linked = {
-    extends: "znode-plugin/tsconfig.json",
-    compilerOptions: { baseUrl: toSlash(path.resolve(path.dirname(base), options.baseUrl || ".")), paths: options.paths || {} },
-  };
-  fs.writeFileSync(file, JSON.stringify(linked, null, 2) + "\n");
-  console.log(`linked ${file} to ${base} (${Object.keys(linked.compilerOptions.paths).length} store aliases)`);
-}
-
-const args = process.argv.slice(2);
-// the store's plugin folder: the argument, else RUNTIME_PLUGINS_DIR, else the project's git-ignored znode.local.json
-// ({ "pluginsDir": "…" }, written by create-znode-plugin --plugins-dir) in the folder the command runs in
-function localPluginsDir() {
-  try {
-    return JSON.parse(fs.readFileSync(path.resolve("znode.local.json"), "utf8")).pluginsDir || undefined;
-  } catch {
-    return undefined;
-  }
-}
-const [command, target, storeDir = process.env.RUNTIME_PLUGINS_DIR || localPluginsDir()] = args;
-if (command === "create") {
-  create(args[1], args[2], args[3]);
-  process.exit(0);
-}
-if (command === "link-store") {
-  if (!target) fail("usage: znode link-store <storeRepoDir> [projectDir]");
-  linkStore(target, args[2]);
-  process.exit(0);
-}
-if (!target) fail("usage: znode <build|pack|check|install|deploy|dev> <dir|zip> [storeDir], znode create <kind> <name> [dir], znode link-store <storeRepoDir>");
-if (command === "check") check(path.resolve(target));
-else if (command === "build") build(path.resolve(target));
-else if (command === "pack") pack(path.resolve(target));
-else if (command === "install") install(path.resolve(target), path.resolve(needStore(storeDir)));
-else if (command === "deploy") deploy(path.resolve(target), path.resolve(needStore(storeDir)));
-else if (command === "dev") dev(path.resolve(target), path.resolve(needStore(storeDir)));
-else fail(`unknown command "${command}"`);
+#!/usr/bin/env node
+// znode-plugin: build, pack and install Znode runtime packages (themes, plugins, widgets, content).
+//
+//   znode build   <packageDir|manifest.json>    build into <packageDir>/dist
+//   znode pack    <packageDir|manifest.json>    build, then zip it as
+//                                                                    <packageDir>/releases/<name>-<version>.zpkg.zip
+//   znode install <zip|packageDir> [storeDir]   validate and install into the store's plugin
+//                                                                    directory (default: RUNTIME_PLUGINS_DIR);
+//                                                                    the registry entry keeps its settings and stores
+//   znode create  <theme|plugin|widget|content> <name> [dir]
+//                                                                    a starter package that builds as it is
+//                                                                    (default dir ./<name>)
+//   znode check   <packageDir>                  marketplace review: metadata, permissions against
+//                                                                    the code, settings, size, server-render format
+//   znode deploy  <packageDir> [storeDir]       pack, then install into the store's plugin directory
+//   znode dev     <packageDir> [storeDir]       deploy, then again on every change under src/ or to the manifest
+//   znode link-store <storeRepoDir> [dir]       the store's real types: writes tsconfig.store.json (see README)
+//   znode eject   [<Name>] [--force]            in a package folder: list the store components that can be ejected, or
+//                                                copy one into src/components/ and register it in its slot
+//
+// A package is a folder with znode-package.json (README.md shows a whole project, as create-znode-plugin makes it):
+// {
+//   "name": "artifi", "version": "1.0.0", "kind": "plugin" | "theme" | "widget" | "content", "apiVersion": 1,
+//   "label": "...", "publisher": "...", "description": "...", "parent": "<theme>",          (parent: themes only)
+//   "build": { "server": "src/server.ts", "browser": "src/browser.tsx" },                  (TypeScript entry points)
+//   "styles": ["src/styles/*.css"], "assets": ["src/assets/fonts/*.woff2"], "messages": "src/i18n/labels.json",
+//   "pages": { "/": "src/pages/home.json" }, "widgets": ["HeroBanner"],
+//   code imports Next.js as an app does: next/image, next/link, next/navigation, next/font/google, react
+//   (next-imports.mjs: the store's own modules at runtime; Google fonts downloaded into the package when it builds)
+//   "overrides": { "/api/place-order": "place-order" },   (store BFF routes it takes over, by one of its routes)
+//   "serverPages": ["/my-page"],   (whole pages at new URLs, rendered by its server part's serverPages)
+//   "dedupeStyles": true,      (styles: drop the rules the store already has; STORE_URL = a page of a running store)
+//   "settingsSchema": { "websiteId": { "type": "string", "required": true, "browser": true, "label": "..." },
+//                       "banner": { "type": "string", "browser": true, "attribute": "StoreBannerText" } },
+//                       (attribute: the value comes from a Znode global attribute, "Code" for the store's, or
+//                        { "code": "...", "levels": ["store", "account", "user"] }; the most specific level wins)
+//   marketplace: "license", "keywords", "homepage", "compatibility": { "webstore": ">=10.0.0" },
+//   "permissions": ["routes", "cartHooks", "overrides", "znodeApi", "externalNetwork", "uploads"]   (what it does beyond UI;
+//                  "uploads": its routes take files, multipart/form-data up to RUNTIME_PLUGIN_UPLOAD_BYTES)
+//   "sandbox": true   (its server part runs in a separate, permission-limited Node process: routes and overrides only)
+// }
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import vm from "node:vm";
+import { TEMPLATES } from "./templates.mjs";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const MANIFEST = "znode-package.json";
+// the build tools (TypeScript, rollup, adm-zip, postcss): this package's own dependencies, wherever npm put them
+// (ZNODE_TOOLS: a node_modules folder to use instead)
+const require = process.env.ZNODE_TOOLS ? createRequire(path.join(process.env.ZNODE_TOOLS, "noop.js")) : createRequire(import.meta.url);
+// a dependency's folder (its package.json's), found from what it resolves to
+function packageDir(name) {
+  for (let dir = path.dirname(require.resolve(name)); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+    const file = path.join(dir, "package.json");
+    if (fs.existsSync(file) && JSON.parse(fs.readFileSync(file, "utf8")).name === name) return dir;
+  }
+  throw new Error(`znode-plugin: ${name} is not installed`);
+}
+const TSC = () => path.join(packageDir("typescript"), "bin", "tsc");
+const ROLLUP = () => path.join(packageDir("rollup"), "dist", "bin", "rollup");
+const AdmZip = require("adm-zip");
+
+const API_VERSION = 1;
+const KINDS = ["theme", "plugin", "widget", "content"];
+const NAME = /^[a-z0-9][a-z0-9-]{1,48}$/;
+const VERSION = /^\d+\.\d+\.\d+(-[0-9a-z.-]+)?$/i;
+const SERVED = new Set([".mjs", ".map", ".css", ".woff2", ".woff", ".ttf", ".otf", ".svg", ".png", ".jpg", ".jpeg", ".webp", ".gif", ".json"]);
+const MAX_BYTES = 10 * 1024 * 1024;
+const SETTING_TYPES = ["string", "number", "boolean", "list", "json", "object", "array"];
+const ATTRIBUTE_LEVELS = ["store", "account", "user"];
+const ATTRIBUTE_CODE = /^[A-Za-z][A-Za-z0-9_]{1,99}$/;
+const PERMISSIONS = ["routes", "cartHooks", "overrides", "znodeApi", "externalNetwork", "uploads"];
+
+const fail = (message) => {
+  console.error(`znode-package: ${message}`);
+  process.exit(1);
+};
+const readJson = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+const glob = (dir, pattern) => {
+  const folder = path.join(dir, path.dirname(pattern));
+  const re = new RegExp(
+    `^${path
+      .basename(pattern)
+      .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+      .replace(/\*/g, ".*")}$`
+  );
+  return fs.existsSync(folder)
+    ? fs
+        .readdirSync(folder)
+        .filter((name) => re.test(name))
+        .map((name) => path.join(folder, name))
+    : [];
+};
+
+function validateManifest(manifest, where) {
+  if (!NAME.test(manifest.name || "")) fail(`${where}: name must be lowercase letters, digits and dashes`);
+  if (!VERSION.test(manifest.version || "")) fail(`${where}: version must be semver (1.2.3)`);
+  if (!KINDS.includes(manifest.kind)) fail(`${where}: kind must be one of ${KINDS.join(", ")}`);
+  if (manifest.apiVersion !== API_VERSION) fail(`${where}: apiVersion ${manifest.apiVersion} isn't supported (this store runs ${API_VERSION})`);
+  if (manifest.parent && manifest.kind !== "theme") fail(`${where}: only a theme has a parent`);
+  // whole pages its server part renders (IRuntimePlugin.serverPages), at new lowercase URLs the store doesn't use
+  if (manifest.serverPages !== undefined) {
+    if (!Array.isArray(manifest.serverPages)) fail(`${where}: serverPages must be a list of paths ("/my-page")`);
+    // the source manifest names the entry (build.server), the built one the file (files.server)
+    if (manifest.serverPages.length && !manifest.build?.server && !manifest.files?.server) fail(`${where}: serverPages need a server part (build.server)`);
+    for (const page of manifest.serverPages) {
+      if (!/^\/[a-z0-9][a-z0-9-]*(\/[a-z0-9][a-z0-9-]*)*$/.test(String(page))) fail(`${where}: serverPages "${page}" must be a lowercase path like /my-page`);
+      if (/^\/(api|runtime-page|_next|login|signup|account|cart|checkout|search|product|category|404|error|maintenance)(\/|$)/.test(page)) fail(`${where}: serverPages "${page}" is a store route`);
+    }
+  }
+  // store BFF routes the package takes over: "/api/<path>" -> one of its own routes
+  for (const [route, target] of Object.entries(manifest.overrides || {})) {
+    if (!/^\/api\/[A-Za-z0-9/_-]+$/.test(route) || /^\/api\/extensions(\/|$)/.test(route)) fail(`${where}: override "${route}" must be a store route under /api/`);
+    if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(String(target))) fail(`${where}: override "${route}" must name one of the package's routes`);
+  }
+  for (const [key, field] of Object.entries(manifest.settingsSchema || {})) {
+    if (field?.type !== undefined && !SETTING_TYPES.includes(field.type)) fail(`${where}: setting "${key}" has type "${field.type}" (one of ${SETTING_TYPES.join(", ")})`);
+    const attribute = field?.attribute;
+    if (attribute === undefined) continue;
+    const code = typeof attribute === "string" ? attribute : attribute?.code;
+    if (!ATTRIBUTE_CODE.test(String(code || ""))) fail(`${where}: setting "${key}" names attribute "${code}" (letters, digits and _, as Znode attribute codes)`);
+    const levels = typeof attribute === "string" ? ["store"] : attribute.levels || ["store"];
+    if (!Array.isArray(levels) || !levels.length || levels.some((level) => !ATTRIBUTE_LEVELS.includes(level))) {
+      fail(`${where}: setting "${key}" attribute levels must be some of ${ATTRIBUTE_LEVELS.join(", ")}`);
+    }
+  }
+  if (manifest.sandbox !== undefined && typeof manifest.sandbox !== "boolean") fail(`${where}: sandbox must be true or false`);
+  if (manifest.permissions !== undefined && (!Array.isArray(manifest.permissions) || manifest.permissions.some((item) => !PERMISSIONS.includes(item)))) {
+    fail(`${where}: permissions must be some of ${PERMISSIONS.join(", ")}`);
+  }
+}
+
+// ---- build: TypeScript entry points -> one ES module each (tsc + rollup), plus styles, assets, labels, pages ----
+// a package folder (its znode-package.json) or one of several manifests in a folder (<name>.znode-package.json)
+function resolvePackage(target) {
+  const isFile = fs.statSync(target).isFile();
+  const dir = isFile ? path.dirname(target) : target;
+  const manifestFile = isFile ? target : path.join(dir, MANIFEST);
+  return { dir, manifestFile, outName: path.basename(manifestFile) === MANIFEST ? "dist" : `dist-${path.basename(manifestFile, `.${MANIFEST}`)}` };
+}
+
+// The package's tsconfig check. tsc also checks the store files the package imports; their errors are the store's, not
+// the package's: listed as warnings. An error in the package's own files stops the build.
+function typeCheck(dir, tsconfigFile) {
+  let output = "";
+  try {
+    execFileSync(process.execPath, [TSC(), "-p", tsconfigFile, "--noEmit", "--pretty", "false"], {
+      cwd: dir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return;
+  } catch (error) {
+    output = `${error.stdout || ""}${error.stderr || ""}`;
+  }
+  // one entry per error: "file(line,col): error TSnnnn: message" and its indented continuation lines
+  const errors = output.split(/\r?\n(?=\S)/).filter((entry) => /^.+?\(\d+,\d+\): error TS\d+:/.test(entry));
+  if (!errors.length) fail(`tsconfig check failed:\n${output}`);
+  // inside the package folder: a relative path that does not climb out (on Windows a file on another drive comes back
+  // absolute from path.relative, which is outside too)
+  const inPackage = (entry) => {
+    const relative = path.relative(dir, path.resolve(dir, entry.slice(0, entry.indexOf("("))));
+    return !relative.startsWith("..") && !path.isAbsolute(relative);
+  };
+  const own = errors.filter(inPackage);
+  const store = errors.filter((entry) => !inPackage(entry));
+  if (store.length) console.log(`warning ${store.length} type error(s) in store files the package imports (the store's to fix):\n  ${store.join("\n  ")}`);
+  if (own.length) fail(`type errors in the package:\n  ${own.join("\n  ")}`);
+}
+
+// every .ts / .tsx under srcRoot compiled to .js under outRoot, one file at a time and without resolving imports (the
+// tsconfig check has done the types): types removed, JSX as Next.js compiles it (react/jsx-runtime)
+function transpileSources(srcRoot, outRoot) {
+  const ts = require("typescript");
+  const walk = (folder) =>
+    fs.readdirSync(folder, { withFileTypes: true }).flatMap((item) => {
+      const file = path.join(folder, item.name);
+      if (item.isDirectory()) return walk(file);
+      return /\.tsx?$/.test(item.name) && !item.name.endsWith(".d.ts") ? [file] : [];
+    });
+  for (const file of walk(srcRoot)) {
+    const { outputText } = ts.transpileModule(fs.readFileSync(file, "utf8"), {
+      fileName: file,
+      compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ES2022, jsx: ts.JsxEmit.ReactJSX, jsxImportSource: "react" },
+    });
+    const target = path.join(outRoot, path.relative(srcRoot, file)).replace(/\.tsx?$/, ".js");
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, outputText);
+  }
+}
+
+// The store the package is linked to (tsconfig.store.json, written by link-store): its root, its @znode paths and its
+// Generated Store Module Registry (packages/extensions/store-module-registry.json), for the package's store imports
+function linkedStore(dir) {
+  const file = path.join(dir, "tsconfig.store.json");
+  if (!fs.existsSync(file)) return null;
+  const { compilerOptions = {} } = readJson(file);
+  if (!compilerOptions.baseUrl) return null;
+  const root = path.resolve(dir, compilerOptions.baseUrl);
+  const registryFile = path.join(root, "packages/extensions/store-module-registry.json");
+  const registry = fs.existsSync(registryFile) ? readJson(registryFile).modules : null;
+  return { root, paths: compilerOptions.paths || {}, registry };
+}
+
+function build(target) {
+  const { dir, manifestFile, outName } = resolvePackage(target);
+  const manifest = readJson(manifestFile);
+  validateManifest(manifest, path.basename(manifestFile));
+  const out = path.join(dir, outName);
+  fs.rmSync(out, { recursive: true, force: true });
+  fs.mkdirSync(out, { recursive: true });
+  const tmp = path.join(dir, ".build");
+  const files = {};
+  const prefix = `${manifest.name}-${manifest.version}`;
+  // next/font/google fonts built into the package (next-imports.mjs): their files and @font-face CSS
+  const fonts = [];
+  // the store modules its browser part imports (Generated Store Module Registry keys), for the store to load first
+  const storeImports = [];
+  const store = linkedStore(dir);
+  // A package with its own tsconfig.json (extending the store's tsconfig.base.json) is checked against the store's real
+  // types (every @znode alias, no declarations to write), then compiled file by file without type information, JSX as
+  // Next.js does (react/jsx-runtime: the store's). Without one, the package compiles as before (tsc, JSX factory h).
+  const tsconfigFile = path.join(dir, "tsconfig.json");
+  const projectMode = fs.existsSync(tsconfigFile);
+  if (projectMode && Object.values(manifest.build || {}).length) typeCheck(dir, tsconfigFile);
+
+  for (const part of ["server", "browser"]) {
+    const entry = manifest.build?.[part];
+    if (!entry) continue;
+    fs.rmSync(tmp, { recursive: true, force: true });
+    if (projectMode) transpileSources(path.dirname(path.join(dir, entry)), tmp);
+    else execFileSync(
+      process.execPath,
+      [
+        TSC(),
+        "--target",
+        "es2022",
+        "--module",
+        "es2022",
+        "--moduleResolution",
+        "bundler",
+        "--lib",
+        "es2022,dom",
+        "--skipLibCheck",
+        // import React from "react", as the store's own components do
+        "--allowSyntheticDefaultImports",
+        "--jsx",
+        "react",
+        "--jsxFactory",
+        "h",
+        "--jsxFragmentFactory",
+        "Fragment",
+        "--outDir",
+        tmp,
+        path.join(dir, entry),
+      ],
+      { stdio: "inherit" }
+    );
+    const compiled = path.join(tmp, path.basename(entry).replace(/\.tsx?$/, ".js"));
+    const target = `${prefix}.${part}.mjs`;
+    // rollup with the Next.js imports plugin (next-imports.mjs), from a config file: the plugin downloads fonts, which
+    // is async, in rollup's own process; what it built comes back in fonts.json
+    const config = path.join(tmp, "rollup.config.mjs");
+    const fontsFile = path.join(tmp, "fonts.json");
+    const storeImportsFile = path.join(tmp, "store-imports.json");
+    fs.writeFileSync(
+      config,
+      [
+        `import fs from "node:fs";`,
+        `import { znodeNext } from ${JSON.stringify(pathToFileURL(path.join(HERE, "next-imports.mjs")).href)};`,
+        `const fonts = [];`,
+        `const storeImports = [];`,
+        `const store = ${JSON.stringify(store)};`,
+        `if (store?.registry) store.registry = new Set(store.registry);`,
+        `export default {`,
+        `  input: ${JSON.stringify(compiled)},`,
+        `  output: { file: ${JSON.stringify(path.join(out, target))}, format: "es", sourcemap: true },`,
+        `  plugins: [`,
+        `    znodeNext({ part: ${JSON.stringify(part)}, prefix: ${JSON.stringify(prefix)}, outDir: ${JSON.stringify(out)}, fonts, store, storeImports }),`,
+        `    { name: "fonts-out", writeBundle() { fs.writeFileSync(${JSON.stringify(fontsFile)}, JSON.stringify(fonts)); fs.writeFileSync(${JSON.stringify(storeImportsFile)}, JSON.stringify(storeImports)); } },`,
+        `  ],`,
+        `};`,
+      ].join("\n")
+    );
+    execFileSync(process.execPath, [ROLLUP(), "--config", config, "--silent"], { stdio: "inherit" });
+    if (fs.existsSync(fontsFile)) fonts.push(...JSON.parse(fs.readFileSync(fontsFile, "utf8")));
+    if (fs.existsSync(storeImportsFile)) storeImports.push(...JSON.parse(fs.readFileSync(storeImportsFile, "utf8")));
+    files[part] = target;
+  }
+  fs.rmSync(tmp, { recursive: true, force: true });
+
+  // styles: concatenated into one stylesheet, after the fonts next/font/google built; assets (fonts, images) keep their
+  // names, which the stylesheet refers to
+  if (manifest.styles?.length || fonts.length) {
+    const css = [
+      ...fonts.map((font) => font.css),
+      ...(manifest.styles || []).flatMap((pattern) => glob(dir, pattern)).map((file) => fs.readFileSync(file, "utf8")),
+    ].join("\n");
+    files.styles = [`${prefix}.css`];
+    fs.writeFileSync(path.join(out, files.styles[0]), css);
+    // rules the store's own stylesheets already have, loaded again later, would beat its responsive variants
+    if (manifest.dedupeStyles) {
+      const target = path.join(out, files.styles[0]);
+      execFileSync(process.execPath, [path.join(HERE, "css-dedupe.mjs"), target, process.env.STORE_URL || "http://staplespromo.localhost:3000/", target], { stdio: "inherit" });
+    }
+  }
+  files.assets = (manifest.assets || [])
+    .flatMap((pattern) => glob(dir, pattern))
+    .map((file) => {
+      fs.copyFileSync(file, path.join(out, path.basename(file)));
+      return path.basename(file);
+    })
+    // the font files next/font/google downloaded, already in dist
+    .concat(fonts.flatMap((font) => font.files));
+  if (manifest.messages) {
+    files.messages = `${prefix}.labels.json`;
+    fs.copyFileSync(path.join(dir, manifest.messages), path.join(out, files.messages));
+  }
+  if (manifest.pages) {
+    files.pages = Object.fromEntries(
+      Object.entries(manifest.pages).map(([route, file], index) => {
+        const target = `${prefix}.page${index}.json`;
+        fs.copyFileSync(path.join(dir, file), path.join(out, target));
+        return [route, target];
+      })
+    );
+  }
+  const { build: _build, styles: _styles, assets: _assets, dedupeStyles: _dedupe, ...rest } = manifest;
+  fs.writeFileSync(path.join(out, MANIFEST), JSON.stringify({ ...rest, files, ...(storeImports.length ? { storeImports: [...new Set(storeImports)].sort() } : {}) }, null, 2) + "\n");
+  console.log(`built ${manifest.kind} ${manifest.name}@${manifest.version}: ${fs.readdirSync(out).length} files`);
+  return { manifest, out };
+}
+
+function pack(target) {
+  const { manifest, out } = build(target);
+  const { dir } = resolvePackage(target);
+  const zip = new AdmZip();
+  for (const name of fs.readdirSync(out)) zip.addLocalFile(path.join(out, name));
+  fs.mkdirSync(path.join(dir, "releases"), { recursive: true });
+  const file = path.join(dir, "releases", `${manifest.name}-${manifest.version}.zpkg.zip`);
+  zip.writeZip(file);
+  console.log(`packed ${path.basename(file)} (${fs.statSync(file).size} bytes)`);
+}
+
+// ---- install: validate, copy into the plugin directory, upsert the registry entry -------------------------------
+// Installs into one folder can run at the same time (several pipelines, an admin upload): each takes the folder's lock
+// (an atomic mkdir) for the read-change-write of plugins.json, writes it atomically (a temp file renamed over it, so the
+// running webstore never reads half a file) and keeps the previous registry in .history/ (the last HISTORY_KEEP).
+const LOCK_WAIT_MS = 60000;
+const LOCK_STALE_MS = 120000;
+const HISTORY_KEEP = 50;
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+function lockRegistry(storeDir) {
+  fs.mkdirSync(storeDir, { recursive: true });
+  const lock = path.join(storeDir, ".plugins.lock");
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      fs.mkdirSync(lock);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      // a lock left by a crashed install
+      try {
+        if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) fs.rmSync(lock, { recursive: true, force: true });
+      } catch {
+        // removed meanwhile
+      }
+      if (Date.now() > deadline) fail(`the registry in ${storeDir} is locked by another install (remove ${lock} if none is running)`);
+      sleep(25 + Math.floor(Math.random() * 50));
+    }
+  }
+  const release = () => fs.rmSync(lock, { recursive: true, force: true });
+  process.on("exit", release);
+  return () => {
+    release();
+    process.off("exit", release);
+  };
+}
+
+function writeRegistry(registryFile, registry) {
+  const dir = path.dirname(registryFile);
+  if (fs.existsSync(registryFile)) {
+    const history = path.join(dir, ".history");
+    fs.mkdirSync(history, { recursive: true });
+    fs.copyFileSync(registryFile, path.join(history, `plugins-${new Date().toISOString().replace(/[:.]/g, "-")}-${process.pid}.json`));
+    const old = fs
+      .readdirSync(history)
+      .filter((name) => name.startsWith("plugins-"))
+      .sort();
+    for (const name of old.slice(0, Math.max(0, old.length - HISTORY_KEEP))) fs.rmSync(path.join(history, name), { force: true });
+  }
+  const temp = `${registryFile}.tmp-${process.pid}`;
+  fs.writeFileSync(temp, JSON.stringify(registry, null, 2) + "\n");
+  fs.renameSync(temp, registryFile);
+}
+const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+// the store's settings over the package defaults; an object setting (labels, panels) keeps the store's values and
+// gains the keys a new version adds
+function mergeSettings(defaults, previous) {
+  const merged = { ...defaults, ...previous };
+  for (const [key, value] of Object.entries(defaults)) {
+    if (isPlainObject(value) && isPlainObject(previous[key])) merged[key] = { ...value, ...previous[key] };
+  }
+  return merged;
+}
+
+function install(source, storeDir) {
+  let entries;
+  if (fs.statSync(source).isDirectory()) {
+    // a package folder's build output (dist; package in packages built before the dist folder)
+    const built = ["dist", "package"].map((name) => path.join(source, name)).find((dir) => fs.existsSync(path.join(dir, MANIFEST)));
+    const dir = built || source;
+    entries = fs.readdirSync(dir).map((name) => ({ name, data: fs.readFileSync(path.join(dir, name)) }));
+  } else {
+    entries = new AdmZip(source)
+      .getEntries()
+      .filter((entry) => !entry.isDirectory)
+      .map((entry) => ({ name: entry.entryName, data: entry.getData() }));
+  }
+  const manifestEntry = entries.find((entry) => entry.name === "znode-package.json");
+  if (!manifestEntry) fail("no znode-package.json in the package");
+  const manifest = JSON.parse(manifestEntry.data.toString("utf8"));
+  validateManifest(manifest, "package");
+
+  const total = entries.reduce((sum, entry) => sum + entry.data.length, 0);
+  if (total > MAX_BYTES) fail(`package is ${total} bytes; the limit is ${MAX_BYTES}`);
+  const files = entries.filter((entry) => entry.name !== "znode-package.json");
+  for (const entry of files) {
+    if (entry.name !== path.basename(entry.name)) fail(`"${entry.name}": a package is flat, no folders`);
+    if (!SERVED.has(path.extname(entry.name).toLowerCase())) fail(`"${entry.name}": file type not allowed`);
+  }
+  const has = (name) => files.some((entry) => entry.name === name);
+  const referenced = [
+    manifest.files?.server,
+    manifest.files?.browser,
+    manifest.files?.messages,
+    ...(manifest.files?.styles || []),
+    ...Object.values(manifest.files?.pages || {}),
+  ].filter(Boolean);
+  for (const name of referenced) if (!has(name)) fail(`znode-package.json names "${name}", which isn't in the package`);
+
+  const registryFile = path.join(storeDir, "plugins.json");
+  const unlock = lockRegistry(storeDir);
+  const registry = fs.existsSync(registryFile) ? readJson(registryFile) : { plugins: [] };
+  // a package never replaces a file another installed package uses
+  const owners = new Map();
+  for (const item of registry.plugins) {
+    if (item.name === manifest.name) continue;
+    for (const name of [item.file, item.browser, item.messages, ...(item.styles || []), ...Object.values(item.pages || {})]) if (name) owners.set(name, item.name);
+  }
+  for (const entry of files) if (owners.has(entry.name)) fail(`"${entry.name}" belongs to package ${owners.get(entry.name)}`);
+
+  fs.mkdirSync(storeDir, { recursive: true });
+  for (const entry of files) fs.writeFileSync(path.join(storeDir, entry.name), entry.data);
+
+  const previous = registry.plugins.find((item) => item.name === manifest.name);
+  const defaults = Object.fromEntries(
+    Object.entries(manifest.settingsSchema || {})
+      .filter(([, field]) => field.default !== undefined)
+      .map(([key, field]) => [key, field.default])
+  );
+  const entry = {
+    name: manifest.name,
+    kind: manifest.kind === "widget" ? "plugin" : manifest.kind,
+    version: manifest.version,
+    label: manifest.label,
+    publisher: manifest.publisher,
+    ...(manifest.parent ? { parent: manifest.parent } : {}),
+    ...(manifest.files?.server ? { file: manifest.files.server } : {}),
+    ...(manifest.files?.browser ? { browser: manifest.files.browser } : {}),
+    ...(manifest.files?.styles?.length ? { styles: manifest.files.styles } : {}),
+    ...(manifest.files?.messages ? { messages: manifest.files.messages } : {}),
+    ...(manifest.files?.pages ? { pages: manifest.files.pages } : {}),
+    ...(manifest.widgets?.length ? { widgets: manifest.widgets } : {}),
+    // the store modules its browser bundle imports: the store loads them first (Generated Store Module Registry)
+    ...(Array.isArray(manifest.storeImports) && manifest.storeImports.length ? { storeImports: manifest.storeImports.map(String) } : {}),
+    ...(manifest.overrides ? { overrides: manifest.overrides } : {}),
+    ...(manifest.serverPages?.length ? { serverPages: manifest.serverPages } : {}),
+    ...(manifest.sandbox === true ? { sandbox: true } : {}),
+    // the webstore accepts files (multipart) only for a package that declares them
+    ...((manifest.permissions || []).includes("uploads") ? { uploads: true } : {}),
+    ...(manifest.settingsSchema ? { settingsSchema: manifest.settingsSchema } : {}),
+    // where it runs and its settings are the store owner's: an upgrade keeps them; a new package starts switched off
+    enabled: previous ? previous.enabled : false,
+    stores: previous ? previous.stores : [],
+    settings: mergeSettings(defaults, previous?.settings || {}),
+  };
+  if (previous) registry.plugins[registry.plugins.indexOf(previous)] = entry;
+  else registry.plugins.push(entry);
+  writeRegistry(registryFile, registry);
+  // the replaced version's files (an upgrade's old bundles and stylesheets) leave the plugin directory
+  const kept = new Set(files.map((file) => file.name));
+  for (const name of [previous?.file, previous?.browser, previous?.messages, ...(previous?.styles || []), ...Object.values(previous?.pages || {})]) {
+    if (name && !kept.has(name) && name === path.basename(name)) fs.rmSync(path.join(storeDir, name), { force: true });
+  }
+
+  unlock();
+
+  const missing = Object.entries(manifest.settingsSchema || {}).filter(([key, field]) => field.required && (entry.settings[key] === undefined || entry.settings[key] === ""));
+  console.log(
+    `installed ${manifest.kind} ${manifest.name}@${manifest.version}${previous ? ` (was ${previous.version || "unversioned"})` : ""}: ${files.length} files, ${entry.enabled ? "enabled" : "disabled"} for ${JSON.stringify(entry.stores)}`
+  );
+  if (missing.length) console.log(`  settings to fill in before enabling: ${missing.map(([key]) => key).join(", ")}`);
+}
+
+// ---- create: a starter package of a kind (templates.mjs), with the API typings next to its sources ---------------
+function create(kind, name, dir) {
+  if (!TEMPLATES[kind]) fail(`kind must be one of ${Object.keys(TEMPLATES).join(", ")}`);
+  if (!NAME.test(name || "")) fail("name must be lowercase letters, digits and dashes (2 to 49)");
+  const target = path.resolve(dir || path.join(process.cwd(), name));
+  if (fs.existsSync(target) && fs.readdirSync(target).length) fail(`${target} exists and is not empty`);
+  for (const [file, content] of Object.entries(TEMPLATES[kind](name))) {
+    const full = path.join(target, file);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, typeof content === "string" ? content : JSON.stringify(content, null, 2) + "\n");
+  }
+  if (kind !== "content") fs.copyFileSync(path.join(HERE, "..", "types", "extension-api.d.ts"), path.join(target, "src", "extension-api.d.ts"));
+  console.log(`created ${kind} ${name} in ${target}`);
+  console.log("  next: fill in label, publisher and description in znode-package.json, then run its build-and-upload.sh");
+}
+
+// ---- check: what a marketplace review looks at, from the package's own files ------------------------------------
+const HOOK_NAMES = ["onCartChanged", "beforeAddToCart", "afterAddToCart", "mapCartItems"];
+
+// the code an entry pulls in: the entry and the files it imports by relative path, followed (a package's server and
+// browser parts share a folder, so a folder read would mix them); type-only imports are skipped
+function sourceOf(dir, entry) {
+  if (!entry) return "";
+  const seen = new Set();
+  const sources = [];
+  const visit = (file) => {
+    if (seen.has(file) || !fs.existsSync(file)) return;
+    seen.add(file);
+    const code = fs.readFileSync(file, "utf8");
+    sources.push(code);
+    for (const [, typeOnly, spec] of code.matchAll(/\bimport\s+(type\s+)?[^;]*?from\s+["'](\.[^"']+)["']/g)) {
+      if (typeOnly) continue;
+      const base = path.resolve(path.dirname(file), spec).replace(/\.(m?js)$/, "");
+      const found = [".ts", ".tsx", ".js", ".mjs", "/index.ts", "/index.tsx"].map((ext) => base + ext).find((candidate) => fs.existsSync(candidate));
+      if (found) visit(found);
+    }
+  };
+  visit(path.join(dir, entry));
+  return sources.join("\n");
+}
+
+// the server renders a browser bundle in this format from one compiled copy for all stores
+// (packages/extensions/src/server-instances.ts); any other is imported once per store, and Node keeps every copy
+function serverRenderFormat(code) {
+  const match = /\bexport\s*(?:\{\s*([A-Za-z_$][\w$]*)\s+as\s+default\s*,?\s*\}|default\s+([A-Za-z_$][\w$]*))\s*;?\s*(?:\/\/#\s*sourceMappingURL=\S*\s*)?$/.exec(code);
+  if (!match || /(^|[^\w$.])import\s*\(/.test(code.slice(0, match.index))) return false;
+  try {
+    new vm.Script(`(function () {\n"use strict";\n${code.slice(0, match.index)}\nreturn ${match[1] || match[2]};\n})`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function check(target) {
+  const { dir, manifestFile } = resolvePackage(target);
+  const manifest = readJson(manifestFile);
+  validateManifest(manifest, path.basename(manifestFile));
+  const errors = [];
+  const warnings = [];
+
+  // the listing
+  for (const key of ["label", "publisher", "description"]) if (!String(manifest[key] || "").trim()) errors.push(`"${key}" is missing (the marketplace shows it)`);
+  if (/describe what it does/i.test(manifest.description || "") || manifest.publisher === "Your company") errors.push("the starter's publisher or description is still in place");
+  else if (String(manifest.description || "").length < 30) warnings.push('"description" is short: say what it does for the store');
+  for (const key of ["license", "compatibility"]) if (!manifest[key]) warnings.push(`"${key}" is missing`);
+
+  // permissions against the code
+  const server = sourceOf(dir, manifest.build?.server);
+  const browser = sourceOf(dir, manifest.build?.browser);
+  const used = new Set();
+  if (/\broutes\s*[:=,}]/.test(server)) used.add("routes");
+  if (HOOK_NAMES.some((hook) => new RegExp(`\\b${hook}\\b`).test(server))) used.add("cartHooks");
+  if (Object.keys(manifest.overrides || {}).length) used.add("overrides");
+  if (/\bznode\s*\(/.test(server)) used.add("znodeApi");
+  if (/\bfetch\s*\(|\bhttps?\.request\s*\(/.test(server)) used.add("externalNetwork");
+  if (/\.files\b/.test(server)) used.add("uploads");
+  const declared = new Set(manifest.permissions || []);
+  for (const item of used) if (!declared.has(item)) errors.push(`uses "${item}" without declaring it in "permissions"`);
+  for (const item of declared) if (!used.has(item)) warnings.push(`declares "${item}" but no code uses it (the review asks why)`);
+  if (/\beval\s*\(|new Function\s*\(/.test(server + browser)) errors.push("uses eval or new Function");
+  if (/document\.cookie/.test(browser)) warnings.push("reads cookies in the browser: keep secrets on the server (routes)");
+
+  // settings
+  for (const [key, field] of Object.entries(manifest.settingsSchema || {})) {
+    if (!field.label) warnings.push(`setting "${key}" has no label (the admin shows it)`);
+    if (field.required && field.default !== undefined) warnings.push(`setting "${key}" is required but has a default`);
+    if (field.browser && /secret|password|token|api_?key/i.test(key)) errors.push(`setting "${key}" looks secret but is sent to the browser ("browser": true)`);
+  }
+  if (manifest.kind === "theme" && !Object.values(manifest.settingsSchema || {}).some((field) => field.attribute)) {
+    warnings.push("no setting is bound to a Znode attribute: per-store branding then needs a registry change per store");
+  }
+
+  // the built files (pack first)
+  const out = path.join(dir, "dist");
+  if (fs.existsSync(out)) {
+    let total = 0;
+    for (const name of fs.readdirSync(out)) {
+      const size = fs.statSync(path.join(out, name)).size;
+      total += size;
+      if (name.endsWith(".browser.mjs")) {
+        if (size > 512 * 1024) warnings.push(`${name} is ${Math.round(size / 1024)} KB: every page of the store loads it`);
+        if (!serverRenderFormat(fs.readFileSync(path.join(out, name), "utf8")))
+          warnings.push(`${name} is not in the server-render format (no imports, one default export): the server keeps a copy per store`);
+      }
+      if (name.endsWith(".css") && size > 200 * 1024) warnings.push(`${name} is ${Math.round(size / 1024)} KB`);
+    }
+    if (total > MAX_BYTES) errors.push(`dist is ${Math.round(total / 1048576)} MB (limit 10 MB)`);
+  } else warnings.push("not built yet: pack it to check sizes and the server-render format");
+
+  for (const item of errors) console.log(`error   ${item}`);
+  for (const item of warnings) console.log(`warning ${item}`);
+  console.log(`check ${manifest.name}@${manifest.version}: ${errors.length} errors, ${warnings.length} warnings`);
+  if (errors.length) process.exit(1);
+}
+
+// ---- project commands: deploy, dev, link-store ------------------------------------------------------------------
+
+const needStore = (storeDir) =>
+  storeDir || fail("needs the store's plugin folder: pass it after the package, or set RUNTIME_PLUGINS_DIR");
+
+// pack, then install the zip it made into the store's plugin folder
+function deploy(target, storeDir) {
+  pack(target);
+  const { dir, manifestFile } = resolvePackage(target);
+  const manifest = readJson(manifestFile);
+  install(path.join(dir, "releases", `${manifest.name}-${manifest.version}.zpkg.zip`), storeDir);
+}
+
+// deploy now, then again whenever the package's sources or manifest change; the store picks a new file up on the next
+// request (it reloads a package when its files change), so a page refresh shows the change
+function dev(target, storeDir) {
+  const { dir } = resolvePackage(target);
+  const self = fileURLToPath(import.meta.url);
+  const run = () => spawnSync(process.execPath, [self, "deploy", dir, storeDir], { stdio: "inherit" });
+  run();
+  let timer = null;
+  const changed = (file) => {
+    if (!file || /(^|[\\/])(dist|releases|\.build|node_modules)([\\/]|$)/.test(String(file))) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      console.log(`znode dev: ${file} changed, deploying`);
+      run();
+    }, 300);
+  };
+  fs.watch(path.join(dir, "src"), { recursive: true }, (_event, file) => changed(file && path.join("src", file)));
+  fs.watch(dir, (_event, file) => file === MANIFEST && changed(file));
+  console.log(`znode dev: watching ${dir} (Ctrl+C to stop)`);
+}
+
+// the store's real types for the editor and the build check: tsconfig.store.json (git-ignored, per machine) is this
+// package's preset plus the store repo's aliases (every @znode path of its tsconfig.base.json, from the store's folder).
+// Only the aliases are taken: the store's own options (its rootDir among them) would refuse a project kept elsewhere.
+function linkStore(storeRepo, project = ".") {
+  const base = path.resolve(storeRepo, "tsconfig.base.json");
+  if (!fs.existsSync(base)) fail(`${base} not found: pass the store repo's folder (the one with tsconfig.base.json)`);
+  const ts = require("typescript");
+  const { config, error } = ts.readConfigFile(base, ts.sys.readFile);
+  if (error) fail(`${base}: ${ts.flattenDiagnosticMessageText(error.messageText, "\n")}`);
+  const options = config.compilerOptions || {};
+  const toSlash = (value) => value.split(path.sep).join("/");
+  const file = path.resolve(project, "tsconfig.store.json");
+  const linked = {
+    extends: "znode-plugin/tsconfig.json",
+    compilerOptions: { baseUrl: toSlash(path.resolve(path.dirname(base), options.baseUrl || ".")), paths: options.paths || {} },
+  };
+  fs.writeFileSync(file, JSON.stringify(linked, null, 2) + "\n");
+  console.log(`linked ${file} to ${base} (${Object.keys(linked.compilerOptions.paths).length} store aliases)`);
+}
+
+// ---- eject: a store component copied into the package, in place of the store's, through its slot ----------------
+// A store component that has a runtime slot whose children are the component itself (withRuntimeWrapper(Wrapper, Base,
+// "Name") where it is defined) can be taken over by a package: `znode eject <Name>` copies its file from the linked store
+// into src/components/<Name>.tsx (relative imports turned into the store's @znode aliases, the runtime wrapper removed so
+// the copy is the plain component) and registers it in src/browser.tsx under the slot, so the store renders the copy
+// instead of its own. `znode eject` lists the components that can be ejected.
+const EJECT_SLOTS = {
+  RuntimeProductBasicInfo: "product.basicInfo",
+  RuntimeProductCard: "product.card",
+  RuntimeProductImage: "product.image",
+  RuntimeAddToCart: "product.addToCart",
+  RuntimeProductVariants: "product.variants",
+  RuntimeAddToCartNotification: "addToCart.notification",
+  RuntimeCheckoutAddress: "checkout.address",
+  RuntimeShippingOptions: "checkout.shippingOptions",
+};
+
+// every withRuntimeWrapper(<Wrapper>, <Base>, "<Name>") in the store's base components, with the slot it fills
+function ejectableComponents(root) {
+  const found = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== "node_modules") walk(file);
+      } else if (/\.tsx?$/.test(entry.name)) {
+        const text = fs.readFileSync(file, "utf8");
+        for (const m of text.matchAll(/withRuntimeWrapper\(\s*(\w+)\s*,\s*(\w+)\s*,\s*"(\w+)"\s*\)/g)) {
+          if (EJECT_SLOTS[m[1]]) found.push({ name: m[3], wrapper: m[1], base: m[2], slot: EJECT_SLOTS[m[1]], file });
+        }
+      }
+    }
+  };
+  for (const dir of ["packages/base-components/src", "packages/page-builder/src"]) if (fs.existsSync(path.join(root, dir))) walk(path.join(root, dir));
+  return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// a store file's import path as the package can import it: the store alias that maps to that file, without extension
+function storeAlias(store, absolute) {
+  const target = absolute.split(path.sep).join("/").replace(/\.(tsx?|jsx?)$/, "").replace(/\/index$/, "");
+  let best = null;
+  const norm = (value) => path.resolve(store.root, value).split(path.sep).join("/").replace(/\.(tsx?|jsx?)$/, "").replace(/\/index$/, "");
+  // an exact alias for this very module ("@znode/base-components/stores": [".../stores/index.ts"]) wins
+  for (const [alias, targets] of Object.entries(store.paths)) {
+    if (!alias.endsWith("/*") && targets.some((pattern) => norm(pattern) === target)) return alias;
+  }
+  for (const [alias, targets] of Object.entries(store.paths)) {
+    if (!alias.endsWith("/*")) continue;
+    for (const pattern of targets) {
+      const prefix = path.resolve(store.root, pattern.replace(/\*$/, "")).split(path.sep).join("/").replace(/\/$/, "") + "/";
+      if (target.startsWith(prefix) && (!best || prefix.length > best.prefix.length)) best = { prefix, alias: alias.slice(0, -1) };
+    }
+  }
+  return best ? best.alias + target.slice(best.prefix.length) : null;
+}
+
+function eject(name, force) {
+  const project = path.resolve(".");
+  if (!fs.existsSync(path.join(project, MANIFEST))) fail(`run znode eject in a package folder (the one with ${MANIFEST})`);
+  const store = linkedStore(project);
+  if (!store) fail("the package is not linked to a store: npm run link-store -- <store repo>");
+  const components = ejectableComponents(store.root);
+  if (!name || name === "--list") {
+    console.log("Store components a package can eject (the slot that takes your copy):\n");
+    for (const c of components) console.log(`  ${c.name.padEnd(34)} ${c.slot.padEnd(26)} ${path.relative(store.root, c.file).split(path.sep).join("/")}`);
+    console.log("\nznode eject <Name>   copies one into src/components/ and registers it in src/browser.tsx");
+    return;
+  }
+  const c = components.find((item) => item.name.toLowerCase() === name.toLowerCase());
+  if (!c) fail(`${name} cannot be ejected: it has no slot that hands over the component (znode eject lists the ones that can)`);
+
+  const out = path.join(project, "src", "components", `${c.name}.tsx`);
+  if (fs.existsSync(out) && !force) fail(`${path.relative(project, out)} exists: delete it or run znode eject ${c.name} --force`);
+  const warnings = [];
+  let text = fs.readFileSync(c.file, "utf8");
+  // relative imports become the store's aliases (the package lives elsewhere); a style file stays the store's
+  text = text.replace(/((?:from|import)\s*\(?\s*["'])(\.{1,2}\/[^"']+)(["'])/g, (whole, before, spec, after) => {
+    const absolute = path.resolve(path.dirname(c.file), spec);
+    if (/\.(s?css)$/.test(spec)) {
+      warnings.push(`style import ${spec}: kept out of the copy; the store's own stylesheet is loaded where the store renders it, add your CSS to src/styles/`);
+      return `${before}${spec}${after}`;
+    }
+    const alias = storeAlias(store, fs.existsSync(absolute) || /\.\w+$/.test(spec) ? absolute : absolute);
+    if (!alias) {
+      warnings.push(`import ${spec}: no store alias for it; change it by hand`);
+      return whole;
+    }
+    return `${before}${alias}${after}`;
+  });
+  // drop scss/css side-effect imports that point into the store (they cannot be bundled into a package)
+  text = text.replace(/^import\s+["'][^"']+\.s?css["'];?\s*\n/gm, "");
+  // the copy is the plain component: no runtime wrapper (the slot is what puts it in place)
+  text = text.replace(new RegExp(`^.*import\\s*\\{[^}]*\\b(?:withRuntimeWrapper|${c.wrapper})\\b[^}]*\\}\\s*from\\s*["'][^"']+["'];?\\s*\\n`, "gm"), "");
+  text = text.replace(new RegExp(`withRuntimeWrapper\\(\\s*${c.wrapper}\\s*,\\s*${c.base}\\s*,\\s*"${c.name}"\\s*\\)`), c.base);
+  const storeFile = path.relative(store.root, c.file).split(path.sep).join("/");
+  const header = `// Ejected from the store: ${storeFile} (${new Date().toISOString().slice(0, 10)}), with \`znode eject ${c.name}\`.\n// The store renders this copy instead of its own through the slot "${c.slot}" (src/browser.tsx). It is yours now: the\n// store's later changes to ${c.name} do not reach it, so compare it with the store's file after a store upgrade.\n`;
+  text = text.startsWith('"use client"') || text.startsWith("'use client'") ? text.replace(/^(["']use client["'];?\s*\n)/, `$1${header}`) : header + text;
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, text);
+  console.log(`ejected ${c.name} -> ${path.relative(project, out)}`);
+
+  // npm packages the copy imports that this package does not have (react, next and the store's @znode modules come from
+  // the store): install them at the store's version, so the types match and the build finds them
+  const PROVIDED = /^(react|react-dom|next|next-intl|@znode)(\/|$)/;
+  const storePackage = (() => {
+    try {
+      return readJson(path.join(store.root, "package.json"));
+    } catch {
+      return {};
+    }
+  })();
+  const storeDeps = { ...(storePackage.devDependencies || {}), ...(storePackage.dependencies || {}) };
+  const missing = new Map();
+  for (const m of text.matchAll(/(?:from|import)\s*\(?\s*["']([^."'/][^"']*)["']/g)) {
+    const spec = m[1];
+    if (PROVIDED.test(spec)) continue;
+    const pkg = spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0];
+    try {
+      createRequire(path.join(project, "package.json")).resolve(`${pkg}/package.json`);
+    } catch {
+      missing.set(pkg, storeDeps[pkg] ? `${pkg}@${storeDeps[pkg].replace(/^[\^~]/, "")}` : pkg);
+    }
+  }
+  if (missing.size) {
+    console.log(`\nThe copy imports npm packages this package does not have (bundled into the package when it builds):`);
+    console.log(`  npm install ${[...missing.values()].join(" ")}`);
+  }
+
+  // register the copy under the slot in src/browser.tsx
+  const browser = path.join(project, "src", "browser.tsx");
+  const exportsDefault = new RegExp(`export\\s+default\\s+${c.name}\\b`).test(text) || new RegExp(`export\\s+default\\s+${c.base}\\b`).test(text);
+  const local = `Ejected${c.name}`;
+  const importLine = exportsDefault
+    ? `import ${local} from "./components/${c.name}.js";`
+    : `import { ${c.name} as ${local} } from "./components/${c.name}.js";`;
+  if (!fs.existsSync(browser)) {
+    warnings.push(`src/browser.tsx not found: register it yourself: ${importLine}  and  slots: { "${c.slot}": ${local} }`);
+  } else {
+    let source = fs.readFileSync(browser, "utf8");
+    if (new RegExp(`["']${c.slot.replace(".", "\\.")}["']\\s*:`).test(source)) {
+      warnings.push(`src/browser.tsx already fills "${c.slot}": point it at ${local} (${importLine}) yourself`);
+    } else if (/slots\s*:\s*\{/.test(source)) {
+      if (!source.includes(importLine)) {
+        const imports = [...source.matchAll(/^import .*;\s*$/gm)];
+        const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length : 0;
+        source = source.slice(0, at) + `\n${importLine}` + source.slice(at);
+      }
+      source = source.replace(/slots\s*:\s*\{\s*\}/, `slots: {\n      "${c.slot}": ${local},\n    }`);
+      if (!source.includes(`"${c.slot}": ${local}`)) source = source.replace(/slots\s*:\s*\{/, `slots: {\n      // ejected (znode eject ${c.name}): the store renders this copy instead of its own\n      "${c.slot}": ${local},`);
+      fs.writeFileSync(browser, source);
+      console.log(`registered "${c.slot}": ${local} in src/browser.tsx`);
+    } else {
+      warnings.push(`no "slots" in src/browser.tsx: add ${importLine} and slots: { "${c.slot}": ${local} }`);
+    }
+  }
+  for (const warning of warnings) console.log(`warning ${warning}`);
+  console.log(`\nNext: npm run build (it names any store import a package cannot use), then npm run dev and open a page that shows ${c.name}.`);
+}
+
+const args = process.argv.slice(2);
+// the store's plugin folder: the argument, else RUNTIME_PLUGINS_DIR, else the project's git-ignored znode.local.json
+// ({ "pluginsDir": "…" }, written by create-znode-plugin --plugins-dir) in the folder the command runs in
+function localPluginsDir() {
+  try {
+    return JSON.parse(fs.readFileSync(path.resolve("znode.local.json"), "utf8")).pluginsDir || undefined;
+  } catch {
+    return undefined;
+  }
+}
+const [command, target, storeDir = process.env.RUNTIME_PLUGINS_DIR || localPluginsDir()] = args;
+if (command === "create") {
+  create(args[1], args[2], args[3]);
+  process.exit(0);
+}
+if (command === "eject") {
+  eject(args.find((arg, index) => index > 0 && !arg.startsWith("--")), args.includes("--force"));
+  process.exit(0);
+}
+if (command === "link-store") {
+  if (!target) fail("usage: znode link-store <storeRepoDir> [projectDir]");
+  linkStore(target, args[2]);
+  process.exit(0);
+}
+if (!target) fail("usage: znode <build|pack|check|install|deploy|dev> <dir|zip> [storeDir], znode create <kind> <name> [dir], znode link-store <storeRepoDir>");
+if (command === "check") check(path.resolve(target));
+else if (command === "build") build(path.resolve(target));
+else if (command === "pack") pack(path.resolve(target));
+else if (command === "install") install(path.resolve(target), path.resolve(needStore(storeDir)));
+else if (command === "deploy") deploy(path.resolve(target), path.resolve(needStore(storeDir)));
+else if (command === "dev") dev(path.resolve(target), path.resolve(needStore(storeDir)));
+else fail(`unknown command "${command}"`);