@sprig-and-prose/sprig-universe 0.1.0

package/src/cli.js

@@ -0,0 +1,1510 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview CLI for Sprig universe parser
+ */
+
+import { readFileSync, writeFileSync, statSync, readdirSync, mkdirSync, existsSync } from 'fs';
+import { join, resolve, dirname, relative } from 'path';
+import { fileURLToPath } from 'url';
+import { parseFiles, parseText } from './index.js';
+import { convertToSceneManifest, convertFilesToSceneManifest } from './scene-manifest.js';
+import { validateScenes } from './validator.js';
+import chokidar from 'chokidar';
+import { globSync } from 'glob';
+
+// Get the directory where this CLI script is located (sprig-universe package root)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = resolve(__dirname, '..');
+
+const DEFAULT_EXCLUDES = ['.sprig/**', 'dist/**', 'node_modules/**', '.git/**'];
+
+function printGlobalHelp() {
+  console.log('Usage: sprig-universe <command> [options]');
+  console.log('Commands:');
+  console.log('  compile           Compile universe and scene files to manifests');
+  console.log('  watch             Watch universe and scene files and recompile on change');
+  console.log('  check:references  Validate repository references');
+  console.log('  validate          Validate scene file sources');
+  console.log('  parse             Parse files (legacy command)');
+  console.log('');
+  console.log('Run: sprig-universe <command> --help for command-specific help.');
+}
+
+function printCompileHelp() {
+  console.log('Usage: sprig-universe compile [--root <path>] [--quiet]');
+  console.log('');
+  console.log('Compiles universe files and scene files to JSON manifests.');
+  console.log('');
+  console.log('Discovery:');
+  console.log('  - Walks upward from current directory (or --root) to find universe.prose');
+  console.log('  - Loads all **/*.prose files under the discovered root');
+  console.log('  - Excludes: .sprig/**, dist/**, node_modules/**, .git/**');
+  console.log('  - Requires exactly one universe declaration across all files');
+  console.log('');
+  console.log('Output:');
+  console.log('  Universe manifest: <root>/.sprig/manifest.json');
+  console.log('  Scenes manifest: <root>/.sprig/scenes.json');
+  console.log('');
+  console.log('Options:');
+  console.log('  --root <path>    Override discovery start path (default: current directory)');
+  console.log('  --quiet          Suppress observable header output');
+}
+
+function printWatchHelp() {
+  console.log('Usage: sprig-universe watch [--root <path>] [--quiet]');
+  console.log('');
+  console.log('Watches universe and scene files and recompiles on change.');
+  console.log('');
+  console.log('Discovery:');
+  console.log('  - Walks upward from current directory (or --root) to find universe.prose');
+  console.log('  - Loads all **/*.prose files under the discovered root');
+  console.log('  - Excludes: .sprig/**, dist/**, node_modules/**, .git/**');
+  console.log('');
+  console.log('Options:');
+  console.log('  --root <path>    Override discovery start path (default: current directory)');
+  console.log('  --quiet          Suppress observable header output');
+}
+
+function printValidateHelp() {
+  console.log('Usage: sprig-universe validate [--root <path>] [--quiet]');
+  console.log('');
+  console.log('Validates scene sources against the compiled scenes manifest.');
+  console.log('Run "sprig-universe compile" first to generate the manifest.');
+  console.log('');
+  console.log('Manifest location: <root>/.sprig/scenes.json');
+  console.log('');
+  console.log('Options:');
+  console.log('  --root <path>    Override discovery start path (default: current directory)');
+  console.log('  --quiet          Suppress observable header output');
+}
+
+function printCheckReferencesHelp() {
+  console.log('Usage: sprig-universe check:references [--root <path>] [--quiet]');
+  console.log('');
+  console.log('Validates repository references in the universe manifest.');
+  console.log('');
+  console.log('Discovery:');
+  console.log('  - Walks upward from current directory (or --root) to find universe.prose');
+  console.log('  - Loads all **/*.prose files under the discovered root');
+  console.log('  - Excludes: .sprig/**, dist/**, node_modules/**, .git/**');
+  console.log('');
+  console.log('Options:');
+  console.log('  --root <path>    Override discovery start path (default: current directory)');
+  console.log('  --quiet          Suppress observable header output');
+}
+
+function printParseHelp() {
+  console.log('Usage: sprig-universe parse <fileOrDir> [--out <path>]');
+  console.log('');
+  console.log('Parses .prose files and prints the JSON graph (or writes to --out).');
+}
+
+function hasHelpFlag(args) {
+  return args.includes('--help') || args.includes('-h');
+}
+
+function resolveRootPath(args) {
+  const rootIndex = args.indexOf('--root');
+  if (rootIndex >= 0 && rootIndex + 1 < args.length) {
+    return resolve(args[rootIndex + 1]);
+  }
+  return process.cwd();
+}
+
+function hasQuietFlag(args) {
+  return args.includes('--quiet');
+}
+
+/**
+ * Validates that exactly one universe declaration exists in the parsed graph
+ * @param {any} graph - Parsed universe graph
+ * @returns {{ valid: boolean, universeName?: string, error?: string }}
+ */
+function validateUniverseCount(graph) {
+  const universeNames = Object.keys(graph.universes);
+  
+  if (universeNames.length === 0) {
+    return {
+      valid: false,
+      error: 'No universe declaration found. At least one universe declaration is required.',
+    };
+  }
+  
+  if (universeNames.length > 1) {
+    const fileList = Array.from(universeNames)
+      .map((name) => {
+        const universe = graph.universes[name];
+        const rootNode = graph.nodes[universe.root];
+        return rootNode?.source?.file || 'unknown';
+      })
+      .filter((file, index, arr) => arr.indexOf(file) === index) // unique files
+      .sort()
+      .join(', ');
+    return {
+      valid: false,
+      error: `Multiple distinct universes found: ${universeNames.join(', ')}. Files: ${fileList}. Exactly one universe declaration is required.`,
+    };
+  }
+  
+  return {
+    valid: true,
+    universeName: universeNames[0],
+  };
+}
+
+/**
+ * Prints observable header with universe info
+ * @param {string} universeName - Name of the universe
+ * @param {string} root - Root directory path
+ * @param {number} fileCount - Number of prose files loaded
+ */
+function printObservableHeader(universeName, root, fileCount) {
+  console.log(`Universe: ${universeName} (root: ${root})`);
+  console.log(`Loaded: ${fileCount} prose files`);
+  console.log(`Ignored: ${DEFAULT_EXCLUDES.join(', ')}`);
+}
+
+/**
+ * Walks upward from startPath to find universe.prose marker
+ * @param {string} startPath - Starting directory path
+ * @returns {string | null} - Path to directory containing universe.prose, or null if not found
+ */
+function discoverUniverseRoot(startPath) {
+  let current = resolve(startPath);
+  const root = resolve('/');
+
+  while (current !== root) {
+    const markerPath = join(current, 'universe.prose');
+    if (existsSync(markerPath) && statSync(markerPath).isFile()) {
+      return current;
+    }
+    current = dirname(current);
+  }
+
+  // Check root directory as well
+  const rootMarkerPath = join(root, 'universe.prose');
+  if (existsSync(rootMarkerPath) && statSync(rootMarkerPath).isFile()) {
+    return root;
+  }
+
+  return null;
+}
+
+/**
+ * Loads all .prose files under root with default excludes
+ * @param {string} root - Universe root directory
+ * @returns {string[]} - Array of prose file paths, sorted deterministically
+ */
+function loadProseFiles(root) {
+  const pattern = join(root, '**/*.prose');
+  const allFiles = globSync(pattern, {
+    absolute: true,
+    ignore: DEFAULT_EXCLUDES.map((exclude) => join(root, exclude)),
+  });
+
+  // Sort for deterministic ordering
+  return allFiles.sort();
+}
+
+/**
+ * Recursively finds all .prose files in a directory
+ * @param {string} dir - Directory path
+ * @returns {string[]}
+ */
+function findSprigFiles(dir) {
+  const files = [];
+  const entries = readdirSync(dir);
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      files.push(...findSprigFiles(fullPath));
+    } else if (entry.endsWith('.prose')) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Recursively finds all .scene.prose files in a directory
+ * @param {string} dir - Directory path
+ * @returns {string[]}
+ */
+function findSceneFiles(dir) {
+  const files = [];
+  const entries = readdirSync(dir);
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      files.push(...findSceneFiles(fullPath));
+    } else if (entry.endsWith('.scene.prose')) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Validate repository kinds exist in repositories directory
+ * @param {Record<string, any>} repositories - Repository config
+ * @param {string} universeRoot - Universe root directory (unused, kept for API compatibility)
+ * @returns {boolean} - True if valid, false otherwise
+ */
+function validateRepositoryKinds(repositories, universeRoot) {
+  // Repositories are located in the sprig-universe package directory, not in the universe project
+  const repositoriesDir = join(PACKAGE_ROOT, 'repositories');
+  const errors = [];
+
+  for (const [repoName, repoConfig] of Object.entries(repositories)) {
+    const kind = repoConfig.kind;
+    if (!kind) {
+      errors.push(`Repository "${repoName}" has no kind specified`);
+      continue;
+    }
+
+    const kindDir = join(repositoriesDir, kind);
+    const indexFile = join(kindDir, 'index.js');
+
+    if (!existsSync(indexFile)) {
+      errors.push(`Repository kind "${kind}" not found. Expected: ${indexFile}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error('Error: Invalid repository configurations:');
+    for (const error of errors) {
+      console.error(`  - ${error}`);
+    }
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Validate repository references
+ * @param {any} graph - Parsed graph
+ * @param {Record<string, any>} repositories - Repository config
+ * @returns {boolean} - True if valid, false otherwise
+ */
+function validateReferences(graph, repositories) {
+  const repoKeys = new Set(Object.keys(repositories || {}));
+  /** @type {Map<string, { count: number, examples: Array<{ file: string, line: number }> }>} */
+  const unknownRepos = new Map();
+
+  for (const node of Object.values(graph.nodes)) {
+    if (!node.references) continue;
+
+    for (const ref of node.references) {
+      if (repoKeys.has(ref.repository)) continue;
+
+      const source = ref.source;
+      const entry = unknownRepos.get(ref.repository) || { count: 0, examples: [] };
+      entry.count += 1;
+
+      if (entry.examples.length < 3 && source?.file && source?.start?.line) {
+        entry.examples.push({ file: source.file, line: source.start.line });
+      }
+
+      unknownRepos.set(ref.repository, entry);
+    }
+  }
+
+  if (unknownRepos.size === 0) {
+    return true;
+  }
+
+  console.error('Error: Reference(s) to unknown repositories:');
+  for (const [repo, info] of unknownRepos.entries()) {
+    const exampleText =
+      info.examples.length > 0
+        ? ` (e.g. ${info.examples
+            .map((ex) => `${ex.file}:${ex.line}`)
+            .join(', ')})`
+        : '';
+    console.error(`  - ${repo}: ${info.count} occurrence(s)${exampleText}`);
+  }
+
+  return false;
+}
+
+/**
+ * Main CLI entry point
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  const command = args[0];
+
+  if (!command || command === '--help' || command === '-h') {
+    printGlobalHelp();
+    return;
+  }
+
+  const commandArgs = args.slice(1);
+  if (hasHelpFlag(commandArgs)) {
+    if (command === 'compile') {
+      printCompileHelp();
+      return;
+    }
+    if (command === 'watch') {
+      printWatchHelp();
+      return;
+    }
+    if (command === 'validate' || command === 'check') {
+      printValidateHelp();
+      return;
+    }
+    if (command === 'check:references') {
+      printCheckReferencesHelp();
+      return;
+    }
+    if (command === 'parse') {
+      printParseHelp();
+      return;
+    }
+  }
+
+  if (command === 'compile') {
+    handleCompile(commandArgs);
+    return;
+  }
+
+  if (command === 'check:references') {
+    handleCheckReferences(commandArgs);
+    return;
+  }
+
+  if (command === 'validate' || command === 'check') {
+    handleValidate(commandArgs);
+    return;
+  }
+
+  if (command === 'watch') {
+    handleWatch(commandArgs);
+    return;
+  }
+
+  if (command === 'parse') {
+    handleParse(commandArgs);
+    return;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  process.exit(1);
+}
+
+/**
+ * Get files to compile from config
+ * @param {any} universeConfig - Universe config section
+ * @param {string} configDir - Directory containing config file
+ * @returns {string[]} - Array of file paths
+ */
+function getFilesToCompile(universeConfig, configDir) {
+  // Support entries array (preferred) or single entry string (backward compat)
+  const entries = universeConfig.input?.entries;
+  const entry = universeConfig.input?.entry || universeConfig.entry;
+
+  // If both are provided, entries takes precedence
+  if (entries && entry) {
+    throw new Error('Cannot specify both "entry" and "entries" in universe config. Use "entries" array for multiple files.');
+  }
+
+  if (!entries && !entry) {
+    throw new Error('Missing "entry" or "entries" in universe config (expected universe.input.entry, universe.input.entries, universe.entry)');
+  }
+
+  const allFiles = new Set(); // Use Set to deduplicate
+
+  // Handle entries array (new format)
+  if (entries) {
+    if (!Array.isArray(entries)) {
+      throw new Error('"entries" must be an array of file paths or glob patterns');
+    }
+
+    // Process each entry in config order
+    // Ordering: preserve config order for explicit files, sort by path for glob results
+    for (const entryPattern of entries) {
+      const resolvedPattern = resolve(configDir, entryPattern);
+      let entryFiles = [];
+
+      try {
+        // Check if it's a glob pattern (contains *, ?, [, {, or **)
+        const isGlob = /[*?[{}]|\*\*/.test(entryPattern);
+        
+        if (isGlob) {
+          // Expand glob pattern
+          const globFiles = globSync(resolvedPattern, { absolute: true });
+          entryFiles = globFiles.filter((f) => f.endsWith('.prose'));
+        } else {
+          // Treat as file or directory path
+          const stat = statSync(resolvedPattern);
+          if (stat.isDirectory()) {
+            entryFiles = findSprigFiles(resolvedPattern);
+          } else if (stat.isFile()) {
+            if (resolvedPattern.endsWith('.prose')) {
+              entryFiles = [resolvedPattern];
+            }
+          } else {
+            throw new Error(`Entry path ${entryPattern} is not a file or directory`);
+          }
+        }
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          throw new Error(`Cannot read entry path ${entryPattern}: file or directory not found`);
+        }
+        throw new Error(`Cannot read entry path ${entryPattern}: ${error.message}`);
+      }
+
+      // Add files to set (deduplicates automatically)
+      for (const file of entryFiles) {
+        allFiles.add(file);
+      }
+    }
+
+    // Convert to array and sort for deterministic ordering
+    // Sort by path to ensure consistent output order
+    const sortedFiles = Array.from(allFiles).sort();
+    
+    if (sortedFiles.length === 0) {
+      throw new Error(`No .prose files found in entries: ${entries.join(', ')}`);
+    }
+
+    return sortedFiles;
+  }
+
+  // Handle single entry string (backward compat)
+  const entryPath = resolve(configDir, entry);
+  let files = [];
+
+  try {
+    const stat = statSync(entryPath);
+    if (stat.isDirectory()) {
+      files = findSprigFiles(entryPath);
+    } else if (stat.isFile()) {
+      files = [entryPath];
+    } else {
+      throw new Error(`Entry path ${entry} is not a file or directory`);
+    }
+  } catch (error) {
+    throw new Error(`Cannot read entry file ${entry}: ${error.message}`);
+  }
+
+  if (files.length === 0) {
+    throw new Error(`No .prose files found in ${entry}`);
+  }
+
+  return files;
+}
+
+/**
+ * Compile scene files to a single merged manifest
+ * @param {string} universeRoot - Universe root directory
+ * @param {boolean} silent - If true, don't print success message
+ * @returns {boolean} - True if successful, false otherwise
+ */
+function compileScenes(universeRoot, silent = false) {
+  // Use defaults relative to universe root
+  const inputDir = resolve(universeRoot, './sprig');
+  const outputDir = resolve(universeRoot, './.sprig');
+  const manifestPath = join(outputDir, 'scenes.json');
+
+  // Find all .scene.prose files in the input directory
+  let sceneFiles = [];
+  try {
+    if (statSync(inputDir).isDirectory()) {
+      sceneFiles = findSceneFiles(inputDir);
+    }
+  } catch (error) {
+    // Input directory doesn't exist, skip
+    return true;
+  }
+
+  if (sceneFiles.length === 0) {
+    return true; // No scene files found, nothing to do
+  }
+
+  // Ensure output directory exists
+  try {
+    mkdirSync(outputDir, { recursive: true });
+  } catch (error) {
+    // Directory might already exist, ignore
+  }
+
+  const fileASTs = [];
+  const errors = [];
+  const sceneNames = [];
+
+  // Parse all scene files
+  for (const sceneFile of sceneFiles) {
+    try {
+      const text = readFileSync(sceneFile, 'utf-8');
+      const ast = parseText(text, sceneFile);
+
+      // Only process if file contains scenes
+      if (ast.scenes && ast.scenes.length > 0) {
+        fileASTs.push(ast);
+        // Collect scene names for status message
+        for (const scene of ast.scenes) {
+          sceneNames.push(scene.name);
+        }
+      }
+    } catch (error) {
+      errors.push({ file: sceneFile, error: error.message });
+      if (!silent) {
+        console.error(`Error compiling ${sceneFile}: ${error.message}`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return false;
+  }
+
+  if (fileASTs.length === 0) {
+    return true; // No scenes found, nothing to do
+  }
+
+  // Merge all scenes into a single manifest
+  try {
+    const manifest = convertFilesToSceneManifest(fileASTs);
+
+    // Write merged manifest
+    const json = JSON.stringify(manifest, null, 2);
+    writeFileSync(manifestPath, json, 'utf-8');
+
+    if (!silent && sceneNames.length > 0) {
+      const sceneList =
+        sceneNames.length > 3
+          ? `${sceneNames.slice(0, 3).join(', ')}, ...`
+          : sceneNames.join(', ');
+      console.log(`✓ Scenes compiled (${sceneList})`);
+    }
+
+    return true;
+  } catch (error) {
+    if (!silent) {
+      console.error(`Error writing scene manifest: ${error.message}`);
+    }
+    return false;
+  }
+}
+
+/**
+ * Compile universe files to manifest (using discovered files)
+ * @param {string} universeRoot - Universe root directory
+ * @param {string[]} files - Array of prose file paths to compile
+ * @param {boolean} silent - If true, don't print success message
+ * @returns {boolean} - True if successful, false otherwise
+ */
+function compileUniverseWithFiles(universeRoot, files, silent = false) {
+  // Repositories will be extracted from prose files by buildGraph
+  // We'll validate them after parsing
+  
+  // Use default output path relative to universe root
+  const outputDir = resolve(universeRoot, './.sprig');
+  const manifestPath = join(outputDir, 'manifest.json');
+
+  // Read and parse files
+  const fileContents = files.map((file) => ({
+    file,
+    text: readFileSync(file, 'utf-8'),
+  }));
+
+  try {
+    const graph = parseFiles(fileContents);
+
+    // Validate exactly one universe (should already be validated, but double-check)
+    const validation = validateUniverseCount(graph);
+    if (!validation.valid) {
+      console.error(`Error: ${validation.error}`);
+      return false;
+    }
+
+    // Validate repository kinds exist
+    if (!validateRepositoryKinds(graph.repositories || {}, universeRoot)) {
+      return false;
+    }
+
+    // Validate references
+    if (!validateReferences(graph, graph.repositories || {})) {
+      return false;
+    }
+
+    // Get series names for status message
+    const seriesNames = Object.values(graph.nodes)
+      .filter((node) => node.kind === 'series')
+      .map((node) => node.name)
+      .sort();
+
+    // Add repositories and metadata to manifest
+    const manifest = {
+      ...graph,
+      repositories: graph.repositories || {},
+      generatedAt: new Date().toISOString(),
+    };
+
+    // Ensure output directory exists
+    const manifestDir = dirname(manifestPath);
+    try {
+      mkdirSync(manifestDir, { recursive: true });
+    } catch (error) {
+      // Directory might already exist, ignore
+    }
+
+    // Write manifest
+    const json = JSON.stringify(manifest, null, 2);
+    writeFileSync(manifestPath, json, 'utf-8');
+
+    // Check for parsing errors
+    const hasErrors = graph.diagnostics.some((d) => d.severity === 'error');
+    if (hasErrors) {
+      return false;
+    }
+
+    // Display warnings
+    const warnings = graph.diagnostics.filter((d) => d.severity === 'warning');
+    if (warnings.length > 0 && !silent) {
+      console.warn(`\n⚠️  ${warnings.length} warning(s):`);
+      for (const warning of warnings) {
+        const source = warning.source
+          ? `${warning.source.file}:${warning.source.start.line}:${warning.source.start.col}`
+          : 'unknown location';
+        console.warn(`   ${source}: ${warning.message}`);
+      }
+      console.warn('');
+    }
+
+    if (!silent) {
+      if (seriesNames.length > 0) {
+        const seriesList =
+          seriesNames.length > 3
+            ? `${seriesNames.slice(0, 3).join(', ')}, ...`
+            : seriesNames.join(', ');
+        console.log(`✓ Universe compiled (${seriesList})`);
+      } else {
+        console.log(`✓ Universe compiled`);
+      }
+    }
+
+    return true;
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    if (error.stack && !silent) {
+      console.error(error.stack);
+    }
+    return false;
+  }
+}
+
+/**
+ * Compile universe files to manifest
+ * @param {any} config - Full config object
+ * @param {string} configPath - Path to config file
+ * @param {boolean} silent - If true, don't print success message
+ * @returns {boolean} - True if successful, false otherwise
+ */
+function compileUniverse(config, configPath, silent = false) {
+  const universeConfig = config.universe;
+  const repositories = config.repositories || {};
+
+  if (!universeConfig) {
+    console.error('Error: Missing "universe" section in config');
+    return false;
+  }
+
+  const configDir = dirname(configPath);
+  
+  // Support both old format (manifest at top level) and new format (manifest in output)
+  let manifestPath;
+  if (universeConfig.output?.manifest) {
+    // New format: manifest is just a filename, goes in output directory
+    const outputDir = resolve(configDir, universeConfig.output.directory || './dist/sprig');
+    manifestPath = join(outputDir, universeConfig.output.manifest);
+  } else if (universeConfig.manifest) {
+    // Old format: manifest might be a full path or relative path
+    manifestPath = resolve(configDir, universeConfig.manifest);
+  } else {
+    // Default: manifest.json in dist/sprig
+    const outputDir = resolve(configDir, './dist/sprig');
+    manifestPath = join(outputDir, 'manifest.json');
+  }
+
+  let files;
+  try {
+    files = getFilesToCompile(universeConfig, configDir);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    return false;
+  }
+
+  // Read and parse files
+  const fileContents = files.map((file) => ({
+    file,
+    text: readFileSync(file, 'utf-8'),
+  }));
+
+  try {
+    const graph = parseFiles(fileContents);
+
+    // Validate references
+    if (!validateReferences(graph, repositories)) {
+      return false;
+    }
+
+    // Get series names for status message
+    const seriesNames = Object.values(graph.nodes)
+      .filter((node) => node.kind === 'series')
+      .map((node) => node.name)
+      .sort();
+
+    // Add repositories and metadata to manifest
+    const manifest = {
+      ...graph,
+      repositories,
+      generatedAt: new Date().toISOString(),
+    };
+
+    // Ensure output directory exists
+    const manifestDir = dirname(manifestPath);
+    try {
+      mkdirSync(manifestDir, { recursive: true });
+    } catch (error) {
+      // Directory might already exist, ignore
+    }
+
+    // Write manifest
+    const json = JSON.stringify(manifest, null, 2);
+    writeFileSync(manifestPath, json, 'utf-8');
+
+    // Check for parsing errors
+    const hasErrors = graph.diagnostics.some((d) => d.severity === 'error');
+    if (hasErrors) {
+      return false;
+    }
+
+    // Display warnings
+    const warnings = graph.diagnostics.filter((d) => d.severity === 'warning');
+    if (warnings.length > 0 && !silent) {
+      console.warn(`\n⚠️  ${warnings.length} warning(s):`);
+      for (const warning of warnings) {
+        const source = warning.source
+          ? `${warning.source.file}:${warning.source.start.line}:${warning.source.start.col}`
+          : 'unknown location';
+        console.warn(`   ${source}: ${warning.message}`);
+      }
+      console.warn('');
+    }
+
+    if (!silent) {
+      if (seriesNames.length > 0) {
+        const seriesList =
+          seriesNames.length > 3
+            ? `${seriesNames.slice(0, 3).join(', ')}, ...`
+            : seriesNames.join(', ');
+        console.log(`✓ Universe compiled (${seriesList})`);
+      } else {
+        console.log(`✓ Universe compiled`);
+      }
+    }
+
+    return true;
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    if (error.stack && !silent) {
+      console.error(error.stack);
+    }
+    return false;
+  }
+}
+
+/**
+ * Handle compile command
+ * @param {string[]} args
+ */
+function handleCompile(args) {
+  const quiet = hasQuietFlag(args);
+  const rootStart = resolveRootPath(args);
+  
+  // Discover universe root
+  const universeRoot = discoverUniverseRoot(rootStart);
+  if (!universeRoot) {
+    console.error(`Error: Could not find universe.prose marker. Searched upward from: ${rootStart}`);
+    process.exit(1);
+  }
+  
+  // Load prose files using new discovery mechanism
+  const proseFiles = loadProseFiles(universeRoot);
+  if (proseFiles.length === 0) {
+    console.error(`Error: No .prose files found under root: ${universeRoot}`);
+    process.exit(1);
+  }
+  
+  // Parse files to get universe info for header
+  const fileContents = proseFiles.map((file) => ({
+    file,
+    text: readFileSync(file, 'utf-8'),
+  }));
+  
+  let graph;
+  try {
+    graph = parseFiles(fileContents);
+  } catch (error) {
+    console.error(`Error parsing files: ${error.message}`);
+    process.exit(1);
+  }
+  
+  // Validate exactly one universe
+  const validation = validateUniverseCount(graph);
+  if (!validation.valid) {
+    console.error(`Error: ${validation.error}`);
+    process.exit(1);
+  }
+  
+  // Print observable header unless quiet
+  if (!quiet) {
+    printObservableHeader(validation.universeName, universeRoot, proseFiles.length);
+  }
+  
+  // Use discovered files for compilation
+  const universeSuccess = compileUniverseWithFiles(universeRoot, proseFiles, quiet);
+  const sceneSuccess = compileScenes(universeRoot, quiet);
+
+  if (!universeSuccess || !sceneSuccess) {
+    process.exit(1);
+  }
+}
+
+/**
+ * Groups errors by a stable signature
+ * @param {Array} errors - Array of validation errors
+ * @returns {Array} Array of error groups
+ */
+function groupErrors(errors) {
+  const groups = new Map();
+  
+  for (const error of errors) {
+    // Create signature key from: actorName, fieldName, errorKind, expected, actual
+    // Normalize expected/actual for stable grouping
+    const fieldName = error.fieldName || '<root>';
+    const errorKind = error.errorKind || 'unknown';
+    const expected = String(error.expected || '').trim();
+    const actual = String(error.actual || '').trim();
+    const severity = error.severity || 'error';
+    
+    // Include dataPath in signature if it materially changes meaning (e.g., nested array errors)
+    const signatureKey = `${error.actorName}|${fieldName}|${errorKind}|${expected}|${actual}${error.occurrence?.dataPath ? `|${error.occurrence.dataPath}` : ''}`;
+    
+    if (!groups.has(signatureKey)) {
+      groups.set(signatureKey, {
+        actorName: error.actorName,
+        fieldName,
+        errorKind,
+        severity,
+        expected,
+        actual,
+        schemaLocation: error.schemaLocation || error.location,
+        hint: error.hint,
+        occurrences: [],
+        files: new Set(),
+      });
+    }
+    
+    const group = groups.get(signatureKey);
+    const dataFile = error.occurrence?.dataFile || error.path;
+    const recordIndex = error.occurrence?.recordIndex ?? null;
+    
+    group.occurrences.push({
+      dataFile,
+      recordIndex,
+      dataPath: error.occurrence?.dataPath,
+    });
+    group.files.add(dataFile);
+  }
+  
+  // Sort occurrences within each group: files sorted, then record index ascending
+  for (const group of groups.values()) {
+    group.occurrences.sort((a, b) => {
+      if (a.dataFile !== b.dataFile) {
+        return a.dataFile.localeCompare(b.dataFile);
+      }
+      // Same file: sort by record index (nulls last)
+      if (a.recordIndex === null && b.recordIndex === null) return 0;
+      if (a.recordIndex === null) return 1;
+      if (b.recordIndex === null) return -1;
+      return a.recordIndex - b.recordIndex;
+    });
+  }
+  
+  return Array.from(groups.values());
+}
+
+/**
+ * Selects representative examples across files (at most 1 per file until N reached)
+ * @param {Array} occurrences - Sorted array of occurrences
+ * @param {number} maxExamples - Maximum number of examples to return
+ * @returns {Array} Selected examples
+ */
+function selectRepresentativeExamples(occurrences, maxExamples = 3) {
+  const examples = [];
+  const filesUsed = new Set();
+  const remaining = [];
+  
+  // First pass: take one example per file
+  for (const occ of occurrences) {
+    if (examples.length >= maxExamples) break;
+    
+    if (!filesUsed.has(occ.dataFile)) {
+      examples.push(occ);
+      filesUsed.add(occ.dataFile);
+    } else {
+      remaining.push(occ);
+    }
+  }
+  
+  // Second pass: if we still need more examples, take from remaining (same files)
+  if (examples.length < maxExamples && remaining.length > 0) {
+    const needed = maxExamples - examples.length;
+    examples.push(...remaining.slice(0, needed));
+  }
+  
+  return examples;
+}
+
+/**
+ * Wraps text to a comfortable line width for hints/notes
+ * @param {string} text - Text to wrap
+ * @param {number} width - Maximum line width (default 75)
+ * @returns {string[]} Array of wrapped lines
+ */
+function wrapHintText(text, width = 75) {
+  if (!text) return [];
+  
+  const words = text.split(/\s+/);
+  const lines = [];
+  let currentLine = '';
+  
+  for (const word of words) {
+    const testLine = currentLine ? `${currentLine} ${word}` : word;
+    if (testLine.length <= width) {
+      currentLine = testLine;
+    } else {
+      if (currentLine) {
+        lines.push(currentLine);
+      }
+      currentLine = word;
+    }
+  }
+  
+  if (currentLine) {
+    lines.push(currentLine);
+  }
+  
+  return lines;
+}
+
+/**
+ * Prints error groups in a calm report format
+ * @param {Array} groups - Array of error groups
+ * @param {string} repoRoot - Repository root directory for relativizing paths
+ */
+function printErrorGroups(groups, repoRoot) {
+  // Separate errors and warnings
+  const errorGroups = groups.filter(g => (g.severity || 'error') === 'error');
+  const warningGroups = groups.filter(g => (g.severity || 'error') === 'warning');
+  const infoGroups = groups.filter(g => (g.severity || 'error') === 'info');
+  
+  if (errorGroups.length > 0) {
+    console.log(`\nErrors:`);
+    for (const group of errorGroups) {
+      printErrorGroup(group, repoRoot);
+    }
+  }
+  
+  if (warningGroups.length > 0) {
+    console.log(`\nWarnings:`);
+    for (const group of warningGroups) {
+      printErrorGroup(group, repoRoot);
+    }
+  }
+  
+  if (infoGroups.length > 0) {
+    console.log(`\nInfo:`);
+    for (const group of infoGroups) {
+      printErrorGroup(group, repoRoot);
+    }
+  }
+}
+
+/**
+ * Prints a single error group
+ * @param {Object} group - Error group
+ * @param {string} repoRoot - Repository root directory for relativizing paths
+ */
+function printErrorGroup(group, repoRoot) {
+    // Check if this is a MySQL validation error (schema-level, not data-level)
+    const isMysqlError = group.errorKind && group.errorKind.startsWith('mysql.');
+    
+    // Format header: [Actor.field] Error kind
+    const header = group.fieldName === '<root>' 
+      ? `[${group.actorName}] ${formatErrorKind(group.errorKind)}`
+      : `[${group.actorName}.${group.fieldName}] ${formatErrorKind(group.errorKind)}`;
+    
+    console.log(`  ${header}`);
+    
+    // Expected vs Actual (or Scene vs DB for MySQL errors)
+    if (group.expected && group.actual) {
+      if (isMysqlError) {
+        // For MySQL errors, use Scene/DB labels for clarity
+        console.log(`    Scene: ${group.expected}`);
+        console.log(`    DB: ${group.actual}`);
+      } else {
+        // For file validation, use Expected/Actual
+        console.log(`    Expected: ${group.expected}`);
+        console.log(`    Actual: ${group.actual}`);
+      }
+    }
+    
+    // Occurrences summary - different phrasing for MySQL vs file validation
+    const totalOccurrences = group.occurrences.length;
+    const uniqueFiles = group.files.size;
+    
+    if (isMysqlError) {
+      // MySQL validation is schema-level, so use database schema/table phrasing
+      if (totalOccurrences === 1) {
+        console.log(`    Database schema: ${group.occurrences[0].dataFile}`);
+      } else {
+        console.log(`    Found in ${totalOccurrences} database schema${totalOccurrences !== 1 ? 's' : ''}`);
+      }
+    } else {
+      // File validation is data-level, so use record/file phrasing
+      console.log(`    Occurrences: ${totalOccurrences} record${totalOccurrences !== 1 ? 's' : ''} across ${uniqueFiles} file${uniqueFiles !== 1 ? 's' : ''}`);
+    }
+    
+    // Examples (representative across files, up to 3)
+    if (group.occurrences.length > 0) {
+      if (isMysqlError && totalOccurrences === 1) {
+        // For single MySQL occurrence, skip examples section since we already showed it
+      } else {
+        console.log(`    Examples:`);
+        const examples = selectRepresentativeExamples(group.occurrences, 3);
+        for (const occ of examples) {
+          if (isMysqlError) {
+            // For MySQL, just show the schema.table
+            console.log(`      - ${occ.dataFile}`);
+          } else {
+            // For file validation, show file with record index if applicable
+            const recordStr = occ.recordIndex !== null ? ` (record ${occ.recordIndex})` : '';
+            const pathStr = occ.dataPath ? ` at ${occ.dataPath}` : '';
+            console.log(`      - ${occ.dataFile}${recordStr}${pathStr}`);
+          }
+        }
+        if (group.occurrences.length > examples.length) {
+          console.log(`      - ...`);
+        }
+      }
+    }
+    
+    // Schema location (repo-relative if possible)
+    if (group.schemaLocation) {
+      let schemaFile = group.schemaLocation.file;
+      if (schemaFile && repoRoot) {
+        try {
+          schemaFile = relative(repoRoot, schemaFile);
+        } catch {
+          // If relativization fails, use absolute path
+        }
+      }
+      const schemaStr = schemaFile && group.schemaLocation.start
+        ? `${schemaFile}:${group.schemaLocation.start.line}:${group.schemaLocation.start.col}`
+        : 'unknown location';
+      console.log(`    Schema: ${schemaStr}`);
+    }
+    
+    // Display hint if present (formatted with line breaks)
+    if (group.hint) {
+      console.log(`    Note:`);
+      const wrappedLines = wrapHintText(group.hint, 75);
+      for (const line of wrappedLines) {
+        console.log(`      ${line}`);
+      }
+    }
+    
+  console.log(''); // Blank line between groups
+}
+
+/**
+ * Formats error kind for display
+ * @param {string} errorKind - Error kind
+ * @returns {string} Formatted error kind
+ */
+function formatErrorKind(errorKind) {
+  const kindMap = {
+    'typeMismatch': 'Type mismatch',
+    'missingRequired': 'Missing required field',
+    'enum': 'Invalid enum value',
+    'identityDuplicate': 'Duplicate identity value',
+    'shapeMismatch': 'Shape mismatch',
+    'parseError': 'Parse error',
+    'fileNotFound': 'File not found',
+    'configError': 'Configuration error',
+    'mysql.connection': 'MySQL connection error',
+    'mysql.tableExists': 'MySQL table not found',
+    'mysql.missingColumn': 'MySQL column not found',
+    'mysql.nullability': 'DB does not enforce required field',
+    'mysql.typeMismatch': 'MySQL type mismatch',
+    'mysql.columns': 'MySQL column validation',
+  };
+  return kindMap[errorKind] || (errorKind || 'Validation error');
+}
+
+/**
+ * Handle validate command
+ * @param {string[]} args
+ */
+async function handleValidate(args) {
+  const quiet = hasQuietFlag(args);
+  const rootStart = resolveRootPath(args);
+  
+  // Discover universe root
+  const universeRoot = discoverUniverseRoot(rootStart);
+  if (!universeRoot) {
+    console.error(`Error: Could not find universe.prose marker. Searched upward from: ${rootStart}`);
+    process.exit(1);
+  }
+
+  // Load scenes manifest using default path
+  const scenesManifestPath = join(universeRoot, './.sprig/scenes.json');
+
+  let scenesManifest;
+  try {
+    const manifestText = readFileSync(scenesManifestPath, 'utf-8');
+    scenesManifest = JSON.parse(manifestText);
+  } catch (error) {
+    console.error(`Error: Failed to load scenes manifest from ${scenesManifestPath}: ${error.message}`);
+    console.error('Run "sprig-universe compile" first to generate the scenes manifest');
+    process.exit(1);
+  }
+
+  // Run validation with empty config (no repositories or connections in v0)
+  const emptyConfig = { repositories: {}, connections: {} };
+  const report = await validateScenes(emptyConfig, scenesManifest, universeRoot);
+
+  // Separate errors by severity
+  const errors = report.errors.filter(e => (e.severity || 'error') === 'error');
+  const warnings = report.errors.filter(e => (e.severity || 'error') === 'warning');
+  const infos = report.errors.filter(e => (e.severity || 'error') === 'info');
+
+  // Print summary
+  console.log(`\nValidation Summary:`);
+  console.log(`  Actors validated: ${report.totalActors}`);
+  console.log(`  Files validated: ${report.totalFiles}`);
+  console.log(`  Errors found: ${errors.length}`);
+  if (warnings.length > 0) {
+    console.log(`  Warnings found: ${warnings.length}`);
+  }
+  if (infos.length > 0) {
+    console.log(`  Info messages: ${infos.length}`);
+  }
+
+  // Group and print errors
+  if (report.errors.length > 0) {
+    const groups = groupErrors(report.errors);
+    printErrorGroups(groups, universeRoot);
+  }
+
+  // Write JSON report
+  const reportOutputDir = resolve(universeRoot, './.sprig');
+  const reportPath = join(reportOutputDir, 'validation.json');
+  try {
+    mkdirSync(reportOutputDir, { recursive: true });
+  } catch {
+    // Directory might already exist
+  }
+  writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf-8');
+  if (!quiet) {
+    console.log(`\nValidation report written to: ${reportPath}`);
+  }
+
+  // Exit with error code only if there are actual errors (not warnings or info)
+  if (errors.length > 0) {
+    process.exit(1);
+  }
+}
+
+/**
+ * Handle watch command
+ * @param {string[]} args
+ */
+function handleWatch(args) {
+  const quiet = hasQuietFlag(args);
+  const rootStart = resolveRootPath(args);
+  
+  // Discover universe root
+  const universeRoot = discoverUniverseRoot(rootStart);
+  if (!universeRoot) {
+    console.error(`Error: Could not find universe.prose marker. Searched upward from: ${rootStart}`);
+    process.exit(1);
+  }
+  
+  // Load prose files using new discovery mechanism
+  const proseFiles = loadProseFiles(universeRoot);
+  if (proseFiles.length === 0) {
+    console.error(`Error: No .prose files found under root: ${universeRoot}`);
+    process.exit(1);
+  }
+  
+  // Parse files to get universe info for header
+  const fileContents = proseFiles.map((file) => ({
+    file,
+    text: readFileSync(file, 'utf-8'),
+  }));
+  
+  let graph;
+  try {
+    graph = parseFiles(fileContents);
+  } catch (error) {
+    console.error(`Error parsing files: ${error.message}`);
+    process.exit(1);
+  }
+  
+  // Validate exactly one universe
+  const validation = validateUniverseCount(graph);
+  if (!validation.valid) {
+    console.error(`Error: ${validation.error}`);
+    process.exit(1);
+  }
+  
+  // Print observable header unless quiet
+  if (!quiet) {
+    printObservableHeader(validation.universeName, universeRoot, proseFiles.length);
+  }
+
+  // Build watch patterns from discovered files
+  const watchPatterns = [...proseFiles];
+
+  // Add scene files to watch patterns using default path
+  const scenesInputDir = resolve(universeRoot, './sprig');
+  try {
+    if (statSync(scenesInputDir).isDirectory()) {
+      watchPatterns.push(join(scenesInputDir, '**/*.scene.prose'));
+    }
+  } catch {
+    // Directory doesn't exist, skip
+  }
+
+  // Initial compile
+  if (!quiet) {
+    console.log('Watching universe and scene files...');
+  }
+  compileUniverseWithFiles(universeRoot, proseFiles, quiet);
+  compileScenes(universeRoot, quiet);
+
+  // Debounce timer
+  /** @type {NodeJS.Timeout | null} */
+  let debounceTimer = null;
+  const DEBOUNCE_MS = 100;
+
+  // Watch files
+  const watcher = chokidar.watch(watchPatterns, {
+    ignored: [
+      /(^|[\/\\])\../, // dotfiles
+      /node_modules/,
+      /dist/,
+    ],
+    persistent: true,
+    ignoreInitial: true,
+  });
+
+  watcher.on('change', (/** @type {string} */ filePath) => {
+    // Debounce rapid changes
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+
+    debounceTimer = setTimeout(() => {
+      const relativePath = relative(process.cwd(), filePath);
+      if (!quiet) {
+        console.log(`Changed: ${relativePath}`);
+      }
+      if (filePath.endsWith('.scene.prose')) {
+        compileScenes(universeRoot, quiet);
+      } else {
+        // Reload prose files in case new files were added
+        const currentProseFiles = loadProseFiles(universeRoot);
+        compileUniverseWithFiles(universeRoot, currentProseFiles, quiet);
+      }
+    }, DEBOUNCE_MS);
+  });
+
+  watcher.on('error', (/** @type {Error} */ error) => {
+    console.error(`Watch error: ${error.message}`);
+  });
+
+  // Handle graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('\nStopping watcher...');
+    watcher.close();
+    process.exit(0);
+  });
+}
+
+/**
+ * Handle check:references command
+ * @param {string[]} args
+ */
+function handleCheckReferences(args) {
+  const quiet = hasQuietFlag(args);
+  const rootStart = resolveRootPath(args);
+  
+  // Discover universe root
+  const universeRoot = discoverUniverseRoot(rootStart);
+  if (!universeRoot) {
+    console.error(`Error: Could not find universe.prose marker. Searched upward from: ${rootStart}`);
+    process.exit(1);
+  }
+  
+  // Load prose files using new discovery mechanism
+  const proseFiles = loadProseFiles(universeRoot);
+  if (proseFiles.length === 0) {
+    console.error(`Error: No .prose files found under root: ${universeRoot}`);
+    process.exit(1);
+  }
+  
+  // Parse files to get universe info for header
+  const fileContents = proseFiles.map((file) => ({
+    file,
+    text: readFileSync(file, 'utf-8'),
+  }));
+  
+  let graph;
+  try {
+    graph = parseFiles(fileContents);
+  } catch (error) {
+    console.error(`Error parsing files: ${error.message}`);
+    process.exit(1);
+  }
+  
+  // Validate exactly one universe
+  const validation = validateUniverseCount(graph);
+  if (!validation.valid) {
+    console.error(`Error: ${validation.error}`);
+    process.exit(1);
+  }
+  
+  // Print observable header unless quiet
+  if (!quiet) {
+    printObservableHeader(validation.universeName, universeRoot, proseFiles.length);
+  }
+
+  // Validate repository kinds exist
+  if (!validateRepositoryKinds(graph.repositories || {}, universeRoot)) {
+    console.error('❌ Repository kind validation failed');
+    process.exit(1);
+  }
+
+  // Validate references
+  if (!validateReferences(graph, graph.repositories || {})) {
+    console.error('❌ Reference validation failed');
+    process.exit(1);
+  }
+
+  // Check for parsing errors
+  const hasErrors = graph.diagnostics.some((d) => d.severity === 'error');
+  if (hasErrors) {
+    process.exit(1);
+  }
+
+  // Display warnings
+  const warnings = graph.diagnostics.filter((d) => d.severity === 'warning');
+  if (warnings.length > 0) {
+    console.warn(`\n⚠️  ${warnings.length} warning(s):`);
+    for (const warning of warnings) {
+      const source = warning.source
+        ? `${warning.source.file}:${warning.source.start.line}:${warning.source.start.col}`
+        : 'unknown location';
+      console.warn(`   ${source}: ${warning.message}`);
+    }
+    console.warn('');
+  }
+
+  console.log('✅ All references are valid');
+}
+
+/**
+ * Handle parse command (legacy)
+ * @param {string[]} args
+ */
+function handleParse(args) {
+
+  const inputPath = args[0];
+  if (!inputPath) {
+    console.error('Error: <fileOrDir> is required');
+    process.exit(1);
+  }
+
+  const outIndex = args.indexOf('--out');
+  const outPath = outIndex >= 0 && outIndex + 1 < args.length ? args[outIndex + 1] : null;
+
+  // Resolve input path
+  const resolvedInput = resolve(inputPath);
+  const stat = statSync(resolvedInput);
+
+  let files = [];
+  if (stat.isDirectory()) {
+    files = findSprigFiles(resolvedInput);
+  } else if (stat.isFile()) {
+    files = [resolvedInput];
+  } else {
+    console.error(`Error: ${inputPath} is not a file or directory`);
+    process.exit(1);
+  }
+
+  if (files.length === 0) {
+    console.error(`Error: No .prose files found in ${inputPath}`);
+    process.exit(1);
+  }
+
+  // Read and parse files
+  const fileContents = files.map((file) => ({
+    file,
+    text: readFileSync(file, 'utf-8'),
+  }));
+
+  try {
+    const graph = parseFiles(fileContents);
+
+    // Output JSON
+    const json = JSON.stringify(graph, null, 2);
+
+    if (outPath) {
+      writeFileSync(outPath, json, 'utf-8');
+    } else {
+      console.log(json);
+    }
+
+    // Check for errors
+    const hasErrors = graph.diagnostics.some((d) => d.severity === 'error');
+    if (hasErrors) {
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    if (error.stack) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main();
+