dr_talon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0f3e2b0a809454db387d0d2782ea7374d93b8ecab4f68088b43775ea000ec04
+  data.tar.gz: 6505483d2a0afc819e039687ad651cf09a18eb4956ae8b0110546ba3ec9e5ae7
+SHA512:
+  metadata.gz: 5f3aae9f5c691833c3d43e76708855baf876358e2bf890b5bd1ee8563d565d48f0844110164ba672991799cba460971af7b5f1e57086f985333c3cf769c7c36e
+  data.tar.gz: f64e5e291bbae8b123015cc1e4eb504f8dc63ed053221f772ab241c56e5b336cc6c7fd2330d404daa3ed169ab8b04d31ef63224016886569a884484690460611

data/CHANGELOG.md

@@ -0,0 +1,60 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-10-11
+
+First release: `talon`, a Rails-style CLI for DragonRuby Game Toolkit.
+
+### Engines
+
+- `talon engine import <zip|dir>` caches a DragonRuby engine as `VERSION-TIER-PLATFORM`, reading the version from
+  `CHANGELOG-CURR.txt`, the platform from the engine directory, and the tier from the zip name (or `--tier`).
+  Executable bits and the hidden `.dragonruby/` directory are kept; re-importing the same zip is a no-op.
+- `talon engine fetch` downloads the latest engine for this machine: Pro and Indie from dragonruby.org with your
+  account login, the free Jam license from DragonRuby's itch.io page with no account, and Standard with itch.io's
+  butler. The tier defaults to your newest cached engine's.
+- `talon engine login` / `logout` check and save, or delete, a dragonruby.org login in `credentials.yml` (mode 0600;
+  refused if others can read it). `DRAGONRUBY_USERNAME` / `DRAGONRUBY_PASSWORD` take precedence.
+- `talon engine list`, `which`, `uninstall` (asks first, since the cache may be the only copy of an old version).
+- `talon engine use [ENGINE]` pins an engine in `.dragonruby-version` (version and tier only, so it works on every
+  OS) and copies it into the project, cloning files on btrfs/XFS. Installed files are tracked in
+  `.talon/engine.yml`, so switching engines removes exactly those; `mygame/` and your own files are never touched,
+  and differing files stop the install unless `--force`. `talon engine current` shows pinned vs installed.
+
+### Projects
+
+- `talon new NAME` creates a game in DragonRuby's layout from the cached engine's own `mygame/`, with a starter
+  test, RuboCop and Solargraph config, `game_metadata.txt` filled in (`--title`, `--dev-id`, `--dev-title`,
+  `config.yml`, or asked for in a terminal, since `dragonruby-publish` needs them), and `git init` /
+  `bundle install`. It asks whether to commit the engine; if not, a managed `.gitignore` block
+  ignores it and `talon engine use` keeps the block current.
+- `talon new NAME --lib` creates a library (the repository root is the game directory) with `lib/`, a demo
+  `app/main.rb` and a DragonRuby test.
+- `talon new NAME --template talon` creates a game on the [Talon](https://github.com/asimmons91/talon) framework,
+  with Talon vendored, a `Title` scene, a `Spin` component and a test.
+- `talon generate scene|component|prefab NAME` (alias `talon g`) writes Talon code and a DragonRuby test, and adds
+  the require to `app/main.rb`.
+- `talon doctor` checks the pin, the cached and installed engine, dependencies, and `game_metadata.txt`.
+- `config.yml` settings: `default_template`, `dev_id`, `dev_title`.
+
+### Running, testing and building
+
+- `talon run [ARGS...]` runs the game; arguments such as `--record` pass through to `dragonruby`.
+- `talon test [FILES...]` runs each `*_tests.rb` with `dragonruby --test`, headless by default, and reads
+  DragonRuby's output (it always exits 0) to report failures, files that don't load, files with no tests and
+  timeouts, exiting non-zero on any of them.
+- `talon build` packages every platform with `dragonruby-publish --only-package`; `talon serve` serves the newest
+  HTML5 build with `dragonruby-httpd`; `talon clean` deletes `builds/`, `logs/`, `tmp/` and `errors/`.
+
+### Dependencies
+
+- Declared in the game directory's `dependencies.rb` with a Foodchain-compatible DSL (`github`, `git`, `url`,
+  `path`), vendored into `vendor/`, and locked below `__END__` to commit SHAs (or SHA-256s for URLs) with a checksum
+  of the vendored files. Foodchain's ETag locks are replaced on the first install.
+- `talon add SOURCE` (`github:owner/repo`, `git:URL`, `url:URL`, `path:DIR`; `--path`, `--ref`, `--as`) installs a
+  dependency and prints the line to require it; `talon remove`, `talon update`, `talon outdated`.
+- `talon install` restores the pinned engine if it's missing, then the locked dependencies. Locally edited vendored
+  files stop it unless `--force`.
+- GitHub dependencies resolve refs with `git ls-remote` and download one tarball per dependency.
+
+[Unreleased]: https://github.com/asimmons91/dr_talon/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/asimmons91/dr_talon/releases/tag/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"dr_talon" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["austin_simmons@fastmail.com"](mailto:"austin_simmons@fastmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Austin Simmons
+
+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,270 @@
+# dr_talon
+
+`talon` is a Rails-style command line tool for [DragonRuby Game Toolkit](https://dragonruby.org):
+
+- **Engines.** It keeps a cache of DragonRuby versions, downloads new ones, and pins one per project, so every
+  clone runs the same engine.
+- **Projects.** `talon new` scaffolds games and libraries; `talon run`, `test`, `build` and `serve` replace the
+  usual shell scripts. `talon test` reports failures properly, even though DragonRuby itself always exits 0.
+- **Dependencies.** It vendors DragonRuby libraries from GitHub, git, URLs or local paths, locked to exact commits.
+- **Talon.** Optionally, it scaffolds games on the [Talon](https://github.com/asimmons91/talon) framework and
+  generates scenes, components and prefabs.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- git, for GitHub and git dependencies
+- A DragonRuby engine. Any license works, including the free [Jam license](#downloading-engines), which `talon`
+  can download for you.
+
+`talon` is developed and tested on Linux. It handles macOS and Windows paths and engine names, but has seen less
+use there.
+
+## Installation
+
+```bash
+gem install dr_talon
+```
+
+The gem installs a `talon` executable. `talon help` lists every command, and `talon help COMMAND` describes one.
+
+## Quick start
+
+```bash
+talon engine fetch --tier jam      # or: talon engine import ~/Downloads/dragonruby-pro-linux-amd64.zip
+talon new my_game                  # asks whether to commit the engine, and your itch.io name
+cd my_game
+talon run                          # ./dragonruby mygame
+talon test                         # *_tests.rb in mygame/test/ and mygame/tests/ (one starter test)
+talon build                        # package every platform your license allows into builds/
+talon doctor                       # check the engine, dependencies and game metadata
+```
+
+`dragonruby-publish` won't package a game until `game_metadata.txt` names its developer, so `talon new` asks for
+your itch.io username and display name, unless you pass `--dev-id` and `--dev-title` or set them in your
+[config](#configuration). It only asks in a terminal; scripts aren't prompted.
+
+## Engines
+
+DragonRuby only offers its latest release for download, so `talon` keeps a cache of every engine you fetch or
+import. That cache is how you get back to an older version.
+
+```bash
+talon engine import ~/Downloads/dragonruby-pro-linux-amd64.zip   # the zip as downloaded, or an extracted directory
+talon engine list
+talon engine which 7.23            # 7.23, 7.23-pro or 7.23-pro-linux-amd64
+talon engine uninstall 7.23        # asks first; --yes to skip
+```
+
+Engines are identified as `VERSION-TIER-PLATFORM`, for example `7.23-pro-linux-amd64`. The version comes from
+`CHANGELOG-CURR.txt` and the platform from the engine directory name. The tier comes from the zip or directory
+name; pass `--tier pro|indie|standard|jam` if the name doesn't include it.
+
+### Downloading engines
+
+```bash
+talon engine fetch --tier jam        # the free Jam license; no account needed
+talon engine login                   # once: saves your dragonruby.org login (mode 600)
+talon engine fetch                   # latest release, same tier as your newest cached engine
+talon engine fetch --tier indie
+talon engine fetch --tier standard   # via itch.io's butler, after `butler login`
+talon engine logout
+```
+
+- **Jam.** The [Jam license](https://dragonruby.itch.io/dragonruby-gtk/devlog/1620970/dragonruby-jam-license-free-to-all)
+  is free and can be used commercially. It has Standard's full API but only exports to the web. `talon` downloads
+  it the same way the Download button on [DragonRuby's itch.io page](https://dragonruby.itch.io/dragonruby-gtk#demo)
+  does, for Linux (x64 and arm64), macOS and Windows. If itch.io changes that page, download the zip by hand and
+  run `talon engine import`.
+- **Pro and Indie.** These come from dragonruby.org's subscription API with your account's login. `talon` looks
+  for it in `DRAGONRUBY_USERNAME` and `DRAGONRUBY_PASSWORD`, then in the file saved by `talon engine login`, and
+  otherwise asks for it (offering to save it). The saved file holds the password in plain text, so it must be
+  readable only by you; `talon` refuses to use it otherwise.
+- **Standard.** This comes from itch.io through [butler](https://itch.io/docs/butler/).
+
+### Pinning an engine to a project
+
+```bash
+cd my_game
+talon engine use 7.23-pro    # pin in .dragonruby-version and install the engine here
+talon engine use             # after cloning: install whatever is pinned
+talon engine current         # pinned vs installed
+```
+
+DragonRuby expects its engine files next to the game, so `talon engine use` copies the cached engine into the
+project. On btrfs and XFS the files are cloned (reflinked), so each copy takes almost no extra disk space.
+
+- **The pin.** `.dragonruby-version` holds only the version and tier (`7.23-pro`), so it works on every OS.
+- **What gets copied.** Games in DragonRuby's layout (`mygame/app/main.rb`) get every engine file except
+  `mygame/`. Libraries, whose root is the game directory (`app/main.rb`), get just the `dragonruby` binary and
+  `font.ttf`.
+- **Switching versions.** The installed files are listed in `.talon/engine.yml`. Switching engines removes exactly
+  those files and never touches `mygame/` or your other files. If an existing file would be overwritten and
+  differs from the engine's copy, the install stops until you pass `--force`.
+
+## Projects
+
+```bash
+talon new my_game                    # a game, in DragonRuby's layout (mygame/)
+talon new my-lib --lib               # a library: lib/, app/main.rb, test/
+talon new my_game --template talon   # a game on the Talon framework (see below)
+talon help new                       # all options
+```
+
+`talon new` pins the newest cached engine (or `--engine 7.23-pro`) and installs it. It also:
+
+- copies the engine's own sample game into `mygame/`
+- adds a starter test, `mygame/tests/main_tests.rb`
+- fills in `game_metadata.txt`: `gameid` and `gametitle` from the name, and `devid`/`devtitle` from
+  `--dev-id`/`--dev-title`, your config, or by asking
+- adds RuboCop and Solargraph config
+- runs `git init` and `bundle install` (`--skip-git`, `--skip-bundle`)
+
+It asks whether to commit the engine to git, which DragonRuby recommends for private and commercial games. Pass
+`--commit-engine` or `--no-commit-engine` to skip the question. If you don't commit it, the engine's files go in a
+marked section of `.gitignore`, and anyone who clones the project runs `talon install` to restore it. Libraries
+never commit the engine.
+
+`talon doctor` checks that the pinned engine is cached and installed, that dependencies are installed and
+unmodified, and that `game_metadata.txt` is ready to publish.
+
+### Running, testing and building
+
+```bash
+talon run                 # ./dragonruby mygame (or . for libraries); extra args such as --record pass through
+talon test                # every *_tests.rb in test/ and tests/ under the game directory
+talon test tests/player_tests.rb --no-headless --timeout 30 --verbose
+talon build               # dragonruby-publish --only-package: into builds/, never uploaded
+talon serve               # the newest HTML5 build at http://localhost:8080/ (--port)
+talon clean               # delete builds/, logs/, tmp/ and errors/
+```
+
+DragonRuby's test runner always exits 0, so `talon test` reads its output instead. It prints each file's result
+and the details of any failure, and it exits non-zero if a test fails, a file doesn't load, a file has no tests,
+or a run passes `--timeout` (default 120 seconds).
+
+Tests run headless by default, using SDL's dummy video and audio drivers, so no window opens and they work in CI.
+Pass `--no-headless` for tests that need real rendering.
+
+## Dependencies
+
+DragonRuby doesn't load gems, so libraries are vendored into the game: their files are copied into `vendor/` inside
+the game directory and committed with it.
+
+```bash
+talon add github:asimmons91/talon --path lib       # vendor/talon, then prints the require line
+talon add github:someone/tweens --ref v1.2.0 --as tweens
+talon add url:https://example.com/easing.rb
+talon add path:../my_lib/lib                       # a local library, copied on every install
+talon install                                      # after cloning: the engine, then locked dependencies
+talon update [NAME...]                             # move to the newest commit of each ref
+talon outdated
+talon remove tweens
+```
+
+Dependencies are declared in `dependencies.rb` in the game directory (`mygame/` for games). The format is
+compatible with [Foodchain](https://github.com/pvande/foodchain), so existing files keep working:
+
+```ruby
+github "asimmons91/talon", path: "lib", ref: "main", as: "talon"
+github :asimmons91, :talon, "lib", destination: "vendor/talon"   # Foodchain style
+git "https://codeberg.org/someone/lib.git", path: "src", ref: "v2"
+url "https://example.com/easing.rb"
+path "../my_lib/lib"
+
+__END__
+
+# The lines below pin the versions of your installed dependencies.
+...
+```
+
+`talon` owns everything below `__END__`. Each dependency gets one tab-separated line with its key, ref,
+destination, locked commit (or a SHA-256 for `url`), and a checksum of the vendored files.
+
+- `talon install` reproduces exactly those versions.
+- If you edit a vendored file, `talon` notices and won't overwrite it unless you pass `--force`.
+- GitHub dependencies resolve refs with `git ls-remote` and download one tarball each, so they don't use up the
+  GitHub API rate limit. Private repositories need `git:` with an SSH URL instead.
+
+## Talon games
+
+[Talon](https://github.com/asimmons91/talon) is a scene, game object and component framework for DragonRuby.
+`talon` works with any DragonRuby game; Talon support is opt-in.
+
+```bash
+talon new my_game --template talon     # Talon vendored, a Title scene, a Spin component and a test
+talon generate scene MainMenu          # app/scenes/main_menu.rb + tests/scenes/main_menu_tests.rb
+talon generate component Health        # app/components/health.rb + test
+talon g prefab EnemyShip               # app/prefabs/enemy_ship.rb + test (spawn(:ship, EnemyShip))
+```
+
+DragonRuby only loads files that are explicitly required, so generators add each new file's `require` to a
+marked section of `app/main.rb`, ordered components, then prefabs, then scenes. If that section is missing, they
+print the line for you to paste.
+
+Generators only run in projects whose `dependencies.rb` includes Talon. To use them in an existing game, run
+`talon add github:asimmons91/talon --path lib` first.
+
+## Configuration
+
+`~/.config/dr_talon/config.yml` (see below for other platforms):
+
+```yaml
+default_template: bare      # or talon, or lib
+dev_id: my_itchio_username  # devid in game_metadata.txt
+dev_title: My Name          # devtitle in game_metadata.txt
+```
+
+### Where talon keeps its files
+
+| | Linux | macOS | Windows |
+|---|---|---|---|
+| Engines (data) | `$XDG_DATA_HOME/dr_talon` (`~/.local/share/dr_talon`) | `~/Library/Application Support/dr_talon` | `%LOCALAPPDATA%\dr_talon` |
+| Downloads (cache) | `$XDG_CACHE_HOME/dr_talon` (`~/.cache/dr_talon`) | `~/Library/Caches/dr_talon` | `%LOCALAPPDATA%\dr_talon\cache` |
+| Config and login | `$XDG_CONFIG_HOME/dr_talon` (`~/.config/dr_talon`) | `~/Library/Application Support/dr_talon` | `%APPDATA%\dr_talon` |
+
+On macOS, explicitly set `XDG_*` variables take precedence. Setting `DR_TALON_HOME` puts everything under that one
+directory (`data/`, `cache/`, `config/`).
+
+## Development
+
+```bash
+bin/setup                # install dependencies
+bundle exec rake         # tests + standardrb
+bundle exec exe/talon    # try the CLI from the checkout
+```
+
+The tests never need a real DragonRuby engine or the network. They build small fake engines, use local git
+repositories in place of GitHub, and run HTTP against a local server. Real DragonRuby output is kept as fixtures in
+`test/fixtures/dragonruby/`. The design and its decisions are in [PLAN.md](PLAN.md).
+
+### Releasing
+
+Add changes to the `## [Unreleased]` section of `CHANGELOG.md` as you go. To release:
+
+```bash
+bundle exec rake release:prepare[minor]   # or major, patch, or an explicit version like 1.2.3
+git push origin main v0.2.0               # the command it prints
+```
+
+`release:prepare` runs the tests, bumps `version.rb` and `Gemfile.lock`, moves the Unreleased notes under a dated
+heading, and commits and tags the release. The first release is `rake release:prepare[0.1.0]`: the current
+version, since it was never tagged.
+
+Pushing the tag runs `.github/workflows/release.yml`. It checks that the tag, version and changelog agree, runs
+the tests, publishes the gem to RubyGems.org with [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/),
+and creates the GitHub release from that version's changelog notes.
+
+One-time setup: on RubyGems.org, add a trusted publisher for this repository with the workflow `release.yml` and the
+environment `release`. Use a "pending" trusted publisher, since the gem has never been pushed.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/asimmons91/dr_talon. This project is
+intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the
+[code of conduct](https://github.com/asimmons91/dr_talon/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+DragonRuby Game Toolkit itself is commercial software under its own license; `talon` doesn't include any part of it.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/exe/talon

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "dr_talon"
+
+DrTalon::CLI.start(ARGV)

data/lib/dr_talon/cli/engine.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "thor"
+require "tmpdir"
+
+module DrTalon
+  class CLI < Thor
+    # +talon engine ...+: manage the cache of DragonRuby engines.
+    class Engine < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      desc "import PATH", "Add a DragonRuby zip (or an extracted engine directory) to the cache"
+      long_desc <<~DESC
+        Copies a DragonRuby distribution into talon's engine cache. PATH can be the
+        zip as downloaded or a directory it was already extracted to.
+
+        The version is read from CHANGELOG-CURR.txt and the platform from the
+        engine directory name. The tier is read from the zip or directory name
+        (e.g. dragonruby-pro-linux-amd64.zip); pass --tier when it isn't there.
+
+        DragonRuby only offers its latest release for download, so import every
+        version you may want to go back to.
+      DESC
+      method_option :tier, enum: DrTalon::Engine::TIERS, desc: "License tier, when the file name doesn't say"
+      method_option :platform, desc: "Engine platform, e.g. linux-amd64, when the directory name doesn't say"
+      method_option :force, type: :boolean, default: false, desc: "Replace a cached engine with the same id"
+      def import(path)
+        result = with_errors do
+          importer = DrTalon::Engine::Importer.new(store, tier: options[:tier], platform: options[:platform], force: options[:force])
+          importer.import(path)
+        end
+        installation = result.installation
+
+        case result.status
+        when :unchanged then say "#{installation.id} is already cached from the same zip."
+        when :replaced then say "Replaced #{installation.id} at #{installation.path}"
+        else say "Imported #{installation.id} to #{installation.path}"
+        end
+      end
+
+      desc "fetch", "Download the latest engine and add it to the cache"
+      long_desc <<~DESC
+        Downloads the newest DragonRuby release for this machine and imports it.
+
+        Jam (DragonRuby's free license: Standard's API, web export only) comes
+        from the free downloads on DragonRuby's itch.io page; no account needed.
+
+        Pro and Indie come from dragonruby.org with your account's username and
+        password, taken from DRAGONRUBY_USERNAME and DRAGONRUBY_PASSWORD, from
+        `talon engine login`, or asked for.
+
+        Standard comes from itch.io with butler (https://itch.io/docs/butler/),
+        after `butler login`.
+
+        The tier defaults to that of your newest cached engine. DragonRuby only
+        offers its latest release, so fetching regularly is how older versions
+        stay available in the cache.
+      DESC
+      method_option :tier, enum: DrTalon::Engine::TIERS, desc: "License tier (default: your newest cached engine's)"
+      method_option :keep_zip, type: :boolean, default: false, desc: "Keep the downloaded zip in talon's cache directory"
+      def fetch
+        tier = options[:tier] || store.latest_native&.tier ||
+          raise(Thor::Error, "Pass --tier #{DrTalon::Engine::TIERS.join("|")} (no cached engine to take it from). " \
+            "Jam is free and needs no account.")
+
+        result = with_errors { fetch_and_import(tier) }
+        installation = result.installation
+
+        if result.status == :unchanged
+          say "#{installation.id} is already cached; it's the latest #{tier} release."
+        else
+          say "Fetched #{installation.id} to #{installation.path}", :green
+          say "Use it in a project with `talon engine use #{installation.version}-#{installation.tier}`."
+        end
+      end
+
+      desc "login", "Save a dragonruby.org login for fetching Pro/Indie engines"
+      long_desc <<~DESC
+        Asks for your dragonruby.org username and password, checks them against
+        the download API, and saves them to credentials.yml in talon's config
+        directory, readable only by you (mode 0600). The password is stored in
+        plain text there; DRAGONRUBY_USERNAME and DRAGONRUBY_PASSWORD are an
+        alternative that stores nothing.
+      DESC
+      method_option :tier, enum: %w[pro indie], default: "pro", desc: "Tier to check the login against"
+      def login
+        credentials = ask_credentials
+        with_errors { DrTalon::Engine::Fetchers::DragonRubyAPI.new(options[:tier]).verify(credentials) }
+        credentials.save(Paths.new.credentials_file)
+        say "Saved the login for #{credentials.username} to #{Paths.new.credentials_file} (mode 600)."
+      end
+
+      desc "logout", "Delete the saved dragonruby.org login"
+      def logout
+        path = Paths.new.credentials_file
+        say DrTalon::Credentials.delete(path) ? "Deleted #{path}." : "No saved login at #{path}."
+      end
+
+      desc "list", "List cached engines"
+      def list
+        installations = with_errors { store.installations }
+
+        if installations.empty?
+          say "No engines cached yet. Add one with `talon engine import <zip>`."
+          return
+        end
+
+        pinned = pinned_installation
+        rows = installations.map do |installation|
+          marker = (installation == pinned) ? "*" : ""
+          [marker, installation.id, installation.version, installation.tier, installation.platform, installation.built_on.to_s]
+        end
+        print_table([["", "ID", "VERSION", "TIER", "PLATFORM", "BUILT"], *rows])
+        say "\n* pinned by this project" if pinned
+      end
+
+      desc "which [ENGINE]", "Print the path of a cached engine (default: this project's pin)"
+      def which(spec = nil)
+        say with_errors { spec ? store.find(spec) : store.find_native(required_pin) }.path
+      end
+
+      desc "use [ENGINE]", "Pin an engine for this project and install it here"
+      long_desc <<~DESC
+        Writes ENGINE (e.g. 7.23-pro) to .dragonruby-version and copies the cached
+        engine into the project, replacing the previously installed one. Without
+        ENGINE, installs the version already pinned, e.g. after cloning.
+
+        Only files talon installed before are removed. Files in mygame/ are never
+        touched, and other project files that differ from the engine's stop the
+        install unless you pass --force.
+
+        Run this in a DragonRuby project: a directory with .dragonruby-version,
+        mygame/app/main.rb (full layout) or app/main.rb (game-only layout).
+      DESC
+      method_option :force, type: :boolean, default: false, desc: "Overwrite project files that differ from the engine's"
+      def use(spec = nil)
+        project = with_errors { Project.locate }
+        installation, previous, result = with_errors do
+          requested = spec ? DrTalon::Engine::Spec.parse(spec) : required_pin(project)
+          installation = store.find_native(requested, default_tier: project.pin&.tier)
+          materializer = DrTalon::Engine::Materializer.new(project)
+          previous = materializer.manifest&.engine
+          result = materializer.install(installation, force: options[:force])
+          DrTalon::Engine::GitIgnore.refresh(project.path(".gitignore"), materializer.manifest.files)
+          [installation, previous, result]
+        end
+
+        repinned = project.pin&.then { |pin| "#{pin.version}-#{pin.tier}" } != "#{installation.version}-#{installation.tier}"
+        project.pin!(installation) if repinned
+
+        details = ["#{result.copied} files"]
+        details << "#{result.cloned} as reflinks" if result.cloned.positive?
+        if previous == installation.id
+          say "Reinstalled #{installation.id} into #{project.root} (#{details.join(", ")})"
+        else
+          details << "replaced #{previous}" if previous
+          say "Installed #{installation.id} into #{project.root} (#{details.join(", ")})"
+        end
+        say "Pinned #{installation.version}-#{installation.tier} in #{Project::PIN_FILE}" if repinned
+      end
+
+      desc "current", "Show the engine this project pins and the one installed"
+      def current
+        project = with_errors { Project.locate }
+        pin = with_errors { project.pin }
+        manifest = with_errors { DrTalon::Engine::Materializer.new(project).manifest }
+
+        say "Pinned:    #{pin || "nothing (no #{Project::PIN_FILE})"}"
+        say "Installed: #{manifest&.engine || "nothing"}"
+      end
+
+      desc "uninstall ENGINE", "Remove an engine from the cache"
+      long_desc <<~DESC
+        Deletes a cached engine. DragonRuby only offers its latest release for
+        download, so the cache may be your only copy of older versions; you're
+        asked to confirm unless you pass --yes.
+      DESC
+      method_option :yes, type: :boolean, aliases: "-y", default: false, desc: "Don't ask for confirmation"
+      def uninstall(spec)
+        installation = with_errors { store.find(spec) }
+
+        unless options[:yes] || yes?("Remove #{installation.id}? The cache may be your only copy of this version. [y/N]")
+          say "Kept #{installation.id}."
+          return
+        end
+
+        store.remove(installation)
+        say "Removed #{installation.id}."
+      end
+
+      no_commands do
+        def store
+          @store ||= DrTalon::Engine::Store.new(Paths.new.engines_dir)
+        end
+
+        def required_pin(project = Project.find)
+          pin = project&.pin
+          return pin if pin
+
+          raise DrTalon::Error, "No engine given and no #{Project::PIN_FILE} found. Pass one, e.g. `7.23-pro`."
+        end
+
+        def pinned_installation
+          pin = Project.find&.pin
+          pin && store.find_native(pin)
+        rescue DrTalon::Error
+          nil
+        end
+
+        def fetch_and_import(tier)
+          fetcher = DrTalon::Engine::Fetchers.for(tier)
+          credentials = fetcher.credentials? ? DrTalon::Credentials.lookup || ask_credentials(offer_to_save: true) : nil
+          say "Downloading the latest #{tier} engine…" unless $stdout.tty?
+
+          path = begin
+            fetcher.fetch(credentials: credentials) { |received, total| show_progress(received, total) }
+          rescue DrTalon::HTTP::Unauthorized
+            source = {env: "DRAGONRUBY_USERNAME/DRAGONRUBY_PASSWORD", file: Paths.new.credentials_file, prompt: "what you typed"}
+            raise DrTalon::Error, "dragonruby.org rejected the login from #{source.fetch(credentials.source)}. " \
+              "Check it, or run `talon engine login`."
+          ensure
+            finish_progress
+          end
+
+          begin
+            DrTalon::Engine::Importer.new(store, tier: tier).import(path)
+          ensure
+            FileUtils.rm_rf(path) unless options[:keep_zip] && File.file?(path)
+          end
+        end
+
+        def ask_credentials(offer_to_save: false)
+          unless $stdin.tty?
+            raise Thor::Error, "No dragonruby.org login. Set #{DrTalon::Credentials::ENV_USERNAME} and " \
+              "#{DrTalon::Credentials::ENV_PASSWORD}, or run `talon engine login` in a terminal."
+          end
+
+          username = ask("dragonruby.org username:").to_s.strip
+          password = ask("dragonruby.org password:", echo: false).to_s
+          say ""
+          raise Thor::Error, "A username and password are needed." if username.empty? || password.empty?
+
+          credentials = DrTalon::Credentials.new(username: username, password: password, source: :prompt)
+          if offer_to_save && yes?("Save this login to #{Paths.new.credentials_file} (mode 600)? [y/N]")
+            credentials.save(Paths.new.credentials_file)
+          end
+          credentials
+        end
+
+        def show_progress(received, total)
+          return unless $stdout.tty?
+
+          @progress_shown = true
+          amount = total ? "#{received * 100 / total}% of #{total / 1_048_576} MB" : "#{received / 1_048_576} MB"
+          print "\rDownloading… #{amount}   "
+        end
+
+        def finish_progress
+          puts if @progress_shown
+          @progress_shown = false
+        end
+
+        def with_errors
+          yield
+        rescue DrTalon::Error => e
+          raise Thor::Error, e.message
+        end
+      end
+    end
+  end
+end