@feeef.dev/cli 0.2.0

package/vendor/template-kit/lib/paths.mjs

@@ -0,0 +1,84 @@
+/**
+ * Path + naming helpers for the Feeef template source tree.
+ *
+ * Folder names prefer `instanceId`; when missing we fall back to a stable
+ * slug from `title` / `type` plus a short hash so siblings never collide.
+ */
+
+import path from "node:path";
+import crypto from "node:crypto";
+
+/** Top-level component fields that live in `export const meta` / component.json. */
+export const COMPONENT_META_KEYS = [
+  "type",
+  "instanceId",
+  "title",
+  "propsSchema",
+  "slotsSchema",
+  "slotsLayout",
+  "props",
+  "refId",
+  "refVersion",
+];
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function slugify(value) {
+  const s = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return s || "component";
+}
+
+/**
+ * Stable short hash for collision-safe folder names.
+ * @param {string} input
+ */
+export function shortHash(input) {
+  return crypto.createHash("sha1").update(input).digest("hex").slice(0, 8);
+}
+
+/**
+ * @param {Record<string, any>} component
+ * @param {number} index
+ * @param {Set<string>} usedNames
+ */
+export function folderNameForComponent(component, index, usedNames) {
+  const base =
+    (component.instanceId && slugify(component.instanceId)) ||
+    (component.title && slugify(component.title)) ||
+    slugify(component.type || "component");
+
+  let name = base;
+  if (usedNames.has(name)) {
+    const id = component.instanceId || `${component.type || "c"}-${index}`;
+    name = `${base}-${shortHash(String(id))}`;
+  }
+  // Still colliding (rare) — append index.
+  let n = 2;
+  while (usedNames.has(name)) {
+    name = `${base}-${n++}`;
+  }
+  usedNames.add(name);
+  return name;
+}
+
+/**
+ * Resolve a path relative to cwd, expanding ~ is not needed for this kit.
+ * @param {string} p
+ */
+export function resolveFromCwd(p) {
+  return path.resolve(process.cwd(), p);
+}
+
+/**
+ * Pretty relative path for logs.
+ * @param {string} abs
+ */
+export function rel(abs) {
+  return path.relative(process.cwd(), abs) || ".";
+}

package/vendor/template-kit/lib/shared.mjs

@@ -0,0 +1,268 @@
+/**
+ * Theme-local shared component library (compile-time).
+ *
+ * Placements reference a shared definition with:
+ *   { "$ref": "shared.footer", "instanceId": "…", "props": { …overrides } }
+ * or shorthand:
+ *   { "shared": "footer", "instanceId": "…", "props": { … } }
+ *
+ * Build expands the ref into a full TemplateDataComponent (deep-merge props).
+ * This is the authoring-time twin of runtime `type:"reference"` (backend library).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { rel } from "./paths.mjs";
+import {
+  componentIdFromPath,
+  listComponentEntries,
+} from "./component-meta.mjs";
+
+/**
+ * Deep-merge plain objects. Arrays and scalars from `override` replace.
+ * @param {any} base
+ * @param {any} override
+ */
+export function deepMerge(base, override) {
+  if (override === undefined) {
+    return base === undefined ? undefined : structuredClone(base);
+  }
+  if (
+    override === null ||
+    typeof override !== "object" ||
+    Array.isArray(override)
+  ) {
+    return structuredClone(override);
+  }
+  if (base === null || typeof base !== "object" || Array.isArray(base)) {
+    return structuredClone(override);
+  }
+  /** @type {Record<string, any>} */
+  const out = structuredClone(base);
+  for (const [key, value] of Object.entries(override)) {
+    if (
+      value &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      out[key] &&
+      typeof out[key] === "object" &&
+      !Array.isArray(out[key])
+    ) {
+      out[key] = deepMerge(out[key], value);
+    } else {
+      out[key] = structuredClone(value);
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {Record<string, any>} component
+ * @returns {string | null}
+ */
+export function sharedIdFromComponent(component) {
+  if (!component || typeof component !== "object") return null;
+  if (typeof component.shared === "string" && component.shared.trim()) {
+    return component.shared.trim().replace(/^shared\./, "");
+  }
+  if (typeof component.$ref === "string" && component.$ref.trim()) {
+    const ref = component.$ref.trim();
+    if (ref.startsWith("shared.")) return ref.slice("shared.".length);
+    // Allow bare "$ref": "footer" only when paired with convention — prefer shared.
+    if (!ref.includes(".")) return ref;
+  }
+  return null;
+}
+
+/**
+ * Load every component under `<srcDir>/shared/components/` (flat or folder).
+ * @param {string} srcDir
+ * @param {(dir: string, fileStack: string[], ctx: { sharedCatalog: Map<string, any>, resolving: Set<string> }) => Record<string, any>} readComponentFn
+ * @returns {Map<string, Record<string, any>>}
+ */
+export function loadSharedCatalog(srcDir, readComponentFn) {
+  /** @type {Map<string, Record<string, any>>} */
+  const catalog = new Map();
+  const sharedRoot = path.join(srcDir, "shared", "components");
+  if (!fs.existsSync(sharedRoot)) return catalog;
+
+  const entries = listComponentEntries(sharedRoot);
+  const ids = entries.map((p) => componentIdFromPath(p));
+
+  const fileStack = [];
+  const resolving = new Set();
+
+  for (let i = 0; i < entries.length; i++) {
+    const id = ids[i];
+    const entryPath = entries[i];
+    // First pass: read without resolving nested shared (catalog incomplete).
+    catalog.set(
+      id,
+      readComponentFn(entryPath, fileStack, {
+        sharedCatalog: catalog,
+        resolving,
+        deferShared: true,
+      }),
+    );
+  }
+
+  // Second pass: resolve $ref inside shared definitions (composable shared).
+  for (const id of ids) {
+    const raw = catalog.get(id);
+    catalog.set(
+      id,
+      resolveSharedInTree(raw, catalog, resolving, `shared/${id}`),
+    );
+  }
+
+  return catalog;
+}
+
+/**
+ * Expand a placement that points at a shared id into a full component.
+ * @param {Record<string, any>} placement
+ * @param {Map<string, Record<string, any>>} catalog
+ * @param {Set<string>} resolving
+ * @param {string} pathHint
+ */
+export function resolveSharedPlacement(
+  placement,
+  catalog,
+  resolving,
+  pathHint = "component",
+) {
+  const id = sharedIdFromComponent(placement);
+  if (!id) return placement;
+
+  if (resolving.has(id)) {
+    throw new Error(
+      `Shared component cycle detected at ${pathHint} → shared.${id}`,
+    );
+  }
+  if (!catalog.has(id)) {
+    throw new Error(
+      `Unknown shared component "shared.${id}" at ${pathHint}. ` +
+        `Add shared/components/${id}/ or fix the $ref.`,
+    );
+  }
+
+  resolving.add(id);
+  const base = structuredClone(catalog.get(id));
+  resolving.delete(id);
+
+  const {
+    $ref: _ref,
+    shared: _shared,
+    order: _order,
+    $schema: _schema,
+    ...overrides
+  } = placement;
+
+  /** Fields that always come from the placement when present */
+  const instanceKeys = ["instanceId", "title", "refId", "refVersion"];
+
+  /** @type {Record<string, any>} */
+  const merged = { ...base };
+
+  for (const key of instanceKeys) {
+    if (Object.prototype.hasOwnProperty.call(overrides, key)) {
+      merged[key] = overrides[key];
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(overrides, "props")) {
+    merged.props = deepMerge(base.props || {}, overrides.props || {});
+  }
+
+  // Explicit slot / children overrides replace (not deep-merge trees).
+  if (Object.prototype.hasOwnProperty.call(overrides, "slots")) {
+    merged.slots = overrides.slots;
+  }
+  if (Object.prototype.hasOwnProperty.call(overrides, "children")) {
+    merged.children = overrides.children;
+  }
+
+  // Allow rare full overrides of schemas/code from placement (escape hatch).
+  for (const key of [
+    "type",
+    "code",
+    "propsSchema",
+    "slotsSchema",
+    "slotsLayout",
+  ]) {
+    if (
+      Object.prototype.hasOwnProperty.call(overrides, key) &&
+      overrides[key] !== undefined
+    ) {
+      merged[key] = overrides[key];
+    }
+  }
+
+  // Strip authoring-only keys from output.
+  delete merged.$ref;
+  delete merged.shared;
+  delete merged.$schema;
+  delete merged.order;
+
+  return merged;
+}
+
+/**
+ * Walk a component tree and expand any shared refs.
+ * @param {any} node
+ * @param {Map<string, Record<string, any>>} catalog
+ * @param {Set<string>} resolving
+ * @param {string} pathHint
+ */
+export function resolveSharedInTree(node, catalog, resolving, pathHint) {
+  if (!node || typeof node !== "object") return node;
+
+  let current = node;
+  if (sharedIdFromComponent(current)) {
+    current = resolveSharedPlacement(current, catalog, resolving, pathHint);
+  }
+
+  if (Array.isArray(current.children)) {
+    current.children = current.children.map((c, i) =>
+      resolveSharedInTree(c, catalog, resolving, `${pathHint}/children[${i}]`),
+    );
+  }
+  if (current.slots && typeof current.slots === "object") {
+    /** @type {Record<string, any[]>} */
+    const next = {};
+    for (const [slotId, list] of Object.entries(current.slots)) {
+      if (!Array.isArray(list)) {
+        next[slotId] = list;
+        continue;
+      }
+      next[slotId] = list.map((c, i) =>
+        resolveSharedInTree(
+          c,
+          catalog,
+          resolving,
+          `${pathHint}/slots/${slotId}[${i}]`,
+        ),
+      );
+    }
+    current.slots = next;
+  }
+  return current;
+}
+
+/**
+ * @param {string} srcDir
+ * @returns {string[]}
+ */
+export function listSharedIds(srcDir) {
+  const sharedRoot = path.join(srcDir, "shared", "components");
+  if (!fs.existsSync(sharedRoot)) return [];
+  return listComponentEntries(sharedRoot).map((p) => componentIdFromPath(p));
+}
+
+/**
+ * Human-readable path helper for errors.
+ * @param {string} abs
+ */
+export function sharedRel(abs) {
+  return rel(abs);
+}

package/vendor/template-kit/lib/theme-schema.mjs

@@ -0,0 +1,300 @@
+/**
+ * Theme-owned TemplateSchema: load overlay, merge Lithium built-ins, package.
+ *
+ * Overlay (preferred): `schema.ts` with `export const schema = … satisfies FeeefThemeSchema`
+ * Fallback: `schema.json`
+ *
+ * Lithium base resolution:
+ *   FEEEF_LITHIUM_SCHEMA → ../storefront/template/schema.json → vendored data/lithium-schema.json
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import vm from "node:vm";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { rel } from "./paths.mjs";
+import { attachLibraryToSchema } from "./library.mjs";
+
+const require = createRequire(import.meta.url);
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * @returns {typeof import('esbuild') | null}
+ */
+function loadEsbuild() {
+  try {
+    return require("esbuild");
+  } catch {
+    try {
+      const cliRoot = path.resolve(here, "../../..");
+      return createRequire(path.join(cliRoot, "package.json"))("esbuild");
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @returns {any}
+ */
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+/**
+ * Resolve Lithium built-in schema JSON path.
+ * @returns {string | null}
+ */
+export function resolveLithiumSchemaPath() {
+  const env = process.env.FEEEF_LITHIUM_SCHEMA?.trim();
+  if (env) {
+    const abs = path.isAbsolute(env) ? env : path.resolve(process.cwd(), env);
+    if (fs.existsSync(abs)) return abs;
+  }
+
+  // Monorepo: cli/vendor/template-kit/lib → cli → feeef.all → storefront
+  const monorepo = path.resolve(here, "../../../../storefront/template/schema.json");
+  if (fs.existsSync(monorepo)) return monorepo;
+
+  // Alternate: storefront/template-kit/lib → storefront/template/schema.json
+  const sfSibling = path.resolve(here, "../../template/schema.json");
+  if (fs.existsSync(sfSibling)) return sfSibling;
+
+  const vendored = path.join(here, "../data/lithium-schema.json");
+  if (fs.existsSync(vendored)) return vendored;
+
+  return null;
+}
+
+/**
+ * @returns {Record<string, any>}
+ */
+export function loadLithiumBaseSchema() {
+  const p = resolveLithiumSchemaPath();
+  if (!p) {
+    throw new Error(
+      "Lithium schema not found. Set FEEEF_LITHIUM_SCHEMA or ensure vendor/template-kit/data/lithium-schema.json exists.",
+    );
+  }
+  return readJson(p);
+}
+
+/**
+ * Evaluate `export const schema` from a .ts/.tsx file.
+ * @param {string} filePath
+ * @returns {Record<string, any>}
+ */
+function evaluateSchemaExport(filePath) {
+  const source = fs.readFileSync(filePath, "utf8");
+  if (!/\bexport\s+const\s+schema\b/.test(source)) {
+    throw new Error(
+      `${rel(filePath)}: expected \`export const schema\``,
+    );
+  }
+
+  const esbuild = loadEsbuild();
+  if (!esbuild) {
+    throw new Error(
+      `Found schema.ts but esbuild is not installed (needed to evaluate ${rel(filePath)})`,
+    );
+  }
+
+  const loader = filePath.endsWith(".tsx") ? "tsx" : "ts";
+  const transformed = esbuild.transformSync(source, {
+    loader,
+    format: "cjs",
+    target: "es2018",
+    logLevel: "silent",
+  });
+
+  const module = { exports: /** @type {Record<string, any>} */ ({}) };
+  const sandbox = {
+    module,
+    exports: module.exports,
+    require: () => ({}),
+    console,
+  };
+
+  try {
+    vm.runInNewContext(transformed.code, sandbox, { filename: filePath });
+  } catch (err) {
+    throw new Error(
+      `Failed to evaluate schema export in ${rel(filePath)}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const schema =
+    module.exports.schema ??
+    module.exports.default?.schema ??
+    module.exports.default;
+
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new Error(
+      `${rel(filePath)}: export const schema must be an object`,
+    );
+  }
+  return { ...schema };
+}
+
+/**
+ * Load theme overlay from schema.ts / schema.tsx / schema.json (or null).
+ * @param {string} srcDir
+ * @returns {Record<string, any> | null}
+ */
+export function loadThemeSchemaOverlay(srcDir) {
+  const ts = path.join(srcDir, "schema.ts");
+  const tsx = path.join(srcDir, "schema.tsx");
+  const json = path.join(srcDir, "schema.json");
+
+  if (fs.existsSync(ts)) return evaluateSchemaExport(ts);
+  if (fs.existsSync(tsx)) return evaluateSchemaExport(tsx);
+  if (fs.existsSync(json)) return readJson(json);
+  return null;
+}
+
+/**
+ * Structural checks on an overlay (throws on hard errors).
+ * @param {Record<string, any>} overlay
+ * @param {string} hint
+ */
+export function validateThemeSchemaOverlay(overlay, hint = "schema") {
+  if (!overlay || typeof overlay !== "object") {
+    throw new Error(`${hint}: overlay must be an object`);
+  }
+  if (overlay.pages !== undefined) {
+    if (!overlay.pages || typeof overlay.pages !== "object" || Array.isArray(overlay.pages)) {
+      throw new Error(`${hint}: pages must be an object map`);
+    }
+    for (const [pageId, page] of Object.entries(overlay.pages)) {
+      if (!page || typeof page !== "object") {
+        throw new Error(`${hint}: pages.${pageId} must be an object`);
+      }
+      if (
+        page.sections === undefined ||
+        typeof page.sections !== "object" ||
+        Array.isArray(page.sections)
+      ) {
+        throw new Error(`${hint}: pages.${pageId}.sections is required`);
+      }
+    }
+  }
+}
+
+/**
+ * Merge Lithium base + theme overlay.
+ *
+ * Theme wins for: name, version, schema, propsSchema, pages (when provided).
+ * components: { ...base.components, ...overlay.components }
+ *
+ * @param {Record<string, any>} base
+ * @param {Record<string, any> | null} overlay
+ * @param {{ name?: string, version?: string }} [manifest]
+ * @returns {Record<string, any>}
+ */
+export function mergeThemeSchema(base, overlay, manifest = {}) {
+  if (overlay) validateThemeSchemaOverlay(overlay, "theme schema");
+
+  /** @type {Record<string, any>} */
+  const out = {
+    ...base,
+    components: {
+      ...(base.components && typeof base.components === "object"
+        ? base.components
+        : {}),
+      ...(overlay?.components && typeof overlay.components === "object"
+        ? overlay.components
+        : {}),
+    },
+  };
+
+  // Identity: overlay → manifest → base
+  if (typeof overlay?.name === "string" && overlay.name.trim()) {
+    out.name = overlay.name.trim();
+  } else if (typeof manifest.name === "string" && manifest.name.trim()) {
+    out.name = manifest.name.trim();
+  }
+
+  if (typeof overlay?.version === "string" && overlay.version.trim()) {
+    out.version = overlay.version.trim();
+  } else if (typeof manifest.version === "string" && manifest.version.trim()) {
+    out.version = manifest.version.trim();
+  }
+
+  if (overlay) {
+    if (overlay.schema !== undefined) {
+      out.schema = overlay.schema;
+    }
+    if (overlay.propsSchema && typeof overlay.propsSchema === "object") {
+      out.propsSchema = overlay.propsSchema;
+    }
+    if (overlay.pages && typeof overlay.pages === "object") {
+      out.pages = overlay.pages;
+    }
+    // Forward-compat extras (except reserved merge keys)
+    for (const [k, v] of Object.entries(overlay)) {
+      if (
+        [
+          "name",
+          "version",
+          "schema",
+          "propsSchema",
+          "pages",
+          "components",
+          "library",
+        ].includes(k)
+      ) {
+        continue;
+      }
+      if (v !== undefined) out[k] = v;
+    }
+  }
+
+  if (!out.name) out.name = "theme";
+  if (!out.version) out.version = "0.1.0";
+  if (!out.schema) out.schema = "1.0";
+
+  return out;
+}
+
+/**
+ * Build packaged schema for dist/schema.json.
+ * @param {object} opts
+ * @param {string} opts.srcDir
+ * @param {{ components?: any[] }} [opts.libraryDoc]
+ * @returns {{ schema: Record<string, any>, overlay: Record<string, any> | null, warnings: string[] }}
+ */
+export function buildPackagedSchema({ srcDir, libraryDoc }) {
+  /** @type {string[]} */
+  const warnings = [];
+  /** @type {Record<string, any>} */
+  let manifest = {};
+  const manifestPath = path.join(srcDir, "feeef.template.json");
+  if (fs.existsSync(manifestPath)) {
+    try {
+      manifest = readJson(manifestPath);
+    } catch {
+      warnings.push("Could not parse feeef.template.json for schema name/version");
+    }
+  }
+
+  const base = loadLithiumBaseSchema();
+  const overlay = loadThemeSchemaOverlay(srcDir);
+  if (!overlay) {
+    warnings.push(
+      "No schema.ts / schema.json — using Lithium pages layout with manifest name/version",
+    );
+  }
+
+  let schema = mergeThemeSchema(base, overlay, {
+    name: typeof manifest.name === "string" ? manifest.name : undefined,
+    version: typeof manifest.version === "string" ? manifest.version : undefined,
+  });
+
+  if (libraryDoc) {
+    schema = attachLibraryToSchema(schema, libraryDoc);
+  }
+
+  return { schema, overlay, warnings };
+}