volaro 0.0.2 → 0.1.0-alpha.10

package/README.md

@@ -1,46 +1,199 @@
 # Volaro
 
-**Pre-release language reference CLI — compiler not included.**
+**Limited alpha** (this is `0.1.0-alpha.10`), published under both the
+`latest` and `alpha` dist-tags: `npm install volaro`.
 
 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
+```
+
+### Benchmark timing log
+
+`check` and `build` can append machine-readable compile attempts to a JSONL
+file. Use one unique run ID for the first attempt and every repair attempt in a
+single trial:
+
+```bash
+volaro check app.vl --benchmark-log benchmark.jsonl --benchmark-run test-006-v-01
+# If it fails, repair app.vl and repeat the exact command with the same run ID.
+```
+
+A first-pass success writes a `clean` summary with `t_clean_ms`. A failure
+followed by a success writes a `recovered` summary with `t_fail_ms`,
+`t_repair_ms`, `t_recompile_ms`, and `t_recover_ms`. The log also retains every
+raw attempt, the number of failures, and compiler overhead not attributable to
+repair. A completed run ID cannot be reused, and a run cannot mix `check` and
+`build` attempts or change compiler arguments between attempts.
+
+The timer measures the compiler subprocess. `T-repair` is the observed wall
+time between a failed compiler exit and the next compiler start. It measures
+the autonomous repair loop, including agent and tool overhead; it is not a
+claim about model-inference time alone.
+
+**Every failed attempt is classified, not just counted.** Each raw `attempt`
+record carries a `classification`: `source_diagnostic` (the compiler ran to
+completion and correctly reported a problem with your source — the only case
+`t_fail_ms` is ever populated for), `operational_failure` (the compiler process
+itself crashed, was killed, or stopped on an invocation/configuration problem —
+`crash_exception_type`/`crash_exception_message` are set when it was a crash),
+`silent_failure` (a non-zero exit with no output at all), or `unknown_failure`
+(a non-zero exit with output that carried none of the compiler's own
+diagnostic signal). This is reported by the compiler itself over a private
+side channel — never guessed from whether stdout/stderr happened to have
+anything in it, since an internal crash prints output too. A `recovered`
+summary whose original failing attempt was not `source_diagnostic` has
+`t_fail_ms: null`, `timing_complete: false`, and a `timing_incomplete_reason`
+explaining why — treat it as an invalid recovery-time sample, not a slow one.
+
+**A `recovered` summary can also be invalidated by the wall clock.**
+`t_repair_ms`/`t_recover_ms` are computed from separate processes' own
+timestamps; if one of those timestamps predates an earlier one (a system
+clock step between two attempts), the summary has `clock_anomaly: true`,
+`timing_complete: false`, and the affected fields are `null` — never a
+clamped, misleadingly small positive number.
+
+`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`. A multi-page project build always emits a
+`server.js` (it serves `public/` and answers a direct link or refresh on a
+dynamic route), so `volaro dev` on a project directory runs that server.
+
+## Scaffold a project
 
 ```bash
-npx volaro crib
-npx volaro spec
-npx volaro example sensors
-npx volaro example station
+npm create volaro my-app      # the separate create-volaro package
 ```
 
-The CLI command is `vl`. The crib is approximately 2.8k o200k_base tokens.
+(If `npm create volaro` prints "This release is a placeholder", npm is
+reusing a cached copy of the old `0.0.1`: run `npm cache clean --force`.)
+
+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
+**Pages, routing and nested layouts are implemented** (2026-09-23). A project
+directory with any `app/**/index.vl` builds as a real multi-page app: nested
+`_layout.vl` shells placing content with `@children`, `(group)` folders that add
+layout ancestry but no URL segment, typed `[name=type]` dynamic parameters, and
+optional `_loading.vl` / `_error.vl` / `_not-found.vl` boundaries, served by a
+client router with a direct-link/refresh fallback in the generated server. Point
+`volaro build` / `volaro dev` at the project directory; `volaro routes` prints
+what was discovered. A single `.vl` entry file still builds exactly as before.
 
-`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.
+**Still out of scope:** server-side rendering and hydration (the shell is
+route-agnostic and the client does the first render); `theme` / `recipe` styling
+in a multi-page build, so styled output is single-entry only; catch-all routes,
+per-file route prefixes, and inherited authorization. **`npm create volaro`
+scaffolds a single-page starter** — a multi-page starter is later work.
+
+## 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:** `input` (a full type matrix, including `checkbox`/`radio`
+binding a `checked` state), `textarea`, `select`/`option`/`optgroup`,
+`fieldset`/`legend`, `datalist`, `button`, `link`. `disabled:` works on
+`button input textarea select fieldset optgroup option`. A toggle is
+`button pressed:<bool>` (a toggle button, `aria-pressed`; there is no
+`switch` role). There is no standalone `label` element. `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.