@zalom/plastic 2.0.0-alpha.27 → 2.0.0-alpha.29

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)
+        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

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+
+module Plastic
+  class CLI
+    module Commands
+      class InstallerVerb < Command
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          unknown = arguments.grep(/\A-/) - self.class::FLAGS
+          raise Usage, "#{unknown.first} is not a flag of this command" unless unknown.empty?
+
+          status = legacy.run(self.class::SCRIPT, *arguments)
+          raise Failure, "#{self.class::SCRIPT} exited #{status}" unless status.zero?
+
+          @output.next_step(self.class::AFTER, because: self.class::BECAUSE)
+        end
+
+        private
+
+        def options
+          @options ||= {}
+        end
+
+        def legacy
+          @legacy ||= Legacy.new(env: @env, runner: @runner)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "subcommand_list"
+
+# `plastic intent` - the list of `plastic intent ...` subcommands, straight out
+# of the table; a word that names none of them is a usage error naming the
+# same list, so a typo never falls through to a script.
+module Plastic
+  class CLI
+    module Commands
+      class Intent < SubcommandList
+        USAGE_LINE = "plastic intent SUBCOMMAND [options]"
+        PREFIX = "intent"
+        NEXT = "plastic intent show ID"
+        BECAUSE = "an id is the one thing every other subcommand needs"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic intent answer` - closes a `needs_decision` node with the owner's
+# ruling (`runner answer`, run through Legacy).
+module Plastic
+  class CLI
+    module Commands
+      class IntentAnswer < IntentCommand
+        USAGE_LINE = 'plastic intent answer ID --node NODE --decision "TEXT" [--json]'
+
+        SCRIPT = "runner"
+        AFTER = "plastic intent step ID"
+        BECAUSE = "step resumes the graph past the node this decision just closed"
+
+        def call
+          raise Usage, "--node is required" if options[:node].to_s.empty?
+          raise Usage, "--decision is required" if options[:decision].to_s.empty?
+
+          super
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--node ID") { |v| @options[:node] = v }
+          parser.on("--decision TEXT") { |v| @options[:decision] = v }
+        end
+
+        def script_arguments
+          ["answer", intent_dir, "--node", options[:node], "--answer", options[:decision]]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+
+# Plastic::CLI::Commands::IntentCommand (intent 372, family 2) - the shared
+# base every `plastic intent ...` subcommand runs on: it turns the positional
+# id into an intent directory through Scope, runs the one script the
+# subclass names, and prints the `next:`/`because:` trailer the plan calls
+# for. A subcommand that needs more than that (extra usage checks, printed
+# guidance, a different script-exit contract) overrides `call`.
+module Plastic
+  class CLI
+    module Commands
+      class IntentCommand < Command
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          status = legacy.run(self.class::SCRIPT, *script_arguments)
+          raise Failure, "#{self.class::SCRIPT} exited #{status}" unless status.zero?
+
+          @output.next_step(self.class::AFTER.sub("ID", id.to_s), because: self.class::BECAUSE)
+        end
+
+        private
+
+        def id
+          arguments.first
+        end
+
+        def intent_dir
+          return @intent_dir if defined?(@intent_dir)
+
+          @intent_dir = scope.intent_dir(id)
+          return @intent_dir if @intent_dir
+
+          raise Failure, "no intent #{id.inspect} in #{scope.slug}; plastic status lists the ones that exist"
+        end
+
+        def legacy
+          @legacy ||= Legacy.new(env: @env, runner: @runner)
+        end
+
+        def script_arguments
+          raise NoMethodError, "#{self.class} must define script_arguments"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic intent end` - closes an intent as delivered or abandoned
+# (`end-intent`, run through Legacy). end-intent's own exit code 4 is a
+# pre-flight refusal (a live foreign session holds the delivery lock), not
+# the exit 3 Legacy's generic contract turns into a Refusal on its own, so
+# this command maps it by hand rather than through Legacy#run.
+module Plastic
+  class CLI
+    module Commands
+      class IntentEnd < IntentCommand
+        USAGE_LINE = 'plastic intent end ID --delivered|--abandoned --summary "TEXT" [--note "TEXT"] [--dry-run] [--json]'
+
+        REFUSAL_STATUS = 4
+
+        SUMMARY_GUIDANCE = [
+          "a good summary is written for the reader deciding whether to merge, release, or accept",
+          "delivered: what shipped, impact and risk first, in plain language, never the checklist",
+          "abandoned: why, and the trail if part of the work was dropped mid-flight"
+        ].freeze
+
+        def call
+          raise Usage, "one of --delivered or --abandoned is required" unless disposition
+          raise Usage, SUMMARY_GUIDANCE.join("\n") if options[:summary].to_s.empty?
+
+          status = legacy.run("end-intent", *end_intent_arguments)
+          raise Refusal, "end-intent needs the owner: the delivery lock is held" if status == REFUSAL_STATUS
+          raise Failure, "end-intent exited #{status}" unless status.zero?
+
+          @output.next_step("plastic status", because: "the intent moved out of Active")
+        end
+
+        private
+
+        def disposition
+          return "delivered" if options[:delivered]
+          "abandoned" if options[:abandoned]
+        end
+
+        def switches(parser)
+          parser.on("--delivered") { @options[:delivered] = true }
+          parser.on("--abandoned") { @options[:abandoned] = true }
+          parser.on("--summary TEXT") { |v| @options[:summary] = v }
+          parser.on("--note TEXT") { |v| @options[:note] = v }
+          parser.on("--dry-run") { @options[:dry_run] = true }
+        end
+
+        def end_intent_arguments
+          intent_dir
+          args = ["--store", scope.store, "--id", id, "--disposition", disposition,
+            "--outcome-summary", options[:summary]]
+          args += ["--index-note", options[:note]] if options[:note]
+          args << "--dry-run" if options[:dry_run]
+          args
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+require_relative "../../index_entry"
+
+module Plastic
+  class CLI
+    module Commands
+      class IntentNew < Command
+        USAGE_LINE = 'plastic intent new "LINE" [--slug SLUG] [--parent ID] [--sources IDS] [--tags TAGS] [--json]'
+        PASSED_THROUGH = %i[parent sources tags].freeze
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          raise Usage, "the one-line intent statement is required" if line.to_s.empty?
+
+          status = Legacy.new(env: @env, runner: @runner).run("new-intent", *new_intent_arguments)
+          raise Failure, "new-intent exited #{status}" unless status.zero?
+
+          IndexEntry.add_active(scope.index_path, dir_name: dir_name, title: line)
+          @output.next_step("plastic intent spec #{id}", because: "a new intent has no specification yet")
+        end
+
+        private
+
+        def line
+          arguments.first
+        end
+
+        def slug
+          options[:slug] || line.downcase.scan(/[a-z0-9]+/).first(5).join("-")
+        end
+
+        def dir_name
+          newest = Dir.glob(File.join(scope.store, "*--#{slug}")).max_by { |path| File.mtime(path) }
+          raise Failure, "new-intent made no directory for #{slug}" unless newest
+
+          File.basename(newest)
+        end
+
+        def id
+          dir_name.split("--").first
+        end
+
+        def switches(parser)
+          parser.on("--slug SLUG") { |v| @options[:slug] = v }
+          PASSED_THROUGH.each { |key| parser.on("--#{key} VALUE") { |v| @options[key] = v } }
+        end
+
+        def new_intent_arguments
+          given = PASSED_THROUGH.select { |key| options[key] }
+          ["--store", scope.store, "--intent", line, "--slug", slug] + given.flat_map { |key| ["--#{key}", options[key]] }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic intent note` - appends a savepoint line to an intent
+# (`savepoint-note`, run through Legacy). `--kind` defaults to Report, the
+# most general of the three savepoint kinds, for a note that names no kind
+# of its own.
+module Plastic
+  class CLI
+    module Commands
+      class IntentNote < IntentCommand
+        USAGE_LINE = 'plastic intent note ID "TEXT" [--kind Review|Commit|Report] [--json]'
+
+        SCRIPT = "savepoint-note"
+        AFTER = "plastic intent show ID"
+        BECAUSE = "the state screen carries the savepoint trail this just wrote"
+
+        DEFAULT_KIND = "Report"
+
+        def call
+          raise Usage, "the note text is required" if text.to_s.empty?
+
+          super
+        end
+
+        private
+
+        def text
+          arguments[1]
+        end
+
+        def switches(parser)
+          parser.on("--kind KIND") { |v| @options[:kind] = v }
+        end
+
+        def script_arguments
+          [intent_dir, "--kind", options[:kind] || DEFAULT_KIND, "--text", text]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic intent rule` - records one ruling in an intent's `## Insights`
+# (`insight-append`, run through Legacy, stamped `--stage Why --author human`
+# since a rule is always the owner's).
+module Plastic
+  class CLI
+    module Commands
+      class IntentRule < IntentCommand
+        USAGE_LINE = 'plastic intent rule ID "TEXT" [--json]'
+
+        SCRIPT = "insight-append"
+        AFTER = "plastic intent show ID"
+        BECAUSE = "the state screen reads Insights straight off the ledger this just wrote"
+
+        def call
+          raise Usage, "the ruling text is required" if text.to_s.empty?
+
+          super
+        end
+
+        private
+
+        def text
+          arguments[1]
+        end
+
+        def script_arguments
+          [intent_dir, text, "--stage", "Why", "--author", "human"]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic intent show` - an intent's state screen (`report-screen state`, run
+# through Legacy).
+module Plastic
+  class CLI
+    module Commands
+      class IntentShow < IntentCommand
+        USAGE_LINE = "plastic intent show ID [--json]"
+
+        SCRIPT = "report-screen"
+        AFTER = "plastic intent step ID"
+        BECAUSE = "the state screen is where the next step comes from"
+
+        private
+
+        def script_arguments
+          ["state", intent_dir]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic intent spec` - an intent's state screen (`report-screen state`,
+# same as `plastic intent show`), then the five rules the speccing
+# conversation itself runs on, so the reply carries both without a second
+# call.
+module Plastic
+  class CLI
+    module Commands
+      class IntentSpec < IntentCommand
+        USAGE_LINE = "plastic intent spec ID [--json]"
+
+        SCRIPT = "report-screen"
+        AFTER = 'plastic intent rule ID "TEXT"'
+        BECAUSE = "a ruling is recorded the moment it lands, never batched"
+
+        RULES = [
+          "1. context first: read the project state and the intent's Context and Insights",
+          "2. assess scope: several independent subsystems become separate thinking conversations",
+          "3. one question per message, in prose; look at the code before asking how something works",
+          "4. propose two or three approaches, trade-offs first, leading with the recommendation",
+          "5. present the design in sections scaled to complexity; get a ruling after each section",
+          "6. record every ruling the instant it lands, never batched:",
+          '   plastic intent rule ID "<ruling text>"',
+          "7. a later ruling that conflicts with an earlier one gets a new insight naming it superseded",
+          "8. both rulings stay on record; the later one wins"
+        ].freeze
+
+        def call
+          super
+          @output.row("rules", RULES)
+        end
+
+        private
+
+        def script_arguments
+          ["state", intent_dir]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic intent step` - runs the graph's next ready step (`runner step`, run
+# through Legacy). An intent with no `graph.md` gets the four-line non-graph
+# procedure printed alongside it, since there is no graph for `step` itself
+# to drive.
+module Plastic
+  class CLI
+    module Commands
+      class IntentStep < IntentCommand
+        USAGE_LINE = "plastic intent step ID [--json]"
+
+        SCRIPT = "runner"
+        AFTER = "plastic intent step ID"
+        BECAUSE = "call step again after each dispatched node returns"
+
+        NON_GRAPH_WORK = [
+          "no graph.md: dispatch ONE plastic-executor subagent with the whole consolidated action pasted in, never a file reference",
+          "it writes the matrix's tests and commits them red, implements the action in order, and drives the suite green",
+          "a tick is two edits made together: mark the item's box [x], and move it from ## In Progress to ## Completed",
+          "add one ## Session Log row per tick; never batch several tasks into one later edit"
+        ].freeze
+
+        def call
+          super
+          @output.row("non-graph work", NON_GRAPH_WORK) unless graph?
+        end
+
+        private
+
+        def graph?
+          File.exist?(File.join(intent_dir, "graph.md"))
+        end
+
+        def script_arguments
+          ["step", intent_dir]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+
+# `plastic intent verify` - the merge-gate checks one intent needs before a
+# close is trustworthy (`verify-intent`, run through Legacy).
+module Plastic
+  class CLI
+    module Commands
+      class IntentVerify < IntentCommand
+        USAGE_LINE = "plastic intent verify ID [--json]"
+
+        SCRIPT = "verify-intent"
+        AFTER = 'plastic intent end ID --delivered --summary "TEXT"'
+        BECAUSE = "a clean verify is what makes the close trustworthy"
+
+        private
+
+        def script_arguments
+          intent_dir
+          ["--store", scope.store, "--id", id]
+        end
+      end
+    end
+  end
+end