lyman 0.1.0

data/lib/lyman/cli/registry.rb

@@ -0,0 +1,98 @@
+module Lyman
+  module CLI
+    # What lyman installs. Everything the generator plants into a client
+    # project is declared here — this list, not directory layout, is the
+    # boundary between what lyman *does* (lib/lyman/cli) and what lyman
+    # *installs* (everything named below).
+    module Registry
+      GEM_ROOT = File.expand_path("../../..", __dir__)
+
+      ARTIFACTS = {
+        "lyman_entry" => {
+          source: "templates/lib_lyman.rb",
+          dest: "lib/lyman.rb",
+          role: :managed,
+          description: "Library entry point; requires shifty and every planted module"
+        },
+        "conversation" => {
+          source: "lib/lyman/conversation.rb",
+          dest: "lib/lyman/conversation.rb",
+          role: :managed,
+          description: "The item that flows through pipelines"
+        },
+        "chat_completion" => {
+          source: "lib/lyman/workers/chat_completion.rb",
+          dest: "lib/lyman/workers/chat_completion.rb",
+          role: :managed,
+          description: "Relay worker: OpenAI-compatible chat completions (streaming + blocking)"
+        },
+        "tool_execution" => {
+          source: "lib/lyman/workers/tool_execution.rb",
+          dest: "lib/lyman/workers/tool_execution.rb",
+          role: :managed,
+          description: "Relay worker: executes pending tool calls"
+        },
+        "harness" => {
+          source: "harness/chat.rb",
+          dest: "harness/chat.rb",
+          role: :owned,
+          description: "The wiring script — yours from day one; lyman never updates it"
+        },
+        "claude_md" => {
+          source: "templates/CLAUDE.md",
+          dest: "CLAUDE.md",
+          role: :owned,
+          description: "Guidance for coding agents working in this project"
+        },
+        "gemfile" => {
+          source: "templates/Gemfile",
+          dest: "Gemfile",
+          role: :owned,
+          description: "Client dependencies: shifty (and ostruct for ruby >= 4)"
+        },
+        "gitignore" => {
+          source: "templates/gitignore",
+          dest: ".gitignore",
+          role: :owned,
+          description: "A minimal starter .gitignore (.lyman/ stays tracked on purpose)"
+        }
+      }.freeze
+
+      def self.fetch(name)
+        ARTIFACTS.fetch(name) do
+          valid = ARTIFACTS.keys.join(", ")
+          raise Thor::Error, "Unknown artifact #{name.inspect}. Valid artifacts: #{valid}"
+        end
+      end
+
+      # Commands accept an artifact name or a project-relative path — you
+      # shouldn't have to remember the token while looking at the file.
+      # Resolution order: registry name, then the path recorded in this
+      # project's manifest (authoritative for where the file actually is),
+      # then the registry's dest (for artifacts not yet planted).
+      def self.resolve(token, manifest: nil)
+        return token if ARTIFACTS.key?(token)
+
+        path = token.delete_prefix("./")
+        if manifest
+          name, _entry = manifest.artifacts.find { |_, entry| entry["path"] == path }
+          return name if name
+        end
+        name, _spec = ARTIFACTS.find { |_, spec| spec[:dest] == path }
+        return name if name
+
+        valid = ARTIFACTS.keys.join(", ")
+        raise Thor::Error, "Unknown artifact #{token.inspect}. " \
+          "Give an artifact name (#{valid}) or a planted path (e.g. lib/lyman/conversation.rb)."
+      end
+
+      def self.managed
+        ARTIFACTS.select { |_, spec| spec[:role] == :managed }
+      end
+
+      def self.source_path(spec, source_root: GEM_ROOT)
+        File.join(source_root, spec[:source])
+      end
+    end
+  end
+end

data/lib/lyman/cli/version.rb

@@ -0,0 +1,7 @@
+module Lyman
+  module CLI
+    # The gem's own version — distinct from any artifact's `planted_at`.
+    # This is what the manifest's top-level `lyman:` key records.
+    VERSION = "0.1.0"
+  end
+end

data/lib/lyman/cli.rb

@@ -0,0 +1,100 @@
+require "thor"
+
+require_relative "cli/version"
+require_relative "cli/registry"
+require_relative "cli/manifest"
+require_relative "cli/planter"
+require_relative "cli/commands/new"
+require_relative "cli/commands/add"
+require_relative "cli/commands/update"
+require_relative "cli/commands/eject"
+require_relative "cli/commands/diff"
+require_relative "cli/commands/doctor"
+
+module Lyman
+  module CLI
+    # The legible table of contents for every lyman command. Root wires
+    # Thor's argument parsing to a plain object per command
+    # (lib/lyman/cli/commands/*.rb) and nothing else — no command grows its
+    # body here.
+    #
+    # Command contract: every command class is built as
+    # `Commands::X.new(thor, source_root:).call(*args)`.
+    #   - `thor` is this Root instance, passed through so a command can use
+    #     Thor's UI helpers (`thor.yes?`, `thor.say`) without inheriting from
+    #     Thor itself — commands are plain objects, not Thor subclasses.
+    #   - `source_root:` is where artifacts are read from (the gem tree by
+    #     default; overridable via LYMAN_SOURCE_ROOT so tests can point it at
+    #     a fixture that simulates a newer lyman release).
+    #   - `#call`'s positional args are whatever the command needs (an
+    #     artifact/project name, or nothing). Project-root discovery
+    #     (Manifest.find!) happens inside each command that needs it — `new`
+    #     is the one command that doesn't have a project root yet.
+    class Root < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      desc "new NAME", "Scaffold a new lyman project at NAME"
+      def new(name)
+        Commands::New.new(self, source_root: source_root).call(name)
+      end
+
+      desc "add ARTIFACT", "Plant an artifact (by name or path) this project doesn't have yet"
+      method_option :force, type: :boolean, default: false,
+        desc: "Skip the confirmation prompt when re-adding an ejected artifact, " \
+          "or overwrite an untracked file at the destination"
+      def add(artifact)
+        Commands::Add.new(self, source_root: source_root).call(artifact, force: options[:force])
+      end
+
+      desc "update", "Refresh managed artifacts from the current lyman release"
+      def update
+        Commands::Update.new(self, source_root: source_root).call
+      end
+
+      desc "eject ARTIFACT", "Take ownership of a managed artifact (by name or path)"
+      def eject(artifact)
+        Commands::Eject.new(self, source_root: source_root).call(artifact)
+      end
+
+      desc "diff ARTIFACT", "Show local and upstream changes for an artifact (by name or path)"
+      def diff(artifact)
+        Commands::Diff.new(self, source_root: source_root).call(artifact)
+      end
+
+      desc "doctor", "Smoke-test that the planted pipeline still runs"
+      def doctor
+        Commands::Doctor.new(self, source_root: source_root).call
+      end
+
+      desc "list", "List every artifact lyman knows how to install"
+      def list
+        manifest_root = Manifest.find
+        manifest = Manifest.load(manifest_root) if manifest_root
+
+        Registry::ARTIFACTS.each do |name, spec|
+          status =
+            if manifest
+              entry = manifest.artifact(name)
+              entry ? entry["status"] : "not planted"
+            end
+
+          line = "#{name} (#{spec[:role]}) #{spec[:dest]}#{" — #{status}" if status} — #{spec[:description]}"
+          say line
+        end
+      end
+
+      desc "version", "Print the lyman gem version"
+      def version
+        say VERSION
+      end
+
+      private
+
+      def source_root
+        ENV.fetch("LYMAN_SOURCE_ROOT", Registry::GEM_ROOT)
+      end
+    end
+  end
+end

data/lib/lyman/conversation.rb

@@ -0,0 +1,65 @@
+module Lyman
+  # The item that flows through the spine and the circuit: the whole
+  # conversation so far, plus the control data workers consult to decide
+  # *whether* to act (never *which of several things* to do).
+  #
+  # Messages use string keys throughout, for clean round-tripping with
+  # OpenAI-compatible wire formats.
+  class Conversation
+    attr_reader :messages
+    attr_accessor :rounds, :max_rounds
+
+    def initialize(system_prompt: nil, max_rounds: 10)
+      @messages = []
+      @messages << {"role" => "system", "content" => system_prompt} if system_prompt
+      @rounds = 0
+      @max_rounds = max_rounds
+      @finished = false
+    end
+
+    def add_user_message(text)
+      @messages << {"role" => "user", "content" => text}
+      @finished = false
+      @rounds = 0
+      self
+    end
+
+    def add_assistant_message(message)
+      @messages << message
+      self
+    end
+
+    def add_tool_result(tool_call_id, content)
+      @messages << {
+        "role" => "tool",
+        "tool_call_id" => tool_call_id,
+        "content" => content
+      }
+      self
+    end
+
+    def pending_tool_calls
+      last = @messages.last
+      return [] unless last && last["role"] == "assistant"
+      last["tool_calls"] || []
+    end
+
+    def last_assistant_content
+      message = @messages.rfind { |m| m["role"] == "assistant" }
+      message && message["content"]
+    end
+
+    def finish!
+      @finished = true
+      self
+    end
+
+    def finished?
+      @finished
+    end
+
+    def runaway?
+      @rounds >= @max_rounds
+    end
+  end
+end

data/lib/lyman/workers/chat_completion.rb

@@ -0,0 +1,154 @@
+require "shifty"
+require "net/http"
+require "json"
+require "uri"
+
+module Lyman
+  module Workers
+    extend Shifty::DSL
+
+    # Relay worker: sends the conversation to an OpenAI-compatible chat
+    # completions endpoint and appends the assistant's reply (which may
+    # include tool calls). Increments the conversation's round counter.
+    #
+    # Pass an on_delta callable to stream: it receives each content
+    # fragment as it arrives. The worker still returns the conversation
+    # with the fully-assembled message appended, so the circuit sees no
+    # difference between streamed and unstreamed rounds.
+    #
+    # Servers disagree about where thinking goes: some put <think> tags
+    # inline in the content, others (e.g. Ollama) stream a separate
+    # reasoning field. The worker normalizes the latter to the former,
+    # so on_delta always sees one convention: <think>...</think> inline.
+    # The raw reasoning text still lands on the message unaltered.
+    #
+    # This is the only part of lyman that knows HTTP exists.
+    def self.chat_completion(base_url:, model:, tools: nil, read_timeout: 300, on_delta: nil)
+      uri = URI("#{base_url.chomp("/")}/chat/completions")
+
+      relay_worker do |conversation|
+        payload = {"model" => model, "messages" => wire_messages(conversation.messages)}
+        payload["tools"] = tools if tools && !tools.empty?
+        payload["stream"] = true if on_delta
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.read_timeout = read_timeout
+
+        message =
+          if on_delta
+            stream_message(http, uri, payload, on_delta)
+          else
+            fetch_message(http, uri, payload)
+          end
+
+        conversation.add_assistant_message(message)
+        conversation.rounds += 1
+        conversation
+      end
+    end
+
+    # The conversation keeps each message's reasoning (it's useful to
+    # observability), but it never rides back to the model: providers
+    # either ignore it, reject it outright (DeepSeek), or would burn
+    # context re-reading thoughts the model already finished thinking.
+    def self.wire_messages(messages)
+      messages.map do |message|
+        message.reject { |key, _| key == "reasoning" || key == "reasoning_content" }
+      end
+    end
+
+    def self.fetch_message(http, uri, payload)
+      response = http.post(
+        uri.path,
+        JSON.generate(payload),
+        "Content-Type" => "application/json"
+      )
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise "chat completion failed (#{response.code}): #{response.body}"
+      end
+
+      message = JSON.parse(response.body).dig("choices", 0, "message")
+      raise "chat completion response had no message: #{response.body}" unless message
+      message
+    end
+
+    def self.stream_message(http, uri, payload, on_delta)
+      request = Net::HTTP::Post.new(uri.path, "Content-Type" => "application/json")
+      request.body = JSON.generate(payload)
+
+      message = {"role" => "assistant", "content" => nil}
+      tool_calls = {}
+      state = {thinking: false}
+      buffer = +""
+
+      http.request(request) do |response|
+        unless response.is_a?(Net::HTTPSuccess)
+          raise "chat completion failed (#{response.code}): #{response.read_body}"
+        end
+
+        response.read_body do |chunk|
+          buffer << chunk
+          # SSE events arrive as "data: {json}" lines, but chunks don't
+          # align with line boundaries.
+          while (newline = buffer.index("\n"))
+            line = buffer.slice!(0..newline).strip
+            next unless line.start_with?("data:")
+
+            data = line.delete_prefix("data:").strip
+            next if data == "[DONE]"
+
+            delta = JSON.parse(data).dig("choices", 0, "delta")
+            apply_delta(message, tool_calls, delta, on_delta, state) if delta
+          end
+        end
+      end
+
+      on_delta.call("</think>") if state[:thinking] # reasoning ran to stream end
+      unless tool_calls.empty?
+        message["tool_calls"] = tool_calls.keys.sort.map { |index| tool_calls[index] }
+      end
+      message
+    end
+
+    # Content deltas concatenate; tool-call deltas arrive as fragments
+    # keyed by index, with the arguments string dribbling in over many
+    # chunks. Reasoning-field deltas stream to on_delta wrapped in
+    # synthesized <think> tags (see chat_completion).
+    def self.apply_delta(message, tool_calls, delta, on_delta, state)
+      reasoning = delta["reasoning"] || delta["reasoning_content"]
+      if reasoning && !reasoning.empty?
+        unless state[:thinking]
+          state[:thinking] = true
+          on_delta.call("<think>")
+        end
+        message["reasoning"] = (message["reasoning"] || +"") + reasoning
+        on_delta.call(reasoning)
+      end
+
+      if (text = delta["content"]) && !text.empty?
+        if state[:thinking]
+          state[:thinking] = false
+          on_delta.call("</think>")
+        end
+        message["content"] = (message["content"] || +"") + text
+        on_delta.call(text)
+      end
+
+      (delta["tool_calls"] || []).each do |fragment|
+        entry = tool_calls[fragment["index"]] ||= {
+          "id" => nil,
+          "type" => "function",
+          "function" => {"name" => +"", "arguments" => +""}
+        }
+        entry["id"] = fragment["id"] if fragment["id"]
+        entry["type"] = fragment["type"] if fragment["type"]
+
+        function = fragment["function"] || {}
+        entry["function"]["name"] << function["name"] if function["name"]
+        entry["function"]["arguments"] << function["arguments"] if function["arguments"]
+      end
+    end
+  end
+end

data/lib/lyman/workers/tool_execution.rb

@@ -0,0 +1,47 @@
+require "shifty"
+require "json"
+
+module Lyman
+  module Workers
+    extend Shifty::DSL
+
+    # Relay worker: executes any tool calls pending on the conversation and
+    # appends their results. Acts only when the turn isn't already finished
+    # and the model has asked for tools; otherwise passes through.
+    #
+    # +handlers+ is a hash of tool name => callable taking a Hash of
+    # arguments and returning something stringable.
+    def self.tool_execution(handlers)
+      relay_worker do |conversation|
+        unless conversation.finished?
+          conversation.pending_tool_calls.each do |tool_call|
+            name = tool_call.dig("function", "name")
+            args = parse_arguments(tool_call.dig("function", "arguments"))
+            handler = handlers[name]
+
+            result =
+              if handler
+                begin
+                  handler.call(args).to_s
+                rescue => e
+                  "Tool #{name} raised #{e.class}: #{e.message}"
+                end
+              else
+                "Unknown tool: #{name}"
+              end
+
+            conversation.add_tool_result(tool_call["id"], result)
+          end
+        end
+        conversation
+      end
+    end
+
+    def self.parse_arguments(raw)
+      return raw if raw.is_a?(Hash)
+      JSON.parse(raw.to_s)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/lyman.rb

@@ -0,0 +1,8 @@
+require "shifty"
+
+require_relative "lyman/conversation"
+require_relative "lyman/workers/chat_completion"
+require_relative "lyman/workers/tool_execution"
+
+module Lyman
+end

data/templates/CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This project was scaffolded by [lyman](https://github.com/joelhelbling/lyman):
+an agentic harness built on the [shifty](https://github.com/joelhelbling/shifty)
+gem's pipeline-of-workers model. `harness/chat.rb` wires a model⇄tool loop
+against any OpenAI-compatible chat completions endpoint (Ollama by default).
+
+## Running it
+
+- `bundle install` — install dependencies (just `shifty` and `ostruct`; this
+  project has no runtime dependency on the `lyman` gem itself).
+- `ruby harness/chat.rb` — run the interactive chat harness. Defaults to
+  Ollama at `http://localhost:11434/v1`; override with `LYMAN_MODEL` and
+  `LYMAN_BASE_URL` env vars.
+
+## The managed/owned boundary
+
+Everything under the `Lyman::` namespace (`lib/lyman.rb`, `lib/lyman/`) is
+**managed** by the lyman CLI: it was planted here, and `lyman update` can
+refresh it from newer lyman releases. Treat it as a library to extend, not a
+file to hand-edit — if you need to change one, run `lyman eject <name>` first,
+which takes ownership explicitly rather than leaving it silently forked.
+`.lyman/manifest.yml` is the record of what's managed, what's owned, and what
+you've ejected; commit it.
+
+`harness/chat.rb` and everything outside `Lyman::` is **owned** — yours from
+day one, never touched by `lyman update`. Put your own workers in your own
+namespace or directory, not inside `lib/lyman/`.
+
+## Four load-bearing facts
+
+1. **The nil-source footgun.** In shifty, a source returning `nil` ends the
+   stream permanently. If you're driving a pipeline off a queue, enqueue
+   before you shift — never pull a source worker while its queue is empty.
+
+2. **The runaway-turn guard.** The model⇄tool circuit is bounded by
+   `Conversation#runaway?` / `max_rounds`. Keep that guard intact when
+   rewiring the circuit; without it, a model that keeps calling tools never
+   lets a turn end.
+
+3. **Item-as-control discipline.** An item may tell a worker *whether* to
+   act, never *which of several things* to do. A worker that switches
+   between jobs based on item state is the anti-pattern to avoid
+   (multi-way dispatch) — split it into stages, or use a splitter, instead.
+
+4. **Wire vs. conversation.** Reasoning/thinking content stays on messages in
+   the `Conversation` for observability, but `Workers.wire_messages` strips
+   it before anything goes out over the wire. Preserve that separation if
+   you touch message handling.
+
+## Other conventions
+
+- `lyman doctor` smoke-tests the pipeline end to end against a stub
+  transport — run it after `lyman update` or whenever something feels off.
+- `lyman list` shows what's managed, owned, or ejected in this project.
+- Messages use string keys throughout, matching the OpenAI-compatible wire
+  format — no symbol-key message hashes.

data/templates/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gem "shifty"
+gem "ostruct" # shifty dependency; no longer a default gem as of ruby 4.0

data/templates/gitignore

@@ -0,0 +1,5 @@
+*.gem
+.DS_Store
+
+# .lyman/ is project state (the manifest + pristine copies), not build
+# output — it belongs in git, not here.

data/templates/lib_lyman.rb

@@ -0,0 +1,8 @@
+require "shifty"
+
+# Every planted module under lib/lyman/ loads here. `lyman add` drops new
+# modules in place without this file ever needing an edit.
+Dir[File.join(__dir__, "lyman", "**", "*.rb")].sort.each { |file| require file }
+
+module Lyman
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: lyman
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joel Helbling
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: shifty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+email:
+- joel.helbling@gmail.com
+executables:
+- lyman
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- docs/design/circuit-pattern.md
+- docs/design/deployment.md
+- docs/vision.md
+- exe/lyman
+- harness/chat.rb
+- lib/lyman.rb
+- lib/lyman/cli.rb
+- lib/lyman/cli/commands/add.rb
+- lib/lyman/cli/commands/diff.rb
+- lib/lyman/cli/commands/doctor.rb
+- lib/lyman/cli/commands/eject.rb
+- lib/lyman/cli/commands/new.rb
+- lib/lyman/cli/commands/update.rb
+- lib/lyman/cli/doctor_check.rb
+- lib/lyman/cli/manifest.rb
+- lib/lyman/cli/planter.rb
+- lib/lyman/cli/registry.rb
+- lib/lyman/cli/version.rb
+- lib/lyman/conversation.rb
+- lib/lyman/workers/chat_completion.rb
+- lib/lyman/workers/tool_execution.rb
+- templates/CLAUDE.md
+- templates/Gemfile
+- templates/gitignore
+- templates/lib_lyman.rb
+homepage: https://github.com/joelhelbling/lyman
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/joelhelbling/lyman
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: A composable agentic harness, delivered as code you own — a pure generator
+  in the shadcn/ui mold, built on shifty
+test_files: []