browser-automation-skill 0.71.0

package/scripts/browser-mcp.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# scripts/browser-mcp.sh — launch the MCP server that exposes browser-skill
+# verbs as MCP tools (stdio JSON-RPC NDJSON, protocol version 2024-11-05).
+#
+# Usage:
+#   bash scripts/browser-mcp.sh serve         # default; reads JSON-RPC on stdin
+#   bash scripts/browser-mcp.sh --help        # usage
+#
+# Wire format: NDJSON. Each request/response is a single JSON object terminated
+# by '\n'. Matches the framing of our existing chrome-devtools-bridge.mjs
+# CLIENT so the codebase converges on one wire shape.
+#
+# Tools exposed (Stage 1): browser_open, browser_snapshot. See
+# scripts/lib/node/mcp-server.mjs::TOOLS for the live registry.
+#
+# Phase 14 (Proposal 2 from midscene research): lets agent-browser / midscene
+# / Stagehand / browser-use reuse our cache + telemetry + secrets vault
+# without re-implementing them.
+
+set -euo pipefail
+IFS=$'\n\t'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+
+BROWSER_SKILL_NODE_BIN="${BROWSER_SKILL_NODE_BIN:-node}"
+
+case "${1:-serve}" in
+  serve)
+    if ! command -v "${BROWSER_SKILL_NODE_BIN}" >/dev/null 2>&1; then
+      die "${EXIT_TOOL_MISSING}" \
+        "node not on PATH (set BROWSER_SKILL_NODE_BIN to override)"
+    fi
+    exec "${BROWSER_SKILL_NODE_BIN}" "${SCRIPT_DIR}/lib/node/mcp-server.mjs"
+    ;;
+  --help|-h|help)
+    cat <<'USAGE'
+browser-mcp — MCP server for browser-skill verbs
+
+Usage:
+  bash scripts/browser-mcp.sh serve   # start JSON-RPC server on stdio
+  bash scripts/browser-mcp.sh --help  # this message
+
+Tools exposed (Stage 1):
+  browser_open      — open a URL
+  browser_snapshot  — capture eN-indexed accessibility snapshot
+
+Protocol: MCP 2024-11-05, NDJSON over stdio. Spawn this server from any
+MCP-capable client (Claude Code, Continue, Cline, agent-browser, midscene,
+etc.) to drive our cache + telemetry without re-implementing it.
+
+Smoke test (manual):
+  printf '%s\n' \
+    '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+    '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+    | bash scripts/browser-mcp.sh serve
+USAGE
+    exit 0
+    ;;
+  *)
+    die "${EXIT_USAGE_ERROR}" "unknown subcommand '${1}' — see --help"
+    ;;
+esac

package/scripts/browser-migrate.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# scripts/browser-migrate.sh
+# Phase 10 part 1-ii — schema migration verb. Sub-mode dispatch over
+# lib/migrate.sh's pure read/write API (10-1-i).
+#
+# Sub-modes:
+#   check                                    read-only; reports schemas needing migration
+#   run [--yes] [--schema NAME]              run all (or one schema); --yes bypasses typed-phrase
+#   rollback --schema NAME [--yes]           single-step rollback for SCHEMA
+#   status                                   echoes versions.json
+#   clean-backups [--keep N] [--yes]         discard backups beyond newest N (default 5)
+#
+# Destructive sub-modes (run/rollback/clean-backups) require either --yes
+# OR a TTY-interactive typed-phrase confirmation. They also acquire a
+# PID-tracked lock at ${BROWSER_SKILL_HOME}/.migrate.lock to prevent
+# concurrent migrations.
+
+set -euo pipefail
+IFS=$'\n\t'
+umask 077
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPTS_DIR="${SCRIPT_DIR}"
+export SCRIPTS_DIR
+
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/output.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/output.sh"
+# shellcheck source=lib/migrate.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/migrate.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  browser-migrate check                                  read-only; reports schemas needing migration
+  browser-migrate status                                 echoes versions.json
+  browser-migrate run [--yes] [--schema NAME]            run all (or one schema)
+  browser-migrate rollback --schema NAME [--yes]         single-step rollback for SCHEMA
+  browser-migrate clean-backups [--keep N] [--yes]       discard backups beyond newest N
+
+Destructive sub-modes (run, rollback, clean-backups) require --yes OR
+TTY-interactive typed-phrase confirmation.
+USAGE
+}
+
+# --- Lock helpers ---
+
+_acquire_migrate_lock() {
+  local lock_path="${BROWSER_SKILL_HOME}/.migrate.lock"
+  if [ -f "${lock_path}" ]; then
+    local owner_pid
+    owner_pid="$(jq -r '.pid // empty' "${lock_path}" 2>/dev/null || true)"
+    if [ -n "${owner_pid}" ] && [ "${owner_pid}" != "null" ] && kill -0 "${owner_pid}" 2>/dev/null; then
+      die "${EXIT_USAGE_ERROR}" "browser-migrate: another migration in progress (pid ${owner_pid}); wait or kill it"
+    fi
+    warn "browser-migrate: stale lock from pid ${owner_pid:-?} cleared"
+    rm -f "${lock_path}"
+  fi
+  printf '%s' "$(jq -nc --arg pid "$$" --arg now "$(now_iso)" \
+    '{pid:($pid|tonumber), acquired_at:$now}')" > "${lock_path}"
+  chmod 600 "${lock_path}"
+  trap '_release_migrate_lock' EXIT
+}
+
+_release_migrate_lock() {
+  rm -f "${BROWSER_SKILL_HOME}/.migrate.lock"
+}
+
+# --- Confirmation ---
+
+# _confirm_phrase EXPECTED
+# When --yes flag set (ARG_YES=1), skip. Otherwise require interactive TTY +
+# read one line from stdin matching EXPECTED. Refuse on mismatch.
+_confirm_phrase() {
+  local expected="$1"
+  if [ "${arg_yes:-0}" = "1" ]; then return 0; fi
+  if [ ! -t 0 ]; then
+    die "${EXIT_TTY_REQUIRED}" "browser-migrate: --yes flag required when no TTY (interactive confirmation needs TTY)"
+  fi
+  printf "type '%s' to confirm:\n" "${expected}" >&2
+  local line
+  IFS= read -r line
+  [ "${line}" = "${expected}" ] || die "${EXIT_USAGE_ERROR}" "browser-migrate: confirmation mismatch; aborted"
+}
+
+# --- Sub-mode dispatch ---
+
+sub_mode="${1:-}"
+[ -n "${sub_mode}" ] || { usage >&2; die "${EXIT_USAGE_ERROR}" "browser-migrate: missing sub-mode (check / run / rollback / status / clean-backups)"; }
+shift
+
+case "${sub_mode}" in
+  -h|--help) usage; exit 0 ;;
+  check|status|run|rollback|clean-backups) ;;
+  *) die "${EXIT_USAGE_ERROR}" "browser-migrate: unknown sub-mode '${sub_mode}' (expected: check / run / rollback / status / clean-backups)" ;;
+esac
+
+# --- check ---
+
+if [ "${sub_mode}" = "check" ]; then
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      -h|--help) usage; exit 0 ;;
+      *) die "${EXIT_USAGE_ERROR}" "browser-migrate check: unknown flag '$1'" ;;
+    esac
+  done
+  migrate_check
+  exit 0
+fi
+
+# --- status ---
+
+if [ "${sub_mode}" = "status" ]; then
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      -h|--help) usage; exit 0 ;;
+      *) die "${EXIT_USAGE_ERROR}" "browser-migrate status: unknown flag '$1'" ;;
+    esac
+  done
+  migrate_status
+  exit 0
+fi
+
+# --- run ---
+
+if [ "${sub_mode}" = "run" ]; then
+  arg_yes=0 arg_schema=""
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --yes)    arg_yes=1; shift ;;
+      --schema) arg_schema="$2"; shift 2 ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "${EXIT_USAGE_ERROR}" "browser-migrate run: unknown flag '$1'" ;;
+    esac
+  done
+  _confirm_phrase "migrate now"
+  _acquire_migrate_lock
+  if [ -n "${arg_schema}" ]; then
+    migrate_run "${arg_schema}"
+  else
+    migrate_run
+  fi
+  exit 0
+fi
+
+# --- rollback ---
+
+if [ "${sub_mode}" = "rollback" ]; then
+  arg_yes=0 arg_schema=""
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --yes)    arg_yes=1; shift ;;
+      --schema) arg_schema="$2"; shift 2 ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "${EXIT_USAGE_ERROR}" "browser-migrate rollback: unknown flag '$1'" ;;
+    esac
+  done
+  [ -n "${arg_schema}" ] || die "${EXIT_USAGE_ERROR}" "browser-migrate rollback: --schema NAME required"
+  _confirm_phrase "migrate rollback ${arg_schema}"
+  _acquire_migrate_lock
+  migrate_rollback "${arg_schema}"
+  duration_ms=$(( $(now_ms) - SUMMARY_T0 ))
+  summary_json verb=migrate mode=rollback schema="${arg_schema}" \
+    duration_ms="${duration_ms}" status=ok
+  exit 0
+fi
+
+# --- clean-backups ---
+
+if [ "${sub_mode}" = "clean-backups" ]; then
+  arg_yes=0 arg_keep="5"
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --yes)  arg_yes=1; shift ;;
+      --keep) arg_keep="$2"; shift 2 ;;
+      -h|--help) usage; exit 0 ;;
+      *) die "${EXIT_USAGE_ERROR}" "browser-migrate clean-backups: unknown flag '$1'" ;;
+    esac
+  done
+  _confirm_phrase "clean backups"
+  _acquire_migrate_lock
+  migrate_clean_backups "${arg_keep}"
+  duration_ms=$(( $(now_ms) - SUMMARY_T0 ))
+  summary_json verb=migrate mode=clean-backups keep="${arg_keep}" \
+    duration_ms="${duration_ms}" status=ok
+  exit 0
+fi

package/scripts/browser-open.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# scripts/browser-open.sh — open a URL via the routed adapter.
+# Usage: bash scripts/browser-open.sh [--site NAME] [--tool NAME] [--dry-run]
+#                                     [--raw] --url <URL>
+# Emits one streaming JSON line per adapter event (if any), then a single
+# JSON summary line. See docs/superpowers/specs/2026-04-27-browser-automation-skill-design.md §5.4
+# and docs/superpowers/specs/2026-05-01-token-efficient-adapter-output-design.md §3.
+
+set -euo pipefail
+IFS=$'\n\t'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/output.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/output.sh"
+# shellcheck source=lib/router.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/router.sh"
+# shellcheck source=lib/verb_helpers.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/verb_helpers.sh"
+# shellcheck source=lib/site.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/site.sh"
+# shellcheck source=lib/memory.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/memory.sh"
+# shellcheck source=lib/stats.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/stats.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+parse_verb_globals "$@"
+
+# Resolve site/session → BROWSER_SKILL_STORAGE_STATE (no-op if neither set).
+# Router's rule_session_required reads the env var to prefer playwright-lib.
+resolve_session_storage_state
+
+url=""
+verb_argv=()
+i=0
+while [ "${i}" -lt "${#REMAINING_ARGV[@]}" ]; do
+  case "${REMAINING_ARGV[i]}" in
+    --url)
+      url="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${url}" ] || die "${EXIT_USAGE_ERROR}" "--url requires a value"
+      verb_argv+=(--url "${url}")
+      i=$((i + 2))
+      ;;
+    *)
+      verb_argv+=("${REMAINING_ARGV[i]}")
+      i=$((i + 1))
+      ;;
+  esac
+done
+
+[ -n "${url}" ] || die "${EXIT_USAGE_ERROR}" "--url <URL> is required"
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  ok "dry-run: would open ${url}"
+  emit_summary verb=open tool=none why=dry-run status=ok url="${url}" dry_run=true
+  exit 0
+fi
+
+picked="$(pick_tool open "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+stats_t0="$(now_ms)"
+set +e
+adapter_out="$(invoke_with_retry open "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+# Phase 12 part 1 + Phase 14 (Bundle #2): per-action telemetry with auto-derived
+# post-condition. The adapter's stdout for `open` typically echoes the navigated
+# URL (e.g. `{"event":"navigate","url":"…","status":200}`); using that as
+# OBSERVED lets us detect redirect-to-login / app-router rewrites that current
+# self-reported success would silently miss (the cheatsheet's killer
+# "oblivious_success" signal). Caller-set env wins via `:=` parameter expansion.
+if [ "${adapter_rc}" -eq 0 ] && [ -n "${adapter_out}" ]; then
+  : "${BROWSER_STATS_EXPECT_TYPE:=url}"
+  : "${BROWSER_STATS_EXPECT_MATCH:=include}"
+  : "${BROWSER_STATS_EXPECT_VALUE:=${url}}"
+  : "${BROWSER_STATS_OBSERVED:=${adapter_out}}"
+else
+  : "${BROWSER_STATS_OBSERVED:=${url}}"
+fi
+export BROWSER_STATS_EXPECT_TYPE BROWSER_STATS_EXPECT_MATCH BROWSER_STATS_EXPECT_VALUE BROWSER_STATS_OBSERVED
+
+stats_run_adapter_emit \
+  "open" "${tool_name}" "${stats_t0}" "${adapter_rc}" "${adapter_out}" "" \
+  -- "${verb_argv[@]}" || true
+
+[ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  # Pick A6: passive observation. Best-effort tee to recent_urls.jsonl when a
+  # site is in scope. --site flag (ARG_SITE from parse_verb_globals) wins;
+  # falls back to current_get (sticky current site). Site-less navigations
+  # skip the tee — recent_urls is site-scoped for `propose --from-recent`.
+  # Failure emits warn: in the helper and continues; never taints exit code.
+  _open_site="${ARG_SITE:-$(current_get 2>/dev/null || true)}"
+  if [ -n "${_open_site}" ]; then
+    memory_record_recent_url "${_open_site}" "${url}" "open" 2>/dev/null || true
+    # Phase 14 B1: opportunistic URL-pattern clustering. Now that recent_urls
+    # has a fresh entry, ask browser-do propose to (a) cluster recent URLs by
+    # templated path, (b) emit patterns that meet threshold ≥3, (c) write
+    # any new patterns to memory/<site>/patterns.json. Compounds zero-token
+    # clicks for repeat actions — the `browser-do` cache engine has been
+    # shipped since Phase 11 but was idle because nothing triggered propose.
+    # Gated by env so existing flows that don't want this overhead can opt out:
+    #   BROWSER_SKILL_OPEN_PROPOSE=0  → skip (default: 1 / on)
+    # Cost: ~50ms (jq + node url-pattern-cluster.mjs). Best-effort: failure
+    # emits its own warn in browser-do; never taints open's exit code.
+    if [ "${BROWSER_SKILL_OPEN_PROPOSE:-1}" = "1" ]; then
+      bash "${SCRIPT_DIR}/browser-do.sh" propose \
+        --site "${_open_site}" --from-recent --auto-record --threshold 3 \
+        >/dev/null 2>&1 || true
+    fi
+  fi
+  emit_summary verb=open tool="${tool_name}" why="${why}" status=ok url="${url}"
+  exit 0
+fi
+emit_summary verb=open tool="${tool_name}" why="${why}" status=error url="${url}"
+exit "${adapter_rc}"

package/scripts/browser-press.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# scripts/browser-press.sh — keyboard press via the picked adapter.
+# Usage: bash scripts/browser-press.sh [--site NAME] [--tool NAME] [--dry-run]
+#                                       [--raw] --key KEY
+#
+# Routes to chrome-devtools-mcp by default (Phase 6 part 1 introduces press
+# via cdt-mcp; playwright-cli/lib don't declare press today). KEY is a
+# Playwright/CDP key name like "Enter", "Tab", "Escape", "ArrowDown",
+# "Cmd+S", "PageDown".
+
+set -euo pipefail
+IFS=$'\n\t'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/output.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/output.sh"
+# shellcheck source=lib/router.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/router.sh"
+# shellcheck source=lib/verb_helpers.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/verb_helpers.sh"
+
+init_paths
+
+SUMMARY_T0="$(now_ms)"; export SUMMARY_T0
+
+parse_verb_globals "$@"
+
+resolve_session_storage_state
+
+key=""
+verb_argv=()
+i=0
+while [ "${i}" -lt "${#REMAINING_ARGV[@]}" ]; do
+  case "${REMAINING_ARGV[i]}" in
+    --key)
+      key="${REMAINING_ARGV[i+1]:-}"
+      [ -n "${key}" ] || die "${EXIT_USAGE_ERROR}" "--key requires a value"
+      verb_argv+=(--key "${key}")
+      i=$((i + 2))
+      ;;
+    *)
+      verb_argv+=("${REMAINING_ARGV[i]}")
+      i=$((i + 1))
+      ;;
+  esac
+done
+
+[ -n "${key}" ] || die "${EXIT_USAGE_ERROR}" "press requires --key KEY (e.g. --key Enter)"
+
+if [ "${ARG_DRY_RUN:-0}" = "1" ]; then
+  ok "dry-run: would press ${key}"
+  emit_summary verb=press tool=none why=dry-run status=ok key="${key}" dry_run=true
+  exit 0
+fi
+
+picked="$(pick_tool press "${verb_argv[@]}")"
+tool_name="${picked%%$'\t'*}"
+why="${picked#*$'\t'}"
+
+source_picked_adapter "${tool_name}"
+
+set +e
+adapter_out="$(invoke_with_retry press "${verb_argv[@]}")"
+adapter_rc=$?
+set -e
+
+[ -n "${adapter_out}" ] && printf '%s\n' "${adapter_out}"
+
+if [ "${adapter_rc}" -eq 0 ]; then
+  emit_summary verb=press tool="${tool_name}" why="${why}" status=ok key="${key}"
+  exit 0
+fi
+emit_summary verb=press tool="${tool_name}" why="${why}" status=error key="${key}"
+exit "${adapter_rc}"

package/scripts/browser-remove-session.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# remove-session — typed-name confirmation, then delete storageState + meta.
+#
+# Does NOT clear site.default_session pointers that reference this session.
+# Dangling pointers surface clearly: `open --site X` with a deleted default
+# session exits EXIT_SESSION_EXPIRED via resolve_session_storage_state with
+# a self-healing "run login" hint. Cascade-clearing is Phase 5 territory.
+
+set -euo pipefail
+IFS=$'\n\t'
+umask 077
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/session.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/session.sh"
+init_paths
+
+name=""; yes=0; dry_run=0
+usage() {
+  cat <<'USAGE'
+Usage: remove-session --as NAME [--yes-i-know] [--dry-run]
+
+  --as NAME        session to remove (required)
+  --yes-i-know     skip the typed-name confirmation
+  --dry-run        print planned action; remove nothing
+USAGE
+}
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --as)          name="$2"; shift 2 ;;
+    --yes-i-know)  yes=1; shift ;;
+    --dry-run)     dry_run=1; shift ;;
+    -h|--help)     usage; exit 0 ;;
+    *)             die "${EXIT_USAGE_ERROR}" "unknown flag: $1" ;;
+  esac
+done
+[ -n "${name}" ] || { usage; die "${EXIT_USAGE_ERROR}" "--as is required"; }
+assert_safe_name "${name}" "session-name"
+
+started_at_ms="$(now_ms)"
+
+if ! session_exists "${name}"; then
+  die "${EXIT_SESSION_EXPIRED}" "session not found: ${name}"
+fi
+
+if [ "${dry_run}" -eq 1 ]; then
+  ok "dry-run: would remove session ${name}"
+  duration_ms=$(( $(now_ms) - started_at_ms ))
+  summary_json verb=remove-session tool=none why=dry-run status=ok would_run=true \
+               session="${name}" duration_ms="${duration_ms}"
+  exit "${EXIT_OK}"
+fi
+
+if [ "${yes}" -ne 1 ]; then
+  printf 'Type the session name (%s) to confirm removal: ' "${name}" >&2
+  answer=""
+  IFS= read -r answer || true
+  if [ "${answer}" != "${name}" ]; then
+    die "${EXIT_USAGE_ERROR}" "removal aborted (confirmation mismatch)"
+  fi
+fi
+
+session_delete "${name}"
+ok "session removed: ${name}"
+
+duration_ms=$(( $(now_ms) - started_at_ms ))
+summary_json verb=remove-session tool=none why=delete status=ok \
+             session="${name}" duration_ms="${duration_ms}"

package/scripts/browser-remove-site.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# remove-site — typed-name confirmation, then delete profile + meta.
+# Cascade: if CURRENT_FILE points at this site, lib/site.sh::site_delete
+# clears it. (Sessions / credentials linked to this site are NOT removed in
+# Phase 2 — that lands with the credential lifecycle in Phase 5.)
+set -euo pipefail
+IFS=$'\n\t'
+umask 077
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/common.sh"
+# shellcheck source=lib/site.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/lib/site.sh"
+init_paths
+
+name=""; yes=0; dry_run=0
+usage() {
+  cat <<'USAGE'
+Usage: remove-site --name NAME [--yes-i-know] [--dry-run]
+
+  --name NAME      site to remove (required)
+  --yes-i-know     skip the typed-name confirmation
+  --dry-run        print planned action; remove nothing
+USAGE
+}
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --name)        name="$2"; shift 2 ;;
+    --yes-i-know)  yes=1; shift ;;
+    --dry-run)     dry_run=1; shift ;;
+    -h|--help)     usage; exit 0 ;;
+    *)             die "${EXIT_USAGE_ERROR}" "unknown flag: $1" ;;
+  esac
+done
+[ -n "${name}" ] || { usage; die "${EXIT_USAGE_ERROR}" "--name is required"; }
+
+started_at_ms="$(now_ms)"
+
+if ! site_exists "${name}"; then
+  die "${EXIT_SITE_NOT_FOUND}" "site not found: ${name}"
+fi
+
+if [ "${dry_run}" -eq 1 ]; then
+  ok "dry-run: would remove site ${name}"
+  duration_ms=$(( $(now_ms) - started_at_ms ))
+  summary_json verb=remove-site tool=none why=dry-run status=ok would_run=true \
+               site="${name}" duration_ms="${duration_ms}"
+  exit "${EXIT_OK}"
+fi
+
+if [ "${yes}" -ne 1 ]; then
+  printf 'Type the site name (%s) to confirm removal: ' "${name}" >&2
+  answer=""
+  IFS= read -r answer || true
+  if [ "${answer}" != "${name}" ]; then
+    die "${EXIT_USAGE_ERROR}" "removal aborted (confirmation mismatch)"
+  fi
+fi
+
+site_delete "${name}"
+ok "site removed: ${name}"
+
+duration_ms=$(( $(now_ms) - started_at_ms ))
+summary_json verb=remove-site tool=none why=delete status=ok \
+             site="${name}" duration_ms="${duration_ms}"