agentilda 1.0.3

data/lib/agentilda/cli/base.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # Shared flags and the plumbing every command needs.
+    class Base < Dry::CLI::Command
+      include UI
+
+      def self.inherited(klass)
+        super
+        klass.option :dir, default: Agentilda::PLANS_DIR, aliases: ["-D"],
+          desc: "The .plans directory"
+        klass.option :quiet, type: :boolean, default: false, aliases: ["-q"],
+          desc: "Suppress progress output on STDERR"
+      end
+
+      private
+
+      # @param options [Hash]
+      # @return [Agentilda::Tree]
+      def tree_for(options)
+        tree = Tree.new(dir: options.fetch(:dir, Agentilda::PLANS_DIR))
+        unless tree.exist?
+          refuse("No #{Agentilda::PLANS_DIR} directory at\n#{tree.dir}\n\n" \
+                 "Run this from the project root, or pass -D.", 66)
+        end
+        tree
+      end
+
+      # Report and stop, in the shape every refusal here takes. The statuses
+      # follow sysexits where one fits: 64 usage, 65 bad data, 66 no input,
+      # 69 a service (GitHub, Linear) refused us.
+      #
+      # @param message [String]
+      # @param status [Integer]
+      # @return [void] never returns
+      def refuse(message, status)
+        error(message)
+        exit status
+      end
+
+      # @param options [Hash]
+      # @return [Boolean]
+      def quiet?(options)
+        quiet = options.fetch(:quiet, false)
+        UI.quiet = quiet
+        quiet
+      end
+
+      # @param options [Hash]
+      # @return [Boolean]
+      def commit?(options) = options.fetch(:commit, false)
+
+      # `claude` prefers a credential in the environment to a claude.ai login,
+      # so a project `.env` that direnv loads on `cd` can redirect every agent
+      # a run spawns to a key meant for the application itself.
+      #
+      # Say it once, before the run starts, because the failure arrives three
+      # minutes later, once per agent, and reads like an agent problem rather
+      # than an environment one.
+      #
+      # @return [void]
+      def credentials_warning
+        names = Executor.foreign_credentials
+        return if names.empty?
+
+        one = names.size == 1
+        warn("#{names.join(" and ")} #{one ? "is" : "are"} set in this shell, so every agent authenticates " \
+             "with #{one ? "it" : "them"} rather than with your claude.ai login.\n" \
+             "A stale one fails every agent in the run with `401 API key is invalid`, " \
+             "three minutes at a time.\n" \
+             "If it came from a project .env, run `unset #{names.join(" ")}` first.")
+      end
+
+      # The line every dry run ends with, so nobody mistakes a preview for the
+      # thing having happened.
+      #
+      # @param count [Integer] how much work is pending
+      # @param what [String]
+      # @return [void]
+      def dry_run_footer(count, what)
+        return if count.zero?
+
+        warn("#{count} #{what} pending — nothing was changed.\nRe-run with --commit to apply.")
+      end
+    end
+  end
+end

data/lib/agentilda/cli/create/create.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda create <words…>` — backs /spec-create.
+    class Create < Base
+      desc "Create the next numbered plan folder"
+
+      argument :words,
+        type: :array,
+        required: false,
+        default: [],
+        desc:
+          "The topic, two to five words; becomes the folder slug. Omit when --from names it"
+
+      option :from,
+        aliases: ["-f"],
+        desc:
+          "Seed from a markdown file: its frontmatter `title:` names the folder, and its body fills the spec."
+      option :after,
+        aliases: ["-a"],
+        desc:
+          "Create a retroactive plan in the gap after this plan, e.g. 002"
+      option :status,
+        aliases: ["-s"],
+        desc: "Open in a state other than the default"
+      option :prs,
+        aliases: ["--pr"],
+        desc:
+          "Document work that already shipped: pull request numbers or URLs, comma separated. Requires --after"
+      option :spec,
+        type: :boolean,
+        default: true,
+        desc:
+          "With --prs, write spec.md from what the pull requests did. --no-spec records them and stops, which is fast and offline"
+      option :draft,
+        type: :boolean,
+        default: true,
+        desc:
+          "For a new feature (no --prs), attempt spec.md's four headings from project context via `claude`. --no-draft leaves them bare"
+      option :open,
+        type: :boolean,
+        default: true,
+        desc:
+          "Open the new spec.md in the system editor when done (macOS `open`). --no-open leaves it for you to open"
+
+      # noinspection RubyMismatchedArgumentType
+      example [
+        "tax rule dsl                        # 003.00-⚪️--tax-rule-dsl, spec.md scaffolded and drafted",
+        "tax rule dsl --no-draft --no-open   # scaffold only, nothing shelled out, nothing opened",
+        "--after 002 schedule k1             # 002.01-🕰️-schedule-k1 (documented after the fact)",
+        "--after 018 --prs 12,15 verify      # …and write spec.md from what those PRs did",
+        "--after 018 --pr https://…/pull/12 verify # verify the pull request by number or URL",
+        "--status ready billing sync         # opens at ⭐️ instead of ⚪️",
+        "--from notes/tax-dsl.md             # title and opening prose from the file's frontmatter and body"
+      ]
+
+      # @param words [Array<String>]
+      # @param options [Hash]
+      # @return [void]
+      def call(words:, **options)
+        dir = options.fetch(:dir, Agentilda::PLANS_DIR)
+        FileUtils.mkdir_p(dir)
+
+        words, seed = resolve_seed(words, options)
+        prs = fetch_prs(options)
+        result =
+          Creator.new(dir:).create(
+            words:,
+            after: options[:after],
+            status: options[:status],
+            prs:
+          )
+
+        result.either(
+          ->(path) { created(path, prs, options, seed:) },
+          ->(message) { refuse("Could not create the plan:\n#{message}", 65) }
+        )
+      end
+
+      private
+
+      # `--from FILE` trades the words argument for a markdown file: the
+      # frontmatter's `title:` names the folder, and the body travels on to
+      # {Brief} as the author's own opening statement. Words and a file are
+      # two answers to one question — the folder's name — so holding both is
+      # refused rather than silently ranked.
+      #
+      # @param words [Array<String>]
+      # @param options [Hash]
+      # @return [Array(Array<String>, String, nil)] the slug words, and the
+      #   seed body when a file supplied them
+      def resolve_seed(words, options)
+        file = options[:from]
+        return words, nil unless file
+
+        unless words.empty?
+          refuse(
+            "--from names the topic by its frontmatter title;\n" \
+              "drop the words, or drop --from",
+            64
+          )
+        end
+        if options[:prs]
+          refuse(
+            "--prs reconstructs spec.md from the pull requests, so a seed file\n" \
+              "would be ignored; use one or the other",
+            64
+          )
+        end
+        unless File.file?(file)
+          refuse("Could not read the seed file:\n#{file} does not exist", 66)
+        end
+
+        title, body = parse_seed(File.read(file, encoding: "UTF-8"))
+        if title.to_s.strip.empty?
+          refuse(
+            "The seed file needs a frontmatter title, e.g.\n" \
+              "---\ntitle: Tax Rule DSL\n---",
+            65
+          )
+        end
+
+        [title.split, body]
+      end
+
+      # Frontmatter that will not parse used to be reported as a missing
+      # title, which sends the author looking for a `title:` line that is
+      # sitting right there. Say which of the two actually went wrong.
+      #
+      # @param content [String]
+      # @return [Array(String, String)] title and body
+      def parse_seed(content)
+        meta, body = Frontmatter.split(content)
+        [meta["title"].to_s, body.strip]
+      rescue Psych::Exception => e
+        refuse(
+          "The seed file's frontmatter is not valid YAML:\n#{e.message}",
+          65
+        )
+      end
+
+      # A retroactive plan documents work that landed *somewhere* in the
+      # sequence, and only its author knows where. Guessing would put the
+      # number — the one thing that never changes — in the wrong place.
+      #
+      # @param options [Hash]
+      # @return [Array<Hash>, nil]
+      def fetch_prs(options)
+        return nil unless options[:prs]
+
+        unless options[:after]
+          refuse(
+            "--prs documents work that already shipped;\n" \
+              "name the plan it landed after with --after, e.g. --after 018",
+            64
+          )
+        end
+
+        GitHub.new.pull_requests(GitHub.parse_refs(options[:prs]))
+      rescue Agentilda::Error => e
+        refuse("Could not read the pull requests:\n#{e.message}", 65)
+      end
+
+      # A plan with recorded pull requests already has its facts — hand it to
+      # the writer that reconstructs a specification from a diff. One without
+      # them does not exist yet, and reconstructing is not the job; {#brief} is.
+      #
+      # @param path [String]
+      # @param prs [Array<Hash>, nil]
+      # @param options [Hash]
+      # @return [void]
+      def created(path, prs, options, seed: nil)
+        from_prs = prs && !prs.empty?
+        path =
+          if from_prs
+            synthesize(path, options) if options.fetch(:spec, true)
+          else
+            brief(path, options, seed:)
+          end || path
+        puts path
+        return if quiet?(options)
+
+        feature = Feature.parse(path)
+        success(
+          "Created #{File.basename(path)}\n\n" \
+            "#{feature.status.emoji} #{feature.status.label} — #{feature.status.note}\n" \
+            "#{next_step(path, feature, from_prs:)}"
+        )
+      end
+
+      # Hand the folder to the writer that already knows how to write a
+      # retroactive specification, then let `resync dirs` decide what the
+      # folder has become — 🕰️ is only true while there is no `spec.md`.
+      #
+      # @param path [String]
+      # @param options [Hash]
+      # @return [String] the folder's path, which the resync may have renamed
+      def synthesize(path, options)
+        agent = Agentilda::Agents.new.find(Agentilda::RETROACTIVE_WRITER) or
+          return path
+        root = options[:root] || File.dirname(path, 2)
+
+        ok, note =
+          UI.spinning("Writing spec.md from #{UI.paint(File.basename(path).to_s, :yellow)}") do
+            Executor.new(root:).call(agent, Subject.new(Feature.parse(path)))
+          end
+        warn_about(note) unless ok
+
+        settle(path)
+      end
+
+      # A folder with no pull requests to reconstruct from is a feature that
+      # does not exist yet. {Brief} writes the four headings a human still has
+      # to answer, makes a best-effort pass at them from what the project
+      # already has on disk, and — unless told not to — opens the result for
+      # a human to finish. The folder's state never moves: ⚪️ New only ever
+      # claimed that a specification exists, not that it is complete.
+      #
+      # @param path [String] the path to the folder
+      # @param seed [String, nil] the seed body from the `--from` file
+      # @param options [Hash] the options hash
+      # @return [String] +path+, unchanged
+      def brief(path, options, seed: nil)
+        feature = Feature.parse(path)
+        return path if feature.status.key == :retroactive
+
+        root = options[:root] || File.dirname(path, 2)
+        brief = Brief.new(path:, title: feature.title, root:, seed:)
+        brief.write_scaffold!
+
+        if options.fetch(:draft, true)
+          # Painted the way Runner::Task#label paints a roster agent, so the
+          # half-agent reads as one of them on the terminal.
+          label =
+            "#{UI.paint(Brief::AGENT_NAME, :yellow, :bold)} drafting spec.md from #{seed}"
+          ok, note = UI.spinning(label) { brief.attempt! }
+          warn_about_draft(note) unless ok
+        end
+
+        open_spec(brief.spec_path) if options.fetch(:open, true)
+        path
+      end
+
+      # @param spec_path [String]
+      # @return [void]
+      def open_spec(spec_path)
+        return unless macos?
+
+        system("open", spec_path, out: File::NULL, err: File::NULL)
+      end
+
+      # `open` is a macOS command; anywhere else the viewer step is skipped
+      # rather than failed. A named seam so a spec can assert the viewer was
+      # asked for without inheriting the platform CI happens to run on.
+      #
+      # @return [Boolean]
+      def macos? = RbConfig::CONFIG["host_os"].to_s.match?(/darwin/)
+
+      # @param path [String]
+      # @return [String] where the folder ended up
+      def settle(path)
+        tree = Tree.new(dir: File.dirname(path))
+        change =
+          Agentilda::Resync::Dirs
+            .new(tree:)
+            .call(commit: true)
+            .find { |c| c.source == path }
+        change ? change.target : path
+      end
+
+      # @param note [String]
+      # @return [void]
+      def warn_about(note)
+        error(
+          "The folder was created, but spec.md was not written:\n#{note}\n\n" \
+            "The pull requests are recorded. Run `agentilda run --commit` to retry."
+        )
+      end
+
+      # @param note [String]
+      # @return [void]
+      def warn_about_draft(note)
+        error(
+          "spec.md was scaffolded, but the drafting attempt did not finish:\n#{note}\n\n" \
+            "The four headings are there, empty. Fill them in by hand, or hand off to leah-researcher."
+        )
+      end
+
+      # @param path [String]
+      # @param feature [Agentilda::Feature]
+      # @return [String]
+      def next_step(path, feature, from_prs:)
+        spec = File.join(File.basename(path), "spec.md")
+        unless feature.status.key == :new &&
+            File.file?(File.join(path, "spec.md"))
+          return "Next: write #{spec}"
+        end
+        if from_prs
+          return (
+            "Next: read #{spec} — it was written from the pull requests, so check it against what actually shipped"
+          )
+        end
+
+        "Next: fill in the four headings in #{spec}, then hand off to leah-researcher"
+      end
+    end
+  end
+end

data/lib/agentilda/cli/docs/docs.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda docs` — regenerate the conventions document.
+    class Docs < Base
+      desc "Generate the conventions document from the state machine itself"
+
+      option :output, aliases: ["-o"], desc: "Write here instead of STDOUT",
+        default: "#{ENV["HOME"]}/.agents/context/workflow.md"
+
+      example ["", "-o ~/.agents/context/workflow.md"]
+
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        document = Documentation.new.render
+
+        if (path = options[:output])
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, document)
+          system("command -v mdformat>/dev/null 2>&1 && mdformat --wrap no #{path} 2>/dev/null")
+          success("created workflow description in [#{path}]") unless quiet?(options)
+        else
+          $stdout.write(document)
+        end
+      end
+    end
+  end
+end

data/lib/agentilda/cli/index/index.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda index` — the plans as one browsable page.
+    class Index < Base
+      desc "Create or update .plans/INDEX.md — a global index of every plan."
+
+      option :output, aliases: ["-o"],
+        desc: "Write somewhere other than <plans>/INDEX.md; - for STDOUT"
+      option :project, aliases: ["-p"],
+        desc: "Heading for the page, default: the repository's directory name"
+
+      example [
+        "                     # write .plans/INDEX.md",
+        "-o -                 # print it instead",
+        "-p 'Equilibris App'  # override the heading"
+      ]
+
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        index = Agentilda::Index.new(tree: tree_for(options), project: options[:project])
+
+        if options[:output] == "-"
+          $stdout.write(index.render)
+          return
+        end
+
+        path = index.write(options[:output])
+        puts path
+        return if quiet?(options)
+
+        success("Wrote #{path}\n\nRegenerate it after any `resync dirs`, which renames folders\nand would otherwise leave every link here pointing at nothing.")
+      end
+    end
+  end
+end

data/lib/agentilda/cli/linear/linear.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda linear …`
+    module Linear
+      # Shared by both linear commands: the team is which workspace this is
+      # about, so it is an argument rather than a flag. There is no default —
+      # a tool that picks a team for you when you forget to say which is a
+      # tool that files a quarter of somebody's work in the wrong place.
+      class Team < Base
+        def self.inherited(klass)
+          super
+          klass.argument :team, required: true,
+            desc: "The Linear team key that prefixes its issues, e.g. TAX"
+        end
+
+        private
+
+        # The key is checked before anything reaches for a token, so a typo in
+        # the team name reports the typo rather than an authentication
+        # problem the user does not have.
+        #
+        # @param team [String]
+        # @return [Agentilda::Linear::Survey]
+        def survey_for(team, tree)
+          key = Agentilda::Linear.key!(team)
+          api = Agentilda::Linear::API.new(token: Agentilda::Linear::API.token_from_env)
+          projects = UI.spinning("Listing #{key} projects") { api.projects(api.team(key)[:id]) }
+          [api, Agentilda::Linear::Survey.new(tree:, projects:)]
+        end
+      end
+    end
+  end
+end

data/lib/agentilda/cli/linear/subcommands/import.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda linear …`
+    module Linear
+      # `linear import` — the plans, as Linear issues under one of your projects.
+      class Import < Team
+        desc "Create Linear issues from the plans: one per folder, one child per work unit"
+
+        option :project, aliases: ["-p", "--project-url", "--project-id"],
+          desc: "The project to file everything under: its URL, its name, or its id"
+        option :commit, type: :boolean, default: false,
+          desc: "Actually create and update in Linear (default: dry run)"
+        option :format, default: "text", values: %w[text json],
+          desc: "json emits the exact arguments the Linear MCP tools take"
+        option :since, aliases: ["-s"],
+          desc: "Skip plans numbered below this, e.g. 010.00"
+        option :status,
+          desc: "Only plans in these states: a comma-separated list of status keys"
+        option :force, type: :boolean, default: false,
+          desc: "Update everything, whether the plan has changed or not"
+
+        example [
+          "TAX -p 'US Tax Law: Self Contained Ruby Gem'   # show what would be created",
+          "TAX -p https://linear.app/acme/project/…       # a URL works too",
+          "TAX -p 'Ruby Gem' --commit                     # do it, using LINEAR_API_KEY",
+          "TAX -p 'Ruby Gem' --format json                # hand it to the MCP transport instead",
+          "TAX -p 'Ruby Gem' --since 010.00               # only the recent plans",
+          "TAX -p 'Ruby Gem' --status building,in_review"
+        ]
+
+        # @param team [String]
+        # @param options [Hash]
+        # @return [void]
+        def call(team:, **options)
+          tree = tree_for(options)
+          require_project!(options)
+          import = build(tree, team, resolve_project(team, tree, options), options)
+
+          return $stdout.puts(import.to_json) if options[:format] == "json"
+
+          if import.pending.empty?
+            success("Linear is already in step with #{tree.dir}.") unless quiet?(options)
+            return
+          end
+
+          preview(import, options)
+        rescue Agentilda::Error => e
+          refuse(e.message, 69)
+        end
+
+        private
+
+        # Looking the project up costs a token, and the whole point of
+        # `--format json` is to work without one. A name needs no lookup — the
+        # MCP server resolves a project by name itself — so only a URL or an
+        # id, which do not carry a name, force the network.
+        #
+        # @return [Hash] `{"id", "name", "url"}`
+        def resolve_project(team, tree, options)
+          reference = options[:project].to_s
+          looks_up = reference.match?(%r{\Ahttps?://}) || reference.match?(/\A[0-9a-f-]{32,}\z/)
+          return {"id" => nil, "name" => reference, "url" => nil} if !looks_up && offline?
+
+          _api, survey = survey_for(team, tree)
+          survey.project(reference)
+        end
+
+        # @return [Boolean]
+        def offline? = Agentilda::Linear::API.token_from_env.nil?
+
+        # @param options [Hash]
+        # @return [void]
+        def require_project!(options)
+          return if options[:project]
+
+          raise Agentilda::Error,
+            "which project? Pass -p with a project's URL, name or id.\n\n" \
+            "This never creates one: a team's project list is something you curated, and " \
+            "every plan is filed under one you named.\n\n  " \
+            "agentilda linear projects <TEAM>   lists them"
+        end
+
+        # @return [Agentilda::Linear::Import]
+        def build(tree, team, project, options)
+          Agentilda::Linear::Import.new(tree:, team: Agentilda::Linear.key!(team), project:,
+            since: options[:since], statuses: statuses(options),
+            force: options.fetch(:force, false))
+        end
+
+        # @param options [Hash]
+        # @return [Array<Symbol>, nil]
+        def statuses(options)
+          return nil unless options[:status]
+
+          options[:status].to_s.split(",").map { |word|
+            Agentilda.status(word.strip)&.key ||
+              raise(Agentilda::Error, "no such state: #{word.strip}")
+          }
+        end
+
+        # @param import [Agentilda::Linear::Import]
+        # @param options [Hash]
+        # @return [void]
+        def preview(import, options)
+          import.pending.each { |action| puts row(action) }
+          return if quiet?(options)
+
+          import.pending.each { |action| say(line(action)) }
+          report_unplaced(import)
+          dry_run_footer(import.pending.size, "Linear change#{"s" unless import.pending.size == 1}")
+        end
+
+        # @param action [Agentilda::Linear::Action]
+        # @return [String]
+        def row(action)
+          [action.op, action.kind, action.ordinal, action.unit || "-",
+            action.identifier || "-", action.title].join("\t")
+        end
+
+        # @param action [Agentilda::Linear::Action]
+        # @return [String]
+        def line(action)
+          verb = paint(action.op.to_s.ljust(6), (action.op == :create) ? :green : :yellow)
+          indent = action.child? ? "    " : ""
+          "#{verb} #{indent}#{action.title}  #{paint("(#{action.reason})", :bright_black)}"
+        end
+
+        # @param import [Agentilda::Linear::Import]
+        # @return [void]
+        def report_unplaced(import)
+          return if import.unplaced.empty?
+
+          listed = import.unplaced.map { |status, ordinals|
+            "  #{status} — #{ordinals.join(", ")}\n#{wrapped(Agentilda::Linear.reason_unplaced(status))}"
+          }
+          warn("Not imported, because nothing here knows where they belong:\n\n" \
+               "#{listed.join("\n\n")}\n\n" \
+               "Decide where they go on your board and add it to Linear::PLACEMENTS.")
+        end
+
+        # A box re-wraps a line that overruns it, and the wrapped remainder
+        # comes back at column zero — which reads as a new entry rather than
+        # the continuation of one. Wrapping it here keeps the indent.
+        #
+        # @param text [String]
+        # @param width [Integer] narrower than the narrowest box
+        # @return [String]
+        def wrapped(text, width: 58)
+          text.split.each_with_object([+""]) { |word, lines|
+            lines << +"" if lines.last.length + word.length + 1 > width
+            lines.last << " " unless lines.last.empty?
+            lines.last << word
+          }.map { |line| "    #{line}" }.join("\n")
+        end
+      end
+    end
+  end
+end