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

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)
+        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)
+        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,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,84 @@
+# 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 "every entry on #{roadmap} is delivered" if id.nil?
+
+        "#{id} is first on the frontier of #{roadmap}"
+      end
+
+      def next_step
+        return "plastic status" unless id
+
+        plan = @scope.intent_dir(id)
+        plan ? "read #{File.join(plan, "plan.md")}" : "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/legacy.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "English"
+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
+      DEFAULT_RUNNER = lambda do |path, arguments|
+        system(RbConfig.ruby, path, *arguments)
+        exit_code($CHILD_STATUS)
+      end
+
+      def self.exit_code(status)
+        return Command::OK if status.success?
+
+        status.exitstatus || Command::FAILED
+      end
+
+      def initialize(env:, runner: nil)
+        @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)
+        status = @runner.call(script_path(script), arguments)
+        raise Command::Refusal, "#{script} needs the owner" if status == Command::REFUSED
+
+        status
+      end
+    end
+  end
+end

package/scripts/lib/cli/output.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+
+# 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
+
+      def initialize(out:, err:)
+        @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 raw(text)
+        @out.puts text
+        self
+      end
+
+      def usage(message, banner)
+        @err.puts "plastic: #{message}"
+        @err.puts banner
+        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."
+        self
+      end
+
+      def failed(message)
+        @err.puts "plastic: #{message}"
+        self
+      end
+
+      private
+
+      def print_json
+        @out.puts JSON.pretty_generate("result" => @rows.to_h, "next" => @next_step,
+          "because" => @because)
+      end
+
+      def print_text
+        printed = print_rows
+        return unless @next_step
+
+        @out.puts if printed
+        @out.puts "next: #{@next_step}"
+        @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

package/scripts/lib/cli/scope.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "../store_layout"
+require_relative "../index_entry"
+require_relative "../store_discovery"
+
+# Plastic::CLI::Scope (intent 363) - which store a command works on. Six skills
+# used to restate this rule in prose; it is stated here once.
+#
+# A named project wins. With no name, the project whose repository holds the
+# working directory wins, longest path first, so a repository nested inside
+# another resolves to the inner one. With neither, the global store answers.
+#
+# Every path comes from the injected environment and home directory, so a test
+# points at a temporary store and never at the real ~/.plastic.
+module Plastic
+  class CLI
+    class Scope
+      UnknownProject = Class.new(StandardError)
+
+      GLOBAL = "global"
+
+      def initialize(env:, home:, slug: nil, directory: Dir.pwd)
+        @env = env
+        @home = home
+        @requested = slug
+        @directory = directory
+      end
+
+      def plastic_home
+        @plastic_home ||= @env["PLASTIC_HOME"] || File.join(@home, ".plastic")
+      end
+
+      def stores
+        @stores ||= StoreDiscovery.discover(plastic_home)[:stores]
+      end
+
+      def slug
+        @slug ||= resolve_slug
+      end
+
+      def root
+        @root ||= found&.fetch(:root) || plastic_home
+      end
+
+      def store
+        File.join(root, "store")
+      end
+
+      def index_path
+        File.join(root, "INDEX.md")
+      end
+
+      def roadmaps_dir
+        File.join(root, "roadmaps")
+      end
+
+      def active_entries
+        return [] unless File.exist?(index_path)
+
+        section(File.read(index_path)).filter_map do |line|
+          match = IndexEntry.match(line)
+          match && [match[1], match[2]]
+        end
+      end
+
+      def active_ids
+        active_entries.map(&:first)
+      end
+
+      def intent_dir(id)
+        Dir.glob(File.join(store, "#{id}--*")).min
+      end
+
+      def directory_project
+        @directory_project = project_for_directory unless defined?(@directory_project)
+        @directory_project
+      end
+
+      def known_slugs
+        stores.map { |store| store[:slug] }.sort
+      end
+
+      private
+
+      def found
+        stores.find { |store| store[:slug] == slug }
+      end
+
+      def resolve_slug
+        return requested_slug if @requested
+
+        directory_project || GLOBAL
+      end
+
+      def requested_slug
+        return @requested if known_slugs.include?(@requested)
+
+        raise UnknownProject,
+          "no project named #{@requested.inspect}; this machine has #{known_slugs.join(", ")}"
+      end
+
+      def project_for_directory
+        repositories
+          .select { |_slug, path| inside?(path) }
+          .max_by { |_slug, path| path.length }
+          &.first
+      end
+
+      def inside?(path)
+        @directory == path || @directory.start_with?("#{path}#{File::SEPARATOR}")
+      end
+
+      def repositories
+        StoreProvisioning.load_projects(plastic_home).filter_map do |slug, info|
+          path = info.is_a?(Hash) ? info["path"].to_s : ""
+          [slug, path] unless path.empty?
+        end
+      end
+
+      def section(text)
+        body = text.match(/^##\s+Active\s*$(.*?)(?=^##\s|\z)/m)
+        body ? body[1].lines.map(&:strip) : []
+      end
+    end
+  end
+end