znode-plugin 0.0.0-stage → 0.1.1

package/lib/znode-package.mjs

@@ -0,0 +1,680 @@
+#!/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}"`);