dev_onboarder 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a976b60fbd1fdf065d23f456c7e8748e3d9a14431355386c8b7e7b55465af4fc
+  data.tar.gz: 7dfbe87e983559d84a811fb9c87dceb0f74c9d1929a082c20310f13969b0a2ce
+SHA512:
+  metadata.gz: 8e0b84e69b5b6dbe02339487cefcea0f7a0d95b5c9f3e687d799b19dcac07da0d37d547ef98fe59b9aac924487e78047785c1eb6a0e03d55992d8954fd578025
+  data.tar.gz: 8d6503b8bc9d9a4d4a2d177d17979723191a4feb3342da456aeb9181e70f0923498b003feb11c7db54169dc4d547a727b38340bfb13bf22349615ed328009524

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+## [Unreleased]
+
+## [0.9.0]
+
+- The gem is a the_local provider: a host that runs `the_local install` gets info, install and develop locals for the setup tool.
+
+## [0.8.0]
+
+- A host adds only the gem and its `Setupfile`, and changes nothing else.
+- A Rails app in development loads `.env` before its own initializers.
+- The setup page is at `/dev_onboarder` in local environments with no route drawn by the app, and uses the app's `ApplicationController`.
+- The setup record is kept inside the clone's git directory, one for each worktree.
+
+## [0.7.0]
+
+- A failed fix shows what it printed, and a requirement can set a time limit for its fix.
+- An error in the `Setupfile`, a repeated key and a missing `Setupfile` are reported without a stack trace.
+- A setup record that cannot be read is reported and written again.
+- The setup page says so when the repo has no `Setupfile`.
+
+## [0.6.0]
+
+- A Rails app with keystone_ui can mount `DevOnboarder::Engine` to show the setup page.
+- An app's server prints one line when it starts locally and a requirement needs setup.
+
+## [0.5.0]
+
+- `env` and `key_file` declare secrets and keys requirements in one line each.
+- Setup asks for a missing variable's value and stores it in the repo's ignored `.env` file.
+- `DevOnboarder::EnvFile#load_into` loads that file into the environment when an app starts.
+
+## [0.4.0]
+
+- `program`, `ruby_version` and `brewfile` declare machine tools requirements in one line each.
+
+## [0.3.0]
+
+- A `feature` block in the `Setupfile` groups the requirements needed only to test one feature.
+- `dev_onboarder setup <feature>` checks and fixes one feature, and `dev_onboarder features` lists which are ready.
+- A run now adds its results to the setup record and keeps the results it did not check.
+
+## [0.2.0]
+
+- `dev_onboarder status` lists each requirement that is new, changed or not met since the last run.
+- The setup record stores a fingerprint of each requirement's check, fix and instruction.
+
+## [0.1.0]
+
+- `dev_onboarder` checks each requirement in a repo's `Setupfile`, runs its fix and records the result.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 tylercschneider
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,127 @@
+# dev_onboarder
+
+One setup command that gets a developer from a fresh clone to a working repo.
+
+## Install
+
+Add the gem to the repo's `Gemfile` and run `bundle install`, then write a `Setupfile`. Nothing else in
+the repo changes: the gem adds no line to its routes, boot code, initializers or `.gitignore`.
+
+## Declare what the repo needs
+
+Write a `Setupfile` at the repo's root. Each line declares one requirement:
+
+```ruby
+requirement :databases, group: :repo_setup, purpose: "Development and test databases exist",
+                        check: "bin/rails db:version", fix: "bin/rails db:prepare"
+
+requirement :price_key, group: :secrets, purpose: "Stock price key is set",
+                        check: "test -n \"$PRICE_KEY\"", instruction: "Ask the team lead for the key"
+```
+
+- `check` is a shell command that exits zero when the requirement is met.
+- `fix` is a shell command run when the check fails, after which the check runs again.
+- `instruction` is shown when the requirement is still not met.
+
+## Declare machine tools in one line
+
+```ruby
+program "psql", version: "17", install: "brew install postgresql@17"
+ruby_version
+brewfile
+```
+
+- `program` requires a program on the path. `version` is the oldest version accepted, read from the
+  program's `--version` output, and `install` is the command run when the program is missing or too old.
+- `ruby_version` requires the running Ruby to be the one the repo's `.ruby-version` names, and shows
+  both versions when they differ.
+- `brewfile` requires every package in the repo's `Brewfile` and installs the missing ones with
+  Homebrew. Without Homebrew it installs nothing and lists the packages.
+
+## Declare secrets and keys in one line
+
+```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` requires an environment variable, set either in the shell or in the repo's `.env` file. When
+  it is missing, setup shows where to get it and asks for the value. What is typed is not shown, and it
+  is written to `.env` and to nowhere else.
+- Setup stores a value only when git ignores `.env`. Otherwise it says to add `.env` to `.gitignore`.
+- An `optional` variable is listed when it is missing and does not fail setup or status.
+- `key_file` requires a file to exist and says who to ask for it.
+- Setup asks for nothing when no keyboard is attached, as in CI.
+
+A Rails app that has keystone_ui reads `.env` when it starts in development, before its own
+initializers run, with nothing added to the app. A variable the shell already sets is left as it is.
+
+## Run it
+
+```
+bundle exec dev_onboarder
+```
+
+The command lists every requirement as met or not met, and exits with a failure status when any is
+still not met. It writes what it found to `dev_onboarder.json` inside the clone's git directory, where
+nothing is ever committed, so a second run shows when each requirement was last checked. Each git
+worktree keeps its own record. Outside git, the record is `.dev_onboarder.json` at the repo's root.
+
+## Declare what one feature needs
+
+A requirement needed only to test one feature goes inside a `feature` block:
+
+```ruby
+feature :payments, "Take a test payment" do
+  requirement :payment_key, group: :secrets, purpose: "Payment test key is set",
+                            check: "test -n \"$PAYMENT_KEY\"", instruction: "Copy the test key from the payment dashboard"
+end
+```
+
+- `bundle exec dev_onboarder` checks a feature's requirements, runs none of their fixes, and does not
+  fail because of them.
+- `bundle exec dev_onboarder setup payments` checks and fixes only that feature's requirements.
+- `bundle exec dev_onboarder features` lists each feature as ready or not ready, from the record of
+  the last run.
+
+## Show the setup page in a Rails app
+
+In a Rails app that has keystone_ui, the gem adds a page that shows what the last setup run recorded:
+every requirement by group with its state and when it was last checked, each feature and whether it is
+ready, and the command to run. The page reads the `Setupfile` and the setup record. It runs no check and
+no fix.
+
+When the app runs locally, the page is at `/dev_onboarder`, and it does not exist in production. It is
+drawn inside the app's own layout when the app has an `ApplicationController`. To use another
+controller, set `DevOnboarder.base_controller = "AdminController"`.
+
+When the app's server starts locally and a requirement outside any feature is new, changed or not met,
+the server output carries one line saying how many need setup and the command to run.
+
+A Rails app without keystone_ui gets no page, no `.env` loading and no startup line, and a repo with no
+Rails app is unaffected. Both use the command alone. The page is tested against keystone_ui 0.30.
+
+## When something fails
+
+- A fix that exits non-zero has what it printed shown under its requirement.
+- A requirement can set a time limit for its fix, in seconds: `fix: "bin/rails db:prepare", timeout: 120`.
+  A fix that runs past it is stopped and reported as failed.
+- An error in the `Setupfile` is reported with the line it is on, and no stack trace.
+- Two requirements with the same key are refused, with the line of each.
+- A setup record that cannot be read is reported, and the run writes it again.
+- A run writes the setup record once, when it ends, so a run stopped part way leaves the earlier record
+  as it was.
+
+## See what changed
+
+```
+bundle exec dev_onboarder status
+```
+
+Status compares the `Setupfile` with the record of the last run and lists each requirement that is
+new, changed or was left not met. It runs no check and no fix and writes nothing. It exits with a
+failure status when it lists anything. A requirement counts as changed when its `check`, `fix` or
+`instruction` changes.
+
+A feature's requirements are listed under the feature's name, and status does not fail because of them.

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]
+
+require "the_local/rake"

data/app/controllers/dev_onboarder/setup_controller.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module DevOnboarder
+  class SetupController < DevOnboarder.base_controller.constantize
+    helper KeystoneUiHelper
+
+    rescue_from DevOnboarder::Error do |error|
+      render html: helpers.ui_alert(message: error.message, type: :warning), layout: true
+    end
+
+    def show
+      @overview = Engine.overview(Rails.root.to_s)
+    end
+  end
+end

data/app/views/dev_onboarder/setup/show.html.erb

@@ -0,0 +1,61 @@
+<%
+  state_badges = {
+    met: { label: "Met", variant: :success },
+    new: { label: "New", variant: :info },
+    changed: { label: "Changed", variant: :warning },
+    not_met: { label: "Not met", variant: :danger }
+  }
+
+  requirement_columns = [
+    Keystone::Ui::Column.new(:requirement, "Requirement"),
+    Keystone::Ui::Column.new(:purpose, "Purpose"),
+    Keystone::Ui::Column.new(:state, "State"),
+    Keystone::Ui::Column.new(:last_checked, "Last checked", mobile_hidden: true)
+  ]
+%>
+
+<%= ui_page do %>
+  <%= ui_page_header(title: "Setup", subtitle: "What this repo needs on your machine") %>
+
+  <% if @overview.notice.present? %>
+    <%= ui_alert(message: @overview.notice, type: :warning) %>
+  <% else %>
+    <%= ui_alert(message: "Everything outside a feature is set up.", type: :success) %>
+  <% end %>
+
+  <%= ui_section do %>
+    <%= ui_code(caption: "Run this command to set up what is missing") do %>bundle exec dev_onboarder<% end %>
+    <%= ui_copy_button(text: "bundle exec dev_onboarder") %>
+  <% end %>
+
+  <% @overview.groups.each do |group| %>
+    <%
+      requirement_rows = group.rows.map do |row|
+        {
+          requirement: row.requirement.key.to_s,
+          purpose: row.requirement.purpose,
+          state: ui_badge(**state_badges.fetch(row.state)),
+          last_checked: row.checked_at ? row.checked_at.utc.strftime("%Y-%m-%d %H:%M UTC") : "Never"
+        }
+      end
+    %>
+    <%= ui_section(title: group.name.to_s.tr("_", " ").capitalize) do %>
+      <%= ui_data_table(items: requirement_rows, columns: requirement_columns) %>
+    <% end %>
+  <% end %>
+
+  <% if @overview.features.any? %>
+    <%
+      feature_rows = @overview.features.map do |entry|
+        {
+          feature: entry.feature.name.to_s,
+          description: entry.feature.description,
+          status: entry.ready ? ui_badge(label: "Ready", variant: :success) : ui_badge(label: "Not ready", variant: :neutral)
+        }
+      end
+    %>
+    <%= ui_section(title: "Features") do %>
+      <%= ui_data_table(items: feature_rows, columns: [{ feature: "Feature" }, { description: "Description" }, { status: "Status" }]) %>
+    <% end %>
+  <% end %>
+<% end %>

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+DevOnboarder::Engine.routes.draw do
+  root to: "setup#show"
+end

data/exe/dev_onboarder

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "dev_onboarder/cli"
+
+exit DevOnboarder::CLI.new(ARGV).call

data/lib/dev_onboarder/cli.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "lines"
+require_relative "record_location"
+require_relative "requirements"
+require_relative "secret_prompt"
+require_relative "setup"
+require_relative "shell"
+require_relative "status"
+
+module DevOnboarder
+  class CLI
+    REQUIREMENTS_FILE = "Setupfile"
+    ENV_FILE = ".env"
+
+    def initialize(argv, out: $stdout, dir: Dir.pwd, shell: Shell.new, clock: -> { Time.now }, input: $stdin)
+      @input = input
+      @argv = argv
+      @out = out
+      @dir = dir
+      @shell = shell
+      @clock = clock
+    end
+
+    def call
+      run
+    rescue Error => e
+      @out.puts e.message
+      1
+    end
+
+    private
+
+    def run
+      return report_status if @argv.first == "status"
+      return report_features if @argv.first == "features"
+      return report_unknown_feature if feature && !declared_feature?
+
+      run_setup
+    end
+
+    def report_status
+      @out.puts status_lines
+      findings_of(nil).all? { |finding| finding.requirement.optional } ? 0 : 1
+    end
+
+    def status_lines
+      return "Nothing has changed since your last setup." if findings.empty?
+
+      outside_any_feature = findings_of(nil).map { |finding| Lines.for_finding(finding) }
+      outside_any_feature + requirements.features.flat_map { |declared| feature_lines(declared) }
+    end
+
+    def feature_lines(declared)
+      listed = findings_of(declared.name)
+      return [] if listed.empty?
+
+      ["#{declared.name} — #{declared.description}"] + listed.map { |finding| "  #{Lines.for_finding(finding)}" }
+    end
+
+    def findings_of(feature_name)
+      findings.select { |finding| finding.requirement.feature == feature_name }
+    end
+
+    def report_features
+      @out.puts(requirements.features.map { |declared| Lines.for_feature(declared, ready: ready?(declared)) })
+      0
+    end
+
+    def ready?(declared)
+      findings.none? { |finding| finding.requirement.feature == declared.name }
+    end
+
+    def report_unknown_feature
+      @out.puts "No feature named #{feature}."
+      1
+    end
+
+    def run_setup
+      @out.puts "The setup record could not be read, so this run writes it again." if record.unreadable?
+      outcomes = setup.call
+      outcomes.each { |outcome| @out.puts Lines.for_outcome(outcome) }
+      outcomes.select { |outcome| required?(outcome.requirement) }.all?(&:met) ? 0 : 1
+    end
+
+    def setup
+      Setup.new(requirements: requirements, record: record, shell: @shell, clock: @clock, feature: feature,
+                secrets: secret_prompt)
+    end
+
+    def required?(requirement)
+      requirement.feature == feature && !requirement.optional
+    end
+
+    def secret_prompt
+      SecretPrompt.new(env_file: EnvFile.new(File.join(@dir, ENV_FILE)), input: @input, out: @out, shell: @shell)
+    end
+
+    def feature
+      @argv[1]&.to_sym
+    end
+
+    def declared_feature?
+      requirements.features.any? { |declared| declared.name == feature }
+    end
+
+    def findings
+      @findings ||= Status.new(requirements: requirements, record: record).call
+    end
+
+    def requirements
+      @requirements ||= Requirements.load(File.join(@dir, REQUIREMENTS_FILE))
+    end
+
+    def record
+      Record.new(RecordLocation.path(@dir))
+    end
+  end
+end

data/lib/dev_onboarder/engine.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+require "keystone_ui"
+require_relative "env_file"
+require_relative "overview"
+require_relative "record_location"
+require_relative "requirements"
+
+module DevOnboarder
+  class << self
+    attr_writer :base_controller
+
+    def base_controller
+      @base_controller || (Object.const_defined?(:ApplicationController) ? "ApplicationController" : "ActionController::Base")
+    end
+  end
+
+  class Engine < ::Rails::Engine
+    isolate_namespace DevOnboarder
+
+    initializer "dev_onboarder.load_environment_file", before: :load_config_initializers do |app|
+      EnvFile.new(app.root.join(".env").to_s).load_into(ENV) if Rails.env.development?
+    end
+
+    initializer "dev_onboarder.page_route" do |app|
+      app.routes.prepend { mount DevOnboarder::Engine, at: "/dev_onboarder" if Rails.env.local? }
+    end
+
+    server do
+      notice = startup_notice(Rails.root.to_s) if Rails.env.local?
+      puts notice if notice
+    end
+
+    def self.startup_notice(root)
+      return unless File.exist?(File.join(root, "Setupfile"))
+
+      overview(root).notice
+    end
+
+    def self.overview(root)
+      Overview.new(requirements: Requirements.load(File.join(root, "Setupfile")),
+                   record: Record.new(RecordLocation.path(root)))
+    end
+  end
+end

data/lib/dev_onboarder/env_file.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DevOnboarder
+  class EnvFile
+    def initialize(path)
+      @path = path
+    end
+
+    def set(name, value)
+      File.write(@path, values.merge(name => value).map { |key, stored| "#{key}=#{stored}\n" }.join)
+    end
+
+    def load_into(environment)
+      values.each { |name, value| environment[name] ||= value }
+    end
+
+    private
+
+    def values
+      return {} unless File.exist?(@path)
+
+      File.readlines(@path, chomp: true).to_h { |line| line.split("=", 2) }
+    end
+  end
+end

data/lib/dev_onboarder/lines.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DevOnboarder
+  module Lines
+    STATE_LABELS = { new: "new    ", changed: "changed", not_met: "not met" }.freeze
+
+    def self.for_outcome(outcome)
+      [outcome_line(outcome), *fix_output(outcome), instruction(outcome)].compact
+    end
+
+    def self.for_finding(finding)
+      "#{STATE_LABELS.fetch(finding.state)}  #{finding.requirement.key} — #{finding.requirement.purpose}"
+    end
+
+    def self.for_feature(feature, ready:)
+      "#{ready ? "ready    " : "not ready"}  #{feature.name} — #{feature.description}"
+    end
+
+    def self.outcome_line(outcome)
+      "#{outcome.met ? "met    " : "not met"}  #{outcome.requirement.key} — #{outcome.requirement.purpose}" \
+        "#{last_checked(outcome)}"
+    end
+
+    def self.fix_output(outcome)
+      outcome.fix_output.to_s.lines(chomp: true).map { |line| "         #{line}" }
+    end
+
+    def self.instruction(outcome)
+      return if outcome.met || outcome.requirement.instruction.nil?
+
+      "         #{outcome.requirement.instruction}"
+    end
+
+    def self.last_checked(outcome)
+      return unless outcome.last_checked_at
+
+      " (last checked #{outcome.last_checked_at.utc.strftime("%Y-%m-%d %H:%M UTC")})"
+    end
+
+    private_class_method :outcome_line, :fix_output, :instruction, :last_checked
+  end
+end

data/lib/dev_onboarder/machine_tools.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module DevOnboarder
+  module MachineTools
+    HOMEBREW_ON_PATH = "command -v brew >/dev/null"
+    VERSION_CHECK = <<~'RUBY'.strip
+      exit Gem::Version.new(%%x(%<name>s --version)[/\d+(\.\d+)+/].to_s) >= Gem::Version.new("%<version>s")
+    RUBY
+
+    def program(name, version: nil, install: nil)
+      requirement name.tr("-", "_").to_sym, group: :machine_tools,
+                                            purpose: "#{name}#{" #{version} or newer" if version} is installed",
+                                            check: installed_check(name, version), fix: install
+    end
+
+    def ruby_version
+      named = File.read(File.join(@dir, ".ruby-version")).strip
+      requirement :ruby_version, group: :machine_tools, purpose: "Ruby #{named} is the running Ruby",
+                                 check: %(test "$(ruby -e 'print RUBY_VERSION')" = "#{named}"),
+                                 instruction: "This repo names Ruby #{named} and you are running Ruby #{RUBY_VERSION}."
+    end
+
+    def brewfile
+      requirement :brewfile, group: :machine_tools, purpose: "Every package in the Brewfile is installed",
+                             check: "#{HOMEBREW_ON_PATH} && brew bundle check --file=Brewfile --no-upgrade",
+                             fix: "#{HOMEBREW_ON_PATH} && brew bundle --file=Brewfile --no-upgrade",
+                             instruction: "Without Homebrew, install these yourself: #{brewfile_packages.join(", ")}."
+    end
+
+    private
+
+    def brewfile_packages
+      File.read(File.join(@dir, "Brewfile")).scan(/^\s*(?:brew|cask)\s+["']([^"']+)["']/).flatten
+    end
+
+    def installed_check(name, version)
+      on_path = "command -v #{name} >/dev/null"
+      return on_path unless version
+
+      "#{on_path} && ruby -e '#{format(VERSION_CHECK, name: name, version: version)}'"
+    end
+  end
+end

data/lib/dev_onboarder/overview.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "record"
+require_relative "status"
+
+module DevOnboarder
+  class Overview
+    Group = Data.define(:name, :rows)
+    Row = Data.define(:requirement, :state, :checked_at)
+    FeatureRow = Data.define(:feature, :ready)
+
+    def initialize(requirements:, record:)
+      @requirements = requirements
+      @record = record
+    end
+
+    def groups
+      @requirements.group_by(&:group).map do |name, requirements|
+        Group.new(name: name, rows: requirements.map { |requirement| row_for(requirement) })
+      end
+    end
+
+    def features
+      @requirements.features.map { |feature| FeatureRow.new(feature: feature, ready: ready?(feature)) }
+    end
+
+    def notice
+      count = findings.count { |finding| finding.requirement.feature.nil? }
+      return if count.zero?
+
+      "dev_onboarder: #{count} requirement#{"s" unless count == 1} need#{"s" if count == 1} setup. " \
+        "Run bundle exec dev_onboarder."
+    end
+
+    private
+
+    def ready?(feature)
+      findings.none? { |finding| finding.requirement.feature == feature.name }
+    end
+
+    def row_for(requirement)
+      Row.new(requirement: requirement, state: states.fetch(requirement.key, :met),
+              checked_at: @record.result_for(requirement.key)&.checked_at)
+    end
+
+    def states
+      @states ||= findings.to_h { |finding| [finding.requirement.key, finding.state] }
+    end
+
+    def findings
+      @findings ||= Status.new(requirements: @requirements, record: @record).call
+    end
+  end
+end