@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/cloudflare/references/reset-guide.md

@@ -0,0 +1,118 @@
+# Cloudflare reset — when and how
+
+Reset is a heavier action than recovery. `reset-tunnel.sh` deletes every tunnel on the brand's Cloudflare account and wipes the on-disk cloudflared config directory. Use it when the state is genuinely corrupt or when the operator wants a known-good baseline; use patching (targeted cleanup) when the state is mostly correct but one record or process is wrong.
+
+---
+
+## Decision tree — reset or patch?
+
+Ask three questions in order. The first `yes` determines the action.
+
+1. **Is cert.pem bound to an account the operator no longer wants to be signed into?** (e.g. the operator signed in to the wrong account, or the previous account was scrubbed / rotated / delisted.)
+   → Full reset. The cert authorises everything `cloudflared` does; a wrong-account cert poisons every subsequent step.
+
+2. **Is `config.yml` referencing a tunnel UUID that no longer exists on the account, or a hostname that the account no longer owns?**
+   → Full reset. The tunnel the config names is unreachable; recovering per-step is slower than starting clean.
+
+3. **Is the only problem a stray CNAME in the dashboard, a rogue token-mode connector process, or an out-of-date `alias-domains.json` entry?**
+   → Patch (see § Patching below). Reset would destroy correct local state alongside the bad record.
+
+When no question reaches `yes`, the state is probably recoverable per-step via `references/manual-setup.md`. Invoke `setup-tunnel.sh` again before reaching for reset.
+
+---
+
+## Full reset — `reset-tunnel.sh`
+
+### What it does
+
+- Reads cert.pem from `${HOME}/.${BRAND}/cloudflared/cert.pem`.
+- Lists every tunnel on the account the cert authorises.
+- Deletes every one of those tunnels via `cloudflared tunnel delete`.
+- Removes `${HOME}/.${BRAND}/cloudflared/` entirely.
+
+### What it does not do
+
+- It does not touch the platform service (`${BRAND}.service`). Restart the service separately with `systemctl --user restart "${BRAND}.service"` once a fresh tunnel is set up.
+- It does not touch DNS records. Records pointing at `<UUID>.cfargotunnel.com` from a deleted tunnel become stray; delete them in the dashboard (see § Patching below).
+- It does not stop token-mode connector processes. If the device is running `cloudflared ... tunnel run --token <X>` for a tunnel the brand's cert does not own, that connector keeps running.
+- It does not switch accounts. If the bound account was wrong, a fresh `cloudflared tunnel login` from inside `setup-tunnel.sh` on the next run will pick a new one — but the operator must sign in with the correct account in the browser.
+
+### Invocation
+
+```
+~/reset-tunnel.sh <brand>
+```
+
+Example:
+
+```
+~/reset-tunnel.sh maxy
+```
+
+The script exits with the number of tunnels deleted. Relay the output verbatim. If the script exits non-zero (e.g. cert missing, cloudflared not installed), quote the error and stop — do not synthesise a recovery path.
+
+### After reset
+
+Invoke `setup-tunnel.sh` with the operator's chosen hostnames (see `SKILL.md` for the input-collection questions). The script re-runs `cloudflared tunnel login`; the operator authorises a fresh cert from the correct account in the VNC browser.
+
+---
+
+## Patching — targeted cleanup without reset
+
+### Stop a token-mode connector the reset script cannot see
+
+Token-mode tunnels are created by a central operator (e.g. Maxy-provided subdomains under `maxy.bot`). The connector runs with `--token <X>` and does not consult `cert.pem`, so `reset-tunnel.sh` (which authorises via cert.pem) cannot stop or delete it. Kill the process directly:
+
+```
+pkill -f 'cloudflared.*tunnel run --token'
+```
+
+The pattern matches exactly connectors started with `tunnel run --token`, leaving cert-mode connectors (started without `--token`) alone. Confirm the kill:
+
+```
+ps -ef | grep '[c]loudflared'
+```
+
+No lines with `--token` should remain. If multiple token-mode connectors are running, all are killed — scope with a more specific pattern if that is not desired (`pkill -f 'cloudflared.*tunnel run --token eyJ...'` matches the token prefix).
+
+### Delete a stray CNAME that survived a tunnel delete
+
+When `reset-tunnel.sh` deletes a tunnel, the DNS CNAMEs that pointed at `<UUID>.cfargotunnel.com` remain in the zone — Cloudflare deliberately does not cascade-delete DNS when you delete a tunnel. Clean up in the dashboard:
+
+1. See `references/dashboard-guide.md` § "Delete a stray CNAME" for the click-path.
+2. Verify the CNAME's target is the tunnel you just deleted (not a live one).
+3. Delete.
+
+When the operator is unsure which records are stray, have them list the zone's CNAMEs (see `references/dashboard-guide.md` § "List CNAME records in a zone") and compare against the currently-running `cloudflared tunnel list` on the device.
+
+### Remove a rogue entry from `alias-domains.json`
+
+`alias-domains.json` controls which hostnames the platform UI classifies as public (serving the public agent) rather than admin. A prior setup flow may have written an `admin.*` hostname into this file by mistake. Remove it manually:
+
+```
+cat "${CFG_DIR}/alias-domains.json"
+```
+
+If `admin.<yourdomain>` is listed, strip it:
+
+```
+jq --arg H "admin.<yourdomain>" 'map(select(. != $H))' "${CFG_DIR}/alias-domains.json" > /tmp/alias.json && mv /tmp/alias.json "${CFG_DIR}/alias-domains.json"
+```
+
+Replace `<yourdomain>` with the actual domain. The platform UI watches the file and reloads without a restart.
+
+### Fix a single wrong DNS record without tearing everything down
+
+If a hostname's CNAME is pointing at the wrong tunnel (e.g. after an account switch left old records), `cloudflared` can overwrite it once the correct cert is in place:
+
+```
+cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel route dns --overwrite-dns "${TUNNEL_ID}" <hostname>
+```
+
+This runs the same logic `setup-tunnel.sh` runs internally for each subdomain. Apex hostnames do not work here — the dashboard is the only path (see `references/dashboard-guide.md` § "Edit an apex CNAME").
+
+---
+
+## Failure discipline
+
+When `reset-tunnel.sh` or a patch command exits non-zero, report the failure with the exact output. Cite the relevant section above for the next action. Do not chain alternative recovery attempts — the agent's job ends at the boundary of a sanctioned surface, and improvisation outside that boundary is the discipline violation IDENTITY.md § Cloudflare operations exists to prevent.

package/payload/platform/plugins/cloudflare/scripts/_stream-log.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# Shared stream-log helpers sourced by setup-tunnel.sh and reset-tunnel.sh.
+#
+# The platform exposes STREAM_LOG_PATH in the `claude` spawn env (Task 556);
+# the Bash-tool subprocess inherits it, and opt-in scripts call these
+# helpers to emit phase lines and tee subprocess output into the same
+# per-conversation file the chat UI's server-side tailer reads.
+#
+# Contract (read by platform/ui/app/lib/script-stream-tailer.ts tailer and
+# .docs/web-chat.md):
+#   [<ISO-ts>] [script:<scope>] <kv …>
+#   [<ISO-ts>] [script:<scope>:<subprocess-tag>] <raw line>
+# Canonical regex — SCRIPT_STREAM_RE at platform/ui/app/lib/script-stream-tailer.ts:
+#   ^\[([^\]]+)\] \[script:([a-z][a-z0-9-]*)((?::[a-z0-9:_-]+)?)\] (.*)$
+# The literal `script:` prefix is the chat-surface namespace (Task 605). It
+# separates chat-surface emitters from log-file-only scopes (`[mcp:<server>]`
+# from mcp-stderr-tee, `[init]` / `[api-wait-*]` / `[mcp-init-error]` /
+# `[subproc-stderr]` / `[compaction-*]` from claude-agent.ts) which share
+# the same per-conversation stream log but must NOT reach the chat UI.
+# Callers of phase_line / tee_subprocess / tee_subprocess_capture pass the
+# bare scope (e.g. `setup-tunnel`, `list-cf-domains`, `reset-tunnel:cloudflared`);
+# these helpers prepend `script:` to the stream-log write. Stderr mirrors
+# stay unprefixed — stderr is for direct-SSH operators and route-handler
+# `reason=<enum>` regex, not the chat-surface contract.
+# <scope> is any `[a-z][a-z0-9-]*` token (Task 592 generalised from the
+# pre-592 enum `setup-tunnel|reset-tunnel`, which silently filtered out the
+# `[list-cf-domains]` lines Task 589 emitted). <subprocess-tag> may contain
+# lowercase, digits, `-`, `_`, `:`. Adding a new chat-surface scope requires
+# no edit to the regex — the shape is the only contract. Any prefix-shape
+# change must be made on both sides (this helper + script-stream-tailer.ts)
+# atomically.
+#
+# Inner layers (e.g. a node/python helper a .sh wrapper spawns — Task 598's
+# `list-cf-domains.sh` → `list-cf-domains.ts` pattern) must write phase lines
+# directly to STREAM_LOG_PATH with the same prefix shape (including the
+# `script:` namespace): stderr alone is silently discarded by runFormSpawn on
+# exit 0. The build-gate `platform/ui/scripts/check-stream-log-contract.mjs`
+# (Task 600) enforces this by rejecting any .sh under `platform/plugins/*/scripts/`
+# that sources this helper and invokes an interpreter subprocess whose target
+# does not pair a STREAM_LOG_PATH env read with an append/write call. Opt out
+# per invocation with `# stream-log-contract: stderr-only (reason: <prose>)`.
+
+# Exit 1 loudly with the variable name and the invoking scope so direct-SSH
+# invocations fail fast and the operator reads exactly what to set. No
+# silent fallback — criterion 4 of Task 556.
+require_stream_log_path() {
+  local scope="$1"
+  if [ -z "${STREAM_LOG_PATH:-}" ]; then
+    echo "ERROR [${scope}]: STREAM_LOG_PATH environment variable is unset." >&2
+    echo "       This script tees subprocess output into a per-conversation" >&2
+    echo "       stream log; it is meaningless without a target path." >&2
+    echo "       The platform sets STREAM_LOG_PATH automatically for every" >&2
+    echo "       \`claude\` spawn. If you are invoking this" >&2
+    echo "       script by hand, export it yourself, for example:" >&2
+    echo "           export STREAM_LOG_PATH=\"\${HOME}/.maxy/logs/manual-invocation.log\"" >&2
+    exit 1
+  fi
+  mkdir -p "$(dirname "${STREAM_LOG_PATH}")"
+}
+
+# ISO-8601 UTC timestamp with millisecond precision.
+stream_log_ts() {
+  date -u +"%Y-%m-%dT%H:%M:%S.%3NZ"
+}
+
+# Append one phase line to STREAM_LOG_PATH AND echo to stderr so the Bash
+# tool's stderr capture carries it. Both paths matter: the stream log is
+# the live tailer surface; stderr is the exit-time Bash-tool surface.
+#
+# The stream-log write carries the `script:` chat-surface namespace (Task 605);
+# the stderr mirror stays unprefixed because stderr is read by direct-SSH
+# operators and the route-handler `reason=<enum>` regex, not the chat UI.
+#
+# Usage: phase_line <scope> <key=value …>
+phase_line() {
+  local scope="$1"; shift
+  local ts
+  ts="$(stream_log_ts)"
+  printf '[%s] [script:%s] %s\n' "${ts}" "${scope}" "$*" >> "${STREAM_LOG_PATH}"
+  printf '[%s] %s\n' "${scope}" "$*" >&2
+}
+
+# Tee a subprocess's combined stdout+stderr into STREAM_LOG_PATH line-by-line
+# with the given tag, mirroring each line to stderr for the Bash tool.
+# Returns the subprocess's exit code.
+#
+# Use for fire-and-forget subprocesses whose stdout does NOT need to be
+# captured by the caller (the caller only cares about the exit code).
+# For subprocesses whose stdout the caller must parse (e.g. JSON output
+# feeding `jq`), use `tee_subprocess_capture` instead.
+#
+# Usage: tee_subprocess <tag> -- <cmd> <args …>
+# Example: tee_subprocess reset-tunnel:cloudflared -- cloudflared --origincert … tunnel delete my-tunnel
+#
+# stdbuf forces line buffering; without it cloudflared holds its stdout in
+# libc's 8 KB buffer until exit and the ≤ 1 s latency criterion fails.
+tee_subprocess() {
+  local tag="$1"; shift
+  if [ "${1:-}" != "--" ]; then
+    echo "tee_subprocess: expected -- before command" >&2
+    return 2
+  fi
+  shift
+  # Prefer `stdbuf -oL -eL` to force line buffering on the subprocess; fall
+  # back to the bare command when stdbuf is unavailable (macOS dev). On the
+  # Pi (Linux), stdbuf is present via coreutils and cloudflared's output
+  # reaches the tee as soon as each line is written.
+  local -a buf_prefix=()
+  if command -v stdbuf >/dev/null 2>&1; then
+    buf_prefix=(stdbuf -oL -eL)
+  fi
+  "${buf_prefix[@]}" "$@" 2>&1 | while IFS= read -r line; do
+    local ts
+    ts="$(stream_log_ts)"
+    printf '[%s] [script:%s] %s\n' "${ts}" "${tag}" "${line}" >> "${STREAM_LOG_PATH}"
+    printf '%s\n' "${line}" >&2
+  done
+  return "${PIPESTATUS[0]}"
+}
+
+# Tee a subprocess's combined stdout+stderr into STREAM_LOG_PATH line-by-line
+# with the given tag, passing each line through on stdout so the caller can
+# capture it with `> file` or `$( … )`. Stderr mirroring is dropped so the
+# caller's stdout is exactly the subprocess's output — `jq` and friends
+# remain parseable.
+#
+# Usage: tee_subprocess_capture <tag> -- <cmd> <args …> > captured.file
+# Example:
+#   tee_subprocess_capture reset-tunnel:cloudflared -- \
+#     cloudflared --origincert "${CERT}" tunnel list --output json \
+#     > "${NAMES_TMP}"
+tee_subprocess_capture() {
+  local tag="$1"; shift
+  if [ "${1:-}" != "--" ]; then
+    echo "tee_subprocess_capture: expected -- before command" >&2
+    return 2
+  fi
+  shift
+  # Prefer `stdbuf -oL -eL` to force line buffering on the subprocess; fall
+  # back to the bare command when stdbuf is unavailable (macOS dev). On the
+  # Pi (Linux), stdbuf is present via coreutils and cloudflared's output
+  # reaches the tee as soon as each line is written.
+  local -a buf_prefix=()
+  if command -v stdbuf >/dev/null 2>&1; then
+    buf_prefix=(stdbuf -oL -eL)
+  fi
+  "${buf_prefix[@]}" "$@" 2>&1 | while IFS= read -r line; do
+    local ts
+    ts="$(stream_log_ts)"
+    printf '[%s] [script:%s] %s\n' "${ts}" "${tag}" "${line}" >> "${STREAM_LOG_PATH}"
+    printf '%s\n' "${line}"
+  done
+  return "${PIPESTATUS[0]}"
+}

package/payload/platform/plugins/cloudflare/scripts/list-cf-domains.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Deterministic scrape of the operator's Cloudflare dashboard to discover
+# the domains on the logged-in account. Output on stdout is a JSON `string[]`,
+# sorted and deduped. Every failure exits non-zero with a `reason=<enum>`
+# token on stderr tagged `[list-cf-domains]`.
+#
+# Usage:
+#   list-cf-domains.sh <brand>
+#
+# Task 954: brand arg is REQUIRED — the prior silent default (string
+# fallback to "maxy" when $1 was empty) made every non-Maxy brand's CF
+# setup form fail on first use because the wrapper's child node helper
+# read the Maxy CDP port from a hardcoded fallback. Missing arg now exits
+# 1 with `phase=error reason=brand-arg-missing`.
+#
+# The wrapper also resolves and exports MAXY_PLATFORM_ROOT from its own
+# script location so the .ts helper can read `<root>/config/brand.json` for
+# the brand's `cdpPort` (Task 924's source of truth). Direct-SSH invocation
+# works because the script lives at `<install>/platform/plugins/cloudflare/
+# scripts/`, making platform root three dirs up from the resolved script.
+#
+# Runtime: Node 22's `--experimental-strip-types` runs the .ts helper
+# directly, so no tsx / playwright / ws dependency exists.
+
+set -euo pipefail
+
+# --------------------------------------------------------------------------
+# Shared stream-log helpers (require STREAM_LOG_PATH, phase_line, …).
+# --------------------------------------------------------------------------
+
+# shellcheck source=_stream-log.sh
+# Resolve symlinks before dirname — ~/list-cf-domains.sh is installed as a
+# symlink into $HOME, so the raw BASH_SOURCE[0] points at $HOME, not the
+# scripts directory where _stream-log.sh lives.
+SCRIPT_DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")"
+source "${SCRIPT_DIR}/_stream-log.sh"
+require_stream_log_path list-cf-domains
+
+if [ "$#" -lt 1 ] || [ -z "${1:-}" ]; then
+  phase_line list-cf-domains phase=error reason=brand-arg-missing
+  exit 1
+fi
+
+BRAND="${1}"
+CONFIG_DIR=".${BRAND}"
+mkdir -p "${HOME}/${CONFIG_DIR}/logs"
+
+# MAXY_PLATFORM_ROOT is set by the systemd service when the admin server
+# spawns this script via runFormSpawn. Direct-SSH invocation has no such env
+# so derive it from the resolved script location: scripts/ → cloudflare/ →
+# plugins/ → platform → install root (three dirs up).
+if [ -z "${MAXY_PLATFORM_ROOT:-}" ]; then
+  MAXY_PLATFORM_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+fi
+
+phase_line list-cf-domains phase=script-start brand="${BRAND}" config_dir="${CONFIG_DIR}"
+
+TS_ENTRY="${SCRIPT_DIR}/list-cf-domains.ts"
+
+if [ ! -f "${TS_ENTRY}" ]; then
+  phase_line list-cf-domains phase=error reason=entry-missing path="${TS_ENTRY}"
+  exit 1
+fi
+
+# 30s hard ceiling. The node helper has its own per-phase budgets totalling
+# ~27s; the wrapper's extra 3s absorbs process startup and CF network jitter.
+# Use `timeout --preserve-status` so the exit code of a timeout is distinct
+# (124) from a helper-reported failure (1).
+HARD_TIMEOUT_SECS=30
+
+# Env passed through:
+#  - CONFIG_DIR    — consumed by the node helper when writing selector-drift
+#                    dumps to ~/.${BRAND}/logs/list-cf-domains-<ts>.html.
+#  - BRAND         — names the brand for log lines naming the brand on
+#                    config-class failures (helper does not derive it from
+#                    CONFIG_DIR to keep the two concerns independent).
+#  - MAXY_PLATFORM_ROOT — install root the helper reads `config/brand.json`
+#                    from for `cdpPort`. Resolved above so direct-SSH
+#                    invocation matches the systemd-spawned path.
+#
+# `node --experimental-strip-types` (stable in Node 22.22) runs the .ts file
+# natively: type annotations are stripped, no enums / decorators are used, so
+# no TS type-transform is needed. `--no-warnings` suppresses the experimental
+# banner which would otherwise leak into stderr and confuse the route parser.
+set +e
+CONFIG_DIR="${CONFIG_DIR}" BRAND="${BRAND}" MAXY_PLATFORM_ROOT="${MAXY_PLATFORM_ROOT}" \
+  timeout --preserve-status --signal=TERM "${HARD_TIMEOUT_SECS}" \
+  node --experimental-strip-types --no-warnings "${TS_ENTRY}"
+EXIT_CODE=$?
+set -e
+
+if [ "${EXIT_CODE}" -eq 124 ]; then
+  phase_line list-cf-domains phase=script-exit code=124 reason=wrapper-timeout budget_secs="${HARD_TIMEOUT_SECS}"
+  exit 1
+fi
+
+phase_line list-cf-domains phase=script-exit code="${EXIT_CODE}"
+exit "${EXIT_CODE}"