lyman 0.1.0

data/lib/lyman/cli/commands/doctor.rb

@@ -0,0 +1,122 @@
+require "open3"
+
+module Lyman
+  module CLI
+    module Commands
+      # `lyman doctor` — smoke-tests a scaffolded project: manifest parses,
+      # every listed file exists (managed files note pristine/modified), and
+      # a subprocess runs the planted pipeline end to end against a stub
+      # transport (lib/lyman/cli/doctor_check.rb). See docs/design/
+      # deployment.md ("Ruby without a type checker").
+      class Doctor
+        # doctor_check.rb is CLI machinery, not a planted artifact — it always
+        # ships from this gem's own tree, never from a fixture source_root
+        # (source_root exists so other commands can point at "a newer lyman
+        # release"; doctor has no such concept, it only checks what's here).
+        CHECK_SCRIPT = File.join(Registry::GEM_ROOT, "lib", "lyman", "cli", "doctor_check.rb")
+
+        def initialize(thor, source_root:)
+          @thor = thor
+          @source_root = source_root
+        end
+
+        def call
+          project_root = Manifest.find!
+          manifest = load_manifest(project_root)
+
+          results = [!manifest.nil?]
+          if manifest
+            results << check_files(manifest, project_root)
+            results << check_pipeline(project_root)
+          end
+
+          exit 1 unless results.all?
+        end
+
+        private
+
+        # Check 1: the manifest itself parses. `Manifest.find!` already
+        # confirmed the file exists; the read can still blow up on malformed
+        # YAML, and that's worth its own ✓/✗ line rather than a raw backtrace.
+        def load_manifest(project_root)
+          manifest = Manifest.load(project_root)
+          report(true, "manifest parses (#{manifest.path})")
+          manifest
+        rescue => e
+          report(false, "manifest failed to parse: #{e.message}")
+          nil
+        end
+
+        # Check 2: every manifest-listed file exists. Managed files also get
+        # a pristine/modified note — modified is informational (that's
+        # `update`'s job to flag as a halt), not a doctor failure. Each entry
+        # records its own path, so this check needs no registry: even
+        # artifacts a future lyman release no longer knows about get checked.
+        def check_files(manifest, project_root)
+          ok = true
+
+          manifest.artifacts.each do |name, entry|
+            next unless entry["path"] # nothing to check without a location
+
+            dest = File.join(project_root, entry["path"])
+            unless File.exist?(dest)
+              report(false, "#{name}: planted file missing (#{dest})")
+              ok = false
+              next
+            end
+
+            if entry["status"] == "managed"
+              current_hash = Planter.hash(File.read(dest))
+              note = (current_hash == entry["hash"]) ? "pristine" : "modified"
+              report(true, "#{name}: file present (#{note})")
+            else
+              report(true, "#{name}: file present")
+            end
+          end
+
+          ok
+        end
+
+        # Check 3: run the planted pipeline against a stub transport, in a
+        # subprocess. It must be a subprocess — the client project has its
+        # own `Lyman::` constants (Conversation, Workers) that would collide
+        # with this CLI process if we required them in-process, and the
+        # client's bundle (not the CLI's) is what needs to resolve shifty.
+        def check_pipeline(project_root)
+          cmd = subprocess_command(project_root)
+          out, status = Open3.capture2e(*cmd, chdir: project_root)
+
+          # doctor_check.rb prints its own ✓/✗ verdict line; relay it
+          # verbatim rather than re-deriving one, so the subprocess's
+          # explanation of *why* it failed (if it did) reaches the user.
+          out.each_line { |line| @thor.say line.chomp }
+          status.success?
+        end
+
+        # A freshly scaffolded project has no Gemfile.lock until the user
+        # runs `bundle install` — `lyman doctor` should still work at that
+        # point, so it falls back to plain `ruby` with explicit `-I` load
+        # paths for shifty/ostruct, borrowed from the CLI process's own
+        # activated gems (Gem.loaded_specs — populated by Bundler when this
+        # CLI itself was launched via `bundle exec`/the installed gem).
+        # Once the client has a lock, `bundle exec` lets their own bundle
+        # (which might pin a different shifty version) resolve instead.
+        def subprocess_command(project_root)
+          if File.exist?(File.join(project_root, "Gemfile.lock"))
+            ["bundle", "exec", "ruby", CHECK_SCRIPT]
+          else
+            load_paths = %w[shifty ostruct].filter_map do |gem_name|
+              spec = Gem.loaded_specs[gem_name]
+              "#{spec.gem_dir}/lib" if spec
+            end
+            ["ruby", *load_paths.flat_map { |p| ["-I", p] }, CHECK_SCRIPT]
+          end
+        end
+
+        def report(ok, message)
+          @thor.say "#{ok ? "✓" : "✗"} #{message}"
+        end
+      end
+    end
+  end
+end

data/lib/lyman/cli/commands/eject.rb

@@ -0,0 +1,53 @@
+module Lyman
+  module CLI
+    module Commands
+      # `lyman eject ARTIFACT` — rewrites a managed artifact's manifest
+      # entry into a tombstone (status: ejected, ejected_at, pristine_hash),
+      # transferring ownership without deleting history. See docs/design/
+      # deployment.md ("Eject-to-own"). The pristine copy is left in place —
+      # it becomes the fork point that makes a later `lyman diff` meaningful.
+      class Eject
+        def initialize(thor, source_root:)
+          @thor = thor
+          @source_root = source_root
+        end
+
+        def call(artifact)
+          project_root = Manifest.find!
+          manifest = Manifest.load(project_root)
+          name = Registry.resolve(artifact, manifest: manifest)
+          entry = manifest.artifact(name)
+
+          case entry&.fetch("status", nil)
+          when "managed"
+            eject(manifest, name, entry)
+          when "owned"
+            @thor.say "#{name} is already yours; lyman never manages #{entry["path"]}."
+          when "ejected"
+            @thor.say "#{name} was already ejected at #{entry["ejected_at"]}; nothing to do."
+          else
+            raise Thor::Error, "#{name} isn't planted in this project; nothing to eject."
+          end
+        end
+
+        private
+
+        # The tombstone keeps the path: it's what lets `diff` and `doctor`
+        # find the fork without consulting a registry that may no longer
+        # know this artifact.
+        def eject(manifest, name, entry)
+          manifest.set_artifact(name, {
+            "status" => "ejected",
+            "ejected_at" => Lyman::CLI::VERSION,
+            "path" => entry["path"],
+            "pristine_hash" => entry["hash"]
+          })
+          manifest.save
+
+          @thor.say "#{name} is yours now. lyman will note upstream changes to it " \
+            "(run `lyman diff #{name}` to compare) but will never touch the file again."
+        end
+      end
+    end
+  end
+end

data/lib/lyman/cli/commands/new.rb

@@ -0,0 +1,72 @@
+require "fileutils"
+
+module Lyman
+  module CLI
+    module Commands
+      # `lyman new NAME` — the one command that doesn't need an existing
+      # project: it creates one, planting every registry artifact and
+      # writing the manifest that makes `update`/`eject`/`diff` possible
+      # afterward.
+      class New
+        def initialize(thor, source_root:)
+          @thor = thor
+          @source_root = source_root
+        end
+
+        def call(name)
+          project_root = File.expand_path(name)
+          refuse_nonempty!(project_root, name)
+          FileUtils.mkdir_p(project_root)
+
+          manifest = Manifest.load(project_root)
+          Registry::ARTIFACTS.each do |artifact_name, spec|
+            plant(manifest, artifact_name, spec, project_root)
+          end
+          manifest.save
+
+          epilogue(name)
+        end
+
+        private
+
+        def refuse_nonempty!(project_root, name)
+          return unless Dir.exist?(project_root)
+          return if Dir.empty?(project_root)
+
+          raise Thor::Error, "#{name} already exists and is not empty; " \
+            "choose a different name or clear the directory first."
+        end
+
+        # The manifest records where each artifact was planted, so every
+        # entry stays self-describing even if a later lyman release renames
+        # or drops the artifact — lifecycle commands read the path from
+        # here, not from the registry.
+        def plant(manifest, artifact_name, spec, project_root)
+          bytes = Planter.plant(artifact_name, spec, project_root: project_root, source_root: @source_root)
+          manifest.write_pristine(spec[:dest], bytes)
+
+          attrs = {
+            "status" => spec[:role].to_s,
+            "planted_at" => Lyman::CLI::VERSION,
+            "path" => spec[:dest]
+          }
+          attrs["hash"] = Planter.hash(bytes) if spec[:role] == :managed
+          manifest.set_artifact(artifact_name, attrs)
+        end
+
+        def epilogue(name)
+          @thor.say <<~EPILOGUE
+
+            Planted a new lyman project in #{name}.
+
+            Next steps:
+              cd #{name}
+              bundle install
+              ruby harness/chat.rb   # defaults to Ollama at http://localhost:11434/v1
+              lyman doctor           # smoke-test the pipeline
+          EPILOGUE
+        end
+      end
+    end
+  end
+end

data/lib/lyman/cli/commands/update.rb

@@ -0,0 +1,154 @@
+module Lyman
+  module CLI
+    module Commands
+      # `lyman update` — walks the manifest (never the filesystem) and
+      # reconciles every managed artifact against the current lyman release.
+      # Three tiers per docs/design/deployment.md: managed artifacts either
+      # replace silently (pristine) or halt with a structured message
+      # (modified/missing); owned artifacts are the user's and are skipped;
+      # ejected artifacts get a one-time advisory. Artifacts not in the
+      # manifest are never even looked at.
+      class Update
+        def initialize(thor, source_root:)
+          @thor = thor
+          @source_root = source_root
+        end
+
+        def call
+          project_root = Manifest.find!
+          manifest = Manifest.load(project_root)
+
+          updated = []
+          up_to_date = []
+          halted = []
+          advisories = []
+
+          manifest.artifacts.each_key.to_a.each do |name|
+            spec = Registry::ARTIFACTS[name]
+            next unless spec # unknown-to-this-release entries are left alone
+
+            entry = manifest.artifact(name)
+            case entry["status"]
+            when "managed"
+              reconcile_managed(manifest, project_root, name, spec, entry, updated, up_to_date, halted)
+            when "owned"
+              next # the user's file; update never touches it
+            when "ejected"
+              reconcile_ejected(manifest, name, spec, entry, advisories)
+            end
+          end
+
+          manifest.save
+          summarize(updated, up_to_date, halted, advisories)
+          exit 1 unless halted.empty?
+        end
+
+        private
+
+        # The manifest's recorded path — not the registry's dest — says where
+        # this project's copy lives; the registry only says where the current
+        # release would plant a fresh one. When the two disagree (someone
+        # moved the file, or upstream relocated the artifact), that's a halt:
+        # update can't know which references would break by moving it.
+        def reconcile_managed(manifest, project_root, name, spec, entry, updated, up_to_date, halted)
+          path = entry["path"]
+          dest = File.join(project_root, path)
+
+          if spec[:dest] != path
+            halted << {name: name, reason: :relocated, path: path, upstream_dest: spec[:dest]}
+            return
+          end
+
+          unless File.exist?(dest)
+            halted << {name: name, reason: :missing, planted_at: entry["planted_at"], path: path}
+            return
+          end
+
+          current_bytes = File.read(dest)
+          current_hash = Planter.hash(current_bytes)
+
+          if current_hash != entry["hash"]
+            halted << {name: name, reason: :modified, planted_at: entry["planted_at"], path: path}
+            return
+          end
+
+          rendered = Planter.render(name, spec, source_root: @source_root)
+          new_hash = Planter.hash(rendered)
+
+          if new_hash == current_hash
+            up_to_date << name
+            return
+          end
+
+          from_version = entry["planted_at"]
+          Planter.plant(name, spec, project_root: project_root, source_root: @source_root)
+          manifest.write_pristine(path, rendered)
+          manifest.set_artifact(name, entry.merge(
+            "hash" => new_hash,
+            "planted_at" => Lyman::CLI::VERSION
+          ))
+          updated << {name: name, from: from_version, to: Lyman::CLI::VERSION}
+        end
+
+        # Ejected artifacts are never touched — the manifest just tracks
+        # whether upstream has moved since the fork point, and fires the
+        # advisory at most once per upstream version so a long-lived fork
+        # doesn't nag forever.
+        def reconcile_ejected(manifest, name, spec, entry, advisories)
+          rendered = Planter.render(name, spec, source_root: @source_root)
+          current_hash = Planter.hash(rendered)
+
+          return if current_hash == entry["pristine_hash"]
+          return if entry["notified"] == Lyman::CLI::VERSION
+
+          advisories << {name: name, ejected_at: entry["ejected_at"], upstream: Lyman::CLI::VERSION}
+          manifest.set_artifact(name, entry.merge("notified" => Lyman::CLI::VERSION))
+        end
+
+        def summarize(updated, up_to_date, halted, advisories)
+          updated.each do |u|
+            @thor.say "updated #{u[:name]} (#{u[:from]} → #{u[:to]})"
+          end
+
+          up_to_date.each do |name|
+            @thor.say "#{name} up to date"
+          end
+
+          halted.each do |h|
+            @thor.say(halt_message(h), :red)
+          end
+
+          advisories.each do |a|
+            @thor.say "#{a[:name]} (ejected at #{a[:ejected_at]}) has upstream changes in " \
+              "#{a[:upstream]}; run `lyman diff #{a[:name]}` to compare.", :yellow
+          end
+
+          @thor.say [
+            "#{updated.size} updated",
+            "#{up_to_date.size} up to date",
+            "#{halted.size} halted",
+            "#{advisories.size} advisories"
+          ].join(", ")
+        end
+
+        def halt_message(halted)
+          case halted[:reason]
+          when :missing
+            "#{halted[:name]} (planted at #{halted[:planted_at]}) is missing its planted file " \
+              "(#{halted[:path]}); run `lyman add #{halted[:name]} --force` to replant it."
+          when :modified
+            "#{halted[:name]} (planted at #{halted[:planted_at]}) has been modified since planting; " \
+              "pristine copy at .lyman/pristine/#{halted[:path]}. " \
+              "Run `lyman diff #{halted[:name]}` to see changes, or " \
+              "`lyman eject #{halted[:name]}` to take ownership."
+          when :relocated
+            "#{halted[:name]} lives at #{halted[:path]} in this project, but this lyman release " \
+              "plants it at #{halted[:upstream_dest]}. Move the file (and any references to it), " \
+              "set its `path:` in .lyman/manifest.yml to match, and rerun `lyman update` — or " \
+              "run `lyman eject #{halted[:name]}` to keep it where it is, as yours."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lyman/cli/doctor_check.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+#
+# lyman doctor's pipeline smoke test, run as a subprocess inside the client
+# project (see lib/lyman/cli/commands/doctor.rb for why it must be a
+# subprocess: the client's Lyman:: constants must not collide with this CLI
+# process's own, and it's the client's bundle — not the CLI's — that needs
+# to resolve shifty).
+#
+# Wires the same circuit shape as harness/chat.rb (docs/design/
+# circuit-pattern.md): a queue-backed source, the model⇄tool round, the
+# finish/requeue plumbing. The only substitution is the transport: a stub
+# stands in at the chat_completion seam. That's legitimate, not a mock
+# reaching inside — the model transport is itself a swappable worker (see
+# docs/design/deployment.md, "Ruby without a type checker"), so a stub here
+# is an alternate implementation of the seam, and every other stage (tool
+# execution, requeue, the finished-turn filter) still runs for real.
+
+require "./lib/lyman"
+
+include Shifty::DSL # standard:disable Style/MixinUsage
+
+conversation = Lyman::Conversation.new(system_prompt: "doctor")
+conversation.add_user_message("ping the tool once, then answer")
+rounds = [] # the circuit's queue, shell scope — mirrors harness/chat.rb
+
+# Stands in for Lyman::Workers.chat_completion: round 1 calls the "ping"
+# tool, round 2 answers plainly. A real transport wouldn't know the round
+# count in advance, but the seam only cares that something plays by the
+# wire's rules — append an assistant message, bump the round counter.
+call_count = 0
+stub_transport = relay_worker do |c|
+  call_count += 1
+  message =
+    if call_count == 1
+      {
+        "role" => "assistant",
+        "content" => nil,
+        "tool_calls" => [
+          {
+            "id" => "call_1",
+            "type" => "function",
+            "function" => {"name" => "ping", "arguments" => "{}"}
+          }
+        ]
+      }
+    else
+      {"role" => "assistant", "content" => "done"}
+    end
+  c.add_assistant_message(message)
+  c.rounds += 1
+  c
+end
+
+pipeline =
+  source_worker { rounds.shift } |
+  stub_transport |
+  relay_worker { |c|
+    c.finish! if c.pending_tool_calls.empty? || c.runaway?
+    c
+  } |
+  Lyman::Workers.tool_execution({"ping" => ->(_) { "pong" }}) |
+  side_worker { |c| rounds << c unless c.finished? } |
+  filter_worker { |c| c.finished? }
+
+# Never pull while the queue is empty (the nil footgun, CLAUDE.md) — enqueue
+# the seed conversation before the first shift.
+rounds << conversation
+result = pipeline.shift
+
+failures = []
+failures << "conversation never finished" unless result.finished?
+
+unless result.messages.all? { |m| m.keys.all? { |k| k.is_a?(String) } }
+  failures << "a message used non-string keys"
+end
+
+valid_roles = %w[system user assistant tool]
+unless result.messages.all? { |m| valid_roles.include?(m["role"]) }
+  failures << "a message had a role outside system|user|assistant|tool"
+end
+
+tool_message = result.messages.find { |m| m["role"] == "tool" }
+if tool_message.nil?
+  failures << "no tool result message found"
+elsif tool_message["tool_call_id"] != "call_1"
+  failures << "tool result did not answer the expected tool call id"
+elsif tool_message["content"] != "pong"
+  failures << "tool result content was #{tool_message["content"].inspect}, expected \"pong\""
+end
+
+if failures.empty?
+  puts "✓ pipeline smoke test passed (#{result.messages.size} messages, tool round-trip ok)"
+  exit 0
+else
+  puts "✗ pipeline smoke test failed: #{failures.join("; ")}"
+  exit 1
+end

data/lib/lyman/cli/manifest.rb

@@ -0,0 +1,113 @@
+require "yaml"
+require "fileutils"
+
+module Lyman
+  module CLI
+    # Reads and writes <project_root>/.lyman/manifest.yml — the record that
+    # makes `update` cheap (hash comparison instead of guessing) and `eject`
+    # meaningful (a tombstone, not a deletion). See docs/design/deployment.md.
+    class Manifest
+      RELATIVE_PATH = File.join(".lyman", "manifest.yml")
+      PRISTINE_DIR = File.join(".lyman", "pristine")
+
+      attr_reader :project_root
+
+      # Walks up from +start_dir+ looking for .lyman/manifest.yml, the same
+      # way git walks up looking for .git. Returns the project root or nil.
+      def self.find(start_dir = Dir.pwd)
+        dir = File.expand_path(start_dir)
+        loop do
+          return dir if File.exist?(File.join(dir, RELATIVE_PATH))
+          parent = File.dirname(dir)
+          break if parent == dir
+          dir = parent
+        end
+        nil
+      end
+
+      # Every command except `new` needs a project to act on; this is the one
+      # place that error is raised, worded for an agent to act on directly.
+      def self.find!(start_dir = Dir.pwd)
+        find(start_dir) || raise(Thor::Error, <<~MSG.strip)
+          Not inside a lyman project (no .lyman/manifest.yml found walking up
+          from #{start_dir}). Run `lyman new NAME` to create one.
+        MSG
+      end
+
+      def self.load(project_root)
+        new(project_root)
+      end
+
+      def initialize(project_root)
+        @project_root = project_root
+        @data = read
+      end
+
+      def path
+        File.join(project_root, RELATIVE_PATH)
+      end
+
+      def lyman_version
+        @data["lyman"]
+      end
+
+      def artifacts
+        @data["artifacts"] ||= {}
+      end
+
+      def artifact(name)
+        artifacts[name]
+      end
+
+      def set_artifact(name, attrs)
+        artifacts[name] = attrs
+      end
+
+      def delete_artifact(name)
+        artifacts.delete(name)
+      end
+
+      def save
+        @data["lyman"] = Lyman::CLI::VERSION
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, dump)
+        self
+      end
+
+      # The pristine cache mirrors the planted tree (.lyman/pristine/lib/
+      # lyman/conversation.rb, not a flat name) — collision-proof, and
+      # browsable as a shadow of exactly what was planted where.
+      def pristine_path(rel_path)
+        File.join(project_root, PRISTINE_DIR, rel_path)
+      end
+
+      def write_pristine(rel_path, bytes)
+        FileUtils.mkdir_p(File.dirname(pristine_path(rel_path)))
+        File.write(pristine_path(rel_path), bytes)
+      end
+
+      def read_pristine(rel_path)
+        File.read(pristine_path(rel_path))
+      end
+
+      def pristine?(rel_path)
+        File.exist?(pristine_path(rel_path))
+      end
+
+      private
+
+      # Stable key order (lyman, then artifacts sorted by name) so the
+      # manifest's own diffs stay calm across runs.
+      def dump
+        ordered = {"lyman" => @data["lyman"] || Lyman::CLI::VERSION}
+        ordered["artifacts"] = artifacts.sort.to_h
+        YAML.dump(ordered)
+      end
+
+      def read
+        return {"lyman" => Lyman::CLI::VERSION, "artifacts" => {}} unless File.exist?(path)
+        YAML.safe_load_file(path) || {}
+      end
+    end
+  end
+end

data/lib/lyman/cli/planter.rb

@@ -0,0 +1,40 @@
+require "digest"
+require "fileutils"
+
+module Lyman
+  module CLI
+    # Turns a registry entry into planted bytes and writes them. Rendering
+    # and hashing are kept together deliberately: the hash must always be a
+    # hash of what actually landed on disk (banner included), never of the
+    # bare source file, or `update` would flag every managed artifact as
+    # locally modified on first run.
+    module Planter
+      BANNER = <<~RUBY
+        # Managed by lyman — extend, don't modify. `lyman eject %<name>s` takes
+        # ownership; see .lyman/manifest.yml.
+
+      RUBY
+
+      def self.render(name, spec, source_root: Registry::GEM_ROOT)
+        source = File.read(Registry.source_path(spec, source_root: source_root))
+        if spec[:role] == :managed && spec[:dest].end_with?(".rb")
+          format(BANNER, name: name) + source
+        else
+          source
+        end
+      end
+
+      def self.plant(name, spec, project_root:, source_root: Registry::GEM_ROOT)
+        bytes = render(name, spec, source_root: source_root)
+        dest = File.join(project_root, spec[:dest])
+        FileUtils.mkdir_p(File.dirname(dest))
+        File.write(dest, bytes)
+        bytes
+      end
+
+      def self.hash(bytes)
+        Digest::SHA256.hexdigest(bytes)
+      end
+    end
+  end
+end