cybertrain 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bfb12d19791bff7ce88504f9ffb5fe6e2d90ae7a55aa24f5571b1909cf11976
-  data.tar.gz: 0eaac7a028bbf9be6c013b716ecec76f02c91fb10aa04e855f7b777f250c8712
+  metadata.gz: '0800072e567ad58afad9d1e6531aeff2aa0e82d8d9c69f2091fb6d3f5e0a5d61'
+  data.tar.gz: 9e93d0e6dc888ad648ab6acef7d78f52822b72f11aa7435dfd4aeae601334e8a
 SHA512:
-  metadata.gz: 66bf793c97cf16d109519514b10c15d929e627137e58a4663d04ad3e88a746fa12e95b39358f15ebe8ba643107a2f8f30dbee54cbc9e95ea5127a4cc870fb417
-  data.tar.gz: 02bcced8e7ab059cb479b06835420eb241271b4447ed0e7d16c2801c6ed50b6b0d3587ff6557ae9b36501a5a108b05c2a4e7d5757caf7887c353ed41e4c2deb7
+  metadata.gz: 6df2e10e9e78787c2328aa2d96116d44bf437a3de08bd312b513129f8321043503df2fae5afc1b8b14e332e0c44d7990765d846e7bdfd04a8f503490f0066a3a
+  data.tar.gz: eb2b9396571a00406590c504e96c330937570609f0d8d860885f9cf739ab13e6c90a4859d5266d77f847fc2a7ac25078779721046237da3400e0ecde8a24e6e6

data/README.md

@@ -6,7 +6,8 @@
 </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/tutorial.html">Tutorial</a> ·
+  <a href="https://saeki-mototsune.github.io/CyberTrain/api/">API reference</a>
 </p>
 
 # cybertrain
@@ -34,6 +35,38 @@ 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` (`Cybertrain::SPINEL_TAG`, the same release as
@@ -150,7 +183,7 @@ 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
+"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`,
@@ -481,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 |
@@ -508,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`) |
+
+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: `host` (`"127.0.0.1"`),
-`views_root` (`"app/views"`), `public_root` (`"public"`), `layout`
+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
@@ -590,11 +640,19 @@ prints the diff stat).
 
 ## Learn more
 
-- [Homepage](https://saeki-mototsune.github.io/CyberTrain/) and
-  [tutorial](https://saeki-mototsune.github.io/CyberTrain/tutorial.html) —
+- [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
@@ -615,8 +673,12 @@ 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.2.0 && git push origin v0.2.0`.
-3. `gem build cybertrain.gemspec && gem push cybertrain-0.2.0.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

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

data/cybertrain/cli/build.rb

@@ -1,10 +1,42 @@
 # `cybertrain build`: dist/ = the app binary with app/views embedded, plus
 # public/. Also the command lists `cybertrain db` and `server` run. Plain Ruby:
 # runs under CRuby (the gem) and compiles under Spinel (spin install).
+require "cybertrain/app_name"
+
 module Cybertrain
   module CLI
     module Build
-      # The [package] name in root/spin.toml, or "" when there is none.
+      # The entries assemble() keeps in dist/ besides the binary: the copied
+      # public/ and the storage/ and tmp/ directories. A package named like
+      # one of them would collide with it (the binary renamed to dist/public
+      # gets moved aside as dist/.public.old and deleted; a dist/storage
+      # directory cannot be replaced by the binary), so `cybertrain build`
+      # (require_dist_name!) and `cybertrain new` refuse these names;
+      # app_name, which every command reads, does not: `cybertrain db` and
+      # `server` work for an existing app named like one. assemble builds its
+      # paths from these constants so the two cannot drift.
+      DIST_PUBLIC = "public"
+      DIST_STORAGE = "storage"
+      DIST_TMP = "tmp"
+      DIST_ENTRIES = [DIST_PUBLIC, DIST_STORAGE, DIST_TMP]
+
+      # "" when name cannot collide with what assemble() puts in dist/, else
+      # the reason. A leading "." covers assemble's scratch entries
+      # (dist/.<name>.tmp, dist/.public.tmp, dist/.public.old) and "."/"..".
+      # The entry names match case-insensitively: on a case-insensitive
+      # filesystem (macOS's default APFS, one of the CI OSes; Windows) "Public"
+      # and "TMP" are the same directory entry as public and tmp. Only a
+      # different spelling of the whole name ("tmp2", "my_public") is another
+      # entry. downcase is ASCII-safe here: the entries are ASCII.
+      def self.dist_name_problem(name)
+        return "" unless DIST_ENTRIES.include?(name.downcase) || name.start_with?(".")
+
+        "collides with what `cybertrain build` keeps in dist/ (#{DIST_ENTRIES.join(", ")}) or its scratch entries: it cannot be one of those names (in any letter case) or start with '.'"
+      end
+
+      # The [package] name in root/spin.toml, or "" when there is none. The
+      # name ends up in shell command strings and file paths, so it must be
+      # a name `cybertrain new` could have produced.
       def self.app_name(root)
         path = "#{root}/spin.toml"
         return "" unless File.exist?(path)
@@ -22,11 +54,35 @@ module Cybertrain
             break
           end
         end
+        # An empty name is run_in_app's "no spin.toml with a [package] name".
+        # Any other name must be usable as a `spin build` target and a
+        # build/bin/<name> path: the same predicate Application.new applies to
+        # the dev rebuilder's target. The name reaches the shell through
+        # quote_arg, so only what breaks that target or path is refused.
+        return "" if name.empty?
+
+        problem = AppName.problem(name)
+        raise InvalidArgument, "spin.toml [package] name '#{name}' #{problem}" unless problem.empty?
+
         name
       end
 
+      # The build path's check, made once in CLI.build_app before the
+      # toolchain is touched (Build.run does not repeat it): a name that
+      # collides with a dist/ entry only matters to assemble. Returns nil.
+      def self.require_dist_name!(name)
+        problem = dist_name_problem(name)
+        raise InvalidArgument, "spin.toml [package] name '#{name}' #{problem}" unless problem.empty?
+
+        nil
+      end
+
+      # name goes through quote_arg too: app_name validates it, but the
+      # command strings stay safe for a caller that skipped that, whatever the
+      # spelling. An empty name cannot reach these from the CLI (run_in_app
+      # refuses it first); a direct caller passing "" gets `spin build ''`.
       def self.commands(name)
-        ["spin run gen -- --embed-views", "spin build #{name}", "spin run gen"]
+        ["spin run gen -- --embed-views", "spin build #{quote_arg(name)}", "spin run gen"]
       end
 
       # `cybertrain db ARGS`, through bin/db.rb (the app binary cannot compile
@@ -55,7 +111,8 @@ module Cybertrain
 
       # port is "" (the app's default, 3000) or a port? string.
       def self.server_commands(name, port)
-        run = port == "" ? "spin run #{name}" : "spin run #{name} -- #{port}"
+        target = quote_arg(name)
+        run = port == "" ? "spin run #{target}" : "spin run #{target} -- #{quote_arg(port)}"
         ["spin run gen", run]
       end
 
@@ -84,6 +141,8 @@ module Cybertrain
       end
 
       # Runs the build in root and assembles dist/. Returns the exit code.
+      # name must already have passed require_dist_name!: CLI.build_app checks
+      # it once, before the toolchain is fetched.
       def self.run(root, name, runner = Runner.new)
         steps = commands(name)
         ok = false
@@ -138,8 +197,8 @@ module Cybertrain
         dist = "#{root}/dist"
         Templates.mkdir_p(dist)
         binary_tmp = "#{dist}/.#{name}.tmp"
-        public_tmp = "#{dist}/.public.tmp"
-        public_old = "#{dist}/.public.old"
+        public_tmp = "#{dist}/.#{DIST_PUBLIC}.tmp"
+        public_old = "#{dist}/.#{DIST_PUBLIC}.old"
         # Leftovers of an interrupted earlier run.
         rm_tree(binary_tmp)
         rm_tree(public_tmp)
@@ -150,20 +209,20 @@ module Cybertrain
 
         File.rename(binary_tmp, "#{dist}/#{name}")
 
-        if File.directory?("#{root}/public")
-          public_command = "cp -R #{shell_quote("#{root}/public")} #{shell_quote(public_tmp)}"
-          raise InvalidArgument, "could not copy public/ to dist/" unless system(public_command)
+        if File.directory?("#{root}/#{DIST_PUBLIC}")
+          public_command = "cp -R #{shell_quote("#{root}/#{DIST_PUBLIC}")} #{shell_quote(public_tmp)}"
+          raise InvalidArgument, "could not copy #{DIST_PUBLIC}/ to dist/" unless system(public_command)
         else
           Dir.mkdir(public_tmp)
         end
-        public_dir = "#{dist}/public"
+        public_dir = "#{dist}/#{DIST_PUBLIC}"
         File.rename(public_dir, public_old) if File.exist?(public_dir) || File.symlink?(public_dir)
         File.rename(public_tmp, public_dir)
         rm_tree(public_old)
 
-        Templates.mkdir_p("#{dist}/storage")
-        Templates.mkdir_p("#{dist}/tmp")
-        ["dist/#{name}", "dist/public/", "dist/storage/", "dist/tmp/"]
+        Templates.mkdir_p("#{dist}/#{DIST_STORAGE}")
+        Templates.mkdir_p("#{dist}/#{DIST_TMP}")
+        ["dist/#{name}", "dist/#{DIST_PUBLIC}/", "dist/#{DIST_STORAGE}/", "dist/#{DIST_TMP}/"]
       end
 
       # A symlink is removed itself, never followed: its target may be

data/cybertrain/cli/new_app.rb

@@ -14,6 +14,11 @@ module Cybertrain
       # relative to dir.
       def self.create(dir, framework_dep)
         package = File.basename(dir)
+        # Before anything is written: `public`, `storage` and `tmp` are valid
+        # identifiers but collide with dist/ entries (Build.dist_name_problem).
+        problem = Build.dist_name_problem(package)
+        raise InvalidArgument, "'#{package}' is not a valid app name: it #{problem}" unless problem.empty?
+
         title = Inflector.camelize(package)
         files = [
           ["spin.toml", Templates.spin_toml(package, framework_dep)],

data/cybertrain/cli/scaffold.rb

@@ -2,6 +2,7 @@
 # migration, model, controller and views of a resource and adds
 # `resources :posts` to config/routes.rb, the way Rails' scaffold does.
 require "cybertrain/generator/inflector"
+require "cybertrain/ident"
 require "cybertrain/cli/templates"
 
 module Cybertrain
@@ -15,17 +16,12 @@ module Cybertrain
       TYPES = %w[string text integer float boolean date datetime references]
 
       # Columns every table already has (the primary key and t.timestamps).
+      # Everything else a column may not be called -- Ruby keywords, names
+      # that collide with the generated model -- comes from Cybertrain::Ident,
+      # the same rules the generator applies, so the scaffold refuses the
+      # name instead of writing files that `spin run gen` then rejects.
       RESERVED_COLUMNS = %w[id created_at updated_at]
 
-      # Ruby keywords: a column (or resource) named after one would generate
-      # `def class` / `|end|` and break the generated code.
-      RUBY_KEYWORDS = %w[
-        __ENCODING__ __LINE__ __FILE__ BEGIN END alias and begin break case
-        class def defined do else elsif end ensure false for if in module
-        next nil not or redo rescue retry return self super then true undef
-        unless until when while yield
-      ]
-
       attr_reader :field_name, :field_type
 
       def self.parse(arg)
@@ -38,11 +34,18 @@ module Cybertrain
         type = parts.size > 1 ? parts[1].to_s : "string"
         type = "references" if type == "belongs_to"
         raise InvalidArgument, "bad field name '#{name}'" unless Templates.identifier?(name)
-        raise InvalidArgument, "'#{name}' is a Ruby keyword and cannot name a field" if RUBY_KEYWORDS.include?(name)
         raise InvalidArgument, "unknown type '#{type}' for #{name} (use #{TYPES.join(", ")})" unless TYPES.include?(type)
 
         field = Field.new(name, type)
         raise InvalidArgument, "'#{field.column_name}' is a column every table already has" if RESERVED_COLUMNS.include?(field.column_name)
+        # Ident.unusable_reason is the one definition of a name the scaffold
+        # must not invent; Scaffold.refuse_unusable! turns its answer into the
+        # message. A name that only shadows an Object method is accepted, as the
+        # generator accepts it, and Scaffold.generate prints a note.
+        Scaffold.refuse_unusable!(field.column_name, "field")
+        # A references field also defines the reader `def <name>` (post:references
+        # -> def post), which answers to the same rules as a column.
+        Scaffold.refuse_unusable!(name, "reference") if field.reference?
 
         field
       end
@@ -109,6 +112,36 @@ module Cybertrain
     module Scaffold
       DRAW_LINE = "Cybertrain::Routes.draw do"
 
+      # Policy: the scaffold refuses what the generator would RENAME (Ruby
+      # keywords, Ident::RESERVED_COLUMN_NAMES): its views and controller call
+      # the reader by the field's name, so a renamed reader would break them.
+      # It accepts what the generator only annotates (a name that shadows an
+      # Object method, `method`, `display`, `send`) and says so on stdout
+      # (shadow_notes), as the generator does in the model file.
+      #
+      # Raises InvalidArgument when `name` is a name the scaffold must not
+      # invent, with the message for the reason Ident.unusable_reason gives;
+      # `what` says what the name would name ("field", "reference",
+      # "resource"). The one place that maps a reason to a message, shared by the
+      # field column, the references reader and the resource singular: a
+      # reason Ident adds must be added here, and the `else` raises for one
+      # that is not (a `case` without it would return nil and let the name
+      # through silently). Returns nil, explicitly, for a usable name (NOTES
+      # rules 10/34: one return type).
+      def self.refuse_unusable!(name, what)
+        case Ident.unusable_reason(name)
+        when ""
+          nil
+        when "keyword"
+          raise InvalidArgument, "'#{name}' is a Ruby keyword and cannot name a #{what}"
+        when "reserved"
+          raise InvalidArgument, "'#{name}' would shadow a method of the generated model (Cybertrain::Model); pick another #{what}"
+        else
+          raise RuntimeError, "Ident.unusable_reason('#{name}') answered a reason Scaffold.refuse_unusable! has no message for"
+        end
+        nil
+      end
+
       # Returns the paths it created (files that already exist are reported
       # as "identical" or "exist" and left alone). Raises InvalidArgument on a
       # bad name, a bad or duplicate field, or a routes file without a
@@ -120,7 +153,18 @@ module Cybertrain
 
         underscored = Inflector.underscore(name)
         raise InvalidArgument, "bad resource name '#{name}'" unless Templates.identifier?(underscored)
-        raise InvalidArgument, "'#{name}' is a Ruby keyword and cannot name a resource" if Field::RUBY_KEYWORDS.include?(Inflector.singularize(underscored))
+        singular = Inflector.singularize(underscored)
+        # Policy (refuse_unusable!): the scaffold refuses a singular the
+        # generator would RENAME. A reserved one (update, save) would give
+        # every referencing model a `<stem>_as_<col>` reader, and the singular
+        # is also the model class name. A shadowing one (display, tap) is
+        # accepted with a note (shadow_notes). The generator itself still
+        # generates a schema with a reserved table (a hand-written table named
+        # `updates` works), so this is the scaffold's choice, not the
+        # generator's refusal. The plural (the has_many side) is left to the
+        # generator, which renames such a reader (`errors_as_post`) -- and
+        # nothing may reference the table.
+        Scaffold.refuse_unusable!(singular, "resource")
 
         parsed = Array.new(0) { Field.new("", "") }
         columns = Array.new(0) { "" }
@@ -145,9 +189,25 @@ module Cybertrain
         record(created, root, "#{views}/edit.html.erb", Templates.edit_view(res))
         record(created, root, "#{views}/_form.html.erb", Templates.form_partial(res))
         add_route(routes_path, res.plural)
+        shadow_notes(res).each { |note| puts note }
         created
       end
 
+      # One line per name the scaffold accepted that shadows an Object method
+      # (Ident::SHADOWING_COLUMN_NAMES), the generator's own note told on
+      # stdout: a field (or references reader) on the model, the resource
+      # singular on every model that references it.
+      def self.shadow_notes(res)
+        notes = Array.new(0) { "" }
+        res.fields.each do |f|
+          notes << "note: '#{f.field_name}' shadows Object##{f.field_name} on the generated model; call it as #{res.singular}.#{f.field_name}" if Ident.shadowing_column?(f.field_name)
+        end
+        if Ident.shadowing_column?(res.singular)
+          notes << "note: '#{res.singular}' shadows Object##{res.singular} on a model that references #{res.plural} (belongs_to reader); call it as record.#{res.singular}"
+        end
+        notes
+      end
+
       def self.record(created, root, path, content)
         created << path if Templates.write(root, path, content) == "create"
         nil

data/cybertrain/cli/templates.rb

@@ -5,6 +5,8 @@
 # The scaffold templates take a Cybertrain::CLI::Resource (cli/scaffold.rb).
 # Generated views stay inside the template language of docs/design.md
 # section 7: literals, @ivars, locals, helper calls, `if` and `each do`.
+require "cybertrain/ident"
+
 module Cybertrain
   module CLI
     module Templates
@@ -39,19 +41,12 @@ module Cybertrain
         nil
       end
 
-      # A lowercase Ruby-ish name: "post", "blog_post", "released_on".
+      # A lowercase Ruby-ish name: "post", "blog_post", "released_on". The
+      # snake_case subset of Ident.column? (what the generator accepts),
+      # letter-first since it names packages, binaries and files too; one
+      # definition of the characters, so the two cannot drift apart.
       def self.identifier?(word)
-        return false if word == ""
-
-        ok = true
-        first = true
-        word.each_char do |ch|
-          lower = ch >= "a" && ch <= "z"
-          digit = ch >= "0" && ch <= "9"
-          ok = false unless lower || (!first && (digit || ch == "_"))
-          first = false
-        end
-        ok
+        Ident.snake_case?(word, false)
       end
 
       # "blog_posts" -> "Blog posts"
@@ -115,7 +110,8 @@ module Cybertrain
         <<~RUBY
           # Application settings; see Cybertrain::Config for every option.
           # Environment variables (PORT, CYBERTRAIN_ENV, CYBERTRAIN_DATABASE,
-          # CYBERTRAIN_SECRET_KEY_BASE) are read before this block runs.
+          # CYBERTRAIN_SECRET_KEY_BASE, CYBERTRAIN_HOST, CYBERTRAIN_SESSION_SAME_SITE,
+          # CYBERTRAIN_SESSION_PARTITIONED) are read before this block runs.
           Cybertrain.configure do |c|
             # c.port = 3000
             # c.workers = 1

data/cybertrain/cli.rb

@@ -67,7 +67,7 @@ module Cybertrain
       when "migration" then run_in_app { |_name| run_spin(Build.db_commands(["migrate"])) }
       when "db" then run_in_app { |_name| run_db(argv) }
       when "server" then run_in_app { |name| run_server(name, argv) }
-      when "build" then run_in_app { |name| Toolchain.ensure! ? Build.run(".", name) : 1 }
+      when "build" then run_in_app { |name| build_app(name) }
       when "spin" then run_spin_passthrough(argv)
       when "setup" then Toolchain.setup(argv[1, argv.size - 1])
       when "doctor" then run_doctor(argv)
@@ -163,6 +163,14 @@ module Cybertrain
       yield name
     end
 
+    # `cybertrain build`: the one dist/ name check, made before the toolchain
+    # is fetched or any spin command runs; Build.run assumes a name that got
+    # past it.
+    def self.build_app(name)
+      Build.require_dist_name!(name)
+      Toolchain.ensure! ? Build.run(".", name) : 1
+    end
+
     # Runs spin commands in turn once a Spinel of the pinned release is on
     # PATH; stops at the first failure.
     def self.run_spin(commands)

data/cybertrain/generator/inflector.rb

@@ -55,8 +55,9 @@ module Cybertrain
     def self.underscore(camel_cased_word)
       return camel_cased_word.dup unless camel_cased_word.match?(/[A-Z-]|::/)
 
-      # Two steps: in a threaded program a collection inside `chars` freed the
-      # unnamed gsub result it was splitting ("Post" came back as "").
+      # Two steps, the gsub result held in a local: in a threaded program a
+      # collection inside `chars` frees an unnamed gsub result it is
+      # splitting ("Post" comes back as "").
       path = camel_cased_word.gsub("::", "/")
       chars = path.chars
       out = +""

data/cybertrain/ident.rb

@@ -0,0 +1,171 @@
+# Cybertrain::Ident -- the one place that says what a column (or scaffold
+# field) may be called. Used by the generator (ModelsEmitter), the ORM
+# (Relation#order) and the CLI (`cybertrain generate scaffold`), so a name
+# the scaffold accepts is a name the generator and the models accept, and
+# the failure comes from the command that would write the files.
+#
+# Plain Ruby with no requires: the CLI gem ships this file and runs it under
+# CRuby, the framework compiles it under Spinel (no Regexp, NOTES rule 1).
+module Cybertrain
+  module Ident
+    # Column names whose plain reader the generated class cannot host: it
+    # would shadow a method the generated class or the framework calls on the
+    # record. The generator renames them, so an existing schema keeps
+    # generating: the column reads as `<column>_column`
+    # (ModelsEmitter.reader_name). The scaffold refuses them: its views and
+    # controller call the reader by the field's name, which a renamed reader
+    # would break. `id` is deliberately
+    # absent: the primary key is Model#id. Names that end in `?` or `!`
+    # cannot be columns at all (column? rejects them), so `valid?`,
+    # `persisted?`, `is_a?` need no entry; keywords (`class`) live in
+    # RUBY_KEYWORDS only, and the generator renames those the same way
+    # (`class_column`). Class methods (`table_name`, `column_names`,
+    # `from_row`) need no entry either: the framework calls them on the
+    # class (`self.class.table_name`, `Post.from_row`), which a column
+    # reader on the instance does not shadow, so a schema with a
+    # `table_name` column keeps generating. script/check-reserved-names
+    # keeps the Model and Object groups here and in SHADOWING_COLUMN_NAMES
+    # in step with the code (it skips `def self.` methods).
+    RESERVED_COLUMN_NAMES = [
+      # Cybertrain::Model: its methods and the ivars behind them (`errors`,
+      # `persisted` -> @errors, @persisted)
+      "errors", "persisted", "attributes", "save", "update", "destroy",
+      "reload", "model_name", "to_json", "as_json", "to_param", "to_row",
+      "load_row", "set_id", "run_callbacks", "insert_row", "update_row",
+      "read_attribute", "write_attribute", "assign_attributes",
+      "read_association", "call_view_method", "initialize",
+      # Object methods Ruby or the framework calls on a record without being
+      # asked: string interpolation and templates (to_s), error messages
+      # (inspect), Hash keys (hash)
+      "hash", "inspect", "to_s",
+      # Implicit-conversion and dispatch hooks Ruby calls on its own (none is
+      # defined on Object, so no reflection finds them): an arity-0 reader
+      # returning a String breaks `puts post` / `[post].flatten` / a splat
+      # (to_ary), string coercion (to_str), keyword splats (to_hash), `&post`
+      # (to_proc), Integer coercion (to_int), and turns every NoMethodError
+      # into an ArgumentError (method_missing). `respond_to_missing?` ends in
+      # `?` and needs no entry.
+      "to_ary", "to_str", "to_hash", "to_proc", "to_int", "to_a", "to_h",
+      "to_sym", "to_io", "to_path", "to_regexp", "coerce", "method_missing",
+      # Hooks Ruby itself calls WITH an argument, which it finds whether they
+      # are public or private (so Object.instance_methods never lists the
+      # private ones): `record.dup` / `clone` call initialize_copy(orig)
+      # (initialize_dup / initialize_clone on the way), and defining, removing
+      # or undefining a singleton method (`def record.x`) calls
+      # singleton_method_added / _removed / _undefined. A zero-arity column
+      # reader in their place raises ArgumentError at that call. These are
+      # reserved, not merely shadowing: the problem is Ruby's call, not a
+      # method the caller could have wanted. script/check-reserved-names
+      # fails when one of Ruby's private hooks is missing here.
+      "initialize_copy", "initialize_dup", "initialize_clone",
+      "singleton_method_added", "singleton_method_removed",
+      "singleton_method_undefined",
+      # The one Kernel method the model calls on implicit self (Model#save!
+      # and #reload would dispatch `raise RecordInvalid, ...` to the
+      # zero-arity reader), and its alias. No other private Kernel method is
+      # reserved: `open`, `format`, `load`, `print`, `select`, `test` are
+      # ordinary column names and nothing in the generated class calls them.
+      "raise", "fail"
+    ]
+
+    # The rest of Object's public instance methods: a column so named shadows
+    # them on its model (`record.display`, `record.tap` are the column), but
+    # neither the generated class nor the framework calls any of them on a
+    # record, so the generator accepts the column and writes a note into the
+    # generated file instead of refusing an existing schema. The scaffold
+    # accepts them the same way, with a note on stdout (Scaffold.shadow_notes):
+    # `payment.method` is the field, which its views and controller call.
+    SHADOWING_COLUMN_NAMES = [
+      "object_id", "__id__", "send", "__send__", "public_send", "freeze",
+      "display", "method", "methods", "public_method", "public_methods",
+      "private_methods", "protected_methods", "singleton_class",
+      "singleton_method", "singleton_methods", "define_singleton_method",
+      "remove_instance_variable", "instance_variable_get",
+      "instance_variable_set", "instance_variables", "instance_eval",
+      "instance_exec", "dup", "clone", "tap", "yield_self", "itself",
+      "extend", "enum_for", "to_enum"
+    ]
+
+    # Ruby keywords a column could be spelled like: `@end` / `def class` are
+    # not shapes worth supporting. The generator reads such a column as
+    # `<column>_column` (ModelsEmitter.reader_name), like a reserved name;
+    # the scaffold refuses them (its views call the reader by name). The
+    # uppercase ones are reachable since column? accepts capitals. `defined`
+    # is not here: the keyword is `defined?`, which column? rejects, and
+    # `defined` is an ordinary method name (`attr_accessor :defined` works).
+    RUBY_KEYWORDS = [
+      "alias", "and", "begin", "break", "case", "class", "def", "do",
+      "else", "elsif", "end", "ensure", "false", "for", "if", "in",
+      "module", "next", "nil", "not", "or", "redo", "rescue", "retry",
+      "return", "self", "super", "then", "true", "undef", "unless", "until",
+      "when", "while", "yield",
+      "BEGIN", "END", "__ENCODING__", "__FILE__", "__LINE__"
+    ]
+
+    # /\A[A-Za-z_][A-Za-z0-9_]*\z/ spelled out: what Ruby needs of a method
+    # name, so a schema with camelCase or mixed-case columns (`createdAt`,
+    # `userId`, a legacy SQLite table) generates under its own name, not a
+    # renamed one; `attr_accessor :createdAt` and `attr_accessor :Title` both
+    # compile and dispatch under Spinel (probed on 2026.09.12). The
+    # scaffold, which chooses new names, keeps the stricter snake_case rule
+    # (CLI::Templates.identifier?). A flag rather than a `return` inside
+    # the block, like Templates.identifier?: a `return` from an each_char
+    # block does leave the method under Spinel (probed), but the flag needs
+    # no such guarantee.
+    def self.column?(name)
+      return false if name.empty?
+
+      ok = true
+      first = true
+      name.each_char do |ch|
+        letter = (ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z")
+        digit = ch >= "0" && ch <= "9"
+        ok = false unless letter || ch == "_" || (digit && !first)
+        first = false
+      end
+      ok
+    end
+
+    # The snake_case subset of column?: lowercase only, and a leading `_`
+    # only when allowed. CLI::Templates.identifier? (app, resource and field
+    # names: letter-first) and Template::Lexer.identifier? (template locals
+    # and block parameters: `_x` allowed) are both this predicate, so the two
+    # cannot drift. A positional default rather than a keyword argument: this
+    # file compiles under Spinel and keeps to the shapes it already uses.
+    def self.snake_case?(word, leading_underscore = true)
+      column?(word) && word == word.downcase && (leading_underscore || !word.start_with?("_"))
+    end
+
+    def self.keyword?(name)
+      RUBY_KEYWORDS.include?(name)
+    end
+
+    def self.reserved_column?(name)
+      RESERVED_COLUMN_NAMES.include?(name)
+    end
+
+    def self.shadowing_column?(name)
+      SHADOWING_COLUMN_NAMES.include?(name)
+    end
+
+    # The one definition of "a name the scaffold must not invent": "" when
+    # `name` may be chosen, otherwise why not -- "keyword" (RUBY_KEYWORDS) or
+    # "reserved" (RESERVED_COLUMN_NAMES): the two kinds the generator RENAMES,
+    # which the scaffold cannot accept because its views and controller call
+    # the reader by the field's name. A SHADOWING_COLUMN_NAMES entry is not
+    # refused: the generator keeps its name with a note, and so does the
+    # scaffold (shadowing_column?). The scaffold asks here at every place it
+    # takes a name from the user (field column, references reader, resource
+    # singular) and raises the message for the reason, so a new list of names
+    # is added to this method once, not to each call site. A String, not nil
+    # or a Symbol, so the return type is the same on every path (NOTES rules
+    # 10/34); a keyword that is also listed in a column array reports
+    # "keyword" first.
+    def self.unusable_reason(name)
+      return "keyword" if keyword?(name)
+      return "reserved" if reserved_column?(name)
+
+      ""
+    end
+  end
+end

data/cybertrain/version.rb

@@ -1,5 +1,5 @@
 module Cybertrain
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 
   # Where `cybertrain new` points an app's spin.toml by default: the git tag
   # "v#{VERSION}" of this repository. Kept here because the gem (CRuby) and

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cybertrain
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Saeki Mototsune
@@ -22,6 +22,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- cybertrain/app_name.rb
 - cybertrain/cli.rb
 - cybertrain/cli/build.rb
 - cybertrain/cli/new_app.rb
@@ -29,6 +30,7 @@ files:
 - cybertrain/cli/templates.rb
 - cybertrain/cli/toolchain.rb
 - cybertrain/generator/inflector.rb
+- cybertrain/ident.rb
 - cybertrain/version.rb
 - exe/cybertrain
 homepage: https://github.com/saeki-mototsune/cybertrain