riffer-rig 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e833f2a4dfe0b87598e2be9d585f3cb772562ab39a2dd528684a38dca87f63ab
-  data.tar.gz: f469b328103a49e52773c0073e02d8c2fbd06d8cf6779daa50c09b49ab2eba8e
+  metadata.gz: 5b5a8d6de921c08c1ddb5caa12c5e22e0b3a68f7d26160b6fc732b647209b963
+  data.tar.gz: a37ce48ed7e46d9bca9a00db9a46411ecc0187550d58627879e9d97d36789650
 SHA512:
-  metadata.gz: 696e8b92a7c1b7a3b71e1f628894e89aed725fbe072dba712d94df277fc5730b06d74def094445b02842d0849409b7900038aedf5d65f29f5416d1450a5b5121
-  data.tar.gz: 3dc42ac6e625d292462e00119bd7b3c7a8d1f23ad3c4f66763fff96cbfc3328f962dca67bdc4613e884ba81a6e3f61d9af86f1ba1d8bbd16e0f3caa307ca453c
+  metadata.gz: b2b6f88978aa64314fb2b420047f97332090c3f8f699caa01564cd1ebf78dd5d862a22dca60e8e0734db647e2506aafbc5bd4de7a1ee1d800ee6a6edf1688b74
+  data.tar.gz: 3d6a59d2a2fa892430ddec4682c29fcc934d8568a3827ecf99546ea064b9ec246a1c5dbd5e96a0848328017408d17be91944bd2e84fd1eaf65dcc7707cf74389

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [0.6.0](https://github.com/bottrall/riffer-rig/compare/v0.5.0...v0.6.0) (2026-09-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* the flat `{"anthropic": "sk-..."}` auth.json shape is no longer read, with no migration. Stored keys must be re-entered or rewritten as `{"anthropic": {"type": "api_key", "api_key": "sk-..."}}`.
+* Riffer::Rig::Host is removed. A host subclasses Riffer::Rig::Hosts::Base and implements all five methods; the null host is Riffer::Rig::Hosts::Null.
+
+### Features
+
+* add the rig event vocabulary and close ([#179](https://github.com/bottrall/riffer-rig/issues/179)) ([35bfa6e](https://github.com/bottrall/riffer-rig/commit/35bfa6e5dc1dc9825fd03843a4e69ec24e675b66))
+* cancel a running turn from any thread ([#186](https://github.com/bottrall/riffer-rig/issues/186)) ([ec68188](https://github.com/bottrall/riffer-rig/commit/ec68188cc7dbcaf0cd56dd41d83cda216661fbe7))
+* **deps:** upgrade riffer to 0.49.0 ([#188](https://github.com/bottrall/riffer-rig/issues/188)) ([821413f](https://github.com/bottrall/riffer-rig/commit/821413f5af65bfcb159ddad532deb3c15779112d))
+* named prompt sections rendered every turn ([#184](https://github.com/bottrall/riffer-rig/issues/184)) ([d190a07](https://github.com/bottrall/riffer-rig/commit/d190a07dfa99764b82bba00745a07e7738c3532a))
+* provider setup table and typed auth.json credentials ([#185](https://github.com/bottrall/riffer-rig/issues/185)) ([0a30c35](https://github.com/bottrall/riffer-rig/commit/0a30c357793716acfabcd1ddd41ea9f98c8a6a8f))
+* store credentials on the Runtime ([#181](https://github.com/bottrall/riffer-rig/issues/181)) ([474a515](https://github.com/bottrall/riffer-rig/commit/474a51586011e413482f0275a7abd3a542e91914))
+
+
+### Code Refactoring
+
+* make the host contract the abstract Hosts::Base ([#183](https://github.com/bottrall/riffer-rig/issues/183)) ([3fd4f14](https://github.com/bottrall/riffer-rig/commit/3fd4f14a193d546ae06e00776f209a52c0593854))
+
+## [0.5.0](https://github.com/bottrall/riffer-rig/compare/v0.4.0...v0.5.0) (2026-09-19)
+
+
+### Features
+
+* add ask, max_steps and riffer response ([#178](https://github.com/bottrall/riffer-rig/issues/178)) ([948d753](https://github.com/bottrall/riffer-rig/commit/948d75354a7d0a5a9d35055b7d890dea9e51f1a1))
+* add Runtime with a per-instance agent, base prompt and tool seam ([#160](https://github.com/bottrall/riffer-rig/issues/160)) ([97019ca](https://github.com/bottrall/riffer-rig/commit/97019ca6f80c95bcf22e443652f1d90d453d02de))
+* type IO streams and JSON boundaries, dropping explicit untyped ([#174](https://github.com/bottrall/riffer-rig/issues/174)) ([22407be](https://github.com/bottrall/riffer-rig/commit/22407befc471d1fbbe14188456ee1ce248ddc4c7))
+
+
+### Bug Fixes
+
+* drain smoother backlog before every animator restart ([#177](https://github.com/bottrall/riffer-rig/issues/177)) ([3126155](https://github.com/bottrall/riffer-rig/commit/3126155fdeba3de2ab2b9905b7e7de55593de834))
+* drop invalid ? optional markers from rbs-inline annotations ([#171](https://github.com/bottrall/riffer-rig/issues/171)) ([60030bf](https://github.com/bottrall/riffer-rig/commit/60030bf7ca930e9d35cbd8c2e3a8ae8ae1692830))
+
 ## [0.4.0](https://github.com/bottrall/riffer-rig/compare/v0.3.0...v0.4.0) (2026-09-13)
 
 

data/README.md

@@ -28,17 +28,54 @@ riffer
 
 ### Authentication
 
-`riffer-rig` talks to Anthropic. Provide your API key in either of two ways:
+`riffer-rig` talks to the provider named by the model's prefix — `anthropic/claude-sonnet-4-6`, the default, means Anthropic. Provide that provider's credentials in either of two ways:
 
-- Set the `ANTHROPIC_API_KEY` environment variable, or
-- Run `riffer` and paste your key when prompted on first launch. It is saved to `~/.riffer/auth.json` (file permissions `600`) for subsequent runs.
+- Set the provider's environment variables, or
+- Run `riffer` and paste each missing value when prompted on first launch. Secrets are saved to `~/.riffer/auth.json` (file permissions `600`); plain values such as an endpoint or region are saved to the `providers` block in `~/.riffer/settings.json`.
 
-Create a key at https://console.anthropic.com/settings/keys.
+Each value resolves on its own: environment variable first, then the stored value, then a provider-specific fallback (the AWS shared config for the Bedrock region), then the prompt. Optional values are never prompted for.
+
+| Provider         | Environment variables                                                     | Guide                                              |
+| ---------------- | ------------------------------------------------------------------------- | -------------------------------------------------- |
+| `anthropic`      | `ANTHROPIC_API_KEY`                                                       | [Anthropic](docs/PROVIDERS.md#anthropic)           |
+| `openai`         | `OPENAI_API_KEY`; optional `OPENAI_BASE_URL`                              | [OpenAI](docs/PROVIDERS.md#openai)                 |
+| `gemini`         | `GEMINI_API_KEY`                                                          | [Gemini](docs/PROVIDERS.md#gemini)                 |
+| `openrouter`     | `OPENROUTER_API_KEY`                                                      | [OpenRouter](docs/PROVIDERS.md#openrouter)         |
+| `azure_openai`   | `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`                           | [Azure OpenAI](docs/PROVIDERS.md#azure-openai)     |
+| `amazon_bedrock` | `AWS_REGION` or `AWS_DEFAULT_REGION`; optional `AWS_BEARER_TOKEN_BEDROCK` | [Amazon Bedrock](docs/PROVIDERS.md#amazon-bedrock) |
+
+`auth.json` holds one typed entry per provider, and a stored secret may be a literal, a `$ENV_VAR` reference or a `!shell command` whose stdout is the secret:
+
+```json
+{
+  "anthropic": { "type": "api_key", "api_key": "sk-ant-…" },
+  "openai": { "type": "api_key", "api_key": "!security find-generic-password -s openai -w" }
+}
+```
+
+The flat `{"anthropic": "sk-…"}` shape earlier versions wrote is no longer read; paste the key again when prompted. [Providers](docs/PROVIDERS.md) has the full format.
 
 ### Configuration
 
-- `RIFFER_MODEL` — override the default model.
 - `AGENTS.md` — if present, an `AGENTS.md` in the current working directory and/or a global `~/.riffer/AGENTS.md` is loaded as additional context.
+- `~/.riffer/settings.json` — optional user settings. Every key is optional:
+
+  ```json
+  {
+    "model": "anthropic/claude-sonnet-4-6",
+    "reasoning": "low",
+    "models": {
+      "anthropic/claude-sonnet-4-6": {
+        "input": 3.0,
+        "output": 15.0,
+        "cache_write": 3.75,
+        "cache_read": 0.3
+      }
+    }
+  }
+  ```
+
+  `models` holds pricing in USD per million tokens; a model without an entry shows no cost. `reasoning` is translated to the provider's own parameter — Anthropic accepts `low`, `medium`, `high`, `xhigh` and `max`; OpenAI and OpenRouter accept `low`, `medium`, `high` and `xhigh`. Omitting it, or supplying an unrecognised value, leaves the model's default reasoning behaviour unchanged.
 
 ## Development
 
@@ -62,7 +99,7 @@ PR titles are [conventional commits](https://www.conventionalcommits.org/) and a
 
 [release-please](https://github.com/googleapis/release-please) keeps a release PR open that bumps `lib/riffer/rig/version.rb` and writes `CHANGELOG.md`. Merging that PR tags `vX.Y.Z`, creates the GitHub Release and publishes the gem to RubyGems.org through Trusted Publishing; nothing is pushed by hand.
 
-riffer is pinned to one minor (`~> 0.45.0`) because its 0.x minors may break. When Dependabot opens the riffer bump, retitle it `feat(deps):` or `fix(deps):` before merging so it releases and appears in the changelog.
+riffer is pinned to one minor (`~> 0.49.0`) because its 0.x minors may break. When Dependabot opens the riffer bump, retitle it `feat(deps):` or `fix(deps):` before merging so it releases and appears in the changelog.
 
 ## Contributing
 

data/lib/riffer/rig/cli.rb

@@ -5,27 +5,22 @@ require 'io/console'
 module Riffer::Rig::CLI
   extend self
 
-  PROVIDER_URLS = {
-    'anthropic' => 'https://console.anthropic.com/settings/keys',
-    'openai' => 'https://platform.openai.com/api-keys',
-    'gemini' => 'https://aistudio.google.com/app/apikey',
-    'openrouter' => 'https://openrouter.ai/keys'
-  }.freeze #: Hash[String, String]
-
-  # @rbs output: untyped
-  # @rbs input: untyped
+  # @rbs output: IO
+  # @rbs input: IO
+  # @rbs model: String
+  # @rbs env: Riffer::Rig::Env
   # @rbs return: Integer
-  def start(output: $stdout, input: $stdin)
-    theme = Riffer::Rig::UI::Theme.for(output)
+  def start(output: $stdout, input: $stdin, model: Riffer::Rig::Settings.model, env: Riffer::Rig::Env.new)
+    theme = Riffer::Rig::UI::Theme.for(output, env:)
 
-    model    = Riffer::Rig::Settings.model
     provider = Riffer::Rig::Settings.provider_for(model)
 
-    api_key = (provider && Riffer::Rig::Credentials.api_key_for(provider)) ||
-              onboard(provider, theme, output:, input:)
-    return 1 if api_key.nil?
+    if provider
+      values = credentials_for(provider, theme, output:, input:, env:)
+      return 1 if values.nil?
 
-    configure_provider(provider, api_key)
+      Riffer::Rig::Credentials.apply(provider, values)
+    end
 
     agent    = Riffer::Rig::CodingAgent.new
     animator = Riffer::Rig::UI::Animator.new(io: output, theme:)
@@ -41,51 +36,60 @@ module Riffer::Rig::CLI
 
   private
 
-  # @rbs provider: String?
-  # @rbs api_key: String
-  # @rbs return: void
-  def configure_provider(provider, api_key)
-    case provider
-    when 'anthropic'  then Riffer.configure { |c| c.anthropic.api_key  = api_key }
-    when 'openai'     then Riffer.configure { |c| c.openai.api_key     = api_key }
-    when 'gemini'     then Riffer.configure { |c| c.gemini.api_key     = api_key }
-    when 'openrouter' then Riffer.configure { |c| c.openrouter.api_key = api_key }
-    end
+  # @rbs provider: String
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs output: IO
+  # @rbs input: IO
+  # @rbs env: Riffer::Rig::Env
+  # @rbs return: Hash[Symbol, String]?
+  def credentials_for(provider, theme, output:, input:, env:)
+    resolution = Riffer::Rig::Credentials.resolve(provider, host: Riffer::Rig::Hosts::Null.new, env:)
+    return resolution.values if resolution.missing.empty?
+
+    onboard(provider, resolution, theme, output:, input:)
   end
 
-  # @rbs provider: String?
+  # @rbs provider: String
+  # @rbs resolution: Riffer::Rig::Credentials::Resolution
   # @rbs theme: Riffer::Rig::UI::Theme
-  # @rbs output: untyped
-  # @rbs input: untyped
-  # @rbs return: String?
-  def onboard(provider, theme, output:, input:)
-    url  = (provider && PROVIDER_URLS[provider]) || 'your provider'
-    name = provider ? provider.capitalize : 'provider'
+  # @rbs output: IO
+  # @rbs input: IO
+  # @rbs return: Hash[Symbol, String]?
+  def onboard(provider, resolution, theme, output:, input:)
+    setup = Riffer::Rig::ProviderSetup.for(provider)
+    missing = setup.fields.select { |field| resolution.missing.include?(field.name) }
 
     output.puts(theme.cyan('♪ welcome to riffer-rig ♪'))
-    output.puts(theme.grey("No #{name} API key found. Create one at #{url}"))
-    output.print("#{theme.pink('›')} Paste your #{name} API key #{theme.grey('(hidden)')}: ")
+    output.puts(theme.grey("No #{provider} credentials found. Create them at #{setup.url || 'your provider'}"))
 
-    key = read_secret(input).to_s.strip
-    output.puts
-
-    if key.empty?
-      output.puts(theme.grey("No key entered. Set #{env_var_for(provider)} or re-run riffer to try again."))
+    answers = missing.to_h { |field| [field.name, prompt(provider, field, theme, output:, input:)] }
+    if answers.values.any?(&:empty?)
+      env_vars = missing.flat_map(&:env).join(', ')
+      output.puts(theme.grey("Nothing entered. Set #{env_vars} or re-run riffer to try again."))
       return nil
     end
 
-    Riffer::Rig::Credentials.save_api_key(provider, key) if provider
-    output.puts(theme.grey("Saved to #{Riffer::Rig::Credentials::PATH} (permissions 600)."))
-    key
+    Riffer::Rig::Credentials.store(provider, answers)
+    output.puts(theme.grey("Saved under #{File.dirname(Riffer::Rig::Credentials::PATH)} (auth.json permissions 600)."))
+    resolution.values.merge(answers)
   end
 
-  # @rbs provider: String?
+  # @rbs provider: String
+  # @rbs field: Riffer::Rig::ProviderSetup::Field
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs output: IO
+  # @rbs input: IO
   # @rbs return: String
-  def env_var_for(provider)
-    (provider && Riffer::Rig::Credentials::PROVIDER_ENV_VARS[provider]) || 'the appropriate API key env var'
+  def prompt(provider, field, theme, output:, input:)
+    hint = field.secret ? " #{theme.grey('(hidden)')}" : ''
+    output.print("#{theme.pink('›')} Paste your #{provider} #{field.name}#{hint}: ")
+
+    answer = (field.secret ? read_secret(input) : input.gets).to_s.strip
+    output.puts
+    answer
   end
 
-  # @rbs input: untyped
+  # @rbs input: IO
   # @rbs return: String?
   def read_secret(input)
     return input.noecho(&:gets) if input.respond_to?(:noecho) && input.tty?

data/lib/riffer/rig/coding_agent.rb

@@ -12,12 +12,7 @@ class Riffer::Rig::CodingAgent < Riffer::Agent
   model Riffer::Rig::Settings.model
   model_options Riffer::Rig::Settings.model_options
 
-  uses_tools [
-    Riffer::Rig::Tools::Read,
-    Riffer::Rig::Tools::Write,
-    Riffer::Rig::Tools::Edit,
-    Riffer::Rig::Tools::Bash
-  ]
+  uses_tools [Riffer::Rig::Tools::Read, Riffer::Rig::Tools::Write, Riffer::Rig::Tools::Edit, Riffer::Rig::Tools::Bash]
 
   skills do
     backend(->(_ctx) { Riffer::Skills::FilesystemBackend.new(GLOBAL_SKILLS_DIR, PROJECT_SKILLS_DIR.call) })

data/lib/riffer/rig/credentials/resolution.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Credentials::Resolution
+  # @dynamic values, missing
+  attr_reader :values #: Hash[Symbol, String]
+  attr_reader :missing #: Array[Symbol]
+
+  # @rbs values: Hash[Symbol, String]
+  # @rbs missing: Array[Symbol]
+  # @rbs return: void
+  def initialize(values:, missing:)
+    @values = values.freeze
+    @missing = missing.freeze
+    freeze
+  end
+end

data/lib/riffer/rig/credentials.rb

@@ -2,88 +2,179 @@
 
 require 'json'
 require 'fileutils'
+require 'open3'
 
-# Reads and writes API keys for each supported provider in
-# <tt>~/.riffer/auth.json</tt>.
-#
-# Keys are stored under the provider name, e.g.:
-#
-#   {
-#     "anthropic": "sk-ant-...",
-#     "openai": "sk-...",
-#     "gemini": "...",
-#     "openrouter": "sk-or-..."
-#   }
-#
-# The environment variable checked per provider:
-#
-#   anthropic  → ANTHROPIC_API_KEY
-#   openai     → OPENAI_API_KEY
-#   gemini     → GEMINI_API_KEY
-#   openrouter → OPENROUTER_API_KEY
-#
 module Riffer::Rig::Credentials
   extend self
 
   PATH = File.expand_path('~/.riffer/auth.json') #: String
 
-  PROVIDER_ENV_VARS = {
-    'anthropic' => 'ANTHROPIC_API_KEY',
-    'openai' => 'OPENAI_API_KEY',
-    'gemini' => 'GEMINI_API_KEY',
-    'openrouter' => 'OPENROUTER_API_KEY'
-  }.freeze #: Hash[String, String]
-
-  # Returns the API key for +provider+, checking the environment variable first,
-  # then the stored file. Returns +nil+ if no key is available.
-  #
-  # @rbs provider: String?
-  # @rbs path: String
-  # @rbs return: String?
-  def api_key_for(provider, path: PATH)
-    env_var = provider && PROVIDER_ENV_VARS[provider]
-    key = env_var && ENV.fetch(env_var, nil).then { |v| v unless v.nil? || v.strip.empty? }
-    key || key_from_file(provider, path)
+  ENTRY_TYPE = 'api_key'
+
+  # @rbs identifier: String | Symbol
+  # @rbs host: Riffer::Rig::Hosts::Base
+  # @rbs setup: Riffer::Rig::ProviderSetup
+  # @rbs env: Riffer::Rig::Env
+  # @rbs auth_path: String
+  # @rbs settings_path: String
+  # @rbs return: Resolution
+  def resolve(
+    identifier,
+    host:,
+    setup: Riffer::Rig::ProviderSetup.for(identifier),
+    env: Riffer::Rig::Env.new,
+    auth_path: PATH,
+    settings_path: Riffer::Rig::Settings::PATH
+  )
+    secrets = stored_secrets(identifier, auth_path)
+    plain = Riffer::Rig::Settings.provider_fields(identifier.to_s, path: settings_path)
+    found = setup.fields.to_h do |field|
+      [field.name, env.value_for(field) || stored_value(field, secrets, plain, env) || field.fallback&.call]
+    end.compact
+    required = setup.fields.select(&:required)
+    answers = ask_for(required.reject { |field| found.key?(field.name) }, identifier, host)
+    store(identifier, answers, setup:, auth_path:, settings_path:)
+
+    values = found.merge(answers)
+    Resolution.new(values:, missing: required.map(&:name) - values.keys)
   end
 
-  # Saves an API key for +provider+ to the auth file with 0600 permissions.
-  #
-  # @rbs provider: String
-  # @rbs key: String
-  # @rbs path: String
-  # @rbs return: String
-  def save_api_key(provider, key, path: PATH)
-    FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
-    data = read(path).tap { |h| h[provider] = key }
-    File.open(path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |file|
-      file.write(JSON.pretty_generate(data))
+  # @rbs identifier: String | Symbol
+  # @rbs values: Hash[Symbol, String]
+  # @rbs config: Riffer::Config
+  # @rbs return: void
+  def apply(identifier, values, config: Riffer.config)
+    return unless Riffer::Rig::ProviderSetup[identifier]
+
+    provider_config = config.public_send(identifier)
+    values.each { |name, value| provider_config.public_send(:"#{name}=", value) }
+  end
+
+  # @rbs identifier: String | Symbol
+  # @rbs values: Hash[Symbol, String]
+  # @rbs setup: Riffer::Rig::ProviderSetup
+  # @rbs auth_path: String
+  # @rbs settings_path: String
+  # @rbs return: void
+  def store(
+    identifier,
+    values,
+    setup: Riffer::Rig::ProviderSetup.for(identifier),
+    auth_path: PATH,
+    settings_path: Riffer::Rig::Settings::PATH
+  )
+    secret_names = setup.fields.select(&:secret).map { |field| field.name.to_s }
+    fields = values.transform_keys(&:to_s)
+    secrets = fields.slice(*secret_names)
+    plain = fields.except(*secret_names)
+
+    unless secrets.empty?
+      entries = read_auth(auth_path).merge(identifier.to_s => secrets) do |_identifier, stored, given|
+        stored.merge(given)
+      end
+      write_auth(auth_path, entries)
     end
-    key
+    Riffer::Rig::Settings.store_provider(identifier.to_s, plain, path: settings_path) unless plain.empty?
+  end
+
+  # @rbs identifier: String | Symbol
+  # @rbs auth_path: String
+  # @rbs settings_path: String
+  # @rbs return: void
+  def remove(identifier, auth_path: PATH, settings_path: Riffer::Rig::Settings::PATH)
+    entries = read_auth(auth_path)
+    write_auth(auth_path, entries.except(identifier.to_s)) if entries.key?(identifier.to_s)
+    Riffer::Rig::Settings.remove_provider(identifier.to_s, path: settings_path)
+  end
+
+  # @rbs identifier: String | Symbol
+  # @rbs setup: Riffer::Rig::ProviderSetup
+  # @rbs env: Riffer::Rig::Env
+  # @rbs auth_path: String
+  # @rbs return: :env | :stored | :chain | :missing
+  def status(identifier, setup: Riffer::Rig::ProviderSetup.for(identifier), env: Riffer::Rig::Env.new, auth_path: PATH)
+    secret_fields = setup.fields.select(&:secret)
+    return :env if secret_fields.any? { |field| env.value_for(field) }
+
+    stored = stored_secrets(identifier, auth_path)
+    return :stored if secret_fields.any? { |field| stored.key?(field.name.to_s) }
+
+    setup.chain ? :chain : :missing
   end
 
   private
 
-  # @rbs provider: String?
-  # @rbs path: String
+  # @rbs fields: Array[Riffer::Rig::ProviderSetup::Field]
+  # @rbs identifier: String | Symbol
+  # @rbs host: Riffer::Rig::Hosts::Base
+  # @rbs return: Hash[Symbol, String]
+  def ask_for(fields, identifier, host)
+    fields.to_h do |field|
+      [field.name, presence(host.ask("#{identifier} #{field.name}", secret: field.secret))]
+    end.compact
+  end
+
+  # @rbs field: Riffer::Rig::ProviderSetup::Field
+  # @rbs secrets: Hash[String, String]
+  # @rbs plain: Hash[String, String]
+  # @rbs env: Riffer::Rig::Env
+  # @rbs return: String?
+  def stored_value(field, secrets, plain, env)
+    field.secret ? expand(secrets[field.name.to_s], env) : plain[field.name.to_s]
+  end
+
+  # @rbs value: String?
+  # @rbs env: Riffer::Rig::Env
+  # @rbs return: String?
+  def expand(value, env)
+    return nil if value.nil?
+    return env[value.delete_prefix('$')] if value.start_with?('$')
+    return presence(run(value.delete_prefix('!'))) if value.start_with?('!')
+
+    value
+  end
+
+  # @rbs command: String
+  # @rbs return: String?
+  def run(command)
+    stdout, status = Open3.capture2(command)
+    stdout if status.success?
+  end
+
+  # @rbs value: String?
   # @rbs return: String?
-  def key_from_file(provider, path)
-    key = read(path)[provider]
-    return nil unless key.is_a?(String)
-    return key unless key.strip.empty?
+  def presence(value)
+    stripped = value.to_s.strip
+    stripped unless stripped.empty?
+  end
 
-    nil
+  # @rbs identifier: String | Symbol
+  # @rbs path: String
+  # @rbs return: Hash[String, String]
+  def stored_secrets(identifier, path)
+    read_auth(path)[identifier.to_s] || {}
   end
 
-  # The parsed auth file, or an empty hash when the file is absent or
-  # malformed.
-  #
   # @rbs path: String
-  # @rbs return: Hash[String, untyped]
-  def read(path)
+  # @rbs return: Hash[String, Hash[String, String]]
+  def read_auth(path)
     return {} unless File.file?(path)
 
     JSON.parse(File.read(path))
+        .select { |_identifier, entry| entry.is_a?(Hash) && entry['type'] == ENTRY_TYPE }
+        .transform_values { |entry| entry.except('type').select { |_name, value| value.is_a?(String) } }
   rescue JSON::ParserError
     {}
   end
+
+  # @rbs path: String
+  # @rbs entries: Hash[String, Hash[String, String]]
+  # @rbs return: void
+  def write_auth(path, entries)
+    FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+    data = entries.transform_values { |fields| { 'type' => ENTRY_TYPE }.merge(fields) }
+    File.open(path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |file|
+      file.write(JSON.pretty_generate(data))
+    end
+  end
 end

data/lib/riffer/rig/env.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Env
+  # @rbs @source: Hash[String, String]
+
+  # @dynamic no_color
+  attr_reader :no_color #: bool
+
+  # @rbs source: Hash[String, String]
+  # @rbs return: void
+  def initialize(source = ENV.to_h)
+    @source = source.freeze
+    @no_color = @source.key?('NO_COLOR')
+    freeze
+  end
+
+  # @rbs name: String
+  # @rbs return: String?
+  def [](name)
+    stripped = @source[name].to_s.strip
+    stripped unless stripped.empty?
+  end
+
+  # @rbs field: Riffer::Rig::ProviderSetup::Field
+  # @rbs return: String?
+  def value_for(field)
+    field.env.filter_map { |name| self[name] }.first
+  end
+end

data/lib/riffer/rig/events/command_output.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Events::CommandOutput < Riffer::Rig::Events::Event
+  # @dynamic command, text
+  attr_reader :command #: String
+  attr_reader :text #: String
+
+  # @rbs command: String
+  # @rbs text: String
+  # @rbs return: void
+  def initialize(command, text)
+    super()
+    @command = command
+    @text = text
+    freeze
+  end
+
+  # @rbs return: Symbol
+  def type
+    :command_output
+  end
+
+  # @rbs return: Hash[Symbol, untyped]
+  def to_h
+    { type: type, command: command, text: text }
+  end
+end

data/lib/riffer/rig/events/event.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Events::Event
+  # @rbs return: Symbol
+  def type
+    raise NotImplementedError, "#{self.class.name} must define type"
+  end
+
+  # @rbs return: Hash[Symbol, untyped]
+  def to_h
+    raise NotImplementedError, "#{self.class.name} must define to_h"
+  end
+
+  # @rbs other: untyped
+  # @rbs return: bool
+  def ==(other)
+    other.class == self.class && other.to_h == to_h
+  end
+
+  # @rbs return: Integer
+  def hash
+    [self.class, to_h].hash
+  end
+
+  # @rbs other: untyped
+  # @rbs return: bool
+  def eql?(other)
+    self == other
+  end
+end

data/lib/riffer/rig/events/notify.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Events::Notify < Riffer::Rig::Events::Event
+  # @dynamic message, level
+  attr_reader :message #: String?
+  attr_reader :level #: Symbol
+
+  # @rbs message: String?
+  # @rbs level: Symbol
+  # @rbs return: void
+  def initialize(message, level)
+    super()
+    @message = message
+    @level = level
+    freeze
+  end
+
+  # @rbs return: Symbol
+  def type
+    :notify
+  end
+
+  # @rbs return: Hash[Symbol, untyped]
+  def to_h
+    { type: type, message: message, level: level }
+  end
+end