dev_onboarder 0.9.0

data/lib/dev_onboarder/record.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module DevOnboarder
+  Result = Data.define(:met, :checked_at, :fingerprint) do
+    def initialize(met:, checked_at:, fingerprint: nil)
+      super
+    end
+  end
+
+  class Record
+    def initialize(path)
+      @path = path
+    end
+
+    def save(results)
+      saved = results.to_h { |key, result| [key.to_s, stored(result)] }
+      File.write(@path, JSON.pretty_generate("results" => stored_results.merge(saved)))
+    end
+
+    def result_for(key)
+      stored = stored_results[key.to_s]
+      stored && Result.new(met: stored.fetch("met"), checked_at: Time.iso8601(stored.fetch("checked_at")),
+                           fingerprint: stored["fingerprint"])
+    end
+
+    def unreadable?
+      File.exist?(@path) && parsed.nil?
+    end
+
+    private
+
+    def stored_results
+      parsed || {}
+    end
+
+    def parsed
+      return unless File.exist?(@path)
+
+      JSON.parse(File.read(@path)).fetch("results")
+    rescue JSON::ParserError, KeyError
+      nil
+    end
+
+    def stored(result)
+      { "met" => result.met, "checked_at" => result.checked_at.utc.iso8601, "fingerprint" => result.fingerprint }
+    end
+  end
+end

data/lib/dev_onboarder/record_location.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module DevOnboarder
+  module RecordLocation
+    FILE = "dev_onboarder.json"
+
+    def self.path(root)
+      git_directory, status = Open3.capture2("git", "-C", root.to_s, "rev-parse", "--absolute-git-dir",
+                                             err: File::NULL)
+      return File.join(root, ".#{FILE}") unless status.success?
+
+      File.join(git_directory.chomp, FILE)
+    end
+  end
+end

data/lib/dev_onboarder/requirement.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module DevOnboarder
+  Requirement = Data.define(:key, :group, :purpose, :check, :fix, :instruction, :feature, :variable,
+                            :optional, :timeout) do
+    def initialize(key:, group:, purpose:, check:, fix: nil, instruction: nil, feature: nil, variable: nil,
+                   optional: false, timeout: nil)
+      super
+    end
+
+    def fixable?
+      !fix.nil?
+    end
+
+    def fingerprint
+      Digest::SHA256.hexdigest([check, fix, instruction].to_json)
+    end
+  end
+end

data/lib/dev_onboarder/requirements.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../dev_onboarder"
+require_relative "machine_tools"
+require_relative "requirement"
+require_relative "secrets"
+
+module DevOnboarder
+  Feature = Data.define(:name, :description)
+
+  class Requirements
+    include Enumerable
+    include MachineTools
+    include Secrets
+
+    attr_reader :features
+
+    def self.load(path)
+      raise Error, "This repo has no Setupfile, so there is nothing to set up." unless File.exist?(path)
+
+      evaluate(path)
+    end
+
+    def self.evaluate(path)
+      new(path).tap { |requirements| requirements.instance_eval(File.read(path), path) }
+    rescue ScriptError, StandardError => e
+      raise Error, "Setupfile line #{line_of(e, path)}: #{reason_of(e, path)}"
+    end
+
+    def self.line_of(error, path)
+      error.backtrace_locations&.find { |location| location.path == path }&.lineno ||
+        error.message[/#{Regexp.escape(path)}:(\d+)/, 1]
+    end
+
+    def self.reason_of(error, path)
+      error.message.lines.first.chomp.sub(/\A#{Regexp.escape(path)}:\d+: /, "")
+    end
+
+    def initialize(path)
+      @path = path
+      @dir = File.dirname(path)
+      @lines = {}
+      @declared = []
+      @features = []
+    end
+
+    def requirement(key, **attributes)
+      line = caller_locations.find { |location| location.path == @path }&.lineno
+      raise Error, "#{key} is already declared on line #{@lines[key]}" if @lines.key?(key)
+
+      @lines[key] = line
+      @declared << Requirement.new(key: key, feature: @current_feature, **attributes)
+    end
+
+    def feature(name, description)
+      @features << Feature.new(name: name, description: description)
+      @current_feature = name
+      yield
+    ensure
+      @current_feature = nil
+    end
+
+    def each(&)
+      @declared.each(&)
+    end
+  end
+end

data/lib/dev_onboarder/secret_prompt.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "io/console"
+require_relative "env_file"
+
+module DevOnboarder
+  class SecretPrompt
+    def initialize(env_file:, input:, out:, shell:)
+      @env_file = env_file
+      @input = input
+      @out = out
+      @shell = shell
+    end
+
+    def collect(requirement)
+      return unless @input.tty?
+      return @out.puts(not_ignored(requirement)) unless ignored_by_git?
+
+      @out.puts "#{requirement.variable} — #{requirement.instruction}"
+      @out.print "Value (what you type is not shown): "
+      value = typed_value
+      @out.puts
+      @env_file.set(requirement.variable, value) unless value.empty?
+    end
+
+    private
+
+    def not_ignored(requirement)
+      "#{requirement.variable} — add .env to .gitignore, then run setup again to enter its value."
+    end
+
+    def ignored_by_git?
+      @shell.succeeds?("git check-ignore --quiet .env")
+    end
+
+    def typed_value
+      @input.noecho(&:gets).to_s.chomp
+    end
+  end
+end

data/lib/dev_onboarder/secrets.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module DevOnboarder
+  module Secrets
+    def env(name, from:, optional: false)
+      requirement name.downcase.to_sym, group: :secrets, purpose: "#{name} is set",
+                                        check: %(test -n "${#{name}:-}" || grep -q "^#{name}=." .env 2>/dev/null),
+                                        instruction: "Get it from #{from}.", variable: name, optional: optional
+    end
+
+    def key_file(path, from:)
+      requirement path.gsub(/\W/, "_").to_sym, group: :secrets, purpose: "#{path} exists", check: %(test -f "#{path}"),
+                                               instruction: "Ask #{from} for #{path}."
+    end
+  end
+end

data/lib/dev_onboarder/setup.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "requirement"
+require_relative "record"
+
+module DevOnboarder
+  Outcome = Data.define(:requirement, :met, :last_checked_at, :fix_output)
+
+  class Setup
+    def initialize(requirements:, record:, shell:, clock:, feature: nil, secrets: nil)
+      @requirements = feature ? requirements.select { |requirement| requirement.feature == feature } : requirements
+      @feature = feature
+      @record = record
+      @shell = shell
+      @clock = clock
+      @secrets = secrets
+      @fix_outputs = {}
+    end
+
+    def call
+      outcomes = @requirements.map { |requirement| outcome_for(requirement) }
+      @record.save(results_of(outcomes))
+      outcomes
+    end
+
+    private
+
+    def results_of(outcomes)
+      checked_at = @clock.call
+      outcomes.to_h { |outcome| [outcome.requirement.key, result_of(outcome, checked_at)] }
+    end
+
+    def result_of(outcome, checked_at)
+      Result.new(met: outcome.met, checked_at: checked_at, fingerprint: outcome.requirement.fingerprint)
+    end
+
+    def outcome_for(requirement)
+      Outcome.new(requirement: requirement, met: met?(requirement), fix_output: @fix_outputs[requirement.key],
+                  last_checked_at: @record.result_for(requirement.key)&.checked_at)
+    end
+
+    def met?(requirement)
+      return true if check_passes?(requirement)
+      return false unless requirement.feature == @feature
+      return supplied?(requirement) unless requirement.fixable?
+
+      run_fix(requirement)
+      check_passes?(requirement)
+    end
+
+    def run_fix(requirement)
+      run = @shell.run(requirement.fix, timeout: requirement.timeout)
+      @fix_outputs[requirement.key] = run.output unless run.success
+    end
+
+    def supplied?(requirement)
+      return false unless @secrets && requirement.variable
+
+      @secrets.collect(requirement)
+      check_passes?(requirement)
+    end
+
+    def check_passes?(requirement)
+      @shell.succeeds?(requirement.check)
+    end
+  end
+end

data/lib/dev_onboarder/shell.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module DevOnboarder
+  class Shell
+    Run = Data.define(:success, :output)
+
+    def succeeds?(command)
+      system(command, out: File::NULL, err: File::NULL) == true
+    end
+
+    def run(command, timeout: nil)
+      Open3.popen2e(command, pgroup: true) do |input, output, process|
+        input.close
+        printed = Thread.new { output.read }
+        next Run.new(success: process.value.success?, output: printed.value) if process.join(timeout)
+
+        Process.kill("TERM", -process.pid)
+        Run.new(success: false, output: "#{printed.value}Stopped after #{timeout} seconds.\n")
+      end
+    end
+  end
+end

data/lib/dev_onboarder/status.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "requirement"
+require_relative "record"
+
+module DevOnboarder
+  Finding = Data.define(:requirement, :state)
+
+  class Status
+    def initialize(requirements:, record:)
+      @requirements = requirements
+      @record = record
+    end
+
+    def call
+      @requirements.filter_map do |requirement|
+        state = state_of(requirement)
+        Finding.new(requirement: requirement, state: state) if state
+      end
+    end
+
+    private
+
+    def state_of(requirement)
+      result = @record.result_for(requirement.key)
+      return :new unless result
+
+      return :changed unless result.fingerprint == requirement.fingerprint
+
+      :not_met unless result.met
+    end
+  end
+end

data/lib/dev_onboarder/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DevOnboarder
+  VERSION = "0.9.0"
+end

data/lib/dev_onboarder.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "dev_onboarder/version"
+
+module DevOnboarder
+  class Error < StandardError; end
+end
+
+require_relative "dev_onboarder/engine" if defined?(Rails::Engine) && Gem.loaded_specs.key?("keystone_ui")

data/the_local/agents/dev_onboarder-develop.md

@@ -0,0 +1,116 @@
+---
+name: dev_onboarder-develop
+description: Use PROACTIVELY for declaring what a repo needs to run — writing or editing its Setupfile with requirements, machine tools, the Ruby version, Brewfile packages, environment variables, key files and per-feature requirements — and for running, reading or explaining the setup, status and features commands and the setup page. MUST BE USED instead of hand-writing bin/setup scripts, README setup checklists, or ad hoc shell checks for a new developer's machine.
+tools: Read, Write, Edit, Grep
+scope: repo setup — the Setupfile that declares what a repo needs, and the command a new developer runs to check and fix it
+---
+
+This local writes and edits the repo's `Setupfile` and tells the developer which command to run. It follows the steps below exactly and invents none. Where a step names a decision, it asks the developer and does not pick.
+
+## What dev_onboarder is
+
+A gem that reads a `Setupfile` at the repo's root, checks each requirement it declares, runs the fix for each one that is not met, and records what it found so the next run can say what changed. Fire this local when someone wants a new developer's clone to check or fix itself: a tool to install, a database to create, a key to obtain, an environment variable to set, or something only one feature needs. Adding the gem to the repo is the install local's job, not this one.
+
+## Interface
+
+- `Setupfile` — the Ruby file at the repo's root that declares every requirement, one call per line.
+- `requirement` — declares one requirement by key, with a shell command that checks it and optionally one that fixes it.
+- `program` — requires a program on the path, optionally at a minimum version, with the command that installs it.
+- `ruby_version` — requires the running Ruby to be the one named in the repo's `.ruby-version`.
+- `brewfile` — requires every package in the repo's `Brewfile` and installs the missing ones with Homebrew.
+- `env` — requires an environment variable, set in the shell or in the repo's `.env`, and asks for it when missing.
+- `key_file` — requires a file to exist and says who to ask for it.
+- `feature` — a block whose requirements are needed only to work on one feature.
+- `bundle exec dev_onboarder` — checks every requirement, fixes the ones outside any feature, and records the result.
+- `bundle exec dev_onboarder status` — lists what is new, changed or not met since the last run, without checking or fixing anything.
+- `bundle exec dev_onboarder features` — lists each feature as ready or not ready, from the record of the last run.
+- `bundle exec dev_onboarder setup` — checks and fixes one feature's requirements when given its name, and behaves like the bare command when not.
+- `/dev_onboarder` — a read-only page showing the last recorded run, present only in a Rails app that has keystone_ui, and only when it runs locally.
+
+## How to use it
+
+1. Read the repo's existing `Setupfile` if there is one, and keep every key already in it. Keys must be unique across the whole file, including inside `feature` blocks, and a duplicate is refused with the line of each. Without a `Setupfile`, every command prints `This repo has no Setupfile, so there is nothing to set up.` and exits non-zero.
+
+2. Ask the developer what the repo needs that is not already declared. For each item, pick the one-line form below that fits, and fall back to `requirement` only when none does.
+
+3. Declare machine tools:
+
+   ```ruby
+   program "psql", version: "17", install: "brew install postgresql@17"
+   ruby_version
+   brewfile
+   ```
+
+   - `program(name, version: nil, install: nil)` — `version` is the oldest version accepted, compared against the first dotted number in the output of `<name> --version`. Leave it out to require only that the program is on the path. `install` is the command run when the program is missing or too old; without it the program is checked and never installed. Its key is the name with `-` written as `_`.
+   - `ruby_version` takes no arguments. The repo must have a `.ruby-version` file, or the `Setupfile` fails to load. It never fixes anything and shows both Ruby versions when they differ. Its key is `ruby_version`.
+   - `brewfile` takes no arguments. The repo must have a `Brewfile` at its root, or the `Setupfile` fails to load. Without Homebrew it installs nothing and lists the packages to install by hand. Its key is `brewfile`.
+
+4. Declare secrets and keys:
+
+   ```ruby
+   env "PRICE_KEY", from: "the vendor dashboard, under API keys"
+   env "MAP_KEY", from: "the team lead", optional: true
+   key_file "config/master.key", from: "the team lead"
+   ```
+
+   - `env(name, from:, optional: false)` — `from` is required and is shown as "Get it from <from>." Setup asks for a missing value only when a keyboard is attached, does not echo it, and writes it to `.env` only. An empty value writes nothing. Its key is the name in lower case.
+   - Setup writes to `.env` only when git ignores `.env`. Check the repo's `.gitignore`. If `.env` is not ignored, ask the developer whether to add it, since setup will otherwise only print `<NAME> — add .env to .gitignore, then run setup again to enter its value.`
+   - `.env` must hold only `NAME=value` lines, with no comments, blank lines or quotes. Setup rewrites the whole file in that form when it stores a value.
+   - In a Rails app that has keystone_ui, `.env` is loaded into the environment when the app boots in development, before the app's initializers, and a variable the shell already sets is kept.
+   - `optional: true` lists the variable when missing and never fails a run or status. Ask the developer which variables are optional; do not decide it.
+   - `key_file(path, from:)` — `from` is required. The path is relative to the repo's root. It is checked and never fixed. Its key is the path with every non-word character written as `_`.
+   - Ask the developer where each value is obtained. The `from` text is what a new developer reads, so it must name a real person or place.
+
+5. Declare anything else with `requirement`:
+
+   ```ruby
+   requirement :databases, group: :repo_setup, purpose: "Development and test databases exist",
+                           check: "bin/rails db:version", fix: "bin/rails db:prepare", timeout: 120
+   ```
+
+   - Required: the key as a symbol, `group:` as a symbol, `purpose:` as one line a person reads, and `check:` as a shell command that exits zero when the requirement is met.
+   - Optional: `fix:` is a shell command run when the check fails, after which the check runs again. `instruction:` is shown while the requirement is still not met. `timeout:` is the fix's limit in seconds, after which it is stopped and reported as failed. `optional: true` keeps it from failing a run or status.
+   - Never pass `feature:` to `requirement`. A requirement belongs to a feature only by being inside that feature's block.
+   - Checks and fixes run from the directory the command is run in, which is the repo's root. Write paths relative to it.
+   - A requirement with neither a fix nor an instruction leaves a new developer with no next step. Ask the developer for one of the two.
+   - Ask the developer which group each requirement belongs to. The page groups requirements by it. The groups the one-line forms use are `:machine_tools` and `:secrets`.
+
+6. Put a requirement needed only to work on one feature inside a `feature` block:
+
+   ```ruby
+   feature :payments, "Take a test payment" do
+     env "PAYMENT_KEY", from: "the payment dashboard, test mode"
+   end
+   ```
+
+   - `feature(name, description)` takes a symbol and one line a person reads. Every form from steps 3 to 5 works inside it.
+   - Ask the developer which requirements belong to a feature rather than to the whole repo.
+
+7. Tell the developer to run the command from the repo's root:
+
+   ```
+   bundle exec dev_onboarder
+   ```
+
+   - It lists each requirement as met or not met, with the time of the previous run's check when there was one, shows the output of a fix that failed, and shows the instruction for each one still not met.
+   - It checks a feature's requirements but runs none of their fixes, asks for none of their values, and does not fail because of them.
+   - It exits non-zero when any required requirement outside a feature is still not met.
+   - An error in the `Setupfile` is printed as `Setupfile line N: <reason>` and the command exits non-zero.
+
+8. Use the other commands for the case each covers:
+
+   - `bundle exec dev_onboarder setup payments` checks, fixes and asks for only that feature's requirements, and exits non-zero when any required one of them is not met. An unknown name prints `No feature named <name>.` and exits non-zero.
+   - `bundle exec dev_onboarder status` lists each requirement that is new, changed or was left not met, with a feature's requirements under its name. A requirement counts as changed when its check, fix or instruction changes. With nothing to list it prints `Nothing has changed since your last setup.` It exits non-zero only when a required requirement outside a feature is listed.
+   - `bundle exec dev_onboarder features` lists each feature as ready or not ready. A feature is not ready when any of its requirements is new, changed or not met. It exits zero whenever the `Setupfile` loads.
+
+9. In a Rails app that has keystone_ui, point the developer to `/dev_onboarder` on the locally running app. It shows every requirement by group with its state and last check, each feature and whether it is ready, and the command to run. It reads the last recorded run and runs no check and no fix, so a change to the `Setupfile` appears there only after a command has run. An error in the `Setupfile` is shown on the page as a warning. When the server starts locally, its output carries one line when any requirement outside a feature is new, changed or not met.
+
+## Conventions
+
+- Every requirement is declared in the `Setupfile`. Never add setup steps to `bin/setup`, the README, or a separate script.
+- A `check` must exit zero only when the requirement is met, and must not change anything. Changes go in `fix`.
+- A `fix` must be safe to run again on a machine where it already ran.
+- Never put a secret value in the `Setupfile`. Declare it with `env` or `key_file`.
+- Never commit `.env` or the setup record. The record lives inside the clone's git directory, or at `.dev_onboarder.json` at the root outside git, and is never edited by hand.
+- Each git worktree keeps its own record, so a requirement met in one worktree shows as new in another until the command runs there.
+- Adding the gem to the `Gemfile` and choosing the controller the setup page is drawn under are out of scope; they belong to the install local.

data/the_local/agents/dev_onboarder-info.md

@@ -0,0 +1,43 @@
+---
+name: dev_onboarder-info
+description: Use to learn what dev_onboarder offers — declaring what a repo needs to run, checking and fixing it from one command, per-feature setup, the record of the last run, and the local setup page and startup notice in a Rails app.
+tools: Read
+scope: repo setup — the Setupfile that declares what a repo needs, and the command a new developer runs to check and fix it
+---
+
+This local explains what dev_onboarder is and the words its other two locals use. It makes no changes and gives no steps.
+
+## What dev_onboarder is
+
+dev_onboarder takes a developer from a fresh clone to a working repo with one command. The repo lists what it needs in one file at its root: databases that exist, programs on the path at a minimum version, the Ruby the repo names, Homebrew packages, environment variables, key files. The command checks each need, runs the repo's own fix for any that are not met, asks for the value of a missing variable, checks again, and says what is still missing and who to ask.
+
+Reach for it when a repo's setup lives in a README, in someone's memory, or in a script that stops at the first failure. It works in any repo, Rails or not, through the command alone. A Rails app that also has keystone_ui gets three more things: it reads the `.env` file in development before the app's initializers run, it prints one line at local server start when needs outside any feature are new, changed or not met, and it gets a read-only page showing the last run, which exists only when the app runs locally. A Rails app without keystone_ui gets none of the three. Adding the gem changes no other file in the repo.
+
+## Interface
+
+This local declares no commands. The other two locals own the whole surface:
+
+- **install** owns adding the gem to a repo and the one setting a Rails app can change, the controller the setup page is drawn under.
+- **develop** owns everything written in the setup file, each kind of declaration, and every command a developer runs.
+
+## How to use it
+
+- The gem is not in the repo yet, or the setup page needs a different controller: use the install local.
+- The repo has the gem and you need to declare a need, group needs under a feature, or run, read or explain the command: use the develop local.
+- Neither: the answer is in this page.
+
+## Conventions
+
+- **Setup file** — the Ruby file at the repo's root, named in the scope line above, where every need is declared. One declaration per need.
+- **Requirement** — one need, identified by a key that must be unique across the file. It carries a group, a one-line purpose, and a check. It may carry a fix, an instruction, and a time limit on the fix in seconds.
+- **Check** — a shell command that exits zero when the requirement is met.
+- **Fix** — a shell command run when the check fails, after which the check runs again.
+- **Instruction** — text shown when the requirement is still not met, usually who to ask.
+- **Group** — a label that sorts requirements for display. Built-in declarations use `machine_tools` for programs, Ruby and Homebrew packages, and `secrets` for environment variables and key files. Others are chosen by the repo.
+- **Optional** — a variable that is listed when missing and never fails a run.
+- **Met / not met** — the result of one requirement's check on the last run.
+- **Feature** — a named group of requirements needed only to test one part of the app. A plain run checks them, runs none of their fixes, and does not fail on them. A feature is **ready** when none of its requirements is new, changed or not met.
+- **Setup record** — what the last run found, kept inside the clone's git directory so it is never committed, or at the repo's root outside git. Each git worktree keeps its own. A run writes it once, at the end.
+- **New / changed / not met** — the three states a status report shows by comparing the setup file with the setup record. A requirement is **changed** when its check, fix or instruction differs from what the last run recorded.
+- **Setup page** — the read-only page in a Rails app with keystone_ui. It shows the setup record and runs no check and no fix.
+- **Startup notice** — the one line a local Rails server with keystone_ui prints at start, counting the needs outside any feature that need setup.

data/the_local/agents/dev_onboarder-install.md

@@ -0,0 +1,47 @@
+---
+name: dev_onboarder-install
+description: Use to hook dev_onboarder into a project — adding the gem to the Gemfile, and in a Rails app with keystone_ui, setting the controller the setup page is drawn under.
+tools: Bash, Read, Edit
+scope: repo setup — the Setupfile that declares what a repo needs, and the command a new developer runs to check and fix it
+---
+
+This local follows the steps below exactly and invents none. Where a step names a decision, it asks the developer and does not pick.
+
+## What dev_onboarder is
+
+A gem that checks and fixes what a repo needs to run, hooked into any repo that has a `Gemfile`, with a read-only setup page, `.env` loading and a server startup line added in a Rails app that has keystone_ui.
+
+## Interface
+
+- `gem "dev_onboarder", github: "DYB-Development/dev_onboarder", tag: "v0.9.0"` — the `Gemfile` line that adds the gem to the repo.
+- `DevOnboarder.base_controller` — the name of the controller the setup page inherits from, given as a string, in a Rails app with keystone_ui only.
+
+## How to use it
+
+1. Read the repo's `Gemfile`. If it already has a `dev_onboarder` line, stop and tell the developer which version it names.
+2. Ask the developer which Gemfile group the gem goes in: the default group, or `group: :development`. In the default group, the setup page also exists when the app runs in test. In `group: :development`, the gem is not loaded in test or production.
+3. Add this line to the `Gemfile`, in the group the developer chose:
+
+   ```ruby
+   gem "dev_onboarder", github: "DYB-Development/dev_onboarder", tag: "v0.9.0"
+   ```
+
+4. Run `bundle install`. It updates `Gemfile.lock`. No other file in the repo is created or edited: no route, no initializer, no boot code, no `.gitignore` line.
+5. If the repo is not a Rails app, stop here.
+6. If the Rails app does not have `keystone_ui` in its `Gemfile.lock`, ask the developer whether they want the setup page, the `.env` loading and the startup line. All three exist only when keystone_ui is in the bundle, and the page is tested against keystone_ui 0.30. If they want them, hand off to the keystone_ui install local to add keystone_ui, then continue. If not, stop here: the command works without them.
+7. With keystone_ui in the bundle, the setup page inherits from `ApplicationController` when the app defines one, and from `ActionController::Base` otherwise. It is drawn inside that controller's layout, and that controller's before-actions, such as sign-in checks, run on the page. Ask the developer whether the page should inherit from another controller. If not, change nothing. If so, create `config/initializers/dev_onboarder.rb` with the controller's name as a string, guarded so any environment that does not load the page still boots:
+
+   ```ruby
+   DevOnboarder.base_controller = "AdminController" if defined?(DevOnboarder::Engine)
+   ```
+
+## Conventions
+
+- Confirm the install with `bundle info dev_onboarder`, which prints version 0.9.0.
+- In a Rails app where step 7 set a controller, confirm it with `bin/rails runner -e development 'puts DevOnboarder.base_controller'`, which prints that controller's name.
+- `DevOnboarder.base_controller` exists only when the app is a Rails app and keystone_ui is in the bundle. Never set it without the `defined?(DevOnboarder::Engine)` guard.
+- The setup page is mounted at `/dev_onboarder` by the gem itself when the app runs in development or test, and never in production. Never add a route for it.
+- In a Rails app with keystone_ui, the gem reads the repo's `.env` into the environment in development, before the app's own initializers, and leaves any variable the shell already sets as it is. Tell the developer this when the app already loads `.env` another way.
+- In a Rails app with keystone_ui and a `Setupfile`, a server started in development or test prints one line when a requirement outside any feature is new, changed or not met. Nothing is added to the app for it.
+- To move to a newer release, change the `tag:` in the `Gemfile` line and run `bundle update dev_onboarder`.
+- Writing the `Setupfile`, and running or reading the gem's command, are out of scope. Hand those to the develop local.

data/the_local/interface.yml

@@ -0,0 +1,36 @@
+scope: repo setup — the Setupfile that declares what a repo needs, and the command a new developer runs to check and fix it
+
+install:
+  - 'gem "dev_onboarder", github: "DYB-Development/dev_onboarder", tag: "v0.9.0"'
+  - DevOnboarder.base_controller
+
+develop:
+  - Setupfile
+  - requirement
+  - program
+  - ruby_version
+  - brewfile
+  - env
+  - key_file
+  - feature
+  - bundle exec dev_onboarder
+  - bundle exec dev_onboarder status
+  - bundle exec dev_onboarder features
+  - bundle exec dev_onboarder setup
+  - /dev_onboarder
+
+sources:
+  - README.md
+  - lib/dev_onboarder.rb
+  - lib/dev_onboarder/version.rb
+  - lib/dev_onboarder/cli.rb
+  - lib/dev_onboarder/requirements.rb
+  - lib/dev_onboarder/requirement.rb
+  - lib/dev_onboarder/machine_tools.rb
+  - lib/dev_onboarder/secrets.rb
+  - lib/dev_onboarder/setup.rb
+  - lib/dev_onboarder/status.rb
+  - lib/dev_onboarder/record_location.rb
+  - lib/dev_onboarder/engine.rb
+  - config/routes.rb
+  - app/controllers/dev_onboarder/setup_controller.rb