agentilda 1.0.3

data/lib/agentilda/linear/import.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Agentilda
+  module Linear
+    # One thing that would happen in Linear.
+    #
+    # `args` is deliberately shaped as the Linear MCP server's `save_issue`
+    # arguments, because that server addresses everything by
+    # the names a human already knows — a team by its key, a project by its
+    # name, a workflow state by its name, an issue by its identifier. Emitting
+    # exactly that shape means the JSON this produces can drive either
+    # transport unchanged: {Push} turns it into GraphQL, and the skill hands
+    # it to the MCP tools as-is. One contract, so the two cannot drift.
+    #
+    # @!attribute [r] kind
+    #   @return [Symbol] `:issue` for a plan, `:subissue` for a unit of one
+    # @!attribute [r] op
+    #   @return [Symbol] `:create`, `:update` or `:skip`
+    # @!attribute [r] ordinal
+    #   @return [String] the plan this belongs to, e.g. "003.00"
+    # @!attribute [r] unit
+    #   @return [String, nil] the {Unit#key}, nil for a plan's own issue
+    # @!attribute [r] identifier
+    #   @return [String, nil] what Linear already calls it, when it exists
+    # @!attribute [r] title
+    #   @return [String] for the human reading the dry run
+    # @!attribute [r] digest
+    #   @return [String] fingerprint of `args`, recorded after a push
+    # @!attribute [r] args
+    #   @return [Hash] the MCP argument shape
+    # @!attribute [r] reason
+    #   @return [String] why this operation and not another
+    Action = Data.define(:kind, :op, :ordinal, :unit, :identifier, :title, :digest, :args, :reason) do
+      # @return [Boolean] whether this would change anything
+      def pending? = op != :skip
+
+      # @return [Boolean] whether this issue hangs off another
+      def child? = kind == :subissue
+
+      # @return [Hash] for `--format json`
+      def to_h_json
+        {kind:, op:, plan: ordinal, unit:, identifier:, title:, digest:, args:}.compact
+      end
+    end
+
+    # What a plan folder would become in Linear, and what has already become
+    # of it. Reads the filesystem; touches nothing else.
+    #
+    # One folder is one issue, and the units inside its `plan.md` are that
+    # issue's children. Projects are never created: a team's project list is
+    # something a human curated, and every plan is filed under one the caller
+    # named on the command line.
+    #
+    # Keeping the whole decision offline is what makes `--commit` honest. The
+    # dry run is not an approximation of what a push would do — it is the same
+    # object the push consumes, so what gets printed and what gets sent cannot
+    # disagree. Everything that needs the network — the project, the repository
+    # pull request list — is handed in.
+    class Import
+      # @param tree [Agentilda::Tree]
+      # @param team [String] the team key, e.g. "TAX"
+      # @param project [Hash] the Linear project, `{"id", "name", "url"}`
+      # @param adopted [Hash{String => Array<Agentilda::PullRequest>}]
+      #   pull requests {Attribution} placed, by folder name
+      # @param since [String, nil] skip plans numbered below this
+      # @param statuses [Array<Symbol>, nil] only these states
+      # @param force [Boolean] update everything, matching digest or not
+      def initialize(tree:, team:, project:, adopted: {}, since: nil, statuses: nil, force: false)
+        @tree = tree
+        @team = team.to_s.strip.upcase
+        @project = project
+        @adopted = adopted
+        @since = since && Ordinal.parse(since)
+        @statuses = statuses
+        @force = force
+      end
+
+      # @return [String] the team key
+      attr_reader :team
+
+      # @return [Hash] the project everything is filed under
+      attr_reader :project
+
+      # @return [String]
+      def project_name = project["name"].to_s
+
+      # @return [Array<Agentilda::Linear::Action>] each plan's issue,
+      #   followed by that issue's children
+      def actions = @actions ||= subjects.flat_map { |s| actions_for(s) }
+
+      # @return [Array<Agentilda::Linear::Action>]
+      def pending = actions.select(&:pending?)
+
+      # @return [String] the whole import, for a pipe
+      def to_json(*_args)
+        JSON.pretty_generate(team:, project: project_name, actions: actions.map(&:to_h_json))
+      end
+
+      # Plans in a state nobody has decided how to file, and why not.
+      #
+      # @return [Hash{Agentilda::Status => Array<String>}] state => ordinals
+      def unplaced
+        @unplaced ||= (chosen - subjects).group_by(&:status)
+          .transform_values { |group| group.map { |s| s.feature.ordinal.to_s } }
+      end
+
+      private
+
+      # @return [Agentilda::Tree]
+      attr_reader :tree
+
+      # @return [Hash]
+      attr_reader :adopted
+
+      # @return [Agentilda::Ordinal, nil]
+      attr_reader :since
+
+      # @return [Array<Symbol>, nil]
+      attr_reader :statuses
+
+      # @return [Boolean]
+      attr_reader :force
+
+      # @return [Array<Agentilda::Subject>]
+      def subjects = @subjects ||= chosen.select { |s| Agentilda::Linear.placement(s.status) }
+
+      # @return [Array<Agentilda::Subject>] before the placement question
+      def chosen
+        @chosen ||= tree.subjects.select { |s|
+          (since.nil? || s.feature.ordinal >= since) &&
+            (statuses.nil? || statuses.include?(s.status.key))
+        }
+      end
+
+      # The units a plan's issue will have children for: the ones its
+      # `plan.md` declares, plus any pull request {Attribution} placed here
+      # that none of them already claims.
+      #
+      # @param subject [Agentilda::Subject]
+      # @return [Array<Agentilda::Linear::Unit>]
+      def units_for(subject)
+        (@units ||= {})[subject.feature.path] ||= begin
+          declared = Units.new(subject:).all
+          claimed = declared.flat_map(&:pull_requests).map(&:number)
+          extra = adopted.fetch(subject.feature.dirname, []).reject { |pr| claimed.include?(pr.number) }
+          declared + extra.map { |pr| adopted_unit(pr) }
+        end
+      end
+
+      # @param pull [Agentilda::PullRequest]
+      # @return [Agentilda::Linear::Unit]
+      def adopted_unit(pull)
+        Unit.new(key: "##{pull.number}", title: Units.clean_title(pull.title),
+          body: "", pull_requests: [pull])
+      end
+
+      # @param subject [Agentilda::Subject]
+      # @return [Agentilda::Linear::Issues]
+      def record_for(subject) = (@records ||= {})[subject.feature.path] ||= Issues.new(dir: subject.feature.path)
+
+      # @param subject [Agentilda::Subject]
+      # @return [Array<Agentilda::Linear::Action>]
+      def actions_for(subject)
+        [plan_action(subject)] + units_for(subject).map { |unit| unit_action(subject, unit) }
+      end
+
+      # The issue that stands for the whole plan folder.
+      #
+      # @param subject [Agentilda::Subject]
+      # @return [Agentilda::Linear::Action]
+      def plan_action(subject)
+        placement = Agentilda::Linear.placement(subject.status)
+        recorded = record_for(subject).by_unit[Issues::PARENT]
+        title = plan_title(subject)
+
+        args = {team:, project: project_name, title:, description: plan_description(subject),
+                state: placement.name, labels: placement.labels}
+        digest = Issues.digest(args)
+
+        op, reason = decide(recorded&.identifier, recorded&.digest, digest)
+        args = args.merge(id: recorded.identifier).except(:team, :project) if op == :update && recorded
+
+        Action.new(kind: :issue, op:, ordinal: subject.feature.ordinal.to_s, unit: Issues::PARENT,
+          identifier: recorded&.identifier, title:, digest:, args:, reason:)
+      end
+
+      # @param subject [Agentilda::Subject]
+      # @param unit [Agentilda::Linear::Unit]
+      # @return [Agentilda::Linear::Action]
+      def unit_action(subject, unit)
+        placement = Agentilda::Linear.placement_for(subject.status, unit.pull_requests)
+        recorded = record_for(subject).by_unit[unit.key]
+        parent = record_for(subject).by_unit[Issues::PARENT]
+
+        args = {team:, project: project_name, title: unit.title,
+                description: unit_description(subject, unit),
+                state: placement.name, labels: placement.labels, links: links_for(unit)}
+        args = args.merge(parentId: parent.identifier) if parent
+        digest = Issues.digest(args.except(:parentId))
+
+        op, reason = decide(recorded&.identifier, recorded&.digest, digest)
+        args = args.merge(id: recorded.identifier).except(:team, :project) if op == :update && recorded
+
+        Action.new(kind: :subissue, op:, ordinal: subject.feature.ordinal.to_s, unit: unit.key,
+          identifier: recorded&.identifier, title: unit.title, digest:, args:, reason:)
+      end
+
+      # The three-way decision, in one place so a plan and a unit cannot
+      # answer it differently.
+      #
+      # @param existing [String, nil] what Linear already calls it
+      # @param was [String, nil] the digest recorded at the last push
+      # @param now [String] the digest of what we would push
+      # @return [Array(Symbol, String)] the operation and its reason
+      def decide(existing, was, now)
+        return [:create, "not recorded in #{Issues::FILENAME}"] if existing.nil?
+        return [:update, "--force"] if force
+        return [:skip, "unchanged since the last import"] if was == now
+
+        [:update, "the plan has changed since #{existing} was pushed"]
+      end
+
+      # @param subject [Agentilda::Subject]
+      # @return [String]
+      def plan_title(subject) = "[#{subject.feature.ordinal}] #{heading(subject)}"
+
+      # The specification's own H1 when it has one, because an agent writing
+      # `spec.md` gives it a real sentence — "Tenancy: users, households,
+      # memberships" — while the folder slug can only carry kebab-case.
+      #
+      # @param subject [Agentilda::Subject]
+      # @return [String]
+      def heading(subject)
+        line = subject.read("spec.md").to_s[/^[ \t]{0,3}#[ \t]+(.+)$/, 1]
+        cleaned = line.to_s.sub(/\A(?:spec(?:ification)?\s*)?\d+(?:\.\d+)?\s*[—–:.-]\s*/i, "").strip
+        cleaned.empty? ? subject.feature.title : cleaned
+      end
+
+      # @param subject [Agentilda::Subject]
+      # @return [String]
+      def plan_description(subject)
+        [
+          subject.goal.join("\n\n"),
+          "**State**: #{subject.status} — #{subject.status.note}",
+          "**Folder**: `#{Agentilda::PLANS_DIR}/#{subject.feature.dirname}`",
+          provenance
+        ].compact.reject(&:empty?).join("\n\n")
+      end
+
+      # @param subject [Agentilda::Subject]
+      # @param unit [Agentilda::Linear::Unit]
+      # @return [String]
+      def unit_description(subject, unit)
+        [
+          truncate(unit.body),
+          "**Plan**: `#{Agentilda::PLANS_DIR}/#{subject.feature.dirname}` · unit `#{unit.key}`",
+          provenance
+        ].compact.reject(&:empty?).join("\n\n")
+      end
+
+      # A pull request is attached to its issue, not listed in its body.
+      #
+      # Linear has a first-class relationship for this and renders it as what
+      # it is — an artifact implementing the work, carrying its own state. A
+      # markdown bullet is a claim about a relationship; an attachment is the
+      # relationship. Links are keyed on the URL, so re-sending one updates
+      # rather than duplicates.
+      #
+      # @param unit [Agentilda::Linear::Unit]
+      # @return [Array<Hash>]
+      def links_for(unit)
+        unit.pull_requests.select(&:url).map { |pr| {url: pr.url, title: pr.label} }
+      end
+
+      # A plan section can run to several hundred lines of design notes and
+      # DDL. Linear is where the work is tracked, not where it is specified,
+      # and the folder is one click away.
+      #
+      # @param body [String]
+      # @param limit [Integer]
+      # @return [String]
+      def truncate(body, limit = 6_000)
+        text = body.to_s.strip
+        return text if text.length <= limit
+
+        "#{text[0, limit].rpartition("\n").first.rstrip}\n\n_…truncated; the plan folder has the rest._"
+      end
+
+      # @return [String]
+      def provenance
+        "_Imported by `agentilda linear import`. The plan folder is the source of truth; " \
+        "edits made here do not travel back._"
+      end
+    end
+  end
+end

data/lib/agentilda/linear/issue.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Agentilda
+  module Linear
+    # One row of a plan's `linear.md`: an issue this tool has already pushed.
+    #
+    # @!attribute [r] unit
+    #   @return [String] the {Unit#key} it was made from
+    # @!attribute [r] identifier
+    #   @return [String] "TAX-41" — Linear resolves this as an id
+    # @!attribute [r] url
+    #   @return [String, nil]
+    # @!attribute [r] title
+    #   @return [String] as pushed
+    # @!attribute [r] state
+    #   @return [String] as pushed
+    # @!attribute [r] digest
+    #   @return [String] fingerprint of the payload as pushed
+    Issue = Data.define(:unit, :identifier, :url, :title, :state, :digest)
+
+    # A plan's record of what it has put into Linear.
+    #
+    # Without it, a second `linear import` cannot tell an issue it created
+    # last week from one it has never created, and the only two outcomes are
+    # duplicating everything or searching Linear by title on every run. The
+    # file is the memory, and it is a committed artifact rather than a dotfile
+    # so the record travels with the plan and shows up in review.
+    #
+    # The `Synced` column is what makes an update cheap to decide: it is a
+    # digest of the payload last pushed, so a run can tell — with no network
+    # at all — whether anything about this issue has changed since. A digest
+    # that no longer matches is the whole trigger for an update.
+    class Issues
+      # The file this reads and writes.
+      FILENAME = "linear.md"
+
+      # The unit key given to the issue that stands for the whole folder. Its
+      # children carry their own unit keys; it carries this, so one table can
+      # hold a plan and its parts without a second shape to parse.
+      PARENT = "PLAN"
+
+      # Fingerprint of a payload, short enough to read in a table.
+      #
+      # @param payload [Object] anything with a stable #inspect ordering
+      # @return [String] eight hex characters
+      def self.digest(payload) = ::Digest::SHA256.hexdigest(JSON.generate(payload))[0, 8]
+
+      # @param team [String] the team key, e.g. "TAX"
+      # @param project [Hash, nil] `{name:, url:}`
+      # @param issues [Array<Agentilda::Linear::Issue>]
+      # @return [String]
+      def self.render(team:, project:, issues:)
+        rows = order(issues).map { |i|
+          "| #{i.unit} | #{link(i.identifier, i.url)} | #{escape(i.title)} | #{i.state} | #{i.digest} |"
+        }
+
+        <<~MARKDOWN
+          # Linear
+
+          #{heading(team, project)}
+
+          | Unit | Issue | Title | State | Synced |
+          | :--- | :---- | :---- | ----: | :----- |
+          #{rows.join("\n")}
+
+          <!-- Written by `agentilda linear import --commit`. Do not hand-edit the
+               Synced column: it fingerprints what was last pushed, and a row whose
+               fingerprint no longer matches the plan is what triggers an update. -->
+        MARKDOWN
+      end
+
+      # The folder's own issue first, then its children. A table that opens
+      # with a child reads as a list of unrelated issues.
+      #
+      # @param issues [Array<Agentilda::Linear::Issue>]
+      # @return [Array<Agentilda::Linear::Issue>]
+      def self.order(issues)
+        parent, children = issues.partition { |i| i.unit == PARENT }
+        parent + children
+      end
+
+      # @param team [String]
+      # @param project [Hash, nil]
+      # @return [String]
+      def self.heading(team, project)
+        return "Team **#{team}**." unless project
+
+        "Team **#{team}** · project #{link(project[:name], project[:url])}"
+      end
+
+      # @param text [String]
+      # @param url [String, nil]
+      # @return [String]
+      def self.link(text, url) = url ? "[#{escape(text)}](#{url})" : escape(text)
+
+      # @param text [String]
+      # @return [String]
+      def self.escape(text) = text.to_s.gsub("|", "\\|").gsub(/\s+/, " ").strip
+
+      # @param dir [String] absolute path to the plan folder
+      def initialize(dir:)
+        @dir = dir
+      end
+
+      # @return [Array<Agentilda::Linear::Issue>] possibly empty
+      def all = @all ||= parse
+
+      # @return [Hash{String => Agentilda::Linear::Issue}] keyed by unit
+      def by_unit = @by_unit ||= all.to_h { |issue| [issue.unit, issue] }
+
+      # The project this plan was last filed under, if any.
+      #
+      # @return [Hash, nil] `{name:, url:}`
+      def project = (@project ||= [parse_project])[0]
+
+      # The issue standing for the folder itself.
+      #
+      # @return [Agentilda::Linear::Issue, nil]
+      def parent = by_unit[PARENT]
+
+      # @return [String] absolute path to `linear.md`
+      def path = File.join(dir, FILENAME)
+
+      # @return [Boolean]
+      def exist? = File.file?(path)
+
+      # @param team [String]
+      # @param project [Hash, nil]
+      # @param issues [Array<Agentilda::Linear::Issue>]
+      # @return [String] the path written
+      def write(team:, project:, issues:)
+        File.write(path, self.class.render(team:, project:, issues:))
+        @all = @by_unit = @project = nil
+        path
+      end
+
+      private
+
+      # @return [String]
+      attr_reader :dir
+
+      # @return [String]
+      def text = @text ||= exist? ? File.read(path, encoding: "UTF-8") : ""
+
+      # @return [Array<Agentilda::Linear::Issue>]
+      def parse
+        table = Markdown.tables(text).find { |t|
+          t[:header].any? { |h| h.match?(/\Aissue\z/i) } && t[:header].any? { |h| h.match?(/\Aunit\z/i) }
+        }
+        return [] unless table
+
+        index = table[:header].each_with_index.to_h { |h, i| [h.downcase.strip, i] }
+        table[:rows].filter_map { |cells| row_to_issue(cells, index) }
+      end
+
+      # @param cells [Array<String>]
+      # @param index [Hash{String => Integer}]
+      # @return [Agentilda::Linear::Issue, nil]
+      def row_to_issue(cells, index)
+        cell = ->(name) { cells[index[name]].to_s }
+        link = cell["issue"].match(/\[([^\]]+)\]\((\S+?)\)/)
+        identifier = (link ? link[1] : cell["issue"]).gsub(/[*_`]/, "").strip
+        return nil if identifier.empty?
+
+        Issue.new(unit: cell["unit"].strip, identifier:, url: link && link[2],
+          title: cell["title"].gsub(/\\([|\\])/, '\1').strip,
+          state: cell["state"].strip, digest: cell["synced"].gsub(/[`\s]/, ""))
+      end
+
+      # @return [Hash, nil]
+      def parse_project
+        line = text.lines.find { |l| l.match?(/project\s+\[/i) }
+        return nil unless line
+
+        link = line.match(/project\s+\[([^\]]+)\]\((\S+?)\)/i)
+        return nil unless link
+
+        {name: link[1].strip.gsub(/\\([|\\])/, '\1'), url: link[2]}
+      end
+    end
+  end
+end

data/lib/agentilda/linear/mapping.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Linear
+    # What a folder's state means to Linear.
+    #
+    # Linear gives every workflow state a *type* — one of five, fixed across
+    # every workspace — and a *name*, which each team chooses for itself. A
+    # team may call its started state "In Progress", "Doing" or "🚧 WIP", so
+    # matching on the name alone works right up until it meets somebody else's
+    # workspace. Each row here therefore carries both: the type, which is the
+    # contract, and the name we would prefer if the team happens to have one.
+    # {Push} resolves the name first and falls back to the type.
+    #
+    # Several states have no Linear equivalent at all — ⭕️ Technical Block is
+    # a reason, not a position in a workflow — so they map to the nearest
+    # position and carry a label saying which reason.
+    #
+    # Two states are left out entirely; see {UNPLACED}.
+    #
+    # @!attribute [r] type
+    #   @return [String] Linear's canonical type: backlog, unstarted, started,
+    #     completed or canceled
+    # @!attribute [r] name
+    #   @return [String] the state name to prefer when the team has one
+    # @!attribute [r] labels
+    #   @return [Array<String>] labels that carry what the type cannot
+    Placement = Data.define(:type, :name, :labels)
+
+    # Linear's five workflow state types, in lifecycle order.
+    TYPES = %w[backlog unstarted started completed canceled].freeze
+
+    # Every plan state this tool is willing to place, keyed by
+    # {Agentilda::Status#key}.
+    #
+    # Between this and {UNPLACED} every entry in {Agentilda::STATUSES} is
+    # named exactly once, and a spec asserts it. That is the guard against the
+    # failure this file is most prone to: a sixteenth state gets added,
+    # nothing here changes, and its plans quietly import as Backlog with no
+    # indication anything was missed.
+    PLACEMENTS = {
+      new: Placement.new(type: "backlog", name: "Backlog", labels: []),
+      researched: Placement.new(type: "backlog", name: "Backlog", labels: %w[researched]),
+      planned: Placement.new(type: "unstarted", name: "Todo", labels: []),
+      building: Placement.new(type: "started", name: "In Progress", labels: []),
+      # Both halves of building are one column on a board. A reader there
+      # wants to know work is under way; which half is under way is this
+      # tool's business, and the label carries it for anyone who does care.
+      building_ui: Placement.new(type: "started", name: "In Progress", labels: %w[frontend]),
+      ready_for_review: Placement.new(type: "started", name: "In Review", labels: []),
+      in_review: Placement.new(type: "started", name: "In Review", labels: []),
+      rejected: Placement.new(type: "started", name: "In Review", labels: %w[changes-requested]),
+      approved: Placement.new(type: "completed", name: "Done", labels: []),
+      deployed: Placement.new(type: "completed", name: "Done", labels: %w[deployed]),
+      blocked: Placement.new(type: "unstarted", name: "Todo", labels: %w[blocked]),
+      product_blocked: Placement.new(type: "unstarted", name: "Todo", labels: %w[blocked-on-product]),
+      deferred: Placement.new(type: "backlog", name: "Backlog", labels: %w[deferred]),
+      retroactive: Placement.new(type: "completed", name: "Done", labels: %w[retroactive]),
+      discarded: Placement.new(type: "canceled", name: "Canceled", labels: [])
+    }.freeze
+
+    # States deliberately left out, and why.
+    #
+    # Both are real positions in this tool's lifecycle and neither is
+    # obviously any position on a Linear board. Where they belong is a
+    # statement about how a particular team works, and this tool does not know
+    # that. Guessing would be worse than not knowing: an issue filed in the
+    # wrong column reads exactly like an issue filed in the right one, and
+    # nobody goes looking for a mistake that renders correctly.
+    #
+    # A plan in one of these states is reported and skipped. To import them,
+    # decide where they belong and move the entry into {PLACEMENTS}.
+    UNPLACED = {
+      shit: "the plan survives and its pull requests do not; whether that is work still to do " \
+            "or work abandoned depends on what the team does next",
+      rolled_back: "it shipped and was pulled; whether that reopens this work or opens new work " \
+                   "depends on what broke"
+    }.freeze
+
+    # Where one unit of work belongs, which is not always where its plan does.
+    #
+    # A plan in 🟡 Building has some units merged and some not started. Giving
+    # every one of its issues the plan's own state says they are all in
+    # progress, which is false about most of them and useless on a board. A
+    # unit's pull requests are the better evidence, so they are used when
+    # there are any.
+    #
+    # @param status [Agentilda::Status] the plan's state
+    # @param pulls [Array<Agentilda::PullRequest>] the unit's
+    # @return [Agentilda::Linear::Placement, nil]
+    def self.placement_for(status, pulls)
+      return placement(status) if pulls.empty?
+      return PLACEMENTS[:building].with(name: "In Review") if pulls.any?(&:open?)
+      return PLACEMENTS[:approved] if pulls.all?(&:merged?)
+
+      placement(status)
+    end
+
+    # Where a plan in this state belongs on a Linear board.
+    #
+    # @param status [Agentilda::Status]
+    # @return [Agentilda::Linear::Placement, nil] nil when nobody has decided
+    def self.placement(status) = PLACEMENTS[status.key]
+
+    # Why a state is not imported, for the report that says so.
+    #
+    # @param status [Agentilda::Status]
+    # @return [String] the reason, or the louder one for a state nobody has considered at all
+    def self.reason_unplaced(status)
+      UNPLACED.fetch(status.key) do
+        "no Linear placement has ever been decided for it — add one to Linear::PLACEMENTS"
+      end
+    end
+  end
+end