meno-core 1.0.0

package/lib/shared/interfaces/contentProvider.ts

@@ -0,0 +1,121 @@
+/**
+ * Content Provider Interfaces
+ * Abstractions for data sources (file system, CMS, API, etc.)
+ */
+
+import type { ComponentDefinition } from '../types/components';
+import type { CMSSchema, CMSItem } from '../types/cms';
+
+/**
+ * Page Provider Interface
+ * Abstracts page data loading from the underlying storage mechanism
+ */
+export interface PageProvider {
+  /**
+   * Load all pages from the data source
+   * @returns Map of page path to raw JSON string content
+   */
+  loadAll(): Promise<Map<string, string>>;
+
+  /**
+   * Get a single page by path
+   * @param path - Page path (e.g., "/" or "/about")
+   * @returns Raw JSON string content, or null if not found
+   */
+  get(path: string): Promise<string | null>;
+
+  /**
+   * Save page content
+   * @param path - Page path
+   * @param content - Raw JSON string content
+   */
+  save(path: string, content: string): Promise<void>;
+
+  /**
+   * Delete a page
+   * @param path - Page path to delete
+   */
+  delete(path: string): Promise<void>;
+
+  /**
+   * Check if a page exists
+   * @param path - Page path
+   * @returns True if page exists
+   */
+  exists(path: string): Promise<boolean>;
+}
+
+/**
+ * Component Provider Interface
+ * Abstracts component definition loading
+ */
+export interface ComponentProvider {
+  /**
+   * Load all component definitions
+   * @returns Map of component name to definition
+   */
+  loadAll(): Promise<Map<string, ComponentDefinition>>;
+
+  /**
+   * Get a single component by name
+   * @param name - Component name
+   * @returns Component definition or null if not found
+   */
+  get(name: string): Promise<ComponentDefinition | null>;
+
+  /**
+   * Get JavaScript code for a component
+   * @param name - Component name
+   * @returns JavaScript string or null if not found
+   */
+  getJS(name: string): Promise<string | null>;
+
+  /**
+   * Get CSS code for a component
+   * @param name - Component name
+   * @returns CSS string or null if not found
+   */
+  getCSS(name: string): Promise<string | null>;
+
+  /**
+   * Save component definition
+   * @param name - Component name
+   * @param definition - Component definition
+   */
+  save(name: string, definition: ComponentDefinition): Promise<void>;
+}
+
+// ============================================================================
+// CMS Provider
+// ============================================================================
+
+/** Schema info extracted from a page file */
+export interface CMSSchemaInfo {
+  schema: CMSSchema;
+  pagePath: string;  // Path to the page file containing this schema
+}
+
+/**
+ * CMS Provider Interface
+ * Abstracts CMS data loading from the underlying storage mechanism
+ * (follows same pattern as PageProvider)
+ */
+export interface CMSProvider {
+  /** Load all CMS schemas (extracted from page files with source: 'cms') */
+  getAllSchemas(): Promise<Map<string, CMSSchemaInfo>>;
+
+  /** Load all items for a collection */
+  getItems(collection: string): Promise<CMSItem[]>;
+
+  /** Get single item by slug */
+  getItemBySlug(collection: string, slug: string): Promise<CMSItem | null>;
+
+  /** Get single item by ID */
+  getItemById(collection: string, id: string): Promise<CMSItem | null>;
+
+  /** Save item (for editor) - saves to cms/<collection>/<slug>.json */
+  saveItem(collection: string, item: CMSItem): Promise<void>;
+
+  /** Delete item by slug */
+  deleteItem(collection: string, slug: string): Promise<void>;
+}

package/lib/shared/nodeUtils.test.ts

@@ -0,0 +1,320 @@
+import { describe, test, expect, beforeAll } from 'bun:test';
+import {
+  isComponentNode,
+  isHtmlNode,
+  getComponentName,
+  getTagName,
+  getDisplayName,
+  extractNodeProperties,
+  isLikelyComponentTag,
+  isSlotMarker,
+  isEmbedNode,
+  isObjectLinkNode,
+  isLocaleListNode,
+  isValidNodeType,
+  canHaveChildren,
+  canHaveStyle,
+  isStructuredComponentDefinition,
+  hasComponentStructure,
+  hasComponentCss,
+} from './nodeUtils';
+import { NODE_TYPE } from './constants';
+import type { ComponentNode, ComponentInstanceNode, HtmlNode, SlotMarker, EmbedNode, ObjectLinkNode, LocaleListNode } from './types';
+import { registerBuiltInNodeTypes } from './registry';
+
+describe('nodeUtils', () => {
+  beforeAll(() => {
+    registerBuiltInNodeTypes();
+  });
+  describe('isComponentNode', () => {
+    test('returns true for component instance nodes', () => {
+      const node: ComponentInstanceNode = { type: NODE_TYPE.COMPONENT, component: 'Button', props: {} };
+      expect(isComponentNode(node)).toBe(true);
+    });
+
+    test('returns false for HTML nodes', () => {
+      const node: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(isComponentNode(node)).toBe(false);
+    });
+
+    test('returns false for null or undefined', () => {
+      expect(isComponentNode(null)).toBe(false);
+      expect(isComponentNode(undefined)).toBe(false);
+    });
+  });
+
+  describe('isHtmlNode', () => {
+    test('returns true for HTML element nodes', () => {
+      const node: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(isHtmlNode(node)).toBe(true);
+    });
+
+    test('returns false for component nodes', () => {
+      const node: ComponentInstanceNode = { type: NODE_TYPE.COMPONENT, component: 'Button', props: {} };
+      expect(isHtmlNode(node)).toBe(false);
+    });
+
+    test('returns false for null or undefined', () => {
+      expect(isHtmlNode(null)).toBe(false);
+      expect(isHtmlNode(undefined)).toBe(false);
+    });
+  });
+
+  describe('getComponentName', () => {
+    test('returns component name for component nodes', () => {
+      const node: ComponentInstanceNode = { type: NODE_TYPE.COMPONENT, component: 'Button', props: {} };
+      expect(getComponentName(node)).toBe('Button');
+    });
+
+    test('returns undefined for HTML nodes', () => {
+      const node: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(getComponentName(node)).toBeUndefined();
+    });
+  });
+
+  describe('getTagName', () => {
+    test('returns tag name for HTML nodes', () => {
+      const node: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(getTagName(node)).toBe('div');
+    });
+
+    test('returns undefined for component nodes', () => {
+      const node: ComponentInstanceNode = { type: NODE_TYPE.COMPONENT, component: 'Button', props: {} };
+      expect(getTagName(node)).toBeUndefined();
+    });
+  });
+
+  describe('getDisplayName', () => {
+    test('returns component name for component nodes', () => {
+      const node: ComponentInstanceNode = { type: NODE_TYPE.COMPONENT, component: 'Button', props: {} };
+      expect(getDisplayName(node)).toBe('Button');
+    });
+
+    test('returns tag name for HTML nodes', () => {
+      const node: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(getDisplayName(node)).toBe('div');
+    });
+
+    test('returns "Embed" for embed nodes', () => {
+      const node: EmbedNode = { type: NODE_TYPE.EMBED, html: '<div>test</div>' };
+      expect(getDisplayName(node)).toBe('Embed');
+    });
+
+    test('returns "Link" for object link nodes', () => {
+      const node: ObjectLinkNode = { type: NODE_TYPE.OBJECT_LINK, object: 'page', id: '123' };
+      expect(getDisplayName(node)).toBe('Link');
+    });
+
+    test('returns "LocaleList" for locale list nodes', () => {
+      const node: LocaleListNode = { type: NODE_TYPE.LOCALE_LIST, locales: {} };
+      expect(getDisplayName(node)).toBe('LocaleList');
+    });
+
+    test('returns "Unknown" for unrecognized nodes', () => {
+      const node = { type: 'unknown' } as any;
+      expect(getDisplayName(node)).toBe('Unknown');
+    });
+  });
+
+  describe('extractNodeProperties', () => {
+    test('extracts component name and props from component node', () => {
+      const node: ComponentInstanceNode = {
+        type: NODE_TYPE.COMPONENT,
+        component: 'Button',
+        props: { text: 'Click me' }
+      };
+      expect(extractNodeProperties(node)).toEqual({
+        componentName: 'Button',
+        props: { text: 'Click me' }
+      });
+    });
+
+    test('extracts tag from HTML node', () => {
+      const node: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(extractNodeProperties(node)).toEqual({
+        tag: 'div',
+        props: {}
+      });
+    });
+
+    test('returns empty props for unknown node types', () => {
+      const node = { type: 'unknown' } as any;
+      expect(extractNodeProperties(node)).toEqual({ props: {} });
+    });
+  });
+
+  describe('isLikelyComponentTag', () => {
+    test('returns true for capitalized tags', () => {
+      expect(isLikelyComponentTag('Button')).toBe(true);
+      expect(isLikelyComponentTag('Card')).toBe(true);
+      expect(isLikelyComponentTag('MyComponent')).toBe(true);
+    });
+
+    test('returns false for lowercase tags', () => {
+      expect(isLikelyComponentTag('div')).toBe(false);
+      expect(isLikelyComponentTag('span')).toBe(false);
+      expect(isLikelyComponentTag('button')).toBe(false);
+    });
+
+    test('returns false for empty string', () => {
+      expect(isLikelyComponentTag('')).toBe(false);
+    });
+  });
+
+  describe('isSlotMarker', () => {
+    test('returns true for slot marker nodes', () => {
+      const node: SlotMarker = { type: NODE_TYPE.SLOT, name: 'default' };
+      expect(isSlotMarker(node)).toBe(true);
+    });
+
+    test('returns false for non-slot nodes', () => {
+      const node: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(isSlotMarker(node)).toBe(false);
+    });
+
+    test('returns false for null or undefined', () => {
+      expect(isSlotMarker(null)).toBe(false);
+      expect(isSlotMarker(undefined)).toBe(false);
+    });
+  });
+
+  describe('isEmbedNode', () => {
+    test('returns true for embed nodes', () => {
+      const node: EmbedNode = { type: NODE_TYPE.EMBED, url: 'https://example.com' };
+      expect(isEmbedNode(node)).toBe(true);
+    });
+
+    test('returns false for non-embed nodes', () => {
+      const node: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(isEmbedNode(node)).toBe(false);
+    });
+  });
+
+  describe('isObjectLinkNode', () => {
+    test('returns true for object link nodes', () => {
+      const node: ObjectLinkNode = { type: NODE_TYPE.OBJECT_LINK, object: 'page', id: '123' };
+      expect(isObjectLinkNode(node)).toBe(true);
+    });
+
+    test('returns false for non-object-link nodes', () => {
+      const node: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(isObjectLinkNode(node)).toBe(false);
+    });
+  });
+
+  describe('isLocaleListNode', () => {
+    test('returns true for locale list nodes', () => {
+      const node: LocaleListNode = { type: NODE_TYPE.LOCALE_LIST, locales: {} };
+      expect(isLocaleListNode(node)).toBe(true);
+    });
+
+    test('returns false for non-locale-list nodes', () => {
+      const node: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(isLocaleListNode(node)).toBe(false);
+    });
+  });
+
+  describe('isValidNodeType', () => {
+    test('returns true for valid node types', () => {
+      expect(isValidNodeType(NODE_TYPE.NODE)).toBe(true);
+      expect(isValidNodeType(NODE_TYPE.COMPONENT)).toBe(true);
+      expect(isValidNodeType(NODE_TYPE.SLOT)).toBe(true);
+      expect(isValidNodeType(NODE_TYPE.EMBED)).toBe(true);
+      expect(isValidNodeType(NODE_TYPE.OBJECT_LINK)).toBe(true);
+      expect(isValidNodeType(NODE_TYPE.LOCALE_LIST)).toBe(true);
+    });
+
+    test('returns false for invalid node types', () => {
+      expect(isValidNodeType('invalid')).toBe(false);
+      expect(isValidNodeType('unknown')).toBe(false);
+    });
+  });
+
+  describe('canHaveChildren', () => {
+    test('returns true for nodes that can have children', () => {
+      const htmlNode: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(canHaveChildren(htmlNode)).toBe(true);
+
+      const componentNode: ComponentInstanceNode = { type: NODE_TYPE.COMPONENT, component: 'Button', props: {} };
+      expect(canHaveChildren(componentNode)).toBe(true);
+    });
+
+    test('returns false for slot markers', () => {
+      const slotNode: SlotMarker = { type: NODE_TYPE.SLOT, name: 'default' };
+      expect(canHaveChildren(slotNode)).toBe(false);
+    });
+
+    test('returns false for null or undefined', () => {
+      expect(canHaveChildren(null)).toBe(false);
+      expect(canHaveChildren(undefined)).toBe(false);
+    });
+  });
+
+  describe('canHaveStyle', () => {
+    test('returns true for nodes that can have style', () => {
+      const htmlNode: HtmlNode = { type: NODE_TYPE.NODE, tag: 'div' };
+      expect(canHaveStyle(htmlNode)).toBe(true);
+
+      const componentNode: ComponentInstanceNode = { type: NODE_TYPE.COMPONENT, component: 'Button', props: {} };
+      expect(canHaveStyle(componentNode)).toBe(true);
+    });
+
+    test('returns false for slot markers', () => {
+      const slotNode: SlotMarker = { type: NODE_TYPE.SLOT, name: 'default' };
+      expect(canHaveStyle(slotNode)).toBe(false);
+    });
+
+    test('returns false for null or undefined', () => {
+      expect(canHaveStyle(null)).toBe(false);
+      expect(canHaveStyle(undefined)).toBe(false);
+    });
+  });
+
+  describe('isStructuredComponentDefinition', () => {
+    test('returns true for structured component definitions', () => {
+      expect(isStructuredComponentDefinition({ interface: [] })).toBe(true);
+      expect(isStructuredComponentDefinition({ structure: {} })).toBe(true);
+      expect(isStructuredComponentDefinition({ javascript: 'code' })).toBe(true);
+      expect(isStructuredComponentDefinition({ css: 'styles' })).toBe(true);
+      expect(isStructuredComponentDefinition({ interface: [], structure: {} })).toBe(true);
+    });
+
+    test('returns false for invalid structures', () => {
+      expect(isStructuredComponentDefinition(null)).toBe(false);
+      expect(isStructuredComponentDefinition(undefined)).toBe(false);
+      expect(isStructuredComponentDefinition('string')).toBe(false);
+      expect(isStructuredComponentDefinition(123)).toBe(false);
+      expect(isStructuredComponentDefinition({})).toBe(false);
+      expect(isStructuredComponentDefinition({ structure: 'invalid' })).toBe(false);
+    });
+  });
+
+  describe('hasComponentStructure', () => {
+    test('returns true if component has structure', () => {
+      const comp = { component: { structure: {} } };
+      expect(hasComponentStructure(comp as any)).toBe(true);
+    });
+
+    test('returns false if component has no structure', () => {
+      const comp = { component: {} };
+      expect(hasComponentStructure(comp as any)).toBe(false);
+    });
+  });
+
+  describe('hasComponentCss', () => {
+    test('returns true if component has CSS string', () => {
+      const comp = { component: { css: 'body { color: red; }' } };
+      expect(hasComponentCss(comp as any)).toBe(true);
+    });
+
+    test('returns false if component has no CSS', () => {
+      const comp = { component: {} };
+      expect(hasComponentCss(comp as any)).toBe(false);
+    });
+
+    test('returns false if CSS is not a string', () => {
+      const comp = { component: { css: 123 } };
+      expect(hasComponentCss(comp as any)).toBe(false);
+    });
+  });
+});

package/lib/shared/nodeUtils.ts

@@ -0,0 +1,220 @@
+/**
+ * Node type utilities and type guards
+ * Provides helper functions for working with ComponentNode types
+ */
+
+import type { ComponentNode, ComponentInstanceNode, HtmlNode, SlotMarker, EmbedNode, ObjectLinkNode, LocaleListNode, ComponentDefinition, StructuredComponentDefinition } from './types';
+import { NODE_TYPE } from './constants';
+
+/**
+ * Type guard to check if a node is a component instance
+ */
+export function isComponentNode(node: ComponentNode | null | undefined): node is ComponentInstanceNode {
+  return node?.type === NODE_TYPE.COMPONENT;
+}
+
+/**
+ * Type guard to check if a node is an HTML element
+ */
+export function isHtmlNode(node: ComponentNode | null | undefined): node is HtmlNode {
+  return node?.type === NODE_TYPE.NODE;
+}
+
+/**
+ * Get the component name from a ComponentNode (for component instances)
+ */
+export function getComponentName(node: ComponentNode): string | undefined {
+  return isComponentNode(node) ? node.component : undefined;
+}
+
+/**
+ * Get the tag name from a ComponentNode (for HTML nodes)
+ */
+export function getTagName(node: ComponentNode): string | undefined {
+  return isHtmlNode(node) ? node.tag : undefined;
+}
+
+/**
+ * Get the display name (tag or component name) from a ComponentNode
+ * Uses registry for automatic display name resolution
+ */
+export function getDisplayName(node: ComponentNode): string {
+  // Dynamic names for component/html nodes
+  if (isComponentNode(node)) {
+    return node.component;
+  }
+  if (isHtmlNode(node)) {
+    return node.tag;
+  }
+
+  // Use registry for all other node types
+  const { globalNodeTypeManager } = require('./registry');
+  const definition = globalNodeTypeManager.getClient().findByNode(node);
+  return definition?.displayName || 'Unknown';
+}
+
+/**
+ * Extract node properties (tag/component, props) based on node type
+ * Returns an object with tag, componentName, and props
+ */
+export function extractNodeProperties(node: ComponentNode): {
+  tag?: string;
+  componentName?: string;
+  props: Record<string, unknown>;
+} {
+  if (isComponentNode(node)) {
+    return {
+      componentName: node.component,
+      props: node.props || {}
+    };
+  }
+  if (isHtmlNode(node)) {
+    return {
+      tag: node.tag,
+      props: {}
+    };
+  }
+  return { props: {} };
+}
+
+/**
+ * Check if a tag name is likely a component (as opposed to HTML element)
+ * This is a heuristic based on naming conventions:
+ * - Components typically start with uppercase (e.g., "Card", "Button")
+ * - HTML elements are lowercase (e.g., "div", "span")
+ * 
+ * Note: This is not foolproof, but works for most cases.
+ * For accurate detection, use component registry lookup.
+ */
+export function isLikelyComponentTag(tag: string): boolean {
+  if (!tag) return false;
+  // Components typically start with uppercase letter
+  return tag.length > 0 && tag[0] === tag[0].toUpperCase() && tag[0] !== tag[0].toLowerCase();
+}
+
+/**
+ * Type guard to check if a node is a slot marker
+ */
+export function isSlotMarker(node: ComponentNode | null | undefined): node is SlotMarker {
+  return node?.type === NODE_TYPE.SLOT;
+}
+
+/**
+ * Type guard to check if a node is an embed node
+ */
+export function isEmbedNode(node: ComponentNode | null | undefined): node is EmbedNode {
+  return node?.type === NODE_TYPE.EMBED;
+}
+
+/**
+ * Type guard to check if a node is an object link node
+ */
+export function isObjectLinkNode(node: ComponentNode | null | undefined): node is ObjectLinkNode {
+  return node?.type === NODE_TYPE.OBJECT_LINK;
+}
+
+/**
+ * Type guard to check if a node is a locale list node
+ */
+export function isLocaleListNode(node: ComponentNode | null | undefined): node is LocaleListNode {
+  return node?.type === NODE_TYPE.LOCALE_LIST;
+}
+
+/**
+ * Validate that a node type is valid
+ */
+export function isValidNodeType(type: string): type is typeof NODE_TYPE[keyof typeof NODE_TYPE] {
+  return type === NODE_TYPE.NODE || type === NODE_TYPE.COMPONENT || type === NODE_TYPE.SLOT ||
+    type === NODE_TYPE.EMBED || type === NODE_TYPE.OBJECT_LINK || type === NODE_TYPE.LOCALE_LIST;
+}
+
+/**
+ * Check if a node can have children property (excludes SlotMarker)
+ */
+export function canHaveChildren(node: ComponentNode | null | undefined): node is Exclude<ComponentNode, SlotMarker> {
+  return node !== null && node !== undefined && !isSlotMarker(node);
+}
+
+/**
+ * Check if a node can have style property (excludes SlotMarker)
+ */
+export function canHaveStyle(node: ComponentNode | null | undefined): node is Exclude<ComponentNode, SlotMarker> {
+  return node !== null && node !== undefined && !isSlotMarker(node);
+}
+
+/**
+ * Type guard to check if a value is a StructuredComponentDefinition
+ */
+export function isStructuredComponentDefinition(comp: unknown): comp is StructuredComponentDefinition {
+  if (!comp || typeof comp !== 'object') {
+    return false;
+  }
+  // Check for required structure properties (interface, structure are optional but structure should be an object if present)
+  const obj = comp as Record<string, unknown>;
+  // Must have at least one of: interface, structure, javascript, css
+  return (
+    ('interface' in obj || 'structure' in obj || 'javascript' in obj || 'css' in obj) &&
+    (obj.structure === undefined || (typeof obj.structure === 'object' && obj.structure !== null))
+  );
+}
+
+/**
+ * Check if a ComponentDefinition has a structure property
+ */
+export function hasComponentStructure(comp: ComponentDefinition): boolean {
+  return comp.component?.structure !== undefined;
+}
+
+/**
+ * Check if a ComponentDefinition has a css property
+ */
+export function hasComponentCss(comp: ComponentDefinition): boolean {
+  return comp.component?.css !== undefined && typeof comp.component.css === 'string';
+}
+
+/**
+ * Get the node type definition from the registry
+ * This is a convenience function that uses the global node type registry
+ * to find the type definition for a node.
+ *
+ * @param node - The node to get the type definition for
+ * @returns The node type definition, or undefined if not found
+ *
+ * @example
+ * const node = { type: 'image', src: 'test.jpg' };
+ * const definition = getNodeTypeDefinition(node);
+ * if (definition) {
+ *   console.log(definition.displayName); // "Image"
+ * }
+ */
+export function getNodeTypeDefinition(node: ComponentNode | null | undefined) {
+  if (!node) return undefined;
+  // Import dynamically to avoid circular dependencies
+  // The globalNodeTypeManager will be initialized by the app entry point
+  const { globalNodeTypeManager } = require('./registry');
+  return globalNodeTypeManager.getClient().findByNode(node);
+}
+
+/**
+ * Check if a node matches a specific type using the registry
+ * This is an alternative to the individual type guards that uses
+ * the centralized node type registry.
+ *
+ * @param node - The node to check
+ * @param nodeType - The node type constant (e.g., NODE_TYPE.EMBED)
+ * @returns true if the node matches the type
+ *
+ * @example
+ * import { NODE_TYPE } from './constants';
+ * const node = { type: 'embed', html: '<div>test</div>' };
+ * if (isNodeType(node, NODE_TYPE.EMBED)) {
+ *   // node is an EmbedNode
+ * }
+ */
+export function isNodeType(node: ComponentNode | null | undefined, nodeType: string): boolean {
+  if (!node) return false;
+  // Import dynamically to avoid circular dependencies
+  const { globalNodeTypeManager } = require('./registry');
+  return globalNodeTypeManager.getClient().isType(node, nodeType);
+}
+