acstack 0.49.0 → 0.49.2

package/assets/terminal-workspace/helpers/acstack-md-lib

@@ -0,0 +1,219 @@
+# A preview pane cannot page, so the same render goes straight to stdout.
+emit() {
+local f="$1" nk rc; shift
+if [ "$PREVIEW" = "1" ]; then cat "$f"; return; fi
+# The binding is a less feature, so only less is handed it. Setting
+# LESSKEYIN for a pager that never reads it is at best noise, and acting on
+# an exit status that pager chose for its own reasons is a bug waiting.
+case "${1:-}" in
+  less|*/less)
+    # b is back-a-page in less. ^B and PageUp both still do that, so this
+    # costs nothing (measured). LESSKEYIN wants less 582 or newer; older
+    # versions ignore it and quietly keep b as it was.
+    #
+    # lesskey reads a line starting with # as a comment, so the key that
+    # means line numbers has to be escaped or the binding is silently
+    # dropped and the key does nothing but ring the bell - measured on less
+    # 590, and how this arrived as a bug report. Only a leading # needs it:
+    # backslash means something of its own to lesskey, and \b would bind
+    # backspace rather than the letter.
+    case "$NUMBER_KEY" in
+      '#'*) nk="\\$NUMBER_KEY" ;;
+      *)    nk="$NUMBER_KEY" ;;
+    esac
+    { printf '#command\n'
+      printf '%s quit A\n' "$BROWSE_KEY"
+      printf '%s quit B\n' "$nk"
+    } > "$KEYS"
+    LESSKEYIN="$KEYS" "$@" "$f"
+    rc=$?
+    if [ "$rc" = "$BROWSE_STATUS" ]; then
+      "$0" --browser "$FILE"
+      exit $?
+    fi
+    if [ "$rc" = "$NUMBER_STATUS" ]; then
+      # One key, both directions: the view you are not in is the one it
+      # takes you to. $FILE is the markdown throughout, never the rendered
+      # temp copy, so either re-read starts from the source again.
+      if [ "$NUMBERED" = "1" ]; then "$0" "$FILE"; else "$0" --numbered "$FILE"; fi
+      exit $?
+    fi
+    ;;
+  *) "$@" "$f" ;;
+esac
+}
+
+# A wide diagram left a marker behind rather than art glow would wrap. Turn
+# the marker into a line a person can read and put the drawing back under it.
+# Both output paths run this: without it the marker reaches the reader raw.
+splice() {
+ACSTACK_PID=$$ ACSTACK_PREVIEW="$PREVIEW" python3 - "$1" <<'PY'
+import os, pathlib, re, sys
+f = pathlib.Path(sys.argv[1])
+pid = os.environ["ACSTACK_PID"]
+preview = os.environ.get("ACSTACK_PREVIEW") == "1"
+lines = []
+for line in f.read_text().split("\n"):
+  m = re.search(r"\x00ACSTACKART(\d+)\x00", line)
+  if not m:
+      lines.append(line); continue
+  art = pathlib.Path(f"/tmp/acstack-md-art.{pid}.{m.group(1)}")
+  lines.append(re.sub(r"\x00ACSTACKART\d+\x00", f"Diagram {m.group(1)}:", line))
+  if art.exists():
+      # Art too wide for the pane would spill past it, so a preview pane
+      # keeps the placeholder and leaves the drawing to a full-width read.
+      if not preview:
+          lines.extend("  " + l for l in art.read_text().splitlines())
+      art.unlink()
+f.write_text("\n".join(lines) + "\n")
+PY
+}
+
+# Rendered markdown has no line numbers, and a reader who wants to quote a
+# line back in a review needs the file's own. The gutter is as wide as the
+# largest number in it, so the source stays on one column whatever the length.
+numbered() {  # numbered <file> -> stdout
+local total width avail
+total=$(awk 'END { print NR }' "$1")
+width=${#total}
+[ "$width" -lt 3 ] && width=3
+if [ "$PREVIEW" = "1" ]; then
+  # A wrapped line makes the gutter lie about which source line you are
+  # looking at, and a pane has no arrow keys to pan with, so it chops.
+  avail=$((COLS - width - 2))
+  [ "$avail" -lt 1 ] && avail=1
+  awk -v w="$width" -v a="$avail" \
+    '{ printf "%" w "d  %s\n", NR, substr($0, 1, a) }' "$1"
+else
+  awk -v w="$width" '{ printf "%" w "d  %s\n", NR, $0 }' "$1"
+fi
+}
+
+
+serve_or_html() {
+if [ "$SERVE" = "1" ] || [ "$HTML" = "1" ]; then
+# One program, two ways out: --serve keeps answering with the document,
+# --html hands it over once and stops. Same renderer either way, so the two
+# cannot drift into disagreeing about what the page looks like.
+MODE=serve; NAME=acstack-md-serve
+if [ "$HTML" = "1" ]; then MODE=html; NAME=acstack-md-html; fi
+# A document bound for the opener on the laptop is handed over once, like
+# --html, but it does end up behind a server - the opener's. So it wants the
+# relative mermaid src that --html cannot use. Internal: set by the --browser
+# dispatch below, never by a caller.
+if [ "${ACSTACK_MD_OPENER:-0}" = "1" ] && [ "$HTML" = "1" ]; then MODE=opener; fi
+# exec -a names the process. Without it a running server is just "python3 -"
+# and there is nothing sensible to pkill.
+exec -a "$NAME" python3 - "$FILE" "$PORT" "$MODE" <<'PY'
+import html, http.server, pathlib, re, socketserver, sys
+try:
+  import markdown
+except ImportError:
+  sys.exit("acstack-md: needs the python markdown package: pip install --user markdown")
+
+src, port, MODE = pathlib.Path(sys.argv[1]), int(sys.argv[2]), sys.argv[3]
+VENDOR = pathlib.Path.home() / ".local/share/acstack/mermaid.min.js"
+
+CSS = """*{box-sizing:border-box}body{max-width:54rem;margin:0 auto;padding:2rem 1.25rem;
+font:16px/1.65 -apple-system,Segoe UI,system-ui,sans-serif;color:#1a1a1a;background:#fff}
+h1,h2,h3{line-height:1.25;margin:2rem 0 .75rem}h1{font-size:1.9rem}h2{font-size:1.45rem}
+code{font:14px/1.5 ui-monospace,Consolas,monospace;background:#f2f2f2;padding:.15em .35em;border-radius:3px}
+pre{background:#f7f7f7;padding:1rem;border-radius:6px;overflow-x:auto}pre code{background:none;padding:0}
+pre.mermaid{background:none;text-align:center}table{border-collapse:collapse;width:100%}
+th,td{border:1px solid #ddd;padding:.4rem .6rem;text-align:left}
+blockquote{margin:1rem 0;padding:.1rem 1rem;border-left:3px solid #ccc;color:#555}
+img{max-width:100%}
+@media(prefers-color-scheme:dark){body{background:#151515;color:#e6e6e6}
+code{background:#242424}pre{background:#1d1d1d}th,td{border-color:#333}
+blockquote{border-color:#444;color:#aaa}}"""
+
+def render():
+  body = markdown.markdown(src.read_text(),
+      extensions=["fenced_code", "tables", "toc", "sane_lists"])
+  # mermaid.js wants <pre class="mermaid">, not a highlighted code block.
+  body = re.sub(r'<pre><code class="language-mermaid">(.*?)</code></pre>',
+                lambda m: '<pre class="mermaid">' + html.unescape(m.group(1)) + "</pre>",
+                body, flags=re.S)
+  # --serve answers for /mermaid.js itself off the vendored copy. A document
+  # standing on its own has no server behind it, so a relative src would be
+  # fetched from whatever host the page ended up on and find nothing there -
+  # it names the CDN instead. Inlining the vendored 3.5MB would make the page
+  # offline-proof and far too big to push through a CDP payload, which is the
+  # whole reason --html exists.
+  # The opener serves the page from the laptop and answers /mermaid.js off
+  # the copy this machine uploaded to it - falling back to the CDN itself if
+  # it has none. So a relative src is right there too, and unlike --serve it
+  # does not depend on this machine having vendored anything.
+  js = ('<script src="/mermaid.js"></script>'
+        if MODE == "opener" or (MODE == "serve" and VENDOR.exists()) else
+        '<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>')
+  return f"""<!doctype html><html><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>{html.escape(src.name)}</title><style>{CSS}</style></head><body>
+{body}
+{js}
+<script>mermaid.initialize({{startOnLoad:true,securityLevel:"loose",
+theme:matchMedia("(prefers-color-scheme:dark)").matches?"dark":"default"}});</script>
+</body></html>""".encode()
+
+# Out before the port is ever looked at: a document is not a server, and a
+# caller that only wants the page must not be stopped by a busy 6419.
+if MODE in ("html", "opener"):
+  sys.stdout.buffer.write(render())
+  raise SystemExit
+
+class H(http.server.BaseHTTPRequestHandler):
+  def do_GET(self):
+      if self.path == "/mermaid.js" and VENDOR.exists():
+          body, ctype = VENDOR.read_bytes(), "application/javascript"
+      else:
+          body, ctype = render(), "text/html; charset=utf-8"   # re-read: edits show on reload
+      self.send_response(200)
+      self.send_header("Content-Type", ctype)
+      self.send_header("Content-Length", str(len(body)))
+      self.send_header("Cache-Control", "no-store")
+      self.end_headers()
+      self.wfile.write(body)
+  def log_message(self, *a): pass
+
+socketserver.TCPServer.allow_reuse_address = True
+def holder(port):
+  """pid and command line of whatever is listening, best effort."""
+  import subprocess
+  try:
+      out = subprocess.run(["ss", "-ltnpH", f"sport = :{port}"],
+                           capture_output=True, text=True, timeout=3).stdout
+      pid = re.search(r"pid=(\d+)", out)
+      if not pid:
+          return None, None
+      pid = pid.group(1)
+      cmd = pathlib.Path(f"/proc/{pid}/cmdline").read_bytes().replace(b"\0", b" ").decode()
+      return pid, cmd.strip()
+  except Exception:
+      return None, None
+
+try:
+  srv = socketserver.TCPServer(("127.0.0.1", port), H)
+except OSError as e:
+  pid, cmd = holder(port)
+  msg = [f"port {port} is busy: {e}"]
+  if pid:
+      mine = "acstack-md-serve" in cmd or "acstack-md" in cmd
+      msg.append(f"  held by pid {pid}: {cmd[:90]}")
+      msg.append(f"  stop it with:  kill {pid}" if mine else
+                 f"  not acstack-md. use another port:  ACSTACK_MD_PORT=<n> acstack-md --serve ...")
+  else:
+      msg.append("  could not identify the holder. try:  ss -ltnp | grep " + str(port))
+  sys.exit("\n".join(msg))
+url = f"http://localhost:{port}"
+# OSC 8 makes it ctrl+clickable; the bare URL below covers terminals without it.
+sys.stderr.write(f"\033]8;;{url}\033\\{src.name}\033]8;;\033\\  {url}\n")
+sys.stderr.write("  reload the page after editing. ctrl+C to stop.\n")
+if not VENDOR.exists():
+  sys.stderr.write("  note: mermaid.js not vendored, falling back to CDN\n")
+try: srv.serve_forever()
+except KeyboardInterrupt: pass
+PY
+fi
+
+}

package/assets/terminal-workspace/helpers/acstack-open

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+# Open a URL from a machine that has no browser of its own.
+#
+#   acstack-open https://github.com/owner/repo/pull/1
+#   acstack-open --why      which route this machine will take, without taking it
+#
+# gh-dash binds o to this. It is bound as a keybinding rather than left to
+# $BROWSER because gh-dash runs $BROWSER with its output discarded and the
+# dashboard still drawn: a route that needs to say anything, or to hand you a
+# link to click, has nowhere to put it. As a keybinding gh-dash steps aside
+# and gives us the terminal.
+#
+# In order: an explicit override, a desktop on this machine, WSL, the opener
+# service on the laptop, the Playwriter bridge to Chrome on the laptop, and
+# last a link you can click.
+# Installed by acstack.
+set -uo pipefail
+
+LOG="${XDG_CACHE_HOME:-$HOME/.cache}/acstack/open.log"
+# An ambient $AGENT_BROWSER_CDP is a hint, never the thing we rely on. See
+# the bridge branch below for what happened when it was.
+BRIDGE="${ACSTACK_BRIDGE_URL:-${AGENT_BROWSER_CDP:-http://127.0.0.1:19988}}"
+OPENER="${ACSTACK_OPENER_URL:-http://127.0.0.1:19989}"
+# The opener refuses anything without this, so its absence is the same as the
+# opener being down - which is exactly how the route probe treats it.
+OPENER_TOKEN="${XDG_CONFIG_HOME:-$HOME/.config}/acstack/opener.token"
+
+WHY=0
+[ "${1:-}" = "--why" ] && { WHY=1; shift; }
+URL="${1:-}"
+[ -n "$URL" ] || [ "$WHY" = 1 ] \
+  || { echo "usage: acstack-open [--why] <url>" >&2; exit 2; }
+
+log() {  # the only record of what happened when the caller discards output
+  mkdir -p "$(dirname "$LOG")"
+  printf '%s %s\n' "$(date -Is)" "$*" >> "$LOG"
+  if [ "$(wc -l < "$LOG" 2>/dev/null || echo 0)" -gt 400 ]; then
+    tail -n 200 "$LOG" > "$LOG.trim" && mv "$LOG.trim" "$LOG"
+  fi
+}
+
+note() {  # say something a suspended TUI cannot print for us
+  command -v herdr >/dev/null 2>&1 \
+    && herdr notification show "$1" --body "$2" >/dev/null 2>&1
+  return 0
+}
+
+# Not [ -t 1 ]: route() runs inside a command substitution for --why, which
+# makes stdout a pipe even when the terminal is right there.
+has_tty() { { : > /dev/tty; } 2>/dev/null; }
+
+# The relay answering on its HTTP port is not the same as the browser being
+# reachable through it. agent-browser quietly launches a headless Chrome on
+# this machine when it cannot attach, and that Chrome navigates happily and
+# shows nobody anything - which is how o came to report a page it had opened
+# where no one could see it. So ask what is actually on the far end.
+#
+# /json/list is the Playwriter extension's own answer to that question. The
+# extension attaches per tab, so `[]` means it is armed on nothing and there
+# is no browser to drive, however healthy the tunnel underneath looks.
+#
+# This used to gate on $HOME/.agent-browser/default.sock existing first, on
+# the reasoning that probing starts a browser as a side effect. It does not:
+# curl starts nothing. What that gate did do was make the bridge unreachable,
+# because nothing on this machine creates that socket until an agent-browser
+# session is already running - so a perfectly healthy bridge still fell
+# through to the link route. Asking the relay is both safer and correct.
+bridge_attached() {
+  [ "${ACSTACK_OPEN_BRIDGE:-auto}" != "off" ] || return 1
+  # agent-browser has to exist to take the route, but is never run to decide
+  # it: deciding must cost one round trip, not a browser launch.
+  command -v agent-browser >/dev/null 2>&1 || return 1
+  # Seconds, not tens of them: the tunnel stays bound on this side after the
+  # relay at the far end stops answering, so an unhealthy bridge connects and
+  # then hangs rather than refusing. Every one of those seconds is spent in
+  # front of someone who just pressed a key.
+  local targets
+  targets=$(curl -fsS --connect-timeout 1 -m 2 "$BRIDGE/json/list" 2>/dev/null) || return 1
+  # Whitespace-only and [] both mean armed on no tab.
+  case "$(printf '%s' "$targets" | tr -d '[:space:]')" in
+    ''|'[]') return 1 ;;
+  esac
+  return 0
+}
+
+# Same discipline as bridge_attached: ask the far end rather than believing
+# anything local. A token on disk proves nothing about a service being up, and
+# a service being up proves nothing without the token it will demand - so the
+# probe carries the token and the route is only taken if that round trip
+# answered.
+opener_ready() {
+  [ "${ACSTACK_OPEN_OPENER:-auto}" != "off" ] || return 1
+  local tok
+  tok=$(cat "$OPENER_TOKEN" 2>/dev/null) || return 1
+  [ -n "$tok" ] || return 1
+  # Seconds, not tens of them - someone just pressed a key and is watching.
+  curl -fsS --connect-timeout 1 -m 2 -H "X-ACStack-Token: $tok" \
+    "$OPENER/health" >/dev/null 2>&1
+}
+
+route() {  # the route this machine will take, decided without taking it
+  [ -n "${ACSTACK_OPEN_CMD:-}" ] && { echo "command"; return; }
+  [ -n "${DISPLAY:-}${WAYLAND_DISPLAY:-}" ] && command -v xdg-open >/dev/null 2>&1 \
+    && { echo "xdg-open"; return; }
+  local opener
+  for opener in wslview wsl-open explorer.exe; do
+    command -v "$opener" >/dev/null 2>&1 && { echo "$opener"; return; }
+  done
+  # Ahead of the bridge deliberately. The bridge drives a browser for an
+  # agent: it attaches per tab, only after someone clicks the extension icon,
+  # and it does so in a Chrome profile that is not the default browser. The
+  # opener needs no click and reaches the browser the user actually uses. See
+  # docs/adr/0006-document-opener-service.md.
+  opener_ready && { echo "opener"; return; }
+  bridge_attached && { echo "bridge"; return; }
+  has_tty && { echo "link"; return; }
+  echo "clipboard"
+}
+
+# A clickable link, on the terminal you are actually sitting at. OSC 8 is a
+# hyperlink the terminal draws itself, so ctrl+click reaches the browser on
+# your own machine with nothing installed anywhere in between. The bare URL
+# on the next line covers terminals that ignore OSC 8, and the clipboard
+# copy covers not wanting to click at all.
+link_screen() {
+  printf '%s' "$URL" | acstack-clip
+  {
+    printf '\n  Open on GitHub\n\n  '
+    printf '\033]8;;%s\033\\%s\033]8;;\033\\\n' "$URL" "$URL"
+    printf '  ctrl+click the link, or paste it - it is on your clipboard\n\n'
+    printf '  Press any key to go back.'
+  } > /dev/tty
+  read -rsn1 < /dev/tty
+  printf '\n' > /dev/tty
+}
+
+ROUTE="$(route)"
+[ "$WHY" = 1 ] && { echo "$ROUTE"; exit 0; }
+
+case "$ROUTE" in
+  command)
+    log "override: $ACSTACK_OPEN_CMD $URL"
+    exec ${ACSTACK_OPEN_CMD} "$URL"
+    ;;
+  xdg-open)
+    # $BROWSER is cleared first: xdg-open reads it too, and $BROWSER may well
+    # be pointing back here, which would loop.
+    log "xdg-open: $URL"
+    BROWSER= exec xdg-open "$URL"
+    ;;
+  explorer.exe)
+    # explorer.exe reports failure even when it opened the page. Ignore it.
+    log "explorer.exe: $URL"
+    explorer.exe "$URL" >/dev/null 2>&1
+    exit 0
+    ;;
+  wslview|wsl-open)
+    log "$ROUTE: $URL"
+    exec "$ROUTE" "$URL"
+    ;;
+  opener)
+    # One POST and the laptop opens it in whatever it considers the default
+    # browser. No tab to arm, no extension, no CDP session to contend for.
+    #
+    # A URL carrying a double quote or a backslash would break out of the JSON
+    # string it is about to become. Rather than escape it, fall through to the
+    # link screen: those characters are not legal in a URL unescaped, so a URL
+    # holding one is malformed and worth showing a human rather than sending.
+    tok=$(cat "$OPENER_TOKEN" 2>/dev/null || true)
+    case "$URL" in
+      *'"'*|*'\\'*) tok="" ;;
+    esac
+    if [ -n "$tok" ] && curl -fsS --connect-timeout 2 -m 10 -X POST \
+         -H "X-ACStack-Token: $tok" -H 'Content-Type: application/json' \
+         --data "$(printf '{"url":"%s"}' "$URL")" \
+         "$OPENER/open" 2>/dev/null | tr -d '[:space:]' | grep -q '"opened":true'; then
+      log "opener $OPENER: $URL"
+      exit 0
+    fi
+    log "opener $OPENER did not open it, handing over the link: $URL"
+    if has_tty; then link_screen; exit 0; fi
+    ;;
+  bridge)
+    # Name the endpoint rather than inheriting one. Leaning on an ambient
+    # $AGENT_BROWSER_CDP made this launch a headless Chrome on the VM when
+    # run from a herdr popup, which reported success and opened nothing
+    # anybody could see.
+    #
+    # The default session, deliberately: the relay takes one CDP client at a
+    # time, so a session of our own cannot connect while an agent holds it.
+    # That also means the new tab becomes the active one for any agent
+    # driving that browser. ACSTACK_OPEN_BRIDGE=off trades the one-key open
+    # for never touching it.
+    if timeout 20 agent-browser --cdp "$BRIDGE" tab new >/dev/null 2>&1 \
+       && timeout 30 agent-browser --cdp "$BRIDGE" open "$URL" >/dev/null 2>&1; then
+      log "bridge $BRIDGE: $URL"
+      exit 0
+    fi
+    log "bridge $BRIDGE unavailable, handing over the link: $URL"
+    if has_tty; then link_screen; exit 0; fi
+    ;;
+esac
+
+[ "$ROUTE" = link ] && { log "link: $URL"; link_screen; exit 0; }
+
+# No terminal to draw on and no browser to reach. The clipboard is still one
+# paste from the browser on the machine you are sitting at, which beats
+# nothing, but report failure anyway: a silent success here is what left
+# gh-dash saying "Opened in browser" about a page that never opened.
+if printf '%s' "$URL" | acstack-clip; then
+  log "copied, not opened: $URL"
+  note "URL copied, not opened" "No browser reachable from here. Paste: $URL"
+  exit 3
+fi
+log "no route: $URL"
+note "Cannot open URL" "$URL"
+exit 1

package/assets/terminal-workspace/helpers/acstack-popup

@@ -0,0 +1,13 @@
+#!/bin/sh
+# Run a herdr popup's command with this folder first on PATH.
+#
+#   acstack-popup <command> [args...]
+#
+# herdr runs a popup with its server's environment, not a login shell. A
+# server started by `herdr --remote` has the sshd default PATH, which lacks
+# this folder, so a bare popup target exits 127. apply calls this helper by
+# absolute path, and it finds its folder from $0. herdr and harlequin always
+# link into ~/.local/bin, so that goes on PATH too. The target and every tool
+# it starts then resolve whatever PATH the server has. Installed by acstack.
+PATH="$(dirname "$0"):$HOME/.local/bin:$PATH"; export PATH
+exec "$@"

package/assets/terminal-workspace/helpers/acstack-view

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# View one file, picked by what the file is.
+#
+#   acstack-view README.md      rendered markdown, mermaid diagrams included
+#   acstack-view src/main.rs    yazi, opened with the cursor on that file
+#
+# tuicr's <leader>v hands us the file under its cursor. Everything this
+# dispatches to is a terminal program, so `q` hands the screen back to tuicr
+# the same way a terminal editor does - which is the whole reason the choice
+# lives in a script rather than in tuicr: changing it is an edit, not a
+# rebuild.
+# Installed by acstack.
+set -uo pipefail
+
+FILE="${1:-}"
+[ -n "$FILE" ] || { echo "usage: acstack-view <file>" >&2; exit 2; }
+[ -e "$FILE" ] || { echo "acstack-view: no such file: $FILE" >&2; exit 1; }
+
+# Markdown is worth rendering rather than listing: acstack-md draws mermaid
+# diagrams as text, and offers --serve for a browser when a diagram needs to
+# be rendered properly.
+case "$FILE" in
+  *.md|*.MD|*.markdown|*.Markdown|*.mdown|*.mkd)
+    command -v acstack-md >/dev/null 2>&1 && exec acstack-md "$FILE"
+    ;;
+esac
+
+# yazi opens on the file's own directory with the cursor on it, so the preview
+# pane shows the file and the tree is right there to move around in.
+command -v yazi >/dev/null 2>&1 && exec yazi "$FILE"
+
+# Neither installed: a pager still beats nothing, and -R keeps any colour.
+exec ${PAGER:-less -R} "$FILE"

package/assets/terminal-workspace/helpers/xclip

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# xclip, for a machine whose clipboard is at the other end of an SSH session.
+# acstack installs this only when no real xclip is present.
+#
+# It exists for programs that reach for xclip directly instead of offering a
+# setting. gh-dash copies pull request URLs through a Go library that looks
+# only for xclip, xsel, wl-copy and termux-clipboard-set, and gives up when
+# none is on PATH. This puts one there, and acstack-clip sends the text to
+# the terminal's own clipboard with OSC 52.
+#
+# Hands over to a real xclip if one turns up on PATH with a display to talk
+# to. Remove it with `setup.sh uninstall`. Installed by acstack.
+set -uo pipefail
+
+PATH="$(cd "$(dirname "$0")" 2>/dev/null && pwd):$PATH"
+
+# A real xclip, anywhere on PATH except beside this script.
+if [ -n "${DISPLAY:-}${WAYLAND_DISPLAY:-}" ]; then
+  self="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+  while IFS= read -r candidate; do
+    [ "$(cd "$(dirname "$candidate")" 2>/dev/null && pwd)" = "$self" ] && continue
+    exec "$candidate" "$@"
+  done < <(type -ap xclip 2>/dev/null)
+fi
+
+for arg in "$@"; do
+  case "$arg" in
+    -o|-out|-output) exec acstack-clip --out ;;
+  esac
+done
+exec acstack-clip

package/assets/terminal-workspace/lib/apply-ghdash.sh

@@ -0,0 +1,78 @@
+apply_ghdash() {
+  have gh || { say "gh not installed, skipping dashboard"; return 0; }
+  gh extension list 2>/dev/null | grep -q gh-dash || gh extension install dlvhdr/gh-dash >/dev/null 2>&1
+  mkdir -p "$(dirname "$GHDASH_CFG")"
+  ACSTACK_CFG="$CFG" py "$GHDASH_CFG" <<'PY'
+import os, sys, yaml
+src, dst = os.environ["ACSTACK_CFG"], sys.argv[1]
+# `or {}` on the section as well as the file. A bare "gh_dash:" with nothing
+# under it, which is what commenting the block out leaves behind, parses to
+# None, and every tw.get below then raises AttributeError. apply_ghdash died
+# on that with a traceback and wrote no config at all. The keybindings and
+# remote lookups below already guard the same way.
+tw = ((yaml.safe_load(open(src)) or {}).get("gh_dash") or {}) if os.path.isfile(src) else {}
+cfg = yaml.safe_load(open(dst)) or {} if os.path.isfile(dst) else {}
+if tw.get("sections"):
+    cfg["prSections"] = [{"title": s["title"], "filters": s["filters"]} for s in tw["sections"]]
+if tw.get("repo_paths"):
+    cfg["repoPaths"] = tw["repo_paths"]
+kb = tw.get("keybindings", {}) or {}
+# Every other setting reaches this script through cfg_get, which carries its
+# own default. This block reads the yaml itself, so a machine with no
+# terminal-workspace config used to land here with an empty dict: the prune
+# below dropped the review and agent keys, and nothing was written back. D
+# and S went silently dead while o, which already defaulted, kept working.
+# Defaults here, matching config.example.yaml. An empty string still disables.
+review = kb.get("review", "D")
+agent_review = kb.get("agent_review", "S")
+# "tree diff" is the old name for the review key, kept here so re-applying
+# over a config written before the rename drops it rather than leaving two
+# bindings on the same key.
+MANAGED = ("review (tuicr)", "tree diff", "agent review", "open in browser")
+prs = [k for k in (cfg.get("keybindings", {}) or {}).get("prs", [])
+       if k.get("name") not in MANAGED]
+if review:
+    prs.append({"key": review, "name": "review (tuicr)",
+                "command": "cd {{.RepoPath}} && tuicr pr {{.PrNumber}}\n"})
+if agent_review:
+    prs.append({"key": agent_review, "name": "agent review",
+                "command": 'cd {{.RepoPath}} && claude "/code-review {{.PrNumber}}"\n'})
+kbs = cfg.setdefault("keybindings", {})
+# o built into gh-dash opens through $BROWSER, whose output it discards. That
+# is enough for a machine with a desktop and nothing at all for one without,
+# where the only way to reach a browser is to hand the terminal a link. Take
+# the key so acstack-open gets a terminal to draw on. GH_HOST covers
+# GitHub Enterprise, whose URLs are the same shape on a different host.
+open_key = (tw.get("remote", {}) or {}).get("open_key", "o")
+if open_key:
+    host = "https://${GH_HOST:-github.com}"
+    prs.append({"key": open_key, "name": "open in browser",
+                "command": f'acstack-open "{host}/{{{{.RepoName}}}}/pull/{{{{.PrNumber}}}}"\n'})
+    issues = [k for k in (cfg.get("keybindings", {}) or {}).get("issues", [])
+              if k.get("name") not in MANAGED]
+    issues.append({"key": open_key, "name": "open in browser",
+                   "command": f'acstack-open "{host}/{{{{.RepoName}}}}/issues/{{{{.IssueNumber}}}}"\n'})
+    kbs["issues"] = issues
+kbs["prs"] = prs
+if tw.get("page_keys", True):
+    uni = [k for k in kbs.get("universal", []) if k.get("builtin") not in ("pageUp", "pageDown")]
+    uni += [{"key": "pgup", "builtin": "pageUp"}, {"key": "pgdown", "builtin": "pageDown"}]
+    kbs["universal"] = uni
+yaml.safe_dump(cfg, open(dst, "w"), sort_keys=False, default_flow_style=False, width=200)
+print("  gh-dash config written")
+PY
+}
+
+# Every edit the pi component makes to pi's own files goes through here, and
+# so does the record of what it changed. pi's config is JSON, which has no
+# comment to mark a managed region with, so ownership lives in $PI_OWNED.
+#   pkg <identity>             the configured source pi holds for a package
+#   own|disown pkg|file <name> record or forget one thing this setup added
+#   owns pkg|file <name>       exit 0 when this setup added it
+#   parses <file>              exit 0 when the file is absent or valid JSON
+#   merge <file> <slot> <json> claim each dotted key with a value, and release
+#                              each one set to null, putting back what it held
+#   pin <identity> <prior> <ours>  record a pin apply moved, keeping the first prior
+#   pin-get <identity>         the prior and our pin, tab-separated
+#   pin-forget <identity>      drop that record
+#   md write|strip             the delegation block in pi's context file

package/assets/terminal-workspace/lib/apply-herdr-numbers.sh

@@ -0,0 +1,49 @@
+apply_herdr_numbers() {
+  have herdr || return 0
+  [ "$(cfg_get herdr.renumber_plugin true)" = "true" ] || return 0
+
+  local dir="$HOME/.config/acstack/herdr-numbers"
+  mkdir -p "$dir"
+  # An absolute command: herdr runs argv without a shell and resolves relative
+  # commands from the plugin root, not from PATH.
+  cat > "$dir/herdr-plugin.toml" <<H
+id = "acstack.herdr-numbers"
+name = "ACStack workspace numbers"
+version = "1.0.0"
+min_herdr_version = "0.8.0"
+description = "Keep the sidebar numbers matching prefix+1..9"
+platforms = ["linux", "macos", "windows"]
+
+# Every event that can move a sidebar row. workspace.moved and
+# workspace.reordered are deliberately absent: the realignment emits both, so
+# hooking them would loop forever. The helper is idempotent, so the overlap
+# between the workspace and worktree events costs nothing.
+[[events]]
+on = "workspace.created"
+command = ["$BIN/acstack-herdr-renumber"]
+
+[[events]]
+on = "workspace.closed"
+command = ["$BIN/acstack-herdr-renumber"]
+
+[[events]]
+on = "worktree.created"
+command = ["$BIN/acstack-herdr-renumber"]
+
+[[events]]
+on = "worktree.opened"
+command = ["$BIN/acstack-herdr-renumber"]
+
+[[events]]
+on = "worktree.removed"
+command = ["$BIN/acstack-herdr-renumber"]
+H
+
+  if herdr plugin list 2>/dev/null | grep -q "acstack.herdr-numbers"; then
+    say "herdr numbers plugin already linked"
+  elif herdr plugin link "$dir" >/dev/null 2>&1; then
+    say "herdr numbers plugin linked, sidebar numbers stay aligned"
+  else
+    say "herdr plugin link failed; run acstack-herdr-renumber by hand"
+  fi
+}