cybertrain 0.1.1 → 0.2.1

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 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).
+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,22 +54,65 @@ 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
+      # 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
 
-      # Through bin/db.rb: the app binary cannot compile before the first
-      # migration has produced gen/models.
+      # `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.
       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
 
@@ -66,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
@@ -120,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)
@@ -132,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

@@ -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
@@ -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)],
@@ -47,28 +52,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

@@ -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
@@ -92,6 +95,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" }
@@ -102,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
@@ -113,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) { "" }
@@ -138,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"
@@ -92,17 +87,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
@@ -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
@@ -326,7 +322,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 +367,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 +378,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 +389,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