znode-plugin 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# znode-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The SDK for Znode runtime plugins and themes: the `znode` command behind every project made with
+`create-znode-plugin`. A package is built on its own and runs in the webstore for the stores it is enabled for, with no
+fork of the store and no webstore rebuild.
+
+## Getting started
+
+Start a new project with the recipe (any one of these, they are the same):
+
+```bash
+npm create znode-plugin@latest my-theme
+npx create-znode-plugin@latest my-theme
+npm init znode-plugin@latest my-theme
+```
+
+It then asks two things, so have them ready:
+
+1. **The store path to connect**: the store repo, the folder with `tsconfig.base.json` at its root. The project gets
+   the store's real types from it (`znode link-store`).
+2. **The store's plugin folder**: where the webstore loads runtime packages from (its `RUNTIME_PLUGINS_DIR`, the folder
+   with `plugins.json`). Usually found for you in the store's `apps/webstore/.env.local` (or `.env`); asked only when
+   the store does not set it. `npm run dev` and `npm run deploy` copy your package there.
+
+Then:
+
+```bash
+cd my-theme
+npm run dev
+```
+
+and, with the webstore running in development mode, preview the theme in your browser only:
+`http://localhost:3000/api/extensions/preview?theme=my-theme`. The full walkthrough (every question, what to enter,
+skipping, scripts and CI, troubleshooting): [`create-znode-plugin`](https://www.npmjs.com/package/create-znode-plugin).
+
+To add the SDK to an existing package instead:
+
+```bash
+npm install -D znode-plugin
+```
+
+## Connecting a project to a store
+
+| What | How | Saved in |
+| --- | --- | --- |
+| The store's types | `npm run link-store -- <store repo>` (`znode link-store <storeRepo> [dir]`) | `tsconfig.store.json` (git-ignored) |
+| The store's plugin folder | Answer the recipe's question, or write it yourself: `{ "pluginsDir": "D:\\znode\\runtime-plugins-store" }` | `znode.local.json` (git-ignored) |
+
+Both are per machine: each developer connects their own checkout. Run `link-store` again after the store adds or moves
+modules.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `znode build <dir>` | Type-check (with a `tsconfig.json`), then build the server and browser bundles into `dist/` |
+| `znode check <dir>` | Marketplace review: metadata, permissions against the code, settings, sizes |
+| `znode pack <dir>` | Build and zip into `releases/<name>-<version>.zpkg.zip` |
+| `znode install <zip\|dir> [storeDir]` | Install into the store's plugin folder (keeps the store's settings and stores) |
+| `znode deploy <dir> [storeDir]` | Pack, then install |
+| `znode dev <dir> [storeDir]` | Deploy, then again on every change under `src/` or to `znode-package.json` |
+| `znode link-store <storeRepo> [dir]` | Writes `tsconfig.store.json` so `@znode/*` imports get the store's real types |
+| `znode create <kind> <name> [dir]` | A minimal starter of a kind (theme, plugin, widget, content) |
+
+`storeDir` (the store's `RUNTIME_PLUGINS_DIR`): the argument, else the `RUNTIME_PLUGINS_DIR` environment variable, else
+`znode.local.json` (`{ "pluginsDir": "…" }`) in the folder the command runs in. With none of them, `deploy`, `install`
+and `dev` stop with `needs the store's plugin folder`.
+
+## After deploying
+
+- **Preview** (your browser only, webstore in development mode):
+  `/api/extensions/preview?theme=<name>`, `…&to=/<path>` to open a page, `/api/extensions/preview` to stop.
+  `/api/extensions/preview?list` lists the themes the store can see.
+- **Live for a store**: in the plugin folder's `plugins.json`, set the package's `"enabled": true` and add the store
+  codes to `"stores"`. Deploying again keeps those settings.
+
+## Imports in a package
+
+| Import | At runtime |
+| --- | --- |
+| `react`, `react/jsx-runtime`, `next/image`, `next/link`, `next/navigation` | The store's own copies (one React, its router and images config) |
+| `next/font/google` | Built into the package: the font files are downloaded at build time |
+| `@znode/…` store modules the store publishes | The store's own modules, in browser parts |
+
+Types for the package API (slots, widgets, server slots, server pages, routes, hooks): `znode-plugin/types/extension-api`.

package/lib/css-dedupe.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Drops the rules a store already has from a stylesheet copied from another site (live widget CSS), so only the missing
+// ones ship: a repeated utility class loaded later would otherwise win over the store's own responsive order.
+// Usage: node css-dedupe.mjs <in.css> <storePageUrl> <out.css>
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// postcss from ZNODE_TOOLS, else the webstore repo's node_modules (as znode-package.mjs)
+const require = createRequire(path.join(process.env.ZNODE_TOOLS || path.resolve(HERE, "../../node_modules"), "noop.js"));
+const postcss = require("postcss");
+
+const [, , input, pageUrl, output] = process.argv;
+const key = (rule) => {
+  let parent = rule.parent;
+  const wrappers = [];
+  while (parent && parent.type === "atrule") {
+    wrappers.unshift(`@${parent.name} ${parent.params}`);
+    parent = parent.parent;
+  }
+  return `${wrappers.join(" ")}|${rule.selector.replace(/\s+/g, " ").trim()}`;
+};
+
+// *.localhost store names resolve to this machine (Node's DNS lookup doesn't know them)
+const fetchText = (url) => {
+  const target = new URL(url);
+  if (!target.hostname.endsWith(".localhost")) return fetch(url).then((response) => response.text());
+  return new Promise((resolve, reject) => {
+    http
+      .get({ host: "127.0.0.1", port: target.port || 80, path: target.pathname + target.search, headers: { host: target.host } }, (response) => {
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => (body += chunk));
+        response.on("end", () => resolve(body));
+      })
+      .on("error", reject);
+  });
+};
+
+const html = await fetchText(pageUrl);
+const hrefs = [...html.matchAll(/<link[^>]+rel="stylesheet"[^>]+href="([^"]+)"/g)].map((match) => new URL(match[1].replace(/&amp;/g, "&"), pageUrl).href);
+const known = new Set();
+for (const href of hrefs) {
+  if (href.includes("/api/extensions/")) continue;
+  postcss.parse(await fetchText(href)).walkRules((rule) => known.add(key(rule)));
+}
+const root = postcss.parse(fs.readFileSync(input, "utf8"));
+let dropped = 0;
+root.walkRules((rule) => {
+  if (known.has(key(rule))) {
+    rule.remove();
+    dropped++;
+  }
+});
+root.walkAtRules((atRule) => {
+  if (atRule.nodes && atRule.nodes.length === 0) atRule.remove();
+});
+fs.writeFileSync(output, root.toString());
+console.log(`css-dedupe: ${dropped} rules the store already has dropped, ${fs.statSync(output).size} bytes kept (${hrefs.length} store stylesheets)`);

package/lib/next-imports.mjs

@@ -0,0 +1,298 @@
+// Next.js imports in a package, as a Next.js app writes them: import Image from "next/image", import Link from
+// "next/link", import { useRouter } from "next/navigation", import { Montserrat } from "next/font/google".
+//
+// A package is built here, not by the store's Next.js, and the store loads it at runtime, so it cannot bundle Next
+// itself (a second React and Next) and nothing compiles next/font for it. This rollup plugin, used by
+// znode-package.mjs build, does both jobs instead:
+//   next/image, next/link, next/navigation, react: stand-ins that use the store's own modules at runtime (the store
+//     publishes them: packages/extensions/src/next-modules.server.ts for server parts, client/runtime.ts for browser
+//     parts), so a package renders the store's next/image with the store's images config, one React, one router
+//   next/font/google: what next/font does, at the package's build: the font's files are downloaded from Google into
+//     the package (served by the store with its other files), @font-face rules and a class are added to the package's
+//     stylesheet, and the call is replaced by { className, style: { fontFamily }, variable }
+// Any other next/* import stops the build: it names what is supported.
+
+import fs from "fs";
+import path from "path";
+import vm from "vm";
+import crypto from "crypto";
+
+// what a package may import, per module: names it can use, and which are components (rendered by the store's own)
+const MODULES = {
+  "next/image": { default: "component" },
+  "next/link": { default: "component" },
+  "next/navigation": {
+    useRouter: "function",
+    usePathname: "function",
+    useSearchParams: "function",
+    useParams: "function",
+    redirect: "function",
+    permanentRedirect: "function",
+    notFound: "function",
+  },
+  react: {
+    // import React from "react": the store's React (React.useState, React.memo, ...)
+    default: "namespace",
+    createElement: "function",
+    cloneElement: "function",
+    isValidElement: "function",
+    Fragment: "value",
+    Suspense: "value",
+    Children: "value",
+    useState: "function",
+    useEffect: "function",
+    useLayoutEffect: "function",
+    useRef: "function",
+    useMemo: "function",
+    useCallback: "function",
+    useReducer: "function",
+    useId: "function",
+    useTransition: "function",
+    useSyncExternalStore: "function",
+  },
+  // JSX compiled as Next.js does it (a package with its own tsconfig.json): the store's React creates the elements
+  "react/jsx-runtime": { jsx: "function", jsxs: "function", Fragment: "value" },
+};
+// the server-only functions a browser part may not need, and the hooks a server part cannot call, stay importable:
+// the store's module for that side decides (a hook in a server part fails as it would in a Next.js server component)
+
+// The store's own modules a browser part may import by the store's path, so a theme's own component (a copy of the
+// store's, say) keeps the store's imports instead of re-creating them: relative paths become "@znode/..." paths (the
+// store publishes them: packages/extensions/src/client/store-modules.ts; keep the two lists the same). Types for
+// package authors: sdk/store-modules.d.ts. Kinds: component (rendered by the store's React), function, object (its
+// properties read when used, its methods bound to it).
+const STORE_MODULES = {
+  lodash: { debounce: "function" },
+  "next-intl": { useTranslations: "function" },
+  "@znode/logger": { logClient: "object" },
+  "@znode/logger/server": { AREA: "object" },
+  "@znode/constants/settings": { SETTINGS: "object" },
+  "@znode/constants/user-activity-event": { USER_ACTIVITY_EVENT: "object" },
+  "@znode/utils/common": { getValidatedRedirectPath: "function" },
+  "@znode/base-components/components/common/icons": { LoadingSpinner: "component", SearchIcon: "component", ZIcons: "component" },
+  "@znode/base-components/components/common/button/Button": { default: "component" },
+  "@znode/base-components/components/common/input/Input": { default: "component" },
+  "@znode/base-components/components/common/image": { CustomImage: "component" },
+  "@znode/base-components/http-request": {
+    getHydratedSuggestionSearch: "function",
+    getHydratedTypeaheadSearchContent: "function",
+    getSearchRedirectURL: "function",
+    userActivityLog: "function",
+  },
+  "@znode/base-components/components/layout-components/header/barcode-scanner/BarcodeScanner": { BarcodeScanner: "component" },
+  "@znode/base-components/components/layout-components/header/search/Search": { DynamicVoiceSearch: "component" },
+  "@znode/base-components/components/layout-components/header/search-box": { SearchBox: "component" },
+  "@znode/base-components/components/layout-components/header/search-box/TypeaheadSearch": { TypeaheadSearch: "component" },
+  "@znode/base-components/components/layout-components/header/search-box/HydratedSearchList": { HydratedSearchList: "component" },
+};
+Object.assign(MODULES, STORE_MODULES);
+
+// react's values, the same in every React 19 build and never read from the store at load
+const VALUES = {
+  Fragment: `Symbol.for("react.fragment")`,
+  Suspense: `Symbol.for("react.suspense")`,
+  Children: `{ map: (...args) => mod().Children.map(...args), forEach: (...args) => mod().Children.forEach(...args), count: (...args) => mod().Children.count(...args), toArray: (...args) => mod().Children.toArray(...args), only: (...args) => mod().Children.only(...args) }`,
+};
+
+const FONT_MODULE = "next/font/google";
+const VIRTUAL = "\0znode-next:";
+const CHROME = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36";
+
+// the stand-in module: each name reads the store's module when used, never at load (a server part is also loaded where
+// nothing renders, e.g. for its routes)
+function standIn(id, part) {
+  const global = part === "server" ? "__znodeNextServer" : "__znodeNextClient";
+  const lines = [
+    `const store = () => globalThis.${global} || {};`,
+    `const mod = () => { const m = store()[${JSON.stringify(id)}]; if (!m) throw new Error(${JSON.stringify(`${id} is not available to this package part`)}); return m; };`,
+  ];
+  for (const [name, kind] of Object.entries(MODULES[id])) {
+    const local = name === "default" ? "__default" : name;
+    if (kind === "component") {
+      lines.push(`function ${local}(props) { return store().react.createElement(mod()[${JSON.stringify(name)}], props); }`);
+    } else if (kind === "function") {
+      lines.push(`const ${local} = (...args) => mod()[${JSON.stringify(name)}](...args);`);
+    } else if (kind === "object" || kind === "namespace") {
+      // an object (SETTINGS, logClient) or the module itself (React): each property read when used, methods bound to it
+      const target = kind === "namespace" ? "mod()" : `mod()[${JSON.stringify(name)}]`;
+      lines.push(
+        `const ${local} = new Proxy({}, { get: (_, key) => { const target = ${target}; const value = target[key]; return typeof value === "function" ? value.bind(target) : value; }, has: (_, key) => key in ${target} });`
+      );
+    } else {
+      // a value, which must not depend on when the package loads (Node keeps a loaded module): React's element types
+      // are global symbols, Children forwards each call
+      lines.push(`const ${local} = ${VALUES[name]};`);
+    }
+    lines.push(name === "default" ? `export default ${local};` : `export { ${local} };`);
+  }
+  return lines.join("\n");
+}
+
+// ---- next/font/google ----------------------------------------------------------------------------------------------
+
+// the call's options, a literal object as next/font requires (no variables, no calls)
+function readOptions(text, where) {
+  try {
+    // the timeout only stops a runaway expression: a busy machine (a build or type-check running) needs room
+    return vm.runInNewContext(`(${text || "{}"})`, Object.create(null), { timeout: 2000 });
+  } catch (error) {
+    throw new Error(`${where}: next/font/google options must be a literal object, as in Next.js (${error?.message || error}): ${text}`);
+  }
+}
+
+// from an opening parenthesis to its closing one, skipping strings
+function closingParen(code, open) {
+  let depth = 0;
+  let quote = "";
+  for (let index = open; index < code.length; index++) {
+    const char = code[index];
+    if (quote) {
+      if (char === "\\") index++;
+      else if (char === quote) quote = "";
+    } else if (char === '"' || char === "'" || char === "`") quote = char;
+    else if (char === "(") depth++;
+    else if (char === ")" && --depth === 0) return index;
+  }
+  return -1;
+}
+
+const asList = (value) => (value === undefined ? [] : Array.isArray(value) ? value.map(String) : [String(value)]);
+
+async function fetchText(url) {
+  const response = await fetch(url, { headers: { "User-Agent": CHROME } });
+  return { status: response.status, text: await response.text() };
+}
+
+// the Google Fonts CSS for a family: the weights and styles asked for, else the variable range, else the default
+async function googleCss(family, options) {
+  const weights = asList(options.weight);
+  const styles = asList(options.style);
+  const name = family.replace(/_/g, " ");
+  const base = `https://fonts.googleapis.com/css2?family=${encodeURIComponent(name).replace(/%20/g, "+")}`;
+  const display = `&display=${options.display || "swap"}`;
+  const italic = styles.includes("italic");
+  const tries = [];
+  if (weights.length && !weights.includes("variable")) {
+    const pairs = weights.flatMap((weight) => (italic ? [`0,${weight}`, `1,${weight}`] : [weight])).sort();
+    tries.push(`${base}:${italic ? "ital," : ""}wght@${pairs.join(";")}${display}`);
+  } else {
+    tries.push(`${base}:${italic ? "ital,wght@0,100..900;1,100..900" : "wght@100..900"}${display}`);
+    tries.push(`${base}${display}`);
+  }
+  for (const url of tries) {
+    const { status, text } = await fetchText(url);
+    if (status === 200) return text;
+  }
+  throw new Error(`next/font/google: Google Fonts has no "${name}" with ${weights.join(", ") || "these options"} (${tries[0]})`);
+}
+
+// downloads one font into the package: its files, its @font-face rules under the package's own family name, a class
+export async function buildFont(family, options, { prefix, outDir, where }) {
+  const subsets = asList(options.subsets);
+  const css = await googleCss(family, options);
+  const key = crypto.createHash("sha1").update(`${family}${JSON.stringify(options)}`).digest("hex").slice(0, 8);
+  const slug = `${family.toLowerCase().replace(/[^a-z0-9]+/g, "-")}-${key}`;
+  const fontFamily = `__${prefix.replace(/[^a-zA-Z0-9]/g, "_")}_${family}_${key}`;
+  const files = [];
+  const faces = [];
+  // a variable font answers the same file for every weight: downloaded once
+  const downloaded = new Map();
+  // Google answers one @font-face per subset, each after a /* subset */ comment
+  for (const match of css.matchAll(/(?:\/\*\s*([\w-]+)\s*\*\/\s*)?@font-face\s*\{([^}]*)\}/g)) {
+    const [, subset, body] = match;
+    if (subsets.length && subset && !subsets.includes(subset)) continue;
+    const source = /url\((https:[^)]+)\)/.exec(body)?.[1];
+    if (!source) continue;
+    let file = downloaded.get(source);
+    if (!file) {
+      file = `${prefix}-font-${slug}-${files.length + 1}${path.extname(new URL(source).pathname) || ".woff2"}`;
+      const response = await fetch(source, { headers: { "User-Agent": CHROME } });
+      if (!response.ok) throw new Error(`${where}: could not download ${source} (${response.status})`);
+      fs.writeFileSync(path.join(outDir, file), Buffer.from(await response.arrayBuffer()));
+      downloaded.set(source, file);
+      files.push(file);
+    }
+    faces.push(`@font-face {${body.replace(/font-family:[^;]+;/, `font-family: '${fontFamily}';`).replace(/url\([^)]+\)/, `url(${file})`)}}`);
+  }
+  if (!faces.length) throw new Error(`${where}: Google Fonts sent no ${family} files for subsets ${subsets.join(", ") || "(all)"}`);
+  const fallback = asList(options.fallback).length ? asList(options.fallback) : ["system-ui", "sans-serif"];
+  const stack = [`'${fontFamily}'`, ...fallback].join(", ");
+  const className = `znf-${prefix}-${slug}`.replace(/[^a-zA-Z0-9_-]/g, "-");
+  const variable = options.variable ? `${className}-variable` : "";
+  const rules = [`.${className} { font-family: ${stack}; }`];
+  if (variable) rules.push(`.${variable} { ${options.variable}: ${stack}; }`);
+  return {
+    files,
+    css: `/* ${family} (next/font/google, built with the package) */\n${faces.join("\n")}\n${rules.join("\n")}\n`,
+    value: { className, style: { fontFamily: stack }, ...(variable ? { variable } : {}) },
+  };
+}
+
+// replaces next/font/google imports and calls in one module's code
+async function transformFonts(code, id, context) {
+  const imports = [...code.matchAll(/import\s*\{([^}]*)\}\s*from\s*["']next\/font\/google["'];?/g)];
+  if (!imports.length) return null;
+  let output = code;
+  for (const match of imports) output = output.replace(match[0], "");
+  const names = imports.flatMap((match) =>
+    match[1]
+      .split(",")
+      .map((part) => part.trim())
+      .filter(Boolean)
+      .map((part) => {
+        const [family, local = family] = part.split(/\s+as\s+/).map((item) => item.trim());
+        return { family, local };
+      })
+  );
+  for (const { family, local } of names) {
+    const call = new RegExp(`(^|[^\\w$.])${local}\\s*\\(`, "g");
+    let match;
+    while ((match = call.exec(output))) {
+      const start = match.index + match[1].length;
+      const open = output.indexOf("(", start);
+      const close = closingParen(output, open);
+      if (close < 0) throw new Error(`${id}: unclosed ${local}( call`);
+      const where = `${path.basename(id)} ${family}()`;
+      const font = await buildFont(family, readOptions(output.slice(open + 1, close).trim(), where), { ...context, where });
+      context.fonts.push(font);
+      const value = JSON.stringify(font.value);
+      output = output.slice(0, start) + value + output.slice(close + 1);
+      call.lastIndex = start + value.length;
+    }
+  }
+  return output;
+}
+
+/**
+ * The rollup plugin. part: "server" | "browser"; prefix: "<name>-<version>"; outDir: dist; fonts: collects what
+ * next/font/google built (files, css), which the build adds to the package's assets and stylesheet.
+ */
+export function znodeNext({ part, prefix, outDir, fonts }) {
+  return {
+    name: "znode-next",
+    resolveId(source) {
+      if (STORE_MODULES[source] && part === "server") {
+        this.error(`"${source}" is a store module for browser parts (src/browser.tsx), not server parts`);
+      }
+      if (MODULES[source]) return VIRTUAL + source;
+      if (source === FONT_MODULE) return null;
+      if (source === "next" || source.startsWith("next/")) {
+        this.error(`"${source}" is not available to packages. Supported: ${[...Object.keys(MODULES), FONT_MODULE].filter((id) => !STORE_MODULES[id]).join(", ")}`);
+      }
+      if (source.startsWith("@znode/")) {
+        this.error(`"${source}" is not available to packages. Store components a package can import: ${Object.keys(STORE_MODULES).join(", ")}`);
+      }
+      return null;
+    },
+    load(id) {
+      return id.startsWith(VIRTUAL) ? standIn(id.slice(VIRTUAL.length), part) : null;
+    },
+    async transform(code, id) {
+      if (id.startsWith(VIRTUAL)) return null;
+      const output = await transformFonts(code, id, { prefix, outDir, fonts });
+      return output === null ? null : { code: output, map: null };
+    },
+  };
+}
+
+export const SUPPORTED_MODULES = MODULES;