cybertrain 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7660171ff57ac0e3f625dbffdef0a5a81de709bb80d2bcaf4e2b55be40034c24
-  data.tar.gz: 467b4243e1b26cfa42b64e276f6f859d01c1c7f9bd96df015e1222b66b31dd5d
+  metadata.gz: 2bfb12d19791bff7ce88504f9ffb5fe6e2d90ae7a55aa24f5571b1909cf11976
+  data.tar.gz: 0eaac7a028bbf9be6c013b716ecec76f02c91fb10aa04e855f7b777f250c8712
 SHA512:
-  metadata.gz: f56d35ff51a73b15c54376c145197847760d0238cf6599c68559d1c82c84f27998d65b0e53fd594ed7951f7d1b9d75ed3da7895571b4746e3ccb3b58e11bb7d1
-  data.tar.gz: 49a0e1927cd913289307e6684065bf157a1c04c22a585bad2e38cd2826f523cf480aa8a2cea19cd2437fb21dd249dd21a4a3ad97e6c43e231a580f166c202aa6
+  metadata.gz: 66bf793c97cf16d109519514b10c15d929e627137e58a4663d04ad3e88a746fa12e95b39358f15ebe8ba643107a2f8f30dbee54cbc9e95ea5127a4cc870fb417
+  data.tar.gz: 02bcced8e7ab059cb479b06835420eb241271b4447ed0e7d16c2801c6ed50b6b0d3587ff6557ae9b36501a5a108b05c2a4e7d5757caf7887c353ed41e4c2deb7

data/README.md

@@ -1,3 +1,14 @@
+<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>
+</p>
+
 # cybertrain
 
 cybertrain is a Rails-shaped web application framework written natively for
@@ -25,28 +36,40 @@ Rails" below.
 
 ## 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 +78,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.0" }`), 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 +197,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 +289,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 +297,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 +432,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 +461,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 +472,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 |
@@ -458,7 +539,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 +554,47 @@ 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/) and
+  [tutorial](https://saeki-mototsune.github.io/CyberTrain/tutorial.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).
 - [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 +615,13 @@ 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.0 && git push origin v0.2.0`.
+3. `gem build cybertrain.gemspec && gem push cybertrain-0.2.0.gem`.
+
+`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/cli/build.rb

@@ -1,5 +1,5 @@
 # `cybertrain build`: dist/ = the app binary with app/views embedded, plus
-# public/. Also the command lists `cybertrain migration` and `server` run. Plain Ruby:
+# public/. Also the command lists `cybertrain db` and `server` run. Plain Ruby:
 # runs under CRuby (the gem) and compiles under Spinel (spin install).
 module Cybertrain
   module CLI
@@ -29,10 +29,28 @@ module Cybertrain
         ["spin run gen -- --embed-views", "spin build #{name}", "spin run gen"]
       end
 
-      # Through bin/db.rb: the app binary cannot compile before the first
-      # migration has produced gen/models.
+      # `cybertrain db ARGS`, through bin/db.rb (the app binary cannot compile
+      # before the first migration has produced gen/models). bin/db.rb only
+      # knows the migrations gen/migrations.rb lists, so gen runs first;
+      # migrate and rollback rewrite db/schema.rb, which gen/models is
+      # derived from, so gen runs again after them.
+      def self.db_commands(args)
+        words = args.map { |arg| quote_arg(arg) }.join(" ")
+        commands = ["spin run gen", "spin run db -- #{words}"]
+        commands << "spin run gen" if args[0] == "migrate" || args[0] == "rollback"
+        commands
+      end
+
+      # `cybertrain migration`: the same as `cybertrain db migrate`.
       def self.migration_commands
-        ["spin run gen", "spin run db -- migrate", "spin run gen"]
+        db_commands(["migrate"])
+      end
+
+      # A word sh reads as itself stays bare; anything else is single-quoted.
+      def self.quote_arg(text)
+        return text if !text.empty? && text.match(/\A[A-Za-z0-9_:.\/-]+\z/)
+
+        shell_quote(text)
       end
 
       # port is "" (the app's default, 3000) or a port? string.

data/cybertrain/cli/new_app.rb

@@ -1,12 +1,12 @@
 # `cybertrain new blog`: writes the skeleton of an application package.
 require "cybertrain/generator/inflector"
 require "cybertrain/cli/templates"
+require "cybertrain/cli/build"
+require "cybertrain/cli/toolchain"
 
 module Cybertrain
   module CLI
     module NewApp
-      KEEP_DIRS = ["db/migrate", "app/models", "app/helpers", "gen", "storage", "tmp", "test"]
-
       # dir is the directory to create ("blog" or "path/to/blog"; its last
       # component names the package). framework_dep is the TOML value that
       # spin.toml's `cybertrain =` line gets: `{ path = "/abs/cybertrain" }` or
@@ -47,28 +47,33 @@ module Cybertrain
 
       # What `rails new` does with `bundle install`: resolve and lock the
       # framework (fetching it into spin's cache, ~/.cache/spin), then write
-      # gen/ so `spin build` works straight away. Without spin on PATH it
-      # only says what to run later. Returns false when a step failed.
+      # gen/ so `spin build` works straight away. Installs Spinel first when
+      # this machine has none of the pinned release (Toolchain.ensure!).
+      # Returns false when a step failed.
       def self.bootstrap(dir)
-        unless system("command -v spin > /dev/null 2>&1")
-          puts "skip spin lock / spin run gen: `spin` is not on PATH"
-          puts "  install Spinel (https://github.com/matz/spinel), then: #{bootstrap_command(dir)}"
-          return true
+        unless Toolchain.ensure!
+          puts "skip spin lock / spin run gen: Spinel #{Cybertrain::SPINEL_TAG} is not available"
+          puts "  fix the problem above (`cybertrain doctor` lists the checks), then: cybertrain setup && #{recovery_command(dir)}"
+          return false
         end
 
         puts "run    spin lock && spin run gen"
         return true if system(bootstrap_command(dir))
 
-        puts "error: bootstrapping #{dir} failed; fix the cause, then run: #{bootstrap_command(dir)}"
+        puts "error: bootstrapping #{dir} failed; fix the cause, then run: #{recovery_command(dir)}"
         false
       end
 
+      # Run by bootstrap once Toolchain.ensure! has put spin on this
+      # process's PATH.
       def self.bootstrap_command(dir)
-        "cd #{shell_quote(dir)} && spin lock && spin run gen"
+        "cd #{Build.shell_quote(dir)} && spin lock && spin run gen"
       end
 
-      def self.shell_quote(text)
-        "'#{text.gsub("'", "'\\\\''")}'"
+      # The same steps for the user to run by hand: through `cybertrain
+      # spin`, since the Spinel cybertrain installed is not on their PATH.
+      def self.recovery_command(dir)
+        "cd #{Build.shell_quote(dir)} && cybertrain spin lock && cybertrain spin run gen"
       end
     end
   end

data/cybertrain/cli/scaffold.rb

@@ -92,6 +92,13 @@ module Cybertrain
         @fields = fields
       end
 
+      # The index route helper's name without _path, as Rails' scaffold
+      # names it: the plural, or "<plural>_index" for a word that is its own
+      # plural (sheep_index_path), matching the routes DSL.
+      def index_helper
+        @plural == @singular ? "#{@plural}_index" : @plural
+      end
+
       # The column the model validates for presence ("" when there is none).
       def first_string_field
         @fields.each { |f| return f.field_name if f.field_type == "string" }

data/cybertrain/cli/templates.rb

@@ -92,17 +92,17 @@ module Cybertrain
 
           ```sh
           cybertrain generate scaffold post title:string body:text
-          cybertrain migration   # gen, apply db/migrate, gen again
+          cybertrain db migrate  # gen, apply db/migrate, gen again
           cybertrain server      # http://127.0.0.1:3000 (`cybertrain server 4000` for another port)
           cybertrain build       # dist/: the binary (views embedded) + public/
           ```
 
-          `spin run gen` (which `migration`, `server` and `build` run for you)
+          `spin run gen` (which `db`, `server` and `build` run for you)
           regenerates `gen/` from db/schema.rb, config/routes.rb and app/;
           commit `gen/`. In development views under `app/views/` are read at
           run time: edit them without rebuilding. `cybertrain db status` and
           `cybertrain db rollback 1` reach the other database commands.
-          `cybertrain migration` runs migrations through `bin/db.rb`; a
+          `cybertrain db migrate` runs migrations through `bin/db.rb`; a
           deployed `dist/#{package}` runs them with `./#{package} migrate`.
 
           To deploy, copy `dist/` to a machine with the same OS and CPU, then
@@ -326,7 +326,7 @@ module Cybertrain
             def destroy
               @#{s}.destroy
               flash[:notice] = "#{human} was successfully destroyed."
-              redirect_to #{p}_path, status: :see_other
+              redirect_to #{res.index_helper}_path, status: :see_other
             end
 
             private
@@ -371,7 +371,7 @@ module Cybertrain
         end
         buf << "<p>\n"
         buf << "  <%= link_to \"Edit this #{words}\", edit_#{s}_path(@#{s}) %> |\n"
-        buf << "  <%= link_to \"Back to #{res.plural.tr("_", " ")}\", #{res.plural}_path %>\n"
+        buf << "  <%= link_to \"Back to #{res.plural.tr("_", " ")}\", #{res.index_helper}_path %>\n"
         buf << "</p>\n\n"
         buf << "<%= button_to \"Destroy this #{words}\", #{s}_path(@#{s}), method: :delete %>\n"
         buf
@@ -382,7 +382,7 @@ module Cybertrain
         buf = +""
         buf << "<h1>New #{s.tr("_", " ")}</h1>\n\n"
         buf << "<%= render \"form\", #{s}: @#{s} %>\n\n"
-        buf << "<p><%= link_to \"Back to #{res.plural.tr("_", " ")}\", #{res.plural}_path %></p>\n"
+        buf << "<p><%= link_to \"Back to #{res.plural.tr("_", " ")}\", #{res.index_helper}_path %></p>\n"
         buf
       end
 
@@ -393,7 +393,7 @@ module Cybertrain
         buf << "<%= render \"form\", #{s}: @#{s} %>\n\n"
         buf << "<p>\n"
         buf << "  <%= link_to \"Show this #{s.tr("_", " ")}\", #{s}_path(@#{s}) %> |\n"
-        buf << "  <%= link_to \"Back to #{res.plural.tr("_", " ")}\", #{res.plural}_path %>\n"
+        buf << "  <%= link_to \"Back to #{res.plural.tr("_", " ")}\", #{res.index_helper}_path %>\n"
         buf << "</p>\n"
         buf
       end