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

package/src/dev-server.ts

@@ -1,238 +0,0 @@
-/**
- * Dev Server — Vite-based development server for MindMatrix React workflows.
- *
- * Uses the Vite plugin to watch .workflow.tsx files. On file change:
- *   1. Compile through Babel plugin → extract IR
- *   2. Diff IR against last known state
- *   3. Notify connected frontends via WebSocket
- *   4. Optionally seed definitions to the dev API
- *
- * Usage (programmatic):
- *   import { createDevServer } from '@mindmatrix/react-compiler';
- *   const server = await createDevServer({ port: 5199 });
- *   // ... server.close() to stop
- *
- * Usage (CLI):
- *   mmrc dev --port 5199 --src src/workflows --seed
- */
-
-import type { ViteDevServer, InlineConfig } from 'vite';
-import { mindmatrixReact, type MindMatrixReactOptions } from './vite';
-import { build, type BuildResult } from './cli/build';
-
-/** Minimal WebSocket interface — avoids requiring @types/ws at compile time */
-interface WsClient {
-  readyState: number;
-  send(data: string): void;
-  close(): void;
-  on(event: string, listener: (...args: unknown[]) => void): void;
-}
-
-export interface DevServerOptions {
-  /** Port for the dev server. Default: 5199 */
-  port?: number;
-  /** Source directory to watch. Default: 'src/workflows' */
-  src?: string;
-  /** Compilation mode. Default: 'infer' */
-  mode?: 'strict' | 'infer';
-  /** Glob patterns for workflow files. Default: ['**\/*.workflow.tsx'] */
-  include?: string[];
-  /** Output directory for .workflow.json sidecar files. Default: 'dist/workflows' */
-  outDir?: string;
-  /** Seed compiled definitions to the dev API on change. Default: false */
-  seed?: boolean;
-  /** Dev API base URL. Default: 'http://localhost:4200/api/v1' */
-  apiUrl?: string;
-  /** Auth token for dev API. Default: reads from MINDMATRIX_TOKEN env */
-  authToken?: string;
-  /** Enable WebSocket notification channel. Default: true */
-  ws?: boolean;
-  /** Open browser on start. Default: false */
-  open?: boolean;
-}
-
-export interface DevServerInstance {
-  /** The underlying Vite dev server */
-  vite: ViteDevServer;
-  /** Port the server is running on */
-  port: number;
-  /** Connected WebSocket clients */
-  clients: Set<WsClient>;
-  /** Trigger a full rebuild of all workflow files */
-  rebuild: () => Promise<BuildResult>;
-  /** Stop the dev server */
-  close: () => Promise<void>;
-}
-
-/**
- * Create and start a MindMatrix dev server.
- *
- * This is a thin Vite server configured with the mindmatrixReact plugin,
- * plus a WebSocket channel that pushes compile events to connected editors.
- */
-export async function createDevServer(options: DevServerOptions = {}): Promise<DevServerInstance> {
-  const {
-    port = 5199,
-    src = 'src/workflows',
-    mode = 'infer',
-    include = ['**/*.workflow.tsx'],
-    outDir = 'dist/workflows',
-    seed = false,
-    apiUrl = 'http://localhost:4200/api/v1',
-    authToken = process.env.MINDMATRIX_TOKEN,
-    ws: enableWs = true,
-    open = false,
-  } = options;
-
-  const clients = new Set<WsClient>();
-
-  // Build the Vite plugin options
-  const pluginOptions: MindMatrixReactOptions = {
-    mode,
-    include,
-    outDir,
-    seedOnCompile: seed,
-    apiUrl,
-    authToken,
-  };
-
-  // Create a custom Vite plugin that intercepts compile results and broadcasts
-  const notifyPlugin = {
-    name: 'mindmatrix-dev-notify',
-    enforce: 'post' as const,
-
-    handleHotUpdate(ctx: { file: string; timestamp: number; modules: unknown[] }) {
-      const isWorkflow = include.some((pattern) => {
-        const regex = pattern
-          .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-          .replace(/\*\*/g, '<<GLOBSTAR>>')
-          .replace(/\*/g, '[^/]*')
-          .replace(/<<GLOBSTAR>>/g, '.*')
-          .replace(/\?/g, '.');
-        return new RegExp(regex).test(ctx.file);
-      });
-
-      if (!isWorkflow) return;
-
-      // Broadcast compile event to all connected WebSocket clients
-      const message = JSON.stringify({
-        type: 'workflow:compiled',
-        file: ctx.file,
-        timestamp: ctx.timestamp,
-      });
-
-      for (const client of clients) {
-        try {
-          if (client.readyState === 1 /* WebSocket.OPEN */) {
-            client.send(message);
-          }
-        } catch {
-          clients.delete(client);
-        }
-      }
-
-      console.log(`[mm-dev] Compiled ${ctx.file.split('/').pop()} — notified ${clients.size} client(s)`);
-    },
-  };
-
-  // Vite config
-  const viteConfig: InlineConfig = {
-    root: process.cwd(),
-    server: {
-      port,
-      open,
-      host: true,
-    },
-    plugins: [
-      mindmatrixReact(pluginOptions),
-      notifyPlugin,
-    ],
-    logLevel: 'info',
-  };
-
-  // Dynamically import Vite to avoid requiring it at module load time
-  const { createServer } = await import('vite');
-  const vite = await createServer(viteConfig);
-  await vite.listen();
-
-  const resolvedPort = vite.config.server.port ?? port;
-
-  // Set up WebSocket server for definition sync
-  if (enableWs && vite.httpServer) {
-    try {
-      // Dynamic import — ws is optional, only needed at runtime
-      // eslint-disable-next-line @typescript-eslint/no-var-requires
-      const wsModule: any = await (Function('return import("ws")')() as Promise<any>);
-      const WebSocketServer = wsModule.WebSocketServer ?? wsModule.default?.WebSocketServer;
-      if (WebSocketServer) {
-        const wss = new WebSocketServer({
-          server: vite.httpServer,
-          path: '/__mm_dev',
-        });
-
-        wss.on('connection', (socket: WsClient) => {
-          clients.add(socket);
-          console.log(`[mm-dev] Editor connected (${clients.size} total)`);
-
-          socket.on('close', () => {
-            clients.delete(socket);
-            console.log(`[mm-dev] Editor disconnected (${clients.size} total)`);
-          });
-
-          socket.send(JSON.stringify({
-            type: 'mm:connected',
-            version: '0.1.0',
-            capabilities: ['compile', 'seed', 'notify'],
-          }));
-        });
-      }
-    } catch {
-      console.warn('[mm-dev] ws package not available — WebSocket notifications disabled');
-    }
-  }
-
-  console.log(`\n[mm-dev] MindMatrix Dev Server running`);
-  console.log(`  Local:     http://localhost:${resolvedPort}`);
-  console.log(`  WebSocket: ws://localhost:${resolvedPort}/__mm_dev`);
-  console.log(`  Watching:  ${src} (${include.join(', ')})`);
-  if (seed) {
-    console.log(`  Seeding:   ${apiUrl}`);
-  }
-  console.log();
-
-  return {
-    vite,
-    port: resolvedPort,
-    clients,
-
-    async rebuild(): Promise<BuildResult> {
-      console.log('[mm-dev] Full rebuild triggered...');
-      const result = await build({ src, outDir, mode });
-
-      const message = JSON.stringify({
-        type: 'workflow:rebuild',
-        compiled: result.compiled,
-        errors: result.errors,
-        timestamp: Date.now(),
-      });
-      for (const client of clients) {
-        try {
-          if (client.readyState === 1) client.send(message);
-        } catch {
-          clients.delete(client);
-        }
-      }
-
-      return result;
-    },
-
-    async close(): Promise<void> {
-      for (const client of clients) {
-        try { client.close(); } catch { /* ignore */ }
-      }
-      clients.clear();
-      await vite.close();
-      console.log('[mm-dev] Server stopped');
-    },
-  };
-}

package/src/envelope/fs-tree.ts

@@ -1,217 +0,0 @@
-/**
- * File System Tree — generates a manifest of project files with roles and hashes.
- *
- * The fs.tree is the first component of the source envelope.
- * It maps every source file to its role in the workflow project.
- *
- * Roles:
- * - view-entry: .workflow.tsx files (main workflow components)
- * - model: models/*.ts files (workflow definitions)
- * - server-action: *.server.ts files (backend action handlers)
- * - layout: layout.tsx files (route layout boundaries)
- * - page: page.tsx files (route page components)
- * - config: mm.config.ts, blueprint.config.ts
- * - component: regular .tsx components used by workflows
- * - asset: static assets (images, styles, etc.)
- * - unknown: unclassified files
- */
-
-import { createHash } from 'crypto';
-import { readFileSync, statSync } from 'fs';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export type FileRole =
-  | 'view-entry'
-  | 'model'
-  | 'server-action'
-  | 'layout'
-  | 'page'
-  | 'config'
-  | 'component'
-  | 'test'
-  | 'asset'
-  | 'unknown';
-
-export interface FsTreeEntry {
-  /** Relative path from project root. */
-  path: string;
-  /** File role in the workflow project. */
-  role: FileRole;
-  /** SHA-256 content hash. */
-  hash: string;
-  /** File size in bytes. */
-  size: number;
-  /** Last modified timestamp. */
-  mtime: string;
-  /** Workflow slug (for view-entry and model files). */
-  slug?: string;
-}
-
-export interface FsTree {
-  /** fs.tree format version. */
-  version: 1;
-  /** Project root directory (absolute). */
-  root: string;
-  /** Timestamp when the tree was generated. */
-  generatedAt: string;
-  /** File entries. */
-  entries: FsTreeEntry[];
-  /** Summary statistics. */
-  summary: {
-    totalFiles: number;
-    byRole: Record<FileRole, number>;
-    totalSize: number;
-  };
-}
-
-// =============================================================================
-// Role Detection
-// =============================================================================
-
-/**
- * Determines the role of a file based on its path and naming convention.
- */
-export function detectFileRole(relativePath: string): FileRole {
-  const path = relativePath.toLowerCase();
-
-  // Test files
-  if (path.includes('.test.') || path.includes('.spec.') || path.includes('__tests__/')) {
-    return 'test';
-  }
-
-  // Workflow view entries
-  if (/\.workflow\.(tsx?|jsx?)$/.test(path)) {
-    return 'view-entry';
-  }
-
-  // Model files
-  if ((path.includes('/models/') || path.startsWith('models/')) && /\.(ts|tsx)$/.test(path)) {
-    return 'model';
-  }
-
-  // Server action files
-  if (/\.server\.(ts|tsx|js|jsx)$/.test(path)) {
-    return 'server-action';
-  }
-
-  // Layout files
-  if (/\/layout\.(tsx?|jsx?)$/.test(path)) {
-    return 'layout';
-  }
-
-  // Page files
-  if (/\/page\.(tsx?|jsx?)$/.test(path)) {
-    return 'page';
-  }
-
-  // Config files
-  if (/mm\.config\.(ts|js)$/.test(path) || /blueprint\.config\.(ts|js)$/.test(path)) {
-    return 'config';
-  }
-
-  // Component files
-  if (/\.(tsx|jsx)$/.test(path)) {
-    return 'component';
-  }
-
-  // Asset files
-  if (/\.(css|scss|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)$/.test(path)) {
-    return 'asset';
-  }
-
-  return 'unknown';
-}
-
-// =============================================================================
-// Tree Generation
-// =============================================================================
-
-/**
- * Generates an FsTree from a list of file paths.
- */
-export function generateFsTree(files: string[], rootDir: string): FsTree {
-  const entries: FsTreeEntry[] = [];
-  let totalSize = 0;
-  const byRole: Record<string, number> = {};
-
-  for (const file of files) {
-    try {
-      const content = readFileSync(file);
-      const stat = statSync(file);
-      const hash = createHash('sha256').update(content).digest('hex');
-      const relativePath = file.startsWith(rootDir)
-        ? file.slice(rootDir.length).replace(/^\//, '')
-        : file;
-      const role = detectFileRole(relativePath);
-
-      const entry: FsTreeEntry = {
-        path: relativePath,
-        role,
-        hash,
-        size: stat.size,
-        mtime: stat.mtime.toISOString(),
-      };
-
-      entries.push(entry);
-      totalSize += stat.size;
-      byRole[role] = (byRole[role] || 0) + 1;
-    } catch {
-      // Skip files that can't be read
-    }
-  }
-
-  return {
-    version: 1,
-    root: rootDir,
-    generatedAt: new Date().toISOString(),
-    entries,
-    summary: {
-      totalFiles: entries.length,
-      byRole: byRole as Record<FileRole, number>,
-      totalSize,
-    },
-  };
-}
-
-/**
- * Filters an FsTree to only include specific roles.
- */
-export function filterByRole(tree: FsTree, roles: FileRole[]): FsTreeEntry[] {
-  return tree.entries.filter((e) => roles.includes(e.role));
-}
-
-/**
- * Finds changed files between two FsTree snapshots.
- */
-export function diffFsTrees(before: FsTree, after: FsTree): {
-  added: FsTreeEntry[];
-  removed: FsTreeEntry[];
-  modified: FsTreeEntry[];
-} {
-  const beforeMap = new Map(before.entries.map((e) => [e.path, e]));
-  const afterMap = new Map(after.entries.map((e) => [e.path, e]));
-
-  const added: FsTreeEntry[] = [];
-  const removed: FsTreeEntry[] = [];
-  const modified: FsTreeEntry[] = [];
-
-  for (const [path, entry] of afterMap) {
-    const prev = beforeMap.get(path);
-    if (!prev) {
-      added.push(entry);
-    } else if (prev.hash !== entry.hash) {
-      modified.push(entry);
-    }
-  }
-
-  for (const [path, entry] of beforeMap) {
-    if (!afterMap.has(path)) {
-      removed.push(entry);
-    }
-  }
-
-  return { added, removed, modified };
-}

package/src/envelope/source-envelope.ts

@@ -1,264 +0,0 @@
-/**
- * Source Envelope — bundles compiled workflows with source metadata.
- *
- * A source envelope is the unit of deployment. It contains:
- * 1. All compiled workflow definitions (IR)
- * 2. File manifest (fs.tree) with content hashes
- * 3. Source bindings (semantic refs ↔ file spans)
- * 4. Deployment metadata (version, timestamp, environment)
- *
- * The envelope enables:
- * - Immutable versioning (content-addressed)
- * - Source-level debugging (map IR back to .tsx source)
- * - Differential deployment (only deploy changed workflows)
- * - P2P sync (envelope is the unit of transfer)
- */
-
-import { createHash } from 'crypto';
-import type { IRWorkflowDefinition } from '@mindmatrix/player-core';
-import type { FsTree } from './fs-tree';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface SourceEnvelope {
-  /** Envelope format version. */
-  version: 1;
-  /** Content-addressed envelope ID (SHA-256 of canonical content). */
-  envelopeId: string;
-  /** Blueprint slug this envelope belongs to. */
-  blueprintSlug: string;
-  /** Blueprint version. */
-  blueprintVersion: string;
-  /** When the envelope was created. */
-  createdAt: string;
-  /** Deployment target environment. */
-  environment?: string;
-  /** Compiled workflow definitions. */
-  definitions: IRWorkflowDefinition[];
-  /** File manifest. */
-  fsTree: FsTree;
-  /** Source bindings (IR element → source location). */
-  sourceBindings: SourceBinding[];
-  /** Deployment metadata. */
-  metadata: EnvelopeMetadata;
-}
-
-/**
- * Maps an IR element to its source location.
- */
-export interface SourceBinding {
-  /** Type of IR element. */
-  kind: 'field' | 'state' | 'transition' | 'action' | 'component' | 'grammar-island';
-  /** Name/ID of the element. */
-  name: string;
-  /** Workflow slug this binding belongs to. */
-  workflowSlug: string;
-  /** Source file path (relative). */
-  file: string;
-  /** Start line (1-based). */
-  startLine: number;
-  /** Start column (0-based). */
-  startColumn: number;
-  /** End line (1-based). */
-  endLine?: number;
-  /** End column (0-based). */
-  endColumn?: number;
-}
-
-/**
- * Deployment metadata.
- */
-export interface EnvelopeMetadata {
-  /** Total number of workflow definitions. */
-  definitionCount: number;
-  /** Total number of fields across all definitions. */
-  totalFields: number;
-  /** Total number of states across all definitions. */
-  totalStates: number;
-  /** Total number of transitions across all definitions. */
-  totalTransitions: number;
-  /** Compiler version. */
-  compilerVersion: string;
-  /** Build mode. */
-  mode: 'strict' | 'infer';
-  /** Whether any errors were detected. */
-  hasErrors: boolean;
-  /** Error/warning summary. */
-  diagnostics: DiagnosticSummary;
-}
-
-export interface DiagnosticSummary {
-  errors: number;
-  warnings: number;
-  errorCodes: string[];
-}
-
-// =============================================================================
-// Envelope Creation
-// =============================================================================
-
-/**
- * Creates a source envelope from compiled definitions.
- */
-export function createSourceEnvelope(params: {
-  blueprintSlug: string;
-  blueprintVersion: string;
-  definitions: IRWorkflowDefinition[];
-  fsTree: FsTree;
-  sourceBindings?: SourceBinding[];
-  environment?: string;
-  mode?: 'strict' | 'infer';
-  compilerVersion?: string;
-}): SourceEnvelope {
-  const {
-    blueprintSlug,
-    blueprintVersion,
-    definitions,
-    fsTree,
-    sourceBindings = [],
-    environment,
-    mode = 'infer',
-    compilerVersion = '0.1.0',
-  } = params;
-
-  // Compute metadata
-  let totalFields = 0;
-  let totalStates = 0;
-  let totalTransitions = 0;
-  let hasErrors = false;
-  const errorCodes = new Set<string>();
-  let errorCount = 0;
-  let warningCount = 0;
-
-  for (const def of definitions) {
-    totalFields += def.fields.length;
-    totalStates += def.states.length;
-    totalTransitions += def.transitions.length;
-
-    const errors = (def.metadata as any)?.errors;
-    const warnings = (def.metadata as any)?.warnings;
-
-    if (errors && errors.length > 0) {
-      hasErrors = true;
-      errorCount += errors.length;
-      for (const e of errors) {
-        errorCodes.add(e.code);
-      }
-    }
-
-    if (warnings && warnings.length > 0) {
-      warningCount += warnings.length;
-    }
-  }
-
-  const metadata: EnvelopeMetadata = {
-    definitionCount: definitions.length,
-    totalFields,
-    totalStates,
-    totalTransitions,
-    compilerVersion,
-    mode,
-    hasErrors,
-    diagnostics: {
-      errors: errorCount,
-      warnings: warningCount,
-      errorCodes: Array.from(errorCodes),
-    },
-  };
-
-  // Build envelope (without ID first, then compute ID)
-  const envelope: SourceEnvelope = {
-    version: 1,
-    envelopeId: '', // computed below
-    blueprintSlug,
-    blueprintVersion,
-    createdAt: new Date().toISOString(),
-    environment,
-    definitions,
-    fsTree,
-    sourceBindings,
-    metadata,
-  };
-
-  // Compute content-addressed ID
-  envelope.envelopeId = computeEnvelopeId(envelope);
-
-  return envelope;
-}
-
-/**
- * Computes a content-addressed ID for an envelope.
- * Uses SHA-256 of the canonical JSON (sorted keys, no whitespace).
- */
-export function computeEnvelopeId(envelope: SourceEnvelope): string {
-  const canonical = {
-    blueprintSlug: envelope.blueprintSlug,
-    blueprintVersion: envelope.blueprintVersion,
-    definitions: envelope.definitions.map((d) => ({
-      slug: d.slug,
-      version: d.version,
-      fields: d.fields.length,
-      states: d.states.length,
-      transitions: d.transitions.length,
-    })),
-    fileHashes: envelope.fsTree.entries.map((e) => e.hash).sort(),
-  };
-
-  return createHash('sha256')
-    .update(JSON.stringify(canonical))
-    .digest('hex')
-    .substring(0, 32);
-}
-
-// =============================================================================
-// Comparison
-// =============================================================================
-
-/**
- * Checks if two envelopes have the same content (ignoring timestamps).
- */
-export function envelopesEqual(a: SourceEnvelope, b: SourceEnvelope): boolean {
-  return computeEnvelopeId(a) === computeEnvelopeId(b);
-}
-
-/**
- * Finds definitions that changed between two envelopes.
- */
-export function diffEnvelopes(
-  before: SourceEnvelope,
-  after: SourceEnvelope
-): {
-  added: string[];
-  removed: string[];
-  modified: string[];
-  unchanged: string[];
-} {
-  const beforeSlugs = new Map(before.definitions.map((d) => [d.slug, d]));
-  const afterSlugs = new Map(after.definitions.map((d) => [d.slug, d]));
-
-  const added: string[] = [];
-  const removed: string[] = [];
-  const modified: string[] = [];
-  const unchanged: string[] = [];
-
-  for (const [slug, def] of afterSlugs) {
-    const prev = beforeSlugs.get(slug);
-    if (!prev) {
-      added.push(slug);
-    } else if (JSON.stringify(prev) !== JSON.stringify(def)) {
-      modified.push(slug);
-    } else {
-      unchanged.push(slug);
-    }
-  }
-
-  for (const slug of beforeSlugs.keys()) {
-    if (!afterSlugs.has(slug)) {
-      removed.push(slug);
-    }
-  }
-
-  return { added, removed, modified, unchanged };
-}