@zalom/plastic 2.0.0-alpha.9 → 2.0.2

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+
+# `plastic project links` - projects every store's `## Links` sections from
+# frontmatter (`project-links`, run through Legacy).
+module Plastic
+  class CLI
+    module Commands
+      class ProjectLinks < Command
+        USAGE_LINE = "plastic project links [--dry-run] [--json]"
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          status = legacy.run("project-links", "--plastic-home", scope.plastic_home, *dry_run_flag)
+          raise Failure, "project-links exited #{status}" unless status.zero?
+
+          if options[:dry_run]
+            @output.next_step("none", because: "the preview wrote no files")
+          else
+            @output.next_step("plastic status", because: "the Links sections just rebuilt across every store")
+          end
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--dry-run") { @options[:dry_run] = true }
+        end
+
+        def dry_run_flag
+          options[:dry_run] ? ["--dry-run"] : []
+        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/project_list.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+
+# `plastic project list` - every store this machine holds, global and
+# project, straight from Scope#stores, in this process.
+module Plastic
+  class CLI
+    module Commands
+      class ProjectList < Command
+        USAGE_LINE = "plastic project list [--json]"
+
+        def call
+          scope.stores.each { |store| @output.row(store[:slug], store[:root]) }
+          @output.next_step("plastic status", because: "status shows what is active in each store this just listed")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+require_relative "../command"
+require_relative "../legacy"
+require_relative "../../store_provisioning"
+
+# `plastic project new` - registers a project in projects.yml, then provisions
+# and validates its store (`provision-project-store`, `validate-project`, run
+# through Legacy). The project directory must already exist; this command
+# never makes one. A slug is lowercase letters, digits and hyphens, starting
+# with a letter or digit, and never `global`. A slug or a path already
+# registered is a Failure.
+module Plastic
+  class CLI
+    module Commands
+      class ProjectNew < Command
+        USAGE_LINE = "plastic project new SLUG --path PATH [--parent ID] [--json]"
+
+        SLUG = /\A[a-z0-9][a-z0-9-]*\z/
+        RESERVED = "global"
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          raise Usage, "SLUG is required" if slug.to_s.empty?
+          raise Usage, "--path is required" if options[:path].to_s.empty?
+          unless slug.match?(SLUG) && slug != RESERVED
+            raise Usage, "SLUG must be lowercase letters, digits and hyphens, start with a letter or digit, and not be global"
+          end
+          raise Failure, "#{options[:path]} does not exist" unless Dir.exist?(options[:path])
+          raise Failure, "#{options[:path]} has no AGENTS.md; write one first" unless File.file?(File.join(options[:path], "AGENTS.md"))
+          raise Failure, "#{slug} is already registered" if StoreProvisioning.registered?(slug, scope.plastic_home)
+          owner = slug_for_path
+          raise Failure, "#{options[:path]} is already registered as #{owner}" if owner
+
+          register
+          run("provision-project-store", slug, "--home", scope.plastic_home)
+          run("validate-project", slug, "--home", scope.plastic_home)
+          @output.next_step("plastic project links", because: "the new store's Links section needs projecting before anything cites it")
+        end
+
+        private
+
+        def slug
+          arguments.first
+        end
+
+        def switches(parser)
+          parser.on("--path PATH") { |v| @options[:path] = v }
+          parser.on("--parent ID") { |v| @options[:parent] = v }
+        end
+
+        def slug_for_path
+          path = File.realpath(options[:path])
+          projects.find do |_slug, info|
+            registered = info.is_a?(Hash) && info["path"].is_a?(String) && info["path"]
+            registered && Dir.exist?(registered) && File.realpath(registered) == path
+          end&.first
+        end
+
+        def projects
+          data = File.exist?(projects_yml) ? YAML.safe_load_file(projects_yml) : nil
+          (data.is_a?(Hash) && data["projects"].is_a?(Hash)) ? data["projects"] : {}
+        end
+
+        def projects_yml
+          File.join(scope.plastic_home, "projects.yml")
+        end
+
+        def register
+          data = File.exist?(projects_yml) ? (YAML.safe_load_file(projects_yml) || {}) : {}
+          data["projects"] ||= {}
+          entry = {"path" => File.expand_path(options[:path]), "registered" => Date.today.to_s, "status" => "active"}
+          entry["parent"] = options[:parent] if options[:parent]
+          data["projects"][slug] = entry
+          File.write(projects_yml, YAML.dump(data))
+        end
+
+        def run(script, *args)
+          status = legacy.run(script, *args)
+          raise Failure, "#{script} exited #{status}" unless status.zero?
+        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/query.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../../search_index"
+
+module Plastic
+  class CLI
+    module Commands
+      class Query < Command
+        USAGE_LINE = "plastic query SQL [--json]"
+
+        def call
+          raise Usage, "SQL is missing" if arguments.empty?
+          raise Failure, "no index at #{database}; run plastic index" unless File.file?(database)
+
+          rows = Sqlite.call(database, arguments.join(" "), readonly: true)
+          rows.each_with_index { |row, index| @output.row((index + 1).to_s, row.map { |key, value| "#{key}=#{value}" }.join("  ")) }
+          @output.next_step("none", because: "the rows are the whole answer; the database is opened read-only")
+        rescue Sqlite::Error => e
+          raise Failure, e.message
+        end
+
+        private
+
+        def database
+          SearchIndex.path(scope.plastic_home)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+
+module Plastic
+  class CLI
+    module Commands
+      class Render < Command
+        USAGE_LINE = "plastic render FILE"
+        STYLE = File.expand_path("../../../../templates/render.css", __dir__)
+        # A leading YAML block is metadata; RDoc would render it as body text.
+        FRONTMATTER = /\A---\r?\n.*?^---[ \t]*(\r?\n|\z)/m
+
+        def call
+          file = arguments.first or raise Usage, "FILE is the markdown file to render"
+          raise Failure, "no file at #{file}" unless File.file?(file)
+
+          require "rubygems"
+          require "rdoc"
+          body = RDoc::Markdown.parse(File.read(file, encoding: "UTF-8").sub(FRONTMATTER, "")).accept(html_formatter)
+          @output.raw("<!doctype html>\n<meta charset=\"utf-8\">\n<title>#{File.basename(file)}</title>\n" \
+            "<style>\n#{File.read(STYLE)}</style>\n#{body}")
+        end
+
+        private
+
+        def html_formatter(formatter_class = RDoc::Markup::ToHtml)
+          initializer = formatter_class.instance_method(:initialize)
+          options = (initializer.parameters.any? { |_, name| name == :options }) ? [RDoc::Options.new] : []
+          formatter_class.new(*options)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "subcommand_list"
+
+# `plastic roadmap` - the list of `plastic roadmap ...` 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 Roadmap < SubcommandList
+        USAGE_LINE = "plastic roadmap SUBCOMMAND [options]"
+        PREFIX = "roadmap"
+        NEXT = "plastic roadmap next"
+        BECAUSE = "next names the roadmap most worth continuing, with no slug to guess"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+
+# `plastic roadmap check` - the roadmap graph's batches, ready set and any
+# cycle or dangling id (`roadmap-graph check`, run through Legacy).
+#
+# A roadmap with no `## Graph` section has nothing to check, and the script's
+# own exit code says only that something failed. That case is named here, with
+# the command that repairs it, so the reader never has to know which script ran.
+module Plastic
+  class CLI
+    module Commands
+      class RoadmapCheck < Command
+        USAGE_LINE = "plastic roadmap check SLUG [--json]"
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          raise Usage, "SLUG is required" if slug.to_s.empty?
+          raise Failure, "no roadmap #{slug} in #{File.basename(scope.roadmaps_dir)}" unless File.file?(path)
+          raise Failure, "#{slug} has no ## Graph section; plastic roadmap migrate #{slug} writes one from its batches" unless graph?
+
+          status = legacy.run("roadmap-graph", "check", path)
+          raise Failure, "roadmap-graph exited #{status}" unless status.zero?
+
+          @output.next_step("plastic roadmap show #{slug}", because: "the graph just checked out clean")
+        end
+
+        private
+
+        def graph?
+          File.foreach(path).any? { |line| line.start_with?("## Graph") }
+        end
+
+        def slug
+          arguments.first
+        end
+
+        def path
+          File.join(scope.roadmaps_dir, "#{slug}.md")
+        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/roadmap_log.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+
+# `plastic roadmap log` - appends a savepoint line to a roadmap's ledger
+# (`roadmap-savepoint append`, run through Legacy).
+module Plastic
+  class CLI
+    module Commands
+      class RoadmapLog < Command
+        USAGE_LINE = 'plastic roadmap log SLUG EVENT "TEXT" [--json]'
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          raise Usage, "SLUG is required" if slug.to_s.empty?
+          raise Usage, "EVENT is required" if event.to_s.empty?
+          raise Usage, "TEXT is required" if text.to_s.empty?
+
+          status = legacy.run("roadmap-savepoint", "append", "--roadmap", path, "--event", event, "--detail", text)
+          raise Failure, "roadmap-savepoint exited #{status}" unless status.zero?
+
+          @output.next_step("plastic roadmap show #{slug}", because: "the log line just landed on the state screen")
+        end
+
+        private
+
+        def slug
+          arguments[0]
+        end
+
+        def event
+          arguments[1]
+        end
+
+        def text
+          arguments[2]
+        end
+
+        def path
+          File.join(scope.roadmaps_dir, "#{slug}.md")
+        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/roadmap_migrate.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+
+# `plastic roadmap migrate` - writes a roadmap's `## Graph` section from the
+# batch headings it already carries (`roadmap-graph migrate`, run through
+# Legacy). This is the repair `plastic roadmap check` names when a roadmap has
+# no graph, so the CLI can perform every repair it asks for.
+module Plastic
+  class CLI
+    module Commands
+      class RoadmapMigrate < Command
+        USAGE_LINE = "plastic roadmap migrate SLUG [--dry-run] [--json]"
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          raise Usage, "SLUG is required" if slug.to_s.empty?
+          raise Failure, "no roadmap #{slug} in #{File.basename(scope.roadmaps_dir)}" unless File.file?(path)
+
+          arguments_for_script = ["migrate", path]
+          arguments_for_script << "--dry-run" if options[:dry_run]
+          status = legacy.run("roadmap-graph", *arguments_for_script)
+          raise Failure, "roadmap-graph exited #{status}" unless status.zero?
+
+          @output.next_step("plastic roadmap check #{slug}", because: "a written graph is what check reads")
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--dry-run") { @options[:dry_run] = true }
+        end
+
+        def slug
+          arguments.first
+        end
+
+        def path
+          File.join(scope.roadmaps_dir, "#{slug}.md")
+        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/roadmap_next.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../command"
+require_relative "../legacy"
+
+# `plastic roadmap next` - the roadmap most worth continuing right now
+# (`roadmap-next --which`, run through Legacy). The script speaks JSON, so this
+# command renders it as a screen and leaves the document to `--json`, the way
+# every other command reads.
+module Plastic
+  class CLI
+    module Commands
+      class RoadmapNext < Command
+        USAGE_LINE = "plastic roadmap next [--json]"
+        AFTER = "plastic roadmap show SLUG"
+        BECAUSE = "the winner it just named is the slug that command wants"
+        TIED = "the roadmaps tie; the first is shown, and any of them may be picked"
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          report = parse(*legacy.capture("roadmap-next", "--roadmaps-dir", scope.roadmaps_dir, "--which"))
+          screen(report)
+          @output.next_step(after(report), because: (report["state"] == "tie") ? TIED : BECAUSE)
+        end
+
+        private
+
+        def parse(text, status)
+          raise Failure, "roadmap-next exited #{status}" unless status.zero?
+
+          JSON.parse(text)
+        rescue JSON::ParserError
+          raise Failure, "roadmap-next did not print a report"
+        end
+
+        def after(report)
+          slug = (report["roadmap"] || tied(report).first).to_s
+          slug.empty? ? AFTER : AFTER.sub("SLUG", slug)
+        end
+
+        # roadmap-next --which reports a tie as state "tie" with "tie" false and
+        # each candidate as an object; older reports carried plain names.
+        def tied(report)
+          Array(report["tie_candidates"]).map { |candidate| candidate.is_a?(Hash) ? candidate["roadmap"] : candidate }
+        end
+
+        def screen(report)
+          @output.row("state", report["state"])
+          @output.row("roadmap", report["roadmap"] || "none")
+          @output.row("wave", report["frontier_wave"]) unless report["frontier_wave"].to_s.empty?
+          @output.row("next", queue(report["dispatchable_queue"]))
+          @output.row("delivering", entries(report["in_flight"]))
+          @output.row("blocked", entries(report["blocked"]))
+          @output.row("tie", tied(report).join(", ")) if report["tie"] || report["state"] == "tie"
+        end
+
+        def queue(list)
+          rows = entries(list)
+          rows.empty? ? "none" : rows
+        end
+
+        def entries(list)
+          Array(list).map { |entry| [entry["id"], entry["status"], entry["wave"]].compact.join("  ") }
+        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/roadmap_show.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../legacy"
+require_relative "../../roadmap_graph"
+
+# `plastic roadmap show` - a roadmap's state screen (`report-screen roadmap
+# FILE state`, run through Legacy). SLUG is required: `plastic roadmap next`
+# is the command that picks one when the caller has none in mind.
+module Plastic
+  class CLI
+    module Commands
+      class RoadmapShow < Command
+        USAGE_LINE = "plastic roadmap show SLUG [--json]"
+
+        def initialize(argv, runner: nil, **streams)
+          super(argv, **streams)
+          @runner = runner
+        end
+
+        def call
+          raise Usage, "SLUG is required" if slug.to_s.empty?
+
+          status = legacy.run("report-screen", "roadmap", path, "state")
+          raise Failure, "report-screen exited #{status}" unless status.zero?
+
+          problems = graph_problems
+          problems.each { |problem| @output.row("warning", problem) }
+          if problems.empty?
+            @output.next_step("plastic roadmap log #{slug} EVENT \"TEXT\"", because: "a savepoint is how this state screen keeps moving")
+          else
+            @output.next_step("plastic roadmap check #{slug}", because: "the graph has problems the state screen cannot show")
+          end
+        end
+
+        private
+
+        # A cycle or a graph id no batch lists (acceptance N8). The state screen
+        # cannot show either, so they are named under it.
+        def graph_problems
+          return [] unless File.file?(path)
+
+          result = RoadmapGraph.analyze(path)
+          problems = []
+          problems << "cyclic graph: #{result[:cycle].join(" > ")}" if result[:cycle]
+          dangling = Array(result[:dangling])
+          problems << "graph names #{dangling.join(", ")}, no batch entry" unless dangling.empty?
+          problems
+        end
+
+        def slug
+          arguments.first
+        end
+
+        def path
+          File.join(scope.roadmaps_dir, "#{slug}.md")
+        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/rollback.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "installer_verb"
+
+# `plastic rollback` - steps back to a version this machine has already run. The
+# work is still scripts/rollback.rb, run through Legacy.
+module Plastic
+  class CLI
+    module Commands
+      class Rollback < InstallerVerb
+        USAGE_LINE = "plastic rollback [--version VERSION] [--downgrade] [--upgrade] [--reinstall]"
+        FLAGS = %w[--version --downgrade --upgrade --reinstall].freeze
+
+        SCRIPT = "rollback.rb"
+        AFTER = "plastic version"
+        BECAUSE = "the version says which build is installed"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../command"
+require_relative "../../search_index"
+require_relative "../../rlm/query"
+
+module Plastic
+  class CLI
+    module Commands
+      class Search < Command
+        USAGE_LINE = "plastic search TERMS [--ask] [--project SLUG] [--limit N] [--json]"
+        DEFAULT_LIMIT = 10
+
+        def call
+          raise Usage, "TERMS is missing" if arguments.empty?
+          raise Failure, "no index at #{database}; run plastic index" unless File.file?(database)
+
+          rows = options[:ask] ? RLM::Query.new(RLM::Probe.new(corpus, limit: limit)).call(arguments.join(" ")) : found(arguments, limit)
+          rows.each { |row| @output.row(row["path"], row["excerpt"].gsub(/\s+/, " ").strip) }
+          @output.row("result", "no match") if rows.empty?
+          @output.next_step("none", because: "the search is complete")
+        rescue Sqlite::Error => e
+          raise Failure, e.message
+        end
+
+        private
+
+        def switches(parser)
+          parser.on("--ask") { @options[:ask] = true }
+          parser.on("--project SLUG") { |slug| @options[:project] = slug }
+          parser.on("--limit N", Integer) { |limit| @options[:limit] = limit }
+        end
+
+        def limit
+          options[:limit] || DEFAULT_LIMIT
+        end
+
+        def found(terms, count)
+          SearchIndex.search(scope.plastic_home, terms, limit: count, prefix: prefix)
+        end
+
+        def corpus
+          RLM::Corpus.new(method(:found))
+        end
+
+        def database
+          SearchIndex.path(scope.plastic_home)
+        end
+
+        def prefix
+          return "" unless options[:project]
+
+          home = scope.plastic_home
+          root = (scope.slug == Scope::GLOBAL) ? StoreLayout.global_store(home) : StoreLayout.project_root(home, scope.slug)
+          "#{root.delete_prefix("#{home}/")}/"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "subcommand_list"
+
+# `plastic session` - the list of `plastic session ...` subcommands, straight
+# out of the table.
+module Plastic
+  class CLI
+    module Commands
+      class Session < SubcommandList
+        USAGE_LINE = "plastic session SUBCOMMAND [options]"
+        PREFIX = "session"
+        NEXT = 'plastic session commit "SUMMARY"'
+        BECAUSE = "a commit is the smallest unit every other session subcommand builds on"
+      end
+    end
+  end
+end