@zalom/plastic 2.0.0-alpha.9 → 2.0.2

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+
+# `plastic session commit` - one commit for a verified checklist item, on the
+# directory this command was invoked from (`session-commit --cwd DIR
+# --summary SUMMARY`, run through Legacy; fail-open by contract, so a Failure
+# here means the script's own usage error, not a git failure).
+module Plastic
+  class CLI
+    module Commands
+      class SessionCommit < Command
+        USAGE_LINE = 'plastic session commit "SUMMARY" [--json]'
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          raise Usage, "SUMMARY is required" if summary.to_s.empty?
+
+          status = legacy.run("session-commit", "--cwd", @directory, "--summary", summary)
+          raise Failure, "session-commit exited #{status}" unless status.zero?
+
+          @output.next_step("plastic session handoff", because: "the line above says whether a commit landed; a handoff keeps the day ledger current")
+        end
+
+        private
+
+        def summary
+          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/session_handoff.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+
+# `plastic session handoff` - writes this session's hand-off into the day
+# ledger (`write-handoff --trigger tick`, run through Legacy).
+module Plastic
+  class CLI
+    module Commands
+      class SessionHandoff < Command
+        USAGE_LINE = "plastic session handoff [--json]"
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          status = legacy.run("write-handoff", "--trigger", "tick")
+          raise Failure, "write-handoff exited #{status}" unless status.zero?
+
+          @output.next_step("plastic session summary", because: "the summary is what a fresh handoff feeds")
+        end
+
+        private
+
+        def legacy
+          @legacy ||= Legacy.new(env: @env, runner: @runner, output: @output, json: options[:json])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+
+# `plastic session summary` - the block SessionStart injects at boot: open
+# items, the last five done, live auto intents, other active sessions
+# (`day-summary`, run through Legacy).
+module Plastic
+  class CLI
+    module Commands
+      class SessionSummary < Command
+        USAGE_LINE = "plastic session summary [--json]"
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          status = legacy.run("day-summary")
+          raise Failure, "day-summary exited #{status}" unless status.zero?
+
+          @output.next_step("plastic status", because: "the board is where the summary's open items are worked from")
+        end
+
+        private
+
+        def legacy
+          @legacy ||= Legacy.new(env: @env, runner: @runner, output: @output, json: options[:json])
+        end
+      end
+    end
+  end
+end

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,55 @@
+# 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]"
+
+        # Rebuilt on every sync; a missing one is named in the plan, so the
+        # preview and the sync report the same work (acceptance N7).
+        DERIVED = [WorkGraph, ReferenceArchive].freeze
+
+        def call
+          home = scope.plastic_home
+          plan = File.exist?(SearchIndex.path(home)) ? StoreSync.plan(home) : [["build", SearchIndex::NAME]]
+          plan += DERIVED.reject { |database| File.exist?(database.path(home)) }.map { |database| ["build", database::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)
+          if plan.include?(["build", SearchIndex::NAME])
+            SearchIndex.build(home)
+          else
+            StoreSync.apply(home, plan.reject { |step| step.first == "build" })
+          end
+          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