@zalom/plastic 1.0.0-alpha.9 → 1.0.0-beta.10

package/scripts/qmd-sync

@@ -0,0 +1,139 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# qmd-sync — deterministic CLI over QmdSync (intent 45a).
+#
+# Plastic skills and hooks call these verbs instead of assembling `qmd` commands
+# themselves. QMD is optional: when `qmd` is absent every verb exits 0 and prints
+# a skip notice, so callers can invoke unconditionally.
+#
+# Usage:
+#   qmd-sync detect                     # exit 0 if qmd present, 1 if absent
+#   qmd-sync register --store <dir>     # register one store as a collection
+#   qmd-sync register --all             # register the global store + all projects
+#   qmd-sync reindex --store <dir>      # update + embed that store's collection
+#   qmd-sync reindex --store <dir> --async  # same, detached/non-blocking
+#   qmd-sync status [--format json]     # read-only status
+#   qmd-sync search "<terms>" [--store <dir>] [--limit N] [--min-score F]
+#                                       # ranked store search; scope by --store or CWD
+#
+# --home <path> overrides the Plastic home (default: ~/.plastic).
+
+require "json"
+require_relative "lib/qmd_sync"
+
+def plastic_home(args)
+  if (i = args.index("--home")) && args[i + 1]
+    File.expand_path(args[i + 1])
+  else
+    File.expand_path(ENV["PLASTIC_HOME"] || "~/.plastic")
+  end
+end
+
+def opt(args, name)
+  (i = args.index(name)) && args[i + 1]
+end
+
+verb = ARGV.shift
+home = plastic_home(ARGV)
+
+unless QmdSync.detect
+  case verb
+  when "detect"
+    warn "QMD not detected on PATH."
+    exit 1
+  else
+    puts "QMD not detected; skipped (#{verb})."
+    exit 0
+  end
+end
+
+case verb
+when "detect"
+  puts "QMD detected."
+  exit 0
+
+when "register"
+  stores =
+    if ARGV.include?("--all")
+      QmdSync.enumerate_stores(plastic_home: home)
+    elsif (dir = opt(ARGV, "--store"))
+      [{ collection: QmdSync.collection_name(dir, plastic_home: home), dir: File.expand_path(dir) }]
+    else
+      warn "register: pass --store <dir> or --all"
+      exit 2
+    end
+  stores.each do |s|
+    next unless Dir.exist?(s[:dir])
+    res = QmdSync.register(collection: s[:collection], dir: s[:dir])
+    puts "registered #{s[:collection]} -> #{s[:dir]} (#{res[:ok] ? "ok" : "warn"})"
+  end
+  exit 0
+
+when "reindex"
+  dir = opt(ARGV, "--store") or (warn("reindex: pass --store <dir>"); exit 2)
+  collection = QmdSync.collection_name(dir, plastic_home: home)
+  if ARGV.include?("--async")
+    QmdSync.reindex_async(collection: collection)
+    puts "reindex (async) #{collection} (started)"
+  else
+    res = QmdSync.reindex(collection: collection)
+    puts "reindexed #{collection} (#{res[:ok] ? "ok" : "warn"})"
+  end
+  exit 0
+
+when "status"
+  st = QmdSync.status(plastic_home: home)
+  if opt(ARGV, "--format") == "json"
+    puts JSON.generate(st)
+  else
+    puts "QMD present: #{st[:present]}"
+    puts "registered: #{Array(st[:registered]).join(", ")}"
+    puts "missing: #{Array(st[:missing]).join(", ")}" unless Array(st[:missing]).empty?
+  end
+  exit 0
+
+when "search"
+  # The query is the first bareword that is NOT the value of a known value-taking
+  # flag. Walk ARGV, skipping each such flag and the token right after it, then
+  # take the first remaining token that does not start with "--".
+  value_flags = %w[--store --limit --min-score --home]
+  query = nil
+  i = 0
+  while i < ARGV.length
+    tok = ARGV[i]
+    if value_flags.include?(tok)
+      i += 2
+      next
+    end
+    unless tok.start_with?("--")
+      query = tok
+      break
+    end
+    i += 1
+  end
+  collections =
+    if (dir = opt(ARGV, "--store"))
+      [QmdSync.collection_name(dir, plastic_home: home), "plastic-global"].uniq
+    else
+      QmdSync.collections_for_cwd(Dir.pwd, plastic_home: home)
+    end
+  limit = (opt(ARGV, "--limit") || "5").to_i
+  min_score = (opt(ARGV, "--min-score") || "0.5").to_f
+  hits = QmdSync.search(query, collections: collections, limit: limit, min_score: min_score)
+  if hits.empty?
+    puts "no qmd hits"
+  else
+    hits.each do |h|
+      pct = (h[:score] * 100).round
+      path = h[:file].to_s.sub(%r{\Aqmd://}, "")
+      puts "[#{pct}%] #{path} - #{h[:title]}"
+    end
+  end
+  exit 0
+
+else
+  warn "qmd-sync: unknown verb #{verb.inspect}. Use detect|register|reindex|status|search."
+  exit 2
+end

package/scripts/rebuild-graph

@@ -0,0 +1,244 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# rebuild-graph — repair the store-wide sources/chain frontmatter graph across the
+# global, plastic, and knowdb stores (intent 49). Deterministic, idempotent, and
+# one-directional (intent 68 I-invariants): dedupe, I3 (formative edge wins), I1
+# in-store backlinks, I2 preserved; cross-store refs resolved via a multi-hop
+# relocation map (relocation wins over coincidental id reuse). Emits a
+# before/after audit, then writes minimal style-preserving frontmatter.
+#
+# Usage:
+#   rebuild-graph [--plastic-home PATH] [--dry-run] [--audit-path PATH]
+#
+# Pure-Ruby (no bash). The pure logic lives in lib/graph_rebuild.rb and
+# lib/frontmatter_writer.rb; this shell does only discovery, IO, and reporting.
+# Never pushes ~/.plastic (no git ops here).
+
+require "yaml"
+require "date"
+require "time"
+require "fileutils"
+
+require_relative "lib/graph_rebuild"
+require_relative "lib/frontmatter_writer"
+require_relative "lib/intent_validator"
+
+class RebuildGraph
+  DEFAULT_HOME = File.join(Dir.home, ".plastic")
+
+  # The 49 intent dir audit destination (relative to plastic_home).
+  DEFAULT_AUDIT_REL =
+    "projects/plastic/store/49--store-wide-double-link-symmetry/resources/audit--graph-rebuild.md"
+
+  KIND_LABELS = {
+    dedupe: "Dedupes",
+    i3: "I3 resolutions (kept in sources, dropped from chain)",
+    repoint: "Cross-store repoints",
+    collapse: "Cross-store collapses (to bare same-store id)",
+    drop: "Dropped dead refs",
+    i1_backlink: "I1 backlinks added",
+  }.freeze
+
+  KIND_ORDER = %i[dedupe i3 repoint collapse drop i1_backlink].freeze
+
+  def initialize(plastic_home: DEFAULT_HOME, dry_run: false, audit_path: nil)
+    @plastic_home = plastic_home
+    @dry_run = dry_run
+
+    # A dry run must NOT stomp the canonical audit (the spec/checklist tell humans
+    # to run --dry-run to review the plan). When no explicit --audit-path is given,
+    # a dry run writes to a distinct `.dry-run.md` sibling, leaving the canonical
+    # real-run audit untouched. An explicit --audit-path is always honored verbatim
+    # (it is the caller's responsibility, and tests inject it).
+    canonical = File.join(plastic_home, DEFAULT_AUDIT_REL)
+    @audit_path =
+      if audit_path
+        audit_path
+      elsif dry_run
+        canonical.sub(/\.md\z/, ".dry-run.md")
+      else
+        canonical
+      end
+  end
+
+  attr_reader :plastic_home, :dry_run, :audit_path
+
+  # The three in-scope stores, each as { key:, root:, store:, index: }.
+  # `root` is the dir holding INDEX.md; `store` is the intents dir.
+  def stores
+    list = []
+    global_store = File.join(plastic_home, "store")
+    list << { key: "global", root: plastic_home, store: global_store,
+              index: File.join(plastic_home, "INDEX.md") } if File.directory?(global_store)
+
+    %w[plastic knowdb].each do |slug|
+      root = File.join(plastic_home, "projects", slug)
+      store = File.join(root, "store")
+      next unless File.directory?(store)
+
+      list << { key: "project:#{slug}", root: root, store: store,
+                index: File.join(root, "INDEX.md") }
+    end
+    list
+  end
+
+  # { id => { sources:, chain:, path: } } for one store.
+  def load_nodes(store_dir)
+    nodes = {}
+    Dir.children(store_dir).reject { |e| e.start_with?(".") }.sort.each do |entry|
+      dir = File.join(store_dir, entry)
+      next unless File.directory?(dir)
+
+      md = File.join(dir, "#{entry}.md")
+      next unless File.exist?(md)
+
+      fm = IntentValidator.parse_frontmatter(md)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      nodes[fm["id"].to_s] = {
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+        path: md,
+      }
+    end
+    nodes
+  end
+
+  def run
+    store_list = stores
+    nodes_by_store = {}
+    index_texts = {}
+    store_index = {}
+
+    store_list.each do |s|
+      nodes_by_store[s[:key]] = load_nodes(s[:store])
+      index_texts[s[:key]] = File.exist?(s[:index]) ? File.read(s[:index]) : ""
+      store_index[s[:key]] = nodes_by_store[s[:key]].keys
+    end
+
+    relocation_map = GraphRebuild.build_relocation_map(index_texts)
+
+    results = {}
+    store_list.each do |s|
+      key = s[:key]
+      input = nodes_by_store[key].transform_values { |v| { sources: v[:sources], chain: v[:chain] } }
+      results[key] = GraphRebuild.rebuild_store(
+        input,
+        referer_store: key,
+        relocation_map: relocation_map,
+        store_index: store_index
+      )
+    end
+
+    write_back(store_list, nodes_by_store, results) unless dry_run
+    emit_audit(store_list, nodes_by_store, results)
+
+    results
+  end
+
+  # Write changed frontmatter back via the minimal style-preserving writer.
+  def write_back(store_list, nodes_by_store, results)
+    store_list.each do |s|
+      key = s[:key]
+      new_nodes = results[key][:nodes]
+      nodes_by_store[key].each do |id, original|
+        rebuilt = new_nodes[id]
+        next if rebuilt.nil?
+        next if rebuilt[:sources] == original[:sources] && rebuilt[:chain] == original[:chain]
+
+        content = File.read(original[:path])
+        updated = FrontmatterWriter.rewrite_arrays(content,
+                                                   sources: rebuilt[:sources],
+                                                   chain: rebuilt[:chain])
+        File.write(original[:path], updated) if updated != content
+      end
+    end
+  end
+
+  # Render the audit and write it (always, even in dry-run, so the human reviews
+  # the dry-run plan). Returns the rendered string.
+  def emit_audit(store_list, _nodes_by_store, results)
+    text = render_audit(store_list, results)
+    FileUtils.mkdir_p(File.dirname(audit_path))
+    File.write(audit_path, text)
+    text
+  end
+
+  # PURE-ish formatter (string from results). Per-store, grouped by kind.
+  def render_audit(store_list, results)
+    total = store_list.sum { |s| results[s[:key]][:changes].size }
+    lines = []
+    lines << "# Audit: store-wide sources/chain graph rebuild (intent 49)"
+    lines << ""
+    lines << "Generated: #{Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")}#{dry_run ? " (DRY RUN)" : ""}"
+    lines << ""
+    lines << "Total changes across all stores: #{total}"
+    lines << ""
+
+    store_list.each do |s|
+      key = s[:key]
+      changes = results[key][:changes]
+      lines << "## #{key}"
+      lines << ""
+      if changes.empty?
+        lines << "No changes."
+        lines << ""
+        next
+      end
+
+      KIND_ORDER.each do |kind|
+        group = changes.select { |c| c[:kind] == kind }
+        next if group.empty?
+
+        lines << "### #{KIND_LABELS[kind]} (#{group.size})"
+        group.each { |c| lines << "- #{format_change(c)}" }
+        lines << ""
+      end
+    end
+
+    lines.join("\n") + "\n"
+  end
+
+  def format_change(c)
+    case c[:kind]
+    when :dedupe
+      "#{c[:intent]}: sources #{c[:before][:sources].inspect} → #{c[:after][:sources].inspect}, " \
+        "chain #{c[:before][:chain].inspect} → #{c[:after][:chain].inspect}"
+    when :i3
+      "#{c[:intent]}: #{c[:before]} kept in sources, dropped from chain"
+    when :repoint
+      "#{c[:intent]}.#{c[:field]}: #{c[:before]} → #{c[:after]} (relocated cross-store)"
+    when :collapse
+      "#{c[:intent]}.#{c[:field]}: #{c[:before]} → #{c[:after]} (collapsed to bare same-store id)"
+    when :drop
+      "#{c[:intent]}.#{c[:field]}: #{c[:before]} dropped (resolves nowhere)"
+    when :i1_backlink
+      "#{c[:intent]}.chain += #{c[:backlink]} (formative backlink)"
+    else
+      c.inspect
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  home = RebuildGraph::DEFAULT_HOME
+  dry = false
+  audit = nil
+  i = 0
+  while i < ARGV.length
+    case ARGV[i]
+    when "--plastic-home" then home = ARGV[i + 1]; i += 2
+    when "--dry-run" then dry = true; i += 1
+    when "--audit-path" then audit = ARGV[i + 1]; i += 2
+    else i += 1
+    end
+  end
+
+  tool = RebuildGraph.new(plastic_home: home, dry_run: dry, audit_path: audit)
+  results = tool.run
+  total = results.values.sum { |r| r[:changes].size }
+  puts "rebuild-graph #{dry ? "DRY RUN" : "applied"}: #{total} change(s) across #{results.size} store(s)."
+  puts "Audit: #{tool.audit_path}"
+end

package/scripts/select-update-target

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# plastic-script-version: 1.0.0
+# Channel-aware update target selector.
+#
+# Usage: npm view @zalom/plastic dist-tags --json | select-update-target <current-version>
+#
+# Prints the best update target to stdout, or nothing if already up to date.
+#
+# Rule: target = the highest version, among the dist-tags reachable from the
+# installed channel, that is strictly greater than the installed version (semver).
+#   alpha installed  -> reachable: alpha, beta, latest
+#   beta installed   -> reachable: beta, latest   (never downgrade to alpha)
+#   stable installed -> reachable: latest         (stable only)
+# A prerelease (1.1.0-alpha.1) is LOWER than its release (1.1.0); the `latest`
+# placeholder (0.0.1) is naturally excluded as lower than any 1.0.0-alpha.N.
+
+require "json"
+
+# Parse "MAJOR.MINOR.PATCH[-prerelease]" into a comparable structure.
+# Returns nil for anything that isn't a clean semver string.
+def parse(version)
+  m = /\A(\d+)\.(\d+)\.(\d+)(?:-(.+))?\z/.match(version.to_s.strip)
+  return nil unless m
+  { maj: m[1].to_i, min: m[2].to_i, pat: m[3].to_i,
+    pre: m[4] ? m[4].split(".") : nil }
+end
+
+# Semver precedence (§11). Returns -1, 0, or 1.
+def compare(a, b)
+  %i[maj min pat].each do |k|
+    return a[k] <=> b[k] unless a[k] == b[k]
+  end
+  # A version with no prerelease is greater than one with a prerelease.
+  return 0 if a[:pre].nil? && b[:pre].nil?
+  return 1 if a[:pre].nil?
+  return -1 if b[:pre].nil?
+  [a[:pre].length, b[:pre].length].max.times do |i|
+    x = a[:pre][i]
+    y = b[:pre][i]
+    return -1 if x.nil?
+    return 1 if y.nil?
+    xn = x.match?(/\A\d+\z/)
+    yn = y.match?(/\A\d+\z/)
+    if xn && yn
+      return x.to_i <=> y.to_i unless x.to_i == y.to_i
+    elsif xn
+      return -1 # numeric identifiers rank lower than alphanumeric
+    elsif yn
+      return 1
+    elsif x != y
+      return x <=> y
+    end
+  end
+  0
+end
+
+def channel(version)
+  return "alpha" if version.include?("-alpha")
+  return "beta" if version.include?("-beta")
+  "stable"
+end
+
+REACH = {
+  "alpha"  => %w[alpha beta latest],
+  "beta"   => %w[beta latest],
+  "stable" => %w[latest],
+}.freeze
+
+current = ARGV[0]
+cur = parse(current)
+exit 0 unless cur
+
+begin
+  tags = JSON.parse($stdin.read)
+rescue JSON::ParserError, StandardError
+  exit 0
+end
+exit 0 unless tags.is_a?(Hash)
+
+best = nil
+best_parsed = nil
+REACH[channel(current)].each do |tag|
+  raw = tags[tag]
+  next unless raw
+  parsed = parse(raw)
+  next unless parsed
+  if compare(parsed, cur) > 0 && (best_parsed.nil? || compare(parsed, best_parsed) > 0)
+    best = raw
+    best_parsed = parsed
+  end
+end
+
+print best if best

package/scripts/spawn-preamble

@@ -0,0 +1,138 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# spawn-preamble — deterministic live-state injection for spawned agents
+# (intent 4a1c1, agent harness foundation).
+#
+# Emits a preamble block built ONLY from filesystem state for a single intent
+# directory. It is a PURE function of the intent dir: no network, no randomness,
+# no wall-clock reads. Two runs over the same on-disk state produce byte-identical
+# output. This is the authoritative L2 (live-state) mechanism for harnesses whose
+# spawned sub-agents do not inherit a top-level session event (see
+# docs/reference/harness-adapters.md).
+#
+# Usage:
+#   spawn-preamble <intent_dir> [--role ROLE] [--step STEP]
+#
+# The preamble reports the active intent (id + intent line from frontmatter), the
+# current lifecycle stage (last savepoint line if present, else derived from which
+# lifecycle files exist), the cycle role/step (from --role/--step, else the
+# derived stage), and an imperative honoring instruction.
+#
+# Exit codes: 0 (preamble emitted), 2 (usage).
+
+require_relative "lib/bridge"
+
+# Verbatim honoring instruction. Kept as one constant so the contract doc and the
+# test assert against the exact same string.
+HONOR_INSTRUCTION =
+  "You are operating inside Plastic. Use it as your operating scaffold. " \
+  "Emit VALID lifecycle artifacts; do not hallucinate intents or stages. " \
+  "Your primary output is valid lifecycle artifacts; you close with a structured report about them."
+
+# Verbatim completion-report contract (intent 74). Kept as one constant so the
+# contract doc (skills/auto/references/agent-report-contract.md), the role prompts,
+# and the test assert against the exact same string. SINGLE SOURCE OF TRUTH for the
+# report wording: the work output is lifecycle artifacts, the final message is a
+# structured report about them. Both are required and they do not contradict.
+REPORT_CONTRACT =
+  "Before you finish, END your turn with a structured completion report as your " \
+  "FINAL MESSAGE (your return value), not a side-channel file. Do not go idle or " \
+  "finish silently. The report carries a common envelope: role, intent id, stage, " \
+  "status (delivered or blocked), artifacts written, verification or tests run, " \
+  "checklist deltas, deviations from spec, and blockers or handoff notes; plus a " \
+  "role-specific payload that fulfils your place in the What, Why, How, Exec cycle " \
+  "(for example the planner explains the plan back to the orchestrator). See " \
+  "skills/auto/references/agent-report-contract.md for the per-role format."
+
+def parse_args(argv)
+  role = nil
+  step = nil
+  positional = []
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--role"
+      role = argv[i + 1]
+      i += 2
+    when "--step"
+      step = argv[i + 1]
+      i += 2
+    else
+      positional << argv[i]
+      i += 1
+    end
+  end
+  [positional.first, role, step]
+end
+
+# Read the intent file frontmatter via the same parser the validator uses, so the
+# id/intent we report match what the rest of Plastic sees. Returns a Hash (possibly
+# empty) — never raises.
+def frontmatter_for(intent_dir)
+  ifile = Bridge.intent_file(intent_dir)
+  return {} unless File.exist?(ifile)
+
+  content = File.read(ifile)
+  return {} unless content.start_with?("---")
+
+  parts = content.split("---", 3)
+  return {} if parts.length < 3
+
+  require "yaml"
+  require "date"
+  require "time"
+  YAML.safe_load(parts[1], permitted_classes: [Date, Time]) || {}
+rescue StandardError
+  {}
+end
+
+# Current stage label. Prefer the last non-empty line of savepoint.md (the ledger
+# already encodes the furthest-reached milestone). Fall back to the file-derived
+# stage when there is no ledger.
+STAGE_LABELS = {
+  "what" => "What", "why" => "Why", "how" => "How",
+  "exec" => "Exec", "done" => "Done"
+}.freeze
+
+def current_stage(intent_dir)
+  ledger = File.join(intent_dir, Bridge::SAVEPOINT_FILE)
+  if File.exist?(ledger)
+    last = File.read(ledger).each_line.map(&:strip).reject(&:empty?).last
+    return last if last
+  end
+  STAGE_LABELS.fetch(Bridge.derive_stage(intent_dir), Bridge.derive_stage(intent_dir))
+end
+
+intent_dir_arg, role, step = parse_args(ARGV)
+
+if intent_dir_arg.nil? || intent_dir_arg.empty?
+  warn "usage: spawn-preamble <intent_dir> [--role ROLE] [--step STEP]"
+  exit 2
+end
+
+intent_dir = File.expand_path(intent_dir_arg)
+
+fm = frontmatter_for(intent_dir)
+id = fm["id"].to_s.strip
+intent_name = fm["intent"].to_s.strip
+id = "(unknown)" if id.empty?
+intent_name = "(unknown)" if intent_name.empty?
+
+stage = current_stage(intent_dir)
+cycle = role || step || stage
+
+lines = []
+lines << "=== Plastic spawn preamble ==="
+lines << "Store: #{intent_dir}"
+lines << "Active intent: #{id} - #{intent_name}"
+lines << "Current stage: #{stage}"
+lines << "Cycle step / role: #{cycle}"
+lines << ""
+lines << HONOR_INSTRUCTION
+lines << ""
+lines << REPORT_CONTRACT
+lines << "=== end preamble ==="
+
+puts lines.join("\n")

package/scripts/uninstall.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Plastic — `uninstall` verb. Runs via `npx @zalom/plastic uninstall` (bin/plastic.js) or directly.
+# Usage: ruby scripts/uninstall.rb [--claude|--codex|--hermes|--all] [--help]
+#
+# Manifest-driven removal of installed files + legacy-plugin migration. Leaves ~/.plastic/
+# (intent store, config, and the versions.json ledger) in place — the ledger is permanent.
+
+require_relative "lib/installer_core"
+
+class Uninstall < InstallerCore
+  def cli(argv = ARGV)
+    if argv.include?("--help") || argv.include?("-h")
+      show_help
+      return 0
+    end
+
+    selected = agent_keys_from(argv)
+    selected = ["claude"] if selected.empty?
+
+    puts "\n\u{1f9e0} Plastic v#{version} — uninstall\n\n"
+    handle_uninstall(selected)
+    0
+  end
+
+  private
+
+  def show_help
+    puts <<~HELP
+
+      plastic uninstall — remove Plastic from an agent
+
+      Usage:
+        npx @zalom/plastic uninstall [options]
+
+      Agent options:
+        --claude      Uninstall from Claude Code (default)
+        --codex       Uninstall from Codex CLI
+        --hermes      Uninstall from Hermes
+        --all         Uninstall from all supported agents
+
+      Other options:
+        -h, --help    Show this help
+
+      Leaves your intent store, config, and version ledger (~/.plastic/) in place.
+
+    HELP
+  end
+end
+
+exit(Uninstall.new(package_root: ENV["PLASTIC_PACKAGE_ROOT"] || File.expand_path("..", __dir__)).cli(ARGV)) if $PROGRAM_NAME == __FILE__