acstack 0.0.0-stage → 0.47.0

package/skills/host/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: host
+description: Declare the dev setup of the machine you are on – which agent orchestrators are installed to host terminal panes and git worktrees, which browser-verification modes work here, and the optional extras. Interviews you for every axis and writes the answers to the ACStack CLI's global config under host.*. Run it once per machine.
+disable-model-invocation: true
+allowed-tools: AskUserQuestion, Read, Bash, Glob, Grep
+---
+
+# Host Setup
+
+Declare what this machine can do, so the skills that need a browser, a terminal
+pane or a git worktree stop guessing.
+
+Three terms, before they get used:
+
+- A **dev setup** is the set of machine-level tools an ACStack session runs
+  inside. It covers which agent orchestrators host the terminal panes and git
+  worktrees. It also covers which browser-verification modes work on this
+  machine, plus the optional extras, such as publishing the dev server to a
+  private network.
+
+- An **orchestrator**, in this skill, means a tool that owns terminal panes and
+  git worktrees. There are two of them, `herdr` and `orca`, and they are
+  declared separately – one yes-or-no answer each – because a machine can have
+  both installed, one, or neither. A machine with neither uses plain git
+  worktrees under `.claude/worktrees` in the repository.
+
+- An **axis** is one setting of the dev setup, recorded as one `host.*` key.
+
+## Why this is per machine, not per project
+
+The answers go to the ACStack CLI's global config, never to
+`acstack/project.yaml`. Read [`notes.md`](notes.md) when the user asks why.
+
+## What this skill installs
+
+This skill declares a setup, and it installs two parts of one. It offers to
+install Orca when Orca is missing here. It offers to write the managed block
+that points herdr at its worktree directory.
+
+Both offers live in Step 5. Each one plans first, shows you the steps, and waits
+for your approval.
+
+Linux is the only target both installs support. On macOS, on Windows and on the
+Windows Subsystem for Linux, each script says it does not support the install
+there, then stops.
+
+This skill does not install a project, and it does not install herdr itself.
+Logging in to Tailscale, connecting the Playwriter bridge and pairing a client
+to Orca stay with you.
+
+One axis this skill never asks: `host.terminal_workspace`. The `setup` skill
+offers the terminal workspace in its last step, because that workspace installs
+binaries and the offer belongs after the project works. Leave the key alone
+here, and never ask about it.
+
+## Step 1: Detect what is already here
+
+Run the detection script that ships beside this file:
+
+```bash
+plugin_root=$(dirname "$(dirname "$(dirname "$(readlink -f ~/.claude/acstack/bin/acstack)")")")
+bash "$plugin_root/skills/host/detect-host.sh"
+```
+
+Read [`notes.md`](notes.md) when the user asks why the path resolution
+above derives the plugin root from a symlink.
+
+If that symlink is missing, the SessionStart hook did not run. Tell the user to
+restart their agent session. If a restart does not fix it, point them at
+`TROUBLESHOOTING.md` in the plugin root.
+
+The script is read-only. It prints one JSON object to standard output and exits
+0 even when it finds nothing at all. Missing tooling is a finding, not an error,
+so a bare machine is a successful run.
+
+Read [`questions.md`](questions.md) before asking anything. It says what
+each detection field is evidence for, and holds the exact wording of every
+question in Steps 2 and 3.
+
+Then read what this machine already declares:
+
+```bash
+~/.claude/acstack/bin/acstack config get host
+```
+
+Exit code 0 prints the declared axes. Exit code 2 means this machine declares
+nothing yet. The message goes to standard error and names the unset key.
+
+Before asking anything, print a short summary to the user: one line per axis,
+naming the current declaration and what the script detected. Re-running this
+skill is safe. It re-asks every axis and uses the current answer as the starting
+point, so a second run loses nothing.
+
+## Step 2: The required axes – detection never decides them
+
+The rule for this whole step is simple. **Auto-detection may pre-fill the
+recommendation, but it never decides a required axis**.
+
+A detected fact belongs in an option's description – "detected: this session is
+running in a herdr pane" – and never in a silent write. The user answers, and
+the detection only makes the answer easy.
+
+### 2a. Orchestrators
+
+There are two orchestrators, and they are two separate questions rather than one
+choice between them. A machine can have both installed, one, or neither, so an
+answer about one says nothing about the other.
+
+Ask both in one call to the question tool (AskUserQuestion on Claude Code),
+one question per orchestrator. There is no skip: every machine has an answer
+to each.
+
+Answering no to both is a real answer. It declares that this machine has no
+orchestrator. The worktree skills then fall back to plain git worktrees under
+`.claude/worktrees`.
+
+The two questions, and the rules for filling their evidence placeholders,
+are in [`questions.md`](questions.md).
+
+### 2b. Browser-verification modes
+
+There are three modes, and they are not alternatives to each other – a machine
+can support any combination:
+
+- **remote** drives a real browser on the developer's own machine, over the
+  Playwriter bridge. That bridge forwards the browser's debugging port to this
+  machine on port 19988.
+
+- **headless** launches headless Chromium on this machine, meaning a browser
+  with no visible window.
+
+- **local** launches a visible browser on this machine, which needs a graphical
+  display.
+
+Ask them as one multi-select question – [`questions.md`](questions.md) holds
+the wording, the "none of these" and "Decide later" rules, and when you
+must ask it.
+
+## Step 3: The optional axes – with skip
+
+Ask these in one question-tool call. It carries a third question only when you
+answered yes to Orca in Step 2. Otherwise omit that question rather than asking
+it and discarding the answer.
+
+The three questions – preview publishing, element picker and Orca topology –
+are in [`questions.md`](questions.md).
+
+A skipped axis and an axis answered `none` or `false` are different things, and
+the difference matters:
+
+- **Skipped** means unset. This skill writes nothing for that axis. Note what
+    that costs at the command line.
+
+    Run `acstack config get` on an unset axis. It writes its message to standard
+    error and exits 2 for required and optional axes alike. Only the
+    `(required)` or `(optional)` qualifier inside that message tells the two
+    apart.
+
+  The difference that actually matters belongs to `acstack config check`, the
+  health check. It lists an unset optional axis as informational, and fails only
+  on an unset required one.
+
+- **`none` and `false`** are real declarations – the user has said this machine
+  does not have the thing.
+
+Never write a value to represent a skip. If the user skips, write nothing for
+that axis.
+
+## Step 4: Write the answers
+
+One `config set` call per answered axis:
+
+```bash
+~/.claude/acstack/bin/acstack config set host.orchestrators.herdr <true|false>
+~/.claude/acstack/bin/acstack config set host.orchestrators.orca <true|false>
+~/.claude/acstack/bin/acstack config set host.browser.remote <true|false>
+~/.claude/acstack/bin/acstack config set host.browser.headless <true|false>
+~/.claude/acstack/bin/acstack config set host.browser.local <true|false>
+~/.claude/acstack/bin/acstack config set host.preview.tailscale_serve <true|false>
+~/.claude/acstack/bin/acstack config set host.element_picker <stagewise|orca-design-mode|none>
+~/.claude/acstack/bin/acstack config set host.orca.topology <local|remote>
+```
+
+The rules for this step:
+
+- Write nothing for a skipped axis.
+- A success prints `Set <key> = <value>`, with the value rendered as JSON rather
+  than bare – so a string axis comes back quoted, `Set host.element_picker =
+  "stagewise"`, and a boolean comes back unquoted, `Set host.browser.local =
+  true`. A non-zero exit has two causes, and the message tells them apart.
+
+- On a non-zero exit, read [`notes.md`](notes.md) – it covers both causes
+  and how to recover from each
+
+- Setting `host.orca.topology` while `host.orchestrators.orca` is not true is
+  accepted, and the CLI warns that nothing reads it, so do not write it in that
+  case at all.
+
+## Step 5: Follow-up for each orchestrator declared installed
+
+Run the follow-up for every orchestrator answered yes in Step 2. Two yes answers
+means both follow-ups run, in either order. Two no answers means neither runs,
+and the last section applies instead.
+
+### What both installers share
+
+Both scripts take `--plan`, `--apply` and `--help`. `--help` prints the usage
+and the options.
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | the run succeeded |
+| 1 | a step failed, or the write failed |
+| 3 | the script does not support this platform, and it changed nothing |
+| 4 | the script cannot safely edit the config file (`install-herdr-block.sh` only) |
+| 64 | the script rejected an argument |
+
+`install-orca.sh` checks `--pairing-address` when it parses the arguments. It
+takes a plain host name or address, and rejects anything else with exit 64. A
+value holding a space or a slash never reaches the unit.
+
+### When you declared Orca installed
+
+Read [`orca.md`](orca.md) when the user declared Orca installed in Step 2.
+It registers this repository, states the Claude settings rewrite, and
+offers to install Orca when it is missing.
+
+### When you declared herdr installed
+
+Read [`herdr.md`](herdr.md) when the user declared herdr installed in
+Step 2. It offers to write the managed block in herdr's config.
+
+### When you declared neither installed
+
+There is nothing to provision. The worktree skills fall back to plain git
+worktrees under `.claude/worktrees` in the repository.
+
+## Step 6: Report
+
+Close with the report in [`report.md`](report.md). Read it once every answer is
+written and every follow-up has run.
+
+## Notes
+
+Read [`notes.md`](notes.md) when a question comes up about what a
+declaration means, or how `host.browser.*` relates to
+`frontend.browser.mode`.

package/skills/host/detect-host.sh

@@ -0,0 +1,297 @@
+#!/usr/bin/env bash
+# ACStack host detection.
+#
+# Reports what dev-setup tooling exists on this machine, as one JSON object on
+# stdout. Nothing else is printed, and the exit code is 0 whenever detection
+# ran - a bare machine with none of the tooling installed is a perfectly valid
+# answer, not a failure. Missing tooling is a finding, never an error.
+#
+# The script is strictly read-only. It never writes a file, never changes a
+# setting and never installs anything. Callers - a skill deciding how to set up
+# browser verification, say - use the facts here to choose, and any change is
+# made by the caller afterwards, with the user watching.
+#
+# Every tool is looked up on PATH with `command -v` and every home path derives
+# from $HOME. Nothing is hardcoded to an absolute location. That is what makes
+# this testable: tests/test-host-detect.sh runs the script under `env -i` with a
+# PATH of fake executables and a temporary HOME, so the output is entirely
+# determined by what the test wired up. Reaching past PATH or $HOME to a real
+# location would defeat that, so don't.
+#
+# Output is built by hand rather than with jq, because jq is one of the things a
+# bare machine may not have, and needing a JSON tool to report that you have no
+# tools would be a poor joke.
+
+set -u
+
+usage() {
+  cat <<'USAGE'
+detect-host.sh - report this machine's dev-setup tooling as JSON.
+
+Usage:
+  detect-host.sh          Detect and print one JSON object to stdout.
+  detect-host.sh --help   Print this help and exit.
+
+The script is read-only: it inspects PATH, environment variables, $HOME and the
+current git repository, and changes nothing. It exits 0 whenever detection ran,
+including on a machine where nothing is installed - absent tooling is reported
+in the JSON, not as an error.
+
+Reported sections: orchestrator, browser, preview, element_picker,
+orca_topology, claude_settings, project.
+USAGE
+}
+
+case "${1-}" in
+  "") ;;
+  --help|-h) usage; exit 0 ;;
+  *) echo "detect-host.sh: unknown argument: $1" >&2
+     echo "detect-host.sh: run with --help for usage." >&2
+     exit 64 ;;
+esac
+
+# --- helpers ---------------------------------------------------------------
+
+# A JSON string literal for $1, or the bare literal null when $1 is empty. Paths
+# come from the filesystem, so a backslash or a quote in one is unlikely - but a
+# single unescaped quote would make the whole object unparseable, and the caller
+# would see a tool crash instead of a finding.
+json_str() {
+  local s="$1"
+  if [ -z "$s" ]; then printf 'null'; return; fi
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  printf '"%s"' "$s"
+}
+
+# Absolute path of $1 if it is on PATH, empty string otherwise. The `|| true`
+# matters: a missing tool is the normal case here, not a reason to stop.
+which_path() {
+  command -v "$1" 2>/dev/null || true
+}
+
+# Some of the tools below talk to a background daemon over a local socket, and a
+# wedged daemon makes them wait for ever rather than fail. This script is run
+# from a skill with a user watching, so a hang there is worse than a missing
+# finding: bound every such call to three seconds, the same bound the curl probe
+# already uses.
+#
+# `timeout` is itself just a command on PATH, and it is not on every machine, so
+# resolve it once and treat its absence as normal. When it is missing the call
+# still runs, just unbounded - a slightly worse outcome than a bounded call, and
+# a much better one than not detecting at all.
+timeout_bin="$(which_path timeout)"
+
+# Run "$@" with the three-second bound when `timeout` is available, and plainly
+# when it is not. The exit status and output are the command's own either way;
+# a call that is cut short simply produces no output, which every caller here
+# already reads as "no evidence".
+run_bounded() {
+  if [ -n "$timeout_bin" ]; then
+    "$timeout_bin" 3 "$@"
+  else
+    "$@"
+  fi
+}
+
+# --- orchestrator ----------------------------------------------------------
+
+herdr_bin="$(which_path herdr)"
+
+# Orca ships its executable as `orca-ide`; older installs put it on PATH as
+# plain `orca`. Prefer the current name and fall back.
+orca_bin="$(which_path orca-ide)"
+[ -n "$orca_bin" ] || orca_bin="$(which_path orca)"
+
+# Which orchestrator is hosting the session we are running inside, judged by the
+# variable each one exports into its panes. Orca wins when both are set: a herdr
+# pane can host an orca session, but not the other way round.
+if [ -n "${ORCA_PANE_KEY:-}" ]; then
+  hosting="orca"
+elif [ -n "${HERDR_ENV:-}" ]; then
+  hosting="herdr"
+else
+  hosting="none"
+fi
+
+# --- browser ---------------------------------------------------------------
+
+agent_browser_bin="$(which_path agent-browser)"
+
+# The Playwriter bridge forwards a real browser's DevTools port to localhost
+# 19988. If something answers there, remote verification is available. The
+# timeout is short and deliberate: a host that has gone away should cost us
+# three seconds, not hang a skill the user is waiting on.
+bridge_answers="false"
+if [ -n "$(which_path curl)" ]; then
+  if curl -fsS --max-time 3 "http://localhost:19988/json/version" >/dev/null 2>&1; then
+    bridge_answers="true"
+  fi
+fi
+
+# Chromium-family browsers, in preference order. Any one of them can drive
+# headless verification, so we report all we find and let the caller pick.
+chromium_json=""
+chromium_found="false"
+for browser in chromium chromium-browser google-chrome google-chrome-stable \
+               brave-browser microsoft-edge; do
+  p="$(which_path "$browser")"
+  [ -n "$p" ] || continue
+  [ -z "$chromium_json" ] || chromium_json="${chromium_json},"
+  chromium_json="${chromium_json}$(json_str "$p")"
+  chromium_found="true"
+done
+
+# A graphical session of either flavour. Without one, a browser can still run
+# headless, but nobody can watch it.
+if [ -n "${DISPLAY:-}" ] || [ -n "${WAYLAND_DISPLAY:-}" ]; then
+  display="true"
+else
+  display="false"
+fi
+
+browser_remote="$bridge_answers"
+browser_headless="$chromium_found"
+if [ "$chromium_found" = "true" ] && [ "$display" = "true" ]; then
+  browser_local="true"
+else
+  browser_local="false"
+fi
+
+# --- preview (tailscale) ---------------------------------------------------
+
+tailscale_bin="$(which_path tailscale)"
+
+# An installed tailscale that nobody has logged in is no use for sharing a
+# preview URL, so the two facts are reported separately.
+tailscale_logged_in="false"
+if [ -n "$tailscale_bin" ]; then
+  # Bounded: `tailscale status` asks the local tailscaled daemon over a socket
+  # and never returns on its own if that daemon is wedged.
+  if run_bounded "$tailscale_bin" status --json 2>/dev/null \
+     | grep -q '"BackendState"[[:space:]]*:[[:space:]]*"Running"'; then
+    tailscale_logged_in="true"
+  fi
+fi
+
+if [ -n "$tailscale_bin" ] && [ "$tailscale_logged_in" = "true" ]; then
+  preview_rec="true"
+else
+  preview_rec="false"
+fi
+
+# --- orca topology ---------------------------------------------------------
+
+# Orca can serve a UI from this machine to a browser elsewhere. A running
+# user-level `orca` unit with no local display is the shape of a remote setup:
+# the machine serves, somebody else looks. Anything else is local.
+serve_unit_active="false"
+if [ -n "$(which_path systemctl)" ]; then
+  # The unit name `orca` is an assumption, not a fact: whatever provisions the
+  # server chooses that name, and nothing pins it yet, so a unit installed under
+  # a different name reads here as "no server". Bounded too, because
+  # `systemctl --user` waits on the user message bus and blocks when that bus is
+  # not available - on a machine with no user session, say.
+  if [ "$(run_bounded systemctl --user is-active orca 2>/dev/null)" = "active" ]; then
+    serve_unit_active="true"
+  fi
+fi
+
+if [ -z "$orca_bin" ]; then
+  orca_topology_rec=""          # emitted as null: no Orca, so no topology
+elif [ "$serve_unit_active" = "true" ] && [ "$display" = "false" ]; then
+  orca_topology_rec="remote"
+else
+  orca_topology_rec="local"
+fi
+
+# --- element picker --------------------------------------------------------
+
+stagewise_bin="$(which_path stagewise)"
+
+# Stagewise is the dedicated tool, so it wins outright. Orca's built-in design
+# mode is the fallback, but only when Orca is driving a local browser - in a
+# remote topology the picker has no window to pick in.
+if [ -n "$stagewise_bin" ]; then
+  picker_rec="stagewise"
+elif [ -n "$orca_bin" ] && [ "$orca_topology_rec" = "local" ]; then
+  picker_rec="orca-design-mode"
+else
+  picker_rec="none"
+fi
+
+# --- claude settings -------------------------------------------------------
+
+# Whether Orca has already wired hooks into the user's Claude settings, and
+# whether a backup of that file exists. A caller about to edit settings.json
+# wants to know both before it touches anything.
+settings_file="${HOME}/.claude/settings.json"
+orca_hooks_present="false"
+# Deliberately loose: any mention of "orca" anywhere in the file counts, so an
+# unrelated path or permission entry containing that word sets this too. It is
+# evidence that Orca may have touched the file, not proof that it did, and
+# callers must word it that way.
+if [ -f "$settings_file" ] && grep -qi orca "$settings_file" 2>/dev/null; then
+  orca_hooks_present="true"
+fi
+
+backup_exists="false"
+[ -f "${settings_file}.bak" ] && backup_exists="true"
+
+# --- project ---------------------------------------------------------------
+
+project_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+
+# A top-level `frontend:` key in the project config is what turns on frontend
+# verification, so we look for it at column zero only - `frontend:` nested under
+# some other key means something else entirely.
+has_frontend="false"
+if [ -n "$project_root" ] && [ -f "${project_root}/acstack/project.yaml" ]; then
+  if grep -q '^frontend:' "${project_root}/acstack/project.yaml" 2>/dev/null; then
+    has_frontend="true"
+  fi
+fi
+
+# --- output ----------------------------------------------------------------
+
+cat <<JSON
+{
+  "orchestrator": {
+    "herdr_binary": $(json_str "$herdr_bin"),
+    "orca_binary": $(json_str "$orca_bin"),
+    "hosting_this_session": $(json_str "$hosting")
+  },
+  "browser": {
+    "agent_browser_binary": $(json_str "$agent_browser_bin"),
+    "bridge_port_answers": ${bridge_answers},
+    "chromium_binaries": [${chromium_json}],
+    "display": ${display},
+    "recommended": {
+      "remote": ${browser_remote},
+      "headless": ${browser_headless},
+      "local": ${browser_local}
+    }
+  },
+  "preview": {
+    "tailscale_binary": $(json_str "$tailscale_bin"),
+    "tailscale_logged_in": ${tailscale_logged_in},
+    "recommended": ${preview_rec}
+  },
+  "element_picker": {
+    "stagewise_binary": $(json_str "$stagewise_bin"),
+    "recommended": $(json_str "$picker_rec")
+  },
+  "orca_topology": {
+    "serve_unit_active": ${serve_unit_active},
+    "recommended": $(json_str "$orca_topology_rec")
+  },
+  "claude_settings": {
+    "orca_hooks_present": ${orca_hooks_present},
+    "backup_exists": ${backup_exists}
+  },
+  "project": {
+    "root": $(json_str "$project_root"),
+    "has_frontend": ${has_frontend}
+  }
+}
+JSON

package/skills/host/herdr.md

@@ -0,0 +1,79 @@
+# herdr follow-up
+
+Read this file when the user declared herdr installed in Step 2.
+
+- `plugin_root` comes from Step 1 in `SKILL.md`
+- Step 5 in `SKILL.md` lists the exit codes both installers share
+
+### When you declared herdr installed
+
+**Write the managed block.** herdr keeps its config at
+`~/.config/herdr/config.toml`. ACStack needs one setting in that file: the
+directory herdr creates worktrees under. Offer to write it.
+
+The installer is `install-herdr-block.sh`, beside this file, and Step 1 in
+`SKILL.md` resolves the same `plugin_root`.
+
+Plan it first:
+
+```bash
+bash "$plugin_root/skills/host/install-herdr-block.sh" --plan
+```
+
+Two options change the defaults. `--config PATH` points at a config file
+elsewhere, and `--worktree-dir PATH` changes the directory. The defaults are
+`~/.config/herdr/config.toml` and `~/.herdr/worktrees`.
+
+Show the printed step list verbatim, then ask with the question tool (AskUserQuestion on Claude Code). Declining is
+a real answer, and nothing runs. On approval, run the same command with
+`--apply`.
+
+This is the block it writes, and it writes nothing else:
+
+```
+# >>> acstack terminal-workspace >>>
+[worktrees]
+directory = "~/.herdr/worktrees"
+# <<< acstack terminal-workspace <<<
+```
+
+It creates the file when the file is absent. It appends the block when the block
+is absent. It replaces the block in place when the block is there and differs.
+
+It refuses and changes nothing whenever the config file is not in a state it can
+safely edit. Editing one of these would corrupt the file, or throw away
+somebody's config:
+
+- a path that exists and is not a regular file
+- a file that already holds more than one block with those markers
+- a start marker count and an end marker count that differ
+- a start marker that the file never closes
+- a `[worktrees]` table defined outside any managed block
+- a block between the markers that defines a table besides `[worktrees]`
+
+It exits 4 and says which case it hit. Tell the user to fix the config by hand,
+then run the plan again.
+
+**What this skill ships, and what is personal taste.** This skill ships the
+managed block and nothing else. The block tells herdr to put worktrees under
+`~/.herdr/worktrees`. The worktree skills read that path, so it is the one
+setting they depend on.
+
+The rest of a herdr setup is personal taste. This skill installs none of it: the
+keymap, the popup key bindings, the `acstack.herdr-numbers` plugin, and the
+`acstack-*` helper binaries in `~/.local/bin`.
+
+Copy your own if you want them. Nothing in ACStack needs any of them.
+
+**The terminal-workspace skill writes the same block, wider.**
+`assets/terminal-workspace/setup.sh apply` fences `[keys]`, one
+`[[keys.command]]` per binding, and `[worktrees]` between these same two
+markers. It takes the directory from `herdr.worktrees_directory` in
+`~/.config/acstack/terminal-workspace.yaml`. A machine that has run it needs
+nothing from this installer.
+
+The installer therefore leaves that block alone. It reports the step as skipped
+when the directory already agrees. It refuses with exit 4 when it does not.
+
+Change the directory in `terminal-workspace.yaml` and run `setup.sh apply`
+again, never this script.