fix(keynote-2): split demo and bench CLI parsing (#4703)

# Description of Changes

This cleans up the `keynote-2` benchmark CLI and fixes the `bench` path
that was broken after `demo` and `bench` started sharing a single
parser. `demo` and `bench` now parse their own command grammars instead
of sharing one import-time parser. This avoids `bench` inheriting
`demo`-style validation and breaking on `test-1 --connectors ...`. in
addition, `bench` also uses the same `cac`-builder as `demo` now, and
I've deleted the unused `runner_1.ts`.

# API and ABI breaking changes

None

# Expected complexity level and risk

3

# Testing

Manually tested the following from `templates/keynote-2`:

- `pnpm bench test-1 --seconds 10 --concurrency 50 --alpha 1.5
--connectors spacetimedb`
- `pnpm demo --seconds 1 --concurrency 5 --alpha 1.5 --systems
spacetimedb --skip-prep --no-animation`
- `deno run --sloppy-imports -A src/demo.ts --help`
- `deno run --sloppy-imports -A src/cli.ts --help`
- `deno run --sloppy-imports -A src/cli.ts test-1 --seconds 10
--concurrency 50 --alpha 1.5 --connectors spacetimedb`

Author: joshua-spacetime

templates/keynote-2/.env.example

@@ -5,7 +5,7 @@ USE_DOCKER=1          # 1 = run docker compose up for pg/crdb; 0 = skip
 #SKIP_SQLITE=1         # 1 = don't init SQLite in prep
 #SKIP_SUPABASE=1       # 1 = don't init Supabase in prep
 SKIP_CONVEX=1          # 1 = don't init Convex in prep
-USE_SPACETIME_METRICS_ENDPOINT=0
+SPACETIME_METRICS_ENDPOINT=0
 
 # ===== PostgreSQL =====
 POSTGRES_USER=postgres
@@ -26,7 +26,6 @@ SQLITE_MODE=default
 STDB_URL=ws://127.0.0.1:3000
 STDB_MODULE=test-1
 STDB_MODULE_PATH=./spacetimedb
-STDB_METRICS_URL=http://127.0.0.1:3000/v1/metrics
 STDB_CONFIRMED_READS=1
 
 # ===== Supabase  =====

templates/keynote-2/DEVELOP.md

@@ -34,6 +34,9 @@ The script will:
 - `--skip-prep` - Skip database seeding
 - `--no-animation` - Disable animated output
 
+`demo` always runs the built-in `test-1` scenario. Use `bench` if you need to choose a test explicitly.
+`demo` uses `--systems`; `bench` uses `--connectors`.
+
 ---
 
 ## Prerequisites
@@ -70,7 +73,7 @@ Copy `.env.example` to `.env` and adjust.
 - `SKIP_SQLITE` – `1` = don't init SQLite in prep
 - `SKIP_SUPABASE` – `1` = don't init Supabase in prep
 - `SKIP_CONVEX` – `1` = don't init Convex in prep
-- `USE_SPACETIME_METRICS_ENDPOINT` – `1` = read committed transfer counts from the SpacetimeDB metrics endpoint; otherwise only local counters are used
+- `SPACETIME_METRICS_ENDPOINT` – `1` = read committed transfer counts from the derived SpacetimeDB metrics endpoint; otherwise only local counters are used
 
 **PostgreSQL / CockroachDB:**
 
@@ -87,7 +90,6 @@ Copy `.env.example` to `.env` and adjust.
 - `STDB_URL` – WebSocket URL for SpacetimeDB
 - `STDB_MODULE` – module name to load (e.g. `test-1`)
 - `STDB_MODULE_PATH` – filesystem path to the module source (for local dev)
-- `STDB_METRICS_URL` – HTTP URL for the SpacetimeDB metrics endpoint
 - `STDB_CONFIRMED_READS` – `1` = force confirmed reads on, `0` = force them off
 
 **Supabase:**
@@ -164,26 +166,26 @@ cd ..
 ### 1. Run a test
 
 ```bash
-npm run bench [test-name] [--seconds N] [--concurrency N] [--alpha A] [--connectors list]
+npm run bench -- [test-name] [--seconds N] [--concurrency N] [--alpha A] [--connectors list]
 ```
 
 Examples:
 
 ```bash
-# Default test (test-1), default args (note: only 1 test right now, and it's embedded)
+# Default test (test-1), default args
 npm run bench
 
 # Explicit test name
-npm run bench test-1
+npm run bench -- test-1
 
 # Short run, 100 concurrent workers
-npm run bench test-1 --seconds 10 --concurrency 100
+npm run bench -- test-1 --seconds 10 --concurrency 100
 
 # Heavier skew on hot accounts
-npm run bench test-1 --alpha 2.0
+npm run bench -- test-1 --alpha 2.0
 
 # Only run selected connectors
-npm run bench test-1 --connectors spacetimedb,sqlite
+npm run bench -- test-1 --connectors spacetimedb,sqlite_rpc
 ```
 
 ### 2. Run the distributed TypeScript SpacetimeDB benchmark
@@ -392,7 +394,7 @@ From `src/cli.ts`:
   - Example:
 
     ```bash
-    --connectors spacetimedb,sqlite,postgres
+    --connectors spacetimedb,sqlite_rpc,postgres_rpc
     ```
 
   - If omitted, all connectors for that test are run
@@ -422,7 +424,7 @@ docker compose run --rm bench \
   --connectors convex
 ```
 
-If using Docker, make sure to set `USE_DOCKER=1` in `.env`, verify docker-compose env variables, verify you've run supabase init, and run `npm prep` before running bench.
+If using Docker, make sure to set `USE_DOCKER=1` in `.env`, verify docker-compose env variables, verify you've run supabase init, and run `npm run prep` before running bench.
 
 ## Output
 

templates/keynote-2/README.md

@@ -7,15 +7,16 @@ A benchmark suite comparing SpacetimeDB against traditional web application stac
 See SpacetimeDB's performance advantage with one command:
 
 ```bash
-npm install
+pnpm install
 npm run demo
 ```
 
 The demo compares SpacetimeDB and Convex by default, since both are easy for anyone to set up and run locally without additional infrastructure. Other systems (Postgres, CockroachDB, SQLite, etc.) are also supported but require more setup. The demo checks that required services are running (prompts you to start them if not), seeds databases, and displays animated results.
 
 **Options:** `--systems a,b,c` | `--seconds N` | `--skip-prep` | `--no-animation`
 
-**Note:** You will need to [install Rust](https://rust-lang.org/tools/install/) to run the spacetimedb benchmark, because we run a [Rust Client](#rust-client).
+**Note:** `demo` always runs the built-in `test-1` scenario. Use `bench` if you need to specify a test name directly.
+**Note:** `demo` selects targets with `--systems`; `bench` filters test connectors with `--connectors`.
 
 ## Results Summary
 
@@ -198,7 +199,7 @@ docker compose up -d pg crdb
 npm run prep
 
 # Run benchmark
-npm run bench -- --seconds 10 --concurrency 50 --alpha 1.5 --connectors spacetimedb,postgres_rpc,sqlite_rpc
+npm run bench -- test-1 --seconds 10 --concurrency 50 --alpha 1.5 --connectors spacetimedb,postgres_rpc,sqlite_rpc
 ```
 
 ## Output

templates/keynote-2/src/cli.ts

@@ -6,101 +6,26 @@ import type { TestCaseModule } from './tests/types';
 import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
 import { RunResult } from './core/types.ts';
-
-const args = process.argv.slice(2);
-
-let testName = 'test-1';
-let posArgs = args;
-
-if (args.length > 0 && !args[0].startsWith('--')) {
-  testName = args[0];
-  posArgs = args.slice(1);
-}
-
-let seconds = 1,
-  concurrency = 10,
-  accounts = process.env.SEED_ACCOUNTS
-    ? Number(process.env.SEED_ACCOUNTS)
-    : 100_000,
-  alpha = 1.5,
-  connectors: string[] | null = null,
-  contentionTests: {
-    startAlpha: number;
-    endAlpha: number;
-    step: number;
-    concurrency: number;
-  } | null = null,
-  concurrencyTests: {
-    startConc: number;
-    endConc: number;
-    step: number;
-    alpha: number;
-  } | null = null;
-
-for (let i = 0; i < posArgs.length; ) {
-  const arg = posArgs[i];
-  if (!arg.startsWith('--')) {
-    i++;
-    continue;
-  }
-  const key = arg.slice(2);
-  const val = posArgs[i + 1];
-  if (!val || val.startsWith('--')) {
-    i++;
-    continue;
-  }
-
-  switch (key) {
-    case 'seconds':
-      seconds = Number(val);
-      i += 2;
-      break;
-    case 'concurrency':
-      concurrency = Number(val);
-      i += 2;
-      break;
-    case 'alpha':
-      alpha = Number(val);
-      i += 2;
-      break;
-    case 'connectors':
-      connectors = val
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean);
-      i += 2;
-      break;
-    case 'contention-tests':
-      contentionTests = {
-        startAlpha: Number(posArgs[i + 1]),
-        endAlpha: Number(posArgs[i + 2]),
-        step: Number(posArgs[i + 3]),
-        concurrency: Number(posArgs[i + 4]),
-      };
-      concurrency = Number(posArgs[i + 4]);
-
-      i += 5;
-      break;
-    case 'concurrency-tests':
-      concurrencyTests = {
-        startConc: Number(posArgs[i + 1]),
-        endConc: Number(posArgs[i + 2]),
-        step: Number(posArgs[i + 3]),
-        alpha: Number(posArgs[i + 4]),
-      };
-      alpha = Number(posArgs[i + 4]);
-
-      i += 5;
-      break;
-  }
-}
-
-interface BenchmarkConfig {
-  connector: any;
-  scenario: any;
-  seconds: number;
-  accounts: number;
-}
+import { parseBenchOptions } from './opts.ts';
+
+const options = parseBenchOptions();
+const {
+  testName,
+  seconds,
+  concurrency,
+  accounts,
+  alpha,
+  connectors,
+  contentionTests,
+  concurrencyTests,
+} = options;
+
+type RunOneArgs = Parameters<typeof runOne>[0];
+
+type BenchmarkConfig = Pick<
+  RunOneArgs,
+  'connector' | 'scenario' | 'seconds' | 'accounts' | 'runtimeConfig'
+>;
 
 class BenchmarkTester {
   private config: BenchmarkConfig;
@@ -229,11 +154,17 @@ const testDirPath = fileURLToPath(testDirUrl);
     const makeConnector = CONNECTORS[tc.system];
     if (!makeConnector) throw new Error(`Unknown connector ${tc.system}`);
 
-    const connector = makeConnector();
+    const connector = makeConnector(options);
 
     let res: any;
 
-    const config = { connector, scenario: tc.run, seconds, accounts };
+    const config = {
+      connector,
+      scenario: tc.run,
+      seconds,
+      accounts,
+      runtimeConfig: options,
+    };
 
     const tester = new BenchmarkTester(config);
 
@@ -259,6 +190,7 @@ const testDirPath = fileURLToPath(testDirUrl);
         concurrency,
         accounts,
         alpha,
+        runtimeConfig: options,
       });
     }