plan_driven 0.1.0 → 0.2.0

data/app/views/plan_driven/wizard/plans/index.html.erb

@@ -0,0 +1,31 @@
+<% content_for :title, "plan_driven" %>
+<h1>Implementation plans</h1>
+<p class="muted">From an idea to merged pull requests, one step at a time. Each button runs the same
+  <code>plan-driven</code> command you could type yourself; the panel on the right shows it.</p>
+
+<div class="row">
+  <%= link_to "New plan", new_plan_path, class: "button primary" %>
+  <%= button_to "Check the setup", run_path(do: "doctor"), form: { style: "display:inline" } %>
+</div>
+
+<% if @plans.any? %>
+  <div class="card">
+    <table>
+      <thead><tr><th>Plan</th><th>Title</th><th>Phase</th><th>Revision</th><th>Tickets</th><th></th></tr></thead>
+      <tbody>
+        <% @plans.each do |plan| %>
+          <tr>
+            <td><strong><%= plan.key %></strong></td>
+            <td><%= plan.title %></td>
+            <td><span class="pill <%= plan.status == "delivered" ? "good" : "wait" %>"><%= plan.status.tr("_", " ") %></span></td>
+            <td><%= plan.revision %></td>
+            <td><%= plan.tickets.size %></td>
+            <td><%= link_to "Open", plan_path(plan.key) %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+<% else %>
+  <div class="card muted">No plans yet. Start with “New plan”.</div>
+<% end %>

data/app/views/plan_driven/wizard/plans/new.html.erb

@@ -0,0 +1,21 @@
+<% content_for :title, "New plan" %>
+<h1>New plan</h1>
+<p class="muted">The same questions <code>plan-driven new</code> asks in the terminal. Your answers go to the
+  command as its input; the model drafts the rest from them and your schema, then the guards check it.</p>
+
+<%= form_with url: plans_path, method: :post do |f| %>
+  <label for="title">Title of the change</label>
+  <%= f.text_field :title, value: params[:title], id: "title", required: true %>
+
+  <% @template.asked.each do |section| %>
+    <label for="answer_<%= section.key %>"><%= section.title %>
+      <small><%= section.prompt %></small></label>
+    <%= text_area_tag "answers[#{section.key}]", params.dig(:answers, section.key), id: "answer_#{section.key}",
+                      rows: section.required ? 4 : 2 %>
+  <% end %>
+
+  <div class="nav">
+    <%= link_to "← Back", root_path, class: "button" %>
+    <button type="submit" class="primary">Draft the plan →</button>
+  </div>
+<% end %>

data/app/views/plan_driven/wizard/plans/show.html.erb

@@ -0,0 +1,36 @@
+<% content_for :title, "#{@plan.key} #{@plan.title}" %>
+<p class="muted" style="margin:0"><%= link_to "All plans", root_path %></p>
+<h1><%= @plan.key %> · <%= @plan.title %></h1>
+<p class="muted" style="margin:0">
+  <span class="pill <%= @plan.status == "delivered" ? "good" : "wait" %>"><%= @plan.status.tr("_", " ") %></span>
+  revision <%= @plan.revision %> · <%= PlanDriven::Workflow::PLAN_DESCRIPTIONS[@plan.status] %>
+</p>
+
+<ol class="steps">
+  <% PlanDriven::Wizard::Steps::ORDER.each_with_index do |(key, title, hint), index| %>
+    <li>
+      <% if key == @step %>
+        <span class="here"><b><%= index + 1 %>. <%= title %></b><%= hint %></span>
+      <% elsif PlanDriven::Wizard::Steps.reached?(@plan, key) %>
+        <%= link_to plan_path(@plan.key, key) do %><b><%= index + 1 %>. <%= title %></b><%= hint %><% end %>
+      <% else %>
+        <span><b><%= index + 1 %>. <%= title %></b><%= hint %></span>
+      <% end %>
+    </li>
+  <% end %>
+</ol>
+
+<%= render @step %>
+
+<% keys = PlanDriven::Wizard::Steps.keys; position = keys.index(@step) %>
+<div class="nav">
+  <% if position.zero? %>
+    <%= link_to "← All plans", root_path, class: "button" %>
+  <% else %>
+    <%= link_to "← Back", plan_path(@plan.key, keys[position - 1]), class: "button" %>
+  <% end %>
+  <% if (following = keys[position + 1]) %>
+    <%= link_to "Next →", plan_path(@plan.key, following),
+                class: "button primary #{"disabled" unless PlanDriven::Wizard::Steps.reached?(@plan, following)}" %>
+  <% end %>
+</div>

data/config/routes.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+PlanDriven::Wizard::Engine.routes.draw do
+  root "plans#index"
+  resources :plans, only: %i[new create], param: :key
+  get "plans/:key(/:step)", to: "plans#show", as: :plan, constraints: { step: /plan|approve|tickets|agents|finish/ }
+  post "plans/:key/run", to: "plans#run", as: :run_plan
+  get "plans/:key/files/:name", to: "plans#file", as: :plan_file, constraints: { name: /[a-z-]+\.(pdf|html)/ }
+  post "run", to: "plans#run_global", as: :run
+  post "actor", to: "plans#actor", as: :actor
+  get "configuration", to: "configuration#show", as: :configuration
+  post "configuration/question", to: "configuration#question", as: :configuration_question
+  post "configuration/connect", to: "configuration#connect", as: :configuration_connect
+  post "configuration/check", to: "configuration#check", as: :configuration_check
+  get "jobs/:id", to: "jobs#show", as: :job
+end

data/exe/plan-driven

@@ -4,4 +4,5 @@
 require "plan_driven"
 require "plan_driven/cli"
 
+$stdout.sync = true
 exit PlanDriven::CLI.start(ARGV)

data/lib/generators/plan_driven/install_generator.rb

@@ -23,6 +23,10 @@ module PlanDriven
         create_file "docs/plans/.keep"
       end
 
+      def mount_wizard
+        route 'mount PlanDriven::Wizard::Engine, at: "/plan_driven" if Rails.env.development?'
+      end
+
       def show_next_steps
         say <<~TEXT
 
@@ -30,6 +34,9 @@ module PlanDriven
             bin/rails db:migrate
             bundle exec plan-driven configure   # keys for the LLM, Cursor and GitHub
             bundle exec plan-driven new "Short title of the change"
+
+          Or do it all in the browser: start the app and open /plan_driven
+          (development only; every step runs the same plan-driven command).
         TEXT
       end
     end

data/lib/generators/plan_driven/templates/plan_driven.rb

@@ -14,11 +14,17 @@ if defined?(PlanDriven.configure)
     # config.plan_approvals = %w[review qa devops director]
     # config.ticket_approvals = %w[review]
 
-    # Cursor cloud agents: one agent and one pull request per ticket.
+    # Coding agents: one agent and one pull request per ticket. Cursor cloud agents by default,
+    # or a local CLI in its own git worktree per ticket.
     # config.agent_model = "composer-2.5"
+    # config.agent_provider = :local
+    # config.agent_command = "claude -p --permission-mode acceptEdits --output-format json"
     # config.base_branch = "main"
     # config.max_parallel_agents = 3
 
+    # Dollars per million tokens, for the cost in `plan-driven usage` and the delivery report.
+    # config.token_prices = { "your-model-id" => { input: 3.0, output: 15.0, cache_read: 0.3 } }
+
     # GitHub. The repository is read from `git remote get-url origin` when not set.
     # config.github_repository = "your-org/your-app"
     # config.sync_issues = true
@@ -35,5 +41,8 @@ if defined?(PlanDriven.configure)
     #   "Service objects live in app/services and respond to .call.",
     #   "Authorization goes through Pundit policies, never in controllers."
     # ]
+
+    # The browser wizard at /plan_driven: development only by default, local requests always.
+    # config.wizard_enabled = true
   end
 end

data/lib/plan_driven/cli/config_commands.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  class CLI
+    # The interview's questions, and connecting the services with a key that's checked first.
+    module ConfigCommands
+      def cmd_questions
+        config = PlanDriven.configuration
+        ui.table(%w[Key Source Asks], config.template.asked.map do |section|
+          [section.key, Interview.origin(section.key, template: config.base_template), section.prompt]
+        end)
+        ui.muted "Changes are in #{Interview::PATH}; commit it so the team gets the same interview."
+      end
+
+      def cmd_question(key = nil)
+        raise ArgumentError, "Which question? Pass its key, for example who." if key.to_s.empty?
+
+        base = PlanDriven.configuration.base_template
+        if @options[:remove]
+          result = Interview.remove(key, template: base)
+          ui.success(result == :removed ? "Question #{key} removed" : "Question #{key} is back to the default")
+        else
+          result = Interview.change(key, question_fields, template: base)
+          ui.success "Question #{key} #{result}"
+        end
+        cmd_questions
+      end
+
+      def cmd_connect(name = nil)
+        service = Connections.find(name)
+        ui.muted "#{service.title}: #{service.purpose}. Get a key at #{service.url}"
+        value = ui.secret("#{service.title} key:")
+        raise ArgumentError, "No key given; nothing was stored." if value.empty?
+
+        ui.say "Checking the key with #{service.title}..."
+        detail = verify_connection(service, value)
+        path = Credentials.store(service.key, value)
+        ui.success "#{service.title}: #{detail}"
+        ui.muted "  stored in #{path} (0600), never in the app"
+        return if ENV[service.env].to_s.strip.empty?
+
+        ui.warn "#{service.env} is set in this environment, and it wins over the stored key."
+      end
+
+      private
+
+      def question_fields
+        fields = { "title" => @options[:title], "question" => @options[:ask], "group" => @options[:group] }.compact
+        fields["required"] = @options[:required] unless @options[:required].nil?
+        fields
+      end
+
+      def verify_connection(service, value)
+        Connections.verify(service, value)
+      rescue Error => e
+        raise ProviderError, "#{e.message}; nothing was stored."
+      end
+    end
+  end
+end

data/lib/plan_driven/cli/plan_commands.rb

@@ -44,7 +44,11 @@ module PlanDriven
         plan = find_plan(reference)
         section = PlanDriven.configuration.template[key] or
           raise ArgumentError, "Which section? One of: #{PlanDriven.configuration.template.keys.join(", ")}"
-        text = edit_in_editor(plan.section(section.key), "#{plan.key}-#{section.key}")
+        text = if @options[:from]
+                 File.read(@options[:from], encoding: "UTF-8")
+               else
+                 edit_in_editor(plan.section(section.key), "#{plan.key}-#{section.key}")
+               end
         return ui.muted("No change.") if text.strip == plan.section(section.key).strip
 
         delivery.edit_section(plan, section.key, text)
@@ -124,7 +128,7 @@ module PlanDriven
         PlanDriven.configuration.template.asked.to_h do |section|
           answer = ""
           loop do
-            answer = ui.ask_multiline("#{section.title}: #{section.question}")
+            answer = ui.ask_multiline("#{section.title}: #{section.prompt}")
             break unless section.required && answer.strip.empty?
 
             ui.warn "#{section.title} is required."

data/lib/plan_driven/cli/setup_commands.rb

@@ -83,6 +83,7 @@ module PlanDriven
       end
 
       def check_cursor
+        return check_local_agents if PlanDriven.configuration.agent_provider.to_sym == :local
         return unless Credentials.fetch(:cursor_api_key)
 
         agents = CursorAgents.new
@@ -92,6 +93,15 @@ module PlanDriven
       rescue Error => e
         ui.error "Cursor API: #{e.message}"
       end
+
+      def check_local_agents
+        command = PlanDriven.configuration.agent_command.to_s
+        return ui.error("Agents: local, but config.agent_command isn't set") if command.empty?
+
+        program = Shellwords.split(command).first
+        found = ENV["PATH"].to_s.split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, program)) }
+        found ? ui.success("Agents: local, #{command}") : ui.error("Agents: #{program} isn't on the PATH")
+      end
     end
   end
 end

data/lib/plan_driven/cli/ticket_commands.rb

@@ -23,7 +23,7 @@ module PlanDriven
         plan.tickets.select(&:issue_number).each do |ticket|
           ui.muted "  #{ticket.key} -> issue ##{ticket.issue_number}"
         end
-        ui.say "Next: `plan-driven develop #{plan.key}` hands the ready tickets to Cursor agents."
+        ui.say "Next: `plan-driven develop #{plan.key}` hands the ready tickets to the coding agents."
       end
 
       def cmd_prompt(reference = nil)
@@ -36,7 +36,9 @@ module PlanDriven
         return explain_waiting(plan) if starting.empty?
 
         starting.each { |ticket| ui.say "  #{ticket.key} #{ticket.title}" }
-        return ui.muted("Nothing started.") unless ui.confirm?("Start #{starting.size} Cursor cloud agent(s)?")
+        unless ui.confirm?("Start #{starting.size} #{PlanDriven.configuration.agent_provider} agent(s)?")
+          return ui.muted("Nothing started.")
+        end
 
         delivery.develop(plan, only: starting.map(&:key)).each do |ticket|
           ui.success "#{ticket.key} agent started: #{ticket.agent_url}"
@@ -123,6 +125,24 @@ module PlanDriven
         run.passed? ? ui.success(Evidence.summary_line(plan)) : ui.warn("#{run.status}: #{Evidence.summary_line(plan)}")
       end
 
+      def cmd_usage(reference = nil)
+        plan = find_plan(reference)
+        rows = Usage.rows(plan)
+        return ui.muted("No token usage recorded for #{plan.key} yet.") if rows.empty?
+
+        ui.table(%w[Step Ticket Model Tokens Time Cost], rows.map do |row|
+          [row.step.to_s, row.ticket.to_s, row.model.to_s, Usage.format_tokens(row.total_tokens),
+           row.duration_ms ? "#{(row.duration_ms / 60_000.0).round(1)} min" : "", Usage.format_cost(row.cost)]
+        end)
+        totals = Usage.totals(rows)
+        ui.say
+        ui.success "#{Usage.format_tokens(totals[:total_tokens])} tokens" \
+                   "#{", #{Usage.format_cost(totals[:cost])}" if totals[:cost]}"
+        return if totals[:unpriced].empty?
+
+        ui.muted "No price for #{totals[:unpriced].join(", ")}; set config.token_prices to see dollars."
+      end
+
       def cmd_report(reference = nil)
         plan = find_plan(reference)
         paths = delivery.report(plan)
@@ -147,7 +167,7 @@ module PlanDriven
       def show_tickets(tickets)
         ui.table(%w[# Title Kind Pts Status PR], tickets.map do |ticket|
           [ticket.key, ticket.title.truncate(48), ticket.kind, ticket.estimate, ticket.status.tr("_", " "),
-           ticket.pr_url.to_s]
+           ticket.pr_number ? "##{ticket.pr_number}" : ""]
         end)
       end
     end

data/lib/plan_driven/cli/ui.rb

@@ -42,7 +42,8 @@ module PlanDriven
         answer.empty? ? default.to_s : answer
       end
 
-      # Several lines, finished by an empty line.
+      # Several lines, finished by an empty line. Piped answers (from the wizard, or a script) are
+      # echoed, so the transcript reads like a typed interview.
       def ask_multiline(prompt)
         say paint(prompt, :cyan)
         muted "  (finish with an empty line)"
@@ -50,6 +51,7 @@ module PlanDriven
         loop do
           output.print "  > "
           line = read_line(nil)
+          output.puts(line.to_s.rstrip) if piped?
           break if line.nil? || line.strip.empty?
 
           lines << line.rstrip
@@ -83,8 +85,12 @@ module PlanDriven
         success ok_message if report.errors.empty? && report.warnings.empty?
       end
 
+      MIN_COLUMN = 16
+
+      # The widest columns are cut to fit the terminal's width, so rows don't wrap.
       def table(headers, rows)
-        widths = headers.each_index.map { |i| ([headers[i]] + rows.map { |row| row[i] }).map { |v| v.to_s.length }.max }
+        rows = fit_columns(headers, rows)
+        widths = column_widths(headers, rows)
         line = ->(cells) { cells.each_with_index.map { |cell, i| cell.to_s.ljust(widths[i]) }.join("  ") }
         say paint(line.call(headers), :bold)
         rows.each { |row| say line.call(row) }
@@ -92,6 +98,39 @@ module PlanDriven
 
       private
 
+      def column_widths(headers, rows)
+        headers.each_index.map { |i| ([headers[i]] + rows.map { |row| row[i] }).map { |v| v.to_s.length }.max }
+      end
+
+      # Cuts the widest columns short, never below MIN_COLUMN, until the table fits the terminal.
+      def fit_columns(headers, rows)
+        columns = terminal_width or return rows
+        widths = column_widths(headers, rows)
+        room = columns - (2 * (widths.size - 1)) - 1
+        while widths.sum > room
+          widest = widths.each_index.max_by { |i| widths[i] }
+          cut = [widths[widest] - (widths.sum - room), MIN_COLUMN, headers[widest].length].max
+          break if cut >= widths[widest]
+
+          widths[widest] = cut
+        end
+        rows.map { |row| row.each_with_index.map { |cell, i| cell.is_a?(String) ? cell.truncate(widths[i]) : cell } }
+      end
+
+      # The terminal's width, or COLUMNS when the output isn't a terminal (the wizard sets it).
+      def terminal_width
+        if output.respond_to?(:tty?) && output.tty? && output.respond_to?(:winsize)
+          output.winsize[1].then { |columns| return columns if columns.positive? }
+        end
+        ENV["COLUMNS"].to_i.then { |columns| columns.positive? ? columns : nil }
+      rescue StandardError
+        nil
+      end
+
+      def piped?
+        !(input.respond_to?(:tty?) && input.tty?)
+      end
+
       def read_line(at_end = "")
         line = input.gets
         line.nil? ? at_end : PlanDriven.utf8(line)

data/lib/plan_driven/cli.rb

@@ -7,6 +7,7 @@ require_relative "cli/ui"
 require_relative "cli/plan_commands"
 require_relative "cli/ticket_commands"
 require_relative "cli/setup_commands"
+require_relative "cli/config_commands"
 
 module PlanDriven
   # bundle exec plan-driven <command> [arguments]
@@ -14,12 +15,13 @@ module PlanDriven
     include PlanCommands
     include TicketCommands
     include SetupCommands
+    include ConfigCommands
 
     COMMANDS = {
       "new" => ["TITLE", "Interview in the terminal, then draft the plan from your answers and the schema"],
       "list" => ["", "Every plan and its phase"],
       "show" => ["PLAN", "Print the plan, or one section with --section"],
-      "edit" => ["PLAN SECTION", "Edit a section in $EDITOR"],
+      "edit" => ["PLAN SECTION", "Edit a section in $EDITOR, or replace it with --from FILE"],
       "redraft" => ["PLAN SECTION \"instruction\"", "Have the model rewrite one section"],
       "check" => ["PLAN", "Run the plan guards"],
       "submit" => ["PLAN", "Send the plan for approval (guards must pass)"],
@@ -29,7 +31,7 @@ module PlanDriven
       "tickets" => ["PLAN [\"instruction\"]", "Draft tickets from the approved plan, or redraft them"],
       "approve-tickets" => ["PLAN", "Approve the tickets (--as ROLE); creates GitHub issues"],
       "prompt" => ["PLAN/TICKET", "Show what the agent will be told"],
-      "develop" => ["PLAN [TICKET...]", "Hand ready tickets to Cursor cloud agents"],
+      "develop" => ["PLAN [TICKET...]", "Hand ready tickets to the coding agents (Cursor cloud, or local)"],
       "status" => ["PLAN", "Poll agents and pull requests, then show every ticket"],
       "review" => ["PLAN/TICKET", "Run the pull request guards"],
       "approve-pr" => ["PLAN/TICKET", "Approve the pull request (guards must pass)"],
@@ -38,11 +40,15 @@ module PlanDriven
       "evidence" => ["PLAN", "Run the plan's Cucumber scenarios and record the results (--from FILE)"],
       "report" => ["PLAN", "Write the delivery report"],
       "log" => ["PLAN", "The audit trail"],
+      "usage" => ["PLAN", "Tokens and cost per step and per agent run"],
+      "questions" => ["", "The interview's questions, with the team's changes"],
+      "question" => ["KEY", "Change or add a question (--title, --ask, --group, --required, --optional, --remove)"],
       "configure" => ["", "Store API keys in ~/.plan_driven/config"],
+      "connect" => ["SERVICE", "Check a key with cursor, openai, anthropic or github, then store it"],
       "doctor" => ["", "Check keys, repository and connections"]
     }.freeze
 
-    NO_APP = %w[configure doctor help version].freeze
+    NO_APP = %w[configure connect doctor help version].freeze
 
     # Plans are UTF-8 whatever the terminal's locale says, so answers typed with č or ž under
     # LANG=C are read as text, not bytes.
@@ -64,7 +70,7 @@ module PlanDriven
       @ui = UI.new(input: @input, output: @output, assume_yes: options[:yes])
       @options = options
       return help if %w[help -h --help].include?(command)
-      return @ui.say(PlanDriven::VERSION) if %w[version -v --version].include?(command)
+      return @ui.say(PlanDriven::VERSION) || 0 if %w[version -v --version].include?(command)
       raise Error, "Unknown command `#{command}`. `plan-driven help` lists them." unless COMMANDS.key?(command)
 
       boot_application unless NO_APP.include?(command)
@@ -109,10 +115,20 @@ module PlanDriven
         parser.on("--section KEY") { |value| options[:section] = value }
         parser.on("--from FILE") { |value| options[:from] = value }
         parser.on("-y", "--yes") { options[:yes] = true }
+        question_options(parser, options)
       end.parse!(argv)
       options
     end
 
+    def question_options(parser, options)
+      parser.on("--title TEXT") { |value| options[:title] = value }
+      parser.on("--ask TEXT") { |value| options[:ask] = value }
+      parser.on("--group NAME") { |value| options[:group] = value }
+      parser.on("--required") { options[:required] = true }
+      parser.on("--optional") { options[:required] = false }
+      parser.on("--remove") { options[:remove] = true }
+    end
+
     def boot_application
       return unless @boot
       return if defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.initialized?

data/lib/plan_driven/configuration.rb

@@ -26,8 +26,13 @@ module PlanDriven
     # Where documentation is written, relative to the application root.
     attr_accessor :docs_path, :root
 
-    # Cursor cloud agents.
-    attr_accessor :agent_model, :base_branch, :max_parallel_agents, :skip_reviewer_request
+    # Coding agents: :cursor (Cursor cloud agents), or :local to run a command such as Claude Code
+    # or Codex on this machine, one git worktree per ticket (see LocalAgents).
+    attr_accessor :agent_provider, :agent_command, :agent_model, :base_branch, :max_parallel_agents,
+                  :skip_reviewer_request, :agent_timeout
+
+    # Dollars per million tokens, by model id, for the cost in the delivery report (see Usage).
+    attr_accessor :token_prices
 
     # GitHub.
     attr_accessor :github_repository, :sync_issues, :merge_method, :issue_labels
@@ -45,11 +50,29 @@ module PlanDriven
     # Anything the LLM should know that the schema doesn't show.
     attr_accessor :extra_context
 
+    # The browser wizard at /plan_driven runs commands on this machine. nil means development
+    # only; it answers local requests either way.
+    attr_accessor :wizard_enabled
+
     # The plan's sections. Template.default mirrors the usual Confluence implementation plan.
     attr_writer :template
 
+    # The template with the team's interview changes (config/plan_driven/interview.yml) applied.
     def template
-      @template ||= Template.default
+      file = Interview.path(root_path)
+      stamp = [base_template.object_id, file.to_s, file.exist? && file.mtime]
+      unless @interview_stamp == stamp
+        @interview_template = Interview.apply(base_template, root_path)
+        @interview_stamp = stamp
+      end
+      @interview_template
+    end
+
+    # The template as the initializer set it, before the interview changes.
+    def base_template
+      return @template if @template
+
+      @template = Template.default
     end
 
     def initialize
@@ -68,10 +91,14 @@ module PlanDriven
       @docs_path = "docs/plans"
       @root = nil
 
+      @agent_provider = :cursor
+      @agent_command = nil
       @agent_model = nil
       @base_branch = "main"
       @max_parallel_agents = 3
       @skip_reviewer_request = false
+      @agent_timeout = 3600
+      @token_prices = {}
 
       @github_repository = nil
       @sync_issues = true
@@ -89,6 +116,7 @@ module PlanDriven
       @team_rules = []
       @pdf_renderer = nil
       @extra_context = nil
+      @wizard_enabled = nil
     end
 
     def llm_model

data/lib/plan_driven/connections.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # The services plan_driven talks to, which of them this app's configuration uses, and a check
+  # that a key works before `plan-driven connect` stores it.
+  module Connections
+    Service = Struct.new(:name, :title, :key, :purpose, :url, keyword_init: true) do
+      def env
+        Credentials::KEYS.fetch(key)
+      end
+    end
+
+    SERVICES = [
+      Service.new(name: "cursor", title: "Cursor", key: "cursor_api_key",
+                  purpose: "Cloud agents, one per ticket, and drafting with llm_provider :cursor",
+                  url: "https://cursor.com/dashboard?tab=integrations"),
+      Service.new(name: "openai", title: "OpenAI", key: "openai_api_key",
+                  purpose: "Drafting plans and tickets with llm_provider :openai",
+                  url: "https://platform.openai.com/api-keys"),
+      Service.new(name: "anthropic", title: "Anthropic", key: "anthropic_api_key",
+                  purpose: "Drafting plans and tickets with llm_provider :anthropic",
+                  url: "https://console.anthropic.com/settings/keys"),
+      Service.new(name: "github", title: "GitHub", key: "github_token",
+                  purpose: "Issues, pull requests, reviews and merges",
+                  url: "https://github.com/settings/personal-access-tokens")
+    ].freeze
+
+    module_function
+
+    def find(name)
+      SERVICES.find { |service| service.name == name.to_s.downcase } or
+        raise ArgumentError, "Connect what? One of: #{SERVICES.map(&:name).join(", ")}"
+    end
+
+    # The services this app needs with its current configuration.
+    def needed(config = PlanDriven.configuration)
+      names = ["github"]
+      names << "cursor" if config.agent_provider.to_sym == :cursor || config.llm_provider.to_sym == :cursor
+      names << config.llm_provider.to_s if %i[openai anthropic].include?(config.llm_provider.to_sym)
+      SERVICES.select { |service| names.include?(service.name) }
+    end
+
+    # Who the key belongs to, or a ProviderError when the service refuses it.
+    def verify(service, key, config = PlanDriven.configuration)
+      case service.name
+      when "cursor"
+        info = CursorAgents.new(api_key: key, config: config).me
+        "connected as #{info["userEmail"] || info["apiKeyName"] || "this key"}"
+      when "github"
+        headers = { "Authorization" => "Bearer #{key}", "Accept" => "application/vnd.github+json" }
+        "connected as #{get(service, "https://api.github.com/user", headers)["login"]}"
+      when "openai"
+        base = config.llm_provider.to_sym == :openai && config.llm_api_base ? config.llm_api_base : "https://api.openai.com/v1"
+        get(service, "#{base.chomp("/")}/models", "Authorization" => "Bearer #{key}")
+        "the key works"
+      when "anthropic"
+        get(service, "https://api.anthropic.com/v1/models", "x-api-key" => key, "anthropic-version" => "2023-06-01")
+        "the key works"
+      end
+    end
+
+    def get(service, url, headers)
+      response = HTTP.request(:get, url, headers: headers.merge("User-Agent" => "plan_driven"), timeout: 30)
+      return response.json if response.success?
+
+      raise ProviderError, "#{service.title} refused the key (HTTP #{response.status})"
+    end
+  end
+end

data/lib/plan_driven/cursor_agents.rb

@@ -10,7 +10,7 @@ module PlanDriven
     BASE = "https://api.cursor.com/v1"
     TERMINAL = %w[FINISHED ERROR CANCELLED EXPIRED].freeze
 
-    Run = Struct.new(:id, :agent_id, :status, :result, :branch, :pr_url, keyword_init: true) do
+    Run = Struct.new(:id, :agent_id, :status, :result, :branch, :pr_url, :duration_ms, keyword_init: true) do
       def terminal?
         TERMINAL.include?(status)
       end
@@ -48,6 +48,14 @@ module PlanDriven
       to_run(request(:post, "/agents/#{agent_id}/runs", { prompt: { text: text } }).fetch("run"))
     end
 
+    # Tokens one run spent, in Usage's field names.
+    def usage(agent_id, run_id)
+      data = request(:get, "/agents/#{agent_id}/usage?runId=#{run_id}")
+      tokens = Array(data["runs"]).first.to_h["usage"] || data["totalUsage"] || {}
+      { "input_tokens" => tokens["inputTokens"].to_i, "output_tokens" => tokens["outputTokens"].to_i,
+        "cache_write_tokens" => tokens["cacheWriteTokens"].to_i, "cache_read_tokens" => tokens["cacheReadTokens"].to_i }
+    end
+
     def me
       request(:get, "/me")
     end
@@ -62,7 +70,7 @@ module PlanDriven
     def to_run(data)
       branch = Array(data.dig("git", "branches")).first || {}
       Run.new(id: data["id"], agent_id: data["agentId"], status: data["status"], result: data["result"],
-              branch: branch["branch"], pr_url: branch["prUrl"])
+              branch: branch["branch"], pr_url: branch["prUrl"], duration_ms: data["durationMs"])
     end
 
     def request(method, path, body = nil)