@parche/core 0.3.0-alpha.0

package/src/integration/registry.ts

@@ -0,0 +1,193 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import type { ParcheUserConfig, ResolvedRegistry, ParcheManifest } from './types.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const coreDir = path.resolve(__dirname, '..');
+
+function corePath(...segments: string[]): string {
+  return path.resolve(coreDir, ...segments);
+}
+
+/** Keep the first entry per theme `value` (parche order = precedence). */
+function dedupeThemes(
+  themes: Array<{ label: string; value: string }>,
+): Array<{ label: string; value: string }> {
+  const seen = new Set<string>();
+  return themes.filter((t) => (seen.has(t.value) ? false : (seen.add(t.value), true)));
+}
+
+/** The always-present base look (no data-theme). Themes are added by parches. */
+const DEFAULT_THEME = { label: 'Default', value: '' };
+
+/** Built-in core component registry */
+const CORE_MODULES: Record<string, string> = {
+  // Theme / i18n engine controls (consumed by the ui parche's Header)
+  'parche:components/ThemeToggle': corePath('components/common/ThemeToggle.astro'),
+  'parche:components/ThemeSelector': corePath('components/common/ThemeSelector.astro'),
+  'parche:components/OptimizedImage': corePath('components/common/OptimizedImage.astro'),
+  'parche:components/LocaleSwitcher': corePath('components/common/LocaleSwitcher.astro'),
+  'parche:components/ThemePanel': corePath('components/common/ThemePanel.astro'),
+
+  // Layouts
+  'parche:layouts/BaseLayout': corePath('layouts/BaseLayout.astro'),
+
+  // DynamicRenderer & LayoutRenderer
+  'parche:DynamicRenderer': corePath('components/DynamicRenderer.astro'),
+  'parche:LayoutRenderer': corePath('components/LayoutRenderer.astro'),
+
+  // Utils (named exports)
+  'parche:utils/metadata': corePath('utils/metadata.ts'),
+  'parche:utils/i18n': corePath('utils/i18n.ts'),
+  'parche:utils/layout': corePath('utils/layout.ts'),
+  // Note: layout/Header, layout/Footer and the contact/content templates are
+  // now provided by the ui parche — core no longer ships chrome or primitives.
+};
+
+/** Modules that use named exports instead of default export */
+const NAMED_EXPORT_MODULES = new Set([
+  'parche:utils/metadata',
+  'parche:utils/i18n',
+  'parche:utils/layout',
+]);
+
+/**
+ * Convert an override key ('widgets:hero:Hero') to a virtual module ID ('parche:widgets/hero/Hero')
+ */
+function overrideKeyToVirtualId(key: string): string {
+  return 'parche:' + key.replace(/:/g, '/');
+}
+
+/**
+ * Build the complete resolved registry from user config.
+ */
+export function createRegistry(
+  userConfig: ParcheUserConfig,
+  rootDir: string,
+  astroI18n?: { locales?: Array<string | { path: string; codes: string[] }>; defaultLocale?: string },
+): ResolvedRegistry {
+  const modules: Record<string, string> = { ...CORE_MODULES };
+
+  // Add config module
+  const configPath = userConfig.config || './src/config.ts';
+  modules['parche:config'] = path.resolve(rootDir, configPath);
+
+  // Register parches (order = precedence: later wins). Each parche contributes
+  // primitives / widgets / templates / routes / config to the system.
+  const parches = userConfig.parches ?? [];
+  const providedPrimitives = new Set<string>();
+  const providedWidgets = new Set<string>();
+  const apps: ParcheManifest[] = [];
+  const contributedStyles: string[] = [];
+  const contributedThemes: Array<{ label: string; value: string }> = [];
+  const contentGlobs: string[] = [];
+
+  for (const parche of parches) {
+    if (parche.styles) contributedStyles.push(...parche.styles);
+    if (parche.themes) contributedThemes.push(...parche.themes);
+    if (parche.content) contentGlobs.push(...parche.content);
+    if (parche.primitives) {
+      for (const [name, absPath] of Object.entries(parche.primitives)) {
+        modules[`parche:primitives/${name}`] = absPath;
+        providedPrimitives.add(name);
+      }
+    }
+    if (parche.widgets) {
+      for (const [name, absPath] of Object.entries(parche.widgets)) {
+        modules[`parche:widgets/${name}`] = absPath;
+        providedWidgets.add(name);
+      }
+    }
+    if (parche.templates) {
+      for (const [name, absPath] of Object.entries(parche.templates)) {
+        modules[`parche:templates/${name}`] = absPath;
+      }
+    }
+    if (parche.namedExportModules) {
+      for (const id of parche.namedExportModules) NAMED_EXPORT_MODULES.add(id);
+    }
+    // A parche that injects routes / resolves slugs / exposes config is an "app".
+    if (parche.routes || parche.resolver || parche.config) {
+      apps.push(parche);
+    }
+  }
+
+  // Add user-defined templates
+  if (userConfig.routes?.templates) {
+    for (const [name, userPath] of Object.entries(userConfig.routes.templates)) {
+      modules[`parche:templates/${name}`] = path.resolve(rootDir, userPath);
+    }
+  }
+
+  // Add user-defined layouts
+  if (userConfig.routes?.layouts) {
+    for (const [name, userPath] of Object.entries(userConfig.routes.layouts)) {
+      modules[`parche:layouts/${name}`] = path.resolve(rootDir, userPath);
+    }
+  }
+
+  // Validate parche requirements (V1: capability presence).
+  const missing: string[] = [];
+  for (const parche of parches) {
+    for (const name of parche.requires?.primitives ?? []) {
+      if (!providedPrimitives.has(name)) missing.push(`"${parche.name}" requires primitive "${name}" (parche:primitives/${name})`);
+    }
+    for (const name of parche.requires?.widgets ?? []) {
+      if (!providedWidgets.has(name)) missing.push(`"${parche.name}" requires widget "${name}" (parche:widgets/${name})`);
+    }
+  }
+  if (missing.length) {
+    throw new Error(
+      '[parche] Unsatisfied parche requirements — add a parche that provides them:\n  - ' + missing.join('\n  - '),
+    );
+  }
+
+  // Apply user overrides (these take priority)
+  if (userConfig.overrides) {
+    for (const [key, overridePath] of Object.entries(userConfig.overrides)) {
+      const virtualId = overrideKeyToVirtualId(key);
+      modules[virtualId] = path.resolve(rootDir, overridePath);
+    }
+  }
+
+  // Resolve i18n config from Astro's official i18n settings
+  const resolvedLocales = (astroI18n?.locales ?? ['en']).map((loc) =>
+    typeof loc === 'string' ? loc : loc.codes[0],
+  );
+  const i18n = {
+    locales: resolvedLocales,
+    defaultLocale: astroI18n?.defaultLocale ?? 'en',
+  };
+
+  // Resolve themes: the base look plus whatever the imported parches contribute.
+  // `themes.available` still overrides explicitly, for full manual control.
+  const themes = userConfig.themes?.available ?? dedupeThemes([DEFAULT_THEME, ...contributedThemes]);
+  const showPanel = userConfig.themes?.showPanel ?? themes.length > 1;
+
+  // Aggregate the CSS to bundle: what the parches contribute (e.g. themes) plus
+  // an optional user entry. A site ships only the CSS of the parches it imports.
+  const styleEntries = [...contributedStyles];
+  if (userConfig.styles?.entry) {
+    styleEntries.push(path.resolve(rootDir, userConfig.styles.entry));
+  }
+
+  // Collect app resolvers
+  const resolvers: Array<{ appName: string; entrypoint: string }> = [];
+  for (const app of apps) {
+    if (app.resolver) {
+      resolvers.push({ appName: app.name, entrypoint: app.resolver.entrypoint });
+    }
+  }
+
+  return {
+    modules,
+    namedExportModules: NAMED_EXPORT_MODULES,
+    i18n,
+    themes,
+    showPanel,
+    styleEntries,
+    contentGlobs,
+    apps,
+    resolvers,
+  };
+}

package/src/integration/types.ts

@@ -0,0 +1,193 @@
+export interface UIRegistry {
+  atoms: Record<string, string>;
+  widgets: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Widget props system (Zod v4 + meta)
+// ---------------------------------------------------------------------------
+
+/** Field-level metadata passed via z.string().meta({ ... }) */
+export interface FieldMeta {
+  /** Override the auto-generated label */
+  label?: string;
+  /** Help text shown below the field */
+  help?: string;
+  /** Placeholder for text/textarea inputs */
+  placeholder?: string;
+  /** Force a specific input type: 'textarea', 'icon', 'color', 'url' */
+  input?: string;
+}
+
+/** Group definition for organising fields in the builder form */
+export interface FieldGroup {
+  key: string;
+  label: string;
+  fields: string[];
+}
+
+/** Widget-level metadata — classification + builder UI config */
+export interface WidgetMeta {
+  widget: {
+    label: string;
+    description?: string;
+    category?: string;
+    icon?: string;
+    thumbnail?: string;
+    tags?: string[];
+  };
+  ui?: {
+    groups?: FieldGroup[];
+  };
+}
+
+/** Capabilities a parche needs from the system (validated at setup). */
+export interface ParcheRequires {
+  /** Primitive names that must exist (parche:primitives/{name}) */
+  primitives?: string[];
+  /** Widget names that must exist (parche:widgets/{name}) */
+  widgets?: string[];
+}
+
+/**
+ * A parche (plugin). Contributes capabilities to the Parche host and declares
+ * what it requires. Primitive-packs, widget-packs and apps are all parches —
+ * they differ only in what they provide.
+ */
+export interface ParcheManifest {
+  /** Unique identifier (e.g. 'primitives', 'ui', 'blog') */
+  name: string;
+  /** Primitives to register: name → absolute path (parche:primitives/{name}) */
+  primitives?: Record<string, string>;
+  /** Widgets to register: virtual ID suffix → absolute path (parche:widgets/{name}) */
+  widgets?: Record<string, string>;
+  /** Templates to register: virtual ID suffix → absolute path */
+  templates?: Record<string, string>;
+  /**
+   * CSS files this parche contributes (absolute paths). Aggregated into the
+   * styles entry so a site bundles only the CSS of the parches it imports.
+   * A theme is just a parche that contributes its override CSS here.
+   */
+  styles?: string[];
+  /**
+   * Theme entries this parche adds to the switcher: { label, value }. The
+   * `value` is the `data-theme` attribute the theme's CSS is scoped to.
+   */
+  themes?: Array<{ label: string; value: string }>;
+  /**
+   * Absolute globs of this parche's own component files, so Tailwind scans them
+   * and generates the utility classes they use. A parche must contribute these
+   * for its classes to survive being installed from npm (relative `@source`
+   * paths can't reach sibling packages once published). Typically:
+   *   content: [path.resolve(dir, '**\/*.astro')]
+   */
+  content?: string[];
+  /** Routes to inject */
+  routes?: Array<{ pattern: string; entrypoint: string }>;
+  /** App config exposed via virtual module parche:app/{name} */
+  config?: Record<string, unknown>;
+  /** Module IDs that use named exports (export *) instead of default */
+  namedExportModules?: string[];
+  /**
+   * Content resolver for root-level routes.
+   * When routes would conflict with the catch-all (e.g. /%slug%), the parche
+   * registers a resolver instead; the catch-all calls it before treating a
+   * slug as a page. The entrypoint must export:
+   *   resolve(slug, locale, opts) → { template, collection, entryId, props, metadata } | null
+   *   getPaths(locales, defaultLocale, opts) → Array<{ params, props }>
+   */
+  resolver?: {
+    entrypoint: string;
+  };
+  /** What this parche needs the system to provide. */
+  requires?: ParcheRequires;
+}
+
+/** @deprecated Use ParcheManifest. Kept as an alias for existing app factories. */
+export type ParcheApp = ParcheManifest;
+
+export interface ParcheI18nConfig {
+  /** Supported locales (e.g. ['en', 'es']) */
+  locales: string[];
+  /** Default locale — served without URL prefix (e.g. 'en') */
+  defaultLocale: string;
+}
+
+export interface ParcheRoutesConfig {
+  /**
+   * Enable the built-in catch-all page route ([...slug].astro).
+   * This route renders pages from your JSON content collections using DynamicRenderer.
+   * Must be explicitly set to true to enable.
+   */
+  pages: boolean;
+  /** Additional templates: { templateName: './src/templates/MyTemplate.astro' } */
+  templates?: Record<string, string>;
+  /** Additional layouts: { layoutName: './src/layouts/MyLayout.astro' } */
+  layouts?: Record<string, string>;
+  /** Override the injected catch-all route entrypoint */
+  catchAllRoute?: string;
+  /** Override the injected 404 page entrypoint */
+  notFoundRoute?: string;
+  /** Override the injected middleware entrypoint */
+  middleware?: string;
+}
+
+export interface ParcheStylesConfig {
+  /**
+   * Path to an extra CSS file imported by injected routes, on top of any CSS
+   * the parches contribute. Use it for project-wide styles.
+   * Default: nothing beyond what the imported parches (e.g. themes) provide.
+   */
+  entry?: string;
+}
+
+export interface ParcheThemesConfig {
+  /** Available themes for ThemeSelector. Each entry: { label, value } */
+  available?: Array<{ label: string; value: string }>;
+  /** Show the floating theme panel. Default: true when multiple themes are available */
+  showPanel?: boolean;
+}
+
+export interface ParcheSeoConfig {
+  /** Allow AI crawlers (GPTBot, CCBot, anthropic-ai, ClaudeBot) in robots.txt. Default: true */
+  allowAICrawlers?: boolean;
+}
+
+export interface ParcheUserConfig {
+  /** Override any component using namespaced keys: 'widgets:hero:Hero', 'primitives:Button', etc.
+   *  Values are paths to .astro component files. */
+  overrides?: Record<string, string>;
+  /** Path to user config file (default: './src/config.ts') */
+  config?: string;
+  /** Parches (plugins): primitive-packs, widget-packs and apps. Order = precedence. */
+  parches?: ParcheManifest[];
+  /** Route injection config */
+  routes?: ParcheRoutesConfig;
+  /** Theme config */
+  themes?: ParcheThemesConfig;
+  /** Styles config */
+  styles?: ParcheStylesConfig;
+  /** SEO build-time config (robots.txt generation, etc.) */
+  seo?: ParcheSeoConfig;
+}
+
+export interface ResolvedRegistry {
+  /** Map of virtual module ID → absolute file path */
+  modules: Record<string, string>;
+  /** Set of virtual IDs that use named exports (export *) instead of default */
+  namedExportModules: Set<string>;
+  /** Resolved i18n config */
+  i18n: ParcheI18nConfig;
+  /** Resolved themes config */
+  themes: Array<{ label: string; value: string }>;
+  /** Whether to show the floating theme panel */
+  showPanel: boolean;
+  /** Absolute CSS paths to import via parche:config/styles (parche-contributed + user entry) */
+  styleEntries: string[];
+  /** Absolute globs of parche component files for Tailwind to scan (@source) */
+  contentGlobs: string[];
+  /** Registered apps */
+  apps: ParcheApp[];
+  /** App resolvers — modules that export resolve() and getPaths() */
+  resolvers: Array<{ appName: string; entrypoint: string }>;
+}