znode-plugin 0.1.5 → 0.1.6

package/README.md

@@ -292,7 +292,8 @@ Run them with `npm run <name>` inside a project (the scripts call `znode … .`)
 | | `npx znode install <zip> [pluginsDir]` | install a released zip into a store's plugin folder |
 | | `npx znode create <theme\|plugin\|widget\|content> <name>` | a minimal starter of another kind |
 | | `npx znode eject` | list the store components a package can take over (each has a slot that hands the component over) |
-| | `npx znode eject <Name> [--force]` | copy the store's component into `src/components/<Name>.tsx` (imports turned into store aliases, runtime wrapper removed) and register it in `src/browser.tsx` under its slot; prints any npm package the copy needs. The copy is yours: store fixes no longer reach it |
+| | `npx znode add-slot <Component> <area.name> [--dry-run] [--file <store file>]` | add a slot around a store component that has none, in the **linked store's source** (not the theme, never `.next`): a `Runtime<Component>` wrapper in `packages/extensions/src/slots/RuntimeAddedSlots.tsx`, the component's export wrapped with `withRuntimeWrapper`, the slot added to the store's slot list and docs, the module registry regenerated. Refuses server components (`async`, server-only imports): a slot is filled in the browser. Nothing is committed: review the diff in the store, commit it there, rebuild the webstore, then `npx znode eject <Component>`. `add slot` (with a space) works too |
+| | `npx znode eject <Name> [--force]` | `<Name>` is the component or its slot (`ProductBasicInfo` or `product.basicInfo`). Copy the store's component into `src/components/<Name>.tsx` (imports turned into store aliases, runtime wrapper removed) and register it in `src/browser.tsx` under its slot; prints any npm package the copy needs. The copy is yours: store fixes no longer reach it |
 
 The plugin folder is taken from: the command's argument, else the `RUNTIME_PLUGINS_DIR` environment variable, else
 `znode.local.json`.

package/lib/znode-package.mjs

@@ -17,6 +17,9 @@
 //   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
+//                                                (<Name> is the component or its slot name)
+//   znode add-slot <Component> <area.name> [--dry-run] [--file <f>]   a slot around a store component, written into
+//                                                the linked store's source (base developers; review and commit there)
 //
 // A package is a folder with znode-package.json (README.md shows a whole project, as create-znode-plugin makes it):
 // {
@@ -697,8 +700,38 @@ const EJECT_SLOTS = {
   RuntimeShippingOptions: "checkout.shippingOptions",
 };
 
+// the slot each store wrapper renders: every `export function Runtime<X>` in packages/extensions/src/slots with the first
+// <RuntimeSlot name="…"> in its body (so a slot added with `znode add-slot` is ejectable with no SDK release); the
+// hand-kept EJECT_SLOTS above fill in for a store that predates this
+function storeWrapperSlots(root) {
+  const slots = { ...EJECT_SLOTS };
+  const dir = path.join(root, "packages/extensions/src/slots");
+  if (!fs.existsSync(dir)) return slots;
+  for (const entry of fs.readdirSync(dir)) {
+    if (!/\.tsx$/.test(entry)) continue;
+    const text = fs.readFileSync(path.join(dir, entry), "utf8");
+    const starts = [...text.matchAll(/export\s+function\s+(Runtime\w+)/g)];
+    starts.forEach((m, i) => {
+      const body = text.slice(m.index, i + 1 < starts.length ? starts[i + 1].index : undefined);
+      // the first slot that is handed the component as children (<RuntimeSlot name="…">…{children}…</RuntimeSlot>); a
+      // layout slot (self-closing, the base rendered hidden beside it) cannot take an ejected copy
+      for (const open of body.matchAll(/<RuntimeSlot\s+name=["']([\w.]+)["']/g)) {
+        const rest = body.slice(open.index + open[0].length);
+        const close = rest.indexOf("</RuntimeSlot>");
+        const next = rest.indexOf("<RuntimeSlot");
+        if (close >= 0 && (next < 0 || close < next) && /\{\s*children\s*\}/.test(rest.slice(0, close))) {
+          if (!slots[m[1]]) slots[m[1]] = open[1];
+          break;
+        }
+      }
+    });
+  }
+  return slots;
+}
+
 // every withRuntimeWrapper(<Wrapper>, <Base>, "<Name>") in the store's base components, with the slot it fills
 function ejectableComponents(root) {
+  const EJECT_SLOTS = storeWrapperSlots(root);
   const found = [];
   const walk = (dir) => {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -748,8 +781,13 @@ function eject(name, force) {
     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 c = components.find((item) => item.name.toLowerCase() === name.toLowerCase() || item.slot.toLowerCase() === name.toLowerCase());
+  if (!c)
+    fail(
+      `${name} cannot be ejected: no store component with that name or slot hands itself over to a slot.\n` +
+        `  znode eject                      lists the ones that can (component name or slot name both work)\n` +
+        `  znode add-slot ${/^[A-Z]/.test(name) ? name : "<Component>"} <area.name>   adds a slot for a store component (edits the linked store's source)`
+    );
 
   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`);
@@ -839,6 +877,170 @@ function eject(name, force) {
   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}.`);
 }
 
+// ---- add-slot: a runtime slot around a store component, written into the linked store's source ------------------
+// `znode add-slot <Component> <area.name>` does in the store what a base developer did by hand for product.basicInfo:
+// a Runtime<Component> wrapper (packages/extensions/src/slots/RuntimeAddedSlots.tsx) that renders <RuntimeSlot name>
+// with the component's props and the component itself as children, and the component's export wrapped with
+// withRuntimeWrapper, so every place that renders it gets the slot. It edits source only (never .next, never git):
+// review the diff, commit it through the store's own flow, rebuild the webstore; then `znode eject <Component>` works.
+const ADDED_SLOTS_FILE = "packages/extensions/src/slots/RuntimeAddedSlots.tsx";
+const SLOT_NAME = /^[a-z][A-Za-z0-9]*(\.[a-z][A-Za-z0-9]*)+$/;
+
+function storeSourceFiles(root) {
+  const files = [];
+  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" && !entry.name.startsWith("__")) walk(file);
+      } else if (/\.tsx$/.test(entry.name) && !/\.(test|spec|stories)\.tsx$/.test(entry.name)) files.push(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 files;
+}
+
+function addSlot(name, slot, { dryRun, file: chosen }) {
+  const usage = "usage: znode add-slot <Component> <area.name> [--dry-run] [--file <store file>]   e.g. znode add-slot ProductBasicInfo product.basicInfo";
+  if (!name || !slot) fail(usage);
+  if (!/^[A-Z]\w*$/.test(name)) fail(`"${name}" is not a component name (PascalCase, e.g. ProductDetails)\n${usage}`);
+  if (!SLOT_NAME.test(slot)) fail(`"${slot}" is not a slot name: area.name in camelCase, e.g. product.details`);
+  const store = linkedStore(path.resolve("."));
+  if (!store) fail("not linked to a store: run it in a package linked with npm run link-store -- <store repo> (add-slot edits that store's source)");
+  const root = store.root;
+  const rel = (file) => path.relative(root, file).split(path.sep).join("/");
+
+  // the slot must be new
+  const slotsDir = path.join(root, "packages/extensions/src/slots");
+  if (!fs.existsSync(slotsDir)) fail(`${rel(slotsDir)} not found: this store has no runtime slots (packages/extensions)`);
+  const wrapperSlots = storeWrapperSlots(root);
+  const taken = Object.entries(wrapperSlots).find(([, value]) => value === slot);
+  if (taken) fail(`slot "${slot}" already exists (${taken[0]}); znode eject lists what it hands over`);
+  const wrapper = `Runtime${name}`;
+  if (wrapperSlots[wrapper] || fs.readdirSync(slotsDir).some((f) => new RegExp(`export\\s+function\\s+${wrapper}\\b`).test(fs.readFileSync(path.join(slotsDir, f), "utf8"))))
+    fail(`${wrapper} already exists in ${rel(slotsDir)}: ${name} already has a slot (znode eject lists it)`);
+
+  // the file that defines the component
+  const DEFINES = new RegExp(`^(export\\s+(?:default\\s+)?)?(async\\s+)?function\\s+${name}\\s*[(<]|^(export\\s+)?const\\s+${name}\\s*(?::[^=]+)?=\\s*(async\\b)?`, "m");
+  let candidates = chosen ? [path.resolve(root, chosen)] : storeSourceFiles(root).filter((f) => DEFINES.test(fs.readFileSync(f, "utf8")));
+  if (chosen && !fs.existsSync(candidates[0])) fail(`${chosen} not found in ${root}`);
+  if (candidates.length > 1) {
+    const named = candidates.filter((f) => path.basename(f, ".tsx") === name);
+    if (named.length === 1) candidates = named;
+    else fail(`${name} is defined in more than one store file; pick one with --file:\n  ${candidates.map(rel).join("\n  ")}`);
+  }
+  if (!candidates.length) fail(`no ${name} component found in packages/base-components/src or packages/page-builder/src (only .tsx components can get a slot)`);
+  const target = candidates[0];
+  let source = fs.readFileSync(target, "utf8");
+  const def = source.match(DEFINES);
+  if (!def) fail(`${rel(target)} does not define ${name} as a function or const component`);
+
+  // only a client-renderable component: a slot is filled in the browser
+  if (new RegExp(`withRuntimeWrapper\\([^)]*["']${name}["']`).test(source)) fail(`${name} is already wrapped (${rel(target)}): it has a slot, znode eject lists it`);
+  if (def[2] || def[4])
+    fail(
+      `${name} is an async server component (${rel(target)}): a runtime slot is filled in the browser, so it cannot wrap a server component.\n` +
+        `  Add the slot to a client component it renders instead (e.g. its ProductBasicInfo), or split ${name} into a server part (data) and a client part (UI) and add the slot to the client part.`
+    );
+  const serverImport = source.match(/^\s*import\b[^;]*["'](server-only|next\/headers|fs|node:fs)["']/m);
+  if (serverImport) fail(`${name} imports ${serverImport[1]} (${rel(target)}): it runs on the server only, so a browser slot cannot wrap it`);
+
+  // wrap the export: <Name>Base is the component, <Name> is the wrapped one every caller already imports
+  const baseName = `${name}Base`;
+  if (new RegExp(`\\b${baseName}\\b`).test(source)) fail(`${rel(target)} already has a ${baseName}: wrap it by hand`);
+  const wrapped = `withRuntimeWrapper(${wrapper}, ${baseName}, "${name}")`;
+  const comment = `// runtime packages render around it through the slot "${slot}" (znode add-slot); with none, it renders as it is`;
+  if (/^export\s+default\s+/.test(def[0])) {
+    source = source.replace(def[0], def[0].replace(/^export\s+default\s+/, "").replace(name, baseName));
+    source = source.trimEnd() + `\n\n${comment}\nconst ${name} = ${wrapped};\n\nexport default ${name};\n`;
+  } else if (def[1] || def[3]) {
+    source = source.replace(def[0], def[0].replace(/^export\s+/, "").replace(name, baseName));
+    source = source.trimEnd() + `\n\n${comment}\nexport const ${name} = ${wrapped};\n`;
+  } else {
+    // defined, exported later (export default Name; / export { Name }): the wrapped const goes right before that export
+    source = source.replace(def[0], def[0].replace(name, baseName));
+    const exportAt = source.search(new RegExp(`^export\\s+(default\\s+${name}\\b|\\{[^}]*\\b${name}\\b)`, "m"));
+    const line = `${comment}\nconst ${name} = ${wrapped};\n\n`;
+    source = exportAt >= 0 ? source.slice(0, exportAt) + line + source.slice(exportAt) : source.trimEnd() + `\n\n${line}`;
+  }
+  // statics set on the component belong to the base (they run before the wrapped const exists)
+  source = source.replace(new RegExp(`\\b${name}\\.(displayName|defaultProps|propTypes)\\b`, "g"), `${baseName}.$1`);
+  const imports = [`import { withRuntimeWrapper } from "@znode/extensions/slots/with-runtime-wrapper";`, `import { ${wrapper} } from "@znode/extensions/slots/RuntimeAddedSlots";`].filter(
+    (line) => !(line.includes("withRuntimeWrapper }") && /import\s*\{[^}]*\bwithRuntimeWrapper\b/.test(source))
+  );
+  const directive = source.match(/^\s*["']use (client|server)["'];?\s*\n/);
+  const at = directive ? directive[0].length : 0;
+  source = source.slice(0, at) + (directive ? "\n" : "") + imports.join("\n") + "\n" + (directive ? "" : "\n") + source.slice(at).replace(/^\n+/, directive ? "" : "");
+
+  // the wrapper
+  const addedFile = path.join(root, ADDED_SLOTS_FILE);
+  const addedBefore = fs.existsSync(addedFile) ? fs.readFileSync(addedFile, "utf8") : null;
+  let added =
+    addedBefore ??
+    `"use client";\n\n// Slots added with \`znode add-slot <Component> <area.name>\` (znode-plugin): each Runtime<Component> renders the slot\n// around the store component (withRuntimeWrapper where the component is defined), with the component's props and the\n// component itself as children. With no runtime package for the slot, the component renders as it is.\n\nimport { ReactNode } from "react";\nimport { RuntimeSlot } from "../client/RuntimeSlot";\n`;
+  added =
+    added.trimEnd() +
+    `\n\n/** ${slot}: the store's ${name} (children), with every prop it gets. Added with \`znode add-slot ${name} ${slot}\` (${new Date().toISOString().slice(0, 10)}). */\n` +
+    `export function ${wrapper}({ children, ...props }: Readonly<Record<string, unknown> & { children?: ReactNode }>) {\n` +
+    `  return (\n    <RuntimeSlot name="${slot}" props={props}>\n      {children}\n    </RuntimeSlot>\n  );\n}\n`;
+
+  const changes = [
+    { file: target, before: fs.readFileSync(target, "utf8"), after: source },
+    { file: addedFile, before: addedBefore, after: added },
+  ];
+  const warnings = [];
+
+  // the slot list in the SDK types of the store (packages/extensions/src/types.ts), when it has one
+  const typesFile = path.join(root, "packages/extensions/src/types.ts");
+  if (fs.existsSync(typesFile)) {
+    const before = fs.readFileSync(typesFile, "utf8");
+    const lines = before.split("\n");
+    const start = lines.findIndex((line) => /^\s*\/\/\s*Slots\s*\(/.test(line));
+    if (start >= 0) {
+      let end = start + 1;
+      while (end < lines.length && /^\s*\/\/\s{3,}/.test(lines[end])) end++;
+      lines.splice(end, 0, `//   ${slot.padEnd(20)} the store's ${name} itself (children)  props: every prop ${name} gets (znode add-slot)`);
+      changes.push({ file: typesFile, before, after: lines.join("\n") });
+    } else warnings.push(`${rel(typesFile)}: no "// Slots (" comment found; add "${slot}" to the slot list yourself`);
+  }
+  // the slot table in docs/RUNTIME_EXTENSIONS_AGENTS.md, when it has one
+  const docsFile = path.join(root, "docs/RUNTIME_EXTENSIONS_AGENTS.md");
+  if (fs.existsSync(docsFile)) {
+    const before = fs.readFileSync(docsFile, "utf8");
+    const lines = before.split("\n");
+    let row = lines.findIndex((line) => line.startsWith("| `product.card`"));
+    if (row >= 0) {
+      while (row + 1 < lines.length && lines[row + 1].startsWith("|")) row++;
+      lines.splice(row + 1, 0, `| \`${slot}\` | \`${wrapper}\` (\`${ADDED_SLOTS_FILE.replace("packages/extensions/src/", "")}\`) | \`${rel(target).replace(/^packages\/[\w-]+\/src\//, "").replace(/\.tsx$/, "")}\` (its children: the component itself) | every ${name} prop; keep \`children\`, wrap it, or render a copy instead (\`znode eject ${name}\`) |`);
+      changes.push({ file: docsFile, before, after: lines.join("\n") });
+    } else warnings.push(`${rel(docsFile)}: slot table not found; add a "${slot}" row yourself`);
+  }
+
+  console.log(`${dryRun ? "would add" : "adding"} slot "${slot}" around ${name} (${rel(target)}) in ${root}\n`);
+  for (const { file, before, after } of changes) {
+    const old = new Set((before || "").split("\n"));
+    const added = after.split("\n").filter((line) => !old.has(line));
+    console.log(`${before === null ? "new " : "edit"} ${rel(file)}`);
+    for (const line of added) console.log(`  + ${line}`);
+  }
+  if (dryRun) {
+    console.log("\n--dry-run: nothing written. Run it again without --dry-run to write these changes.");
+    return;
+  }
+  for (const { file, after } of changes) fs.writeFileSync(file, after);
+
+  // the store's module registry, when the store generates one (the ejected copy's imports are checked against it)
+  const registry = path.join(root, "scripts/gen-store-module-registry.mjs");
+  if (fs.existsSync(registry)) spawnSync(process.execPath, [registry], { cwd: root, stdio: "inherit" });
+  for (const warning of warnings) console.log(`warning ${warning}`);
+  console.log(
+    `\nDone (the store's source only: nothing committed, .next untouched). Next:\n` +
+      `  1. review the diff in ${root} (git diff) and commit it through the store's own flow (hooks, review: it edits base components)\n` +
+      `  2. rebuild / restart the webstore so it renders the slot\n` +
+      `  3. here: npx znode eject ${name}   (or fill "${slot}" in src/browser.tsx with a component of your own)`
+  );
+}
+
 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
@@ -858,6 +1060,14 @@ if (command === "eject") {
   eject(args.find((arg, index) => index > 0 && !arg.startsWith("--")), args.includes("--force"));
   process.exit(0);
 }
+if (command === "add-slot" || (command === "add" && args[1] === "slot")) {
+  const rest = args.slice(command === "add" ? 2 : 1).filter((arg) => arg !== "--");
+  const fileAt = rest.indexOf("--file");
+  const file = fileAt >= 0 ? rest[fileAt + 1] : undefined;
+  const positional = rest.filter((arg, index) => !arg.startsWith("--") && !(fileAt >= 0 && index === fileAt + 1));
+  addSlot(positional[0], positional[1], { dryRun: rest.includes("--dry-run"), file });
+  process.exit(0);
+}
 if (command === "link-store") {
   if (!target) fail("usage: znode link-store <storeRepoDir> [projectDir]");
   linkStore(target, args[2]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "znode-plugin",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Build, check, pack and deploy Znode runtime plugins and themes: the SDK behind every create-znode-plugin project.",
   "license": "UNLICENSED",
   "type": "module",