samagotchi 0.3.0 → 0.5.0

data/lib/samagotchi/bundles/skills/plugin.rb

@@ -0,0 +1,419 @@
+# The skills bundle (docs/plugins.md, The skills bundle): a skill is a memory
+# named skill_<name> that holds the steps of a task done with the user
+# (docs/memory.md, Skills). The system bundle's identity already tells the
+# model to save, follow and update skills; this bundle adds `/skill` for the
+# user and keeps an eye on the model's rewrites.
+#
+# History: before memory_write, write or edit changes a skill's file, the
+# file as it was is kept under $XDG_STATE_HOME/samagotchi/plugins/skills/
+# history/<scope>/<name>/<UTC time>.md (state, not the memories dir, so
+# bundle build and dotfile syncs never see it), history_keep per skill. The
+# after_tool_call of that call (calls run one at a time; that event carries
+# no call, so the before side stashes it) compares the file on disk and
+# shows a line: "skill release updated (+2 −1): …" or "skill release saved
+# (project, 14 lines)".
+#
+# The nudge (nudge: true), for models that skip a failing step instead of
+# fixing the skill: in a turn that read a skill (memory_read of a skill_*
+# name, or a read of its file), the first failing tool call after it (an
+# execute with "exit: N", N ≠ 0, or with no exit line an Error: line near
+# the top; any tool's "[tool] Error: …") steers the model once to find out
+# why and fix the skill. At the turn's end, a failed step with no rewrite of
+# the skill gets a notice line.
+#
+# Settings (config.yml, bundles: skills:):
+#   history_keep: 20   older versions kept per skill
+#   nudge: true        steer the model once when a skill's step fails
+require "date"
+require "fileutils"
+
+class Plugin
+  WRITE_TOOLS = %w[memory_write write edit].freeze
+  NOTICE_WIDTH = 60 # the changed line in an update's notice
+  NUDGE = "A step of skill %s failed. Find out why before skipping it; if the skill is out of date, fix it now: " \
+          "memory_write the whole skill, its title and every section as they were, that step fixed, a Changelog " \
+          "line added."
+  NOT_FAILURES = %w[memory_read memory_write].freeze
+  USAGE = "usage: /skill save [name] [--system] | list | show <name> | diff <name> [N]"
+
+  def initialize(settings = {})
+    settings = {} unless settings.is_a?(Hash)
+    @history_keep = positive(settings["history_keep"]) || 20
+    @nudge = settings.key?("nudge") ? settings["nudge"] != false : true
+    @stash = nil
+    reset_turn
+  end
+
+  def register(chi)
+    chi.on(:before_turn) { |_event, _ctx| reset_turn }
+    chi.on(:after_turn) { |_event, ctx| after_turn(ctx) }
+    chi.on(:before_tool_call) { |event, ctx| before_tool_call(event, ctx) }
+    chi.on(:after_tool_call) { |event, ctx| after_tool_call(event, ctx) }
+    chi.command "/skill", "skills (steps of a task we did): save [name] [--system], list, show <name>, diff <name> [N]",
+                anytime: true do |args, ctx|
+      command(args.to_s.strip, ctx)
+    end
+  end
+
+  private
+
+  # --- a skill's file changes ----------------------------------------------
+
+  def before_tool_call(event, ctx)
+    @stash = nil
+    tool = event.dig(:call, :name).to_s
+    note_read(tool, event)
+    return unless WRITE_TOOLS.include?(tool)
+
+    path = Array(event.dig(:targets, :paths)).find { |target| skill_at(target) }
+    return unless path
+
+    scope, name = skill_at(path)
+    old = File.file?(path) ? File.read(path) : nil
+    keep_version(ctx, scope, name, old) if old
+    @stash = { tool: tool, path: File.expand_path(path), scope: scope, name: name, old: old }
+  end
+
+  # Success is the file changed on disk, whatever the output says. A call
+  # that didn't match the stash (a cancelled turn fires no before) drops it.
+  def after_tool_call(event, ctx)
+    stash = @stash
+    @stash = nil
+    step_failed(event) if @nudge && !@read.empty?
+    return unless stash && stash[:tool] == event[:tool].to_s
+
+    now = File.file?(stash[:path]) ? File.read(stash[:path]) : nil
+    return if now.nil? || now == stash[:old]
+
+    @written << stash[:name]
+    ctx.notify(change_notice(stash, now))
+  end
+
+  def change_notice(stash, now)
+    name = stash[:name]
+    return "skill #{name} saved (#{stash[:scope]}, #{now.lines.size} lines)" unless stash[:old]
+
+    ops = line_diff(stash[:old].lines(chomp: true), now.lines(chomp: true))
+    added = ops.count { |op, _| op == :add }
+    removed = ops.count { |op, _| op == :del }
+    first = ops.find { |op, _| op == :add } || ops.find { |op, _| op == :del }
+    line = first ? cut(first.last.strip) : ""
+    "skill #{name} updated (+#{added} −#{removed})#{line.empty? ? "" : ": #{line}"} · /skill diff #{name}"
+  end
+
+  # --- the nudge ------------------------------------------------------------
+
+  def reset_turn
+    @read = []      # skills read this turn, in order
+    @written = []   # skills changed this turn
+    @failed = false # a step failed after a skill was read
+    @nudged = false
+  end
+
+  def note_read(tool, event)
+    names = case tool
+            when "memory_read"
+              event.dig(:call, :content).to_s.split(",").map(&:strip).select { |entry| entry.start_with?("skill_") }
+                   .filter_map { |entry| skill_name(entry) }
+            when "read"
+              Array(event.dig(:targets, :paths)).filter_map { |path| skill_at(path)&.last }
+            else []
+            end
+    @read |= names
+  end
+
+  def step_failed(event)
+    tool = event[:tool].to_s
+    return if NOT_FAILURES.include?(tool) || !failure?(tool, event[:output].to_s)
+
+    @failed = true
+    return if @nudged
+
+    @nudged = !!event[:steer]&.call(format(NUDGE, @read.join(", ")))
+  end
+
+  # A tool error ("[x] Error: …" raised, "[x]\nError: …" returned), or an
+  # execute that exited non-zero; its "exit: N" line may be cut off by the
+  # hook's output cap, and then an Error: line near the top counts.
+  def failure?(tool, output)
+    return true if output.match?(/\A\[#{Regexp.escape(tool)}\](?: |\n)Error:/)
+    return false unless tool == "execute"
+
+    exit_line = output.match(/^exit: (\d+)(?: \(no output\))?\s*\z/)
+    return exit_line[1] != "0" if exit_line
+
+    output.lines.first(20).any? { |line| line.match?(/\A\s*Error:/i) }
+  end
+
+  def after_turn(ctx)
+    return unless @nudge && @failed
+
+    missed = @read - @written
+    return unless missed.size == @read.size
+
+    ctx.notify("skill #{missed.join(", ")} was followed, a step failed, the skill wasn't updated")
+  end
+
+  # --- history ---------------------------------------------------------------
+
+  # Keep +content+ as the newest version, unless it is the newest already (a
+  # denied or failed write leaves the file as it was).
+  def keep_version(ctx, scope, name, content)
+    dir = history_dir(ctx, scope, name)
+    FileUtils.mkdir_p(dir)
+    newest = versions(dir).first
+    return if newest && File.read(newest) == content
+
+    stamp = Time.now.utc.strftime("%Y%m%dT%H%M%S.%6NZ")
+    path = File.join(dir, "#{stamp}.md")
+    File.write("#{path}.tmp", content)
+    File.rename("#{path}.tmp", path)
+    versions(dir).drop(@history_keep).each { |old| File.delete(old) }
+  rescue SystemCallError => e
+    ctx.log.warn(:history_failed, skill: name, error: e.class.name, msg: e.message)
+  end
+
+  # history/system/<name>, history/project-<project folder>/<name>
+  def history_dir(ctx, scope, name)
+    key = scope == "system" ? "system" : "project-#{File.basename(memory_dirs["project"])}"
+    File.join(ctx.data_dir, "history", key, name)
+  end
+
+  # The kept versions, newest first.
+  def versions(dir) = Dir.glob(File.join(dir, "*.md")).sort.reverse
+
+  # --- /skill ----------------------------------------------------------------
+
+  def command(args, ctx)
+    verb, rest = args.split(/\s+/, 2)
+    rest = rest.to_s.strip
+    case verb
+    when "save" then save(rest, ctx)
+    when "list" then rest.empty? ? list : USAGE
+    when "show" then show(rest)
+    when "diff" then diff(rest, ctx)
+    else USAGE
+    end
+  end
+
+  # /skill save [name] [--system]: asks the model, in this session, to save
+  # what was just done (the model has seen the commands; a side answer
+  # wouldn't). The request runs as a turn; sent while a turn runs it joins
+  # that turn at its next step, and the request says to finish the task
+  # first. A REPL session (--no-shared) takes no messages: the request is
+  # shown for the user to send.
+  def save(rest, ctx)
+    words = rest.split
+    scope = words.delete("--system") ? "system" : "project"
+    return USAGE if words.size > 1 || words.any? { |word| word.start_with?("-") }
+
+    name = words.first && skill_name(words.first)
+    return "/skill save: a name is letters, digits, _ and - (got #{words.first})" if words.first && !name
+
+    request = save_request(name, scope, exists: name && skill_path(name))
+    begin
+      ctx.sessions.send(ctx.session_id, request)
+    rescue Samagotchi::Plugin::Sessions::Error => e
+      return "/skill save: #{e.message}. Send this yourself:\n\n#{request}"
+    end
+    what = name ? "skill #{name}" : "a skill"
+    "asked chi to save #{what} (#{scope} scope); a running turn gets it at its next step"
+  end
+
+  def save_request(name, scope, exists:)
+    target = name ? "skill `skill_#{name}`" : "a skill named `skill_<name>` (a short name for the task)"
+    update = exists ? " It exists already: read it, keep what still holds, fix what changed, add a Changelog line." : ""
+    <<~TEXT.strip
+      Save what we just did as #{target} with memory_write, scope #{scope}.#{update} If you are still in the middle of the task, finish it first.
+      Content: plain Markdown, no frontmatter:
+
+      # Skill: #{name || "<name>"}
+
+      ## Steps
+      1. …
+      ## Gotchas
+      - …
+      ## Changelog
+      - #{Date.today.iso8601} created
+
+      Steps are the commands and checks that worked, in order, with the real file and command names; a step that must pass says "stop if it fails". Dead ends and surprises go under Gotchas. Give memory_write a description: one line that starts with what this task is and names its main steps, in this task's own words, so the skill is found next time. Then show the skill briefly.
+    TEXT
+  end
+
+  # /skill list: the skill_* memories of both scopes, with their index line's
+  # date and description.
+  def list
+    skills = memory_dirs.flat_map do |scope, dir|
+      index = index_lines(dir)
+      Dir.glob(File.join(dir, "skill_*.md")).filter_map do |path|
+        name = File.basename(path, ".md").delete_prefix("skill_")
+        next unless skill_name(name) == name
+
+        date, description = index.fetch("skill_#{name}", [nil, nil])
+        line = +"#{name} · #{scope}"
+        line << " · #{date}" if date
+        line << " — #{description}" if description
+        line
+      end.sort
+    end
+    return "no skills yet: after a task we did together, /skill save [name]" if skills.empty?
+
+    "skills:\n#{skills.map { |line| "  #{line}" }.join("\n")}"
+  end
+
+  # /skill show <name>: the skill as saved (project first).
+  def show(rest)
+    name = skill_name(rest)
+    return USAGE unless name
+
+    path = skill_path(name) or return "no skill #{name} (/skill list shows them)"
+    "skill #{name} · #{scope_of(path)}\n\n#{File.read(path).strip}"
+  end
+
+  # /skill diff <name> [N]: the skill now against its N-th newest kept
+  # version (1, the one before the last change, by default), unified.
+  def diff(rest, ctx)
+    word, back = rest.split
+    name = skill_name(word)
+    n = back ? Integer(back, exception: false) : 1
+    return USAGE unless name && n&.positive? && rest.split.size <= 2
+
+    path = skill_path(name) or return "no skill #{name} (/skill list shows them)"
+    kept = versions(history_dir(ctx, scope_of(path), name))
+    return "skill #{name} has no older version yet" if kept.empty?
+    return "skill #{name} has #{kept.size} older version#{"s" if kept.size > 1} (/skill diff #{name} 1..#{kept.size})" if n > kept.size
+
+    old = kept[n - 1]
+    body = unified(File.read(old).lines(chomp: true), File.read(path).lines(chomp: true))
+    return "skill #{name} is the same as version #{n}" if body.empty?
+
+    "--- skill_#{name} (#{version_time(old)})\n+++ skill_#{name} (now)\n#{body}"
+  end
+
+  CONTEXT = 3
+
+  # Hunks with CONTEXT lines around each change, as diff -u prints them.
+  def unified(a, b)
+    ops = line_diff(a, b)
+    changed = ops.each_index.reject { |k| ops[k].first == :eq }
+    return "" if changed.empty?
+
+    # Group changes whose context would touch into one hunk.
+    groups = changed.slice_when { |x, y| y - x > 2 * CONTEXT + 1 }.to_a
+    old_at = new_at = 0
+    positions = ops.map do |op, _|
+      at = [old_at, new_at]
+      old_at += 1 unless op == :add
+      new_at += 1 unless op == :del
+      at
+    end
+    groups.map do |group|
+      from = [group.first - CONTEXT, 0].max
+      to = [group.last + CONTEXT, ops.size - 1].min
+      slice = ops[from..to]
+      old_count = slice.count { |op, _| op != :add }
+      new_count = slice.count { |op, _| op != :del }
+      old_start, new_start = positions[from]
+      header = "@@ -#{range(old_start, old_count)} +#{range(new_start, new_count)} @@"
+      lines = slice.map { |op, line| "#{{ eq: " ", del: "-", add: "+" }[op]}#{line}" }
+      [header, *lines].join("\n")
+    end.join("\n")
+  end
+
+  # diff -u's "start,count" (1-based; an empty side names the line before).
+  def range(start, count)
+    first = count.zero? ? start : start + 1
+    count == 1 ? first.to_s : "#{first},#{count}"
+  end
+
+  # "2026-09-30 10:22 UTC" from a version's file name.
+  def version_time(path)
+    stamp = File.basename(path, ".md")
+    match = stamp.match(/\A(\d{4})(\d\d)(\d\d)T(\d\d)(\d\d)/)
+    match ? "#{match[1]}-#{match[2]}-#{match[3]} #{match[4]}:#{match[5]} UTC" : stamp
+  end
+
+  # --- skills on disk --------------------------------------------------------
+
+  # "release", "skill_release", "Release-Notes" → "release", "release-notes";
+  # nil for anything else.
+  def skill_name(word)
+    name = word.to_s.downcase.delete_suffix(".md").delete_prefix("skill_")
+    name.match?(/\A[a-z0-9][a-z0-9_-]*\z/) ? name : nil
+  end
+
+  # The memories dir of each scope, as memory_read/memory_write resolve it.
+  def memory_dirs
+    %w[project system].to_h { |scope| [scope, File.expand_path(Samagotchi::Tools::MemoryRead.memories_dir(scope))] }
+  end
+
+  # The skill's file, project first (as memory_read looks), or nil.
+  def skill_path(name, scope: nil)
+    dirs = scope ? memory_dirs.slice(scope) : memory_dirs
+    dirs.each_value do |dir|
+      path = File.join(dir, "skill_#{name}.md")
+      return path if File.file?(path)
+    end
+    nil
+  end
+
+  # [scope, name] when +path+ is a skill_<name>.md right in a memories dir.
+  def skill_at(path)
+    path = File.expand_path(path.to_s)
+    scope = memory_dirs.key(File.dirname(path))
+    name = File.basename(path, ".md").delete_prefix("skill_")
+    return nil unless scope && File.basename(path) == "skill_#{name}.md" && skill_name(name) == name
+
+    [scope, name]
+  end
+
+  def scope_of(path) = memory_dirs.key(File.dirname(path)) || "?"
+
+  # The managed index.md lines, {name => [date, description]}:
+  # "- **name** · scope · date · bytes — description".
+  def index_lines(dir)
+    path = File.join(dir, "index.md")
+    return {} unless File.file?(path)
+
+    File.readlines(path, chomp: true).each_with_object({}) do |line, lines|
+      match = line.match(/\A- \*\*(?<name>[^*]+)\*\* · [^·]+ · (?<date>[^·]+?) · [^—]+?(?: — (?<description>.+))?\z/)
+      lines[match[:name]] = [match[:date].strip, match[:description]&.strip] if match
+    end
+  end
+
+  # --- helpers ---------------------------------------------------------------
+
+  # The lines of +a+ and +b+ as [:eq|:del|:add, line], in order (a longest
+  # common subsequence; skills are short).
+  def line_diff(a, b)
+    lcs = Array.new(a.size + 1) { Array.new(b.size + 1, 0) }
+    (a.size - 1).downto(0) do |i|
+      (b.size - 1).downto(0) do |j|
+        lcs[i][j] = a[i] == b[j] ? lcs[i + 1][j + 1] + 1 : [lcs[i + 1][j], lcs[i][j + 1]].max
+      end
+    end
+    ops = []
+    i = j = 0
+    while i < a.size && j < b.size
+      if a[i] == b[j]
+        ops << [:eq, a[i]]
+        i += 1
+        j += 1
+      elsif lcs[i + 1][j] >= lcs[i][j + 1]
+        ops << [:del, a[i]]
+        i += 1
+      else
+        ops << [:add, b[j]]
+        j += 1
+      end
+    end
+    ops.concat(a[i..].map { |line| [:del, line] }, b[j..].map { |line| [:add, line] })
+  end
+
+  def cut(text) = text.length > NOTICE_WIDTH ? "#{text[0, NOTICE_WIDTH - 1]}…" : text
+
+  def positive(value)
+    number = Integer(value.to_s, exception: false)
+    number&.positive? ? number : nil
+  end
+end

data/lib/samagotchi/bundles/source-links/hooks/source_links.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Loaded through module_eval: it requires what it uses.
+require "open3"
+
 # An after_turn hook that links the source refs the model's answer
 # mentions — a JIRA ticket, a GitHub issue, an internal wiki page. In the
 # web, each ref in the answer becomes a link (`[JIRA-123](https://…)`,
@@ -22,10 +25,24 @@
 #           pattern: '\bGH-(\d+)\b'   # full form: a regex
 #           url: 'https://github.com/org/repo/issues/{match}'
 #           case_insensitive: false   # optional, default false
+#         - name: Issues              # `#12` → this project's repo,
+#                                     # `owner/repo#12` → that repo
+#           pattern: '(?<![\w/&])(?:(?<repo>[A-Za-z0-9][\w-]*/[\w.-]*\w))?#(?<num>\d+)\b'
+#           url: 'https://github.com/{repo}/issues/{num}'
+#           remote: origin            # optional: the git remote {repo}/{host}
+#                                     # come from, default origin
+#           remote_host: github.com   # optional: a host or a list; else a
+#                                     # remote on another host links nothing
 #       max: 10                       # optional: refs per line, default 10
 #       note: false                   # optional: no sources line (the web
 #                                     # links stay), default true
 #
+# A `url:` template takes {match} (group 1, else the whole ref), {1}…{9}
+# (numbered groups), {name} (named groups), and {repo}/{host}: the named
+# group when it took part, else the project's (Dir.pwd's) git remote, asked
+# of git once per worker. A ref with a placeholder that can't be filled is
+# not linked; a `{word}` that is none of these stays text (warned at load).
+#
 # The note is not stored in the conversation: it is an event, replayed by a
 # UI only while the session's worker lives (a reload keeps it; a stopped
 # worker loses it). The links are stored as the answer's display. A ref in
@@ -47,6 +64,32 @@ class SourceLinks
   MARKDOWN_LINK = /\[([^\]]*)\]\(([^)]*)\)/
   # A fenced code block's opening line (up to 3 spaces, then ``` or ~~~).
   FENCE_OPEN = /\A {0,3}(`{3,}|~{3,})/
+  # A `{word}` or `{N}` placeholder in a `url:` template.
+  PLACEHOLDER = /\{(\w+)\}/
+  # Placeholders every pattern has: {match} (group 1, else the whole ref),
+  # and {repo}/{host} (a named group, else the project's git remote).
+  BUILTIN_PLACEHOLDERS = %w[match repo host].freeze
+  # `git remote get-url` output: a URL with a scheme, `[user[:pw]@]host[:port]/path`.
+  REMOTE_URL = %r{\A(?:https?|ssh|git)://(?:[^/]*@)?(\[[^\]]*\]|[^/:@]+)(?::[^/]*)?(/.*)?\z}i
+  # scp-like `[user@]host:path`: a colon before any slash; a leading `/` or
+  # `.` is a local path.
+  REMOTE_SCP = %r{\A(?:[^@/:]+@)?([^/:.@][^/:@]*):(.*)\z}
+
+  # The {host:, repo:} a git remote URL names, or nil (a local path,
+  # `file://`, an empty path, or a path with an empty or dot segment).
+  def self.parse_remote_url(url)
+    url = url.to_s.strip
+    # Any other scheme (file://, a transport helper's) is not a web host.
+    match = url.include?("://") ? url.match(REMOTE_URL) : url.match(REMOTE_SCP)
+    return nil unless match
+
+    host = match[1]
+    repo = match[2].to_s.sub(%r{\A/+}, "").sub(%r{/+\z}, "").sub(/\.git\z/, "").sub(%r{/+\z}, "")
+    segments = repo.split("/", -1)
+    return nil if host.empty? || segments.empty? || segments.any? { |segment| ["", ".", ".."].include?(segment) }
+
+    { host: host, repo: repo }
+  end
 
   def initialize(settings = {})
     settings = {} unless settings.is_a?(Hash)
@@ -54,6 +97,9 @@ class SourceLinks
     max = settings["max"].to_i
     @max = max.positive? ? max : DEFAULT_MAX
     @note = settings["note"] != false
+    # [Dir.pwd, remote name] => {host:, repo:} or nil, for the worker's life.
+    @remotes = {}
+    @host_mismatch_logged = {}
   end
 
   def call(event)
@@ -115,9 +161,12 @@ class SourceLinks
           next if inside_markdown_link?(links, text, match)
           next if url_adjacent?(text, match)
 
+          # An unresolved placeholder: no link, from this source.
+          url = source[:url].call(match[0], match)
+          next if url.nil?
+
           quiet = inside_any?(code, start, finish) || inside_any?(labels, start, finish)
-          hits << { start: start, finish: finish, name: source[:name], ref: match[0],
-                    url: source[:url].call(match[0], match), quiet: quiet }
+          hits << { start: start, finish: finish, name: source[:name], ref: match[0], url: url, quiet: quiet }
         end
       rescue Regexp::TimeoutError
         Samagotchi::Log.warn(:hooks, "source_links_timeout",
@@ -131,11 +180,12 @@ class SourceLinks
   end
 
   # [name, ref, url] for the note: first-occurrence order, deduped by the
-  # ref text case-insensitively.
+  # URL case-insensitively (`#12` and `o/r#12` may name one issue; with
+  # case_insensitive, `JIRA-1` and `jira-1` are one ticket).
   def collect(hits)
     seen = {}
     hits.filter_map do |hit|
-      key = hit[:ref].downcase
+      key = hit[:url].downcase
       next if seen.key?(key)
 
       seen[key] = true
@@ -336,7 +386,12 @@ class SourceLinks
       name = "source" if name.empty?
       regex = Regexp.new(pattern, flags, timeout: REGEX_TIMEOUT)
       template = entry["url"].to_s
-      { name: name, regex: regex, url: ->(ref, match) { template.gsub("{match}", escape_url(match[1] || ref)) } }
+      known = known_placeholders(name, template, regex)
+      remote = entry["remote"].to_s.strip
+      remote = "origin" if remote.empty?
+      hosts = Array(entry["remote_host"]).map { |host| host.to_s.strip.downcase }.reject(&:empty?)
+      source = { name: name, remote: remote, remote_hosts: hosts }
+      source.merge(regex: regex, url: ->(ref, match) { render_url(template, known, match, ref, source) })
     else
       warn_invalid("a source needs a prefix: or a pattern:")
       nil
@@ -346,6 +401,124 @@ class SourceLinks
     nil
   end
 
+  # The placeholders of +template+ this pattern can fill: {match}, {repo},
+  # {host}, its named groups and {1}…{N} for its N groups. Any other
+  # `{word}` stays as text, with one warning here, at compile time.
+  def known_placeholders(name, template, regex)
+    used = template.scan(PLACEHOLDER).flatten.uniq
+    groups = group_count(regex)
+    known, unknown = used.partition do |word|
+      if word.match?(/\A\d+\z/)
+        groups.nil? || (word.to_i.between?(1, groups))
+      else
+        BUILTIN_PLACEHOLDERS.include?(word) || regex.names.include?(word)
+      end
+    end
+    unless unknown.empty?
+      list = unknown.map { |word| "{#{word}}" }.join(", ")
+      Samagotchi::Log.warn(:hooks, "source_links_unknown_placeholder",
+                           echo: "[samagotchi:hooks] source-links: #{name}: #{list}: no such group in its pattern; " \
+                                 "left as text")
+    end
+    known
+  end
+
+  # How many groups +regex+ captures (with named groups, only those), found
+  # by matching an always-empty alternative; nil when that fails.
+  def group_count(regex)
+    probe = Regexp.new("(?:#{regex.source}\n)|", regex.options, timeout: REGEX_TIMEOUT)
+    probe.match("").size - 1
+  rescue RegexpError, Regexp::TimeoutError
+    nil
+  end
+
+  # The URL for one hit: +template+ with its +known+ placeholders filled, or
+  # nil when one can't be (a group that didn't take part, a {repo} with an
+  # empty or dot segment, no remote): we never build a URL with a hole.
+  def render_url(template, known, match, ref, source)
+    unresolved = false
+    url = template.gsub(PLACEHOLDER) do
+      word = Regexp.last_match(1)
+      next Regexp.last_match(0) unless known.include?(word)
+
+      value = placeholder_value(word, match, ref, source)
+      unresolved = true if value.nil?
+      value.to_s
+    end
+    unresolved ? nil : url
+  end
+
+  # One placeholder's escaped value, or nil when it is unresolved.
+  def placeholder_value(word, match, ref, source)
+    case word
+    when "match" then escape_url(match[1] || ref)
+    when /\A\d+\z/ then match[word.to_i]&.then { |value| escape_url(value) }
+    when "repo", "host"
+      value = match.names.include?(word) ? match[word] : nil
+      value ||= remote_value(word, source)
+      word == "repo" ? escape_repo(value) : value&.then { |host| escape_url(host) }
+    else match[word]&.then { |value| escape_url(value) }
+    end
+  end
+
+  # {repo} / {host} from the project's git remote (the source's `remote:`,
+  # default origin); nil when there is none, or when its host is not one of
+  # the source's `remote_host:` list.
+  def remote_value(word, source)
+    remote = project_remote(source[:remote])
+    return nil unless remote
+
+    hosts = source[:remote_hosts]
+    unless hosts.empty? || hosts.include?(remote[:host].downcase)
+      key = [source[:name], remote[:host]]
+      unless @host_mismatch_logged[key]
+        @host_mismatch_logged[key] = true
+        Samagotchi::Log.debug(:hooks, "source_links_remote_host_mismatch", source: source[:name],
+                                                                          host: remote[:host], remote_host: hosts.join(","))
+      end
+      return nil
+    end
+    remote[word.to_sym]
+  end
+
+  # The project's (Dir.pwd's) remote +name+ as {host:, repo:}, or nil.
+  # Asked of git lazily (only a hit that needs it) and remembered, nil too,
+  # per [Dir.pwd, name]: git applies insteadOf rewrites and includes, and a
+  # worktree reports its main repo's remote.
+  def project_remote(name)
+    key = [Dir.pwd, name]
+    return @remotes[key] if @remotes.key?(key)
+
+    @remotes[key] = read_remote(key[0], name)
+  end
+
+  def read_remote(dir, name)
+    out, status = Open3.capture2({ "GIT_DIR" => nil, "GIT_WORK_TREE" => nil },
+                                 "git", "-C", dir, "remote", "get-url", name, err: File::NULL)
+    unless status.success?
+      Samagotchi::Log.debug(:hooks, "source_links_no_remote", remote: name, exit: status.exitstatus)
+      return nil
+    end
+    remote = self.class.parse_remote_url(out)
+    Samagotchi::Log.debug(:hooks, "source_links_remote", remote: name, host: remote&.dig(:host), repo: remote&.dig(:repo))
+    remote
+  rescue SystemCallError => e
+    Samagotchi::Log.debug(:hooks, "source_links_no_remote", remote: name, error: e.class.name)
+    nil
+  end
+
+  # A repo path with each `/`-separated segment escaped and the `/` kept
+  # (GitLab's `group/sub/proj`); nil for an empty, `.` or `..` segment, which
+  # a browser would resolve out of the path.
+  def escape_repo(value)
+    return nil if value.nil?
+
+    segments = value.split("/", -1)
+    return nil if segments.empty? || segments.any? { |segment| ["", ".", ".."].include?(segment) }
+
+    segments.map { |segment| escape_url(segment) }.join("/")
+  end
+
   def warn_invalid(reason)
     Samagotchi::Log.warn(:hooks, "source_links_invalid_source",
                          echo: "[samagotchi:hooks] source-links: skipping a source: #{reason}")

data/lib/samagotchi/bundles/source-links/manifest.yml

@@ -1,14 +1,14 @@
 ---
 name: source-links
-version: 0.2.0
+version: 0.3.0
 scope: system
 description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
 files:
-  source_links.md: sha256:0fb30311603c60f062740917ad0670904e022e8975b1d0eafe3df9e2904f2fe0
+  source_links.md: sha256:aebd37f1e25491780994ecc4afc20ed6e8db32b724dc038302bb050177efada8
 hooks:
   source_links.rb:
-    sha256: sha256:5f2b8d5248efc7e0a98185d9e53a47e6a3edfe7c43ee5bf0ebe44d07f18d61aa
+    sha256: sha256:0ee86a932efc90d81777855c81dea16510710d7371fe8b6b146a5a16b29794c2
     event: after_turn
     on_error: log
     priority: 90

data/lib/samagotchi/bundles/source-links/source_links.md

@@ -2,4 +2,4 @@
 
 The `source-links` bundle's `after_turn` hook links the source refs (a JIRA ticket, a GitHub issue, …) in your answers. In the web, each ref in the answer becomes a link; that is how the answer is **shown**, not what you wrote: your own message keeps the plain ref. A `sources: NAME ref → url, …` line right after an answer is the same hook's note, which every UI shows (the terminals only see this line). The line is **not part of the conversation**: it is an event, so it is not in the session file and you cannot refer back to it. A UI replays it while the session's worker lives (a page reload keeps it; a stopped worker loses it).
 
-The refs come from the `bundles: source-links:` section of config.yml: each source is a `prefix:` + `base_url:` pair (simple) or a `pattern:` regex + `url:` template (full form), plus an optional `max:` for refs per line and `note: false` to drop the line (the web links stay). With no sources configured the hook does nothing. A ref already inside a URL is not linked again, and a ref in code or in a markdown link is not linked in the answer.
+The refs come from the `bundles: source-links:` section of config.yml: each source is a `prefix:` + `base_url:` pair (simple) or a `pattern:` regex + `url:` template (full form), plus an optional `max:` for refs per line and `note: false` to drop the line (the web links stay). A `url:` template can take the project's own repo from its git remote, so a bare `#12` links to this project's issue and `owner/repo#12` to that repo's. With no sources configured the hook does nothing. A ref already inside a URL is not linked again, and a ref in code or in a markdown link is not linked in the answer.