@feeef.dev/cli 0.2.0

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

@@ -0,0 +1,324 @@
+/**
+ * Unpack a Lithium TemplateData JSON blob into a folder-based source tree.
+ *
+ * Layout:
+ *   <out>/
+ *     feeef.template.json
+ *     props.json
+ *     pages/<pageId>/page.json
+ *     pages/<pageId>/components/          (main-only pages — preferred)
+ *       <name>.tsx | <name>.json | <name>/…
+ *     pages/<pageId>/sections/<sectionId>/components/  (legacy multi-section)
+ *       …
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  COMPONENT_META_KEYS,
+  folderNameForComponent,
+  rel,
+} from "./paths.mjs";
+import { formatMetaExport } from "./component-meta.mjs";
+
+const SCHEMA_ABS = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../schemas/component.schema.json",
+);
+
+/**
+ * @param {string} filePath
+ * @param {unknown} data
+ */
+function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} content
+ */
+function writeText(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  // Normalize trailing newline for clean git diffs.
+  const body = content.endsWith("\n") ? content : `${content}\n`;
+  fs.writeFileSync(filePath, body, "utf8");
+}
+
+/**
+ * Light cleanup so VS Code / tsc treat common marketplace helpers kindly.
+ * (e.g. local `function t(key, params)` is called with one arg everywhere.)
+ * @param {string} code
+ */
+function sanitizeComponentSourceForEditor(code) {
+  return code.replace(
+    /\bfunction\s+t\s*\(\s*([A-Za-z_$][\w$]*)\s*,\s*([A-Za-z_$][\w$]*)\s*\)/g,
+    "function t($1, $2?)",
+  );
+}
+
+/**
+ * Write one component (and nested slots/children).
+ * Leaf customs → `<name>.tsx`; leaf built-ins → `<name>.json`;
+ * nested trees → `<name>/` folder (legacy layout).
+ *
+ * @param {Record<string, any>} component
+ * @param {string} destPath Intended path without extension (`…/components/hero`)
+ * @param {number} order
+ * @param {{ files: number }} stats
+ */
+function writeComponent(component, destPath, order, stats) {
+  const children = component.children;
+  const hasChildFolders = Array.isArray(children) && children.length > 0;
+
+  const slots = component.slots;
+  const slotEntries =
+    slots && typeof slots === "object" && !Array.isArray(slots)
+      ? Object.entries(slots)
+      : [];
+  const hasSlotFolders = slotEntries.some(
+    ([, list]) => Array.isArray(list) && list.length > 0,
+  );
+  const needsFolder = hasChildFolders || hasSlotFolders;
+
+  const schemaBase = needsFolder ? destPath : path.dirname(destPath);
+  /** @type {Record<string, any>} */
+  const meta = {
+    $schema: path.relative(schemaBase, SCHEMA_ABS).split(path.sep).join("/"),
+    order,
+  };
+  for (const key of COMPONENT_META_KEYS) {
+    // Preserve explicit nulls (Dawn/editor blobs often include them).
+    if (Object.prototype.hasOwnProperty.call(component, key)) {
+      meta[key] = component[key];
+    }
+  }
+  // Preserve unknown top-level keys (forward-compat) except tree/code.
+  for (const [key, value] of Object.entries(component)) {
+    if (
+      key === "code" ||
+      key === "children" ||
+      key === "slots" ||
+      key === "order" ||
+      COMPONENT_META_KEYS.includes(key)
+    ) {
+      continue;
+    }
+    if (value !== undefined) meta[key] = value;
+  }
+
+  // Nested trees: non-empty → folders; empty/null → keep on meta for round-trip.
+  if (Object.prototype.hasOwnProperty.call(component, "children")) {
+    if (hasChildFolders) {
+      delete meta.children;
+    } else {
+      meta.children = children ?? null;
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(component, "slots")) {
+    if (hasSlotFolders) {
+      delete meta.slots;
+    } else {
+      meta.slots = slots ?? null;
+    }
+  }
+
+  const hasCode =
+    typeof component.code === "string" && component.code.trim().length > 0;
+
+  if (!needsFolder) {
+    // Flat leaf: hero.tsx or hero.json
+    if (hasCode) {
+      const metaForExport = { ...meta };
+      delete metaForExport.$schema;
+      const tsx = `${formatMetaExport(metaForExport)}${sanitizeComponentSourceForEditor(component.code)}`;
+      writeText(`${destPath}.tsx`, tsx);
+      stats.files += 1;
+    } else {
+      if (Object.prototype.hasOwnProperty.call(component, "code")) {
+        meta.code = component.code ?? null;
+      }
+      writeJson(`${destPath}.json`, meta);
+      stats.files += 1;
+    }
+    return;
+  }
+
+  // Folder layout for nested children/slots
+  const dir = destPath;
+  fs.mkdirSync(dir, { recursive: true });
+
+  if (hasCode) {
+    const metaForExport = { ...meta };
+    delete metaForExport.$schema;
+    const tsx = `${formatMetaExport(metaForExport)}${sanitizeComponentSourceForEditor(component.code)}`;
+    writeText(path.join(dir, "component.tsx"), tsx);
+    stats.files += 1;
+  } else {
+    if (Object.prototype.hasOwnProperty.call(component, "code")) {
+      meta.code = component.code ?? null;
+    }
+    writeJson(path.join(dir, "component.json"), meta);
+    stats.files += 1;
+  }
+
+  if (hasChildFolders) {
+    const used = new Set();
+    children.forEach((child, i) => {
+      if (!child || typeof child !== "object") return;
+      const name = folderNameForComponent(child, i, used);
+      writeComponent(child, path.join(dir, "children", name), i, stats);
+    });
+  }
+
+  if (hasSlotFolders) {
+    for (const [slotId, list] of slotEntries) {
+      if (!Array.isArray(list) || list.length === 0) {
+        continue;
+      }
+      const used = new Set();
+      list.forEach((child, i) => {
+        if (!child || typeof child !== "object") return;
+        const name = folderNameForComponent(child, i, used);
+        writeComponent(
+          child,
+          path.join(dir, "slots", slotId, name),
+          i,
+          stats,
+        );
+      });
+    }
+    const emptySlots = {};
+    let anyEmpty = false;
+    for (const [slotId, list] of slotEntries) {
+      if (!Array.isArray(list) || list.length === 0) {
+        emptySlots[slotId] = Array.isArray(list) ? list : [];
+        anyEmpty = true;
+      }
+    }
+    if (anyEmpty) {
+      writeJson(path.join(dir, "slots.empty.json"), emptySlots);
+      stats.files += 1;
+    }
+  }
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.inputPath Absolute path to data.json
+ * @param {string} opts.outDir Absolute output directory
+ * @param {boolean} [opts.force] Wipe outDir if it exists
+ */
+export function unpackTemplate({ inputPath, outDir, force = false }) {
+  if (!fs.existsSync(inputPath)) {
+    throw new Error(`Input not found: ${inputPath}`);
+  }
+
+  const raw = fs.readFileSync(inputPath, "utf8");
+  /** @type {Record<string, any>} */
+  const data = JSON.parse(raw);
+
+  if (!data.pages || typeof data.pages !== "object") {
+    throw new Error("Invalid TemplateData: missing pages");
+  }
+
+  if (fs.existsSync(outDir)) {
+    if (!force) {
+      throw new Error(
+        `Output exists: ${rel(outDir)} (pass --force to overwrite)`,
+      );
+    }
+    fs.rmSync(outDir, { recursive: true, force: true });
+  }
+
+  const pageIds = Object.keys(data.pages);
+  const stats = { files: 0, pages: pageIds.length, components: 0 };
+
+  writeJson(path.join(outDir, "feeef.template.json"), {
+    $schema: "../../template-kit/schemas/template.schema.json",
+    name: path.basename(outDir),
+    version: "0.1.0",
+    source: path.relative(outDir, inputPath),
+    pages: pageIds,
+  });
+  stats.files += 1;
+
+  fs.writeFileSync(
+    path.join(outDir, ".gitignore"),
+    "# Compiled output — regenerate with `npm run template:build`\ndist/\n",
+    "utf8",
+  );
+
+  if (data.props && typeof data.props === "object") {
+    writeJson(path.join(outDir, "props.json"), data.props);
+    stats.files += 1;
+  }
+
+  for (const pageId of pageIds) {
+    const page = data.pages[pageId] || {};
+    const pageDir = path.join(outDir, "pages", pageId);
+    writeJson(path.join(pageDir, "page.json"), {
+      props: page.props && typeof page.props === "object" ? page.props : {},
+    });
+    stats.files += 1;
+
+    const sections =
+      page.sections && typeof page.sections === "object" ? page.sections : {};
+
+    // Main-only pages → flat `pages/<id>/components/` (sections optional on disk).
+    // Multi-section pages → legacy `sections/<id>/components/`.
+    const sectionKeys = Object.keys(sections);
+    const nonEmptyKeys = sectionKeys.filter((id) => {
+      const list = sections[id]?.components;
+      return Array.isArray(list) && list.length > 0;
+    });
+    const useFlatPageComponents =
+      nonEmptyKeys.length === 0
+        ? sectionKeys.length === 0 ||
+          (sectionKeys.length === 1 && sectionKeys[0] === "main")
+        : nonEmptyKeys.length === 1 && nonEmptyKeys[0] === "main";
+
+    if (useFlatPageComponents) {
+      const components = Array.isArray(sections.main?.components)
+        ? sections.main.components
+        : [];
+      const componentsDir = path.join(pageDir, "components");
+      fs.mkdirSync(componentsDir, { recursive: true });
+      const used = new Set();
+      components.forEach((comp, i) => {
+        if (!comp || typeof comp !== "object") return;
+        const name = folderNameForComponent(comp, i, used);
+        writeComponent(comp, path.join(componentsDir, name), i, stats);
+        stats.components += 1;
+      });
+      continue;
+    }
+
+    for (const [sectionId, section] of Object.entries(sections)) {
+      const components = Array.isArray(section?.components)
+        ? section.components
+        : [];
+      const sectionDir = path.join(pageDir, "sections", sectionId);
+      // Always create the section folder so empty sections round-trip.
+      fs.mkdirSync(path.join(sectionDir, "components"), { recursive: true });
+
+      const used = new Set();
+      components.forEach((comp, i) => {
+        if (!comp || typeof comp !== "object") return;
+        const name = folderNameForComponent(comp, i, used);
+        writeComponent(
+          comp,
+          path.join(sectionDir, "components", name),
+          i,
+          stats,
+        );
+        stats.components += 1;
+      });
+    }
+  }
+
+  return stats;
+}

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

@@ -0,0 +1,207 @@
+/**
+ * Lightweight structural validation for compiled TemplateData.
+ * Returns issues (errors + warnings) instead of throwing.
+ */
+
+/**
+ * @typedef {{ level: 'error' | 'warning'; path: string; message: string }} Issue
+ */
+
+/**
+ * @param {any} data
+ * @param {{ srcDir?: string }} [_ctx]
+ * @returns {Issue[]}
+ */
+export function validateTemplateData(data, _ctx = {}) {
+  /** @type {Issue[]} */
+  const issues = [];
+
+  if (!data || typeof data !== "object") {
+    issues.push({
+      level: "error",
+      path: "/",
+      message: "Root must be an object",
+    });
+    return issues;
+  }
+
+  if (!data.pages || typeof data.pages !== "object") {
+    issues.push({
+      level: "error",
+      path: "/pages",
+      message: "Missing pages object",
+    });
+    return issues;
+  }
+
+  for (const [pageId, page] of Object.entries(data.pages)) {
+    const pagePath = `/pages/${pageId}`;
+    if (!page || typeof page !== "object") {
+      issues.push({
+        level: "error",
+        path: pagePath,
+        message: "Page must be an object",
+      });
+      continue;
+    }
+    if (!page.sections || typeof page.sections !== "object") {
+      issues.push({
+        level: "error",
+        path: `${pagePath}/sections`,
+        message: "Page must have sections",
+      });
+      continue;
+    }
+    for (const [sectionId, section] of Object.entries(page.sections)) {
+      const sectionPath = `${pagePath}/sections/${sectionId}`;
+      if (!Array.isArray(section?.components)) {
+        issues.push({
+          level: "error",
+          path: `${sectionPath}/components`,
+          message: "Section.components must be an array",
+        });
+        continue;
+      }
+      section.components.forEach((c, i) =>
+        validateComponent(c, `${sectionPath}/components[${i}]`, issues),
+      );
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * @param {any} component
+ * @param {string} path
+ * @param {Issue[]} issues
+ */
+function validateComponent(component, path, issues) {
+  if (!component || typeof component !== "object") {
+    issues.push({
+      level: "error",
+      path,
+      message: "Component must be an object",
+    });
+    return;
+  }
+
+  if (typeof component.type !== "string" || !component.type.trim()) {
+    issues.push({
+      level: "error",
+      path: `${path}/type`,
+      message: "type is required",
+    });
+  }
+
+  if (component.props === undefined || component.props === null) {
+    issues.push({
+      level: "warning",
+      path: `${path}/props`,
+      message: "props missing — Lithium usually expects an object",
+    });
+  } else if (typeof component.props !== "object" || Array.isArray(component.props)) {
+    issues.push({
+      level: "error",
+      path: `${path}/props`,
+      message: "props must be an object",
+    });
+  }
+
+  if (component.type === "custom") {
+    if (
+      typeof component.code !== "string" ||
+      component.code.trim().length === 0
+    ) {
+      issues.push({
+        level: "error",
+        path: `${path}/code`,
+        message:
+          'type "custom" requires <name>.tsx or component.tsx with function App() (and export const meta)',
+      });
+    } else if (!/\bfunction\s+App\s*\(/.test(component.code)) {
+      issues.push({
+        level: "warning",
+        path: `${path}/code`,
+        message:
+          "react-live expects `function App()` — code may not render",
+      });
+    }
+  }
+
+  const slotSchemaKeys =
+    component.slotsSchema && typeof component.slotsSchema === "object"
+      ? Object.keys(component.slotsSchema)
+      : [];
+
+  if (component.slots && typeof component.slots === "object") {
+    for (const [slotId, list] of Object.entries(component.slots)) {
+      if (slotSchemaKeys.length > 0 && !slotSchemaKeys.includes(slotId)) {
+        issues.push({
+          level: "warning",
+          path: `${path}/slots/${slotId}`,
+          message: `slot "${slotId}" not declared in slotsSchema`,
+        });
+      }
+      if (!Array.isArray(list)) {
+        issues.push({
+          level: "error",
+          path: `${path}/slots/${slotId}`,
+          message: "slot contents must be an array",
+        });
+        continue;
+      }
+      list.forEach((c, i) =>
+        validateComponent(c, `${path}/slots/${slotId}[${i}]`, issues),
+      );
+    }
+  }
+
+  if (component.slotsLayout && typeof component.slotsLayout === "object") {
+    const leaves = collectLayoutLeaves(component.slotsLayout);
+    for (const leaf of leaves) {
+      if (slotSchemaKeys.length > 0 && !slotSchemaKeys.includes(leaf)) {
+        issues.push({
+          level: "warning",
+          path: `${path}/slotsLayout`,
+          message: `slotsLayout leaf "${leaf}" is not a slotsSchema key`,
+        });
+      }
+    }
+  }
+
+  if (Array.isArray(component.children)) {
+    component.children.forEach((c, i) =>
+      validateComponent(c, `${path}/children[${i}]`, issues),
+    );
+  }
+}
+
+/**
+ * @param {any} node
+ * @returns {string[]}
+ */
+function collectLayoutLeaves(node) {
+  /** @type {string[]} */
+  const out = [];
+  /** @param {any} n */
+  function walk(n) {
+    if (n == null) return;
+    if (typeof n === "string") {
+      out.push(n);
+      return;
+    }
+    if (Array.isArray(n)) {
+      n.forEach(walk);
+      return;
+    }
+    if (typeof n === "object") {
+      if (Array.isArray(n.children)) n.children.forEach(walk);
+      else {
+        for (const v of Object.values(n)) walk(v);
+      }
+    }
+  }
+  walk(node);
+  return out;
+}

package/vendor/template-kit/schemas/component.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://feeef.org/schemas/template-component.json",
+  "title": "Feeef Template Component",
+  "description": "Metadata for one component instance. Prefer flat <name>.tsx (export const meta + App); legacy folder uses component.tsx / component.json.",
+  "type": "object",
+  "required": ["type"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "order": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Sibling sort order within the parent components/slots/children folder."
+    },
+    "type": {
+      "type": "string",
+      "description": "Registry type, or custom / reference / grid / flex / container."
+    },
+    "instanceId": { "type": ["string", "null"] },
+    "title": { "type": ["string", "null"] },
+    "props": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "propsSchema": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "slotsSchema": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "name": { "type": ["string", "null"] },
+          "maxChildren": { "type": ["integer", "null"] }
+        }
+      }
+    },
+    "slotsLayout": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "refId": { "type": "string" },
+    "refVersion": { "type": "number" },
+    "$ref": {
+      "type": "string",
+      "description": "Compile-time shared placement, e.g. \"shared.footer\". Expanded by template-kit build."
+    },
+    "shared": {
+      "type": "string",
+      "description": "Shorthand for $ref shared.<id> (e.g. \"footer\")."
+    }
+  },
+  "additionalProperties": true
+}

package/vendor/template-kit/schemas/template.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://feeef.org/schemas/feeef-template.json",
+  "title": "Feeef Template Manifest",
+  "type": "object",
+  "properties": {
+    "$schema": { "type": "string" },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "source": { "type": "string" },
+    "pages": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Page id order for the compiled data.json"
+    }
+  },
+  "additionalProperties": true
+}