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

package/scripts/new-intent

@@ -0,0 +1,226 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# new-intent (intent 60b) - the one-call scaffolding contract.
+#
+# A single invocation scaffolds a COMPLETE intent: it allocates the Folgezettel
+# id (root vs branch by --parent), creates the directory tree (<id>--<slug>/ plus
+# actions/ and resources/), renders the born-complete intent file from
+# templates/intent.md, writes sentinel placeholder lifecycle files (spec.md,
+# plan.md, checklist.md, outcome.md, each carrying <!-- plastic:placeholder -->
+# as its first line), wires reciprocal file links, and self-validates with
+# IntentValidator (exit non-zero if not born complete).
+#
+# It does NOT touch INDEX.md, git, or project creation: those remain skill/agent
+# responsibilities (see plastic-creating-intent).
+#
+# Usage:
+#   new-intent --store <store_path> --intent "<one-line>" --slug <slug> \
+#              [--parent <id>] [--author <name>] [--sources id,id] \
+#              [--tags tag,tag] [--templates <dir>]
+#
+# Exit codes: 0 (born complete), 1 (scaffold failed self-validation or bad input).
+
+require "fileutils"
+require "date"
+require_relative "lib/bridge"
+require_relative "lib/intent_validator"
+
+# --- Explicit flag parsing (no eval, no global injection) ------------------
+
+def parse_args(argv)
+  opts = {
+    store: nil, intent: nil, slug: nil, parent: nil,
+    author: "claude-code", sources: [], tags: [], templates: nil
+  }
+  i = 0
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--store"     then opts[:store] = argv[i += 1]
+    when "--intent"    then opts[:intent] = argv[i += 1]
+    when "--slug"      then opts[:slug] = argv[i += 1]
+    when "--parent"    then opts[:parent] = argv[i += 1]
+    when "--author"    then opts[:author] = argv[i += 1]
+    when "--sources"   then opts[:sources] = split_list(argv[i += 1])
+    when "--tags"      then opts[:tags] = split_list(argv[i += 1])
+    when "--templates" then opts[:templates] = argv[i += 1]
+    else
+      abort "new-intent: unknown argument #{arg.inspect}"
+    end
+    i += 1
+  end
+  opts
+end
+
+def split_list(value)
+  value.to_s.split(",").map(&:strip).reject(&:empty?)
+end
+
+def expand(path)
+  File.expand_path(path.to_s.sub(/\A~/, Dir.home))
+end
+
+# Default templates dir: sibling of this script's dir. Works in-repo
+# (<repo>/scripts/new-intent -> <repo>/templates) and installed
+# (~/.plastic/scripts/new-intent -> ~/.plastic/templates when present).
+def default_templates_dir
+  File.expand_path("../templates", __dir__)
+end
+
+def render_tokens(text, tokens)
+  tokens.reduce(text) { |acc, (k, v)| acc.gsub("{{#{k}}}", v.to_s) }
+end
+
+# Add an id to a source intent's frontmatter `chain` array, idempotently (I1
+# reciprocity: `child in parent.sources` => `parent.chain` gains `child`). A
+# targeted edit of the `chain:` line only; the body (including `## Links`) is
+# preserved byte-for-byte and no other frontmatter key is touched, so the file
+# stays born-complete. Renders the array in flow style (`["a", "b"]`) to match
+# templates/intent.md. No-op when the id is already present.
+def add_to_chain(file_path, new_id)
+  return unless File.exist?(file_path)
+  content = File.read(file_path)
+  return unless content.start_with?("---")
+
+  parts = content.split("---", 3)
+  return unless parts.length >= 3
+
+  fm = parts[1]
+  chain_line = fm.lines.find { |l| l.match?(/\A\s*chain\s*:/) }
+  return unless chain_line
+
+  existing = fm.match(/\bchain\s*:\s*\[(.*?)\]/m)
+  ids =
+    if existing
+      existing[1].scan(/"([^"]*)"|'([^']*)'/).flatten.compact
+    else
+      []
+    end
+  return if ids.include?(new_id)
+
+  ids << new_id
+  rendered = "chain: [#{ids.map { |i| "\"#{i}\"" }.join(", ")}]"
+  new_fm = fm.sub(/^\s*chain\s*:.*$/, rendered)
+  File.write(file_path, ["", new_fm, parts[2]].join("---"))
+end
+
+# Append a wikilink line under the file's `## Links` section, idempotently.
+def append_link(file_path, link_line)
+  return unless File.exist?(file_path)
+  content = File.read(file_path)
+  return if content.include?(link_line)
+
+  lines = content.lines
+  idx = lines.index { |l| l.strip == "## Links" }
+  return unless idx
+
+  insert_at = lines.length
+  ((idx + 1)...lines.length).each do |j|
+    if lines[j].strip.start_with?("## ")
+      insert_at = j
+      break
+    end
+  end
+  lines.insert(insert_at, "#{link_line}\n")
+  File.write(file_path, lines.join)
+end
+
+def main(argv)
+  opts = parse_args(argv)
+  abort "new-intent: --store is required" if opts[:store].nil? || opts[:store].empty?
+  abort "new-intent: --intent is required" if opts[:intent].nil? || opts[:intent].empty?
+  abort "new-intent: --slug is required" if opts[:slug].nil? || opts[:slug].empty?
+
+  store = expand(opts[:store])
+  abort "new-intent: store dir does not exist: #{store}" unless Dir.exist?(store)
+
+  templates = opts[:templates] ? expand(opts[:templates]) : default_templates_dir
+  abort "new-intent: templates dir not found: #{templates}" unless Dir.exist?(templates)
+
+  # 1. Allocate id via the existing folgezettel-id logic (root vs branch).
+  folg = File.expand_path("folgezettel-id", __dir__)
+  cmd = [folg, store]
+  cmd << opts[:parent] if opts[:parent] && !opts[:parent].empty?
+  id = `#{cmd.map { |c| "'#{c}'" }.join(" ")}`.strip
+  abort "new-intent: id allocation failed" if id.empty?
+
+  slug = opts[:slug]
+  intent_dir = File.join(store, "#{id}--#{slug}")
+  abort "new-intent: #{intent_dir} already exists" if File.exist?(intent_dir)
+
+  # 2. Create dirs.
+  FileUtils.mkdir_p(File.join(intent_dir, "actions"))
+  FileUtils.mkdir_p(File.join(intent_dir, "resources"))
+
+  # 3. Render the born-complete intent file from templates/intent.md.
+  sources = opts[:sources]
+  sources = sources | [opts[:parent]] if opts[:parent] && !opts[:parent].empty? && !sources.include?(opts[:parent])
+  sources_str = sources.map { |s| "\"#{s}\"" }.join(", ")
+  tags_str = opts[:tags].map { |t| "\"#{t}\"" }.join(", ")
+
+  intent_template = File.read(File.join(templates, "intent.md"))
+  intent_body = render_tokens(intent_template, {
+    "ID" => id,
+    "INTENT" => opts[:intent],
+    "SOURCES" => sources_str,
+    "DATE" => Date.today.iso8601,
+    "AUTHOR" => opts[:author],
+    "TAGS" => tags_str,
+    "DESCRIPTION" => opts[:intent],
+  })
+  intent_file = File.join(intent_dir, "#{id}--#{slug}.md")
+  File.write(intent_file, intent_body)
+
+  # 4a. I1 reciprocity: write the child's id into EACH source intent's frontmatter
+  # `chain` (the formative-reciprocity backlink), for BOTH the `--parent` and the
+  # `--sources` path. `sources` is the redundant-explicit set from step 3 (it already
+  # folds in `--parent`). Scope boundary: 68 fixes ONLY the frontmatter `chain`
+  # backlink; the `## Links` wikilink projection for the `--sources` path is intent 72.
+  sources.each do |src_id|
+    next if src_id.nil? || src_id.empty?
+
+    src_dir = Dir.glob(File.join(store, "#{src_id}--*")).find { |d| File.directory?(d) }
+    next unless src_dir
+
+    src_file = File.join(src_dir, "#{File.basename(src_dir)}.md")
+    add_to_chain(src_file, id)
+  end
+
+  # 4b. Reciprocal `## Links` wikilinks: forward link to parent + back-reference in
+  # the parent (kept parent-only; the `--sources` path's wikilink is intent 72's scope).
+  if opts[:parent] && !opts[:parent].empty?
+    parent_id = opts[:parent]
+    append_link(intent_file, "- [[#{parent_id}]]")
+    parent_dir = Dir.glob(File.join(store, "#{parent_id}--*")).find { |d| File.directory?(d) }
+    if parent_dir
+      parent_file = File.join(parent_dir, "#{File.basename(parent_dir)}.md")
+      append_link(parent_file, "- [[#{id}]]")
+    end
+  end
+
+  # 5. Sentinel placeholders for each lifecycle file. The sentinel is the FIRST
+  # line; the rendered template body follows so the file is a usable starting
+  # point once an agent deletes the sentinel.
+  %w[spec.md plan.md checklist.md outcome.md].each do |name|
+    template_path = File.join(templates, name)
+    body = File.exist?(template_path) ? File.read(template_path) : ""
+    body = render_tokens(body, { "INTENT_NAME" => opts[:intent] })
+    File.write(File.join(intent_dir, name), "#{Bridge::PLACEHOLDER_SENTINEL}\n#{body}")
+  end
+
+  # 6. Self-validate (frontmatter + sanctioned sections).
+  result = IntentValidator.validate(intent_dir)
+  unless result[:ok]
+    warn "new-intent: scaffolded intent is NOT born complete:"
+    result[:missing].each { |f| warn "  missing field: #{f}" }
+    result[:errors].each { |e| warn "  #{e}" }
+    exit 1
+  end
+
+  puts intent_dir
+  exit 0
+end
+
+main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/provision-project-store

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# provision-project-store — deterministic CLI over StoreProvisioning (intent 61).
+#
+# Creates a registered project's store at ~/.plastic/projects/{slug}/store: it
+# makes the store directory, then writes, only if missing, .gitkeep, INDEX.md,
+# and project.yml. It is pure filesystem and idempotent, so re-running never
+# clobbers existing files and performs no qmd mutation. The project must already
+# be registered in projects.yml; an unregistered slug exits non-zero and creates
+# nothing.
+#
+# Usage:
+#   provision-project-store <slug> [--home <path>]
+#
+# Exit codes: 0 (store provisioned), 1 (unregistered slug / error on stderr),
+# 2 (usage). --home <path> overrides the Plastic home (default: ~/.plastic).
+
+require_relative "lib/store_provisioning"
+
+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
+
+home = plastic_home(ARGV)
+
+# First positional arg, skipping any flag and the value that follows --home.
+home_value_index = (i = ARGV.index("--home")) ? i + 1 : nil
+slug_index = ARGV.each_index.find do |idx|
+  arg = ARGV[idx]
+  !arg.start_with?("--") && idx != home_value_index
+end
+slug = slug_index && ARGV[slug_index]
+
+if slug.nil?
+  warn "usage: provision-project-store <slug> [--home <path>]"
+  exit 2
+end
+
+result = StoreProvisioning.provision(slug, plastic_home: home)
+
+if result[:ok]
+  puts "OK: #{result[:store_dir]}"
+  exit 0
+end
+
+warn result[:error]
+exit 1

package/scripts/qmd-sync

@@ -0,0 +1,92 @@
+#!/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 status [--format json]     # read-only status
+#
+# --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)
+  res = QmdSync.reindex(collection: collection)
+  puts "reindexed #{collection} (#{res[:ok] ? "ok" : "warn"})"
+  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
+
+else
+  warn "qmd-sync: unknown verb #{verb.inspect}. Use detect|register|reindex|status."
+  exit 2
+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,121 @@
+#!/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 output is a deliverable, not a message."
+
+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 << "=== 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__