@sprig-and-prose/sprig 0.8.0 → 0.9.1

package/src/cli.ts

@@ -3,6 +3,7 @@
 import { resolve, join } from "node:path";
 import { existsSync, writeFileSync } from "node:fs";
 import { discoverUniverseRoot } from "./root.js";
+import { discoverSceneFiles } from "./scene-discovery.js";
 import { loadProseFiles } from "./prose.js";
 import { compileUniverse } from "./compiler.js";
 import { compileScenes } from "./scene-compiler.js";
@@ -26,13 +27,15 @@ function printHelp() {
   console.log("  --legacy            Use the legacy parser/graph pipeline");
   console.log("");
   console.log("Root discovery:");
-  console.log("  - Walks upward from provided path (or current directory)");
+  console.log("  - Walks upward from path (or cwd for 'sprig compile')");
   console.log("  - Finds directory containing universe.prose");
+  console.log("  - Scene-only mode: requires --out when no universe.prose");
 }
 
 function parseArgs(): {
   command: Command | null;
   path: string;
+  pathExplicit: boolean;
   port?: number;
   universeName?: string;
   legacy?: boolean;
@@ -41,7 +44,7 @@ function parseArgs(): {
   const args = process.argv.slice(2);
 
   if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
-    return { command: null, path: process.cwd() };
+    return { command: null, path: process.cwd(), pathExplicit: false };
   }
 
   const command = args[0] as Command;
@@ -57,11 +60,12 @@ function parseArgs(): {
       console.error("Usage: sprig init <UniverseName>");
       process.exit(1);
     }
-    return { command, path: process.cwd(), universeName: args[1] };
+    return { command, path: process.cwd(), pathExplicit: false, universeName: args[1] };
   }
 
   // Parse path and options
   let path = process.cwd();
+  let pathExplicit = false;
   let port: number | undefined;
   let legacy = false;
   let out: string | undefined;
@@ -92,8 +96,9 @@ function parseArgs(): {
     } else if (arg === "--legacy") {
       legacy = true;
     } else if (!arg.startsWith("-")) {
-      // First non-option argument is the path
+      // First non-option argument is the path (in-directory)
       path = resolve(arg);
+      pathExplicit = true;
     } else {
       console.error(`Error: Unknown option "${arg}"`);
       console.error("Run 'sprig --help' for usage information");
@@ -101,22 +106,78 @@ function parseArgs(): {
     }
   }
 
-  return { command, path, port, legacy, out };
+  return { command, path, pathExplicit, port, legacy, out };
 }
 
-async function handleCompile(path: string, outDir: string | undefined, legacy = false): Promise<void> {
+async function handleCompile(
+  path: string,
+  outDir: string | undefined,
+  legacy = false,
+  pathExplicit = false,
+): Promise<void> {
   const root = discoverUniverseRoot(path);
-  if (!root) {
-    console.error("Could not find universe.prose when walking upward from", path);
-    console.error("");
-    console.error("Make sure you're inside a universe repository.");
+
+  if (!pathExplicit) {
+    // sprig compile (no path): discover from cwd, require universe
+    if (!root) {
+      console.error("No universe.prose found.");
+      process.exit(1);
+    }
+    const outputDir = outDir || join(root, ".sprig");
+    await runUniverseCompile(root, outputDir, legacy);
+    return;
+  }
+
+  // sprig compile <in-directory>: path was explicitly provided
+  if (root) {
+    // Universe found: output to in-directory/.sprig or --out
+    const outputDir = outDir || join(path, ".sprig");
+    await runUniverseCompile(root, outputDir, legacy);
+    return;
+  }
+
+  // Universe not found: scene-only gated by --out
+  if (!outDir) {
+    console.error(`No universe.prose found for ${path}. Provide --out <out-directory> to compile scenes only.`);
+    process.exit(1);
+  }
+
+  const discovery = discoverSceneFiles(path);
+  if (!discovery) {
+    console.error("No universe.prose found and no *.scene.prose files found in:", path);
+    process.exit(1);
+  }
+
+  const sceneResult = await compileScenes(discovery.searchRoot, outDir, {
+    sceneFiles: discovery.sceneFiles,
+    emitManifests: true,
+  });
+
+  const errors = sceneResult.diagnostics.filter((d) => d.severity === "error");
+  const warnings = sceneResult.diagnostics.filter((d) => d.severity === "warning");
+
+  if (!sceneResult.success) {
+    if (errors.length > 0) {
+      printDiagnostics(errors, "Error");
+    }
     process.exit(1);
   }
 
-  // Resolve output directory: --out flag takes precedence over default
-  const outputDir = outDir || join(root, ".sprig");
+  const sceneCount = sceneResult.scenes.length;
+  const scenesText = sceneCount === 1 ? "scene" : "scenes";
+  console.log(`✓ Compiled ${sceneCount} ${scenesText}`);
+
+  if (warnings.length > 0) {
+    console.log("");
+    printDiagnostics(warnings, "Warning");
+  }
+}
 
-  // Compile universe
+async function runUniverseCompile(
+  root: string,
+  outputDir: string,
+  legacy: boolean,
+): Promise<void> {
   const files = await loadProseFiles(root);
   const universeResult = await compileUniverse(root, files, true, { legacy, outputDir });
 
@@ -128,10 +189,8 @@ async function handleCompile(path: string, outDir: string | undefined, legacy =
     process.exit(1);
   }
 
-  // Compile scenes
   const sceneResult = await compileScenes(root, outputDir);
-  
-  // Combine diagnostics
+
   const allDiagnostics = [...universeResult.diagnostics, ...sceneResult.diagnostics];
   const errors = allDiagnostics.filter((d) => d.severity === "error");
   const warnings = allDiagnostics.filter((d) => d.severity === "warning");
@@ -143,7 +202,6 @@ async function handleCompile(path: string, outDir: string | undefined, legacy =
     process.exit(1);
   }
 
-  // Print summary
   const sceneCount = sceneResult.scenes.length;
   const scenesText = sceneCount === 1 ? "scene" : "scenes";
   console.log(`✓ Compiled 1 universe + ${sceneCount} ${scenesText}`);
@@ -341,7 +399,7 @@ async function handleUI(path: string, port?: number, legacy = false): Promise<vo
 }
 
 async function main() {
-  const { command, path, port, universeName, legacy, out } = parseArgs();
+  const { command, path, pathExplicit, port, universeName, legacy, out } = parseArgs();
 
   if (!command) {
     printHelp();
@@ -351,7 +409,7 @@ async function main() {
   try {
     switch (command) {
       case "compile":
-        await handleCompile(path, out, legacy);
+        await handleCompile(path, out, legacy, pathExplicit);
         break;
       case "validate":
         await handleValidate(path, legacy);

package/src/scene-compiler.ts

@@ -53,26 +53,41 @@ function generateManifestId(): string {
   return `time:${new Date().toISOString()}`;
 }
 
+export interface CompileScenesOptions {
+  /** Explicit scene file paths (skips globbing) */
+  sceneFiles?: string[];
+  /** If false, parse and validate only; do not write manifests or error files */
+  emitManifests?: boolean;
+}
+
 /**
  * Compile all scene files in the universe
- * @param universeRoot - Universe root directory
+ * @param universeRoot - Universe root directory (or search root for scene-only mode)
  * @param outputDir - Output directory for scene manifests
+ * @param options - Optional: sceneFiles (explicit list), emitManifests (default true in universe mode)
  * @returns Compile result with success status and list of compiled scenes
  */
 export async function compileScenes(
   universeRoot: string,
   outputDir: string,
+  options?: CompileScenesOptions,
 ): Promise<SceneCompileResult> {
   const diagnostics: Array<{ severity: string; message: string; source?: unknown; scene?: string }> = [];
   const compiledScenes: string[] = [];
+  const emitManifests = options?.emitManifests !== false;
 
   try {
-    // Find all .scene.prose files
-    const sceneFiles = await fg("**/*.scene.prose", {
-      cwd: universeRoot,
-      absolute: true,
-      ignore: ["node_modules/**", ".git/**"],
-    });
+    // Use explicit scene files or discover via glob
+    let sceneFiles: string[];
+    if (options?.sceneFiles && options.sceneFiles.length > 0) {
+      sceneFiles = options.sceneFiles;
+    } else {
+      sceneFiles = await fg("**/*.scene.prose", {
+        cwd: universeRoot,
+        absolute: true,
+        ignore: ["node_modules/**", ".git/**"],
+      });
+    }
 
     if (sceneFiles.length === 0) {
       // No scenes to compile is not an error
@@ -83,15 +98,17 @@ export async function compileScenes(
       };
     }
 
-    // Ensure output directory exists
-    try {
-      mkdirSync(outputDir, { recursive: true });
-    } catch (error) {
-      // Directory might already exist, ignore
+    if (emitManifests) {
+      // Ensure output directory exists
+      try {
+        mkdirSync(outputDir, { recursive: true });
+      } catch (error) {
+        // Directory might already exist, ignore
+      }
     }
 
     const generatedAt = new Date().toISOString();
-    const manifestId = generateManifestId();
+    const manifestId = emitManifests ? generateManifestId() : "";
 
     // Compile each scene
     for (const sceneFile of sceneFiles) {
@@ -107,35 +124,39 @@ export async function compileScenes(
             message,
             source: sceneFile,
           });
-          writeSceneErrors(outputDir, sceneFile, [message], sourceText);
+          if (emitManifests) {
+            writeSceneErrors(outputDir, sceneFile, [message], sourceText);
+          }
           continue;
         }
 
-        // Inject metadata
-        const manifestWithMeta = {
-          ...manifest,
-          meta: {
-            generatedAt,
-            manifestId,
-          },
-        };
-
-        // Write to output directory
-        const outputPath = join(outputDir, `${manifest.sceneName}.scene.json`);
-        const tempPath = `${outputPath}.tmp`;
-        const json = JSON.stringify(manifestWithMeta, null, 2);
-        writeFileSync(tempPath, json, "utf-8");
-        renameSync(tempPath, outputPath);
-
-        // Remove any prior .error.txt for this scene (same source file base name)
-        const errorPath = join(outputDir, `${sceneFileBaseName(sceneFile)}.error.txt`);
-        try {
-          unlinkSync(errorPath);
-        } catch {
-          // ignore if missing
-        }
-
         compiledScenes.push(manifest.sceneName);
+
+        if (emitManifests) {
+          // Inject metadata
+          const manifestWithMeta = {
+            ...manifest,
+            meta: {
+              generatedAt,
+              manifestId,
+            },
+          };
+
+          // Write to output directory
+          const outputPath = join(outputDir, `${manifest.sceneName}.scene.json`);
+          const tempPath = `${outputPath}.tmp`;
+          const json = JSON.stringify(manifestWithMeta, null, 2);
+          writeFileSync(tempPath, json, "utf-8");
+          renameSync(tempPath, outputPath);
+
+          // Remove any prior .error.txt for this scene (same source file base name)
+          const errorPath = join(outputDir, `${sceneFileBaseName(sceneFile)}.error.txt`);
+          try {
+            unlinkSync(errorPath);
+          } catch {
+            // ignore if missing
+          }
+        }
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         diagnostics.push({
@@ -143,7 +164,9 @@ export async function compileScenes(
           message: `Scene compile failed: ${message}`,
           source: sceneFile,
         });
-        writeSceneErrors(outputDir, sceneFile, [message], sourceText);
+        if (emitManifests) {
+          writeSceneErrors(outputDir, sceneFile, [message], sourceText);
+        }
       }
     }
 

package/src/scene-discovery.ts

@@ -0,0 +1,51 @@
+import { statSync, existsSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import fg from "fast-glob";
+
+export interface SceneDiscovery {
+  sceneFiles: string[];
+  searchRoot: string;
+}
+
+/**
+ * Discover scene files when no universe.prose is found.
+ * @param path - Path (file or directory) from user
+ * @returns SceneDiscovery with sceneFiles and searchRoot, or null if no scenes found
+ */
+export function discoverSceneFiles(path: string): SceneDiscovery | null {
+  const resolved = resolve(path);
+
+  if (!existsSync(resolved)) {
+    return null;
+  }
+
+  const stat = statSync(resolved);
+
+  if (stat.isFile()) {
+    if (/\.scene\.prose$/i.test(resolved)) {
+      return {
+        sceneFiles: [resolved],
+        searchRoot: dirname(resolved),
+      };
+    }
+    // Other file: search in same directory
+    const searchRoot = dirname(resolved);
+    const sceneFiles = fg.sync("**/*.scene.prose", {
+      cwd: searchRoot,
+      absolute: true,
+      ignore: ["node_modules/**", ".git/**"],
+    });
+    return sceneFiles.length > 0 ? { sceneFiles, searchRoot } : null;
+  }
+
+  if (stat.isDirectory()) {
+    const sceneFiles = fg.sync("**/*.scene.prose", {
+      cwd: resolved,
+      absolute: true,
+      ignore: ["node_modules/**", ".git/**"],
+    });
+    return sceneFiles.length > 0 ? { sceneFiles, searchRoot: resolved } : null;
+  }
+
+  return null;
+}

package/tests/compile-scene-only.test.js

@@ -0,0 +1,109 @@
+import { test } from "node:test";
+import { strict as assert } from "node:assert";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURES = join(__dirname, "fixtures");
+const CLI_PATH = join(__dirname, "..", "dist", "cli.js");
+
+function runCompile(args, cwd) {
+  const result = spawnSync("node", [CLI_PATH, "compile", ...args], {
+    encoding: "utf-8",
+    cwd: cwd ?? join(__dirname, ".."),
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+test("sprig compile with no universe in cwd: errors", () => {
+  const cwd = join(FIXTURES, "scene-only-empty");
+  const { status, stderr } = runCompile([], cwd);
+
+  assert.notStrictEqual(status, 0, "Expected non-zero exit");
+  assert.ok(stderr.includes("No universe.prose found."), "Should show expected error");
+});
+
+test("sprig compile <dir> universe in dir, no --out: writes to dir/.sprig", () => {
+  const dir = join(FIXTURES, "universe-unchanged");
+  const { status, stderr } = runCompile([dir]);
+
+  assert.strictEqual(status, 0, `Expected exit 0, got ${status}. stderr: ${stderr}`);
+
+  const sprigDir = join(dir, ".sprig");
+  assert.ok(existsSync(sprigDir), ".sprig should exist");
+  assert.ok(existsSync(join(sprigDir, "manifest.json")), "manifest.json should exist");
+  assert.ok(existsSync(join(sprigDir, "TestScene.scene.json")), "TestScene.scene.json should exist");
+});
+
+test("sprig compile <dir> --out <out> universe found: writes to out", () => {
+  const dir = join(FIXTURES, "universe-unchanged");
+  const outDir = join(dir, "custom-out");
+  const { status, stderr } = runCompile([dir, "--out", outDir]);
+
+  assert.strictEqual(status, 0, `Expected exit 0, got ${status}. stderr: ${stderr}`);
+
+  assert.ok(existsSync(join(outDir, "manifest.json")), "manifest.json should exist in --out");
+  assert.ok(existsSync(join(outDir, "TestScene.scene.json")), "TestScene.scene.json should exist in --out");
+});
+
+test("sprig compile <dir> no universe, no --out: errors with guidance", () => {
+  const dir = join(FIXTURES, "scene-only-valid");
+  const { status, stderr } = runCompile([dir]);
+
+  assert.notStrictEqual(status, 0, "Expected non-zero exit");
+  assert.ok(
+    stderr.includes("No universe.prose found for"),
+    "Should mention no universe for dir",
+  );
+  assert.ok(stderr.includes("Provide --out"), "Should suggest --out");
+});
+
+test("sprig compile <dir> --out <out> no universe, scenes present: emits to out", () => {
+  const dir = join(FIXTURES, "scene-only-valid");
+  const outDir = join(dir, ".sprig-out");
+  const { status, stderr } = runCompile([dir, "--out", outDir]);
+
+  assert.strictEqual(status, 0, `Expected exit 0, got ${status}. stderr: ${stderr}`);
+
+  assert.ok(existsSync(join(outDir, "SimpleScene.scene.json")), "SimpleScene.scene.json should exist");
+  assert.ok(existsSync(join(outDir, "AnotherScene.scene.json")), "AnotherScene.scene.json should exist");
+});
+
+test("sprig compile <dir> --out <out> no universe, no scenes: errors", () => {
+  const dir = join(FIXTURES, "scene-only-empty");
+  const outDir = join(dir, ".sprig-out");
+  const { status, stderr } = runCompile([dir, "--out", outDir]);
+
+  assert.notStrictEqual(status, 0, "Expected non-zero exit");
+  assert.ok(
+    stderr.includes("No universe.prose found and no *.scene.prose files found in:"),
+    "Should show no scenes error",
+  );
+});
+
+test("sprig compile <dir> universe in parent, no --out: writes to in-directory/.sprig", () => {
+  const subdir = join(FIXTURES, "universe-upstream", "subdir");
+  const { status, stderr } = runCompile([subdir]);
+
+  assert.strictEqual(status, 0, `Expected exit 0, got ${status}. stderr: ${stderr}`);
+
+  const sprigDir = join(subdir, ".sprig");
+  assert.ok(existsSync(sprigDir), "Output should be in subdir/.sprig (in-directory)");
+  assert.ok(existsSync(join(sprigDir, "manifest.json")), "manifest.json should exist");
+  assert.ok(existsSync(join(sprigDir, "OneScene.scene.json")), "OneScene.scene.json should exist");
+});
+
+test("scene-only invalid dir with --out: exits non-zero", () => {
+  const dir = join(FIXTURES, "scene-only-invalid");
+  const outDir = join(dir, ".sprig-out");
+  const { status, stderr } = runCompile([dir, "--out", outDir]);
+
+  assert.notStrictEqual(status, 0, "Expected non-zero exit on invalid scene");
+  assert.ok(stderr.includes("BadScene") || stderr.includes("bad.scene.prose"), "Error should mention scene or file");
+});

package/tests/fixtures/scene-only-invalid/.sprig-out/bad.error.txt

@@ -0,0 +1,2 @@
+Field 'id' may only define a single type (e.g. integer, string, array, or an actor). This error appears because two or more types are defined for this field.
+  at BadScene

package/tests/fixtures/scene-only-invalid/bad.scene.prose

@@ -0,0 +1,10 @@
+scene BadScene {
+  actor Actor {
+    shape {
+      id {
+        integer
+        string
+      }
+    }
+  }
+}

package/tests/fixtures/scene-only-valid/.sprig-emit/AnotherScene.scene.json

@@ -0,0 +1,15 @@
+{
+  "sceneName": "AnotherScene",
+  "actors": {
+    "NameActor": {
+      "type": "string",
+      "identity": []
+    }
+  },
+  "portals": {},
+  "derived": {},
+  "meta": {
+    "generatedAt": "2026-02-21T20:00:48.348Z",
+    "manifestId": "git:e97c34ae2cb10839cafef399d1ef329411e3bd22"
+  }
+}

package/tests/fixtures/scene-only-valid/.sprig-emit/SimpleScene.scene.json

@@ -0,0 +1,15 @@
+{
+  "sceneName": "SimpleScene",
+  "actors": {
+    "IntActor": {
+      "type": "integer",
+      "identity": []
+    }
+  },
+  "portals": {},
+  "derived": {},
+  "meta": {
+    "generatedAt": "2026-02-21T20:00:48.348Z",
+    "manifestId": "git:e97c34ae2cb10839cafef399d1ef329411e3bd22"
+  }
+}

package/tests/fixtures/scene-only-valid/.sprig-out/AnotherScene.scene.json

@@ -0,0 +1,15 @@
+{
+  "sceneName": "AnotherScene",
+  "actors": {
+    "NameActor": {
+      "type": "string",
+      "identity": []
+    }
+  },
+  "portals": {},
+  "derived": {},
+  "meta": {
+    "generatedAt": "2026-02-21T20:23:33.528Z",
+    "manifestId": "git:e97c34ae2cb10839cafef399d1ef329411e3bd22"
+  }
+}

package/tests/fixtures/scene-only-valid/.sprig-out/SimpleScene.scene.json

@@ -0,0 +1,15 @@
+{
+  "sceneName": "SimpleScene",
+  "actors": {
+    "IntActor": {
+      "type": "integer",
+      "identity": []
+    }
+  },
+  "portals": {},
+  "derived": {},
+  "meta": {
+    "generatedAt": "2026-02-21T20:23:33.528Z",
+    "manifestId": "git:e97c34ae2cb10839cafef399d1ef329411e3bd22"
+  }
+}

package/tests/fixtures/scene-only-valid/another.scene.prose

@@ -0,0 +1,3 @@
+scene AnotherScene {
+  actor NameActor { string }
+}

package/tests/fixtures/scene-only-valid/simple.scene.prose

@@ -0,0 +1,3 @@
+scene SimpleScene {
+  actor IntActor { integer }
+}

package/tests/fixtures/universe-unchanged/.sprig/TestScene.scene.json

@@ -0,0 +1,15 @@
+{
+  "sceneName": "TestScene",
+  "actors": {
+    "IntActor": {
+      "type": "integer",
+      "identity": []
+    }
+  },
+  "portals": {},
+  "derived": {},
+  "meta": {
+    "generatedAt": "2026-02-21T20:23:33.122Z",
+    "manifestId": "git:e97c34ae2cb10839cafef399d1ef329411e3bd22"
+  }
+}

package/tests/fixtures/universe-unchanged/.sprig/manifest.json

@@ -0,0 +1,62 @@
+{
+  "version": 1,
+  "universes": {
+    "TestUniverse": {
+      "name": "TestUniverse",
+      "root": "TestUniverse:universe:TestUniverse"
+    }
+  },
+  "nodes": {
+    "TestUniverse:universe:TestUniverse": {
+      "id": "TestUniverse:universe:TestUniverse",
+      "kind": "universe",
+      "name": "TestUniverse",
+      "children": [],
+      "source": {
+        "file": "/home/grumpy/git/sprig/packages/cli/tests/fixtures/universe-unchanged/universe.prose",
+        "start": {
+          "line": 1,
+          "col": 1,
+          "offset": 0
+        },
+        "end": {
+          "line": 5,
+          "col": 2,
+          "offset": 63
+        }
+      },
+      "describe": {
+        "raw": "\n    A test universe.\n  ",
+        "normalized": "\n    A test universe.\n  ",
+        "source": {
+          "file": "/home/grumpy/git/sprig/packages/cli/tests/fixtures/universe-unchanged/universe.prose",
+          "start": {
+            "line": 2,
+            "col": 3,
+            "offset": 26
+          },
+          "end": {
+            "line": 4,
+            "col": 4,
+            "offset": 61
+          }
+        }
+      }
+    }
+  },
+  "edges": [],
+  "edgesAsserted": [],
+  "diagnostics": [],
+  "repositories": {},
+  "references": {},
+  "arcs": {},
+  "documentsByName": {},
+  "relationshipDecls": {
+    "TestUniverse": {}
+  },
+  "generatedAt": "2026-02-21T20:23:33.116Z",
+  "meta": {
+    "generatedAt": "2026-02-21T20:23:33.116Z",
+    "manifestId": "git:e97c34ae2cb10839cafef399d1ef329411e3bd22"
+  }
+}

package/tests/fixtures/universe-unchanged/custom-out/TestScene.scene.json

@@ -0,0 +1,15 @@
+{
+  "sceneName": "TestScene",
+  "actors": {
+    "IntActor": {
+      "type": "integer",
+      "identity": []
+    }
+  },
+  "portals": {},
+  "derived": {},
+  "meta": {
+    "generatedAt": "2026-02-21T20:23:33.279Z",
+    "manifestId": "git:e97c34ae2cb10839cafef399d1ef329411e3bd22"
+  }
+}