paracosm 0.7.431 → 0.7.450

package/README.md

@@ -350,14 +350,28 @@ The dashboard includes a scenario editor where you can write, import, compile, a
 
 ### 4. Or run the standalone CLI
 
-After `npm install paracosm -g` you get two binaries:
+After `npm install paracosm -g` you get one umbrella binary with subcommands. Every level supports `--help` / `-h` and a global `--version` / `-v`:
 
 ```bash
-paracosm                # run one leader once; prints turn-by-turn narrative
-paracosm-dashboard 6    # start the web dashboard and run a 6-turn sim
+paracosm --help                        # lists every subcommand
+paracosm --version                     # prints "paracosm 0.7.x"
+
+paracosm run                           # run a sim against leaders.json
+paracosm run --leader 1 --turns 5      # leader index 1, 5 turns
+paracosm run --name "Reyes" --openness 0.85 --conscientiousness 0.4 --turns 6
+paracosm run --leaders ./my-leaders.json --live   # custom roster + live web search
+
+paracosm dashboard                     # SSE dashboard at http://localhost:3456
+paracosm dashboard 6                   # auto-launch with 6 turns
+
+paracosm compile scenarios/lunar.json --seed-url <url> --max-searches 5
+
+paracosm init my-app --domain "Submarine crew of 8" --leaders 3
 ```
 
-Both CLIs look for `leaders.json` in this order:
+A second back-compat binary `paracosm-dashboard` is shipped as an alias for `paracosm dashboard` so existing scripts and Docker invocations don't break.
+
+The CLI looks for `leaders.json` in this order:
 
 1. `--leaders <path>` flag (explicit)
 2. `./leaders.json` in your current directory
@@ -644,11 +658,11 @@ Pass real-world source material into the compiler and Paracosm grounds the scena
 
 ```bash
 # Inline text seed
-npx paracosm compile scenarios/lunar.json \
+paracosm compile scenarios/lunar.json \
   --seed-text "$(cat ./papers/iss-radiation-overview.md)"
 
 # URL seed (Firecrawl extracts clean markdown)
-npx paracosm compile scenarios/lunar.json \
+paracosm compile scenarios/lunar.json \
   --seed-url https://ntrs.nasa.gov/citations/20210018970
 ```
 

package/dist/cli/compile.d.ts

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 /**
- * CLI: Compile a scenario JSON draft into a runnable ScenarioPackage.
+ * Compile a scenario JSON draft. Thin shim around the dispatcher's
+ * compile handler so existing `npx tsx src/cli/compile.ts ...` calls
+ * still work. Callers on a published install should prefer
+ * `paracosm compile`.
  *
- * Usage:
- *   npx tsx src/cli/compile.ts scenarios/submarine.json
- *   npx tsx src/cli/compile.ts scenarios/submarine.json --provider anthropic --model claude-sonnet-4-6
- *   npx tsx src/cli/compile.ts scenarios/submarine.json --no-cache
+ * @module paracosm/cli/compile
  */
 export {};
 //# sourceMappingURL=compile.d.ts.map

package/dist/cli/compile.js

@@ -1,92 +1,23 @@
 #!/usr/bin/env node
 /**
- * CLI: Compile a scenario JSON draft into a runnable ScenarioPackage.
+ * Compile a scenario JSON draft. Thin shim around the dispatcher's
+ * compile handler so existing `npx tsx src/cli/compile.ts ...` calls
+ * still work. Callers on a published install should prefer
+ * `paracosm compile`.
  *
- * Usage:
- *   npx tsx src/cli/compile.ts scenarios/submarine.json
- *   npx tsx src/cli/compile.ts scenarios/submarine.json --provider anthropic --model claude-sonnet-4-6
- *   npx tsx src/cli/compile.ts scenarios/submarine.json --no-cache
+ * @module paracosm/cli/compile
  */
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { compileScenario } from '../engine/compiler/index.js';
-import { parseCompileCliOptions } from './compile-cli-options.js';
-async function main() {
-    const rawArgs = process.argv.slice(2);
-    const options = parseCompileCliOptions(rawArgs);
-    if (rawArgs.length === 0 || rawArgs.includes('--help') || rawArgs.includes('-h')) {
-        console.log(`
-paracosm compile - Generate runtime hooks for a scenario JSON draft
-
-Usage:
-  npx tsx src/cli/compile.ts <scenario.json> [options]
-
-Options:
-  --provider <provider>   LLM provider: openai | anthropic (default: anthropic)
-  --model <model>         Model name (default: claude-sonnet-4-6)
-  --no-cache              Skip disk cache
-  --cache-dir <dir>       Cache directory (default: .paracosm/cache)
-  --seed-text <text>      Ground the scenario with an inline prompt, brief, or document
-  --seed-url <url>        Ground the scenario with a URL before hook generation
-  --no-web-search         Skip live citation grounding during seed ingestion
-  --max-searches <n>      Cap the number of live grounding searches during seed ingestion
-  -h, --help              Show this help
-`);
-        process.exit(0);
-    }
-    if (!options.scenarioPath) {
-        console.error('  Scenario JSON path required. Run with --help for usage.');
-        process.exit(1);
-    }
-    const jsonPath = resolve(options.scenarioPath);
-    console.log(`\n  Compiling scenario: ${jsonPath}`);
-    console.log(`  Provider: ${options.provider} | Model: ${options.model} | Cache: ${options.cache}`);
-    if (options.seedUrl) {
-        console.log(`  Seed URL: ${options.seedUrl} | Web search: ${options.webSearch} | Max searches: ${options.maxSearches ?? 5}`);
-    }
-    else if (options.seedText) {
-        console.log(`  Seed text: ${Math.min(options.seedText.length, 160)} chars | Web search: ${options.webSearch} | Max searches: ${options.maxSearches ?? 5}`);
-    }
-    console.log();
-    let scenarioJson;
-    try {
-        scenarioJson = JSON.parse(readFileSync(jsonPath, 'utf-8'));
-    }
-    catch (err) {
-        console.error(`  Error reading ${jsonPath}: ${err}`);
-        process.exit(1);
-    }
-    const scenario = await compileScenario(scenarioJson, {
-        provider: options.provider,
-        model: options.model,
-        cache: options.cache,
-        cacheDir: options.cacheDir,
-        seedText: options.seedText,
-        seedUrl: options.seedUrl,
-        webSearch: options.webSearch,
-        maxSearches: options.maxSearches,
-        onProgress(hookName, status) {
-            const icons = {
-                generating: '...',
-                cached: '(cached)',
-                done: 'done',
-                fallback: 'FALLBACK',
-            };
-            if (status === 'generating') {
-                process.stdout.write(`  Generating ${hookName}... `);
-            }
-            else {
-                console.log(icons[status] ?? status);
-            }
-        },
-    });
-    console.log(`\n  Scenario compiled: ${scenario.id} v${scenario.version}`);
-    console.log(`  Departments: ${scenario.departments.map(d => d.id).join(', ')}`);
-    console.log(`  Hooks: ${Object.keys(scenario.hooks).filter(k => scenario.hooks[k]).join(', ')}`);
-    console.log(`  Ready for: runSimulation(leader, personnel, { scenario })\n`);
+import { runCompile } from './run-compile.js';
+import { printCommandHelp } from './help.js';
+const argv = process.argv.slice(2);
+if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    printCommandHelp('compile');
+    process.exit(0);
 }
-main().catch((err) => {
-    console.error('Compile failed:', err);
+runCompile(argv).then((exitCode) => {
+    process.exit(exitCode);
+}).catch((err) => {
+    process.stderr.write(`Compile failed: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
     process.exit(1);
 });
 //# sourceMappingURL=compile.js.map

package/dist/cli/compile.js.map

@@ -1 +1 @@
-{"version":3,"file":"compile.js","sourceRoot":"","sources":["../../src/cli/compile.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compile.js","sourceRoot":"","sources":["../../src/cli/compile.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACxE,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC5B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE;IACjC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3G,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/cli/help.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Help text for the paracosm CLI router. Single source of truth so
+ * `paracosm --help`, `paracosm run --help`, etc. all stay in sync.
+ *
+ * @module paracosm/cli/help
+ */
+/**
+ * Print top-level help to stdout.
+ */
+export declare function printTopLevelHelp(): void;
+/**
+ * Print help for a specific subcommand. Falls back to top-level help when
+ * the command is unknown.
+ */
+export declare function printCommandHelp(command: string): void;
+/**
+ * Read paracosm's own version from the package.json shipped with the
+ * installed package. Looks two directories up from `dist/cli/help.js`
+ * (the published location), and one directory up from
+ * `src/cli/help.ts` (when running via tsx during development).
+ */
+export declare function readPackageVersion(): string;
+//# sourceMappingURL=help.d.ts.map

package/dist/cli/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiIH;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAQtD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAmB3C"}

package/dist/cli/help.js

@@ -0,0 +1,174 @@
+/**
+ * Help text for the paracosm CLI router. Single source of truth so
+ * `paracosm --help`, `paracosm run --help`, etc. all stay in sync.
+ *
+ * @module paracosm/cli/help
+ */
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const TOP_LEVEL_HELP = `paracosm <command> [options]
+
+A structured world model for AI agents. Compile prompts, briefs, URLs, or
+JSON contracts into typed scenarios. Run HEXACO-personality leaders against
+a deterministic kernel.
+
+Commands:
+  run                   Run a simulation against leaders.json
+  dashboard             Start the SSE web dashboard at http://localhost:3456
+  compile <scenario>    Compile a scenario draft into runnable hooks (cached)
+  init <dir>            Scaffold a starter project from a free-text brief
+  help [command]        Show help for a specific command
+  version               Print version
+
+Global flags:
+  --help, -h            Show help (works on every subcommand)
+  --version, -v         Print version
+
+Examples:
+  paracosm run                                            # default leader, full turns
+  paracosm run --leader 1 --turns 5                       # leader index 1, 5 turns
+  paracosm run --name "Reyes" --openness 0.85 6           # inline HEXACO override
+  paracosm dashboard --turns 6                            # opens browser dashboard
+  paracosm compile scenarios/lunar.json --seed-url <url>  # compile + cache
+  paracosm init my-app --domain "Submarine crew of 8"     # scaffold a project
+
+Docs:   https://paracosm.agentos.sh/docs
+GitHub: https://github.com/framersai/paracosm
+`;
+const RUN_HELP = `paracosm run [options]
+
+Run a simulation against leaders.json (or --leaders <path>) and print
+turn-by-turn narrative to stdout. Saves the full RunArtifact JSON to
+./output/v3-<archetype>-<timestamp>.json (override with PARACOSM_OUTPUT_DIR).
+
+Options:
+  --leader <n>            Leader index in leaders.json (default: 0)
+  --leaders <path>        Custom leaders.json path
+  --turns <n>             Override turn count
+  --seed <n>              Override seed
+  --start-time <n>        Override start time / year
+  --provider <p>          openai | anthropic (defaults to whichever key is set)
+  --cost <p>              quality | economy (default: quality)
+  --live                  Enable live web search during department analysis
+  --name <s>              Override leader name
+  --archetype <s>         Override leader archetype
+  --unit <s>              Override leader unit
+  --instructions <s>      Override leader instructions
+  --openness <0-1>        HEXACO openness override
+  --conscientiousness <0-1>
+  --extraversion <0-1>
+  --agreeableness <0-1>
+  --emotionality <0-1>
+  --honesty <0-1>         HEXACO honesty-humility override
+
+Positional turn count: a single trailing number is read as --turns
+  paracosm run 5          # equivalent to: paracosm run --turns 5
+`;
+const DASHBOARD_HELP = `paracosm dashboard [turns] [options]
+
+Start the SSE web dashboard at http://localhost:3456 (override with PORT).
+The dashboard exposes the Setup, Reports, Library, Branches, Viz, and Chat
+tabs over a streaming connection. Without [turns], waits for setup at
+/sim?tab=settings; with [turns], auto-launches a simulation on boot.
+
+Options:
+  [turns]               Auto-launch with N turns. Omit to wait for setup.
+  --leaders <path>      Custom leaders.json path
+  --seed <n>            Override seed
+  --start-time <n>      Override start time
+  --provider <p>        openai | anthropic
+  --live                Enable live web search
+
+Environment:
+  PORT                  Dashboard port (default: 3456)
+  PARACOSM_ENABLE_SIMULATE_ENDPOINT=true   Enable POST /simulate one-shot endpoint
+`;
+const COMPILE_HELP = `paracosm compile <scenario.json> [options]
+
+Compile a scenario JSON draft into a runnable ScenarioPackage with generated
+TypeScript hooks. Caches per-hook on (scenario hash + model + schema version)
+so re-runs hit disk. Cost: roughly $0.10 per first compile, free thereafter.
+
+Options:
+  <scenario.json>       Required: path to a scenario JSON draft
+  --provider <p>        openai | anthropic (default: anthropic)
+  --model <m>           Model name (default: claude-sonnet-4-6)
+  --no-cache            Skip disk cache; force regeneration
+  --cache-dir <dir>     Cache directory (default: .paracosm/cache)
+  --seed-text <s>       Ground the scenario with an inline brief
+  --seed-url <url>      Ground the scenario with a URL (Firecrawl extraction)
+  --no-web-search       Skip live citation grounding during seed ingestion
+  --max-searches <n>    Cap live grounding searches (default: 5)
+`;
+const INIT_HELP = `paracosm init <dir> --domain <text|url> [options]
+
+Scaffold a runnable paracosm project from a free-text brief or a URL.
+Calls compileFromSeed + generateQuickstartLeaders, then writes
+package.json, run.mjs, README.md, .env.example, .gitignore to <dir>.
+
+Options:
+  <dir>                 Output directory (default: ./paracosm-app)
+  --domain <text|url>   Required: seed text or URL describing the scenario
+  --mode <m>            turn-loop | batch-trajectory | batch-point (default: turn-loop)
+  --leaders <n>         Number of HEXACO leaders, 2-6 (default: 3)
+  --name <s>            Project name (default: derived from --domain)
+  --force               Overwrite a non-empty target directory
+
+Example:
+  paracosm init my-app --domain "Submarine crew of 8 in deep ocean for 30 days"
+`;
+const HELP_BY_COMMAND = {
+    run: RUN_HELP,
+    dashboard: DASHBOARD_HELP,
+    compile: COMPILE_HELP,
+    init: INIT_HELP,
+};
+/**
+ * Print top-level help to stdout.
+ */
+export function printTopLevelHelp() {
+    process.stdout.write(TOP_LEVEL_HELP);
+}
+/**
+ * Print help for a specific subcommand. Falls back to top-level help when
+ * the command is unknown.
+ */
+export function printCommandHelp(command) {
+    const text = HELP_BY_COMMAND[command];
+    if (text) {
+        process.stdout.write(text);
+    }
+    else {
+        process.stdout.write(`Unknown command: ${command}\n\n`);
+        process.stdout.write(TOP_LEVEL_HELP);
+    }
+}
+/**
+ * Read paracosm's own version from the package.json shipped with the
+ * installed package. Looks two directories up from `dist/cli/help.js`
+ * (the published location), and one directory up from
+ * `src/cli/help.ts` (when running via tsx during development).
+ */
+export function readPackageVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/cli/help.js -> dist/.. -> package root
+    // src/cli/help.ts  -> src/..  -> package root
+    const candidates = [
+        resolve(here, '..', '..', 'package.json'),
+        resolve(here, '..', 'package.json'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            const pkg = JSON.parse(readFileSync(candidate, 'utf-8'));
+            if (pkg.name === 'paracosm' && typeof pkg.version === 'string') {
+                return pkg.version;
+            }
+        }
+        catch {
+            // Try next candidate.
+        }
+    }
+    return 'unknown';
+}
+//# sourceMappingURL=help.js.map

package/dist/cli/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BtB,CAAC;AAEF,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BhB,CAAC;AAEF,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;CAkBtB,CAAC;AAEF,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;CAgBpB,CAAC;AAEF,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;CAgBjB,CAAC;AAEF,MAAM,eAAe,GAA2B;IAC9C,GAAG,EAAE,QAAQ;IACb,SAAS,EAAE,cAAc;IACzB,OAAO,EAAE,YAAY;IACrB,IAAI,EAAE,SAAS;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,OAAO,MAAM,CAAC,CAAC;QACxD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACvC,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,8CAA8C;IAC9C,8CAA8C;IAC9C,MAAM,UAAU,GAAG;QACjB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;QACzC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;KACpC,CAAC;IACF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAwC,CAAC;YAChG,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAC/D,OAAO,GAAG,CAAC,OAAO,CAAC;YACrB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,sBAAsB;QACxB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/cli/router.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Subcommand dispatcher for `paracosm <command>`. Lives separately
+ * from run.ts so it can be unit-tested without the binary's
+ * process-exit path firing.
+ *
+ * Recognized subcommands:
+ *   run, dashboard, compile, init, help, version
+ *
+ * Global flags `--help`/`-h` and `--version`/`-v` short-circuit at
+ * any position before subcommand parsing.
+ *
+ * Back-compat path: when argv has neither a recognized subcommand nor
+ * a global flag, dispatch falls through to `run` and the result carries
+ * a one-line `deprecation` hint the binary surfaces to stderr.
+ *
+ * @module paracosm/cli/router
+ */
+export interface DispatchResult {
+    /** Process exit code returned by the subcommand handler. */
+    exitCode: number;
+    /** Deprecation message for the binary to print to stderr, if any. */
+    deprecation?: string;
+}
+/**
+ * Dispatch argv to the appropriate subcommand handler. Pure: no
+ * process.exit, no top-level await side effects.
+ */
+export declare function dispatch(argv: readonly string[]): Promise<DispatchResult>;
+//# sourceMappingURL=router.d.ts.map

package/dist/cli/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/cli/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA0BH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA2BD;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAkF/E"}

package/dist/cli/router.js

@@ -0,0 +1,144 @@
+/**
+ * Subcommand dispatcher for `paracosm <command>`. Lives separately
+ * from run.ts so it can be unit-tested without the binary's
+ * process-exit path firing.
+ *
+ * Recognized subcommands:
+ *   run, dashboard, compile, init, help, version
+ *
+ * Global flags `--help`/`-h` and `--version`/`-v` short-circuit at
+ * any position before subcommand parsing.
+ *
+ * Back-compat path: when argv has neither a recognized subcommand nor
+ * a global flag, dispatch falls through to `run` and the result carries
+ * a one-line `deprecation` hint the binary surfaces to stderr.
+ *
+ * @module paracosm/cli/router
+ */
+import { printTopLevelHelp, printCommandHelp, readPackageVersion } from './help.js';
+const KNOWN_COMMANDS = new Set([
+    'run',
+    'dashboard',
+    'compile',
+    'init',
+    'help',
+    'version',
+]);
+/**
+ * Sim flags that the legacy `paracosm <flags>` (no subcommand) form
+ * accepted. When any of these appear in argv with no subcommand, the
+ * router falls through to `run` with a deprecation hint instead of
+ * printing help and exiting.
+ */
+const LEGACY_RUN_FLAGS = new Set([
+    '--leader', '--leaders', '--name', '--archetype', '--unit', '--instructions',
+    '--openness', '--conscientiousness', '--extraversion', '--agreeableness',
+    '--emotionality', '--honesty', '--turns', '--seed', '--start-time',
+    '--provider', '--cost', '--live',
+]);
+/**
+ * Inspect argv for a global short-circuit (`--help`, `-h`,
+ * `--version`, `-v`) without consuming positional args.
+ */
+function checkGlobalFlags(argv) {
+    for (const arg of argv) {
+        if (arg === '--help' || arg === '-h')
+            return 'help';
+        if (arg === '--version' || arg === '-v')
+            return 'version';
+    }
+    return null;
+}
+/**
+ * Detect whether legacy bare-command sim invocations were used.
+ * Heuristic: argv has no recognized subcommand at index 0, and at
+ * least one entry is a known sim flag OR a positional integer.
+ */
+function looksLikeLegacyRun(argv) {
+    for (const arg of argv) {
+        if (LEGACY_RUN_FLAGS.has(arg))
+            return true;
+        if (/^\d+$/.test(arg))
+            return true;
+    }
+    return false;
+}
+/**
+ * Dispatch argv to the appropriate subcommand handler. Pure: no
+ * process.exit, no top-level await side effects.
+ */
+export async function dispatch(argv) {
+    // Global short-circuits first; they win at any position.
+    const global = checkGlobalFlags(argv);
+    if (global === 'version') {
+        process.stdout.write(`paracosm ${readPackageVersion()}\n`);
+        return { exitCode: 0 };
+    }
+    if (global === 'help' && (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h')) {
+        printTopLevelHelp();
+        return { exitCode: 0 };
+    }
+    const [command, ...rest] = argv;
+    // No args: print help.
+    if (!command) {
+        printTopLevelHelp();
+        return { exitCode: 0 };
+    }
+    // `--help` / `-h` after a known subcommand: print that command's help.
+    const commandHelpFlagPresent = rest.includes('--help') || rest.includes('-h');
+    if (KNOWN_COMMANDS.has(command) && commandHelpFlagPresent) {
+        printCommandHelp(command);
+        return { exitCode: 0 };
+    }
+    switch (command) {
+        case 'help': {
+            const target = rest[0];
+            if (target) {
+                printCommandHelp(target);
+            }
+            else {
+                printTopLevelHelp();
+            }
+            return { exitCode: 0 };
+        }
+        case 'version': {
+            process.stdout.write(`paracosm ${readPackageVersion()}\n`);
+            return { exitCode: 0 };
+        }
+        case 'run': {
+            const { runSim } = await import('./run-sim.js');
+            const exitCode = await runSim(rest);
+            return { exitCode };
+        }
+        case 'dashboard': {
+            const { runDashboard } = await import('./run-dashboard.js');
+            const exitCode = await runDashboard(rest);
+            return { exitCode };
+        }
+        case 'compile': {
+            const { runCompile } = await import('./run-compile.js');
+            const exitCode = await runCompile(rest);
+            return { exitCode };
+        }
+        case 'init': {
+            const { runInit } = await import('./init.js');
+            const exitCode = await runInit(rest);
+            return { exitCode };
+        }
+        default:
+            // Legacy fallthrough: bare `paracosm --leader 0 6` etc. dispatched
+            // to `run` with a deprecation hint. Removal scheduled for 0.8.0.
+            if (looksLikeLegacyRun(argv)) {
+                const { runSim } = await import('./run-sim.js');
+                const exitCode = await runSim(argv);
+                return {
+                    exitCode,
+                    deprecation: 'bare `paracosm <flags>` is deprecated; use `paracosm run <flags>` instead. Removal in 0.8.0.',
+                };
+            }
+            process.stderr.write(`Unknown command: ${command}\n\n`);
+            printTopLevelHelp();
+            return { exitCode: 1 };
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/cli/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/cli/router.ts"],"names":[],"mappings":"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"}

package/dist/cli/run-compile.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Implementation of `paracosm compile`. Extracted from compile.ts so
+ * the subcommand router can dispatch to it without process-level side
+ * effects firing on import.
+ *
+ * @module paracosm/cli/run-compile
+ */
+/**
+ * Compile a scenario JSON draft. Returns a process exit code.
+ */
+export declare function runCompile(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=run-compile.d.ts.map

package/dist/cli/run-compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-compile.d.ts","sourceRoot":"","sources":["../../src/cli/run-compile.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8DzE"}