@zalom/plastic 1.0.0-beta.2 → 1.0.0-beta.21

package/scripts/lib/worktree.rb

@@ -0,0 +1,409 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "socket"
+require "time"
+
+# Worktree -- Plastic-supplied git worktree isolation and the delivery lock
+# (intent 73c / 73c1).
+#
+# The harness `EnterWorktree` tool assumes cwd IS the repo root, which is false
+# for Plastic (cwd is often the parent of the repo subdir). When the mismatch
+# occurs the tool silently degrades to a plain feature branch on the shared
+# checkout, so parallel intent deliveries are NOT isolated. This module makes
+# isolation deterministic and cwd-independent: Plastic resolves the repo from
+# projects.yml and runs `git -C <repo> worktree add`, so the cwd-not-root bug
+# dies by construction (decision D6).
+#
+# Two worktrees per project intent, both named `{id}--{slug}` (decision D2):
+#   code  worktree  <repo>/.claude/worktrees/{id}--{slug}  branch plastic/{id}--{slug}
+#   store worktree  <plastic_home>/.worktrees/{id}--{slug} branch plastic-store/{id}--{slug}
+#
+# The bridge file doubles as the delivery lock (decision D3): single-owner,
+# stale-lock reclaim via pid liveness.
+#
+# Pure and dependency-injected: every git call goes through an injected
+# `ShellRunner`, so unit tests are hermetic (no real git; inject a fake runner).
+# No eval, no global/ENV config injection.
+module Worktree
+  module_function
+
+  # --- ShellRunner (DI seam) -------------------------------------------------
+
+  # The default runner shells out to real `git`. Tests inject a fake with the
+  # same `run(*args)` contract so no real git runs in unit tests.
+  class ShellRunner
+    Result = Struct.new(:status, :stdout, :stderr) do
+      def success?
+        status.zero?
+      end
+    end
+
+    def run(*args)
+      require "open3"
+      out, err, status = Open3.capture3("git", *args.map(&:to_s))
+      Result.new(status.exitstatus.to_i, out, err)
+    end
+  end
+
+  # --- pure helpers ----------------------------------------------------------
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+
+  # The `{id}--{slug}` identity shared by both worktrees and both branches.
+  def dir_name(intent_id, intent_slug)
+    "#{intent_id}--#{intent_slug}"
+  end
+
+  # Pure, deterministic. Returns the four paths/branches. No git calls.
+  # `repo_path` is resolved from projects.yml when nil; when it cannot be
+  # resolved the code worktree path/branch are nil (a global-store-only intent).
+  def paths(slug:, intent_id:, intent_slug:, home: Dir.home, repo_path: nil)
+    name = dir_name(intent_id, intent_slug)
+    repo = repo_path || repo_for(slug, home: home)
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+
+    code_path = repo ? File.join(File.expand_path(repo), ".claude", "worktrees", name) : nil
+    store_path = File.join(plastic_home, ".worktrees", name)
+
+    {
+      "code" => code_path,
+      "code_branch" => code_path ? "plastic/#{name}" : nil,
+      "store" => store_path,
+      "store_branch" => "plastic-store/#{name}",
+    }
+  end
+
+  # Absolute repo path for a project slug from `~/.plastic/projects.yml`, or nil.
+  # Reuses the qmd_sync safe-loader pattern: any failure yields nil.
+  def repo_for(slug, home: Dir.home)
+    return nil if blank?(slug)
+    projects = load_projects(home)
+    info = projects[slug.to_s]
+    path = info.is_a?(Hash) ? info["path"] : nil
+    return nil if blank?(path)
+    File.expand_path(path)
+  end
+
+  # --- provisioning ----------------------------------------------------------
+
+  # Resolve the slug from the bridge's intent.store, create code + store
+  # worktrees (idempotent: reuse an existing worktree path, do not error), write
+  # the `worktree` block plus `provisioned: true` onto bridge_data, return it.
+  #
+  # Fails open with a stderr log when the repo is non-git or unresolvable:
+  # sets `provisioned: false` and leaves `code: null`. All git ops use
+  # `git -C <resolved path>` -- never cwd (decision D6).
+  def provision(bridge_data, home: Dir.home, runner: ShellRunner.new)
+    return bridge_data unless bridge_data.is_a?(Hash)
+    intent = bridge_data["intent"] || {}
+    intent_id = intent["id"].to_s
+    store = intent["store"].to_s
+    intent_slug = slug_from_dir(intent["dir"]) || slug_from_dir(store)
+
+    slug = slug_for_store(store, home: home)
+    p = paths(slug: slug, intent_id: intent_id, intent_slug: intent_slug, home: home)
+
+    block = {
+      "code" => nil,
+      "code_branch" => nil,
+      "store" => p["store"],
+      "store_branch" => p["store_branch"],
+      "provisioned" => false,
+    }
+
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+
+    # Gitignore safety (intent 73c3): the store worktrees live under the store git
+    # repo, so without ignoring `.worktrees/` a `git add -A` sweeps their gitlinks
+    # into the store commit. Ensure both ignore entries before any worktree add.
+    ensure_gitignored(plastic_home, ".worktrees/", runner: runner)
+
+    # Store worktree: created against the plastic home git repo. Fail-open if the
+    # store repo is not a git repo (a fresh global store may be ungit'd).
+    store_ok = add_worktree(runner, repo: plastic_home,
+                            worktree: p["store"], branch: p["store_branch"],
+                            label: "store")
+
+    # Code worktree: MANDATORY for project intents. Fail-open when the repo is
+    # unresolvable or non-git -- that is the global-store-only / non-git case.
+    repo = repo_for(slug, home: home)
+    code_ok = false
+    if repo && git_repo?(runner, repo)
+      ensure_gitignored(repo, ".claude/worktrees/", runner: runner)
+      code_ok = add_worktree(runner, repo: repo,
+                             worktree: p["code"], branch: p["code_branch"],
+                             label: "code")
+      if code_ok
+        block["code"] = p["code"]
+        block["code_branch"] = p["code_branch"]
+      end
+    else
+      warn "plastic: worktree provision fail-open -- repo for slug #{slug.inspect} " \
+           "is unresolvable or not a git repo; code worktree skipped"
+    end
+
+    block["store"] = store_ok ? p["store"] : nil
+    block["store_branch"] = store_ok ? p["store_branch"] : nil
+
+    # provisioned is true only when the MANDATORY code worktree exists. The gate
+    # fails open on provisioned: false (non-git / global-only).
+    block["provisioned"] = code_ok
+
+    bridge_data["worktree"] = block
+    bridge_data
+  end
+
+  # Remove both worktrees (then `git worktree prune`), clear the worktree block.
+  # No-op when nothing was provisioned. CLEANUP (73c3) layers the merge-vs-remove
+  # policy on top via `finish`; this is the plain remove. Pass `remove: false` to
+  # clear the block WITHOUT touching git (so `finish` can merge first, then call
+  # release to drop the worktrees once the code branch is integrated).
+  def release(bridge_data, home: Dir.home, runner: ShellRunner.new, remove: true)
+    return bridge_data unless bridge_data.is_a?(Hash)
+    block = bridge_data["worktree"]
+    return bridge_data unless block.is_a?(Hash)
+
+    if remove
+      plastic_home = File.expand_path(File.join(home, ".plastic"))
+      slug = slug_for_store(bridge_data.dig("intent", "store").to_s, home: home)
+      repo = repo_for(slug, home: home)
+
+      remove_worktree(runner, repo: repo, worktree: block["code"]) if repo && block["code"]
+      remove_worktree(runner, repo: plastic_home, worktree: block["store"]) if block["store"]
+
+      prune(runner, repo: repo) if repo
+      prune(runner, repo: plastic_home)
+    end
+
+    bridge_data.delete("worktree")
+    bridge_data
+  end
+
+  # --- cleanup policy (merge-vs-remove) -------------------------------------
+
+  # Finish an intent's delivery by tearing down its worktrees, optionally merging
+  # the code branch back first (intent 73c3). The merge-vs-remove decision is the
+  # one piece of policy on top of the plain `release`:
+  #
+  #   merge: true  -> the releasing path. Merge the intent's code branch
+  #                   (`plastic/{id}--{slug}`) into the repo's default branch
+  #                   BEFORE removing the worktrees, so the work is integrated and
+  #                   not lost when the worktree disappears. Then `release`.
+  #   merge: false -> the disarm / abandon path. Just `release` (plain remove);
+  #                   the branch survives and can be reclaimed.
+  #
+  # Fail-open and idempotent throughout: a missing block, missing branch, or any
+  # git failure never raises and never blocks teardown. All git ops use
+  # `git -C <path>`, never cwd (decision D6). No-op when nothing was provisioned.
+  def finish(bridge_data, home: Dir.home, runner: ShellRunner.new, merge: false)
+    return bridge_data unless bridge_data.is_a?(Hash)
+    block = bridge_data["worktree"]
+    return bridge_data unless block.is_a?(Hash)
+
+    if merge
+      slug = slug_for_store(bridge_data.dig("intent", "store").to_s, home: home)
+      repo = repo_for(slug, home: home)
+      branch = block["code_branch"]
+      merge_branch(runner, repo: repo, branch: branch) if repo && !blank?(branch)
+    end
+
+    release(bridge_data, home: home, runner: runner, remove: true)
+  end
+
+  # Merge `branch` into the repo's default branch from the main checkout. The
+  # worktree the branch is checked out in stays put; we merge in the repo dir
+  # itself (its own current branch is the integration target). Idempotent: a
+  # no-op merge ("Already up to date") still succeeds. Fail-open: a conflicting
+  # or otherwise failing merge is aborted and logged, never raised, so teardown
+  # still proceeds (CLEANUP must not strand a worktree).
+  def merge_branch(runner, repo:, branch:)
+    return false if blank?(repo) || blank?(branch)
+    target = current_branch(runner, repo: repo)
+    return false if blank?(target) || target == branch
+
+    res = runner.run("-C", repo, "merge", "--no-ff", "--no-edit", branch)
+    return true if res.success?
+
+    # Leave the integration branch clean: abort a half-applied/conflicted merge.
+    runner.run("-C", repo, "merge", "--abort")
+    warn "plastic: worktree finish could not merge #{branch.inspect} into " \
+         "#{target.inspect}: #{res.stderr.to_s.strip}; removing worktree without merge"
+    false
+  end
+
+  # The repo's current branch (the integration target), or nil when detached /
+  # unresolvable.
+  def current_branch(runner, repo:)
+    return nil if blank?(repo)
+    res = runner.run("-C", repo, "rev-parse", "--abbrev-ref", "HEAD")
+    return nil unless res.success?
+    name = res.stdout.to_s.strip
+    (name.empty? || name == "HEAD") ? nil : name
+  end
+
+  # --- gitignore safety ------------------------------------------------------
+
+  # Ensure `entry` is present in `<repo>/.gitignore`, appending it once if absent
+  # (idempotent). Without this, the store worktrees that live UNDER the store git
+  # repo (~/.plastic/.worktrees/) get swept into the store commit by a `git add
+  # -A`, polluting the index with worktree gitlinks (observed during 73c1
+  # integration). Provisioning and cleanup both call this so the repos' indexes
+  # stay clean. Best-effort and non-raising: any failure is logged, never raised.
+  def ensure_gitignored(repo, entry, runner: ShellRunner.new)
+    return false if blank?(repo) || blank?(entry) || !Dir.exist?(repo)
+    gitignore = File.join(File.expand_path(repo), ".gitignore")
+    want = entry.to_s.strip
+
+    existing = File.exist?(gitignore) ? File.read(gitignore) : ""
+    present = existing.each_line.any? { |line| line.strip == want }
+    return true if present
+
+    File.open(gitignore, "a") do |io|
+      io.write("\n") unless existing.empty? || existing.end_with?("\n")
+      io.write("#{want}\n")
+    end
+    true
+  rescue StandardError => e
+    warn "plastic: ensure_gitignored(#{entry.inspect}) failed for #{repo.inspect}: #{e.message}"
+    false
+  end
+
+  # --- lock ------------------------------------------------------------------
+
+  # pid liveness: signal 0 probes without sending. Any error (no such process,
+  # not ours) means not live.
+  def session_live?(pid)
+    n = Integer(pid) rescue nil
+    return false if n.nil? || n <= 0
+    Process.kill(0, n)
+    true
+  rescue StandardError
+    false
+  end
+
+  # True iff ANOTHER bridge for this intent has a LIVE owner pid that is not
+  # current_session. Scans /tmp/plastic-*.json (or `tmp`). The current session's
+  # own bridge never counts as "other". A dead owner does not hold the lock
+  # (stale-lock reclaim).
+  def lock_held_by_other?(intent_id:, store:, current_session:, home: Dir.home, tmp: nil)
+    tmp ||= default_tmp
+    id = intent_id.to_s
+    st = File.expand_path(store.to_s) unless blank?(store)
+
+    Dir.glob(File.join(tmp, "plastic-*.json")).each do |f|
+      next if f.end_with?(".tmp")
+      data = (JSON.parse(File.read(f)) rescue nil)
+      next unless data.is_a?(Hash)
+
+      intent = data["intent"] || {}
+      next unless intent["id"].to_s == id
+      unless st.nil?
+        bstore = intent["store"].to_s
+        next unless bstore.empty? || File.expand_path(bstore) == st
+      end
+
+      session = data["session"].to_s
+      next if !blank?(current_session) && session == current_session.to_s
+
+      lock = data["lock"] || {}
+      owner_pid = lock["pid"]
+      return true if session_live?(owner_pid)
+    end
+    false
+  rescue StandardError
+    false
+  end
+
+  # --- git operations (all use -C, never cwd) --------------------------------
+
+  # Idempotent worktree add. If `worktree` already exists on disk, treat as
+  # reuse (success, no git call). Otherwise `git -C <repo> worktree add <wt>
+  # -b <branch>`; if the branch already exists, retry without -b (reattach).
+  def add_worktree(runner, repo:, worktree:, branch:, label:)
+    return false if blank?(repo) || blank?(worktree)
+    return true if Dir.exist?(worktree) # idempotent reuse
+
+    res = runner.run("-C", repo, "worktree", "add", worktree, "-b", branch)
+    return true if res.success?
+
+    # Branch may already exist (a prior provision that was pruned but kept the
+    # branch). Retry attaching the existing branch.
+    res2 = runner.run("-C", repo, "worktree", "add", worktree, branch)
+    return true if res2.success?
+
+    warn "plastic: worktree add (#{label}) failed: #{res.stderr.to_s.strip}"
+    false
+  end
+
+  def remove_worktree(runner, repo:, worktree:)
+    return false if blank?(repo) || blank?(worktree)
+    res = runner.run("-C", repo, "worktree", "remove", worktree)
+    unless res.success?
+      # Force-remove tolerates dirty/locked worktrees; CLEANUP owns merge policy.
+      res = runner.run("-C", repo, "worktree", "remove", "--force", worktree)
+    end
+    res.success?
+  end
+
+  def prune(runner, repo:)
+    return false if blank?(repo)
+    runner.run("-C", repo, "worktree", "prune").success?
+  end
+
+  # True iff `repo` is a git work tree (idempotent, no mutation).
+  def git_repo?(runner, repo)
+    return false if blank?(repo) || !Dir.exist?(repo)
+    res = runner.run("-C", repo, "rev-parse", "--is-inside-work-tree")
+    res.success? && res.stdout.to_s.strip == "true"
+  end
+
+  # --- internals (projects.yml resolution, mirrors qmd_sync) -----------------
+
+  def load_projects(home)
+    path = File.join(File.expand_path(home), ".plastic", "projects.yml")
+    return {} unless File.exist?(path)
+    data = begin
+      YAML.safe_load(File.read(path)) || {}
+    rescue StandardError
+      {}
+    end
+    projects = data.is_a?(Hash) ? data["projects"] : nil
+    projects.is_a?(Hash) ? projects : {}
+  end
+
+  # Resolve a project slug from a store directory. A project's tactical store
+  # lives at <plastic_home>/projects/<slug>/store; the global store yields nil
+  # (no project repo). Mirrors qmd_sync's slug_for_store fallback.
+  def slug_for_store(store_dir, home: Dir.home)
+    return nil if blank?(store_dir)
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+    store_dir = File.expand_path(store_dir)
+    return nil if store_dir == File.join(plastic_home, "store")
+
+    parts = store_dir.split(File::SEPARATOR)
+    idx = parts.rindex("projects")
+    return parts[idx + 1] if idx && parts[idx + 1] && parts[idx + 2] == "store"
+    nil
+  end
+
+  # Best-effort slug for the worktree dir-name from an intent dir/store path:
+  # the basename `{id}--{slug}` -> the `{slug}` portion (split on the first
+  # `--`). Used only for naming.
+  def slug_from_dir(dir)
+    return nil if blank?(dir)
+    base = File.basename(dir.to_s)
+    idx = base.index("--")
+    return nil unless idx
+    base[(idx + 2)..]
+  end
+
+  def default_tmp
+    t = ENV["PLASTIC_TMP"]
+    (t.nil? || t.strip.empty?) ? "/tmp" : t
+  end
+end

package/scripts/link-suggest

@@ -0,0 +1,211 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# link-suggest - support links decided by CONTEXT INFLUENCE (intent 91, D7). Links are
+# NOT graded by a script: whether one intent's context influenced another is a
+# judgement an agent makes by reading the candidate's Intent + Context. This tool
+# gathers candidates with that evidence, records a CONFIRMED edge plus its rating and
+# reason in `link-decisions.md`, and flags drift. It never writes a `## Links` line and
+# never deletes.
+#
+# `## Links` is a DERIVED view of `sources`/`chain` (Convention over Configuration).
+# Tiers, by context influence:
+#   sources - the foundational context that shaped this intent's creation.
+#   chain   - the context that materially helps DELIVER this intent. HIGH bar.
+#   tags    - loose theme grouping for search. Not a link.
+#
+# Usage:
+#   link-suggest <subject_id> [--store-dir PATH] [--plastic-home PATH]
+#   link-suggest <subject_id> --record <target_id> --edge <sources|chain>
+#                --rating <high|medium|low> --reason "..." --confirm
+#   link-suggest --help
+#
+# Default (no --record) prints candidates WITH their Intent+Context plus any drift, and
+# writes nothing. --record without --confirm prints what would happen and writes
+# nothing. --edge is explicit and required (sources is decided by origin, never
+# inferred); --rating is required when --edge is chain.
+
+require_relative "lib/link_suggestions"
+
+module LinkSuggestCLI
+  module_function
+
+  DEFAULT_HOME = File.join(Dir.home, ".plastic")
+
+  USAGE = <<~TXT
+    Usage:
+      link-suggest <subject_id> [--store-dir PATH] [--plastic-home PATH]
+      link-suggest <subject_id> --record <target_id> --edge <sources|chain> \\
+                   --rating <high|medium|low> --reason "..." --confirm
+      link-suggest --help
+
+    Links are decided by context influence, judged by an agent reading each
+    candidate's Intent + Context. This tool only gathers candidates with that
+    evidence, records a confirmed edge plus its rating/reason in link-decisions.md,
+    and flags drift. It never writes a ## Links line and never deletes.
+
+    --edge is explicit and required (sources is decided by origin, never inferred).
+    --rating is required when --edge is chain. Without --confirm, nothing is written.
+  TXT
+
+  def parse(argv)
+    opts = { home: DEFAULT_HOME, store_dir: nil, subject: nil, help: false,
+             record: nil, edge: nil, rating: nil, reason: nil, confirm: false }
+    i = 0
+    while i < argv.length
+      case argv[i]
+      when "--help", "-h" then opts[:help] = true; i += 1
+      when "--plastic-home" then opts[:home] = argv[i + 1]; i += 2
+      when "--store-dir" then opts[:store_dir] = argv[i + 1]; i += 2
+      when "--record" then opts[:record] = argv[i + 1]; i += 2
+      when "--edge" then opts[:edge] = (argv[i + 1] || "").to_sym; i += 2
+      when "--rating" then opts[:rating] = argv[i + 1]; i += 2
+      when "--reason" then opts[:reason] = argv[i + 1]; i += 2
+      when "--confirm" then opts[:confirm] = true; i += 1
+      else
+        opts[:subject] ||= argv[i]
+        i += 1
+      end
+    end
+    opts[:store_dir] ||= File.join(opts[:home], "store")
+    opts
+  end
+
+  # Print the discovery candidates with their Intent + Context evidence, plus drift.
+  def report(tool, subject, out: $stdout)
+    nodes = tool.load_nodes
+    unless nodes.key?(subject)
+      out.puts "link-suggest: no intent #{subject.inspect} in #{tool.store_dir}"
+      return 1
+    end
+
+    cands = tool.gather(subject, nodes: nodes)
+    out.puts "Candidates for #{subject} (discovery only; judge influence by reading context):"
+    if cands.empty?
+      out.puts "  (none)"
+    else
+      cands.each { |c| print_candidate(c, out) }
+    end
+
+    flaws = tool.drift(subject, nodes: nodes)
+    out.puts "Drift for #{subject}:"
+    if flaws.empty?
+      out.puts "  (none)"
+    else
+      flaws.each { |f| out.puts "  [drift] #{f.detail}" }
+    end
+    0
+  end
+
+  def print_candidate(cand, out)
+    out.puts "  - #{cand.id}  #{cand.label}"
+    out.puts "    Intent:  #{excerpt(cand.intent)}" unless cand.intent.empty?
+    out.puts "    Context: #{excerpt(cand.context)}" unless cand.context.empty?
+  end
+
+  # A one-paragraph excerpt of a section, for scannable evidence.
+  def excerpt(text, limit: 280)
+    flat = text.to_s.gsub(/\s+/, " ").strip
+    flat.length > limit ? "#{flat[0, limit]}..." : flat
+  end
+
+  def do_record(tool, opts, out: $stdout)
+    if opts[:edge].nil? || !%i[sources chain].include?(opts[:edge])
+      out.puts "link-suggest: --record requires --edge sources|chain (explicit, never inferred)."
+      return 1
+    end
+    if opts[:edge] == :chain && (opts[:rating].nil? || !LinkSuggestions::RATINGS.include?(opts[:rating]))
+      out.puts "link-suggest: --rating high|medium|low is required for a chain edge."
+      return 1
+    end
+
+    unless opts[:confirm]
+      out.puts "Would record #{opts[:edge]} edge #{opts[:subject]} -> #{opts[:record]} " \
+               "(rating #{opts[:rating] || "-"}, reason: #{opts[:reason] || "-"}). " \
+               "Re-run with --confirm to write. Nothing written."
+      return 0
+    end
+
+    wrote = tool.record_edge(opts[:subject], opts[:record],
+                             edge: opts[:edge], rating: opts[:rating],
+                             reason: opts[:reason], confirm: true)
+    if wrote
+      out.puts "Recorded #{opts[:edge]} edge #{opts[:subject]} -> #{opts[:record]} " \
+               "and appended to link-decisions.md. Reproject with scripts/project-links."
+      return 0
+    end
+    out.puts "No edge written (edge may already exist, or intent missing)."
+    0
+  end
+
+  def run(argv, out: $stdout)
+    opts = parse(argv)
+    if opts[:help]
+      out.puts USAGE
+      return 0
+    end
+    unless opts[:subject]
+      out.puts USAGE
+      return 1
+    end
+
+    tool = LinkSuggestions.new(store_dir: opts[:store_dir], finder: build_finder(opts[:store_dir]))
+
+    return do_record(tool, opts, out: out) if opts[:record]
+
+    report(tool, opts[:subject], out: out)
+  end
+
+  # The real candidate-finder, wired here (not in the lib): use QMD when available,
+  # else fall back to the lib's cheap family/tag/adjacent net. Discovery only.
+  def build_finder(store_dir)
+    qmd = qmd_finder(store_dir)
+    qmd || LinkSuggestions::FamilyTagFinder.new
+  end
+
+  # A QMD-backed finder when the `qmd` (or qmd-sync) CLI is on PATH. It seeds discovery
+  # from the subject's intent line, unions the hits with the cheap fallback net, and
+  # returns ids present in the store. Any failure falls back silently. Discovery only,
+  # never a grade.
+  def qmd_finder(_store_dir)
+    return nil unless qmd_available?
+
+    fallback = LinkSuggestions::FamilyTagFinder.new
+    lambda do |subject_id, nodes|
+      base = fallback.call(subject_id, nodes)
+      subject = nodes[subject_id]
+      return base unless subject
+
+      hits = qmd_search_ids(subject[:label], nodes)
+      (base + hits).uniq.reject { |id| id == subject_id }
+    end
+  end
+
+  def qmd_available?
+    %w[qmd qmd-sync].any? { |c| system("command -v #{c} >/dev/null 2>&1") }
+  rescue StandardError
+    false
+  end
+
+  # Best-effort: ask qmd-sync for related text and map any id-shaped tokens back to
+  # store ids. Never raises; returns [] on any trouble.
+  def qmd_search_ids(query, nodes)
+    return [] if query.to_s.strip.empty?
+
+    out = `ruby #{File.join(Dir.home, ".plastic", "scripts", "qmd-sync")} search #{shell_quote(query)} 2>/dev/null`
+    return [] if out.nil? || out.empty?
+
+    out.scan(/\b([0-9]+[a-z0-9]*)\b/).flatten.uniq.select { |id| nodes.key?(id) }
+  rescue StandardError
+    []
+  end
+
+  def shell_quote(str)
+    "'#{str.to_s.gsub("'", "'\\\\''")}'"
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  exit LinkSuggestCLI.run(ARGV)
+end