@mmapp/react 0.1.0-alpha.1 → 0.1.0-alpha.3

package/src/config/defineBlueprint.ts

@@ -1,329 +0,0 @@
-/**
- * defineBlueprint — declarative configuration for a MindMatrix workflow blueprint.
- *
- * Everything is a workflow. Blueprints, modules, and apps are all workflow
- * definitions distinguished only by category labels. A definition can be
- * ["workflow", "blueprint", "module"] simultaneously.
- *
- * This is the SINGLE manifest file (mm.config.ts) for any project. It declares
- * what the project provides (models, routes, actions) and what
- * it requires (dependencies, capabilities).
- *
- * Usage in mm.config.ts:
- *   import { defineBlueprint } from '@mindmatrix/react';
- *
- *   export default defineBlueprint({
- *     slug: 'mod-authentication',
- *     name: 'Authentication & Authorization',
- *     version: '3.0.0',
- *     category: 'module',
- *     models: ['models/authentication', 'models/user'],
- *     routes: [{ path: '/login', view: 'app/login', label: 'Login' }],
- *     actions: [{ id: 'server:authenticate', handler: 'actions.server' }],
- *   });
- */
-
-import type { RuntimeProfile } from '@mindmatrix/player-core';
-
-// =============================================================================
-// Shared Sub-Types (used by BlueprintConfig)
-// =============================================================================
-
-/**
- * Slot contributions from this blueprint to a target blueprint.
- * Keys are slot names, values are component identifiers that fill them.
- */
-export type SlotContributions = Record<string, string[]>;
-
-/** A route this definition adds to the host application. */
-export interface BlueprintRoute {
-  /** Route path (e.g., '/login', '/admin/auth/users'). */
-  path: string;
-  /** Display label for navigation. */
-  label?: string;
-  /** The view component file path (relative to project root). */
-  view: string;
-  /** Route guard expression (e.g., 'context.actor_role == "admin"'). */
-  guard?: string;
-  /** Redirect path when guard fails. */
-  redirect?: string;
-  /** Route group for organization (e.g., 'auth', 'admin'). */
-  group?: string;
-  /** Icon name for navigation. */
-  icon?: string;
-  /** Whether to show in navigation menus. */
-  showInNav?: boolean;
-}
-
-/** A slot contribution — what this definition injects into parent slots. */
-export interface BlueprintSlotContribution {
-  /** Target slot name (e.g., 'app:sidebar', 'app:settings-tabs'). */
-  slot: string;
-  /** Component to render in the slot. */
-  view: string;
-  /** Priority for ordering (lower = earlier). */
-  priority?: number;
-  /** Guard expression for conditional rendering. */
-  guard?: string;
-}
-
-/** A server action this definition registers. */
-export interface BlueprintAction {
-  /** Action identifier (e.g., 'server:authenticate'). */
-  id: string;
-  /** Description. */
-  description?: string;
-  /** Source file path (relative to project root). */
-  handler: string;
-  /** Function name in the handler file. */
-  functionName?: string;
-}
-
-/** Setup wizard step definition. */
-export interface SetupWizardStep {
-  /** Step identifier. */
-  id: string;
-  /** Step label. */
-  label: string;
-  /** Step description. */
-  description?: string;
-  /** View component for this step. */
-  view: string;
-  /** Whether this step can be skipped. */
-  optional?: boolean;
-  /** Validation expression — must be truthy to proceed. */
-  validate?: string;
-  /** Config fields collected in this step. */
-  fields?: Array<{
-    key: string;
-    label: string;
-    type: 'text' | 'number' | 'boolean' | 'select';
-    defaultValue?: unknown;
-    description?: string;
-    options?: Array<{ value: string; label: string }>;
-  }>;
-}
-
-/** Setup wizard definition. */
-export interface SetupWizard {
-  /** Title shown during setup. */
-  title: string;
-  /** Description shown on the wizard landing. */
-  description?: string;
-  /** Ordered list of setup steps. */
-  steps: SetupWizardStep[];
-  /** View component for the completion screen. */
-  completionView?: string;
-}
-
-/** Configuration schema. */
-export interface BlueprintConfigSchema {
-  /** Slug of the configuration model (must be one of this definition's models). */
-  modelSlug: string;
-  /** Default configuration values. */
-  defaults?: Record<string, unknown>;
-}
-
-/** Route configuration for a module dependency. */
-export interface ModuleRouteConfig {
-  /** URL prefix for all module routes (e.g., '/auth'). Derived from slug if omitted. */
-  prefix?: string;
-  /**
-   * Per-route overrides. Keys are module route paths, values are:
-   * - string: remap to this parent path (e.g., '/login' → '/')
-   * - false: disable this route entirely
-   * Unmapped routes use the prefix.
-   */
-  routes?: Record<string, string | false>;
-}
-
-/** Dependency on another definition. */
-export interface BlueprintDependency {
-  /** Definition slug. */
-  slug: string;
-  /** Semver version range (e.g., '>=2.0.0', '^3.0.0'). */
-  version?: string;
-  /** Whether the dependency is optional. */
-  optional?: boolean;
-  /** Whether this dependency is required (default: false). */
-  required?: boolean;
-  /** Route composition configuration. */
-  routeConfig?: ModuleRouteConfig;
-  /**
-   * Slot name remapping. Keys are module's internal slot names,
-   * values are the parent's slot namespace.
-   * E.g., { 'auth:login-providers': 'app:social-login' }
-   */
-  slotMapping?: Record<string, string>;
-  /** Configuration values passed to the module at install time. */
-  config?: Record<string, unknown>;
-}
-
-// =============================================================================
-// Blueprint Config
-// =============================================================================
-
-/**
- * Blueprint configuration — the input to defineBlueprint().
- *
- * This is the unified manifest for any MindMatrix project. Everything is a
- * workflow definition — blueprints, modules, and apps are distinguished only
- * by their category label.
- */
-export interface BlueprintConfig {
-  /** Unique identifier for this definition (kebab-case). */
-  slug: string;
-  /** Human-readable display name. */
-  name: string;
-  /** Semantic version string. */
-  version: string;
-  /** Optional description. */
-  description?: string;
-  /** Author name. */
-  author?: string;
-  /** License identifier. */
-  license?: string;
-  /** Icon URL or icon name. */
-  icon?: string;
-  /** Tags for discovery. */
-  tags?: string[];
-  /** Compilation mode: strict enforces @mindmatrix/react-only hooks; infer allows escape hatches. */
-  mode?: 'strict' | 'infer';
-  /** Default runtime profile for all workflows in this definition. */
-  defaultRuntime?: RuntimeProfile;
-  /**
-   * Category for the compiled workflow definition.
-   * Can be a single string or an array of categories.
-   * A definition can be ["workflow", "blueprint", "module"] simultaneously.
-   */
-  category?: string | string[];
-
-  // ── Structure ──
-
-  /**
-   * Entry file paths relative to the project root.
-   * If omitted, auto-discovered from app/ directory.
-   */
-  entries?: string[];
-  /**
-   * Model file paths relative to the project root.
-   * If omitted, auto-discovered from models/ directory.
-   */
-  models?: string[];
-
-  // ── Provides ──
-
-  /** Routes this definition adds. */
-  routes?: BlueprintRoute[];
-  /** Slot contributions to parent blueprints (structured). */
-  contributions?: BlueprintSlotContribution[];
-  /**
-   * Slot contributions to other blueprints (legacy shorthand).
-   * Key = target blueprint slug, value = slot name → component list.
-   */
-  contributes_to?: Record<string, SlotContributions>;
-  /** Server actions this definition registers. */
-  actions?: BlueprintAction[];
-  /**
-   * Public model surface — model slugs that consuming blueprints can query.
-   * E.g., ['user', 'session', 'role'] exposes these models for cross-module data access.
-   */
-  exports?: string[];
-
-  // ── Requires ──
-
-  /** Dependencies on other definitions. */
-  dependencies?: BlueprintDependency[];
-  /** Required host capabilities (e.g., 'email', 'oauth', 'file-storage'). */
-  capabilities?: string[];
-  /** Required host slots that must exist for contributions. */
-  requiredSlots?: string[];
-
-  // ── Configuration ──
-
-  /** Configuration schema. */
-  configSchema?: BlueprintConfigSchema;
-  /** Setup wizard definition. */
-  setupWizard?: SetupWizard;
-}
-
-/**
- * Blueprint manifest — the resolved output of defineBlueprint().
- * Used by the compiler and build pipeline.
- */
-export interface BlueprintManifest extends BlueprintConfig {
-  /** Always populated with defaults applied. */
-  slug: string;
-  name: string;
-  version: string;
-  mode: 'strict' | 'infer';
-  defaultRuntime: RuntimeProfile;
-  category: string | string[];
-}
-
-// =============================================================================
-// Implementation
-// =============================================================================
-
-/**
- * Creates a validated blueprint manifest from configuration.
- *
- * Applies defaults:
- * - mode: 'infer'
- * - defaultRuntime: 'local'
- * - category: 'blueprint'
- */
-export function defineBlueprint(config: BlueprintConfig): BlueprintManifest {
-  if (!config.slug) {
-    throw new Error('defineBlueprint: slug is required');
-  }
-  if (!config.name) {
-    throw new Error('defineBlueprint: name is required');
-  }
-  if (!config.version) {
-    throw new Error('defineBlueprint: version is required');
-  }
-
-  // Validate slug format (kebab-case)
-  if (!/^[a-z][a-z0-9-]*$/.test(config.slug)) {
-    throw new Error(
-      `defineBlueprint: slug must be kebab-case (got "${config.slug}")`
-    );
-  }
-
-  // Validate version format (semver-like)
-  if (!/^\d+\.\d+\.\d+/.test(config.version)) {
-    throw new Error(
-      `defineBlueprint: version must be semver (got "${config.version}")`
-    );
-  }
-
-  return {
-    ...config,
-    mode: config.mode || 'infer',
-    defaultRuntime: config.defaultRuntime || 'local',
-    category: config.category || 'blueprint',
-  };
-}
-
-// =============================================================================
-// Legacy Aliases (backwards compatibility with defineModule types)
-// =============================================================================
-
-/** @deprecated Use BlueprintRoute */
-export type ModuleRoute = BlueprintRoute;
-/** @deprecated Use BlueprintSlotContribution */
-export type SlotContribution = BlueprintSlotContribution;
-/** @deprecated Use BlueprintAction */
-export type ModuleAction = BlueprintAction;
-/** @deprecated Use BlueprintConfigSchema */
-export type ModuleConfigSchema = BlueprintConfigSchema;
-/** @deprecated Use BlueprintDependency */
-export type ModuleDependency = BlueprintDependency;
-/** @deprecated Use BlueprintConfig */
-export type ModuleManifest = BlueprintConfig;
-
-/** @deprecated Use defineBlueprint() — modules and blueprints are the same thing. */
-export function defineModule<const M extends BlueprintConfig>(manifest: M): M & { mode: 'strict' | 'infer'; defaultRuntime: RuntimeProfile; category: string | string[] } {
-  return defineBlueprint(manifest as BlueprintConfig) as M & { mode: 'strict' | 'infer'; defaultRuntime: RuntimeProfile; category: string | string[] };
-}