@zalom/plastic 2.0.0-alpha.9 → 2.0.2

package/scripts/lib/cli/commands/auto_brief.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic auto brief` - an intent's spawn preamble (`spawn-preamble`, run
+# through Legacy). `--role advisor` also prints the three shapes an advisor
+# request takes, so a dispatching lead never has to look them up.
+module Plastic
+  class CLI
+    module Commands
+      class AutoBrief < IntentCommand
+        USAGE_LINE = "plastic auto brief ID [--role ROLE] [--json]"
+
+        SCRIPT = "spawn-preamble"
+        AFTER = "plastic auto report ID"
+        BECAUSE = "the report closes the turn the preamble opened"
+
+        ADVISOR_SHAPES =
+          "State the shape you need: a verdict plus the biggest risk for one bounded " \
+          "decision; a stepped plan plus a risk map for a plan or plan review; rival " \
+          "approaches and kill criteria for architecture, one-way doors, or deadlocks."
+
+        def call
+          super
+          @output.row("advisor request shapes", ADVISOR_SHAPES) if role == "advisor"
+        end
+
+        private
+
+        def role
+          options[:role]
+        end
+
+        def switches(parser)
+          parser.on("--role ROLE") { |v| @options[:role] = v }
+        end
+
+        def script_arguments
+          role ? [intent_dir, "--role", role] : [intent_dir]
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/auto_lock.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../command"
+require_relative "../legacy"
+
+# `plastic auto lock` - inspects, repairs, or releases an intent's delivery
+# lock (`plastic-lock status|fix|release --intent-dir DIR`, run through
+# Legacy). The verb comes first, then the id, since the verb is what the
+# table's two-token match consumes as part of the command name.
+#
+# `status` and `fix` speak JSON, so this command renders them as a screen and
+# leaves the document to `--json`. `release` already reports in prose. A lock
+# another session owns exits 3, which travels as a refusal.
+module Plastic
+  class CLI
+    module Commands
+      class AutoLock < Command
+        USAGE_LINE = "plastic auto lock status|fix|release ID [--json]"
+
+        VERBS = %w[status fix release].freeze
+        AFTER = {"status" => "none", "fix" => "plastic auto brief ID",
+                 "release" => "plastic session summary"}.freeze
+        BECAUSE = {"status" => "inspection is complete; a held lock does not authorize repair",
+                   "fix" => "a repaired lock is ready for the preamble again",
+                   "release" => "the summary is what a freed lock leads to"}.freeze
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          raise Usage, "VERB must be one of #{VERBS.join(", ")}" unless VERBS.include?(verb)
+
+          case verb
+          when "status" then screen(report("status"))
+          when "fix" then options[:json] ? run_verb : fix_screen(report("fix"))
+          else run_verb
+          end
+          @output.next_step(AFTER.fetch(verb).sub("ID", id.to_s), because: BECAUSE.fetch(verb))
+        end
+
+        private
+
+        def run_verb
+          status = legacy.run("plastic-lock", verb, "--intent-dir", intent_dir)
+          raise Failure, "plastic-lock exited #{status}" unless status.zero?
+        end
+
+        def report(name)
+          text, status = legacy.capture("plastic-lock", name, "--intent-dir", intent_dir)
+          raise Failure, "plastic-lock exited #{status}" unless status.zero?
+
+          JSON.parse(text)
+        rescue JSON::ParserError
+          raise Failure, "plastic-lock did not print a report"
+        end
+
+        def screen(report)
+          @output.row("intent", File.basename(report["intent_dir"].to_s))
+          @output.row("lock", lock_line(report))
+          @output.row("worktree", worktree_line(report["worktree"]))
+          @output.row("delivering", report["delivering"] ? "yes" : "no")
+          @output.row("claims", Array(report["claims"]).map(&:to_s))
+        end
+
+        def fix_screen(report)
+          lock = report["lock"] || {}
+          @output.row("lock", "#{report["status"]} by #{lock["owner_session"] || report["session"]}, " \
+                              "#{lock["run_mode"]} mode")
+          @output.row("actions", Array(report["actions"]).map(&:to_s))
+        end
+
+        def lock_line(report)
+          lock = report["lock"]
+          return "corrupt, plastic auto lock fix #{id} rewrites it" if report["lock_corrupt"]
+          return "none" if lock.nil?
+
+          holder = lock.is_a?(Hash) ? (lock["owner_session"] || lock["session"]) : lock
+          "held by #{holder}#{", stale" unless report["lock_fresh"]}"
+        end
+
+        def worktree_line(worktree)
+          return "none" unless worktree.is_a?(Hash) && worktree["provisioned"]
+
+          [worktree["code"], worktree["code_branch"]].compact.join("  on  ")
+        end
+
+        def verb
+          arguments[0]
+        end
+
+        def id
+          arguments[1]
+        end
+
+        def intent_dir
+          dir = scope.intent_dir(id)
+          raise Failure, "no intent #{id.inspect} in #{scope.slug}; plastic status lists the ones that exist" unless dir
+
+          dir
+        end
+
+        def legacy
+          @legacy ||= Legacy.new(env: @env, runner: @runner, output: @output, json: options[:json])
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/auto_report.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic auto report` - an intent's completion report (`agent-report`, run
+# through Legacy), then the review-by-risk rules a lead checks it against.
+module Plastic
+  class CLI
+    module Commands
+      class AutoReport < IntentCommand
+        USAGE_LINE = "plastic auto report ID [--role ROLE] [--json]"
+
+        SCRIPT = "agent-report"
+        AFTER = "plastic auto lock release ID"
+        BECAUSE = "closing the lock is what a delivered or abandoned report leads to"
+
+        REVIEW_RULES = <<~TEXT.chomp
+          Review by risk, boot 3, only when a rule fires; otherwise the green suite is
+          the review. Dispatch the post-execution reviewer when any of these holds:
+          1. the diff touches a path on the risk list (hooks, the lock, the arming
+             module, the installer, a release file).
+          2. a failure-mode matrix row names a test not in the diff, or a test the
+             green run did not execute.
+          3. the completion report carries a status other than delivered, or a
+             non-empty deviations or blockers field.
+          The reviewer returns a pass or fixes; at most one review-fix round, ever.
+        TEXT
+
+        def call
+          super
+          @output.row("review rules", REVIEW_RULES)
+        end
+
+        private
+
+        def role
+          options[:role]
+        end
+
+        def switches(parser)
+          parser.on("--role ROLE") { |v| @options[:role] = v }
+        end
+
+        def script_arguments
+          role ? [intent_dir, "--role", role] : [intent_dir]
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/auto_take.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "intent_command"
+
+# `plastic auto take` - arms the intent's delivery lock for this session
+# (`plastic-lock arm --intent-dir DIR --mode auto`, run through Legacy).
+# The lock records who took it: --harness, --agent, --model and --thread pass
+# through, and a Claude Code session names its harness when none is given.
+# plastic-lock answers in JSON, so this command renders it as a screen and
+# leaves the document to `--json`. A lock another session owns exits 3.
+module Plastic
+  class CLI
+    module Commands
+      class AutoTake < IntentCommand
+        USAGE_LINE = "plastic auto take ID [--allow-inline] [--harness NAME] [--agent NAME] " \
+                     "[--model MODEL] [--thread ID] [--json]"
+
+        SCRIPT = "plastic-lock"
+        AFTER = "plastic auto brief ID"
+        BECAUSE = "the preamble is the live state a taken intent is read from next"
+        PROVENANCE = %i[harness agent model thread].freeze
+
+        def call
+          return super if options[:json]
+
+          text, status = legacy.capture(SCRIPT, *script_arguments)
+          raise Failure, "#{SCRIPT} exited #{status}" unless status.zero?
+
+          screen(JSON.parse(text))
+          command, reason = after_run
+          @output.next_step(command, because: reason)
+        rescue JSON::ParserError
+          raise Failure, "#{SCRIPT} did not print a report"
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--allow-inline") { @options[:allow_inline] = true }
+          PROVENANCE.each do |name|
+            parser.on("--#{name} VALUE") { |value| @options[name] = value }
+          end
+        end
+
+        def script_arguments
+          args = ["arm", "--intent-dir", intent_dir, "--mode", "auto"]
+          provenance.each { |name, value| args.push("--#{name}", value) }
+          args << "--allow-inline" if options[:allow_inline]
+          args
+        end
+
+        def provenance
+          given = PROVENANCE.to_h { |name| [name, options[name]] }
+          given[:harness] ||= "claude" if @env["CLAUDE_CODE_SESSION_ID"].to_s.strip != ""
+          given.compact
+        end
+
+        def screen(report)
+          worktree = report["worktree"] || {}
+          @output.row("intent", File.basename(report["intent_dir"].to_s))
+          @output.row("lock", "#{report["status"]} by #{report["session"]}, #{report["run_mode"]} mode")
+          @output.row("worktree", worktree["provisioned"] ? worktree["code"].to_s : "none")
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/backup.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "version"
+require_relative "../../backup"
+
+module Plastic
+  class CLI
+    module Commands
+      class Backup < Command
+        USAGE_LINE = "plastic backup [--list] [--json]"
+
+        def call
+          options[:list] ? list : write
+        rescue Plastic::Backup::Missing => e
+          @output.next_step("plastic sync", because: "a backup copies the three databases, and sync builds them")
+          raise Failure, "no #{e.message} at #{scope.plastic_home}; run plastic sync"
+        rescue Sqlite::Error => e
+          raise Failure, e.message
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--list") { options[:list] = true }
+        end
+
+        def write
+          version = Version.new([], out: nil, err: nil, env: @env).found.last
+          @output.row("archive", Plastic::Backup.call(scope.plastic_home, version: version))
+          @output.next_step("plastic backup --list", because: "to restore, unpack the archive into an empty ~/.plastic and run plastic checkout")
+        end
+
+        def list
+          archives = Plastic::Backup.list(scope.plastic_home)
+          archives.each { |path| @output.row(File.basename(path), "#{File.size(path)} bytes  #{File.mtime(path).strftime("%Y-%m-%d %H:%M")}") }
+          @output.row("result", "no backup yet") if archives.empty?
+          @output.next_step("plastic backup", because: "copying backups/ off this machine is your choice; Plastic sends nothing")
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/checkout.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../../store_sync"
+
+module Plastic
+  class CLI
+    module Commands
+      class Checkout < Command
+        USAGE_LINE = "plastic checkout [--json]"
+
+        def call
+          home = scope.plastic_home
+          raise Failure, "no databases at #{home}; run plastic sync" unless File.exist?(ReferenceArchive.path(home))
+
+          restored = StoreSync.checkout(home)
+          @output.row("restored", restored.empty? ? "nothing was missing" : restored)
+          @output.next_step("plastic sync --dry-run", because: "checkout restores missing files only; a changed file is never overwritten")
+        rescue Sqlite::Error => e
+          raise Failure, e.message
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/continue.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../frontier"
+require_relative "../scope"
+
+# `plastic continue` - where one project stands and what runs next: the store it
+# uses, the intents it has open, its liveliest roadmap and that roadmap's
+# frontier, then the step to take and the rule behind it.
+#
+# With no roadmap the first active intent answers instead, so a project that
+# never grew a roadmap still gets a next step.
+module Plastic
+  class CLI
+    module Commands
+      class Continue < Command
+        USAGE_LINE = "plastic continue [--project SLUG] [--json]"
+
+        def call
+          @output.row("project", scope.slug)
+          @output.row("root", scope.root)
+          @output.row("active", active)
+          @output.row("roadmap", roadmap)
+          command, because = decision
+          @output.next_step(command, because: because)
+        rescue RoadmapSavepoint::MissingGroupingHeading => e
+          raise Failure, e.message
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--project SLUG") { |slug| @options[:project] = slug }
+        end
+
+        def active
+          scope.active_entries.map { |id, title| "#{id}  #{title}" }
+        end
+
+        def roadmap
+          return Frontier::NONE unless frontier.roadmap
+
+          "#{frontier.roadmap}  frontier #{frontier.heading}"
+        end
+
+        def decision
+          return [frontier.next_step, frontier.because] if frontier.roadmap
+
+          id = scope.active_ids.first
+          return [plan_for(id), "#{id} is the first active intent in #{scope.slug}"] if id
+
+          ["plastic help", "#{scope.slug} has no active work and no roadmap"]
+        end
+
+        def plan_for(id)
+          dir = scope.intent_dir(id)
+          dir ? "plastic intent show #{id}" : "plastic status"
+        end
+
+        def frontier
+          @frontier ||= Frontier.new(scope)
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/doctor.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "installer_verb"
+
+# `plastic doctor` - diagnoses Plastic installation health. The work is still
+# scripts/doctor.rb, run through Legacy; each finding prints its own repair.
+# The script speaks JSON, so this command renders it as a screen and keeps the
+# document itself behind `--json`, the way every other command reads. A report
+# that is not `pass` exits non-zero, because findings are what doctor is for.
+#
+# InstallerVerb keeps the raw argv rather than running the option parser, so
+# `--json` is taken off the line here instead of through `options`.
+module Plastic
+  class CLI
+    module Commands
+      class Doctor < InstallerVerb
+        USAGE_LINE = "plastic doctor [--core] [--agent claude|codex|hermes] [--store WHICH] [--json]"
+        FLAGS = %w[--core --agent --store].freeze
+
+        SCRIPT = "doctor.rb"
+        AFTER = "none"
+        BECAUSE = "the findings are the whole answer, and each one names its own repair"
+
+        def call
+          as_document = !@argv.delete("--json").nil?
+          unknown = arguments.grep(/\A-/) - FLAGS
+          raise Usage, "#{unknown.first} is not a flag of this command" unless unknown.empty?
+
+          report = parse(legacy.capture(SCRIPT, *arguments).first)
+          as_document ? document(report) : screen(report)
+          @output.next_step(AFTER, because: BECAUSE)
+          flush
+          raise Failure, verdict(report) unless report["status"] == "pass"
+        end
+
+        def flush
+          @output.flush(json: false) unless @document_printed
+        end
+
+        private
+
+        def parse(report)
+          JSON.parse(report)
+        rescue JSON::ParserError
+          raise Failure, "#{SCRIPT} did not print a report"
+        end
+
+        def document(report)
+          @document_printed = true
+          @output.document(report)
+        end
+
+        def findings(report)
+          report["checks"].to_a.reject { |check| check["status"] == "pass" }
+        end
+
+        def verdict(report)
+          found = findings(report)
+          "doctor found #{found.size} #{(found.size == 1) ? "finding" : "findings"}, listed above"
+        end
+
+        def screen(report)
+          checks = report["checks"].to_a
+          found = findings(report)
+
+          @output.row("status", "#{report["status"]}  #{checks.size - found.size} of #{checks.size} checks pass")
+          @output.row("version", report["version"])
+          @output.row("agent", report["agent"])
+          found.each { |finding| finding_rows(finding) }
+        end
+
+        def finding_rows(finding)
+          name = [finding["category"], finding["name"]].compact.join("/")
+          @output.row(finding["status"], "#{name}  #{finding["message"]}")
+          @output.row("", "fix: #{finding["fix_hint"]}") if finding["fix_hint"]
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/feedback.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+
+# `plastic feedback "TITLE"` - files a report with feedback-report, the body
+# read from standard input and passed to the child process unchanged.
+module Plastic
+  class CLI
+    module Commands
+      class Feedback < Command
+        USAGE_LINE = 'plastic feedback "TITLE"'
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          raise Usage, "plastic feedback needs a title" if title.nil? || title.strip.empty?
+
+          status = legacy.run("feedback-report", "--title", title)
+          raise Failure, "feedback-report exited #{status}" unless status.zero?
+
+          @output.next_step("none", because: "the report is saved as a draft; open the printed URL to send it")
+        end
+
+        private
+
+        def title
+          arguments.first
+        end
+
+        def legacy
+          @legacy ||= Legacy.new(env: @env, runner: @runner, output: @output, json: options[:json])
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/help.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../table"
+
+# `plastic help` - the command list plus the help topics, straight out of the
+# table and docs/help, or one command's usage line, or one topic's chapter. A
+# command name always wins over a topic of the same name. The list loads no
+# command file: that is what the table's summary column is for.
+module Plastic
+  class CLI
+    module Commands
+      class Help < Command
+        USAGE_LINE = "plastic help [COMMAND|TOPIC] [--json]"
+
+        def call
+          name = arguments.join(" ")
+          return list if name.empty?
+          return one_command(name) if TABLE.key?(name)
+          return one_topic(name) if topic?(name)
+
+          raise Usage, "no command or help topic named #{name.inspect}"
+        end
+
+        private
+
+        def list
+          @output.row("usage", "plastic <command> [options]")
+          TABLE.sort.each { |name, (_file, _const, summary)| @output.row(name, summary) }
+          @output.row("topics", topic_names)
+          @output.next_step("plastic status", because: "it needs no argument and names the rest")
+        end
+
+        def one_command(name)
+          file, const, summary = TABLE.fetch(name)
+          require_relative "../#{file}"
+          @output.row("usage", Commands.const_get(const)::USAGE_LINE)
+          @output.row("summary", summary)
+          @output.next_step("none", because: "the usage line is the whole answer")
+        end
+
+        def one_topic(name)
+          @output.row(name, File.read(topic_path(name)))
+          @output.next_step("none", because: "the chapter is the whole answer")
+        end
+
+        def topic?(name)
+          name == File.basename(name) && File.file?(topic_path(name))
+        end
+
+        def topic_names
+          Dir.glob(File.join(help_dir, "*.md")).map { |path| File.basename(path, ".md") }.sort
+        end
+
+        def topic_path(name)
+          File.join(help_dir, "#{name}.md")
+        end
+
+        def help_dir
+          File.join(package_root, "docs", "help")
+        end
+
+        def package_root
+          @env["PLASTIC_PACKAGE_ROOT"] || File.expand_path("../../../..", __dir__)
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/hook.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "English"
+require_relative "../command"
+require_relative "../legacy"
+
+module Plastic
+  class CLI
+    module Commands
+      class Hook < Command
+        USAGE_LINE = "plastic hook EVENT"
+        EVENTS = %w[call-budget capture close record savepoint session-start stop].freeze
+
+        DEFAULT_RUNNER = lambda do |path|
+          system(path)
+          Legacy.exit_code($CHILD_STATUS)
+        end
+
+        def self.call(argv, runner: DEFAULT_RUNNER, **seams)
+          return super(argv, **seams) unless EVENTS.include?(argv.first)
+
+          root = Legacy.new(env: seams.fetch(:env, ENV)).package_root
+          runner.call(File.join(root, "hooks", argv.first))
+        end
+
+        def call
+          raise Usage, "EVENT is one of #{EVENTS.join(", ")}"
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/index.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../../search_index"
+
+module Plastic
+  class CLI
+    module Commands
+      class Index < Command
+        USAGE_LINE = "plastic index [--json]"
+
+        def call
+          count = SearchIndex.build(scope.plastic_home)
+          @output.row("indexed", "#{count} files")
+          @output.row("database", SearchIndex.path(scope.plastic_home))
+          @output.next_step("plastic search TERMS", because: "the index is whole and new; it is rebuilt, never updated")
+        rescue Sqlite::Error => e
+          raise Failure, e.message
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/commands/install.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "installer_verb"
+
+# `plastic install` - wires Plastic into this machine's agents. The work is
+# still scripts/install.rb, run as a child process through Legacy; this command
+# is what replaces the Node shim the npm package used to carry.
+module Plastic
+  class CLI
+    module Commands
+      class Install < InstallerVerb
+        USAGE_LINE = "plastic install [--claude] [--codex] [--hermes] [--all] [--reinstall] [--force] [--advisor NAME] [--no-advisor] [--statusline] [--ledger-action NAME]"
+        FLAGS = %w[--claude --codex --hermes --all --reinstall --force --advisor --no-advisor --statusline --ledger-action].freeze
+
+        SCRIPT = "install.rb"
+        AFTER = "plastic version"
+        BECAUSE = "the install is done, and the version proves the command works"
+      end
+    end
+  end
+end