cybertrain 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7660171ff57ac0e3f625dbffdef0a5a81de709bb80d2bcaf4e2b55be40034c24
-  data.tar.gz: 467b4243e1b26cfa42b64e276f6f859d01c1c7f9bd96df015e1222b66b31dd5d
+  metadata.gz: '0800072e567ad58afad9d1e6531aeff2aa0e82d8d9c69f2091fb6d3f5e0a5d61'
+  data.tar.gz: 9e93d0e6dc888ad648ab6acef7d78f52822b72f11aa7435dfd4aeae601334e8a
 SHA512:
-  metadata.gz: f56d35ff51a73b15c54376c145197847760d0238cf6599c68559d1c82c84f27998d65b0e53fd594ed7951f7d1b9d75ed3da7895571b4746e3ccb3b58e11bb7d1
-  data.tar.gz: 49a0e1927cd913289307e6684065bf157a1c04c22a585bad2e38cd2826f523cf480aa8a2cea19cd2437fb21dd249dd21a4a3ad97e6c43e231a580f166c202aa6
+  metadata.gz: 6df2e10e9e78787c2328aa2d96116d44bf437a3de08bd312b513129f8321043503df2fae5afc1b8b14e332e0c44d7990765d846e7bdfd04a8f503490f0066a3a
+  data.tar.gz: eb2b9396571a00406590c504e96c330937570609f0d8d860885f9cf739ab13e6c90a4859d5266d77f847fc2a7ac25078779721046237da3400e0ecde8a24e6e6

data/README.md

@@ -1,3 +1,15 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="site/assets/brand/lockup-stacked-dark.svg">
+    <img alt="CyberTrain" src="site/assets/brand/lockup-stacked-light.svg" width="360">
+  </picture>
+</p>
+<p align="center">
+  <a href="https://saeki-mototsune.github.io/CyberTrain/">Homepage</a> ·
+  <a href="https://saeki-mototsune.github.io/CyberTrain/tutorial.html">Tutorial</a> ·
+  <a href="https://saeki-mototsune.github.io/CyberTrain/api/">API reference</a>
+</p>
+
 # cybertrain
 
 cybertrain is a Rails-shaped web application framework written natively for
@@ -23,30 +35,74 @@ authentication, mailers, jobs, WebSockets/ActionCable, an asset pipeline,
 i18n, and anything beyond a minimal `render json:` — see "Differences from
 Rails" below.
 
+## Try it in the browser
+
+[Open the playground in GitHub Codespaces](https://codespaces.new/saeki-mototsune/CyberTrain?quickstart=1)
+to try cybertrain without installing anything: VS Code opens in your browser with
+Spinel 2026.09.12, the `cybertrain` CLI and the blog from the walkthrough below
+already created (`cybertrain new blog`, the article scaffold, the root route and
+the first migration, built once so the server starts without compiling), its
+development server running in a terminal and the app, showing the article list,
+in the editor's preview. The app is a git repository with one commit, so Source
+Control shows what you change. `PLAYGROUND.md` in the app lists what to try, from
+editing a view to carrying on with the walkthrough's comments. A view edit shows
+on the next reload; a Ruby edit is a full rebuild, about a minute, after which the
+server restarts by itself; the preview does not reload by itself. `cybertrain new`
+works there with no network.
+
+- A GitHub account is required, and the codespace runs on your own Codespaces
+  quota: GitHub's free plan includes 120 core-hours and 15 GB-month of storage a
+  month, about 60 hours on the default 2-core machine the playground uses. GitHub
+  stops an idle codespace after 30 minutes by default; its storage counts until
+  you delete it.
+- Inside the preview, pop-ups and `confirm()` dialogs do not work; the Ports
+  view's "Open in Browser" shows the app in a normal tab.
+- The same image runs locally (it is published for linux/amd64; on arm64, build
+  it from a checkout):
+
+  ```sh
+  docker run --rm -it --init -p 127.0.0.1:3000:3000 -e CYBERTRAIN_HOST=0.0.0.0 ghcr.io/saeki-mototsune/cybertrain-playground
+  ```
+
+  Then open http://localhost:3000. [playground/README.md](playground/README.md)
+  describes the image, building it and the Codespaces setup.
+
 ## Requirements
 
-- Spinel `2026.09.12`, with `spinel` and `spin` on `PATH` (see `SPINEL_TAG`
-  in [.github/workflows/ci.yml](.github/workflows/ci.yml)); untested against
-  other versions.
-- A C toolchain (`cc`) — Spinel compiles every program to C.
-- Ruby 3.2+ and RubyGems, for the `cybertrain` command only (applications
-  never run on CRuby).
+- Spinel `2026.09.12` (`Cybertrain::SPINEL_TAG`, the same release as
+  `SPINEL_TAG` in [.github/workflows/ci.yml](.github/workflows/ci.yml));
+  untested against other versions. You do not install it by hand: the
+  `cybertrain` command builds that release into `~/.cybertrain` the first
+  time it needs it (`cybertrain setup` does that on request), unless a
+  `spinel` of that release is already on `PATH` — see "Installing the CLI".
+- To build it: a C toolchain (`cc`, or the compiler `CC` names) and `make`
+  — Spinel compiles every program to C — plus `git` and `curl`.
 - SQLite 3 headers/library (`libsqlite3-dev` on Debian/Ubuntu; present with
   Xcode's command line tools on macOS) — models use Spinel's FFI directly,
-  not a gem. Building Spinel itself also needs OpenSSL's headers
-  (`libssl-dev`); cybertrain itself does not link OpenSSL.
+  not a gem.
+- Ruby 3.2+ and RubyGems, for the `cybertrain` command only (applications
+  never run on CRuby).
+- OpenSSL's headers (`libssl-dev`) are optional: without them Spinel builds
+  without its `openssl` package, which cybertrain does not use.
+
+`cybertrain doctor` checks these tools and headers and the Spinel install;
+when a required one is missing it also prints the install command for your
+platform.
 
-The framework has no separate test runner; it tests itself:
+The framework has no separate test runner; it tests itself. `spin` comes
+with Spinel, and `cybertrain spin` runs the copy `cybertrain` installs
+without touching `PATH` (or put that copy on `PATH` with the `export
+PATH=...` line `cybertrain setup` prints, and call `spin` directly):
 
 ```sh
-spin test
+cybertrain spin test
 ```
 
 compiles and runs every program under `test/` and diffs its output against a
 committed `test/<name>.rb.expected` snapshot — minitest/RSpec can't run under
 Spinel, since they find test methods by reflection and an ahead-of-time
-compiler has nothing to reflect on at run time. `spin test --regen
-test/<name>.rb` rewrites a snapshot from CRuby's output; a few tests that
+compiler has nothing to reflect on at run time. `cybertrain spin test
+--regen test/<name>.rb` rewrites a snapshot from CRuby's output; a few tests that
 touch SQLite through FFI take theirs from the compiled binary instead
 ([spikes/NOTES.md](spikes/NOTES.md), rule 23); `script/regen-snapshot
 test/<name>.rb` does that build-then-capture step for you and prints the diff stat.
@@ -55,38 +111,93 @@ test/<name>.rb` does that build-then-capture step for you and prints the diff st
 
 ```sh
 gem install cybertrain
+cybertrain new blog    # also installs Spinel, the first time (a few minutes)
+cd blog
+cybertrain g scaffold article title:string body:text
+cybertrain db migrate
+cybertrain server      # http://127.0.0.1:3000
+cybertrain build       # production: dist/
 ```
 
 The `cybertrain` command is plain Ruby and the gem runs it under CRuby
-(3.2 or newer); the framework itself is not in the gem. Its commands
-(`cybertrain help` prints them):
+(3.2 or newer); neither the framework nor Spinel is in the gem. Its
+commands (`cybertrain help` prints them):
 
-- `cybertrain new NAME` creates an application in NAME, then runs `spin
-  lock` and `spin run gen` in it.
+- `cybertrain new NAME [--path DIR | --version V | --git URL [--ref R]]
+  [--skip-spin]` creates an application in NAME, then runs `spin lock` and
+  `spin run gen` in it, installing Spinel first when it is needed.
 - `cybertrain generate scaffold NAME field:type ...` (alias `g scaffold`)
   adds a resource to the application in the current directory.
-- `cybertrain migration` generates, applies pending migrations, and
-  generates again (`spin run gen; spin run db -- migrate; spin run gen`).
-- `cybertrain db COMMAND...` runs any database command: `status`,
-  `rollback [N]`, `schema:dump`, `create`.
+- `cybertrain db migrate` generates, applies pending migrations, and
+  generates again (`spin run gen; spin run db -- migrate; spin run gen`);
+  `cybertrain migration` is kept as an alias.
+- `cybertrain db COMMAND...` runs any other database command after `spin
+  run gen`: `status`, `rollback [N]` (which generates again afterwards),
+  `schema:dump`, `create`.
 - `cybertrain server [PORT]` generates, then starts the development server
   (`spin run gen; spin run NAME`, or `spin run NAME -- PORT`; default port
   3000).
 - `cybertrain build` builds NAME with `app/views/` embedded and assembles
   `dist/` (the binary, `public/`, `storage/`, `tmp/`).
+- `cybertrain spin ARGS...` runs `spin` with the pinned Spinel from any
+  directory (`cybertrain spin test`, `cybertrain spin run gen -- --check`).
+- `cybertrain setup [--force]` installs Spinel `2026.09.12` into
+  `~/.cybertrain` unless a `spinel` of that release is already on `PATH`;
+  `--force` rebuilds the copy under `~/.cybertrain`.
+- `cybertrain doctor` checks the C toolchain, the SQLite headers and the
+  Spinel install.
+- `cybertrain version` prints the version.
+
+`db`, `server` and `build` run inside an application; NAME is the
+`[package] name` in its `spin.toml`.
+
+Every command that runs `spin` (`new`, `db`, `server`, `build`, `spin`) first makes
+sure a Spinel of the release in `Cybertrain::SPINEL_TAG` is available. A
+`spinel` on `PATH` (with a `spin`) whose `spinel --version` reports that
+release is used as it is; otherwise the copy `cybertrain` keeps under
+`~/.cybertrain/spinel/2026.09.12/` is used; otherwise `cybertrain` builds
+that copy from the release tag (`git clone`, `make deps`, `make -j`, `make
+install PREFIX=...`), once, in a few minutes. The build log is
+`~/.cybertrain/log/spinel-2026.09.12-build.log` (its last lines are printed
+if a step fails); if a tool the build needs is missing, `cybertrain` says
+which and prints the install command for your platform before it starts. A
+`spinel` of another release on `PATH` is never used or touched:
+`cybertrain` keeps its own copy (and says so when it installs it).
+
+`cybertrain setup` does the same on request and, whenever its own copy is
+the one in use, prints the line that puts it on `PATH`, for running `spin`
+yourself (`~/.cybertrain/bin` holds `spinel` and `spin` links to the release
+in use, so the line survives a release bump; `cybertrain spin ...` needs no
+`PATH` at all):
 
-`migration`, `db`, `server` and `build` run inside an application; NAME is
-the `[package] name` in its `spin.toml`.
+```sh
+export PATH="$HOME/.cybertrain/bin:$PATH"
+```
 
-`cybertrain new` points the app's `spin.toml` at the release matching the
-CLI — `cybertrain = { git = "https://github.com/saeki-mototsune/cybertrain",
-ref = "v0.1.1" }` — then runs `spin lock` (spin fetches the framework into
-its cache, `~/.cache/spin/packages/`, and pins the commit in `spin.lock`)
-and `spin run gen`, much as `rails new` runs `bundle install`. Nothing of
-the framework is copied into the app; commit `spin.toml` and `spin.lock`.
-`--skip-spin` leaves both steps for later, `--path DIR` depends on a local
-checkout instead, and `--version V` on an index version once cybertrain is
-on a `spin-index`.
+Two environment variables override all this: `CYBERTRAIN_HOME` replaces
+`~/.cybertrain` (a path without spaces, quotes, `$` or `:`, which Spinel's
+Makefile and `PATH` cannot take), and `CYBERTRAIN_SPINEL_HOME=PREFIX` forces
+an existing install — `cybertrain` then uses the `spinel` and `spin` in `PREFIX/bin` (or
+in `PREFIX` itself, if `spinel` is directly in it) and stops with an error
+if they are not that release.
+
+`cybertrain new` writes the application with its `spin.toml` pointing at
+the release matching the CLI (`cybertrain = { git =
+"https://github.com/saeki-mototsune/cybertrain", ref = "v0.2.1" }`), makes
+sure Spinel is installed, then runs `spin lock` (spin fetches the framework
+into its cache, `~/.cache/spin/packages/`, and pins the commit in
+`spin.lock`) and `spin run gen`, much as `rails new` runs `bundle install`,
+and prints the next steps. Nothing of the framework is copied into the app;
+commit `spin.toml` and `spin.lock`. If Spinel or one of the two `spin`
+steps fails, the files stay, `new` exits with 1 and prints what to run once
+the cause is fixed (for Spinel: `cybertrain setup`, then `cybertrain spin
+lock && cybertrain spin run gen` in the new directory).
+
+`--skip-spin` only writes the files: no Spinel install, no `spin lock`, no
+`spin run gen`. `--path DIR` depends on a local checkout instead,
+`--git URL [--ref R]` on the framework at URL (at branch or tag R), and
+`--version V` on an index version once cybertrain is on a `spin-index`.
+Give only one of `--path`, `--version` and `--git`; `--ref` needs `--git`.
 
 Working on cybertrain itself, run the CLI from the checkout (`spin install`
 builds `bin/cybertrain.rb` into `~/.local/bin/cybertrain`; `ruby -I.
@@ -119,14 +230,15 @@ blog/
 `bin/blog.rb` is the application's one entry point, the program `spin build
 blog` compiles: `./blog` serves, `./blog migrate` and `./blog db status`
 manage the database. `bin/gen.rb` runs the generator (`spin run gen`), and
-`bin/db.rb` runs the migrator during development (`cybertrain migration`
+`bin/db.rb` runs the migrator during development (`cybertrain db migrate`
 uses it, since `bin/blog.rb` cannot compile until the first migration has
 generated `gen/models/`). `gen/` already holds `views.rb`, the committed,
 empty table of embedded views (see "How it works").
 
 Apps created before `cybertrain build` existed have `bin/server.rb` and
 no `bin/<name>.rb`: copy `bin/<name>.rb` from a fresh `cybertrain new` (with
-the same NAME), delete `bin/server.rb` and run `spin run gen`.
+the same NAME), delete `bin/server.rb`, add `/dist/` to `.gitignore` (the old
+template did not ignore it) and run `cybertrain spin run gen`.
 
 `ApplicationController` starts with the one thing every controller inherits:
 
@@ -210,7 +322,7 @@ end
 ### Generate, migrate, run
 
 ```sh
-cybertrain migration     # spin run gen; spin run db -- migrate; spin run gen
+cybertrain db migrate    # spin run gen; spin run db -- migrate; spin run gen
 cybertrain server        # http://127.0.0.1:3000; rebuilds on Ruby edits, views reload without a rebuild
 ```
 
@@ -218,14 +330,15 @@ cybertrain server        # http://127.0.0.1:3000; rebuilds on Ruby edits, views
 writes `gen/`; `spin run db -- migrate` applies `db/migrate/*.rb` and
 rewrites `db/schema.rb`.
 
-Re-run `spin run gen` (and commit `gen/`) after touching the schema, routes,
-or a controller/model's callbacks and ivars — the dev server does this for
+Re-run `cybertrain spin run gen` (and commit `gen/`) after touching the
+schema, routes, or a controller/model's callbacks and ivars — the dev server does this for
 you automatically (see "How it works").
 
 ### Add comments, nested under articles
 
 ```sh
 cybertrain generate scaffold comment commenter:string body:text article:references
+cybertrain db migrate    # the scaffold wrote a migration for the comments table
 ```
 
 `article:references` adds an `article_id` column, index and foreign key —
@@ -352,8 +465,8 @@ merge.
 **Views are interpreted, not compiled.** `app/views/**/*.html.erb` files look
 like Rails ERB but are parsed into an AST at request time, then walked by a
 tree-walking interpreter. Where the source comes from depends on the mode:
-in development (and test) the engine reads `app/views/` from disk and
-re-parses a template when it changes, so view edits need no rebuild.
+in development (and test) the engine reads `app/views/` from disk, and in
+development re-parses a template when it changes, so view edits need no rebuild.
 `cybertrain build` runs `spin run gen -- --embed-views`, which writes every
 template's source into `gen/views.rb` as a string table for that one `spin
 build`, then runs `spin run gen` again to restore the empty table that is
@@ -381,9 +494,10 @@ adapter today (PostgreSQL via `libpq` FFI is noted as possible future work).
 `cybertrain build`) also polls `app/**/*.rb`, `config/**/*.rb`, `db/schema.rb`
 and `gen/**/*.rb` every half second (views are excluded — the engine reloads
 those itself — and so is `gen/views.rb`, empty in development). A change runs `spin run gen && spin build NAME` in the
-background; success sends the server `SIGHUP`, whose handler stops listening
-and `execv`s the new binary on the same port and PID, invisible to a client
-mid-session. A failed build keeps serving the old binary and banners the
+background; success requests a restart (the same flag an external `kill -HUP`
+sets): a monitor thread stops the listener and drains open requests, then the
+main thread `execv`s the new binary on the same port and PID, invisible to a
+client mid-session. A failed build keeps serving the old binary and banners the
 compiler output on every HTML response. None of this loads in production.
 
 ## Differences from Rails
@@ -391,7 +505,7 @@ compiler output on every HTML response. None of this loads in production.
 | Rails | cybertrain |
 | --- | --- |
 | `rails console` | No console — Spinel has no `eval` |
-| Edit code, the running app picks it up | Ruby needs a rebuild; `cybertrain server` in development does this for you (rebuild, `SIGHUP`, `execv`) |
+| Edit code, the running app picks it up | Ruby needs a rebuild; `cybertrain server` in development does this for you (rebuild, stop, `execv`) |
 | Edit a view, no reload needed | Same — views are parsed from disk per request in development |
 | `def new` | `def new_action` (`new` would shadow `Klass.new(ctx)`) |
 | `before_action { do_thing }` (implicit `self`) | `before_action { \|c\| c.do_thing }` — no `instance_exec` on a stored block, so callbacks take the controller/record explicitly |
@@ -400,7 +514,10 @@ compiler output on every HTML response. None of this loads in production.
 | Session holds any marshalled object | Session values are Strings only, HMAC-signed cookie |
 | Many database adapters | SQLite only, via FFI |
 | `has_many :through`, `includes`, `pluck`, `dependent:`, enums, STI, polymorphic associations | Not implemented; associations come from schema foreign keys only |
+| Any column name; an association can shadow `errors` | A column name must be an ASCII identifier (`[A-Za-z_][A-Za-z0-9_]*`): a schema with a non-ASCII column name (`名前`, `prénom`) generated under CRuby before PR #10 and `spin run gen` refuses it now, so rename the column when upgrading (a name like `first-name` was never a method name). A column named like a method the generated class or the framework calls on a record (`errors`, `save`, `attributes`, `hash`, `to_s`, `to_ary`, `raise`, ...) or like a Ruby keyword (`end`, `class`, `begin`) generates under `<column>_column` (`hash_column`, reader, writer and ivar) with a note in the generated file; its SQL name keeps working in `read_attribute`, params and `attributes["hash"]`, and a template reaches it under either name (`post.hash`, `post.hash_column`), except `errors` and `to_param`, which a template resolves as the model methods, so use `post.errors_column` there; the query API (`where`, `order`, `find_by`) always takes the SQL column name (`Post.where(hash: 1)`), the Ruby name being the reader/writer and the template name only. A column named like another Object method (`display`, `tap`, `methods`) generates under its own name with a note. `cybertrain generate scaffold` refuses keywords and reserved names (it would have to call a renamed reader) and accepts a shadowing name with a note, like the generator. An association whose plain name a column, another association or a `Model` method already owns is emitted under a fallback name with a comment in the generated file: `<table>_as_<column stem>` for a `has_many` (`comments_as_article`), `<stem>_as_<column>` for a `belongs_to` (`author_as_author_id`) |
 | `namespace`, format/`respond_to`, `constraints`, `mount` | Not implemented — flat names, `render json:` only |
+| `rescue StandardError` catches a bad `JSON.parse` | Under Spinel `JSON::ParserError` is not a `StandardError`: app code must `rescue JSON::ParserError, StandardError`. The server catches it as a last resort and answers 500 |
+| `order("lower(title)")`, `order("posts.title")`, `order(params[:sort])` | `order` takes only `column [ASC\|DESC]` lists (each column quoted) and raises `ArgumentError` (a 500: the string is the developer's) on anything else; request data must go through an allowlist first, e.g. `SORTS = { "title" => "title", "newest" => "created_at DESC" }` and `Post.order(SORTS.fetch(params[:sort].to_s, "id"))`, because a well-formed term can still name a missing column (a 500 from SQLite) or a column the client must not sort by; raw ORDER BY text goes through `order_sql` (`Post.order_sql("lower(title)")`, also on a relation), which must never see request data. A `limit`/`offset` on `delete_all` is honoured (a subselect), and request parameters nest at most 32 levels / 4096 pairs (400 past that). `Query.parse`, `Query.value_of`, `Query.decode` and `request.form_value` / `query_value` raise `Cybertrain::QueryMalformed` (a `StandardError` under `Cybertrain::QueryInvalid`, not an `ArgumentError`) on a malformed percent-escape, on both runtimes (`Cookies.parse` still keeps the raw value). They raise it too on an invalid UTF-8 byte sequence, raw (whatever the String's tag) or percent-encoded (Rails likewise answers 400 for an invalid parameter encoding), and so does a raw byte that only an escape would complete (`a=\xC3%A9`); `Cookies.parse` keeps such a value raw, and a path with an invalid sequence (raw, or percent-decoded in a segment) is a 400 as well (`request.path_segments`; a malformed escape in a path stays literal, a 404 by non-match). App code that rescued `ArgumentError` around them should rescue `Cybertrain::QueryInvalid` instead (upgrade note). The request keeps no parameter tree of its own (the Router builds `params`, the middleware read one key); an app that wants the whole tree parses it itself, `Query.parse(request.utf8_query_string)`, and owns the result |
 | Full backtrace on an exception | Class, message, request line, template name/line — Spinel exposes no backtraces |
 | Rack, its middleware, and any gem in a `Gemfile` | No Rack compatibility; a small fixed middleware set; Spinel's own `spin-index`, limited to what compiles under its Ruby subset |
 | minitest / RSpec | `Cybertrain::Test` — reflection-based runners can't work ahead-of-time |
@@ -427,13 +544,27 @@ end
 | `CYBERTRAIN_DATABASE` | `database_path` | `storage/#{env}.sqlite3` |
 | `CYBERTRAIN_SECRET_KEY_BASE` | `secret_key_base` | required in production; dev/test auto-generate one into `tmp/secret_key` |
 | `SPINEL_WORKERS` | `workers` | `1` |
+| `CYBERTRAIN_HOST` | `host` | `"127.0.0.1"`; `0.0.0.0` listens on every interface (containers) |
+| `CYBERTRAIN_SESSION_SAME_SITE` | `session_same_site` | `"Lax"`; also `Strict` or `None` (`None` always adds `Secure`); anything else stops the server at boot |
+| `CYBERTRAIN_SESSION_PARTITIONED` | `session_partitioned` | `false`; `1` or `true` adds `Partitioned` (and `Secure`) |
 
-Other attributes with fixed, overridable defaults: `host` (`"127.0.0.1"`),
-`views_root` (`"app/views"`), `public_root` (`"public"`), `layout`
+Use `None` (with `CYBERTRAIN_SESSION_PARTITIONED=1`) only for an app shown
+inside another site's frame, such as the playground's Codespaces preview; the
+browser must reach the app over HTTPS.
+
+Other attributes with fixed, overridable defaults: `views_root`
+(`"app/views"`), `public_root` (`"public"`), `layout`
 (`"layouts/application"`), `log_level` (`:info`), `session_cookie_name`,
 `session_max_age` (2 weeks), `session_secure` (`true` in production, which
-marks the session cookie `Secure`; `false` elsewhere), `pool_size` (4),
-`static_files`/`csrf` (`true`).
+marks the session cookie `Secure`; `false` elsewhere, though `SameSite=None`
+and `Partitioned` add `Secure` anyway), `pool_size` (4), `static_files`/`csrf`
+(`true`), `max_render_depth` (12 renders open at once: the page and its
+partials; raise it for partials that legitimately recurse deeper; it must be
+at least 1, or boot fails). Upgrade note: render nesting, unlimited before, is
+now capped at 12 by default (the page is depth 1, so partials can nest 11
+levels; the layout renders after the page and does not nest), and an app with
+a deeper tree (threaded comments, a category menu) gets a template error until
+it sets `max_render_depth`.
 
 **Deployment:** `cybertrain build` produces `dist/`: the binary `dist/NAME`
 with the views embedded, `dist/public/` (static assets, or let a reverse
@@ -458,7 +589,7 @@ systemd, Caddy with HTTPS, redeploys, rollbacks and backups.
 App tests are plain Spinel programs under `test/`, like the framework's own:
 
 ```ruby
-require "cybertrain/test"
+require_relative "support/blog_test"   # the app, BLOG and Cybertrain::Test
 
 test "title must be present" do
   article = Article.new(body: "a body long enough to pass length")
@@ -473,29 +604,55 @@ full HTTP flows, `Cybertrain::Test::Client` drives an app in-process (no
 socket) with a cookie jar, so sessions and CSRF behave as behind a browser:
 
 ```ruby
-require "cybertrain/test/client"
-
-client = Cybertrain::Test::Client.new(BLOG)
-client.get("/articles/new")
-res = client.post("/articles", "article[title]" => "Hello",
-                                "article[body]" => "I am on Rails!",
-                                "authenticity_token" => token)  # from the rendered form
-assert_redirected_to res, "/articles/1"
-assert_response res, :see_other
+require_relative "support/blog_test"   # the app, BLOG and Cybertrain::Test
+
+test "POST /articles creates an article and redirects to it" do
+  client = Cybertrain::Test::Client.new(BLOG)
+  client.get("/articles/new")
+  res = client.post("/articles", { "authenticity_token" => BlogTest.form_token(client),
+                                   "article[title]" => "Hello Rails",
+                                   "article[body]" => "I am on Rails! This is my first article." })
+  assert_redirected_to res, BlogTest.article_path(Article.last)
+  assert_response res, :see_other
+end
 ```
 
-`examples/blog/test/articles.rb`/`comments.rb` (setup in
-`test/support/blog_test.rb`) show the full pattern, including token
-extraction, against a freshly migrated `storage/test.sqlite3`.
-
-Run with `spin test`: it compiles each `test/*.rb` into its own program and
-diffs stdout against `test/<name>.rb.expected`. Regenerate with `spin test
---regen test/<name>.rb`; FFI/database tests can't run under CRuby, so their
-snapshot comes from the compiled binary instead: `spin test test/<name>.rb &&
-./build/test/<name> > test/<name>.rb.expected`.
+Both snippets start from the example's helper,
+[`examples/blog/test/support/blog_test.rb`](examples/blog/test/support/blog_test.rb):
+copy it into an app's `test/support/`, where files are required, not run.
+It migrates a fresh `storage/test.sqlite3`, boots the app as `BLOG`, loads
+`Cybertrain::Test` and its client, and reads the CSRF token out of the last
+rendered form (`BlogTest.form_token`). End each test file with
+`Cybertrain::Test.run!`; `examples/blog/test/articles.rb` and `comments.rb`
+show the full pattern.
+
+Run with `cybertrain spin test`: it compiles each `test/*.rb` into its own
+program and diffs its output (stdout and stderr together) against
+`test/<name>.rb.expected`. Regenerate with `cybertrain spin test --regen
+test/<name>.rb`; FFI/database tests can't run under CRuby, so their snapshot
+comes from the compiled binary instead: `rm -f build/test/<name>; cybertrain
+spin test test/<name>.rb; [ -x build/test/<name> ] && ./build/test/<name> >
+test/<name>.rb.expected 2>&1` (`cybertrain spin test` exits non-zero while the
+snapshot is stale, so it is followed by `;`, not `&&`; the `[ -x ]` check skips
+the capture when the compile failed, so the old snapshot is kept; in the
+framework checkout, `script/regen-snapshot test/<name>.rb` does exactly this and
+prints the diff stat).
 
 ## Learn more
 
+- [Homepage](https://saeki-mototsune.github.io/CyberTrain/),
+  [tutorial](https://saeki-mototsune.github.io/CyberTrain/tutorial.html) and
+  [playground](https://saeki-mototsune.github.io/CyberTrain/playground.html) —
+  the source lives in [site/](site/), published by
+  [.github/workflows/pages.yml](.github/workflows/pages.yml); the logo files and
+  brand notes are in [site/assets/brand/](site/assets/brand/BRAND.md).
+- [API reference](https://saeki-mototsune.github.io/CyberTrain/api/) — every
+  class and method an application uses (controllers, params, session and
+  flash, models and relations, routes, migrations, configuration, tests),
+  including what `spin run gen` generates. It is built by YARD
+  (`script/api-docs`, into `site/api/`) from the doc comments marked
+  `@api public` in `cybertrain/` and from [docs/api/](docs/api/); a method
+  without that tag is internal and stays out. CI fails on any YARD warning.
 - [docs/design.md](docs/design.md) — the design record (Japanese): every
   decision, what was rejected and why, and the Spinel constraints behind it.
 - [docs/template-language.md](docs/template-language.md) — the full template
@@ -516,8 +673,17 @@ before the gem is pushed:
 1. Bump `Cybertrain::VERSION` (`cybertrain/version.rb`) and `version` in
    `spin.toml` together (CI checks they match); spin caches a git
    dependency by that version.
-2. Merge to `main`, then tag and push: `git tag v0.1.1 && git push origin v0.1.1`.
-3. `gem build cybertrain.gemspec && gem push cybertrain-0.1.1.gem`.
+2. Merge to `main`, then tag and push: `git tag v0.2.1 && git push origin v0.2.1`.
+3. `gem build cybertrain.gemspec && gem push cybertrain-0.2.1.gem`.
+4. The tag also publishes the playground image
+   `ghcr.io/saeki-mototsune/cybertrain-playground:X.Y.Z` (and `latest`) through
+   [.github/workflows/playground-image.yml](.github/workflows/playground-image.yml);
+   check that run.
+
+`Cybertrain::SPINEL_TAG` (also in `cybertrain/version.rb`) is the Spinel
+release `cybertrain setup` installs. It must equal `SPINEL_TAG` in
+[.github/workflows/ci.yml](.github/workflows/ci.yml), which CI checks, so
+change the two together when the framework moves to another Spinel release.
 
 ## License
 

data/cybertrain/app_name.rb

@@ -0,0 +1,36 @@
+module Cybertrain
+  # The one definition of "a name usable as the application's package name":
+  # `cybertrain build`/`server` (CLI::Build.app_name, reading spin.toml) and
+  # the development rebuilder (Dev::Rebuilder.new, which shells out with the
+  # name Application.new(name:) was given) both ask here, so the rules
+  # cannot drift apart. Application.new itself does not: production never
+  # builds. A leaf file with no requires: the CLI (CRuby) and the framework
+  # (Spinel) both load it. String methods only, no Regexp, because it
+  # compiles under Spinel (see Dev::Rebuilder).
+  module AppName
+    # "" when name works as a `spin build` target and as the build/bin/<name>
+    # path, else the reason (a String on every path, NOTES rules 10/34).
+    # Shell safety is not this method's job: both callers quote the name when
+    # they build a command ("my-app" and "MyApp" are fine for `spin build`),
+    # so only what breaks the target or the path is refused.
+    def self.problem(name)
+      # An empty name would become an explicit "" argument to spin.
+      return "cannot be empty" if name.empty?
+      # "." and ".." name build/bin/. and build/bin/.., which exist already
+      # (the latter is build/) and only fail later, in assemble's cp.
+      return "cannot be '.' or '..'" if name == "." || name == ".."
+      # Quoting leaves a leading "-" bare ("-" is in quote_arg's safe set),
+      # and even quoted `spin build '-x'` is parsed by spin as an option, not
+      # as the package name. Whether spin accepts `--` before the target is
+      # unverified, hence a refusal.
+      return "cannot start with '-' (spin would read it as an option)" if name.start_with?("-")
+      # A "/" would put the binary in a subdirectory of build/bin.
+      return "cannot contain '/'" if name.include?("/")
+      # Whitespace splits the target in the places that do not quote it, and
+      # a newline ends a command line.
+      return "cannot contain whitespace" if name.include?(" ") || name.include?("\t") || name.include?("\n") || name.include?("\r")
+
+      ""
+    end
+  end
+end