volaro 0.0.2 → 0.1.0-alpha.10

package/bin/vl.js

@@ -1,34 +1,835 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
+// The `volaro` command (alias: `vl`): a thin Node wrapper around the Volaro compiler, which
+// ships as Python sources under ../compiler and is invoked as a subprocess.
+//
+//   volaro check <path>...        validate .vl source (lexer / parser / resolver)
+//   volaro build <file.vl>        transpile to a runnable bundle
+//   volaro dev [file.vl]          build, serve on localhost, rebuild on change
+//   volaro routes [project]       print discovered pages and the page-server route manifest
+//   volaro crib | volaro spec         print the language reference
+//   volaro example <name>         print a worked example
+//   volaro version | volaro help
+//
+// Python is located and version-checked up front with an actionable message
+// (see ../lib/env.js). Nothing here depends on the Volaro repository layout.
+
+import { appendFileSync, readFileSync, existsSync, statSync, lstatSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve as resolvePath, extname, relative, sep, delimiter } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { createServer } from "node:http";
+import { resolvePython, nodeCanRunServer, VolaroEnvError, MIN_NODE_FOR_SERVER } from "../lib/env.js";
 
 const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const read = (p) => readFileSync(join(root, p), "utf8");
-const { version } = JSON.parse(read("package.json"));
-const cmd = process.argv[2];
-
-if (cmd === "crib") process.stdout.write(read("language/crib.md"));
-else if (cmd === "spec") process.stdout.write(read("language/spec.md"));
-else if (cmd === "example") {
-  const n = process.argv[3];
-  if (n === "sensors" || n === "station") process.stdout.write(read(`examples/${n}.vl`));
-  else console.log("usage: vl example sensors|station");
-} else {
-  console.log(`Volaro ${version} — pre-release.
-
-An application language written to be authored by an AI agent and read by a
-person: views, HTTP endpoints, outbound API clients and user accounts.
-
-  vl crib               the one-page language reference (~1,700 tokens)
-  vl spec               the full language specification
-  vl example sensors    a worked example — models, unions, a fallible fn
-  vl example station    a worked example — a guarded service and a view
-
-TO AN AI AGENT reading this: run \`vl crib\` and load its output. That is the
-complete authoring reference — it is designed to be read once and written from.
-
-The toolchain (vl new / check / build / dev) is not published yet, so Volaro
-written today cannot yet be compiled from this package.
-`);
+const pkg = JSON.parse(read("package.json"));
+
+// The canonical command is `volaro`; `vl` is a compatibility alias. Messages
+// use whichever name this process was invoked as, defaulting to `volaro`.
+const CLI = (() => {
+  const b = (process.argv[1] || "").split(/[\\/]/).pop() || "";
+  return b === "vl" || b === "vl.js" ? "vl" : "volaro";
+})();
+
+const COMPILER = join(root, "compiler");
+const VALIDATOR_PP = join(COMPILER, "validator");
+const VLBUILD_PP = join(COMPILER, "vlbuild");
+
+function fail(msg, code = 1) {
+  process.stderr.write((msg.endsWith("\n") ? msg : msg + "\n"));
+  process.exit(code);
+}
+
+function haveCompiler() {
+  return existsSync(join(VALIDATOR_PP, "vlcheck", "__main__.py")) &&
+    existsSync(join(VLBUILD_PP, "vlbuild", "__main__.py"));
+}
+
+function python() {
+  if (!haveCompiler()) {
+    fail(
+      `${CLI}: the bundled compiler is missing from this package.\n` +
+        "If you are working inside the Volaro repo, run:\n" +
+        "  bash packaging/volaro/scripts/sync-compiler.sh\n" +
+        "An installed copy from `npm pack` / a published release always includes it.",
+    );
+  }
+  try {
+    return resolvePython();
+  } catch (err) {
+    if (err instanceof VolaroEnvError) fail(`${CLI}: ` + err.message);
+    throw err;
+  }
+}
+
+// Shared Python-invocation setup for both the streaming and capturing paths.
+function pyInvocation(pp, moduleName, moduleArgs) {
+  const py = python();
+  const env = {
+    ...process.env,
+    PYTHONPATH: [pp, VALIDATOR_PP, process.env.PYTHONPATH].filter(Boolean).join(delimiter),
+    PYTHONDONTWRITEBYTECODE: "1",
+    // Diagnostics and build summaries contain non-ASCII (box drawing, arrows).
+    // Without this, Windows encodes a redirected stdout with the legacy code
+    // page and the compiler dies with UnicodeEncodeError; the capturing path
+    // below also decodes the child's output as UTF-8.
+    PYTHONIOENCODING: "utf-8",
+  };
+  return { cmd: py.cmd, argv: ["-B", "-m", moduleName, ...moduleArgs], env };
+}
+
+function elapsedMs(start) {
+  return Number(process.hrtime.bigint() - start) / 1e6;
+}
+
+function roundedMs(value) {
+  return Math.round(value * 1000) / 1000;
+}
+
+function benchmarkRecords(path, runId) {
+  if (!existsSync(path)) return [];
+  let raw;
+  try {
+    const st = statSync(path);
+    if (st.isDirectory()) {
+      fail(`${CLI}: benchmark log ${path} is a directory, not a file`);
+    }
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    fail(`${CLI}: cannot read benchmark log ${path}: ${err.message}`);
+  }
+  return raw
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        fail(`${CLI}: invalid JSONL in benchmark log ${path} at line ${index + 1}: ` +
+             `${JSON.stringify(line.length > 80 ? line.slice(0, 80) + "…" : line)}`);
+      }
+    })
+    .filter((row) => row.schema === "volaro.compile-timing.v1" && row.run_id === runId);
+}
+
+function appendBenchmark(path, record) {
+  try {
+    appendFileSync(path, JSON.stringify(record) + "\n", { encoding: "utf8", flag: "a" });
+  } catch (err) {
+    fail(`${CLI}: cannot append benchmark log ${path}: ${err.message}`);
+  }
+}
+
+function ensureBenchmarkLog(path) {
+  try {
+    appendFileSync(path, "", { encoding: "utf8", flag: "a" });
+  } catch (err) {
+    fail(`${CLI}: cannot open benchmark log ${path}: ${err.message}`);
+  }
+}
+
+function compilerProvenance() {
+  try {
+    return JSON.parse(readFileSync(join(COMPILER, "SOURCE_INFO.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function parseBenchmarkArgs(args, command) {
+  let log = null;
+  let runId = null;
+  let logCount = 0;
+  let runCount = 0;
+  const compilerArgs = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--benchmark-log" || arg === "--benchmark-run") {
+      if (i + 1 >= args.length || args[i + 1].startsWith("--")) {
+        fail(`${CLI} ${command}: ${arg} requires a value`, 2);
+      }
+      if (arg === "--benchmark-log") {
+        log = args[++i];
+        logCount++;
+      } else {
+        runId = args[++i];
+        runCount++;
+      }
+    } else if (arg.startsWith("--benchmark-log=")) {
+      log = arg.slice("--benchmark-log=".length);
+      logCount++;
+    } else if (arg.startsWith("--benchmark-run=")) {
+      runId = arg.slice("--benchmark-run=".length);
+      runCount++;
+    } else {
+      compilerArgs.push(arg);
+    }
+  }
+  if ((log === null) !== (runId === null)) {
+    fail(`${CLI} ${command}: --benchmark-log and --benchmark-run must be supplied together`, 2);
+  }
+  if (logCount > 1 || runCount > 1) {
+    fail(`${CLI} ${command}: benchmark options may be supplied only once`, 2);
+  }
+  if (log !== null && log.trim() === "") {
+    fail(`${CLI} ${command}: --benchmark-log must not be empty`, 2);
+  }
+  if (runId !== null && runId.trim() === "") {
+    fail(`${CLI} ${command}: --benchmark-run must not be empty`, 2);
+  }
+  return {
+    args: compilerArgs,
+    benchmark: log === null ? null : { log: resolvePath(log), runId },
+  };
+}
+
+// Four possible outcomes for a FAILED attempt (never called for exitCode 0).
+// This is the entire classification: it never inspects captured stdout/
+// stderr TEXT, only (a) whether the OS delivered a kill signal and (b)
+// the compiler's own structural report of what kind of stop it made (see
+// `vlcheck/benchmark_signal.py`'s module docstring). "Any output happened"
+// is deliberately NOT a diagnostic signal on its own -- an internal
+// traceback is output too.
+function classifyAttempt(signal, benchmarkSignal, firstOutputMs) {
+  if (signal) return "operational_failure"; // killed by the OS, never a diagnostic
+  if (benchmarkSignal) {
+    if (benchmarkSignal.kind === "crash") return "operational_failure";
+    if (benchmarkSignal.kind === "diagnostic") {
+      // Each module's OWN reserved "diagnostics found in valid input" code
+      // is exactly 1 (see vlcheck/vlbuild __main__.py); any other code the
+      // compiler intentionally stopped with (a usage/configuration error,
+      // for instance) is a real, honest stop but not a SOURCE diagnostic.
+      return benchmarkSignal.exit_code === 1 ? "source_diagnostic" : "operational_failure";
+    }
+  }
+  // No structured signal reached us at all: the compiler crashed before
+  // reaching its own signal-emission wrapper (an import-time failure, an
+  // interpreter that never started, a segfault) or the side channel was
+  // lost. Distinguished only by whether anything was captured on stdout/
+  // stderr, not by reading it.
+  return firstOutputMs === null ? "silent_failure" : "unknown_failure";
+}
+
+function writeBenchmarkResult(benchmark, command, compilerArgv, code, signal, startedAt,
+                              startedMono, firstOutputMs, benchmarkSignal) {
+  const finishedEpochMs = Date.now();
+  const durationMs = elapsedMs(startedMono);
+  const prior = benchmarkRecords(benchmark.log, benchmark.runId);
+  if (prior.some((row) => row.record === "summary")) {
+    fail(`${CLI}: benchmark run ${JSON.stringify(benchmark.runId)} is already complete`, 2);
+  }
+
+  const attempts = prior.filter((row) => row.record === "attempt");
+  const exitCode = signal ? 1 : code ?? 0;
+  const provenance = compilerProvenance();
+  const classification = exitCode === 0 ? null : classifyAttempt(signal, benchmarkSignal, firstOutputMs);
+  const attempt = {
+    schema: "volaro.compile-timing.v1",
+    record: "attempt",
+    run_id: benchmark.runId,
+    attempt: attempts.length + 1,
+    command,
+    compiler_argv: compilerArgv,
+    compiler_version: pkg.version,
+    compiler_revision: provenance.revision || null,
+    compiler_content_sha256: provenance.content_sha256 || null,
+    started_at: startedAt,
+    finished_at: new Date(finishedEpochMs).toISOString(),
+    exit_code: exitCode,
+    signal: signal || null,
+    outcome: exitCode === 0 ? "success" : "failure",
+    classification,
+    duration_ms: roundedMs(durationMs),
+    // Raw fact, any classification: did output arrive, and when -- kept
+    // even for a crash/silent/unknown failure as the "available output
+    // metadata" a human investigating an invalid run needs.
+    first_output_ms: firstOutputMs === null ? null : roundedMs(firstOutputMs),
+    // Only ever populated for a genuine source diagnostic -- T-fail's
+    // whole point is "how long until the compiler told you about YOUR
+    // bug", which an operational/silent/unknown failure never did.
+    first_diagnostic_ms: classification === "source_diagnostic" && firstOutputMs !== null
+      ? roundedMs(firstOutputMs) : null,
+    crash_exception_type: benchmarkSignal && benchmarkSignal.kind === "crash"
+      ? benchmarkSignal.exception_type : null,
+    crash_exception_message: benchmarkSignal && benchmarkSignal.kind === "crash"
+      ? benchmarkSignal.exception_message : null,
+  };
+  appendBenchmark(benchmark.log, attempt);
+
+  if (exitCode !== 0) return;
+
+  const allAttempts = [...attempts, attempt];
+  const failures = allAttempts.filter((row) => row.outcome === "failure");
+  if (failures.length === 0) {
+    appendBenchmark(benchmark.log, {
+      schema: "volaro.compile-timing.v1",
+      record: "summary",
+      run_id: benchmark.runId,
+      command,
+      outcome: "clean",
+      timing_complete: true,
+      timing_incomplete_reason: null,
+      clock_anomaly: false,
+      attempt_count: 1,
+      failed_attempts: 0,
+      t_clean_ms: attempt.duration_ms,
+      t_fail_ms: null,
+      t_repair_ms: null,
+      t_recompile_ms: null,
+      t_recover_ms: null,
+      compiler_overhead_ms: null,
+    });
+    return;
+  }
+
+  // Wall-clock gaps between separate process invocations, computed from
+  // each process's own Date.now()-derived timestamps -- vulnerable to a
+  // backward system clock step (an NTP sync) between two attempts. A
+  // negative gap is never clamped to zero and reported as if it were a
+  // real, small repair time: that would silently corrupt the median/p90
+  // aggregation STAGE3-PROTOCOL.md §6.1 defines over this data. Instead
+  // the whole run is marked invalid for recovery-time comparison, with
+  // every raw timestamp still preserved untouched in the attempts above.
+  let repairMs = 0;
+  let clockAnomaly = false;
+  for (let i = 1; i < allAttempts.length; i++) {
+    const previous = allAttempts[i - 1];
+    if (previous.outcome === "failure") {
+      const gap = Date.parse(allAttempts[i].started_at) - Date.parse(previous.finished_at);
+      if (gap < 0) clockAnomaly = true;
+      repairMs += gap;
+    }
+  }
+  const first = allAttempts[0];
+  const recoverMs = finishedEpochMs - Date.parse(first.started_at);
+  if (recoverMs < 0) clockAnomaly = true;
+
+  const firstIsDiagnostic = first.classification === "source_diagnostic";
+  const failMs = firstIsDiagnostic ? first.first_diagnostic_ms : null;
+  const timingComplete = firstIsDiagnostic && !clockAnomaly;
+  const compilerOverheadMs = timingComplete
+    ? recoverMs - failMs - repairMs - attempt.duration_ms
+    : null;
+
+  let timingIncompleteReason = null;
+  if (!firstIsDiagnostic) {
+    timingIncompleteReason = `the original failing attempt was classified ` +
+      `${JSON.stringify(first.classification)}, not "source_diagnostic" -- ` +
+      `t_fail_ms and compiler_overhead_ms are not valid recovery-time samples for this run`;
+  } else if (clockAnomaly) {
+    timingIncompleteReason = "a wall-clock timestamp in this run predates an earlier one " +
+      "(a backward system clock step between two compiler invocations) -- " +
+      "t_repair_ms/t_recover_ms/compiler_overhead_ms are not valid recovery-time samples for this run";
+  }
+
+  appendBenchmark(benchmark.log, {
+    schema: "volaro.compile-timing.v1",
+    record: "summary",
+    run_id: benchmark.runId,
+    command,
+    outcome: "recovered",
+    timing_complete: timingComplete,
+    timing_incomplete_reason: timingIncompleteReason,
+    clock_anomaly: clockAnomaly,
+    attempt_count: allAttempts.length,
+    failed_attempts: failures.length,
+    t_clean_ms: null,
+    t_fail_ms: failMs,
+    t_repair_ms: clockAnomaly ? null : roundedMs(repairMs),
+    t_recompile_ms: attempt.duration_ms,
+    t_recover_ms: clockAnomaly ? null : roundedMs(recoverMs),
+    compiler_overhead_ms: timingComplete ? roundedMs(Math.max(0, compilerOverheadMs)) : null,
+  });
+}
+
+// Run a Python module, streaming its output, and exit with its status.
+function runPython(pp, moduleName, moduleArgs, benchmark = null, command = moduleName) {
+  const { cmd, argv, env } = pyInvocation(pp, moduleName, moduleArgs);
+  if (!benchmark) {
+    const child = spawn(cmd, argv, { stdio: "inherit", env });
+    child.on("error", (e) => fail(`${CLI}: failed to start Python (${cmd}): ${e.message}`));
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : code ?? 0));
+    return;
+  }
+
+  ensureBenchmarkLog(benchmark.log);
+  const existing = benchmarkRecords(benchmark.log, benchmark.runId);
+  if (existing.some((row) => row.record === "summary")) {
+    fail(`${CLI}: benchmark run ${JSON.stringify(benchmark.runId)} is already complete`, 2);
+  }
+  if (existing.some((row) => row.record === "attempt" && row.command !== command)) {
+    fail(`${CLI}: benchmark run ${JSON.stringify(benchmark.runId)} cannot mix check and build`, 2);
+  }
+  const compilerArgv = [moduleName, ...moduleArgs];
+  if (existing.some((row) => row.record === "attempt" &&
+      JSON.stringify(row.compiler_argv) !== JSON.stringify(compilerArgv))) {
+    fail(`${CLI}: benchmark run ${JSON.stringify(benchmark.runId)} must reuse the exact compiler command`, 2);
+  }
+
+  const startedEpochMs = Date.now();
+  const startedAt = new Date(startedEpochMs).toISOString();
+  const startedMono = process.hrtime.bigint();
+  let firstOutputMs = null;
+  // fd 3: a private side channel the compiler writes its own structural
+  // diagnostic/crash signal to (see vlcheck/benchmark_signal.py) -- never
+  // stdout/stderr, so ordinary output forwarded to the terminal below is
+  // untouched by this. VOLARO_BENCHMARK_SIGNAL_FD tells the compiler that
+  // channel exists; it is a documented no-op when unset, which is exactly
+  // every non-benchmark invocation.
+  const child = spawn(cmd, argv, {
+    stdio: ["inherit", "pipe", "pipe", "pipe"],
+    env: { ...env, PYTHONUNBUFFERED: "1", VOLARO_BENCHMARK_SIGNAL_FD: "3" },
+  });
+  const forward = (stream, target) => stream.on("data", (chunk) => {
+    if (firstOutputMs === null) firstOutputMs = elapsedMs(startedMono);
+    target.write(chunk);
+  });
+  forward(child.stdout, process.stdout);
+  forward(child.stderr, process.stderr);
+  const signalChunks = [];
+  child.stdio[3].on("data", (chunk) => signalChunks.push(chunk));
+  child.on("error", (e) => fail(`${CLI}: failed to start Python (${cmd}): ${e.message}`));
+  child.on("close", (code, signal) => {
+    let benchmarkSignal = null;
+    const signalRaw = Buffer.concat(signalChunks).toString("utf8").trim();
+    if (signalRaw) {
+      // The compiler writes exactly one JSON line and closes the stream
+      // (benchmark_signal.py); take the first line defensively rather than
+      // assuming that held.
+      try {
+        benchmarkSignal = JSON.parse(signalRaw.split(/\r?\n/)[0]);
+      } catch {
+        benchmarkSignal = null; // malformed signal -> falls through to unknown_failure
+      }
+    }
+    writeBenchmarkResult(benchmark, command, compilerArgv, code, signal, startedAt,
+                         startedMono, firstOutputMs, benchmarkSignal);
+    process.exit(signal ? 1 : code ?? 0);
+  });
+}
+
+function pyCapture(pp, moduleName, moduleArgs) {
+  const { cmd, argv, env } = pyInvocation(pp, moduleName, moduleArgs);
+  return spawnSync(cmd, argv, { encoding: "utf8", env });
+}
+
+// ---- subcommands -----------------------------------------------------------
+
+function cmdCheck(args) {
+  const parsed = parseBenchmarkArgs(args, "check");
+  if (parsed.args.length === 0) fail("usage: volaro check <file-or-dir>... [--release] [--config PATH]");
+  // Always resolve: a bare structural pass is weaker than the real check.
+  runPython(VALIDATOR_PP, "vlcheck", ["--resolve", ...parsed.args], parsed.benchmark, "check");
+}
+
+function parseBuildArgs(args) {
+  const out = { source: null, o: null, data: null, release: false, config: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "-o" || a === "--out") out.o = args[++i];
+    else if (a === "--data") out.data = args[++i];
+    else if (a === "--config") out.config = args[++i];
+    else if (a === "--release") out.release = true;
+    else if (a.startsWith("-")) fail(`volaro build: unknown option ${a}`);
+    else if (!out.source) out.source = a;
+    else fail(`volaro build: unexpected argument ${a}`);
+  }
+  return out;
+}
+
+function resolveEntry(explicit) {
+  if (explicit) {
+    if (!existsSync(explicit)) fail(`${CLI}: no such file: ${explicit}`);
+    return resolvePath(explicit);
+  }
+  for (const c of ["app.vl", join("src", "app.vl")]) {
+    if (existsSync(c)) return resolvePath(c);
+  }
+  fail(
+    "volaro: no entry file given and no app.vl found in this directory.\n" +
+      "Pass one explicitly:  volaro build path/to/app.vl",
+  );
+}
+
+function cmdBuild(args) {
+  const parsed = parseBenchmarkArgs(args, "build");
+  const b = parseBuildArgs(parsed.args);
+  const source = resolveEntry(b.source);
+  const outDir = b.o ? resolvePath(b.o) : resolvePath("build");
+  const pyArgs = [source, "-o", outDir];
+  if (b.data) pyArgs.push("--data", resolvePath(b.data));
+  if (b.config) pyArgs.push("--config", resolvePath(b.config));
+  if (b.release) pyArgs.push("--release");
+  runPython(VLBUILD_PP, "vlbuild", pyArgs, parsed.benchmark, "build");
+}
+
+// Synchronous single build for `volaro dev`; returns { ok, server } or exits on env error.
+function buildOnce(source, outDir, extra = []) {
+  const r = pyCapture(VLBUILD_PP, "vlbuild", [source, "-o", outDir, ...extra]);
+  if (r.error) fail(`${CLI}: failed to start Python: ${r.error.message}`);
+  if (r.stdout) process.stdout.write(r.stdout);
+  if (r.stderr) process.stderr.write(r.stderr);
+  return { ok: r.status === 0, server: existsSync(join(outDir, "server.js")) };
+}
+
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".map": "application/json",
+};
+
+function staticServer(dir, port) {
+  const base = resolvePath(dir);
+  const srv = createServer((req, res) => {
+    let rel = decodeURIComponent((req.url || "/").split("?")[0]);
+    if (rel.endsWith("/")) rel += "index.html";
+    const target = resolvePath(join(base, rel));
+    // Contain to `base`: an exact match, or a path that starts with `base` +
+    // separator. A bare `startsWith(base)` would also accept a sibling like
+    // `<base>-notes/…`.
+    if (target !== base && !target.startsWith(base + sep)) {
+      res.writeHead(403).end("forbidden");
+      return;
+    }
+    if (!existsSync(target) || statSync(target).isDirectory()) {
+      res.writeHead(404, { "content-type": "text/html; charset=utf-8" });
+      res.end("<!doctype html><meta charset=utf-8><title>404</title><p>Not found. The dev server serves the built bundle in <code>" + dir + "</code>.");
+      return;
+    }
+    res.writeHead(200, { "content-type": MIME[extname(target)] || "application/octet-stream", "cache-control": "no-store" });
+    res.end(readFileSync(target));
+  });
+  srv.on("error", (e) => {
+    if (e.code === "EADDRINUSE") fail(`volaro dev: port ${port} is already in use. Pass --port <n>.`);
+    fail(`volaro dev: ${e.message}`);
+  });
+  srv.listen(port, "127.0.0.1");
+  return srv;
+}
+
+// Snapshot every .vl file under dir (bounded depth) as path -> "mtime:size".
+// Polling beats fs.watch here: it is identical across platforms and editors
+// (rename-replace, truncate-write and append all show up), which fs.watch is
+// not, and the cost is trivial for a project-sized tree.
+function scanVl(dir, depth = 6, acc = new Map(), excluded = null) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    if (e.name === "node_modules" || e.name === ".git" || e.name.startsWith(".")) continue;
+    const p = join(dir, e.name);
+    if (resolvePath(p) === excluded) continue;
+    if (e.isDirectory()) {
+      if (depth > 0) scanVl(p, depth - 1, acc, excluded);
+    } else if (extname(e.name) === ".vl") {
+      try {
+        const s = statSync(p);
+        acc.set(p, `${s.mtimeMs}:${s.size}`);
+      } catch {}
+    }
+  }
+  return acc;
+}
+
+function snapEqual(a, b) {
+  if (a.size !== b.size) return false;
+  for (const [k, v] of a) if (b.get(k) !== v) return false;
+  return true;
+}
+
+// Poll watchDir for .vl changes and call onChange (debounced by the interval).
+// Returns a close() that stops polling.
+function watchVl(watchDir, onChange, outDir) {
+  const snapshot = () => {
+    const acc = scanVl(watchDir, 6, new Map(), resolvePath(outDir));
+    const scanAssets = (dir) => {
+      try {
+        const s = lstatSync(dir);
+        acc.set(dir, `${s.mtimeMs}:${s.ctimeMs}:${s.size}`);
+        if (s.isDirectory() && !s.isSymbolicLink()) {
+          for (const name of readdirSync(dir)) scanAssets(join(dir, name));
+        }
+      } catch {}
+    };
+    scanAssets(join(watchDir, "assets"));
+    return acc;
+  };
+  let prev = snapshot();
+  const iv = setInterval(() => {
+    const now = snapshot();
+    if (!snapEqual(prev, now)) {
+      prev = now;
+      onChange();
+    }
+  }, 250);
+  iv.unref();
+  return () => clearInterval(iv);
+}
+
+function cmdDev(args) {
+  let source = null,
+    port = 5173,
+    outDir = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--port" || a === "-p") port = Number(args[++i]);
+    else if (a === "-o" || a === "--out") outDir = args[++i];
+    else if (a.startsWith("-")) fail(`volaro dev: unknown option ${a}`);
+    else if (!source) source = a;
+  }
+  if (!Number.isInteger(port) || port < 1 || port > 65535) fail("volaro dev: --port must be 1..65535");
+  const entry = resolveEntry(source);
+  const out = outDir ? resolvePath(outDir) : resolvePath("build");
+  // A project build's entry is the project directory itself (`volaro dev .`);
+  // watching its dirname would watch the PARENT directory instead.
+  const watchDir = statSync(entry).isDirectory() ? entry : dirname(entry);
+
+  process.stdout.write(`volaro dev: building ${relative(process.cwd(), entry) || entry}\n`);
+  const first = buildOnce(entry, out);
+  if (!first.ok) fail("volaro dev: initial build failed. Fix the errors above and re-run.");
+
+  let shuttingDown = false;
+  let stopWatch = () => {};
+
+  // ---- full-stack: run server.js, restart it on a successful rebuild ----
+  if (first.server) {
+    if (!nodeCanRunServer()) {
+      fail(
+        `volaro dev: this app builds a full-stack server (server.js), which needs Node ` +
+          `${MIN_NODE_FOR_SERVER.join(".")}+ for node:sqlite. You have ${process.versions.node}.`,
+      );
+    }
+    const serverPath = join(out, "server.js");
+    let child = null;
+    let restarting = false;
+
+    const startServer = () => {
+      child = spawn(process.execPath, [serverPath], {
+        stdio: "inherit",
+        env: { ...process.env, PORT: String(port) },
+      });
+      child.on("exit", (code, signal) => {
+        if (shuttingDown || restarting) return;
+        // the server died on its own (e.g. a port clash it reported to stderr)
+        stopWatch();
+        process.exit(signal ? 1 : code ?? 0);
+      });
+    };
+
+    const restartServer = () =>
+      new Promise((done) => {
+        if (!child) return done();
+        restarting = true;
+        child.once("exit", () => {
+          restarting = false;
+          done();
+        });
+        child.kill("SIGTERM");
+      });
+
+    process.stdout.write(`volaro dev: full-stack app — starting ${relative(process.cwd(), serverPath) || serverPath}\n`);
+    startServer();
+
+    stopWatch = watchVl(watchDir, async () => {
+      process.stdout.write("volaro dev: change detected — rebuilding\n");
+      const r = buildOnce(entry, out);
+      if (!r.ok) {
+        process.stdout.write("volaro dev: build failed — server left running on the last good build\n");
+        return;
+      }
+      await restartServer();
+      startServer();
+      process.stdout.write("volaro dev: server restarted\n");
+    }, out);
+
+    const bye = () => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      stopWatch();
+      if (child) child.kill("SIGTERM");
+      setTimeout(() => {
+        if (child) child.kill("SIGKILL");
+        process.exit(0);
+      }, 2000).unref();
+      if (child) child.once("exit", () => process.exit(0));
+      else process.exit(0);
+    };
+    process.on("SIGINT", bye);
+    process.on("SIGTERM", bye);
+    return;
+  }
+
+  // ---- static single-page: serve the bundle, rebuild on change ----
+  const srv = staticServer(out, port);
+  process.stdout.write(`volaro dev: serving http://127.0.0.1:${port}  (Ctrl+C to stop)\n`);
+
+  stopWatch = watchVl(watchDir, () => {
+    process.stdout.write("volaro dev: change detected — rebuilding\n");
+    const r = buildOnce(entry, out);
+    process.stdout.write(r.ok ? "volaro dev: rebuilt\n" : "volaro dev: build failed — keeping last good bundle\n");
+  }, out);
+
+  const bye = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    stopWatch();
+    srv.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 1000).unref();
+  };
+  process.on("SIGINT", bye);
+  process.on("SIGTERM", bye);
+}
+
+function cmdReference(which) {
+  if (which === "spec") {
+    // `volaro-language-spec.md` is the whole-language DESIGN — a superset of
+    // what this build accepts. `supported.md` is the version-specific
+    // shipped-feature guide; `crib.md` is the authoring reference.
+    process.stderr.write(
+      `note: \`${CLI} spec\` is the full language design — a SUPERSET of this build.\n` +
+        `      \`${CLI} supported\` is what version ${pkg.version} actually accepts;\n` +
+        `      \`${CLI} crib\` is the authoring reference.\n\n`,
+    );
+  }
+  const file = which === "supported" ? "supported" : which;
+  // `supported.md`'s own title carries this build's exact version as a
+  // `{{VERSION}}` placeholder rather than a hardcoded string -- found stale
+  // (still reading a prior release's version after a version bump, since
+  // nothing kept it in sync) in the Test_003 benchmark's packaged-docs
+  // finding. Substituted from `package.json` at print time so it can never
+  // drift again, the same way the "supported"-vs-"spec" note above already
+  // reads `pkg.version` live rather than a copy-pasted string.
+  process.stdout.write(read(`language/${file}.md`).replace("{{VERSION}}", pkg.version));
+}
+
+function cmdExample(name) {
+  if (name === "sensors" || name === "station") process.stdout.write(read(`examples/${name}.vl`));
+  else fail("usage: volaro example sensors|station");
+}
+
+function cmdRoutes(args) {
+  let json = false;
+  let project = null;
+  for (const a of args) {
+    if (a === "--json") json = true;
+    else if (a.startsWith("-")) fail(`usage: volaro routes [project] [--json]`, 2);
+    else if (!project) project = a;
+    else fail(`usage: volaro routes [project] [--json]`, 2);
+  }
+  const pyArgs = [resolvePath(project || ".")];
+  if (json) pyArgs.push("--json");
+  runPython(VALIDATOR_PP, "vlcheck.routes_cli", pyArgs);
+}
+
+const HELP = `Volaro ${pkg.version} — an application language for AI authoring and human review.
+
+USAGE
+  volaro <command> [args]         (installed as both \`volaro\` and \`vl\`;
+                                   \`volaro\` is the canonical name)
+
+COMMANDS
+  check <path>...        Validate .vl source. Runs the full resolver, not just
+                         a structural pass. Exit non-zero on any error.
+      --benchmark-log <file>  append raw timing records as JSONL
+      --benchmark-run <id>    group attempts into one clean/recovery trial
+  build <file.vl>        Transpile to a runnable bundle (default: ./build).
+      -o <dir>             output directory
+      --data <file>        data.json to bundle
+      --release            fail on unresolved placeholders (e.g. img alt_todo:)
+                           and ship the minified runtime
+      --benchmark-log <file>  append raw timing records as JSONL
+      --benchmark-run <id>    group attempts into one clean/recovery trial
+  dev [file.vl]         Build, serve on http://127.0.0.1:5173, and rebuild
+                         when a .vl file changes. Defaults to ./app.vl. A
+                         full-stack build runs server.js instead (Node 22.5+)
+                         and restarts it after each successful rebuild.
+      --port <n>           dev server port (passed to server.js as $PORT)
+  routes [project]       Print discovered browser pages (spec §8.15: URL,
+                         source, layout chain, boundaries) and the
+                         page-server route manifest (spec §10.2: final URL,
+                         method, source file, parameter types, generated
+                         client member, authorization). Project defaults to
+                         ".". Exits non-zero on any collision or project-
+                         validity error (page/route or layout-composition).
+      --json               emit the language-neutral manifest as JSON
+  crib                   The authoring reference (write from this).
+  supported             What version ${pkg.version} actually accepts.
+  spec                   The full language design (a SUPERSET of this build).
+  example <name>         Print a worked example: sensors | station.
+  version               Print the version.
+  help                  This message.
+
+The compiler is Python and ships inside this package. Set VOLARO_PYTHON to
+choose the interpreter if \`python3\` is not the one you want.
+
+SHIPPED SUBSET: single page (no router); \`input\` (full type matrix incl.
+checkbox/radio), \`textarea\`, \`select\`/\`option\`/\`optgroup\`,
+\`fieldset\`/\`legend\`, \`datalist\`, \`button\` (a toggle is \`button pressed:\`,
+aria-pressed; no switch role), \`link\` (no standalone \`label\`); \`if\` as an expression is
+binary; \`match\` is a statement; a module-level \`fn\` cannot be called from a
+view. \`volaro crib\` + \`volaro supported\` are authoritative for this build;
+\`volaro spec\` is the wider design, not what it accepts.
+
+Run commands via your project's \`npm run …\` scripts or \`npx --no-install
+volaro …\` inside the project. A bare \`npx volaro …\` from elsewhere may fetch
+the wrong thing.
+
+TO AN AI AGENT: run \`volaro crib\` and load its output — that is the complete
+authoring reference. Then write source, run \`volaro check\`, and repair from the
+diagnostics until it is clean.`;
+
+// ---- dispatch ------------------------------------------------------------
+
+const [cmd, ...rest] = process.argv.slice(2);
+switch (cmd) {
+  case "check":
+    cmdCheck(rest);
+    break;
+  case "build":
+    cmdBuild(rest);
+    break;
+  case "dev":
+    cmdDev(rest);
+    break;
+  case "routes":
+    cmdRoutes(rest);
+    break;
+  case "crib":
+    cmdReference("crib");
+    break;
+  case "spec":
+    cmdReference("spec");
+    break;
+  case "supported":
+    cmdReference("supported");
+    break;
+  case "example":
+    cmdExample(rest[0]);
+    break;
+  case "version":
+  case "--version":
+  case "-v":
+    process.stdout.write(pkg.version + "\n");
+    break;
+  case undefined:
+  case "help":
+  case "--help":
+  case "-h":
+    process.stdout.write(HELP + "\n");
+    break;
+  default:
+    fail(`${CLI}: unknown command "${cmd}". Run \`${CLI} help\`.`, 2);
 }