volaro 0.0.2 → 0.1.0-alpha.3

package/README.md

@@ -1,46 +1,138 @@
 # Volaro
 
-**Pre-release language reference CLI — compiler not included.**
+**Limited alpha, published as `0.1.0-alpha.1` under the `alpha` dist-tag** —
+`npm install volaro@alpha`. Not `latest` (that still resolves to an earlier
+`0.0.x` placeholder) — always specify `@alpha` or the exact version.
 
 Volaro is an experimental application language intended for AI authoring and
-human review. This package contains its specification, authoring crib and
-examples. It does not include the repository's prototype compiler.
+human review. This package ships the language reference **and a working
+compiler for a supported subset**: `volaro check`, `volaro build`,
+`volaro dev`.
 
-## Use the reference
+The command is **`volaro`** (canonical). **`vl` is a compatibility alias** for
+the same binary. Run it via your project's `npm run …` scripts or
+`npx --no-install volaro …` inside the project — a bare `npx volaro` / `npx vl`
+from elsewhere may resolve an unrelated package.
+
+## What you need
+
+- **Python 3.10+** — runs the compiler, which is bundled inside this package
+  (`compiler/`). `volaro` finds `python3` on your PATH; set `VOLARO_PYTHON` to
+  choose a different interpreter. A missing or too-old Python is reported with
+  the fix, not a stack trace.
+- **Node.js** — runs the `volaro` command and the dev server. The minimum
+  depends on what you build:
+
+  | App shape | Node | Verified in CI |
+  |---|---|---|
+  | Minimal single-page (view only): `check` / `build` / static `dev` | **≥ 18** | 18, 20, 22, 24 (packaging matrix) |
+  | Full-stack: a `service` backed by a `model` → generated `server.js` (`node:sqlite`) | **≥ 22.5** | 22, 24 (packaging matrix, full-stack `dev`) |
+  | Password-auth: the generated server's built-in Argon2 | **≥ 24.7** | 24 only (`./verify.sh` browser journey) |
+
+  A green packaging matrix establishes the minimal-app row across 18–24; it
+  does **not** by itself establish the full-stack or auth rows on 18/20.
+
+### Operating systems
+
+| OS | Status |
+|---|---|
+| **Linux** | **Verified** — CI (`verify` + `packaging` matrix) and an isolated-install test |
+| **macOS** | **Unverified** — never run. No known blocker, but no evidence. |
+| **Windows** | **Unverified** — the `npm.cmd` / `PYTHONPATH` handling is present but untested; the packaging test scripts are `bash`. |
+
+Do not treat this as cross-platform support. Only Linux has been tested.
+
+No global install, no repository checkout, and no network access are needed
+once the package is installed.
+
+## Commands
+
+```bash
+volaro check <path>...   # validate .vl source (full resolver), exit non-zero on error
+volaro build app.vl      # transpile to ./build (index.html + app.js + runtime)
+volaro build app.vl -o dist --release
+volaro dev               # build ./app.vl, serve http://127.0.0.1:5173, rebuild on change
+volaro crib              # the authoring reference (write from this)
+volaro supported         # what THIS version accepts (the shipped-feature guide)
+volaro spec              # the full language design (a superset of this build)
+volaro example sensors   # a worked example (also: station)
+volaro version | volaro help
+```
+
+`volaro dev` serves a static bundle for a single-page app. If the app compiles
+to a full-stack server (`server.js`), it runs that instead and needs
+Node 22.5+ for `node:sqlite`.
+
+## Scaffold a project
 
 ```bash
-npx volaro crib
-npx volaro spec
-npx volaro example sensors
-npx volaro example station
+npm create volaro@alpha my-app      # the separate create-volaro package
 ```
 
-The CLI command is `vl`. The crib is approximately 2.8k o200k_base tokens.
+(`@alpha` matters — `npm create volaro` with no tag resolves `latest`, which
+is still an earlier `0.0.x` placeholder, not this build.)
+
+It writes one single-page starter, a `volaro.json`, and `package.json` scripts
+(`dev` / `build` / `check`) that call `volaro`.
 
 ## Scope and evidence
 
-The project-authored twelve-feature corpus records roughly 3.00× source density
-against selected baselines. This is not a general productivity result.
+The project-authored twelve-feature corpus records roughly 3.00× source
+density against selected baselines — not a general productivity result.
 Security and accessibility checks cover a tested prototype subset, not a
-universal guarantee. Independent human-readability validation remains outstanding.
+universal guarantee. Independent human-readability validation is outstanding.
 
-## Not included
+**MVP scope is single-page.** Routing, nested layouts and multi-page starters
+are later work; `volaro build` / `volaro dev` target one entry file.
 
-`vl new`, `vl check`, `vl build` and `vl dev` are not provided by this package.
-The repository has a working compiler for a supported subset, but distributing
-that toolchain is separate work. Styling and project creation are not supplied
-by this reference CLI.
+## Not included
 
-`npm create volaro` currently runs a separate placeholder package: it prints
-a status message and does not create an application.
+Migrations, deployable production output, a specified stdlib surface, and
+escape hatches to npm packages (email, payments, storage) are not here. Styled
+builds (`theme` / `recipe`) additionally need a one-time
+`npm ci` inside `compiler/vlbuild/styling`; the single-page starter does not
+use them.
 
-The legacy `volara` npm package is unchanged by this release.
+**Form controls:** the element set is `text` inputs plus `button` / `link` —
+there is no `checkbox`, `radio`, `select`, `textarea`, or `disabled` attribute.
+Model a toggle as a `button` reading a `state` bool. `variant:` is a literal
+style name, not a computed expression. `if` used as an expression is binary
+(`if c a else b`); `match` and block `if` are statements only. A module-level
+`fn` is not available to a view. **`volaro supported` and `volaro crib` are
+authoritative** for what this build accepts — `volaro spec` describes the
+wider language design, not this subset.
 
 ## Local testing
 
-Run `node bin/vl.js crib` from this package directory, or use `npm pack` and
-install the tarball into a temporary project. No global installation is required.
+```bash
+npm pack                       # runs prepack -> vendors compiler/ -> volaro-*.tgz
+npm test                       # scripts/selftest.mjs: check + build in a temp dir
+```
+
+The legacy `volara` npm package is unrelated to this release.
 
 ## License
 
 MIT
+
+
+## Local assets
+
+Put public files in `assets/` beside your entry `.vl` file and use
+`img src:"assets/logo.svg" alt:"Logo"`. Build and dev copy them to the browser
+bundle. Dev watches changes; refresh the browser after a rebuild. Missing
+literal asset references fail the build. Output `assets/` is compiler-owned.
+
+## Package provenance
+
+`compiler/SOURCE_REV` records the source commit. `compiler/SOURCE_INFO.json`
+adds its origin, Git dirty status where available, and a SHA-256 digest of
+compiler and CLI/documentation content. A package version alone does not
+identify a local candidate; preserve the tarball hash as well.
+
+Packaging a Git export uses `.volaro-source-rev`, expanded by `git archive`.
+For other exported source, set `VOLARO_SOURCE_REV` to the full source commit
+hash before `npm pack`. Missing/invalid revisions fail packaging; an explicit
+revision cannot override a different checkout HEAD. Export metadata identifies
+the base revision, not an assurance that someone has not modified the export;
+the content hash distinguishes modified candidates. Nothing is published by packing.

package/bin/vl.js

@@ -1,34 +1,472 @@
 #!/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 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 { 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",
+  };
+  return { cmd: py.cmd, argv: ["-B", "-m", moduleName, ...moduleArgs], env };
+}
+
+// Run a Python module, streaming its output, and exit with its status.
+function runPython(pp, moduleName, moduleArgs) {
+  const { cmd, argv, env } = pyInvocation(pp, moduleName, moduleArgs);
+  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));
+}
+
+function pyCapture(pp, moduleName, moduleArgs) {
+  const { cmd, argv, env } = pyInvocation(pp, moduleName, moduleArgs);
+  return spawnSync(cmd, argv, { encoding: "utf8", env });
+}
+
+// ---- subcommands -----------------------------------------------------------
+
+function cmdCheck(args) {
+  if (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", ...args]);
+}
+
+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 b = parseBuildArgs(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);
+}
+
+// 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");
+  const watchDir = 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");
+}
+
+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.
+  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:)
+  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)
+  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); text \`input\` / \`button\` / \`link\`
+only (no checkbox/select/textarea/disabled — a toggle is a \`button\` + \`state\`,
+not a semantic checkbox); \`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 "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);
 }

package/compiler/SOURCE_INFO.json

@@ -0,0 +1,6 @@
+{
+  "revision": "a450e6fe6549b8c7df43ba343793ab2e52758a78",
+  "source": "git",
+  "dirty": false,
+  "content_sha256": "095f3d5b55826d6aa0c560ce5570c91752d8f03cbd0e869ce61df1fcf53e2593"
+}

package/compiler/SOURCE_REV

@@ -0,0 +1 @@
+a450e6fe6549b8c7df43ba343793ab2e52758a78