@mmapp/react-compiler 0.1.0-alpha.1

package/src/cli/lock-file.ts

@@ -0,0 +1,94 @@
+/**
+ * mm.lock — Lock file management for installed workflow packages.
+ *
+ * Simple JSON lock file that tracks installed packages, versions, and modes.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+
+export interface LockEntry {
+  slug: string;
+  version: string;
+  installedAt: string;
+  mode: 'type-only' | 'full';
+  hash: string;
+}
+
+export type LockData = Record<string, LockEntry>;
+
+const LOCK_FILENAME = 'mm.lock';
+
+/**
+ * Read the lock file from the given directory.
+ * Returns an empty object if the lock file doesn't exist.
+ */
+export function readLockFile(dir: string): LockData {
+  const lockPath = join(dir, LOCK_FILENAME);
+  if (!existsSync(lockPath)) {
+    return {};
+  }
+
+  try {
+    const content = readFileSync(lockPath, 'utf-8');
+    return JSON.parse(content) as LockData;
+  } catch {
+    // Corrupted lock file — start fresh
+    return {};
+  }
+}
+
+/**
+ * Write the lock file to the given directory.
+ */
+export function writeLockFile(dir: string, entries: LockData): void {
+  const lockPath = join(dir, LOCK_FILENAME);
+
+  // Sort keys for deterministic output
+  const sorted: LockData = {};
+  for (const key of Object.keys(entries).sort()) {
+    sorted[key] = entries[key];
+  }
+
+  writeFileSync(lockPath, JSON.stringify(sorted, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Add or update a lock entry.
+ */
+export function upsertLockEntry(
+  dir: string,
+  slug: string,
+  version: string,
+  mode: 'type-only' | 'full',
+  content: string,
+): void {
+  const entries = readLockFile(dir);
+  entries[slug] = {
+    slug,
+    version,
+    installedAt: new Date().toISOString(),
+    mode,
+    hash: computeHash(content),
+  };
+  writeLockFile(dir, entries);
+}
+
+/**
+ * Remove a lock entry.
+ */
+export function removeLockEntry(dir: string, slug: string): boolean {
+  const entries = readLockFile(dir);
+  if (!(slug in entries)) return false;
+  delete entries[slug];
+  writeLockFile(dir, entries);
+  return true;
+}
+
+/**
+ * Compute a content hash for change detection.
+ */
+export function computeHash(content: string): string {
+  return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}

package/src/cli/mmrc.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * mmrc — MindMatrix React Compiler CLI
+ *
+ * This is an alias entry point. The actual CLI logic lives in ./index.ts.
+ *
+ * Commands:
+ *   mmrc dev      Start dev server with hot reload
+ *   mmrc build    Compile workflow files to Pure Form IR
+ *   mmrc test     Run workflow test files
+ *   mmrc deploy   Compile + upload workflows to backend DB
+ *   mmrc pull     Fetch a definition from DB and scaffold local project
+ *   mmrc install  <slug>         Install a workflow definition (type-only by default)
+ *   mmrc install  <slug> --full  Install with full source code
+ *   mmrc list                    List installed workflow packages
+ *   mmrc update                  Update all installed packages
+ *   mmrc remove   <slug>         Remove an installed package
+ *   mmrc search   <query>        Search available definitions
+ */
+
+// Re-export from main CLI entry point
+import './index';

package/src/cli/pull.ts

@@ -0,0 +1,172 @@
+/**
+ * CLI Pull Command — fetches a workflow definition from DB and scaffolds
+ * a local React framework project.
+ *
+ * Usage:
+ *   mmrc pull <slug> --api-url http://... --token TOKEN --out ./my-project
+ *
+ * Pipeline:
+ *   GET /api/v1/workflow/definitions?slug=<slug>
+ *     → IRWorkflowDefinition
+ *     → project-decompiler
+ *     → local files (mm.config.ts, main.workflow.tsx, pages/, models/)
+ */
+
+import { mkdirSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { decompileProjectEnhanced as decompileProject } from '../decompiler/project-decompiler';
+import type { IRWorkflowDefinition } from '@mindmatrix/player-core';
+
+export interface PullOptions {
+  slug: string;
+  apiUrl: string;
+  token: string;
+  outDir?: string;
+}
+
+export interface PullResult {
+  slug: string;
+  filesWritten: string[];
+  outDir: string;
+}
+
+export async function pull(options: PullOptions): Promise<PullResult> {
+  const { slug, apiUrl, token } = options;
+  const outDir = options.outDir ?? slug;
+
+  console.log(`[mmrc pull] Fetching "${slug}" from ${apiUrl}...`);
+
+  // 1. Fetch the definition from the API
+  const ir = await fetchDefinition(apiUrl, token, slug);
+  if (!ir) {
+    throw new Error(`Definition "${slug}" not found`);
+  }
+
+  console.log(`  Found: ${ir.name || ir.slug} (${ir.category || 'workflow'}, v${ir.version || '1.0.0'})`);
+  console.log(`  Fields: ${ir.fields?.length ?? 0}, States: ${ir.states?.length ?? 0}, Transitions: ${ir.transitions?.length ?? 0}`);
+
+  // 2. Decompile to project files
+  const result = decompileProject(ir);
+
+  // 3. Write files to disk
+  mkdirSync(outDir, { recursive: true });
+  const filesWritten: string[] = [];
+
+  for (const file of result.files) {
+    const filePath = join(outDir, file.path);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, file.content, 'utf-8');
+    filesWritten.push(file.path);
+    console.log(`  + ${file.path}`);
+  }
+
+  console.log(`\n[mmrc pull] Scaffolded ${filesWritten.length} files in ${outDir}/`);
+  console.log(`  Entry: ${result.entryFile}`);
+  console.log(`\n  Next steps:`);
+  console.log(`    cd ${outDir}`);
+  console.log(`    mmrc dev --src .`);
+  console.log(`    # Edit files, then deploy back:`);
+  console.log(`    mmrc deploy --src . --api-url ${apiUrl} --token <token>`);
+
+  return { slug, filesWritten, outDir };
+}
+
+// =============================================================================
+// API fetch
+// =============================================================================
+
+async function fetchDefinition(
+  apiUrl: string,
+  token: string,
+  slug: string,
+): Promise<IRWorkflowDefinition | null> {
+  // Try by slug first
+  const bySlug = await tryFetch(`${apiUrl}/workflow/definitions?slug=${encodeURIComponent(slug)}`, token);
+  if (bySlug) return bySlug;
+
+  // Try the definitions endpoint with search
+  const bySearch = await tryFetch(`${apiUrl}/workflow/catalog/search?q=${encodeURIComponent(slug)}`, token);
+  if (bySearch) return bySearch;
+
+  // Try modules endpoint (for category=module definitions)
+  const modulesRes = await fetch(`${apiUrl}/modules`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (modulesRes.ok) {
+    const modules = await modulesRes.json() as any[];
+    const mod = modules.find((m: any) => m.module_id === slug || m.name?.toLowerCase() === slug.toLowerCase());
+    if (mod) {
+      // Re-fetch the full definition by ID
+      const fullRes = await fetch(`${apiUrl}/workflow/definitions/${mod.module_id}`, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      if (fullRes.ok) {
+        return normalizeApiResponse(await fullRes.json());
+      }
+    }
+  }
+
+  return null;
+}
+
+async function tryFetch(url: string, token: string): Promise<IRWorkflowDefinition | null> {
+  try {
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) return null;
+
+    const data = await res.json() as any;
+
+    // Handle array responses (search/list endpoints)
+    if (Array.isArray(data)) {
+      if (data.length === 0) return null;
+      return normalizeApiResponse(data[0]);
+    }
+
+    // Handle paginated responses (items or data key)
+    const items = data.items ?? data.data;
+    if (items && Array.isArray(items)) {
+      if (items.length === 0) return null;
+      return normalizeApiResponse(items[0]);
+    }
+
+    // Direct object
+    return normalizeApiResponse(data);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Normalize API response to IRWorkflowDefinition shape.
+ * Backend uses `view` for experience tree, IR uses `metadata.experience`.
+ */
+function normalizeApiResponse(def: any): IRWorkflowDefinition {
+  const ir: any = {
+    slug: def.slug,
+    name: def.name,
+    version: def.version || '1.0.0',
+    description: def.description || '',
+    category: def.category || 'workflow',
+    fields: def.fields || [],
+    states: def.states || [],
+    transitions: def.transitions || [],
+    roles: def.roles || [],
+    on_event: def.on_event || [],
+    metadata: {
+      ...(def.metadata || {}),
+    },
+  };
+
+  // The experience tree may be in `view`, `experience`, or `metadata.experience`
+  // Must set ir.experience at top level — the decompiler checks definition.experience
+  const experience = def.view || def.experience || def.metadata?.experience;
+  if (experience) {
+    ir.experience = experience;
+    ir.metadata.experience = experience;
+    ir.view = experience;
+  }
+
+  return ir as IRWorkflowDefinition;
+}

package/src/cli/registry-client.ts

@@ -0,0 +1,175 @@
+/**
+ * Registry client — fetches workflow definitions from the MindMatrix API.
+ * Uses native fetch (Node 18+). No external dependencies.
+ */
+
+export interface RegistryConfig {
+  apiUrl: string;
+  authToken?: string;
+}
+
+export interface WorkflowDefinitionResponse {
+  id?: string;
+  slug: string;
+  name: string;
+  version: string;
+  description?: string;
+  category: string;
+  fields: Array<{
+    name: string;
+    type: string;
+    typeVersion?: string;
+    baseType?: string;
+    label?: string;
+    required?: boolean;
+    default_value?: unknown;
+    computed?: string;
+    computed_deps?: string[];
+    validation?: {
+      enum?: string[];
+      min?: number;
+      max?: number;
+      pattern?: string;
+    };
+  }>;
+  states: Array<{
+    name: string;
+    type: string;
+    description?: string;
+  }>;
+  transitions: Array<{
+    name: string;
+    from: string[];
+    to: string;
+    description?: string;
+    roles?: string[];
+    auto?: boolean;
+    required_fields?: string[];
+  }>;
+  roles?: Array<{ name: string; description?: string }>;
+  metadata?: Record<string, unknown>;
+  experience?: unknown;
+  view?: unknown;
+}
+
+function buildHeaders(config: RegistryConfig): Record<string, string> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+  if (config.authToken) {
+    headers['Authorization'] = `Bearer ${config.authToken}`;
+  }
+  return headers;
+}
+
+function extractDefinition(data: unknown): WorkflowDefinitionResponse | null {
+  if (!data || typeof data !== 'object') return null;
+
+  // Handle array responses
+  if (Array.isArray(data)) {
+    return data.length > 0 ? (data[0] as WorkflowDefinitionResponse) : null;
+  }
+
+  const obj = data as Record<string, unknown>;
+
+  // Handle paginated responses
+  const items = obj.items ?? obj.data;
+  if (items && Array.isArray(items)) {
+    return items.length > 0 ? (items[0] as WorkflowDefinitionResponse) : null;
+  }
+
+  // Direct object — must have slug
+  if ('slug' in obj) {
+    return obj as unknown as WorkflowDefinitionResponse;
+  }
+
+  return null;
+}
+
+function extractDefinitions(data: unknown): WorkflowDefinitionResponse[] {
+  if (!data || typeof data !== 'object') return [];
+
+  if (Array.isArray(data)) {
+    return data as WorkflowDefinitionResponse[];
+  }
+
+  const obj = data as Record<string, unknown>;
+  const items = obj.items ?? obj.data;
+  if (items && Array.isArray(items)) {
+    return items as WorkflowDefinitionResponse[];
+  }
+
+  if ('slug' in obj) {
+    return [obj as unknown as WorkflowDefinitionResponse];
+  }
+
+  return [];
+}
+
+/**
+ * Fetch a single workflow definition by slug.
+ */
+export async function fetchDefinition(
+  slug: string,
+  config: RegistryConfig,
+): Promise<WorkflowDefinitionResponse> {
+  const url = `${config.apiUrl}/workflow/definitions?slug=${encodeURIComponent(slug)}`;
+
+  let res: Response;
+  try {
+    res = await fetch(url, { headers: buildHeaders(config) });
+  } catch (err) {
+    throw new Error(
+      `Failed to connect to registry at ${config.apiUrl}. ` +
+      `Is the API server running? (${err instanceof Error ? err.message : String(err)})`,
+    );
+  }
+
+  if (!res.ok) {
+    if (res.status === 401) {
+      throw new Error('Authentication required. Provide --token or set MM_AUTH_TOKEN.');
+    }
+    if (res.status === 404) {
+      throw new Error(`Definition "${slug}" not found in registry.`);
+    }
+    throw new Error(`Registry returned ${res.status}: ${res.statusText}`);
+  }
+
+  const data = await res.json();
+  const def = extractDefinition(data);
+  if (!def) {
+    throw new Error(`Definition "${slug}" not found in registry.`);
+  }
+
+  return def;
+}
+
+/**
+ * Search definitions by query string.
+ */
+export async function searchDefinitions(
+  query: string,
+  config: RegistryConfig,
+): Promise<WorkflowDefinitionResponse[]> {
+  const url = `${config.apiUrl}/workflow/catalog/definitions?search=${encodeURIComponent(query)}`;
+
+  let res: Response;
+  try {
+    res = await fetch(url, { headers: buildHeaders(config) });
+  } catch (err) {
+    throw new Error(
+      `Failed to connect to registry at ${config.apiUrl}. ` +
+      `Is the API server running? (${err instanceof Error ? err.message : String(err)})`,
+    );
+  }
+
+  if (!res.ok) {
+    if (res.status === 401) {
+      throw new Error('Authentication required. Provide --token or set MM_AUTH_TOKEN.');
+    }
+    throw new Error(`Registry returned ${res.status}: ${res.statusText}`);
+  }
+
+  const data = await res.json();
+  return extractDefinitions(data);
+}