@zalom/plastic 2.0.0-alpha.8 → 2.0.1

package/scripts/lib/hook_replay.rb

@@ -0,0 +1,229 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "timeout"
+
+# HookReplay (intent 331a, T1; promoted to a production lib in 331e) - streams
+# text through a MessageDisplay launcher the way Claude Code streams an
+# assistant reply, chunk by chunk, and returns every chunk's raw stdout.
+#
+# 331a's test/support/hook_replay.rb held this as test-only code; 331e's
+# doctor `display_hook_paints` check (scripts/doctor.rb) needs the exact same
+# mechanics to replay the INSTALLED launcher for real, so the logic lives
+# here and test/support/hook_replay.rb now delegates to it (a require, not a
+# duplicate). Never require this from scripts/lib/doctor_core.rb: that file
+# is the SessionStart boot path (test/doctor_core_split_test.rb T2 pins its
+# exact require set), and the paint check that needs this lib runs only from
+# the full scripts/doctor.rb.
+module HookReplay
+  module_function
+
+  # Streams `text` through `hook_path` in fixed-size chunks. `session_id`/
+  # `message_id` default to fixed values since nothing about a replay depends
+  # on the ambient session at all.
+  #
+  # `env` (intent 331e): extra child-process environment, merged over the
+  # PLASTIC_TMP entry every call already sets (a caller's own key wins). A
+  # `nil` value unsets that variable in the child (Process.spawn's own
+  # convention) is how a caller forces NO_COLOR off regardless of the ambient
+  # environment. Default `{}` keeps every existing caller's behavior
+  # unchanged: this is an extension, not a fork.
+  #
+  # `timeout` (intent 331e): when given, bounds EACH chunk's spawn to that
+  # many seconds. A bare `Timeout.timeout` around `Open3.capture3` does not
+  # reliably bound a genuinely hanging child: capture3's own wait still
+  # blocks on Process.waitpid for the child regardless of the raised
+  # Timeout::Error (the same gotcha scripts/hook-record works around), so a
+  # timeout here spawns directly and kills the child on expiry instead.
+  # Default `nil` keeps every existing caller on the original unbounded
+  # Open3.capture3 path.
+  def replay(hook_path:, tmp_root:, text:, chunk: 40, session_id: "s-replay", message_id: "replay",
+              env: {}, timeout: nil)
+    chunks = text.scan(/.{1,#{chunk}}/m)
+    chunks = [""] if chunks.empty?
+    full_env = { "PLASTIC_TMP" => tmp_root }.merge(env)
+
+    chunks.each_with_index.map do |delta, i|
+      payload = {
+        "session_id" => session_id, "message_id" => message_id, "index" => i,
+        "final" => i == chunks.length - 1, "delta" => delta, "cwd" => tmp_root,
+        "hook_event_name" => "MessageDisplay",
+      }
+      out, err, exitstatus = run_one(hook_path, payload, full_env, tmp_root, timeout)
+      { index: i, exitstatus: exitstatus, stdout: out, stderr: err, final: payload["final"] }
+    end
+  end
+
+  # replay_concurrent (intent 331a1) - streams `text` through `hook_path` the
+  # way `replay` does, but fires every chunk in its OWN thread, staggered by
+  # `gap_ms` (plus up to half a gap of jitter when `jitter` is true) rather
+  # than run sequentially. This is what reproduces the decision-race defect
+  # 331a1 fixes: Claude Code fires the per-chunk hook processes CONCURRENTLY
+  # in production, and `replay`'s strictly-sequential default never puts two
+  # chunks in flight at once, so it could never have reproduced the race in
+  # the first place.
+  #
+  # `gap_ms: 5` plus jitter is the default on purpose, not "fire everything
+  # at once": firing all 335 chunks of the live session capture with no
+  # stagger at all takes about 8 s of wall clock on this 8-core machine,
+  # because EACH chunk boots its own real Ruby process and the completions
+  # cluster at the tail once every core is saturated - a load real streaming
+  # never produces (a real stream delivers a chunk every few tens of
+  # milliseconds, one at a time). One Ruby process per streamed chunk is the
+  # actual throughput ceiling here, not something this method works around.
+  #
+  # `replay`'s own signature and sequential default are UNCHANGED by this
+  # method's existence (`scripts/doctor.rb:2571` calls `replay` directly and
+  # must keep working exactly as it does today) - this is a sibling method
+  # in the same module, never a replacement.
+  #
+  # Returns the SAME result shape `replay` returns (one Hash per chunk, keys
+  # index/exitstatus/stdout/stderr/final), ordered by index regardless of
+  # the order the threads actually finish in.
+  def replay_concurrent(hook_path:, tmp_root:, text:, chunk: 40, session_id: "s-replay",
+                         message_id: "replay", env: {}, gap_ms: 5, jitter: true, lead_until_engaged: false)
+    chunks = text.scan(/.{1,#{chunk}}/m)
+    chunks = [""] if chunks.empty?
+    full_env = { "PLASTIC_TMP" => tmp_root }.merge(env)
+    gap = gap_ms / 1000.0
+
+    payloads = chunks.each_with_index.map do |delta, i|
+      {
+        "session_id" => session_id, "message_id" => message_id, "index" => i,
+        "final" => i == chunks.length - 1, "delta" => delta, "cwd" => tmp_root,
+        "hook_event_name" => "MessageDisplay",
+      }
+    end
+    results = Array.new(chunks.length)
+
+    # `lead_until_engaged` runs chunks one at a time until one engages, so
+    # the decision marker is on disk before the rest fire concurrently. A
+    # caller proving "no late passthrough once the decision is in place"
+    # then tests exactly that, instead of whether chunk 0's own process
+    # booted inside a later chunk's poll budget on a loaded machine.
+    lead = 0
+    if lead_until_engaged
+      payloads.each_with_index do |payload, i|
+        out, err, exitstatus = run_one(hook_path, payload, full_env, tmp_root, nil)
+        results[i] = { index: i, exitstatus: exitstatus, stdout: out, stderr: err, final: payload["final"] }
+        lead = i + 1
+        break unless out.to_s.empty?
+      end
+    end
+
+    threads = payloads.each_with_index.drop(lead).map do |payload, i|
+      Thread.new do
+        begin
+          delay = (i - lead) * gap
+          delay += (rand * gap / 2.0) if jitter
+          sleep(delay)
+          out, err, exitstatus = run_one(hook_path, payload, full_env, tmp_root, nil)
+          results[i] = { index: i, exitstatus: exitstatus, stdout: out, stderr: err, final: payload["final"] }
+        rescue StandardError => e
+          # A raise inside a thread body is invisible until join, and an
+          # unrescued one aborts `threads.each(&:join)` at the first dead
+          # thread: every later thread is then never joined and outlives the
+          # call, racing whatever the caller does next (typically removing
+          # the very tmp root those threads are still writing under). Report
+          # the failure as this chunk's own result instead, so the array is
+          # always complete, every thread is always joined, and a replay
+          # tells its caller what went wrong rather than throwing at it.
+          results[i] = { index: i, exitstatus: nil, stdout: "", stderr: e.message,
+                         final: payload["final"] }
+        end
+      end
+    end
+    threads.each { |thread| thread.join }
+    results
+  end
+
+  # Indices of the chunks that reached the terminal as raw Markdown: a
+  # non-final chunk that emitted nothing at all, after the engaging chunk.
+  # A chunk "passed through" when its stdout is empty; a chunk was
+  # "blanked" (correctly buffered, not shown raw) when its stdout contains
+  # `"displayContent":""`. Only chunks with an index greater than the
+  # engaging chunk's own index count - the engaging chunk is the first one
+  # (at or after `start_index`) whose stdout is non-empty, and chunks
+  # before it already reached the terminal live, verbatim, through the
+  # ordinary passthrough path (they were never candidates for buffering at
+  # all, so an empty stdout from one of them is not this defect).
+  def passthrough_indices(outs, start_index: 0)
+    engaging = outs.find { |o| o[:index] >= start_index && !o[:stdout].to_s.empty? }
+    return [] unless engaging
+
+    outs.select { |o| o[:index] > engaging[:index] && o[:final] != true && o[:stdout].to_s.empty? }
+        .map { |o| o[:index] }
+  end
+
+  def run_one(hook_path, payload, full_env, tmp_root, timeout)
+    return capture(hook_path, payload, full_env) unless timeout
+
+    run_bounded(hook_path, payload, full_env, tmp_root, timeout)
+  end
+
+  def capture(hook_path, payload, full_env)
+    out, err, status = Open3.capture3(full_env, hook_path, stdin_data: JSON.generate(payload))
+    [out, err, status.exitstatus]
+  end
+
+  # Spawn directly (never Open3.capture3) so a timeout can actually kill the
+  # child, with stdin/stdout/stderr routed through scratch files under the
+  # caller's own tmp_root, and never pipes, so a stalled or oversized write can
+  # never deadlock the read side, and never anywhere outside tmp_root, so a
+  # bounded replay carries the same "writes only under the injected tmp
+  # root" guarantee as the unbounded path.
+  def run_bounded(hook_path, payload, full_env, tmp_root, timeout)
+    token = "#{Process.pid}-#{(Time.now.to_f * 1_000_000).to_i}-#{rand(1_000_000)}"
+    in_path = File.join(tmp_root, ".hook-replay-in-#{token}")
+    out_path = File.join(tmp_root, ".hook-replay-out-#{token}")
+    err_path = File.join(tmp_root, ".hook-replay-err-#{token}")
+    File.write(in_path, JSON.generate(payload))
+
+    pid = Process.spawn(full_env, hook_path, in: in_path, out: out_path, err: err_path)
+    exitstatus =
+      begin
+        Timeout.timeout(timeout) { Process.wait(pid) }
+        $?.exitstatus
+      rescue Timeout::Error
+        kill_and_reap(pid)
+        nil # nil exitstatus is the caller's signal that this chunk timed out
+      end
+
+    out = File.exist?(out_path) ? File.read(out_path) : ""
+    err = File.exist?(err_path) ? File.read(err_path) : ""
+    [out, err, exitstatus]
+  ensure
+    [in_path, out_path, err_path].each { |p| File.delete(p) if p && File.exist?(p) }
+  end
+
+  def kill_and_reap(pid)
+    Process.kill("KILL", pid)
+  rescue StandardError
+    nil
+  ensure
+    begin
+      Process.wait(pid)
+    rescue StandardError
+      nil
+    end
+  end
+
+  # The final chunk's parsed displayContent, or nil when it emitted nothing
+  # (no envelope at all: the message never engaged).
+  def final_display_content(outs)
+    final = outs.last
+    return nil if final[:stdout].to_s.empty?
+
+    JSON.parse(final[:stdout]).dig("hookSpecificOutput", "displayContent")
+  rescue JSON::ParserError
+    nil
+  end
+
+  # True when any chunk's spawn hit its timeout (run_bounded's nil-exitstatus
+  # signal). A replay made with no `timeout:` never reports true.
+  def timed_out?(outs)
+    outs.any? { |o| o[:exitstatus].nil? }
+  end
+end

package/scripts/lib/index_entry.rb

@@ -0,0 +1,62 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# IndexEntry - the shared INDEX.md entry matcher and Active check (intent 188,
+# D12/D13; moved off the retired shared-helpers module by intent 344, D2).
+#
+# ONE definition site for the "- [ID <sep> Title](link)" shape both `active?`
+# (below) and `scripts/end-intent`'s own INDEX-move parser depend on, so the
+# two regexes can never drift apart. Accepts a real em dash (U+2014) OR a
+# plain hyphen as the id/title separator on READ; every WRITE still emits the
+# real em dash (D10). The separator is built from the codepoint, not a
+# literal byte, so this file stays em-dash free.
+require_relative "atomic_write"
+
+module IndexEntry
+  module_function
+
+  EM_DASH = "\u2014".freeze
+  ENTRY_RE = /\A- \[(\S+)\s+(?:#{Regexp.escape(EM_DASH)}|-)\s+(.*?)\]\(([^)]+)\)/.freeze
+
+  # Match `line` (already chomped) against the shared INDEX entry shape.
+  # Returns a MatchData (captures: 1 = id, 2 = title, 3 = link) or nil.
+  def match(line)
+    line.to_s.match(ENTRY_RE)
+  end
+
+  def add_active(index_path, dir_name:, title:)
+    id = dir_name.split("--").first
+    line = "- [#{id} #{EM_DASH} #{title}](store/#{dir_name}/#{dir_name}.md)\n"
+    text = File.read(index_path, encoding: "UTF-8")
+    AtomicWrite.write(index_path, text.sub(/^## Active\n/) { |heading| heading + line })
+  end
+
+  # True iff the intent is Active in its store's INDEX.md, which lives at the
+  # PARENT of the store/ dir. Non-raising: any failure (missing or unreadable
+  # INDEX, bad arg) returns false. `index_active_ids` is a pure-data test
+  # seam: when an Array of id strings is supplied, membership is checked
+  # against it directly with no file read.
+  def active?(intent_id, store:, index_active_ids: nil)
+    target = intent_id.to_s
+    return index_active_ids.include?(target) if index_active_ids.is_a?(Array)
+
+    index = File.join(File.dirname(store.to_s), "INDEX.md")
+    return false unless File.exist?(index)
+
+    in_active = false
+    File.foreach(index) do |line|
+      stripped = line.chomp
+      if stripped == "## Active"
+        in_active = true
+        next
+      end
+      next unless in_active
+      break if stripped.start_with?("## ") # next section ends the Active block
+      m = match(stripped)
+      return true if m && m[1] == target
+    end
+    false
+  rescue StandardError
+    false
+  end
+end

package/scripts/lib/index_projection.rb

@@ -0,0 +1,201 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "doctor_exclusions"
+require_relative "graph_file"
+require_relative "atomic_write"
+
+# IndexProjection (intent 337, n5): computes every intent's status from its
+# own savepoint.md ledger, reads the status INDEX.md currently claims, and
+# reports the drift between them. The ledger wins WHERE THE LEDGER SPEAKS
+# (row 5.1/5.2): a REAL terminal line (Done delivered/abandoned, or a
+# classifiable Done detail) beats a stale INDEX section. An intent whose
+# ledger is silent (no terminal line) or absent (no savepoint.md at all)
+# keeps the status INDEX already carries (row 5.13, merged at the
+# 2026-09-10 plan review): 63 of 451 intents in the plastic store have no
+# savepoint.md and 59 more never reach a Done line, and a literal reading
+# would demote all of them. This module computes and compares only; it
+# writes nothing (row 5.11) and reads no clock or environment variable.
+module IndexProjection
+  module_function
+
+  INDEX_SECTIONS = %w[Active Future Completed Abandoned].freeze
+  TERMINAL_STATUSES = %w[Completed Abandoned].freeze
+  EXCLUSION_RULES = %w[savepoint_operational backfilled_complete].freeze
+
+  # `store_path` holds the intent directories (a project's own `store/`, or
+  # the global `~/.plastic/store`). `index_path` defaults to a sibling
+  # `INDEX.md` inside `store_path` (matching every fixture in this test
+  # file), but the real Plastic layout keeps INDEX.md one level ABOVE
+  # `store/` - callers there (doctor.rb, the CLI) pass it explicitly.
+  def analyze(store_path, index_path: nil)
+    index_path ||= File.join(store_path, "INDEX.md")
+    index_map = read_index(index_path)
+    dir_ids = store_intent_ids(store_path)
+
+    excluded = excluded_ids(index_path)
+
+    drift = index_map.filter_map do |id, index_status|
+      next if index_status == "Future" # 5.5: Future has no ledger counterpart
+      next if excluded.include?(id) # 5.12
+
+      ledger_status = ledger_status_for(store_path, id)
+      next unless TERMINAL_STATUSES.include?(ledger_status) # 5.3/5.13
+      next if ledger_status == index_status
+
+      { id: id, index_status: index_status, ledger_status: ledger_status }
+    end
+
+    index_only = (index_map.keys - dir_ids).reject { |id| excluded.include?(id) }
+                                            .map { |id| { id: id, index_status: index_map[id] } }
+    directory_only = (dir_ids - index_map.keys).reject { |id| excluded.include?(id) }
+                                                .map { |id| { id: id } }
+
+    { ok: true, drift: drift, index_only: index_only, directory_only: directory_only, errors: [] }
+  end
+
+  # Render the four status sections (## Active, ## Future, ## Completed,
+  # ## Abandoned) from the projection and write through AtomicWrite. Only
+  # entries `analyze` actually reported as `drift` ever move - an entry
+  # whose ledger is silent or absent never appears in `drift` (row 5.13),
+  # so --write can never demote it (row 6.14). Every other line, including
+  # ## Clusters and ## Relocated (or any other section), is untouched
+  # (row 6.13): only the four named headings are ever replaced.
+  def write(store_path, index_path:, renamer: File.method(:rename))
+    return { ok: false, written: false, error: "no INDEX.md at #{index_path}" } unless File.exist?(index_path)
+
+    analysis = analyze(store_path, index_path: index_path)
+    text = read_utf8(index_path)
+
+    original_lines = {}
+    INDEX_SECTIONS.each do |heading|
+      section_body(text, heading).each_line do |line|
+        next unless line.strip.start_with?("- [")
+
+        m = line.strip.match(/\A-\s*\[(\S+)\s/)
+        original_lines[m[1]] = line if m
+      end
+    end
+
+    moves = analysis[:drift].each_with_object({}) { |r, h| h[r[:id]] = r[:ledger_status] }
+
+    new_bodies = INDEX_SECTIONS.each_with_object({}) do |heading, h|
+      kept = section_body(text, heading).each_line.reject do |line|
+        stripped = line.strip
+        next false unless stripped.start_with?("- [")
+
+        m = stripped.match(/\A-\s*\[(\S+)\s/)
+        m && moves.key?(m[1])
+      end
+      arriving = moves.select { |_id, target| target == heading }.keys
+      h[heading] = (kept + arriving.filter_map { |id| original_lines[id] }).join
+    end
+
+    content = text
+    INDEX_SECTIONS.each do |heading|
+      content = GraphFile.replace_or_append_section(content, "## #{heading}", new_bodies[heading].rstrip + "\n")
+    end
+
+    AtomicWrite.write(index_path, content, renamer: renamer)
+    { ok: true, written: true, moved: analysis[:drift], error: nil }
+  end
+
+  # --- INDEX -------------------------------------------------------------------
+
+  def read_index(index_path)
+    map = {}
+    return map unless File.exist?(index_path)
+
+    text = read_utf8(index_path)
+    INDEX_SECTIONS.each do |heading|
+      section_body(text, heading).each_line do |line|
+        stripped = line.strip
+        next unless stripped.start_with?("- [")
+
+        m = stripped.match(/\A-\s*\[(\S+)\s/)
+        map[m[1]] = heading if m
+      end
+    end
+    map
+  end
+
+  def section_body(text, heading)
+    m = text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)
+    m ? m[1] : ""
+  end
+
+  # --- store directories ---------------------------------------------------------
+
+  def store_intent_ids(store_path)
+    return [] unless Dir.exist?(store_path)
+
+    Dir.entries(store_path).select { |e| e.include?("--") && File.directory?(File.join(store_path, e)) }
+       .map { |e| e.split("--", 2).first }
+  end
+
+  def intent_dir_for(store_path, id)
+    Dir.glob(File.join(store_path, "#{id}--*")).find { |p| File.directory?(p) }
+  end
+
+  # --- the ledger (savepoint.md) --------------------------------------------------
+
+  # "Completed", "Abandoned", "Active" (no terminal line yet), "unknown" (no
+  # directory or no savepoint.md), or "indeterminate" (a Done line whose
+  # detail is neither delivered/merged nor abandoned, row 5.14).
+  def ledger_status_for(store_path, id)
+    dir = intent_dir_for(store_path, id)
+    return "unknown" unless dir
+
+    sp_path = File.join(dir, "savepoint.md")
+    return "unknown" unless File.exist?(sp_path)
+
+    parsed = complete_lines(read_utf8(sp_path)).filter_map { |l| parse_line(l) }
+    last_done = parsed.reverse.find { |p| p[:kind] == "Done" }
+    return "Active" unless last_done
+
+    classify_done_detail(last_done[:detail]) || "indeterminate"
+  end
+
+  # Drop the trailing torn fragment: a savepoint line that never got its
+  # closing newline because the process died mid-append (row 5.6). Works
+  # whether the file ends in a newline (the dropped element is the empty
+  # string split(-1) always yields after a final "\n") or not (the dropped
+  # element is the torn fragment itself).
+  def complete_lines(content)
+    return [] if content.to_s.empty?
+
+    lines = content.split("\n", -1)
+    lines.pop
+    lines.reject { |l| l.strip.empty? }
+  end
+
+  def parse_line(line)
+    parts = line.strip.split(/\s{2,}/, 3)
+    return nil unless parts.length == 3
+
+    { time: parts[0], kind: parts[1], detail: parts[2] }
+  end
+
+  def classify_done_detail(detail)
+    d = detail.to_s.strip
+    return "Abandoned" if d.start_with?("abandoned")
+    return "Completed" if d.start_with?("delivered") || d.start_with?("merged")
+
+    nil
+  end
+
+  # --- doctor exclusions (row 5.12) -----------------------------------------------
+
+  def excluded_ids(index_path)
+    loaded = DoctorExclusions.load(index_path)
+    EXCLUSION_RULES.flat_map { |rule| loaded[:rules][rule] || [] }.uniq
+  end
+
+  # --- utf-8 -----------------------------------------------------------------------
+
+  def read_utf8(path)
+    text = File.read(path)
+    text.force_encoding(Encoding::UTF_8)
+    text.valid_encoding? ? text : text.scrub("")
+  end
+end

package/scripts/lib/insights.rb

@@ -2,7 +2,7 @@
 # encoding: UTF-8
 
 # insights.rb - the blessed write path for an intent's `## Insights` section
-# (intent 82). A sibling library to bridge.rb so the insight write path stays
+# (intent 82). A standalone library so the insight write path stays
 # independent of the savepoint ledger (the spec forbids touching the ledger).
 #
 # Every entry leads with a fixed, machine-parseable prefix