@zalom/plastic 2.0.0-alpha.9 → 2.0.2

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, output: @output, json: options[:json])
+        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,58 @@
+# 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?
+
+          command, reason = after_run
+          @output.next_step(command, because: reason)
+        end
+
+        private
+
+        def after_run
+          [self.class::AFTER.sub("ID", id.to_s), self.class::BECAUSE]
+        end
+
+        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, output: @output, json: options[:json])
+        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,75 @@
+# 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
+
+        # end-intent's own refusals the agent can act on: the reason is theirs to
+        # fix, so they stay failures (exit 1), but each is named rather than
+        # surfaced as a bare exit code.
+        REFUSED = {
+          7 => "end-intent refused a hollow delivered close: write outcome.md's ## Delivered rows to match the action headings",
+          8 => "end-intent refused to deliver an untouched scaffold: do the work first, or close it with --abandoned",
+          9 => "end-intent refused a delivered close whose code is not merged: run the git merge it names in the repo, then run the close again"
+        }.freeze
+
+        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, "choose only one of --delivered or --abandoned" if options[:delivered] && options[:abandoned]
+          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, REFUSED.fetch(status) { "end-intent exited #{status}" } unless status.zero?
+
+          if options[:dry_run]
+            @output.next_step("none", because: "the dry run wrote nothing and found nothing that would refuse the close")
+          else
+            @output.next_step("plastic status", because: "the intent moved out of Active")
+          end
+        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, output: @output, json: options[:json]).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,32 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+require_relative "../intent_progress"
+
+# `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"
+
+        def call
+          super
+          command, reason = IntentProgress.new(scope, id).decision
+          @output.next_step(command, because: reason)
+        end
+
+        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,79 @@
+# frozen_string_literal: true
+
+require_relative "intent_command"
+require_relative "../intent_progress"
+require_relative "../../runner_core"
+
+# `plastic intent step` - runs the graph's next ready step (`runner step`, run
+# through Legacy). Direct intents report their next checklist item. Graph
+# execution requires ownership, resolved by the same rules as the runner.
+module Plastic
+  class CLI
+    module Commands
+      class IntentStep < IntentCommand
+        USAGE_LINE = "plastic intent step ID [--return NODE=PATH] [--harness NAME] [--allow-core-drift] [--json]"
+
+        SCRIPT = "runner"
+        AFTER = "plastic intent step ID"
+        BECAUSE = "call step again after each dispatched node returns"
+        COMPLETE = "every node in the graph has finished"
+
+        def call
+          intent_dir
+          command, reason = IntentProgress.new(scope, id).decision
+          return @output.next_step(command, because: reason) if command == "none"
+
+          if graph?
+            return unless graph_owner?
+
+            super
+          elsif command == "plastic intent step #{id}"
+            item = IntentScreen.checklist_items(intent_dir).find { |entry| !entry[:done] }
+            @output.row("work", item[:text])
+            @output.row("checklist", File.join(intent_dir, "checklist.md"))
+            @output.next_step("none", because: "perform this checklist item, record its verification, then run plastic intent show #{id} --project #{scope.slug}")
+          else
+            @output.next_step(command, because: reason)
+          end
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--return NODE=PATH") { |pair| (@options[:returns] ||= []) << pair }
+          parser.on("--harness NAME") { |name| @options[:harness] = name }
+          parser.on("--allow-core-drift") { @options[:allow_core_drift] = true }
+        end
+
+        def graph_owner?
+          session = RunnerCore.resolve_owning_session(intent_dir, explicit: nil,
+            env_session: @env["CLAUDE_CODE_SESSION_ID"], store: scope.store, intent_id: id)
+          return true if session
+          raise Refusal, "intent #{id} is held by another session; inspect with plastic auto lock status #{id} --project #{scope.slug}" if Lock.read(intent_dir)
+          raise Refusal, "return not accepted: take intent #{id} with plastic auto take #{id} --project #{scope.slug} before submitting it" unless Array(options[:returns]).empty?
+
+          @output.next_step("plastic auto take #{id}", because: "graph execution requires this session to take the delivery lock")
+          false
+        end
+
+        def after_run
+          return super unless RunnerCore.complete?(RunnerCore.context(intent_dir: intent_dir, home: File.dirname(scope.plastic_home)))
+
+          ["plastic intent verify #{id}", COMPLETE]
+        end
+
+        def graph?
+          File.exist?(File.join(intent_dir, "graph.md"))
+        end
+
+        def script_arguments
+          args = ["step", intent_dir]
+          Array(options[:returns]).each { |pair| args.concat(["--return", pair]) }
+          args.concat(["--harness", options[:harness]]) if options[:harness]
+          args << "--allow-core-drift" if options[:allow_core_drift]
+          args
+        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

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "subcommand_list"
+
+module Plastic
+  class CLI
+    module Commands
+      class Migrate < SubcommandList
+        USAGE_LINE = "plastic migrate SUBCOMMAND [options]"
+        PREFIX = "migrate"
+        NEXT = "plastic migrate stores --dry-run"
+        BECAUSE = "a dry run prints every move and rewrite and changes nothing"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../../stores_move"
+
+module Plastic
+  class CLI
+    module Commands
+      class MigrateStores < Command
+        USAGE_LINE = "plastic migrate stores [--dry-run] [--json]"
+
+        def call
+          move = StoresMove.new(scope.plastic_home, qmd_index: File.join(@home, ".config", "qmd", "index.yml"), dry_run: options[:dry_run])
+          move.call.each { |verb, text| @output.row(verb, text) }
+          return @output.next_step("plastic migrate stores", because: "the dry run changed nothing") if options[:dry_run]
+
+          @output.row("remove", "rm -rf #{move.copy}")
+          @output.next_step("plastic doctor", because: "it checks the moved stores, and the copy stays until you remove it")
+        rescue StoresMove::Refused => e
+          raise Refusal, e.message
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--dry-run") { options[:dry_run] = true }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../frontier"
+require_relative "../scope"
+
+# `plastic next` - one line saying what to pick up, then the step to take and
+# the rule that chose it. `--why` adds the roadmap, its frontier batch, and
+# what is dispatchable, in flight and blocked.
+module Plastic
+  class CLI
+    module Commands
+      class Next < Command
+        USAGE_LINE = "plastic next [--why] [--project SLUG] [--json]"
+
+        def call
+          active_id = scope.active_ids.first unless frontier.roadmap
+          @output.row("next work", active_id ? "#{active_id}  in #{scope.slug}" : frontier.summary)
+          detail if options[:why]
+          if active_id
+            @output.next_step("plastic intent show #{active_id}", because: "#{active_id} is the first active intent in #{scope.slug}")
+          else
+            @output.next_step(frontier.next_step, because: frontier.because)
+          end
+        rescue RoadmapSavepoint::MissingGroupingHeading => e
+          raise Failure, e.message
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--why") { @options[:why] = true }
+          parser.on("--project SLUG") { |slug| @options[:project] = slug }
+        end
+
+        def detail
+          @output.row("roadmap", frontier.roadmap || Frontier::NONE)
+          @output.row("frontier", frontier.heading || Frontier::NONE)
+          @output.row("dispatchable", listed(frontier.dispatchable_ids))
+          @output.row("in flight", listed(frontier.in_flight_ids))
+          @output.row("blocked", listed(frontier.blocked_ids))
+        end
+
+        def listed(ids)
+          ids.empty? ? Frontier::NONE : ids.join(", ")
+        end
+
+        def frontier
+          @frontier ||= Frontier.new(scope)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "subcommand_list"
+
+# `plastic project` - the list of `plastic project ...` 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 Project < SubcommandList
+        USAGE_LINE = "plastic project SUBCOMMAND [options]"
+        PREFIX = "project"
+        NEXT = "plastic project list"
+        BECAUSE = "the stores it lists are what every other subcommand names a slug from"
+      end
+    end
+  end
+end