plan_driven 0.1.0

data/lib/plan_driven/cli/ui.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module PlanDriven
+  class CLI
+    # Terminal output and input. Colour only when writing to a terminal.
+    class UI
+      COLORS = { red: 31, green: 32, yellow: 33, blue: 34, magenta: 35, cyan: 36, gray: 90, bold: 1 }.freeze
+
+      attr_reader :input, :output
+
+      def initialize(input: $stdin, output: $stdout, assume_yes: false)
+        @input = input
+        @output = output
+        @assume_yes = assume_yes
+      end
+
+      def say(text = "")
+        output.puts(text)
+      end
+
+      def paint(text, color)
+        return text unless output.respond_to?(:tty?) && output.tty? && ENV["NO_COLOR"].nil?
+
+        "\e[#{COLORS.fetch(color)}m#{text}\e[0m"
+      end
+
+      def heading(text)
+        say
+        say paint(text, :bold)
+      end
+
+      def success(text) = say(paint("✓ #{text}", :green))
+      def warn(text) = say(paint("! #{text}", :yellow))
+      def error(text) = say(paint("✗ #{text}", :red))
+      def muted(text) = say(paint(text, :gray))
+
+      def ask(prompt, default: nil)
+        output.print(default ? "#{prompt} [#{default}] " : "#{prompt} ")
+        answer = read_line.strip
+        answer.empty? ? default.to_s : answer
+      end
+
+      # Several lines, finished by an empty line.
+      def ask_multiline(prompt)
+        say paint(prompt, :cyan)
+        muted "  (finish with an empty line)"
+        lines = []
+        loop do
+          output.print "  > "
+          line = read_line(nil)
+          break if line.nil? || line.strip.empty?
+
+          lines << line.rstrip
+        end
+        lines.join("\n")
+      end
+
+      def secret(prompt)
+        output.print "#{prompt} "
+        value = input.respond_to?(:noecho) && input.tty? ? PlanDriven.utf8(input.noecho(&:gets)) : read_line
+        output.puts
+        value.to_s.strip
+      end
+
+      def confirm?(prompt)
+        return true if @assume_yes
+
+        ask("#{prompt} [y/N]").match?(/\Ay(es)?\z/i)
+      end
+
+      def confirm_word?(prompt, word)
+        return true if @assume_yes
+
+        ask("#{prompt} Type #{paint(word, :bold)} to continue:") == word
+      end
+
+      def report(report, ok_message: "All checks passed")
+        report.fixes.each { |fix| muted "  fixed: #{fix}" }
+        report.errors.each { |message| error message }
+        report.warnings.each { |message| warn message }
+        success ok_message if report.errors.empty? && report.warnings.empty?
+      end
+
+      def table(headers, rows)
+        widths = headers.each_index.map { |i| ([headers[i]] + rows.map { |row| row[i] }).map { |v| v.to_s.length }.max }
+        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) }
+      end
+
+      private
+
+      def read_line(at_end = "")
+        line = input.gets
+        line.nil? ? at_end : PlanDriven.utf8(line)
+      end
+    end
+  end
+end

data/lib/plan_driven/cli.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "tempfile"
+
+require_relative "cli/ui"
+require_relative "cli/plan_commands"
+require_relative "cli/ticket_commands"
+require_relative "cli/setup_commands"
+
+module PlanDriven
+  # bundle exec plan-driven <command> [arguments]
+  class CLI
+    include PlanCommands
+    include TicketCommands
+    include SetupCommands
+
+    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"],
+      "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)"],
+      "approve" => ["PLAN", "Approve the plan (--as ROLE, --note)"],
+      "reject" => ["PLAN", "Send the plan back with --note (--as ROLE)"],
+      "pdf" => ["PLAN", "Write the plan to docs/plans as Markdown, HTML and PDF"],
+      "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"],
+      "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)"],
+      "feedback" => ["PLAN/TICKET \"text\"", "Send review feedback to the ticket's agent"],
+      "merge" => ["PLAN/TICKET", "Merge an approved pull request"],
+      "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"],
+      "configure" => ["", "Store API keys in ~/.plan_driven/config"],
+      "doctor" => ["", "Check keys, repository and connections"]
+    }.freeze
+
+    NO_APP = %w[configure 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.
+    def self.start(argv, **options)
+      Encoding.default_external = Encoding::UTF_8
+      new(**options).run(argv.map { |arg| PlanDriven.utf8(arg) })
+    end
+
+    def initialize(input: $stdin, output: $stdout, delivery: nil, boot: true)
+      @input = input
+      @output = output
+      @delivery = delivery
+      @boot = boot
+    end
+
+    def run(argv)
+      options = parse_options(argv)
+      command = argv.shift || "help"
+      @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)
+      raise Error, "Unknown command `#{command}`. `plan-driven help` lists them." unless COMMANDS.key?(command)
+
+      boot_application unless NO_APP.include?(command)
+      public_send("cmd_#{command.tr("-", "_")}", *argv)
+      0
+    rescue GuardError => e
+      ui.error "Blocked by #{e.problems.size} problem(s):"
+      e.problems.each { |problem| ui.say "  - #{problem}" }
+      1
+    rescue Error, ActiveRecord::RecordNotFound, ArgumentError => e
+      ui.error e.message
+      1
+    end
+
+    def ui
+      @ui ||= UI.new(input: @input, output: @output)
+    end
+
+    def help
+      ui.say "plan-driven #{PlanDriven::VERSION}: from implementation plan to merged, tested pull requests"
+      ui.say
+      ui.say "Usage: bundle exec plan-driven COMMAND [ARGS] [--yes]"
+      ui.say
+      width = COMMANDS.map { |name, (args, _)| "#{name} #{args}".length }.max
+      COMMANDS.each { |name, (args, text)| ui.say "  #{"#{name} #{args}".ljust(width)}  #{text}" }
+      ui.say
+      ui.say "Phases: plan draft -> in review -> approved -> tickets -> tickets approved -> in development -> delivered"
+      0
+    end
+
+    private
+
+    def delivery
+      @delivery ||= Delivery.new
+    end
+
+    def parse_options(argv)
+      options = {}
+      OptionParser.new do |parser|
+        parser.on("--as ROLE") { |value| options[:role] = value }
+        parser.on("--note TEXT") { |value| options[:note] = value }
+        parser.on("--section KEY") { |value| options[:section] = value }
+        parser.on("--from FILE") { |value| options[:from] = value }
+        parser.on("-y", "--yes") { options[:yes] = true }
+      end.parse!(argv)
+      options
+    end
+
+    def boot_application
+      return unless @boot
+      return if defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.initialized?
+
+      environment = File.expand_path("config/environment.rb", Dir.pwd)
+      unless File.exist?(environment)
+        raise Error,
+              "Run plan-driven from the root of a Rails application (no config/environment.rb here)."
+      end
+
+      require environment
+      return if ActiveRecord::Base.connection.table_exists?("plan_driven_plans")
+
+      raise Error, "The plan_driven tables are missing. Run `bin/rails generate plan_driven:install` " \
+                   "and `bin/rails db:migrate`."
+    end
+
+    def find_plan(reference)
+      raise ArgumentError, "Which plan? Pass its key, for example PD-1." if reference.to_s.empty?
+
+      Plan.find_by_reference!(reference.to_s.split("/").first)
+    end
+
+    def find_ticket(reference)
+      plan_key, ticket_key = reference.to_s.split("/")
+      raise ArgumentError, "Pass a ticket as PLAN/TICKET, for example PD-1/T2." unless ticket_key
+
+      find_plan(plan_key).ticket!(ticket_key)
+    end
+
+    def show_paths(paths)
+      paths.compact.each { |path| ui.muted "  #{path.relative_path_from(PlanDriven.configuration.root_path)}" }
+    end
+  end
+end

data/lib/plan_driven/configuration.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # Everything has a default, so `plan-driven new` works in a fresh app with only keys set.
+  #
+  #     PlanDriven.configure do |config|
+  #       config.llm_provider = :anthropic
+  #       config.llm_model = "claude-sonnet-4-5"
+  #       config.plan_approvals = %w[review qa devops director]
+  #       config.cucumber = true
+  #     end
+  class Configuration
+    DEFAULT_MODELS = { openai: "gpt-4.1", anthropic: "claude-sonnet-4-5", cursor: "claude-opus-5-5" }.freeze
+    KEY_FOR_PROVIDER = { openai: :openai_api_key, anthropic: :anthropic_api_key, cursor: :cursor_api_key }.freeze
+
+    # Planning and ticket writing are the steps where a stronger model pays for itself.
+    attr_accessor :llm_provider, :llm_api_base, :temperature, :request_timeout, :max_repair_attempts
+    attr_writer :llm_model
+
+    # llm_provider :cursor runs the Cursor SDK under Node 22.13+.
+    attr_accessor :node_command, :cursor_sdk_path
+
+    # Who has to approve what before the next phase can start.
+    attr_accessor :plan_approvals, :ticket_approvals
+
+    # 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
+
+    # GitHub.
+    attr_accessor :github_repository, :sync_issues, :merge_method, :issue_labels
+
+    # Guards.
+    attr_accessor :estimate_scale, :max_estimate, :max_pr_changed_lines, :require_specs_in_pr,
+                  :spec_paths, :cucumber, :features_path
+
+    # Extra rules appended to every agent prompt: your team's conventions, in plain English.
+    attr_accessor :team_rules
+
+    # PDF rendering. A callable taking (html_path, pdf_path), or nil to use headless Chrome.
+    attr_accessor :pdf_renderer
+
+    # Anything the LLM should know that the schema doesn't show.
+    attr_accessor :extra_context
+
+    # The plan's sections. Template.default mirrors the usual Confluence implementation plan.
+    attr_writer :template
+
+    def template
+      @template ||= Template.default
+    end
+
+    def initialize
+      @llm_provider = :openai
+      @llm_model = nil
+      @llm_api_base = nil
+      @temperature = 0.2
+      @request_timeout = 180
+      @max_repair_attempts = 2
+      @node_command = ENV.fetch("PLAN_DRIVEN_NODE", "node")
+      @cursor_sdk_path = nil
+
+      @plan_approvals = %w[review]
+      @ticket_approvals = %w[review]
+
+      @docs_path = "docs/plans"
+      @root = nil
+
+      @agent_model = nil
+      @base_branch = "main"
+      @max_parallel_agents = 3
+      @skip_reviewer_request = false
+
+      @github_repository = nil
+      @sync_issues = true
+      @merge_method = "squash"
+      @issue_labels = %w[plan-driven]
+
+      @estimate_scale = [1, 2, 3, 5, 8]
+      @max_estimate = 5
+      @max_pr_changed_lines = 800
+      @require_specs_in_pr = true
+      @spec_paths = %w[spec/ test/ features/]
+      @cucumber = true
+      @features_path = "features"
+
+      @team_rules = []
+      @pdf_renderer = nil
+      @extra_context = nil
+    end
+
+    def llm_model
+      @llm_model || DEFAULT_MODELS.fetch(llm_provider.to_sym, DEFAULT_MODELS[:openai])
+    end
+
+    def llm_api_key
+      Credentials.fetch(llm_key_name)
+    end
+
+    def llm_key_name
+      KEY_FOR_PROVIDER.fetch(llm_provider.to_sym, :openai_api_key)
+    end
+
+    def root_path
+      Pathname(root || (defined?(Rails) && Rails.respond_to?(:root) && Rails.root) || Dir.pwd)
+    end
+
+    def docs_root
+      root_path.join(docs_path)
+    end
+  end
+end

data/lib/plan_driven/credentials.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "open3"
+
+module PlanDriven
+  # Keys live outside the application, in ~/.plan_driven/config (0600 inside a 0700 directory):
+  #
+  #     openai_api_key: sk-...
+  #     anthropic_api_key: sk-ant-...
+  #     cursor_api_key: key_...
+  #     github_token: ghp_...
+  #
+  # The environment always wins, and a key found there is never copied into the file.
+  module Credentials
+    KEYS = {
+      "openai_api_key" => "OPENAI_API_KEY",
+      "anthropic_api_key" => "ANTHROPIC_API_KEY",
+      "cursor_api_key" => "CURSOR_API_KEY",
+      "github_token" => "GITHUB_TOKEN"
+    }.freeze
+
+    DIRECTORY = File.join(Dir.home, ".plan_driven")
+
+    class << self
+      def path
+        ENV.fetch("PLAN_DRIVEN_CREDENTIALS", File.join(DIRECTORY, "config"))
+      end
+
+      def fetch(name)
+        name = name.to_s
+        env = KEYS.fetch(name)
+        value = ENV[env].to_s.strip
+        return value unless value.empty?
+
+        stored = read[name].to_s.strip
+        return stored unless stored.empty?
+
+        name == "github_token" ? gh_token : nil
+      end
+
+      def source(name)
+        name = name.to_s
+        return "environment (#{KEYS.fetch(name)})" unless ENV[KEYS.fetch(name)].to_s.strip.empty?
+        return path unless read[name].to_s.strip.empty?
+        return "gh auth token" if name == "github_token" && gh_token
+
+        nil
+      end
+
+      def store(name, value)
+        raise ArgumentError, "unknown credential #{name}" unless KEYS.key?(name.to_s)
+
+        data = read
+        data[name.to_s] = value.to_s.strip
+        write(data)
+      end
+
+      def read
+        return {} unless File.exist?(path)
+
+        data = YAML.safe_load_file(path) || {}
+        data.is_a?(Hash) ? data : {}
+      rescue StandardError
+        {}
+      end
+
+      private
+
+      def write(data)
+        directory = File.dirname(path)
+        FileUtils.mkdir_p(directory)
+        File.chmod(0o700, directory) if File.owned?(directory)
+        File.write(path, YAML.dump(data))
+        File.chmod(0o600, path)
+        path
+      end
+
+      def gh_token
+        return @gh_token if defined?(@gh_token)
+
+        output, status = Open3.capture2("gh", "auth", "token", err: File::NULL)
+        @gh_token = status.success? && !output.strip.empty? ? output.strip : nil
+      rescue StandardError
+        @gh_token = nil
+      end
+    end
+  end
+end

data/lib/plan_driven/cursor_agents.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module PlanDriven
+  # Cursor Cloud Agents API v1: one agent per ticket, running on a Cursor-hosted VM against a
+  # fresh clone, opening a pull request when it finishes.
+  # https://cursor.com/docs/cloud-agent/api/endpoints
+  class CursorAgents
+    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
+      def terminal?
+        TERMINAL.include?(status)
+      end
+
+      def finished?
+        status == "FINISHED"
+      end
+    end
+
+    def initialize(api_key: Credentials.fetch(:cursor_api_key), base: BASE, config: PlanDriven.configuration)
+      @api_key = api_key
+      @base = base
+      @config = config
+    end
+
+    def launch(prompt:, repo_url:, name:)
+      body = {
+        prompt: { text: prompt },
+        name: name[0, 100],
+        repos: [{ url: repo_url, startingRef: @config.base_branch }],
+        autoCreatePR: true,
+        skipReviewerRequest: @config.skip_reviewer_request
+      }
+      body[:model] = { id: @config.agent_model } if @config.agent_model
+      response = request(:post, "/agents", body)
+      agent = response.fetch("agent")
+      [agent, to_run(response.fetch("run"))]
+    end
+
+    def run(agent_id, run_id)
+      to_run(request(:get, "/agents/#{agent_id}/runs/#{run_id}"))
+    end
+
+    def follow_up(agent_id, text)
+      to_run(request(:post, "/agents/#{agent_id}/runs", { prompt: { text: text } }).fetch("run"))
+    end
+
+    def me
+      request(:get, "/me")
+    end
+
+    # IDs and aliases of the models this key can start agents with.
+    def model_ids
+      Array(request(:get, "/models")["items"]).flat_map { |item| [item["id"], *Array(item["aliases"])] }.compact.uniq
+    end
+
+    private
+
+    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"])
+    end
+
+    def request(method, path, body = nil)
+      raise ConfigurationError, "No Cursor API key. Run `plan-driven configure` or set CURSOR_API_KEY." unless @api_key
+
+      response = HTTP.request(method, "#{@base}#{path}", body: body, timeout: 60, headers: {
+                                "Authorization" => "Basic #{Base64.strict_encode64("#{@api_key}:")}",
+                                "Content-Type" => "application/json"
+                              })
+      return response.json if response.success?
+
+      error = response.json["error"]
+      message = error.is_a?(Hash) ? error["message"] || error["code"] : error
+      raise ProviderError, "Cursor API returned #{response.status}: #{message || response.body.to_s[0, 200]}"
+    end
+  end
+end

data/lib/plan_driven/cursor_llm.mjs

@@ -0,0 +1,70 @@
+// Runs one read-only Cursor agent turn for plan_driven and prints {"text", "usage"} as JSON.
+// Input on stdin: {"model", "prompt", "cwd", "sdkPaths"}. The key comes from CURSOR_API_KEY.
+// `--check` only resolves the SDK, for `plan-driven doctor`.
+import { createRequire } from "node:module";
+import { execSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+
+const READ_ONLY_TOOLS = ["read", "grep", "glob", "ls"];
+
+function globalRoot() {
+  try {
+    return execSync("npm root -g", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function loadSdk(dirs) {
+  const candidates = [...dirs, path.join(os.homedir(), ".plan_driven", "node"), globalRoot()].filter(Boolean);
+  for (const dir of candidates) {
+    try {
+      return createRequire(path.join(dir, "package.json"))("@cursor/sdk");
+    } catch {
+      // try the next place
+    }
+  }
+  throw new Error(
+    "@cursor/sdk not found. Install it with `npm install --prefix ~/.plan_driven/node @cursor/sdk` (Node 22.13+)."
+  );
+}
+
+async function readStdin() {
+  let data = "";
+  for await (const chunk of process.stdin) data += chunk;
+  return JSON.parse(data);
+}
+
+function fail(message) {
+  process.stdout.write(JSON.stringify({ error: message }));
+  process.exit(1);
+}
+
+try {
+  if (process.argv.includes("--check")) {
+    const dirs = process.argv.slice(3);
+    loadSdk(dirs);
+    process.stdout.write(JSON.stringify({ ok: true, node: process.version }));
+    process.exit(0);
+  }
+
+  const input = await readStdin();
+  const { Agent } = loadSdk([input.cwd, ...(input.sdkPaths || [])]);
+  const result = await Agent.prompt(input.prompt, {
+    apiKey: process.env.CURSOR_API_KEY,
+    model: { id: input.model },
+    tools: READ_ONLY_TOOLS,
+    local: { cwd: input.cwd },
+  });
+  if (result.status !== "finished") fail(result.error?.message || `agent run ${result.status}`);
+
+  const usage = result.usage || {};
+  process.stdout.write(JSON.stringify({
+    text: result.result || "",
+    usage: { input: usage.inputTokens, output: usage.outputTokens },
+  }));
+  process.exit(0);
+} catch (error) {
+  fail(error?.message || String(error));
+}

data/lib/plan_driven/cursor_llm.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "timeout"
+
+module PlanDriven
+  # Drafting through a Cursor agent (Claude Opus, GPT, Composer...) on the user's Cursor account.
+  # The agent runs locally with read-only tools, so it can read the application's code while it
+  # writes, and can't change a file. It goes through the Cursor SDK, which is Node, via
+  # cursor_llm.mjs.
+  class CursorLLM
+    BRIDGE = File.expand_path("cursor_llm.mjs", __dir__)
+
+    def initialize(config)
+      @config = config
+    end
+
+    def chat(system:, messages:)
+      data = run_bridge(JSON.generate(model: @config.llm_model, prompt: prompt(system, messages),
+                                      cwd: @config.root_path.to_s, sdkPaths: Array(@config.cursor_sdk_path)))
+      LLM::Reply.new(text: data["text"].to_s, input_tokens: data.dig("usage", "input"),
+                     output_tokens: data.dig("usage", "output"))
+    end
+
+    # [ok, detail] for doctor: whether Node can load the SDK.
+    def check
+      out, status = Open3.capture2e(@config.node_command, BRIDGE, "--check", @config.root_path.to_s,
+                                    *Array(@config.cursor_sdk_path))
+      data = parse(out)
+      [status.success?, data["error"] || "Node #{data["node"]}, @cursor/sdk found"]
+    rescue Errno::ENOENT
+      [false, "#{@config.node_command} not found; the Cursor SDK needs Node 22.13+"]
+    end
+
+    private
+
+    def prompt(system, messages)
+      turns = messages.map do |message|
+        message = message.to_h.stringify_keys
+        "## #{message["role"]}\n\n#{message["content"]}"
+      end
+      <<~PROMPT
+        #{system}
+
+        You are inside the application's repository and may read any file to ground your answer in
+        the real code. Don't try to change files. Reply with the JSON object only, no prose around it.
+
+        # Conversation
+
+        #{turns.join("\n\n")}
+      PROMPT
+    end
+
+    def run_bridge(input)
+      key = @config.llm_api_key or
+        raise ConfigurationError, "No Cursor API key. Run `plan-driven configure` or set CURSOR_API_KEY."
+
+      out, err, status = Timeout.timeout(@config.request_timeout) do
+        Open3.capture3({ "CURSOR_API_KEY" => key }, @config.node_command, BRIDGE, stdin_data: input)
+      end
+      data = parse(out)
+      return data if status.success? && !data.key?("error")
+
+      raise ProviderError, "cursor: #{data["error"] || err.to_s.strip.last(300).presence || "agent failed"}"
+    rescue Timeout::Error
+      raise ProviderError, "cursor: no answer within #{@config.request_timeout}s (config.request_timeout)"
+    rescue Errno::ENOENT
+      raise ConfigurationError, "#{@config.node_command} not found; the Cursor SDK needs Node 22.13+ " \
+                                "(set config.node_command or PLAN_DRIVEN_NODE)"
+    end
+
+    def parse(out)
+      JSON.parse(out.to_s.strip.lines.last.to_s)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end