@zalom/plastic 2.0.0-alpha.8 → 2.0.1

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+
+# `plastic status` - every store this machine holds, the intents each one has
+# open, and the one store worth continuing.
+#
+# The store to continue is chosen by a fixed rule, so two runs never disagree:
+# the store whose repository holds the working directory, else the store with
+# the most active intents, and on a tie the first in discovery order, which puts
+# the global store ahead of the projects and the projects in name order.
+module Plastic
+  class CLI
+    module Commands
+      class Status < Command
+        USAGE_LINE = "plastic status [--json]"
+
+        def call
+          counted.each { |slug, ids| @output.row(slug, summary(ids)) }
+          command, because = decision
+          @output.next_step(command, because: because)
+        end
+
+        private
+
+        def counted
+          @counted ||= scope.stores.to_h do |store|
+            slug = store[:slug]
+            [slug, Scope.new(env: @env, home: @home, slug: slug, directory: @directory).active_ids]
+          end
+        end
+
+        def summary(ids)
+          return "0 active" if ids.empty?
+
+          "#{ids.length} active  #{ids.join(", ")}"
+        end
+
+        def decision
+          here = scope.directory_project
+          return [continue_command(here), "the working directory is inside #{here}"] if busy?(here)
+
+          chosen = busiest
+          return ["plastic help", "no store has active work"] unless chosen
+
+          [continue_command(chosen), "#{chosen} holds the most active work, #{intents(chosen)}"]
+        end
+
+        def busy?(slug)
+          slug && !counted.fetch(slug, []).empty?
+        end
+
+        def busiest
+          counted.reject { |_slug, ids| ids.empty? }.max_by { |_slug, ids| ids.length }&.first
+        end
+
+        def intents(slug)
+          count = counted.fetch(slug).length
+          (count == 1) ? "1 intent" : "#{count} intents"
+        end
+
+        def continue_command(slug)
+          (slug == Scope::GLOBAL) ? "plastic continue" : "plastic continue --project #{slug}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../table"
+
+# Plastic::CLI::Commands::SubcommandList (intent 372, family 3) - the shared
+# base every bare group command (`plastic intent`, `plastic project`,
+# `plastic roadmap`) runs on: list the table rows under its prefix, or a
+# usage error naming that same list for a word that matches none of them.
+module Plastic
+  class CLI
+    module Commands
+      class SubcommandList < Command
+        def call
+          unless arguments.empty?
+            raise Usage, "no subcommand named #{arguments.first.inspect}. Try: #{subcommand_names.join(", ")}"
+          end
+
+          @output.row("usage", self.class::USAGE_LINE)
+          subcommands.each { |name, (_file, _const, summary)| @output.row(name, summary) }
+          @output.next_step(self.class::NEXT, because: self.class::BECAUSE)
+        end
+
+        private
+
+        def subcommands
+          TABLE.select { |name, _| name.start_with?("#{self.class::PREFIX} ") }.sort.to_h
+        end
+
+        def subcommand_names
+          subcommands.keys
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../../store_sync"
+require_relative "../../work_graph"
+
+module Plastic
+  class CLI
+    module Commands
+      class Sync < Command
+        USAGE_LINE = "plastic sync [--dry-run] [--json]"
+
+        def call
+          home = scope.plastic_home
+          plan = File.exist?(SearchIndex.path(home)) ? StoreSync.plan(home) : [["build", SearchIndex::NAME]]
+          refuse(home, plan.filter_map { |action, path| path if action == "conflict" })
+          plan.group_by(&:first).each { |action, pairs| @output.row(action, pairs.map(&:last)) }
+          @output.row("result", "nothing to do") if plan.empty?
+          apply(home, plan) unless options[:dry_run]
+          @output.next_step("plastic search TERMS", because: "a changed file is read into its row, a changed row is written out, and both changed is yours to settle")
+        rescue Sqlite::Error => e
+          raise Failure, e.message
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--dry-run") { options[:dry_run] = true }
+        end
+
+        def refuse(home, conflicts)
+          return if conflicts.empty?
+
+          diffs = conflicts.map { |path| "#{path}\n#{StoreSync.diff(home, path)}" }
+          raise Refusal, "the file and the row both changed; nothing was written\n#{diffs.join("\n")}"
+        end
+
+        def apply(home, plan)
+          (plan == [["build", SearchIndex::NAME]]) ? SearchIndex.build(home) : StoreSync.apply(home, plan)
+          WorkGraph.build(home)
+          ReferenceArchive.build(home)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "installer_verb"
+
+# `plastic uninstall` - removes Plastic from this machine's agents and leaves
+# the store alone. The work is still scripts/uninstall.rb, run through Legacy.
+module Plastic
+  class CLI
+    module Commands
+      class Uninstall < InstallerVerb
+        USAGE_LINE = "plastic uninstall [--claude] [--codex] [--hermes] [--all]"
+        FLAGS = %w[--claude --codex --hermes --all].freeze
+
+        SCRIPT = "uninstall.rb"
+        AFTER = "none"
+        BECAUSE = "Plastic is removed from this machine's agents"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "installer_verb"
+
+# `plastic update` - moves this machine to the next version on its channel. The
+# work is still scripts/update.rb, run through Legacy.
+module Plastic
+  class CLI
+    module Commands
+      class Update < InstallerVerb
+        USAGE_LINE = "plastic update [--claude] [--codex] [--hermes] [--all] [--latest] [--beta] [--alpha] [--yes] [--reinstall] [--full-doctor]"
+        FLAGS = %w[--claude --codex --hermes --all --latest --beta --alpha --yes --reinstall --full-doctor].freeze
+
+        SCRIPT = "update.rb"
+        AFTER = "plastic version"
+        BECAUSE = "the update is done, and restarting the session picks up the new conventions"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../command"
+
+# `plastic version` - the version of the package this command came from, and the
+# file it was read from. The VERSION file wins, because an installed copy
+# carries one; the package manifest answers in a checkout, which has none.
+module Plastic
+  class CLI
+    module Commands
+      class Version < Command
+        USAGE_LINE = "plastic version [--json]"
+
+        SOURCES = ["VERSION", "package.json"].freeze
+
+        def call
+          path, number = found
+          raise Failure, "no VERSION file and no package.json under #{package_root}" unless number
+
+          @output.row("version", number)
+          @output.row("source", path)
+          @output.next_step("plastic status", because: "the command line works, so read the work next")
+        end
+
+        def found
+          SOURCES.each do |name|
+            path = File.join(package_root, name)
+            number = read(path)
+            return [path, number] if number
+          end
+          [nil, nil]
+        end
+
+        private
+
+        def read(path)
+          return nil unless File.file?(path)
+          return File.read(path).strip unless path.end_with?(".json")
+
+          number = JSON.parse(File.read(path))["version"]
+          number&.to_s&.strip
+        rescue JSON::ParserError
+          nil
+        end
+
+        def package_root
+          @package_root ||= @env["PLASTIC_PACKAGE_ROOT"] || File.expand_path("../../../..", __dir__)
+        end
+      end
+    end
+  end
+end

package/scripts/lib/cli/frontier.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../roadmap_queue"
+
+# Plastic::CLI::Frontier (intent 363) - the one reader of "what comes next" in a
+# scope. `plastic next` prints it as a line and `plastic continue` prints it
+# inside a project block, so the rule that picks the work is stated once rather
+# than twice.
+#
+# It reads RoadmapQueue's queue mode: the liveliest roadmap, its frontier batch,
+# the entries that can be dispatched, the entries in flight and the blocked
+# ones. With no roadmap at all it answers the "none" state rather than raising,
+# and a roadmap with no grouping heading raises through to the command, which
+# fails loudly instead of parsing it as zero entries.
+module Plastic
+  class CLI
+    class Frontier
+      NONE = "none"
+
+      def initialize(scope)
+        @scope = scope
+      end
+
+      def state
+        payload["state"]
+      end
+
+      def roadmap
+        payload["roadmap"]
+      end
+
+      def heading
+        payload["frontier_wave"]
+      end
+
+      def dispatchable_ids
+        ids(payload["dispatchable_queue"])
+      end
+
+      def in_flight_ids
+        ids(payload["in_flight"])
+      end
+
+      def blocked_ids
+        ids(payload["blocked"])
+      end
+
+      def id
+        (dispatchable_ids + in_flight_ids).first
+      end
+
+      def summary
+        return NONE unless id
+
+        "#{id}  in #{heading}"
+      end
+
+      def because
+        return "#{@scope.slug} has no roadmap" if state == NONE
+        return "#{roadmap} has blocked work: #{blocked_ids.join(", ")}" if id.nil? && !blocked_ids.empty?
+        return "#{roadmap} has an invalid graph: #{heading}" if state == "error"
+        return "every entry on #{roadmap} is delivered" if id.nil?
+
+        "#{id} is first on the frontier of #{roadmap}"
+      end
+
+      def next_step
+        return "none" unless id
+
+        plan = @scope.intent_dir(id)
+        plan ? "plastic intent show #{id}" : "plastic status"
+      end
+
+      private
+
+      def payload
+        @payload ||= RoadmapQueue.new(roadmaps_dir: @scope.roadmaps_dir,
+          index_path: @scope.index_path).queue
+      end
+
+      def ids(entries)
+        Array(entries).map { |entry| entry["id"] }
+      end
+    end
+  end
+end

package/scripts/lib/cli/intent_progress.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../intent_screen"
+
+module Plastic
+  class CLI
+    class IntentProgress
+      def initialize(scope, id)
+        @scope = scope
+        @id = id
+        @dir = scope.intent_dir(id)
+      end
+
+      def decision
+        status, = IntentScreen.index_fields(@scope.root, @id)
+        return ["none", "the intent is #{status.downcase}"] if %w[Completed Abandoned].include?(status)
+        return ["plastic intent step #{@id}", "the graph is ready for its next step"] if File.file?(File.join(@dir, "graph.md"))
+        return ["plastic intent spec #{@id}", "write spec.md with the accepted scope"] unless prepared?("spec.md")
+        return ["plastic intent spec #{@id}", "write plan.md and checklist.md before execution"] unless prepared?("plan.md") && IntentScreen.items_present?(@dir)
+
+        items = IntentScreen.checklist_items(@dir)
+        return ["plastic intent spec #{@id}", "the checklist needs concrete work items"] if items.empty?
+        return ["plastic intent verify #{@id}", "all checklist items are complete"] if items.all? { |item| item[:done] }
+
+        ["plastic intent step #{@id}", "the checklist has unfinished work"]
+      end
+
+      private
+
+      def prepared?(name)
+        path = File.join(@dir, name)
+        File.file?(path) && !File.read(path).strip.empty? && !File.read(path).include?(IntentScreen::PLACEHOLDER_SENTINEL)
+      end
+    end
+  end
+end

package/scripts/lib/cli/legacy.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "English"
+require "open3"
+require "rbconfig"
+require_relative "command"
+
+# Plastic::CLI::Legacy (intent 363) - runs a script that has not moved into a
+# module yet as a child process, and passes its output straight through. It is
+# scaffolding: when the last family is migrated it is deleted, and the commands
+# call their modules in the same process instead.
+#
+# A child that exits 3 refused, and the refusal travels as a Refusal so the
+# agent is told to stop and ask rather than to retry with a flag. Every other
+# status is handed back to the caller unchanged.
+module Plastic
+  class CLI
+    class Legacy
+      # A runner answers with the child's exit status. Asked to capture, it
+      # answers with the child's stdout and that status, for a command that
+      # renders the script's JSON as a screen. stderr is never captured, so a
+      # warning the script writes there still reaches the terminal.
+      DEFAULT_RUNNER = lambda do |path, arguments, capture: false|
+        unless capture
+          system(RbConfig.ruby, path, *arguments)
+          next exit_code($CHILD_STATUS)
+        end
+
+        out, process = Open3.capture2(RbConfig.ruby, path, *arguments)
+        [out, exit_code(process)]
+      end
+
+      NON_OWNER_EXIT_THREE = %w[verify-intent runner].freeze
+
+      def self.exit_code(status)
+        return Command::OK if status.success?
+
+        status.exitstatus || Command::FAILED
+      end
+
+      def initialize(env:, runner: nil, output: nil, json: false)
+        @output = output
+        @json = json
+        @env = env
+        @runner = runner || DEFAULT_RUNNER
+      end
+
+      def package_root
+        @package_root ||= @env["PLASTIC_PACKAGE_ROOT"] || File.expand_path("../../..", __dir__)
+      end
+
+      def script_path(script)
+        File.join(package_root, "scripts", script)
+      end
+
+      def run(script, *arguments)
+        if @json
+          text, status = @runner.call(script_path(script), arguments, capture: true)
+          @output.raw(text) unless text.empty?
+        else
+          status = @runner.call(script_path(script), arguments)
+        end
+        raise Command::Refusal, "#{script} needs the owner" if owner_refusal?(script, status)
+
+        status
+      end
+
+      def owner_refusal?(script, status)
+        status == Command::REFUSED && !NON_OWNER_EXIT_THREE.include?(script)
+      end
+
+      def capture(script, *arguments)
+        out, status = @runner.call(script_path(script), arguments, capture: true)
+        raise Command::Refusal, "#{script} needs the owner" if owner_refusal?(script, status)
+
+        [out, status]
+      end
+    end
+  end
+end

package/scripts/lib/cli/output.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+require "shellwords"
+
+# Plastic::CLI::Output (intent 363) - one place where a command's answer is
+# printed. A result is rows of label and value; every command ends with a
+# `next:` line and the `because:` line that gives the rule behind it, which is
+# where the step order the skills used to carry now lives. `--json` prints the
+# same three things with stable keys.
+#
+# Results go to the output stream and diagnostics to the error stream, so a
+# caller can pipe one without the other. Nothing here colours its output.
+module Plastic
+  class CLI
+    class Output
+      LABEL_GAP = 2
+
+      attr_writer :project
+
+      def initialize(out:, err:, json: false)
+        @json = json
+        @raw = []
+        @out = out
+        @err = err
+        @rows = []
+        @next_step = nil
+        @because = nil
+        @flushed = false
+      end
+
+      def row(label, value)
+        @rows << [label, value]
+        self
+      end
+
+      def next_step(command, because:)
+        @next_step = command
+        @because = because
+        self
+      end
+
+      def flush(json: false)
+        return self if @flushed
+
+        @flushed = true
+        json ? print_json : print_text
+        self
+      end
+
+      def document(value)
+        @out.puts JSON.pretty_generate(value)
+        @flushed = true
+        self
+      end
+
+      def raw(text)
+        @json ? @raw << text : @out.puts(text)
+        self
+      end
+
+      def usage(message, banner)
+        @err.puts "plastic: #{message}"
+        @err.puts banner
+        error_document(message, "usage")
+        self
+      end
+
+      def refused(message)
+        @err.puts "plastic: refused, #{message}"
+        @err.puts "This step belongs to the owner. Stop and ask; do not retry with a flag."
+        error_document(message, "refused")
+        self
+      end
+
+      def failed(message)
+        @err.puts "plastic: #{message}"
+        error_document(message, "failed")
+        self
+      end
+
+      private
+
+      def error_document(message, kind)
+        return unless @json
+
+        row("error", {"kind" => kind, "message" => message})
+        next_step("none", because: message)
+        flush(json: true)
+      end
+
+      def result
+        data = @rows.to_h
+        data["output"] = @raw unless @raw.empty?
+        data
+      end
+
+      def scoped_next
+        return @next_step unless @project && @next_step&.match?(/\Aplastic (?:intent|auto|roadmap|continue|next|search)\b/)
+        return @next_step if @next_step.include?("--project")
+
+        "#{@next_step} --project #{Shellwords.escape(@project)}"
+      end
+
+      def print_json
+        @out.puts JSON.pretty_generate("result" => result, "next" => scoped_next,
+          "because" => @because)
+      end
+
+      def print_text
+        printed = print_rows
+        return unless @next_step
+
+        @out.puts if printed
+        @out.puts "next: #{scoped_next}"
+        @out.puts "because: #{@because}"
+      end
+
+      def print_rows
+        width = label_width
+        printed = false
+        @rows.each do |label, value|
+          Array(value).each_with_index do |item, index|
+            @out.puts "#{(index.zero? ? label : "").ljust(width)}#{item}"
+            printed = true
+          end
+        end
+        printed
+      end
+
+      def label_width
+        widths = @rows.reject { |_label, value| Array(value).empty? }.map { |label, _value| label.length }
+        widths.empty? ? 0 : widths.max + LABEL_GAP
+      end
+    end
+  end
+end