plan_driven 0.1.0 → 0.3.0

data/lib/plan_driven/wizard.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "securerandom"
+require "shellwords"
+
+module PlanDriven
+  # The browser wizard at /plan_driven. Every button runs a real `plan-driven` command in the
+  # background and streams its output to the page, so the wizard can do nothing the CLI can't,
+  # and the terminal panel shows exactly which command ran.
+  module Wizard
+    # The commands the wizard may run, built from form fields. Nothing else reaches a shell:
+    # arguments are passed as an array, never interpolated.
+    module Commands
+      PLAN_ONLY = %w[check submit pdf status evidence report usage stats log].freeze
+
+      BUILDERS = {
+        "doctor" => ->(_p) { [] },
+        "new" => ->(p) { [required(p, "title")] },
+        "edit" => ->(p) { [plan(p), section(p), "--from", required(p, "file")] },
+        "redraft" => ->(p) { [plan(p), section(p), required(p, "instruction")] },
+        "approve" => ->(p) { [plan(p), *role(p), *note(p)] },
+        "reject" => ->(p) { [plan(p), *role(p), "--note", required(p, "note")] },
+        "tickets" => ->(p) { [plan(p), *p["instruction"].to_s.strip.presence] },
+        "approve-tickets" => ->(p) { [plan(p), *role(p)] },
+        "develop" => ->(p) { [plan(p), *Array(p["tickets"]).map { |key| ticket_key(key) }] },
+        "review" => ->(p) { [ticket(p)] },
+        "merge" => ->(p) { [ticket(p)] },
+        "approve-pr" => ->(p) { [ticket(p), *note(p)] },
+        "feedback" => ->(p) { [ticket(p), required(p, "feedback")] },
+        "questions" => ->(_p) { [] },
+        "question" => ->(p) { [question_key(p), *question_flags(p)] },
+        # The key itself goes on stdin, so it's never in the command line or the panel.
+        "connect" => ->(p) { [Connections.find(required(p, "service")).name] }
+      }.merge(PLAN_ONLY.to_h { |name| [name, ->(p) { [plan(p)] }] }).freeze
+
+      module_function
+
+      def argv(action, params)
+        builder = BUILDERS[action.to_s] or raise ArgumentError, "the wizard can't run `#{action}`"
+        [action.to_s, *builder.call(params.to_h.transform_keys(&:to_s)), "--yes"]
+      end
+
+      # What `new` reads on stdin. The interview takes each answer up to an empty line, so blank
+      # lines inside an answer are folded away, and an empty answer is the empty line alone.
+      def interview_input(template, answers)
+        template.asked.map do |section|
+          answer = answers[section.key].to_s.strip.gsub(/\r\n?/, "\n").gsub(/\n\s*\n+/, "\n")
+          answer.empty? ? "\n" : "#{answer}\n\n"
+        end.join
+      end
+
+      def required(params, name)
+        params[name].to_s.strip.presence or raise ArgumentError, "#{name.tr("_", " ")} is required"
+      end
+
+      def plan(params)
+        key = required(params, "plan").upcase
+        raise ArgumentError, "not a plan key" unless key.match?(/\A[A-Z]+-\d+\z/)
+
+        key
+      end
+
+      def ticket(params)
+        "#{plan(params)}/#{ticket_key(required(params, "ticket"))}"
+      end
+
+      def ticket_key(key)
+        key.to_s.upcase.tap { |value| raise ArgumentError, "not a ticket key" unless value.match?(/\AT\d+\z/) }
+      end
+
+      def section(params)
+        key = required(params, "section")
+        PlanDriven.configuration.template[key] or raise ArgumentError, "unknown section #{key}"
+        key
+      end
+
+      def role(params)
+        params["role"].to_s.strip.empty? ? [] : ["--as", params["role"].strip]
+      end
+
+      def note(params)
+        params["note"].to_s.strip.empty? ? [] : ["--note", params["note"].strip]
+      end
+
+      def question_key(params)
+        required(params, "key").tap do |key|
+          raise ArgumentError, "not a question key" unless key.match?(Interview::KEY)
+        end
+      end
+
+      def question_flags(params)
+        return ["--remove"] if params["remove"].to_s == "1"
+
+        flags = []
+        flags += ["--title", params["title"].strip] if params["title"].to_s.strip != ""
+        flags += ["--ask", params["question"].strip] if params["question"].to_s.strip != ""
+        flags += ["--group", params["group"]] if params["group"].to_s != ""
+        flags << "--required" if params["required"].to_s == "1"
+        flags << "--optional" if params["required"].to_s == "0"
+        flags
+      end
+    end
+
+    # One command run: its output in a log file, its state in a JSON file next to it, so any
+    # request (and any Puma thread) can read how it's going.
+    class Job
+      # About as many characters as fit on a line of the terminal panel, for tables.
+      PANEL_COLUMNS = 76
+      SERVER_ENV = %w[RAILS_ENV RACK_ENV PORT PIDFILE].freeze
+
+      attr_reader :id
+
+      def self.dir(root = PlanDriven.configuration.root_path)
+        root.join("tmp/plan_driven/wizard").tap { |path| FileUtils.mkdir_p(path) }
+      end
+
+      def self.find(id, root: PlanDriven.configuration.root_path)
+        raise ArgumentError, "not a job" unless id.to_s.match?(/\A[a-f0-9]{16}\z/)
+
+        new(id, root: root).tap { |job| raise ArgumentError, "no job #{id}" unless job.state_file.exist? }
+      end
+
+      # Starts `argv` in a thread and returns at once.
+      def self.start(argv, stdin: nil, actor: nil, root: PlanDriven.configuration.root_path)
+        job = new(SecureRandom.hex(8), root: root)
+        job.begin!(argv, stdin: stdin, actor: actor)
+        job
+      end
+
+      def initialize(id, root:)
+        @id = id
+        @root = Pathname(root)
+      end
+
+      def begin!(argv, stdin:, actor:)
+        command = executable + argv
+        write_state("command" => display(command, actor), "status" => "running", "started_at" => Time.now.to_i)
+        File.write(log_file, "")
+        Thread.new { execute(command, stdin, actor) }
+      end
+
+      def state
+        JSON.parse(state_file.read)
+      end
+
+      def output
+        log_file.exist? ? log_file.read.force_encoding(Encoding::UTF_8).scrub : ""
+      end
+
+      def to_h
+        state.merge("id" => id, "output" => output)
+      end
+
+      def state_file
+        self.class.dir(@root).join("#{id}.json")
+      end
+
+      def log_file
+        self.class.dir(@root).join("#{id}.log")
+      end
+
+      private
+
+      def execute(command, stdin, actor)
+        env = { "LANG" => "en_US.UTF-8", "LC_ALL" => "en_US.UTF-8", "NO_COLOR" => "1", "COLUMNS" => PANEL_COLUMNS.to_s }
+        # The server's own environment stays with the server: a command runs as it would when typed.
+        SERVER_ENV.each { |name| env[name] = nil }
+        env["PLAN_DRIVEN_ACTOR"] = actor if actor.present?
+        status = Open3.popen2e(env, *command, chdir: @root.to_s) do |input, output, thread|
+          input.write(stdin.to_s)
+          input.close
+          File.open(log_file, "a") do |log|
+            output.each_char do |char|
+              log.write(char)
+              log.flush if char == "\n"
+            end
+          end
+          thread.value
+        end
+        finish(status.exitstatus)
+      rescue StandardError => e
+        File.write(log_file, "\n✗ #{e.message}\n", mode: "a")
+        finish(1)
+      end
+
+      def finish(code)
+        write_state(state.merge("status" => code.to_i.zero? ? "succeeded" : "failed", "exit" => code,
+                                "finished_at" => Time.now.to_i))
+      end
+
+      def write_state(data)
+        File.write(state_file, JSON.generate(data))
+      end
+
+      def executable
+        binstub = @root.join("bin/plan-driven")
+        binstub.exist? ? ["bin/plan-driven"] : %w[bundle exec plan-driven]
+      end
+
+      def display(command, actor)
+        prefix = actor.present? ? "PLAN_DRIVEN_ACTOR=#{Shellwords.escape(actor)} " : ""
+        shown = command.map { |arg| arg.start_with?(@root.to_s) ? arg.delete_prefix("#{@root}/") : arg }
+        prefix + Shellwords.join(shown)
+      end
+    end
+
+    # The wizard's pages, in order, and which ones a plan in a given phase has reached.
+    module Steps
+      ORDER = [
+        ["plan", "Plan", "Read it, edit or redraft any section, then submit"],
+        ["approve", "Approve", "Every role signs off on this revision"],
+        ["tickets", "Tickets", "Draft the tickets, steer them, approve them"],
+        ["agents", "Agents & PRs", "One agent and one pull request per ticket"],
+        ["finish", "Proof & report", "Evidence, the delivery report, tokens and cost"]
+      ].freeze
+
+      REACHED = {
+        "draft" => "plan", "in_review" => "approve", "approved" => "tickets", "ticketed" => "tickets",
+        "tickets_approved" => "agents", "in_development" => "agents", "delivered" => "finish"
+      }.freeze
+
+      module_function
+
+      def keys
+        ORDER.map(&:first)
+      end
+
+      def current(plan)
+        REACHED.fetch(plan.status, "plan")
+      end
+
+      def reached?(plan, step)
+        keys.index(step).to_i <= keys.index(current(plan)).to_i
+      end
+    end
+  end
+end
+
+if defined?(Rails::Railtie)
+  require "rails/engine"
+  require_relative "wizard/engine"
+end

data/lib/plan_driven.rb

@@ -12,6 +12,8 @@ require_relative "plan_driven/errors"
 require_relative "plan_driven/credentials"
 require_relative "plan_driven/configuration"
 require_relative "plan_driven/template"
+require_relative "plan_driven/interview"
+require_relative "plan_driven/connections"
 require_relative "plan_driven/schema_context"
 require_relative "plan_driven/workflow"
 require_relative "plan_driven/models"
@@ -26,10 +28,15 @@ require_relative "plan_driven/agent_prompt"
 require_relative "plan_driven/http"
 require_relative "plan_driven/github"
 require_relative "plan_driven/cursor_agents"
+require_relative "plan_driven/local_agents"
+require_relative "plan_driven/usage"
 require_relative "plan_driven/repository"
-require_relative "plan_driven/renderer"
 require_relative "plan_driven/evidence"
+require_relative "plan_driven/statistics"
+require_relative "plan_driven/charts"
+require_relative "plan_driven/renderer"
 require_relative "plan_driven/delivery"
+require_relative "plan_driven/wizard"
 require_relative "plan_driven/railtie" if defined?(Rails::Railtie)
 
 module PlanDriven

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: plan_driven
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ivan Blažević
 bindir: exe
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -50,9 +50,10 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '9'
 description: |
-  plan_driven runs a Rails team's delivery process from the command line. A terminal interview
-  turns an idea into an implementation plan grounded in your real schema; the plan is checked
-  by guards written in Ruby, rendered to PDF and approved. Approved plans become tickets, each
+  plan_driven runs a Rails team's delivery process inside your Rails app, from a browser wizard
+  or the command line: every button in the wizard runs the same plan-driven command. A short
+  interview turns an idea into an implementation plan grounded in your real schema; the plan
+  is checked by guards written in Ruby, rendered to PDF and approved. Approved plans become tickets, each
   ticket is handed to a Cursor cloud agent that opens a pull request, and only pull requests
   you approve are merged. Acceptance criteria map to Cucumber scenarios, and every phase leaves
   documentation behind: the plan, the tickets, the pull requests and a delivery report.
@@ -66,18 +67,37 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- app/controllers/plan_driven/wizard/application_controller.rb
+- app/controllers/plan_driven/wizard/configuration_controller.rb
+- app/controllers/plan_driven/wizard/jobs_controller.rb
+- app/controllers/plan_driven/wizard/plans_controller.rb
+- app/views/layouts/plan_driven/wizard/application.html.erb
+- app/views/plan_driven/wizard/configuration/show.html.erb
+- app/views/plan_driven/wizard/plans/_agents.html.erb
+- app/views/plan_driven/wizard/plans/_approve.html.erb
+- app/views/plan_driven/wizard/plans/_finish.html.erb
+- app/views/plan_driven/wizard/plans/_plan.html.erb
+- app/views/plan_driven/wizard/plans/_tickets.html.erb
+- app/views/plan_driven/wizard/plans/index.html.erb
+- app/views/plan_driven/wizard/plans/new.html.erb
+- app/views/plan_driven/wizard/plans/show.html.erb
+- app/views/plan_driven/wizard/plans/statistics.html.erb
+- config/routes.rb
 - exe/plan-driven
 - lib/generators/plan_driven/install_generator.rb
 - lib/generators/plan_driven/templates/create_plan_driven_tables.rb.tt
 - lib/generators/plan_driven/templates/plan_driven.rb
 - lib/plan_driven.rb
 - lib/plan_driven/agent_prompt.rb
+- lib/plan_driven/charts.rb
 - lib/plan_driven/cli.rb
+- lib/plan_driven/cli/config_commands.rb
 - lib/plan_driven/cli/plan_commands.rb
 - lib/plan_driven/cli/setup_commands.rb
 - lib/plan_driven/cli/ticket_commands.rb
 - lib/plan_driven/cli/ui.rb
 - lib/plan_driven/configuration.rb
+- lib/plan_driven/connections.rb
 - lib/plan_driven/credentials.rb
 - lib/plan_driven/cursor_agents.rb
 - lib/plan_driven/cursor_llm.mjs
@@ -95,8 +115,10 @@ files:
 - lib/plan_driven/guards/ticket_guard.rb
 - lib/plan_driven/guards/ticket_normalizer.rb
 - lib/plan_driven/http.rb
+- lib/plan_driven/interview.rb
 - lib/plan_driven/json_reply.rb
 - lib/plan_driven/llm.rb
+- lib/plan_driven/local_agents.rb
 - lib/plan_driven/models.rb
 - lib/plan_driven/models/approval.rb
 - lib/plan_driven/models/event.rb
@@ -112,9 +134,13 @@ files:
 - lib/plan_driven/renderer/style.css
 - lib/plan_driven/repository.rb
 - lib/plan_driven/schema_context.rb
+- lib/plan_driven/statistics.rb
 - lib/plan_driven/template.rb
 - lib/plan_driven/ticket_generator.rb
+- lib/plan_driven/usage.rb
 - lib/plan_driven/version.rb
+- lib/plan_driven/wizard.rb
+- lib/plan_driven/wizard/engine.rb
 - lib/plan_driven/workflow.rb
 homepage: https://github.com/blaz1988/plan-driven
 licenses:
@@ -142,5 +168,5 @@ requirements: []
 rubygems_version: 3.6.4
 specification_version: 4
 summary: From implementation plan to merged, tested pull requests, driven from the
-  terminal.
+  browser or the terminal.
 test_files: []