@feeef.dev/cli 0.2.0

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

@@ -0,0 +1,377 @@
+/**
+ * Build a folder-based template source tree into Lithium TemplateData (data.json).
+ *
+ * Resolves `shared/components/*` placements (`$ref: "shared.foo"`) at compile time
+ * so every page that references the same shared id stays design-consistent.
+ *
+ * Components may be:
+ * - Flat page-level: `pages/<page>/components/hero.tsx` → published as `sections.main`
+ * - Legacy sections: `pages/<page>/sections/<id>/components/…`
+ * - Flat or folder entries under any `components/` dir (`hero.tsx` or `hero/component.tsx`)
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { validateTemplateData } from "./validate.mjs";
+import {
+  loadSharedCatalog,
+  resolveSharedInTree,
+  sharedIdFromComponent,
+} from "./shared.mjs";
+import { buildSchemaLibrary } from "./library.mjs";
+import { buildThemeI18n, writeLocaleFiles } from "./locales.mjs";
+import { compileComponentSource } from "./compile-component.mjs";
+import {
+  componentIdFromPath,
+  listComponentEntries,
+  loadComponentMeta,
+  isFlatComponentFile,
+} from "./component-meta.mjs";
+import { buildPackagedSchema } from "./theme-schema.mjs";
+
+/**
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function listDirs(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+    .map((d) => d.name)
+    .sort();
+}
+
+/**
+ * @param {string} filePath
+ * @returns {any}
+ */
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+/**
+ * Read one component entry from disk (does not expand shared refs).
+ * Meta: `export const meta` in .tsx/.jsx, or legacy .json / component.json.
+ * Nested slots/children only apply to folder entries.
+ * @param {string} root Absolute folder or flat file path
+ * @param {string[]} fileStack
+ * @returns {Record<string, any>}
+ */
+function readComponentRaw(root, fileStack) {
+  const loaded = loadComponentMeta(root);
+  const track = loaded.jsonPath || loaded.entry || root;
+  fileStack.push(track);
+  const meta = loaded.meta;
+  fileStack.pop();
+
+  /** @type {Record<string, any>} */
+  const component = { ...meta };
+  delete component.order;
+  delete component.$schema;
+
+  const compiled = compileComponentSource(root);
+  if (compiled) {
+    component.code = compiled.code;
+  }
+
+  // Flat leaves cannot host children/slots folders.
+  if (isFlatComponentFile(root)) {
+    return component;
+  }
+
+  const childrenDir = path.join(root, "children");
+  if (fs.existsSync(childrenDir)) {
+    const childEntries = listComponentEntries(childrenDir);
+    if (childEntries.length > 0) {
+      component.children = childEntries.map((d) =>
+        readComponentRaw(d, fileStack),
+      );
+    }
+  }
+
+  const slotsDir = path.join(root, "slots");
+  /** @type {Record<string, any[]>} */
+  const slotsFromDirs = {};
+  if (fs.existsSync(slotsDir)) {
+    for (const slotId of listDirs(slotsDir)) {
+      const slotChildren = listComponentEntries(path.join(slotsDir, slotId));
+      slotsFromDirs[slotId] = slotChildren.map((d) =>
+        readComponentRaw(d, fileStack),
+      );
+    }
+  }
+
+  const emptySlotsPath = path.join(root, "slots.empty.json");
+  /** @type {Record<string, any[]>} */
+  let emptySlots = {};
+  if (fs.existsSync(emptySlotsPath)) {
+    emptySlots = readJson(emptySlotsPath);
+  }
+
+  if (
+    Object.keys(slotsFromDirs).length > 0 ||
+    Object.keys(emptySlots).length > 0
+  ) {
+    component.slots = { ...emptySlots, ...slotsFromDirs };
+  }
+
+  return component;
+}
+
+/**
+ * @param {string} srcDir
+ * @returns {Map<string, Record<string, any>>}
+ */
+function buildSharedCatalog(srcDir) {
+  const sharedRoot = path.join(srcDir, "shared", "components");
+  /** @type {Map<string, Record<string, any>>} */
+  const catalog = new Map();
+  if (!fs.existsSync(sharedRoot)) return catalog;
+
+  const fileStack = [];
+  const entries = listComponentEntries(sharedRoot);
+  const ids = entries.map((p) => componentIdFromPath(p));
+  for (let i = 0; i < entries.length; i++) {
+    catalog.set(ids[i], readComponentRaw(entries[i], fileStack));
+  }
+
+  // Expand nested shared refs inside library definitions.
+  const resolving = new Set();
+  for (const id of ids) {
+    catalog.set(
+      id,
+      resolveSharedInTree(
+        structuredClone(catalog.get(id)),
+        catalog,
+        resolving,
+        `shared/${id}`,
+      ),
+    );
+  }
+  return catalog;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.srcDir
+ * @param {string} [opts.outPath]
+ * @param {boolean} [opts.write]
+ */
+export function buildTemplate({ srcDir, outPath, write = true }) {
+  if (!fs.existsSync(srcDir)) {
+    throw new Error(`Source not found: ${srcDir}`);
+  }
+
+  const manifestPath = path.join(srcDir, "feeef.template.json");
+  /** @type {Record<string, any>} */
+  let manifest = {};
+  if (fs.existsSync(manifestPath)) {
+    manifest = readJson(manifestPath);
+  }
+
+  const propsPath = path.join(srcDir, "props.json");
+  const props = fs.existsSync(propsPath) ? readJson(propsPath) : undefined;
+
+  const sharedCatalog = buildSharedCatalog(srcDir);
+  const resolving = new Set();
+
+  const pagesDir = path.join(srcDir, "pages");
+  const pageIdsFromDisk = listDirs(pagesDir);
+  const pageIds =
+    Array.isArray(manifest.pages) && manifest.pages.length > 0
+      ? manifest.pages.filter((id) => pageIdsFromDisk.includes(id))
+      : pageIdsFromDisk;
+
+  for (const id of pageIdsFromDisk) {
+    if (!pageIds.includes(id)) pageIds.push(id);
+  }
+
+  /** @type {Record<string, any>} */
+  const pages = {};
+  const fileStack = [];
+  let sharedPlacementCount = 0;
+
+  for (const pageId of pageIds) {
+    const pageDir = path.join(pagesDir, pageId);
+    const pageJsonPath = path.join(pageDir, "page.json");
+    let pageProps = {};
+    if (fs.existsSync(pageJsonPath)) {
+      const pageJson = readJson(pageJsonPath);
+      pageProps =
+        pageJson.props && typeof pageJson.props === "object"
+          ? pageJson.props
+          : pageJson;
+    }
+
+    /** @type {Record<string, any>} */
+    const sections = {};
+    const pageComponentsDir = path.join(pageDir, "components");
+    const sectionsDir = path.join(pageDir, "sections");
+    const flatEntries = listComponentEntries(pageComponentsDir);
+
+    /** Count legacy section component entries (any section with ≥1 component). */
+    let legacyComponentCount = 0;
+    const sectionIds = listDirs(sectionsDir);
+    for (const sectionId of sectionIds) {
+      legacyComponentCount += listComponentEntries(
+        path.join(sectionsDir, sectionId, "components"),
+      ).length;
+    }
+
+    if (flatEntries.length > 0 && legacyComponentCount > 0) {
+      throw new Error(
+        `Page "${pageId}" has both pages/${pageId}/components/ and pages/${pageId}/sections/…/components/. ` +
+          `Use one layout: flat page components (→ sections.main) or legacy sections folders.`,
+      );
+    }
+
+    if (flatEntries.length > 0) {
+      sections.main = {
+        components: flatEntries.map((entryPath) => {
+          const raw = readComponentRaw(entryPath, fileStack);
+          if (sharedIdFromComponent(raw)) sharedPlacementCount += 1;
+          return resolveSharedInTree(
+            raw,
+            sharedCatalog,
+            resolving,
+            `${pageId}/main/${componentIdFromPath(entryPath)}`,
+          );
+        }),
+      };
+    } else {
+      for (const sectionId of sectionIds) {
+        const componentsDir = path.join(sectionsDir, sectionId, "components");
+        const componentEntries = listComponentEntries(componentsDir);
+        sections[sectionId] = {
+          components: componentEntries.map((entryPath) => {
+            const raw = readComponentRaw(entryPath, fileStack);
+            if (sharedIdFromComponent(raw)) sharedPlacementCount += 1;
+            return resolveSharedInTree(
+              raw,
+              sharedCatalog,
+              resolving,
+              `${pageId}/${sectionId}/${componentIdFromPath(entryPath)}`,
+            );
+          }),
+        };
+      }
+    }
+
+    pages[pageId] = { props: pageProps, sections };
+  }
+
+  /** @type {Record<string, any>} */
+  const data = { pages };
+  if (props !== undefined) data.props = props;
+
+  const metaPath = path.join(srcDir, "feeef.template.json");
+  let defaultLocale;
+  if (fs.existsSync(metaPath)) {
+    try {
+      const meta = readJson(metaPath);
+      if (typeof meta.defaultLocale === "string") {
+        defaultLocale = meta.defaultLocale;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  const i18n = buildThemeI18n(srcDir, { defaultLocale });
+  if (i18n) {
+    data.i18n = i18n;
+  }
+
+  const issues = validateTemplateData(data, { srcDir });
+  const errors = issues.filter((i) => i.level === "error");
+  if (errors.length > 0) {
+    const msg = errors.map((e) => `  [${e.path}] ${e.message}`).join("\n");
+    throw new Error(`Template validation failed:\n${msg}`);
+  }
+
+  const libraryDoc = buildSchemaLibrary({
+    srcDir,
+    readComponentRaw,
+    resolveSharedInTree,
+    sharedCatalog,
+  });
+
+  const resolvedOut = outPath || path.join(srcDir, "dist", "data.json");
+  const libraryOut = path.join(path.dirname(resolvedOut), "schema.library.json");
+  const schemaOut = path.join(path.dirname(resolvedOut), "schema.json");
+
+  const { schema: packagedSchema, warnings: schemaWarnings } = buildPackagedSchema({
+    srcDir,
+    libraryDoc,
+  });
+  for (const w of schemaWarnings) {
+    issues.push({ level: "warning", path: "schema", message: w });
+  }
+
+  if (write) {
+    fs.mkdirSync(path.dirname(resolvedOut), { recursive: true });
+    fs.writeFileSync(
+      resolvedOut,
+      `${JSON.stringify(data, null, 2)}\n`,
+      "utf8",
+    );
+    fs.writeFileSync(
+      libraryOut,
+      `${JSON.stringify(libraryDoc, null, 2)}\n`,
+      "utf8",
+    );
+    if (i18n) {
+      writeLocaleFiles(path.dirname(resolvedOut), i18n);
+    }
+    fs.writeFileSync(
+      schemaOut,
+      `${JSON.stringify(packagedSchema, null, 2)}\n`,
+      "utf8",
+    );
+  }
+
+  return {
+    data,
+    library: libraryDoc,
+    schema: packagedSchema,
+    i18n,
+    outPath: resolvedOut,
+    libraryOutPath: libraryOut,
+    schemaOutPath: schemaOut,
+    warnings: issues.filter((i) => i.level === "warning"),
+    pageCount: Object.keys(pages).length,
+    componentCount: countComponents(data),
+    sharedCount: sharedCatalog.size,
+    sharedPlacementCount,
+    libraryCount: libraryDoc.components.length,
+    localeCount: i18n?.locales?.length ?? 0,
+  };
+}
+
+// Re-export for tests / CLI introspection
+export { loadSharedCatalog };
+
+/**
+ * @param {Record<string, any>} data
+ */
+function countComponents(data) {
+  let n = 0;
+  /** @param {any} c */
+  function walk(c) {
+    if (!c || typeof c !== "object") return;
+    n += 1;
+    if (Array.isArray(c.children)) c.children.forEach(walk);
+    if (c.slots && typeof c.slots === "object") {
+      for (const list of Object.values(c.slots)) {
+        if (Array.isArray(list)) list.forEach(walk);
+      }
+    }
+  }
+  for (const page of Object.values(data.pages || {})) {
+    for (const section of Object.values(page.sections || {})) {
+      (section.components || []).forEach(walk);
+    }
+  }
+  return n;
+}

package/vendor/template-kit/lib/compile-component.mjs

@@ -0,0 +1,188 @@
+/**
+ * Compile theme component source (JSX/TSX) into a react-live `code` string.
+ *
+ * - Plain `.jsx` without imports → returned as-is (legacy path).
+ * - `.tsx` and/or `import`/`export` → esbuild transpile + optional bundle.
+ * - `react` / `react-dom` stay external (injected by CustomLive scope).
+ * - Result always exposes top-level `function App` for react-live.
+ * - npm packages resolve from the theme root `node_modules` (walk up to
+ *   `feeef.template.json`).
+ *
+ * `root` may be a component folder (`…/hero/`) or a flat file (`…/hero.tsx`).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import {
+  isFlatComponentFile,
+  resolveComponentEntry,
+  stripMetaExport,
+} from "./component-meta.mjs";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * @returns {typeof import('esbuild') | null}
+ */
+function loadEsbuild() {
+  try {
+    return require("esbuild");
+  } catch {
+    try {
+      const here = path.dirname(fileURLToPath(import.meta.url));
+      const cliRoot = path.resolve(here, "../../..");
+      return createRequire(path.join(cliRoot, "package.json"))("esbuild");
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Find theme root (`feeef.template.json`) walking up from a component folder.
+ * @param {string} startDir
+ * @returns {string}
+ */
+export function findThemeRoot(startDir) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, "feeef.template.json"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.resolve(startDir);
+    dir = parent;
+  }
+}
+
+/**
+ * @param {string} source
+ */
+export function sourceNeedsCompile(source) {
+  return (
+    /^\s*import\s/m.test(source) ||
+    /^\s*export\s/m.test(source) ||
+    /:\s*[A-Za-z<{]/.test(source)
+  );
+}
+
+/**
+ * @param {string} root Absolute component folder or flat `.tsx`/`.jsx` file
+ * @returns {{ code: string, entry: string, bundled: boolean } | null}
+ */
+export function compileComponentSource(root) {
+  /** @type {string | null} */
+  let entry = null;
+  /** @type {string} */
+  let resolveDir;
+
+  if (isFlatComponentFile(root)) {
+    const ext = path.extname(root).toLowerCase();
+    if (ext === ".json") return null;
+    entry = root;
+    resolveDir = path.dirname(root);
+  } else {
+    entry = resolveComponentEntry(root);
+    resolveDir = root;
+  }
+  if (!entry) return null;
+
+  const source = stripMetaExport(
+    fs.readFileSync(entry, "utf8").replace(/\s+$/, ""),
+  );
+  const isTsx = entry.endsWith(".tsx");
+  const hasModuleSyntax =
+    /^\s*import\s/m.test(source) || /^\s*export\s/m.test(source);
+
+  if (!isTsx && !hasModuleSyntax) {
+    return { code: source, entry, bundled: false };
+  }
+
+  const esbuild = loadEsbuild();
+  if (!esbuild) {
+    throw new Error(
+      `Component ${path.basename(root)} uses TypeScript or imports, but esbuild is not installed. ` +
+        `Install it in the Feeef CLI package (or the theme) and retry.`,
+    );
+  }
+
+  const themeRoot = findThemeRoot(resolveDir);
+  const themeNodeModules = path.join(themeRoot, "node_modules");
+
+  if (!hasModuleSyntax) {
+    const result = esbuild.transformSync(source, {
+      loader: "tsx",
+      format: "esm",
+      target: "es2018",
+      jsx: "preserve",
+    });
+    let code = result.code.replace(/\s+$/, "");
+    code = code.replace(/^\s*export\s+/gm, "");
+    if (!/\bfunction\s+App\s*\(/.test(code)) {
+      throw new Error(
+        `${path.relative(process.cwd(), entry)}: expected function App() after transpile`,
+      );
+    }
+    return { code, entry, bundled: false };
+  }
+
+  let stdinContents = source;
+  if (
+    /\bfunction\s+App\s*\(/.test(source) &&
+    !/\bexport\s+(async\s+)?function\s+App\b/.test(source) &&
+    !/\bexport\s*\{[^}]*\bApp\b/.test(source)
+  ) {
+    stdinContents = `${source}\nexport { App };\n`;
+  }
+
+  /** @type {import('esbuild').BuildOptions} */
+  const buildOpts = {
+    stdin: {
+      contents: stdinContents,
+      resolveDir,
+      sourcefile: path.basename(entry),
+      loader: isTsx ? "tsx" : "jsx",
+    },
+    bundle: true,
+    write: false,
+    format: "iife",
+    globalName: "__FeeefThemeMod",
+    platform: "browser",
+    target: "es2018",
+    jsx: "transform",
+    absWorkingDir: themeRoot,
+    external: [
+      "react",
+      "react-dom",
+      "react/jsx-runtime",
+      "react/jsx-dev-runtime",
+    ],
+    logLevel: "silent",
+  };
+
+  if (fs.existsSync(themeNodeModules)) {
+    buildOpts.nodePaths = [themeNodeModules];
+  }
+
+  const result = esbuild.buildSync(buildOpts);
+
+  const bundled = result.outputFiles?.[0]?.text;
+  if (!bundled) {
+    throw new Error(`esbuild produced no output for ${entry}`);
+  }
+
+  const code = `${bundled.replace(/\s+$/, "")}
+function App() {
+  var m = (typeof __FeeefThemeMod !== "undefined" && __FeeefThemeMod) || {};
+  var C = m.App || m.default;
+  if (typeof C !== "function") {
+    throw new Error("Bundled component did not export App");
+  }
+  return C.apply(this, arguments);
+}
+`;
+
+  return { code, entry, bundled: true };
+}