@zalom/plastic 2.0.0-alpha.2 → 2.0.0-alpha.20

package/scripts/report-screen

@@ -0,0 +1,281 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# report-screen - the pre-delivery plan (intent 331b), the four delivery
+# reports: mid-delivery state, post-delivery delivered, and delay (intent
+# 317), plus session, the whole of one session's delivered work followed by
+# the roster (intent 330). Each fills from the record via
+# scripts/lib/report_screen.rb; no number here is written by eye.
+#
+# Usage:
+#   report-screen plan <intent_dir> [--ansi]
+#   report-screen state <intent_dir> [--changed "<text>"] [--ansi]
+#   report-screen state --all <store_root> [--changed "<text>"] [--ansi]
+#   report-screen delivered <intent_dir> [--ansi] [--repo <dir>]
+#   report-screen delay <intent_dir> [--ansi]
+#   report-screen session <tier_root> [--session <id>] [--since <iso>]
+#                                     [--ledger-root <dir>] [--ansi]
+#   report-screen roadmap <roadmap.md> plan|state|delivered [--ansi] [--store-root <dir>]
+#   report-screen archive <store_root> [--ansi]
+#
+# --ansi delegates to ScreenPaint (intent 317a, D1), the parser/re-layouter
+# in the shared TUI core. Selection is by capability, never by harness:
+# NO_COLOR forces plain, a non-TTY stdout stays plain unless
+# PLASTIC_FORCE_COLOR=1 (the test seam), and an unparseable screen falls
+# open to the plain text untouched.
+#
+# Exit codes:
+#   0 - the screen is on stdout
+#   2 - usage error, or the path/store is not what the verb expects (one line
+#       on stderr, stdout empty)
+
+require "yaml"
+require "shellwords"
+require_relative "lib/report_screen"
+require_relative "lib/intent_screen"
+require_relative "lib/screen_paint"
+require_relative "lib/session_ledger"
+
+# Intent 331a (D6/R8): every caller-added screen kind file registers itself
+# on load (ScreenPaint.register), so this glob is the ONLY wiring a new kind
+# needs - no edit here, no edit to screen_paint.rb. Sorted for a
+# deterministic load order; tolerates the directory being absent or empty
+# (Dir.glob answers [] either way), which is this repo's own state today.
+Dir.glob(File.join(__dir__, "lib", "screens", "*.rb")).sort.each { |f| require_relative f }
+
+def usage_abort(message)
+  warn "report-screen: #{message}"
+  exit 2
+end
+
+# The one place allowed to shell out (D2/D20): resolves the tag that CONTAINS
+# the intent's merge commit, in the project's own repository, so the version
+# on the delivered screen is the release that merge shipped in. The
+# repository comes from --repo, else from projects.yml beside the store (the
+# installed layout, <home>/projects/<slug>/store/<id>), else the repository
+# this script lives in (the in-repo layout, `include_self: true`) - unless
+# `include_self: false` (the branch reader, D23), in which case a global
+# intent's repo never falls back to the script's own repository, since that
+# is not the intent's repository at all. No merge sha, no repository, or no
+# containing tag all answer nil, and the screen says "not recorded" rather
+# than guessing from HEAD (D14). The pure module never reads git.
+def resolve_repo(intent_dir, explicit_repo, script_dir, include_self: true)
+  candidates = []
+  candidates << File.expand_path(explicit_repo) if explicit_repo
+  if (m = intent_dir.match(%r{\A(.*)/projects/([^/]+)/store/[^/]+\z}))
+    home, slug = m[1], m[2]
+    projects_yml = File.join(home, "projects.yml")
+    if File.exist?(projects_yml)
+      data = begin
+        YAML.safe_load(File.read(projects_yml))
+      rescue StandardError
+        nil
+      end
+      entry = data.is_a?(Hash) && data["projects"].is_a?(Hash) ? data["projects"][slug] : nil
+      path = entry.is_a?(Hash) ? entry["path"].to_s : ""
+      candidates << File.expand_path(path) unless path.empty?
+    end
+  end
+  candidates << File.expand_path("..", script_dir) if include_self
+  candidates.find { |c| File.exist?(File.join(c, ".git")) }
+end
+
+def git_tag_reader(explicit_repo:, script_dir:)
+  lambda do |intent_dir|
+    sha = ReportScreen.merge_sha(intent_dir)
+    return nil unless sha
+    repo = resolve_repo(intent_dir, explicit_repo, script_dir)
+    return nil unless repo
+    tags = `git -C #{repo.shellescape} tag --contains #{sha.shellescape} 2>/dev/null`
+    versions = tags.lines.map(&:strip).reject(&:empty?).filter_map do |tag|
+      v = tag.sub(/\Av/, "")
+      Gem::Version.correct?(v) ? [Gem::Version.new(v), tag] : nil
+    end
+    versions.min_by(&:first)&.last
+  end
+end
+
+# D9/D23: the injected branch reader. flow_base (a pure YAML read, never
+# git) wins when the intent's project names a flow base; otherwise the
+# repository's remote HEAD, else whichever of main/master exists. Resolves
+# the repo with `include_self: false` (D23): a global-store intent must
+# never fall back to the script's OWN repository (~/.plastic itself, on
+# "main" in the installed layout) and print a confident, wrong branch.
+def git_branch_reader(explicit_repo:, script_dir:)
+  lambda do |intent_dir|
+    flow = ReportScreen.flow_base(intent_dir)
+    next flow if flow && !flow.to_s.empty?
+
+    repo = resolve_repo(intent_dir, explicit_repo, script_dir, include_self: false)
+    next nil unless repo
+
+    branch = `git -C #{repo.shellescape} symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null`.strip
+    branch = branch.sub(%r{\Aorigin/}, "")
+    next branch unless branch.empty?
+
+    %w[main master].find do |b|
+      system("git", "-C", repo, "rev-parse", "--verify", "--quiet", b, out: File::NULL, err: File::NULL)
+    end
+  end
+end
+
+args = ARGV.dup
+verb = args.shift
+changed = nil
+ansi = false
+template_path = nil
+repo_flag = nil
+session_flag = nil
+since_flag = nil
+ledger_root_flag = nil
+store_root_flag = nil
+positional = []
+
+while (arg = args.shift)
+  case arg
+  when "--changed"
+    usage_abort("--changed needs a value") if args.empty?
+    changed = args.shift
+  when "--ansi"
+    ansi = true
+  when "--all"
+    positional << "--all"
+  when "--repo"
+    repo_flag = args.shift or usage_abort("--repo needs a path")
+  when "--template"
+    template_path = args.shift or usage_abort("--template needs a path")
+  when "--session"
+    session_flag = args.shift or usage_abort("--session needs a value")
+  when "--since"
+    since_flag = args.shift or usage_abort("--since needs a value")
+  when "--ledger-root"
+    ledger_root_flag = args.shift or usage_abort("--ledger-root needs a path")
+  when "--store-root"
+    store_root_flag = args.shift or usage_abort("--store-root needs a path")
+  else
+    usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--") && arg != "--all"
+    positional << arg
+  end
+end
+
+usage_abort("usage: report-screen plan|state|delivered|delay|session <intent_dir> [--changed \"<text>\"] [--ansi]") unless verb
+
+all_mode = positional.delete("--all") ? true : false
+target = positional.first
+
+ansi_enabled = ansi && ENV["NO_COLOR"].to_s.empty? &&
+               ($stdout.tty? || ENV["PLASTIC_FORCE_COLOR"] == "1")
+
+def paint(text, ansi_enabled, _renderer_path = nil)
+  return text unless ansi_enabled
+  ScreenPaint.paint(text, color: true) || text
+end
+
+case verb
+when "plan"
+  usage_abort("usage: report-screen plan <intent_dir> [--ansi]") unless target
+  intent_dir = File.expand_path(target)
+  usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+  store_root = File.expand_path("../..", intent_dir)
+  template_path ||= File.expand_path("../templates/report-plan.md", __dir__)
+  usage_abort("template not found at #{template_path}") unless File.exist?(template_path)
+  out = ReportScreen.render_plan(intent_dir: intent_dir, store_root: store_root,
+                                  template: File.read(template_path))
+  $stdout.write paint(out, ansi_enabled)
+when "state"
+  if all_mode
+    usage_abort("usage: report-screen state --all <store_root>") unless target
+    store_root = File.expand_path(target)
+    usage_abort("#{store_root} is not a store (no INDEX.md)") unless File.exist?(File.join(store_root, "INDEX.md"))
+    out = ReportScreen.render_roster(store_root, changed: changed)
+    $stdout.write paint(out, ansi_enabled)
+  else
+    usage_abort("usage: report-screen state <intent_dir> [--changed \"<text>\"]") unless target
+    intent_dir = File.expand_path(target)
+    usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+    store_root = File.expand_path("../..", intent_dir)
+    template_path ||= File.expand_path("../templates/report-state.md", __dir__)
+    usage_abort("template not found at #{template_path}") unless File.exist?(template_path)
+    out = ReportScreen.render_state(intent_dir: intent_dir, store_root: store_root, changed: changed,
+                                     template: File.read(template_path))
+    $stdout.write paint(out, ansi_enabled)
+  end
+when "delivered"
+  usage_abort("usage: report-screen delivered <intent_dir>") unless target
+  intent_dir = File.expand_path(target)
+  usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+  out = ReportScreen.render_delivered(intent_dir: intent_dir,
+                                      tag_reader: git_tag_reader(explicit_repo: repo_flag, script_dir: __dir__),
+                                      branch_reader: git_branch_reader(explicit_repo: repo_flag, script_dir: __dir__))
+  $stdout.write paint(out, ansi_enabled)
+when "delay"
+  usage_abort("usage: report-screen delay <intent_dir>") unless target
+  intent_dir = File.expand_path(target)
+  usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+  out = ReportScreen.render_delay(intent_dir: intent_dir)
+  $stdout.write paint(out, ansi_enabled)
+when "session"
+  usage_abort("usage: report-screen session <tier_root> [--session <id>] [--since <iso>] [--ledger-root <dir>] [--ansi]") unless target
+  store_root = File.expand_path(target)
+  usage_abort("#{store_root} is not a store (no INDEX.md)") unless File.exist?(File.join(store_root, "INDEX.md"))
+
+  now = Time.now
+  session_id = session_flag || ENV[SessionLedger::SESSION_ID_ENV_KEY]
+  ledger_root = ledger_root_flag ? File.expand_path(ledger_root_flag) : ReportScreen.default_ledger_root(store_root)
+
+  if since_flag
+    begin
+      Time.parse(since_flag)
+    rescue ArgumentError
+      usage_abort("--since needs an ISO timestamp, got #{since_flag.inspect}")
+    end
+  end
+
+  dirs, skipped = ReportScreen.session_delivered_dirs(ledger_root: ledger_root, tier_root: store_root,
+                                                       session: session_id, since: since_flag, now: now)
+  # D17: the widened window is announced whether the id was missing or simply
+  # matched nothing. A resumed background job carries a session id that is not
+  # the one on the ledger lines, and that case must not answer silently. An
+  # explicit --since is the caller naming the window, so it needs no note.
+  note =
+    if since_flag
+      nil
+    elsif session_id.nil? || session_id.to_s.strip.empty?
+      ReportScreen.window_note(ReportScreen.fallback_day(ledger_root, SessionLedger.day_id(now)),
+                               "no session id given")
+    elsif !ReportScreen.session_tagged?(ledger_root: ledger_root, session: session_id, now: now)
+      ReportScreen.window_note(ReportScreen.fallback_day(ledger_root, SessionLedger.day_id(now)),
+                               "this session has no line in the day ledger")
+    end
+
+  out = ReportScreen.render_session(
+    dirs: dirs, skipped: skipped, store_root: store_root,
+    tag_reader: git_tag_reader(explicit_repo: nil, script_dir: __dir__),
+    branch_reader: git_branch_reader(explicit_repo: nil, script_dir: __dir__),
+    note: note, now: now, painter: ->(text) { paint(text, ansi_enabled) }
+  )
+  $stdout.write out
+when "roadmap"
+  usage_abort("usage: report-screen roadmap <roadmap.md> plan|state|delivered [--ansi] [--store-root <dir>]") if positional.empty?
+  roadmap_path = File.expand_path(positional[0])
+  usage_abort("#{roadmap_path} does not exist") unless File.exist?(roadmap_path)
+  sub_verb = positional[1]
+  usage_abort("usage: report-screen roadmap <roadmap.md> plan|state|delivered") unless sub_verb
+  unless %w[plan state delivered].include?(sub_verb)
+    usage_abort("unknown sub-verb #{sub_verb.inspect} (use plan|state|delivered)")
+  end
+  roadmap_store_root = store_root_flag ? File.expand_path(store_root_flag) : nil
+  out = ReportScreen.render_roadmap(path: roadmap_path, verb: sub_verb, store_root: roadmap_store_root)
+  $stdout.write paint(out, ansi_enabled)
+when "archive"
+  usage_abort("usage: report-screen archive <store_root>") unless target
+  store_root = File.expand_path(target)
+  usage_abort("#{store_root} is not a store (no INDEX.md)") unless File.exist?(File.join(store_root, "INDEX.md"))
+  out = ReportScreen.render_archive(store_root)
+  $stdout.write paint(out, ansi_enabled)
+else
+  usage_abort("unknown verb #{verb.inspect} (use plan|state|delivered|delay|session|roadmap|archive)")
+end
+
+exit 0

package/scripts/roadmap-graph

@@ -0,0 +1,119 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# roadmap-graph - the CLI over the roadmap graph model (intent 337, G4):
+# `check`, `render`, `migrate`, every verb honouring --dry-run.
+#
+# Usage:
+#   roadmap-graph check <roadmap.md> [--dry-run]
+#   roadmap-graph render <roadmap.md> [--dry-run]
+#   roadmap-graph migrate <roadmap.md> [--dry-run]
+#
+# Exit codes:
+#   0 - printed / rendered / migrated cleanly (or a migrate skip: the
+#       roadmap already carries a graph)
+#   1 - a real finding: a cyclic graph, a dangling id, or a render/migrate
+#       refusal (no ## Graph, no grouping heading)
+#   2 - usage: no argument, an unknown verb, or a missing/non-file path
+
+require_relative "lib/roadmap_graph"
+require_relative "lib/roadmap_render"
+require_relative "lib/roadmap_migration"
+
+module RoadmapGraphCli
+  module_function
+
+  VERBS = %w[check render migrate].freeze
+
+  def usage
+    warn "Usage: roadmap-graph <#{VERBS.join('|')}> <roadmap.md> [--dry-run]"
+  end
+
+  def main(argv)
+    args = argv.dup
+    dry_run = !!args.delete("--dry-run")
+
+    verb = args.shift
+    unless verb && VERBS.include?(verb)
+      warn "roadmap-graph: unknown verb #{verb.inspect} (use #{VERBS.join(', ')})" if verb
+      usage
+      return 2
+    end
+
+    path = args.shift
+    unless path && File.file?(path)
+      warn "roadmap-graph: #{path.inspect} is not a file"
+      return 2
+    end
+
+    case verb
+    when "check" then check(path)
+    when "render" then render(path, dry_run)
+    when "migrate" then migrate(path, dry_run)
+    end
+  end
+
+  def check(path)
+    result = RoadmapGraph.analyze(path)
+    unless result[:has_graph]
+      warn "roadmap-graph check: #{result[:reason]}"
+      return 1
+    end
+    if result[:cycle]
+      warn "roadmap-graph check: cyclic graph: #{result[:cycle].join(' > ')}"
+      return 1
+    end
+    if result[:reason]
+      warn "roadmap-graph check: #{result[:reason]}"
+      return 1
+    end
+
+    puts "Batches: #{result[:batches].map { |b| b.join(', ') }.join(' | ')}"
+    puts "Ready: #{result[:ready].join(', ')}"
+    puts "Dead ends: #{result[:dead_ends].join(', ')}" unless result[:dead_ends].empty?
+
+    unless result[:dangling].empty?
+      warn "roadmap-graph check: graph names #{result[:dangling].map(&:inspect).join(', ')}, no batch entry"
+      return 1
+    end
+
+    0
+  end
+
+  def render(path, dry_run)
+    result = RoadmapRender.write(path, dry_run: dry_run)
+    unless result[:ok]
+      warn "roadmap-graph render: #{result[:error]}"
+      return 1
+    end
+
+    if dry_run
+      puts result[:content]
+    else
+      puts "roadmap-graph render: wrote #{path}"
+    end
+    0
+  end
+
+  def migrate(path, dry_run)
+    result = RoadmapMigration.write(path, dry_run: dry_run)
+    unless result[:ok]
+      if result[:skipped]
+        puts "roadmap-graph migrate: #{result[:reason]}"
+        return 0
+      end
+      warn "roadmap-graph migrate: #{result[:reason]}"
+      return 1
+    end
+
+    if dry_run
+      puts result[:content]
+    else
+      puts "roadmap-graph migrate: wrote #{path}"
+    end
+    0
+  end
+end
+
+exit(RoadmapGraphCli.main(ARGV)) if $PROGRAM_NAME == __FILE__

package/scripts/roadmap-savepoint

@@ -18,6 +18,7 @@
 # rebuilds an empty ledger.
 
 require_relative "lib/roadmap_savepoint"
+require_relative "lib/guarded_append"
 
 def opt(args, name)
   (i = args.index(name)) && args[i + 1]
@@ -47,6 +48,12 @@ when "append"
   rescue ArgumentError => e
     warn "append: #{e.message}"
     exit 2
+  rescue GuardedAppend::Unavailable => e
+    # Intent 335 (spec D14): the write guard could not be taken; nothing was written. Exit 4
+    # rather than let a backtrace reach the six skill recipes that drive this CLI - it rescues
+    # ArgumentError alone today and would otherwise print one straight to the terminal.
+    warn "append: #{e.message}"
+    exit 4
   end
 
 when "rebuild"