terret 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6d2cb467e17acca48ee7001c042d041bbc9e50a923fedeb2828050603f6319e
-  data.tar.gz: 60bdcb7b49ce9ecefea229cb5cf8e9ac913651ec05a9910846840d5803e1907d
+  metadata.gz: 5dbd83ac7632140b6d208f2e242ae24bfd0e11c0c05a2fd5b61d144c2b156190
+  data.tar.gz: c5f750acb8b699b3e6740677767ee11737f589dd16085395116d0fbd84b550fa
 SHA512:
-  metadata.gz: e09b72fd5e9b76d06f11946bf88f4285e570334b7b6e05021e3736338135ed0a2ac4f6aa01fe0621b3a3e59de351e1f8372a7738d736e8a88671bc5dabcf80f2
-  data.tar.gz: 5ffdcb91c1d5fb8026c1debcb888ef0270cb0e2f7fe579544c18246cbdb91e02b3dcf6d43e96fa9e3eea78fb8bc4a7675f8ea662bfafff5eb741e84c44ec0ab2
+  metadata.gz: bee7e82ba1466f623a5b3852f698568ae14ed884564cc041c4bdc9b78cb69aca394a75cdb4a5f0612135e4dc544207ef5d3a4c7f80069260d2ff5fa9b71e9d93
+  data.tar.gz: 2ca60bc9a5143f9105b419eacb94e90715aeff0679e4c3f3456eac30ca4a87bc0b8bc44bf92fdd9c0f32026bb65d365516c8a2ec5638fa25464e2e67bdd44ba1

data/config/bundle.yml

@@ -0,0 +1,189 @@
+# terret-base — layer one of every profile (docs/composition.md §6).
+#
+# These rows are the answer to "what is a Terret": the session log, the
+# harness, the model seam, the execution world, the tool roster, and the
+# policy floor. A profile stacks this bundle first and then says what is
+# different about ITS machine, in profile.yml settings and patch.yml rows.
+#
+# Two things here are secure-by-default rather than convenient-by-default, and
+# both are called out where they sit: the sandbox is docker with the network
+# denied, and every allow list starts closed.
+#
+# Remember that a patch replaces a row's config WHOLESALE. Read a row here
+# before you patch it (or run `trt dump-config`) — a patch that mentions one
+# key drops the rest.
+name: terret-base
+
+# A bundle ships rows; the code those rows name comes from the gems the bundle
+# depends on (see terret.gemspec). Bundler puts them on the load path, and
+# these are the files that pull them in before a row's constant has to resolve.
+requires:
+  - terret/store/sqlite
+  - terret/openrouter
+  - terret/exec
+  - terret/tools_std
+  - terret/sandbox/docker
+
+rows:
+  # -- the durable log ------------------------------------------------------
+  # Everything the model can see is a projection of this file. Losing it loses
+  # the agent's memory; it is the one row worth backing up.
+  - id: session_store
+    plugin: Terret::Store::SQLite
+    config:
+      path: !setting store.path
+
+  - id: sessions
+    plugin: Terret::Sessions
+
+  - id: prompt
+    plugin: Terret::Prompt
+
+  - id: tools
+    plugin: Terret::Tools::Registry
+
+  # -- the model seam -------------------------------------------------------
+  # Roles are "provider/model"; "openrouter" is the provider name the row
+  # below registers. Point a role somewhere else by patching this row — and
+  # restate every role you still want, because the replacement is wholesale.
+  - id: llm
+    plugin: Terret::LLM::Service
+    config:
+      roles:
+        main: !setting model.main
+
+  # nil api_key is deliberate when the variable is unset: the adapter falls
+  # back to OPENROUTER_API_KEY itself and raises a better error than YAML can,
+  # and dump-config stays runnable on a machine that holds no secrets.
+  - id: openrouter
+    plugin: Terret::OpenRouter::Plugin
+    config:
+      api_key: !env OPENROUTER_API_KEY
+
+  # -- the execution world --------------------------------------------------
+  # THE SANDBOX ROW IS THE ONE TO READ TWICE. Every argv the harness spawns
+  # goes through ctx[:sandbox], and the default is a container with no
+  # network. Running tools directly on the host is a per-profile opt-in
+  # (docs/security.md, plan §13) — the shipped headless patch.yml shows what
+  # that opt-in looks like and what it costs.
+  - id: sandbox
+    plugin: Terret::Sandbox::Docker
+    config:
+      image: !setting sandbox.image
+      network: none
+      workspace: !setting workspace
+
+  - id: subprocess
+    plugin: Terret::Exec::Subprocess
+
+  # AND THE FS ROW FOR THE OPPOSITE REASON: `workspace:` is what every
+  # filesystem tool is contained to, and an empty or unconfigured list DENIES
+  # EVERY FILE OPERATION rather than permitting them. There is no
+  # ungranted-but-permitted state, so a profile that never sets
+  # settings.workspace gets an agent that cannot read a file. That is the safe
+  # failure, and a confusing one if nobody says so in advance.
+  - id: fs
+    plugin: Terret::Exec::FS
+    config:
+      workspace: !setting workspace
+
+  - id: shell
+    plugin: Terret::Exec::Shell
+
+  - id: terminals
+    plugin: Terret::Exec::Terminals
+
+  - id: jobs
+    plugin: Terret::Exec::Jobs
+
+  # -- the tool roster ------------------------------------------------------
+  # Claude Code's names wherever it has one. Every handler reaches the world
+  # only through a seam, which is why swapping the sandbox row above moves the
+  # whole roster into a container with no tool change.
+  - id: std_files
+    plugin: Terret::ToolsStd::Files
+
+  - id: std_bash
+    plugin: Terret::ToolsStd::Bash
+
+  - id: std_terminals
+    plugin: Terret::ToolsStd::Terminals
+
+  - id: std_jobs
+    plugin: Terret::ToolsStd::Jobs
+
+  - id: std_todo
+    plugin: Terret::ToolsStd::Todo
+
+  # Deny-by-default, like every other list here: WebFetch reaches nothing
+  # until a profile names hosts in `allow`. Patch this row with the globs your
+  # agent actually needs.
+  - id: std_web_fetch
+    plugin: Terret::ToolsStd::WebFetch
+    config:
+      allow: []
+      deny: []
+
+  - id: subagents
+    plugin: Terret::Subagents
+
+  - id: std_task
+    plugin: Terret::ToolsStd::Task
+
+  - id: loop
+    plugin: Terret::Loop
+
+  # -- policy ---------------------------------------------------------------
+  # Provider secrets resolved in one place (plan §6.9): ENV <PROVIDER>_API_KEY
+  # always wins, then an optional AES-256-GCM file store (its master key in ENV
+  # TERRET_CREDENTIALS_KEY, never config). Every value it resolves is fed to the
+  # scrubber below, so a resolved credential can never reach the log even if a
+  # tool echoes it. With no `file:` set this is ENV-only — the current behavior
+  # — and inert until a deployment points it at an encrypted store.
+  - id: credentials
+    plugin: Terret::Credentials
+
+  # The scrubber at the append boundary and at tools/post_execute: a
+  # credential that reaches a tool result never reaches the session log or the
+  # model. These patterns are a floor, not a guarantee — add the shapes your
+  # environment actually issues.
+  - id: redactor
+    plugin: Terret::Redactor
+    config:
+      patterns:
+        - "sk-[A-Za-z0-9_-]{16,}"
+        - "gh[pousr]_[A-Za-z0-9]{20,}"
+        - "AKIA[0-9A-Z]{16}"
+        - "xox[baprs]-[A-Za-z0-9-]{10,}"
+
+  # The floor: the policy governing a session that never issued a
+  # policy/updated of its own. It names exactly the roster mounted above, so a
+  # tool arriving from a third-party bundle is denied until a profile says
+  # otherwise — that is what deny-by-default buys, and the cost is this list.
+  - id: allow_list
+    plugin: Terret::Tools::AllowListFloor
+    config:
+      patterns:
+        - Read
+        - Write
+        - Edit
+        - Glob
+        - Grep
+        - Bash
+        - WebFetch
+        - Task
+        - TodoWrite
+        - terminal_open
+        - terminal_read
+        - terminal_input
+        - terminal_close
+        - job_start
+        - job_collect
+        - job_stop
+
+  # Present but unmounted: approvals are opt-in per tool (M6), and an
+  # unattended profile has nobody to ask. Flip `disabled` in a patch to turn
+  # them on; the row is here so you can see what you are turning on.
+  - id: approvals
+    plugin: Terret::Tools::Approvals
+    disabled: true

data/exe/trt

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The one caller that turns CLI.start's status into an exit. Everything else
+# drives Terret::CLI.start(argv, out:, err:) in-process.
+begin
+  require "terret/boot"
+rescue LoadError
+  require_relative "../lib/terret/boot" # monorepo path source
+end
+
+exit Terret::CLI.start(ARGV)

data/lib/terret/boot.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# Running from a source checkout, the sibling gems are not on the load path;
+# a `gem install` puts them there. Seeding them here is what lets a bundle's
+# `requires:` name `terret/exec` and resolve identically in both worlds, and it
+# is the same monorepo path-source affordance every other gem's entry file
+# makes for terret-core.
+gems_root = File.expand_path("../../..", __dir__)
+if File.directory?(File.join(gems_root, "terret-core", "lib"))
+  # One unshift, so the sibling libs keep the order they are listed in rather
+  # than the reverse of it.
+  $LOAD_PATH.unshift(*Dir.children(gems_root).sort
+                        .map { |gem_dir| File.join(gems_root, gem_dir, "lib") }
+                        .select { |lib| File.directory?(lib) && !$LOAD_PATH.include?(lib) })
+end
+
+require "terret"
+
+require_relative "version"
+require_relative "home"
+require_relative "composition"
+require_relative "doctor"
+require_relative "cli"
+
+module Terret
+  # Resolve the layers, hand the row list to the Hames loader, return the
+  # booted context (docs/composition.md §7). That is the whole surface, and its
+  # shape is the embeddability goal made concrete: a Rails app calls this in an
+  # initializer and holds the ctx, with no process to supervise and no socket
+  # to speak.
+  def self.boot(profile:, patches: [], allow_config_ruby: false, home: nil)
+    Boot.new(Composition.resolve(profile: profile, home: home, patches: patches),
+             allow_config_ruby: allow_config_ruby).boot!
+  end
+
+  # The impure half: requiring the code a composition names, turning plugin
+  # names into constants, and mounting. Split out from Composition so the pure
+  # half stays runnable on a machine with none of this installed.
+  class Boot
+    Error = Class.new(StandardError)
+
+    attr_reader :resolved, :allow_config_ruby
+
+    def initialize(resolved, allow_config_ruby: false)
+      @resolved = resolved
+      @allow_config_ruby = allow_config_ruby
+    end
+
+    def boot! = loader.boot!
+
+    # The loader rather than the context, for a caller that wants
+    # reconfigure!/unload! on the composition it just booted. Memoized, because
+    # a second loader would be a second context: `b.loader` then `b.boot!`
+    # would hand back two unrelated worlds built from the same rows.
+    def loader
+      @loader ||= begin
+        require_code!
+        built = Hames::Loader.new.layer(rows)
+        # Reachable from the context it boots. Terret.boot returns the ctx and
+        # nothing else, so without this a caller holding one has no way to
+        # reconfigure a row, unload one, or shut the composition down through
+        # the services' own stop hooks.
+        built.ctx.register_service(:loader, built)
+        built
+      end
+    end
+
+    def rows
+      @rows ||= resolved.materialize(allow_config_ruby: allow_config_ruby)
+                        .map { |row| row.merge(plugin: constantize(row[:plugin], row[:id])) }
+    end
+
+    # A bundle's requires first, then the profile's own `plugins:` — code that
+    # is not a bundle loads last so it can reopen what a bundle defined.
+    def require_code!
+      # A bundle's requires: ship inside a gem the operator added to the Gemfile
+      # and installed, so they are trusted and may name a path to their own lib.
+      # A profile's plugins: is portable config a profile "downloaded from
+      # anywhere" (docs/composition.md §5) carries, so a path-shaped one there is
+      # arbitrary code execution — gated behind the same --allow-config-ruby
+      # consent as !ruby. Validate up front so a bad path fails before any
+      # require has run a line of code.
+      resolved.plugins.each do |file|
+        next if allow_config_ruby || Composition.load_path_feature?(file)
+
+        raise Error, "profile #{resolved.profile.inspect} refuses to require #{file.inspect}: " \
+                     "it is a filesystem path, not a load-path feature name. Loading Ruby by " \
+                     "path is arbitrary code execution; pass --allow-config-ruby to permit it " \
+                     "(docs/composition.md §5, docs/security.md)."
+      end
+
+      (resolved.requires + resolved.plugins).each do |file|
+        require file
+      rescue LoadError => e
+        raise Error, "profile #{resolved.profile.inspect} needs #{file.inspect}, " \
+                     "which is not on the load path (#{e.message}). Is the gem " \
+                     "that ships it in your Gemfile?"
+      end
+    end
+
+    def constantize(name, id)
+      klass = Object.const_get(name)
+      unless klass.is_a?(Class) && klass.method_defined?(:apply)
+        raise Error, "row #{id.inspect}: #{name} is not a plugin — a plugin is a " \
+                     "class whose instances respond to #apply(ctx), which is what " \
+                     "subclassing Hames::Service gives you"
+      end
+
+      klass
+    rescue NameError
+      raise Error, "row #{id.inspect}: no such plugin #{name}. The constant did not " \
+                   "resolve, so either the name is wrong or the gem that defines it " \
+                   "is not required by any bundle in this profile."
+    end
+
+    # Take a booted context down through the loader, so every row's own stop
+    # hook runs: the shell closes its bash, the sandbox discards its container,
+    # the SQLite store closes its handle. A hand-written list of seams runs
+    # none of the hooks it does not happen to name, and grows a hole every time
+    # a bundle mounts something new.
+    #
+    # Reverse MOUNT order, which is exact reverse-dependency order: a consumer
+    # comes down before the service it injects, and the session store — which
+    # everything else may still be writing to — closes last.
+    #
+    # Best-effort means each step is separately best-effort. One wedged seam
+    # aborting the rest is how a container survives the process that owned it.
+    #
+    # A context built by hand rather than by Terret.boot has no loader to find,
+    # and this says so rather than quietly disposing and running no hooks at
+    # all — pass `loader:` to get the real teardown.
+    def self.shutdown(ctx, loader: nil)
+      loader ||= ctx[:loader] if ctx.service?(:loader)
+      if loader
+        loader.mounted.keys.reverse_each { |id| step("row #{id}") { loader.unload!(id) } }
+      else
+        warn "terret: shutdown: no loader for this context, so no service's stop hook ran. " \
+             "Boot through Terret.boot, or pass shutdown(ctx, loader:) — disposing registrations only."
+      end
+      step("dispose") { ctx.dispose! }
+    end
+
+    def self.step(what)
+      yield
+    rescue StandardError => e
+      warn "terret: shutdown: #{what}: #{e.class}: #{e.message}"
+    end
+  end
+end

data/lib/terret/cli.rb

@@ -1,21 +1,279 @@
 # frozen_string_literal: true
 
+require "optparse"
+require "yaml"
+require_relative "version"
+require_relative "composition"
+require_relative "doctor"
+
 module Terret
-  # The `trt` command line interface.
+  # The `trt` command line interface (docs/composition.md §8).
+  #
+  # Non-interactive: optparse, no thor, no REPL, no TUI. Nothing here is a chat
+  # window and nothing here competes with the socket. `trt boot` starts the
+  # reactor and parks, the other two print and exit, and every one of them is a
+  # thin wrapper over Terret.boot or over pure resolution.
   #
-  # Not implemented yet. The CLI is M4 work in docs/terret-implementation-plan.md
-  # and it needs a real model adapter to drive, which is M2 work still outstanding.
-  # This gem exists so that the `terret` name belongs to the project that will
-  # fill it. Everything that currently works lives in terret-core and hames.
+  # start returns a process exit status rather than calling exit, so the tests
+  # can drive it in-process with captured IO. exe/trt is the one caller that
+  # turns the status into an exit.
   module CLI
-    VERSION = "0.0.2"
+    COMMANDS = %w[boot dump-config doctor acp].freeze
+
+    USAGE = <<~TXT
+      Usage: trt <command> [options]
+
+      Commands:
+        boot           compose a profile, mount it, and park until interrupted
+        dump-config    print the resolved rows, annotated with the layer that
+                       contributed each one; secrets stay unresolved
+        doctor         resolve a profile and report on its rows without booting
+        acp            compose a profile and serve the Agent Client Protocol
+                       on stdio, so an editor can drive an agent; stdout carries
+                       only ACP frames and diagnostics go to stderr
+
+      Options:
+        -p, --profile NAME       profile to compose (required)
+            --patch FILE         overlay a patch file; repeatable, applied in order
+            --home DIR           Terret home (default: $TERRET_HOME, else ~/.terret)
+            --allow-config-ruby  permit !ruby scalars in this composition
+        -v, --version            print the terret version
+        -h, --help               print this message
+    TXT
+
+    Options = Struct.new(:command, :profile, :patches, :home, :allow_config_ruby)
+
+    def self.start(argv = ARGV, out: $stdout, err: $stderr, input: $stdin)
+      opts = parse(argv, out: out, err: err)
+      return opts if opts.is_a?(Integer)
+
+      dispatch(opts, out: out, err: err, input: input)
+    rescue Composition::Error => e
+      # Boot failures are caught in .boot, which is also the only command that
+      # needs boot.rb — this file must not name a constant from the file that
+      # requires it.
+      err.puts "trt: #{e.message}"
+      1
+    rescue SystemCallError, IOError, ScriptError => e
+      # Belt and braces. Resolution turns these into Composition::Error where
+      # it meets them, but a config file is a file on somebody's disk and a
+      # !ruby scalar is a compiler — neither is done surprising us, and a
+      # backtrace is not an error message.
+      err.puts "trt: #{e.class}: #{e.message.lines.first.to_s.strip}"
+      1
+    rescue Interrupt
+      err.puts "trt: interrupted"
+      130
+    end
+
+    def self.dispatch(opts, out:, err:, input: $stdin)
+      case opts.command
+      when "boot" then boot(opts, out: out, err: err)
+      when "dump-config" then dump_config(opts, out: out)
+      when "doctor" then Doctor.run(resolve(opts), allow_config_ruby: opts.allow_config_ruby, out: out)
+      when "acp" then acp(opts, out: out, err: err, input: input)
+      end
+    end
+
+    # -- argument parsing ------------------------------------------------------
+
+    # Returns Options, or an exit status when the run is over (help, version,
+    # usage error).
+    def self.parse(argv, out:, err:)
+      opts = Options.new(nil, nil, [], nil, false)
+      parser = OptionParser.new do |o|
+        o.banner = USAGE
+        o.on("-p", "--profile NAME") { |v| opts.profile = v }
+        o.on("--patch FILE") { |v| opts.patches << v }
+        o.on("--home DIR") { |v| opts.home = v }
+        o.on("--allow-config-ruby") { opts.allow_config_ruby = true }
+        o.on("-v", "--version") { out.puts "trt #{Terret::Meta::VERSION}"; return 0 }
+        o.on("-h", "--help") { out.puts USAGE; return 0 }
+      end
+
+      rest = begin
+        parser.parse(argv.dup)
+      rescue OptionParser::ParseError => e
+        return usage_error(e.message, err: err)
+      end
+
+      opts.command = rest.shift
+      return usage_error("no command given", err: err) if opts.command.nil?
+      return usage_error("unknown command #{opts.command.inspect}", err: err) unless COMMANDS.include?(opts.command)
+      return usage_error("unexpected arguments: #{rest.join(' ')}", err: err) unless rest.empty?
+      return usage_error("#{opts.command} needs --profile NAME", err: err) if opts.profile.nil?
+
+      opts
+    end
+
+    def self.usage_error(message, err:)
+      err.puts "trt: #{message}"
+      err.puts
+      err.puts USAGE
+      2
+    end
+
+    def self.resolve(opts)
+      Composition.resolve(profile: opts.profile, home: opts.home, patches: opts.patches)
+    end
+
+    # -- boot ------------------------------------------------------------------
+
+    def self.boot(opts, out:, err:)
+      require_relative "boot" # the one command that needs it; already loaded via exe/trt
+      ctx = nil
+      ctx = Terret.boot(profile: opts.profile, home: opts.home, patches: opts.patches,
+                        allow_config_ruby: opts.allow_config_ruby)
+      out.puts "trt: profile #{opts.profile.inspect} is up. Interrupt to stop."
+      out.flush
+      begin
+        park
+      rescue Interrupt
+        out.puts
+      end
+      out.puts "trt: stopping"
+      0
+    rescue StandardError => e
+      err.puts "trt: boot failed: #{e.class}: #{e.message}"
+      1
+    ensure
+      # Teardown belongs here, not on the success path: a park that raises
+      # rather than catching its Interrupt used to return 1 and leak the whole
+      # booted world — its container, its bash, its open database. A boot that
+      # got as far as a live context is always torn down; a Terret.boot that
+      # never returned leaves ctx nil and nothing to shut down.
+      Boot.shutdown(ctx) if ctx
+    end
+
+    # -- acp -------------------------------------------------------------------
+
+    # Boot a profile and serve the Agent Client Protocol on stdio, so an editor
+    # can drive an agent (docs/acp.md). The one hard rule of this wire is that
+    # stdout carries ONLY ACP frames: diagnostics go to `err` (stderr), never
+    # `out`, and `serve` blocks on the reactor until the editor closes the pipe.
+    # The IO trio is injectable so a test drives the whole subcommand over an
+    # in-memory pipe; `exe/trt` passes $stdout/$stderr/$stdin.
+    def self.acp(opts, out:, err:, input:)
+      require_relative "boot"
+      ctx = nil
+      ctx = Terret.boot(profile: opts.profile, home: opts.home, patches: opts.patches,
+                        allow_config_ruby: opts.allow_config_ruby)
+      unless ctx.service?(:acp)
+        err.puts "trt: profile #{opts.profile.inspect} mounts no acp row to serve"
+        return 1
+      end
+
+      err.puts "trt: profile #{opts.profile.inspect} is up; serving ACP on stdio. Interrupt to stop."
+      err.flush
+      ctx[:acp].serve(input: input, output: out)
+      0
+    rescue Interrupt
+      err.puts "trt: interrupted"
+      130
+    rescue StandardError => e
+      err.puts "trt: acp failed: #{e.class}: #{e.message}"
+      1
+    ensure
+      # The same teardown boot does, and for the same reason: a serve that
+      # returned on EOF, or raised, must still take its container, its bash, and
+      # its open database down. A Terret.boot that never returned leaves ctx nil.
+      Boot.shutdown(ctx) if ctx
+    end
+
+    # An agent is a task tree on the fiber scheduler, so a booted process
+    # belongs on the reactor even when this command has nothing of its own to
+    # run. Without async there is nothing to park on but the process itself.
+    def self.park
+      require "async"
+      Async { |task| task.sleep }
+    rescue LoadError
+      sleep
+    end
+
+    # -- dump-config -----------------------------------------------------------
+
+    # The resolved tree with each row annotated by the layer that contributed
+    # it. SECRETS RENDER AS THEIR UNRESOLVED TAG — `api_key: !env
+    # OPENROUTER_API_KEY` prints as written and the resolved value never
+    # appears here at all. This output exists to be pasted into an issue, and a
+    # resolved credential printed once is a credential rotated.
+    def self.dump_config(opts, out:)
+      resolved = resolve(opts)
+      lines = [["# resolved: profile #{resolved.profile.inspect}", nil], ["rows:", nil]]
+
+      resolved.rows.each do |row|
+        # Row ids are validated at resolution, but plugin names (constant paths)
+        # and layer labels (bundle names, --patch paths) are not — so every
+        # identifier printed here goes through one_line, and a newline in one
+        # cannot forge a row or a provenance line in this output.
+        lines << ["  - id: #{safe(row.id)}", "row: #{safe(row.row_layer)}"]
+        # Annotated only when a later layer swapped it, so the annotation means
+        # "somebody changed this" rather than being visual noise on every row.
+        swapped = row.plugin_layer unless row.plugin_layer == row.row_layer
+        lines << ["    plugin: #{safe(row.plugin)}", swapped && "plugin: #{safe(swapped)}"]
+        lines << ["    disabled: true", nil] if row.disabled
+        if row.config.empty?
+          lines << ["    config: {}", "config: #{safe(row.config_layer)}"]
+        else
+          lines << ["    config:", "config: #{safe(row.config_layer)}"]
+          yaml_lines(row.config, 3).each { |l| lines << [l, nil] }
+        end
+      end
+
+      out.puts align(lines)
+      0
+    end
+
+    # Comments live in a column so the provenance reads as a column.
+    def self.align(lines)
+      width = lines.filter_map { |text, comment| text.length if comment }.max.to_i
+      column = [width + 2, 32].max
+      lines.map { |text, comment| comment ? "#{text.ljust(column)}# #{comment}" : text }
+    end
+
+    def self.yaml_lines(value, depth)
+      pad = "  " * depth
+      case value
+      when Hash
+        value.flat_map do |key, sub|
+          k = key_cell(key)
+          nested?(sub) ? ["#{pad}#{k}:", *yaml_lines(sub, depth + 1)] : ["#{pad}#{k}: #{scalar(sub)}"]
+        end
+      when Array
+        value.flat_map do |sub|
+          next ["#{pad}- #{scalar(sub)}"] unless nested?(sub)
+
+          nested = yaml_lines(sub, depth + 1)
+          ["#{pad}- #{nested.first.lstrip}", *nested.drop(1)]
+        end
+      else [pad + scalar(value)]
+      end
+    end
+
+    def self.nested?(value) = (value.is_a?(Hash) || value.is_a?(Array)) && !value.empty?
+
+    def self.safe(value) = Composition.one_line(value.to_s)
+
+    # A config KEY is attacker-influenceable the same way a value or a plugin
+    # name is (an explicit YAML key can carry a newline that forges a provenance
+    # line, or spell a secret), so it goes through the same one_line/redact path
+    # the values already use — not the Psych.dump `scalar` path, because a key is
+    # printed bare rather than quoted.
+    def self.key_cell(key) = Composition.one_line(Composition.redact_secrets(key.to_s))
 
-    def self.start(_argv = ARGV)
-      abort <<~MSG
-        terret: the trt CLI does not exist yet.
+    # Psych does the quoting, so a value that would reparse as a boolean, a
+    # number, or a null comes back quoted. A tag renders as itself (unresolved).
+    # A LITERAL string value is the one way a real secret reaches this output —
+    # !env/!setting stay tags — so a secret-shaped literal is redacted, and any
+    # control characters are neutralized so a value cannot forge a line either.
+    def self.scalar(value)
+      return safe(value) if value.is_a?(Composition::Tagged)
+      return "{}" if value == {}
+      return "[]" if value == []
 
-        What works today is the library. See https://terret.org
-      MSG
+      value = Composition.one_line(Composition.redact_secrets(value)) if value.is_a?(String)
+      body = Psych.dump(value).delete_prefix("---").sub(/\n\z/, "").strip
+      body.empty? ? "~" : body
     end
   end
 end