@rubytech/create-maxy 1.0.627 → 1.0.629

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.627",
+  "version": "1.0.629",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"

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

@@ -0,0 +1,124 @@
+#!/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/api/admin/chat/route.ts tailer and
+# .docs/platform.md):
+#   [<ISO-ts>] [<scope>] <kv …>
+#   [<ISO-ts>] [<scope>:<subprocess-tag>] <raw line>
+# where <scope> ∈ {setup-tunnel, reset-tunnel}. The tailer regex is
+#   ^\[[^]]+\] \[(setup-tunnel|reset-tunnel)(:[^]]+)?\]
+# so any prefix change must be made on both sides atomically.
+
+# 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 (Task 556). 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.
+#
+# Usage: phase_line <scope> <key=value …>
+phase_line() {
+  local scope="$1"; shift
+  local ts
+  ts="$(stream_log_ts)"
+  printf '[%s] [%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] [%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] [%s] %s\n' "${ts}" "${tag}" "${line}" >> "${STREAM_LOG_PATH}"
+    printf '%s\n' "${line}"
+  done
+  return "${PIPESTATUS[0]}"
+}

package/payload/platform/plugins/cloudflare/scripts/reset-tunnel.sh

@@ -19,6 +19,20 @@
 
 set -euo pipefail
 
+# --------------------------------------------------------------------------
+# Shared stream-log helpers (require STREAM_LOG_PATH, phase_line, tee_subprocess).
+# Task 556: any cloudflared subprocess this script spawns is teed line-by-line
+# into the per-conversation stream log so the chat UI tailer renders live
+# progress — same contract as setup-tunnel.sh.
+# --------------------------------------------------------------------------
+
+# shellcheck source=_stream-log.sh
+# Resolve symlinks before dirname — ~/reset-tunnel.sh is installed as a symlink
+# (see packages/create-maxy/src/index.ts:installTunnelScripts), so the raw
+# BASH_SOURCE[0] points at $HOME, not the scripts directory where _stream-log.sh lives.
+source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/_stream-log.sh"
+require_stream_log_path reset-tunnel
+
 if [ "$#" -lt 1 ]; then
   echo "Usage: $0 <brand>" >&2
   exit 2
@@ -28,28 +42,54 @@ BRAND="$1"
 CFG_DIR="${HOME}/.${BRAND}/cloudflared"
 CERT="${CFG_DIR}/cert.pem"
 
+phase_line reset-tunnel step=start brand="${BRAND}" cfg_dir="${CFG_DIR}"
+
 if [ ! -f "${CERT}" ]; then
+  phase_line reset-tunnel step=no-cert cfg_dir="${CFG_DIR}"
   echo "No cert.pem at ${CERT} — nothing to delete via CLI."
   echo "Removing ${CFG_DIR} if present."
   rm -rf "${CFG_DIR}"
+  phase_line reset-tunnel step=done result=wiped-no-cert
   exit 0
 fi
 
 # Delete every tunnel on the account (the cert is per-account for tunnel CRUD).
-NAMES="$(cloudflared --origincert "${CERT}" tunnel list --output json 2>/dev/null \
-  | jq -r '.[]?.name' | sort -u)"
+# cloudflared's list/delete output is teed into STREAM_LOG_PATH; the `list`
+# call uses tee_subprocess_capture so NAMES_TMP receives the JSON for jq to
+# parse. Using the non-capture variant here would strand the JSON in stderr
+# and leave NAMES_TMP empty — every tunnel would silently survive reset.
+phase_line reset-tunnel step=list-tunnels
+NAMES_TMP="$(mktemp -t maxy-reset-tunnel-list.XXXXXX)"
+# shellcheck disable=SC2064
+trap "rm -f '${NAMES_TMP}'" EXIT
+if ! tee_subprocess_capture reset-tunnel:cloudflared -- \
+      cloudflared --origincert "${CERT}" tunnel list --output json \
+      > "${NAMES_TMP}"; then
+  phase_line reset-tunnel step=list-tunnels result=error reason=cloudflared-list-failed
+  echo "ERROR: cloudflared tunnel list failed. See stream log for detail." >&2
+  exit 1
+fi
+NAMES="$(jq -r '.[]?.name' "${NAMES_TMP}" 2>/dev/null | sort -u || true)"
 if [ -z "${NAMES}" ]; then
+  phase_line reset-tunnel step=list-tunnels result=empty
   echo "No tunnels to delete on this brand's account."
 else
   while IFS= read -r NAME; do
     [ -z "${NAME}" ] && continue
+    phase_line reset-tunnel step=delete-tunnel name="${NAME}"
     echo "Deleting tunnel: ${NAME}"
-    cloudflared --origincert "${CERT}" tunnel delete "${NAME}"
+    if ! tee_subprocess reset-tunnel:cloudflared -- \
+          cloudflared --origincert "${CERT}" tunnel delete "${NAME}"; then
+      phase_line reset-tunnel step=delete-tunnel result=error name="${NAME}"
+      echo "ERROR: cloudflared tunnel delete failed for ${NAME}. See stream log." >&2
+      exit 1
+    fi
   done <<< "${NAMES}"
 fi
 
 # Wipe the brand-scoped cloudflared state directory.
 rm -rf "${CFG_DIR}"
+phase_line reset-tunnel step=wipe-cfg-dir path="${CFG_DIR}"
 echo "Removed ${CFG_DIR}"
 
 echo ""
@@ -63,3 +103,5 @@ echo "The platform service (${BRAND}.service) was not touched. To release any"
 echo "running cloudflared connector started by ${BRAND}.service's ExecStartPre,"
 echo "either restart the service (which will no-op on resume since tunnel.state"
 echo "is gone) or leave it running until you re-run setup-tunnel.sh."
+
+phase_line reset-tunnel step=done result=ok brand="${BRAND}"

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -13,9 +13,28 @@
 # via `cloudflared tunnel route dns` — see manual-setup.md §Step 4 Apex
 # hostnames. The script writes the ingress rule for them but prints an
 # explicit ACTION REQUIRED message naming the manual dashboard step.
+#
+# Task 556: Step 1 owns the browser-spawn deterministically. Instead of
+# delegating to cloudflared's xdg-open (which silently degrades to "print
+# URL and wait"), the script drives Chromium on :99 via CDP `PUT /json/new?<url>`
+# on http://127.0.0.1:9222 — the same mechanism
+# /api/admin/device-browser/navigate uses. cloudflared's stdout+stderr is
+# teed line-by-line into STREAM_LOG_PATH so the chat UI's server-side
+# tailer renders live progress in-turn.
 
 set -euo pipefail
 
+# --------------------------------------------------------------------------
+# Shared stream-log helpers (require STREAM_LOG_PATH, phase_line, …).
+# --------------------------------------------------------------------------
+
+# shellcheck source=_stream-log.sh
+# Resolve symlinks before dirname — ~/setup-tunnel.sh is installed as a symlink
+# (see packages/create-maxy/src/index.ts:installTunnelScripts), so the raw
+# BASH_SOURCE[0] points at $HOME, not the scripts directory where _stream-log.sh lives.
+source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/_stream-log.sh"
+require_stream_log_path setup-tunnel
+
 # --------------------------------------------------------------------------
 # Args
 # --------------------------------------------------------------------------
@@ -31,6 +50,8 @@ PORT="$2"
 shift 2
 HOSTNAMES=("$@")
 
+phase_line setup-tunnel step=start brand="${BRAND}" port="${PORT}" hostnames="${HOSTNAMES[*]}"
+
 # --------------------------------------------------------------------------
 # Step 0: Set brand context (paths + dirs). Corresponds to runbook Step 0.
 # --------------------------------------------------------------------------
@@ -40,24 +61,144 @@ mkdir -p "${CFG_DIR}"
 
 # --------------------------------------------------------------------------
 # Step 1: OAuth login (only if cert.pem missing). Corresponds to runbook Step 1.
-# cloudflared always writes cert.pem to ~/.cloudflared/cert.pem regardless
-# of --origincert — mv it into the brand-scoped path on fresh login.
+#
+# Control flow, rewritten per Task 556:
+#   1. CDP precheck on 127.0.0.1:9222 — loud failure if Chromium isn't up.
+#   2. Spawn cloudflared with stdout+stderr teed line-by-line to
+#      $STREAM_LOG_PATH with prefix [setup-tunnel:cloudflared].
+#   3. Extract the authorize URL with a tolerant regex as it streams.
+#   4. Drive the VNC Chromium to that URL via CDP `PUT /json/new?<url>`.
+#   5. Wait for ~/.cloudflared/cert.pem to land with bounded timeout.
+#   6. Move cert.pem into the brand-scoped path.
+#
+# Every branch exits 1 loudly naming the failure — no silent retries,
+# no xdg-open race, no cloudflared-internal browser-spawn path.
 # --------------------------------------------------------------------------
 
 if [ ! -f "${CFG_DIR}/cert.pem" ]; then
-  echo "No cert.pem at ${CFG_DIR}/cert.pem — starting OAuth login (DISPLAY=${DISPLAY:-:99})"
-  DISPLAY="${DISPLAY:-:99}" cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel login &
-  LOGIN_PID=$!
-  # cloudflared login writes to ~/.cloudflared/cert.pem regardless of --origincert
+  phase_line setup-tunnel step=oauth-login cert_path="${CFG_DIR}/cert.pem" display="${DISPLAY:-:99}"
+
+  # CDP precheck — fail loudly if Chromium DevTools is not answering.
+  if ! curl -sf --max-time 2 "http://127.0.0.1:9222/json/version" > /dev/null 2>&1; then
+    phase_line setup-tunnel step=oauth-login result=error reason=cdp-unreachable \
+      endpoint=http://127.0.0.1:9222 hint="run ~/vnc.sh restart"
+    echo "ERROR: Chromium CDP on 127.0.0.1:9222 is not reachable." >&2
+    echo "       The script needs CDP to drive the authorize URL on the VNC browser." >&2
+    echo "       Fix: run 'vnc.sh restart' to bring Chromium up on :99." >&2
+    exit 1
+  fi
+  phase_line setup-tunnel step=oauth-login cdp=ok
+
+  URL_FILE="$(mktemp -t maxy-setup-tunnel-url.XXXXXX)"
+  LAST_LINE_FILE="$(mktemp -t maxy-setup-tunnel-last.XXXXXX)"
+  : > "${URL_FILE}"
+  : > "${LAST_LINE_FILE}"
+  # Track the cloudflared pipeline PID so the EXIT trap can kill it on any
+  # failure path — including ones that `exit 1` without an explicit kill.
+  # Missing this trap leaks a cloudflared subshell waiting for the OAuth
+  # callback forever; subsequent setup-tunnel runs see a stale cert.pem
+  # landing asynchronously and race against the new URL-extraction pass.
+  CF_PIPELINE_PID=""
+  cleanup_oauth() {
+    [ -n "${CF_PIPELINE_PID}" ] && kill "${CF_PIPELINE_PID}" 2>/dev/null || true
+    rm -f "${URL_FILE}" "${LAST_LINE_FILE}"
+  }
+  trap cleanup_oauth EXIT
+
+  # cloudflared is line-buffered (stdbuf), teed to the stream log, URL
+  # extracted as it streams. The subshell holds the whole pipeline so
+  # PIPESTATUS[0] (cloudflared's exit code) is reachable later.
+  (
+    DISPLAY="${DISPLAY:-:99}" stdbuf -oL -eL cloudflared \
+      --origincert "${CFG_DIR}/cert.pem" tunnel login 2>&1 |
+      while IFS= read -r line; do
+        ts="$(stream_log_ts)"
+        printf '[%s] [setup-tunnel:cloudflared] %s\n' "${ts}" "${line}" >> "${STREAM_LOG_PATH}"
+        printf '%s\n' "${line}" >&2
+        printf '%s\n' "${line}" > "${LAST_LINE_FILE}"
+        if [ ! -s "${URL_FILE}" ]; then
+          url="$(printf '%s' "${line}" | grep -oE 'https://dash\.cloudflare\.com/argotunnel\?[^ ]+' | head -1 || true)"
+          if [ -n "${url}" ]; then
+            printf '%s' "${url}" > "${URL_FILE}"
+          fi
+        fi
+      done
+  ) &
+  CF_PIPELINE_PID=$!
+
+  # Wait up to ~15s for the URL to surface in cloudflared's output.
+  URL_WAIT=0
+  while [ ! -s "${URL_FILE}" ] && [ "${URL_WAIT}" -lt 30 ]; do
+    if ! kill -0 "${CF_PIPELINE_PID}" 2>/dev/null; then
+      phase_line setup-tunnel step=oauth-login result=error \
+        reason=cloudflared-exited-before-url \
+        last_line="$(cat "${LAST_LINE_FILE}" 2>/dev/null || echo none)"
+      echo "ERROR: cloudflared exited before printing the authorize URL." >&2
+      exit 1
+    fi
+    sleep 0.5
+    URL_WAIT=$((URL_WAIT + 1))
+  done
+
+  if [ ! -s "${URL_FILE}" ]; then
+    kill "${CF_PIPELINE_PID}" 2>/dev/null || true
+    phase_line setup-tunnel step=oauth-login result=error \
+      reason=url-not-extracted waited=15s \
+      last_line="$(cat "${LAST_LINE_FILE}" 2>/dev/null || echo none)"
+    echo "ERROR: cloudflared ran for ~15s without emitting a dash.cloudflare.com/argotunnel URL." >&2
+    echo "       cloudflared output-format may have changed. Check the stream log tail for the raw lines." >&2
+    exit 1
+  fi
+
+  AUTH_URL="$(cat "${URL_FILE}")"
+  phase_line setup-tunnel step=browser-drive url_extracted=1
+
+  # Drive CDP. Same PUT /json/new?<url> contract as
+  # platform/ui/app/lib/cdp-client.ts (which uses encodeURIComponent on
+  # the URL). Without percent-encoding, CDP's URL parser splits on the
+  # inner `?` and `&` in the argotunnel URL and drops the callback/token
+  # query params — Chromium lands on a bare argotunnel page and the
+  # consent screen is never reached. `jq -sRr @uri` percent-encodes a raw
+  # string, matching the TS client exactly.
+  AUTH_URL_ENC="$(printf '%s' "${AUTH_URL}" | jq -sRr @uri)"
+  CDP_RESP="$(curl -sf --max-time 5 -X PUT "http://127.0.0.1:9222/json/new?${AUTH_URL_ENC}" 2>&1 || true)"
+  if [ -z "${CDP_RESP}" ]; then
+    kill "${CF_PIPELINE_PID}" 2>/dev/null || true
+    phase_line setup-tunnel step=browser-drive result=error reason=cdp-put-failed
+    echo "ERROR: CDP PUT /json/new?<url> returned empty — Chromium rejected the navigate." >&2
+    exit 1
+  fi
+  phase_line setup-tunnel step=browser-drive result=accepted
+
+  # Wait for cert.pem to land — cloudflared writes to ~/.cloudflared/cert.pem
+  # regardless of --origincert, so watch the canonical location.
+  LOGIN_TIMEOUT="${SETUP_TUNNEL_LOGIN_TIMEOUT:-180}"
+  LOGIN_WAIT=0
   while [ ! -f "${HOME}/.cloudflared/cert.pem" ]; do
-    if ! kill -0 "${LOGIN_PID}" 2>/dev/null; then
-      echo "ERROR: cloudflared tunnel login exited before cert.pem landed" >&2
+    if ! kill -0 "${CF_PIPELINE_PID}" 2>/dev/null; then
+      # Pipeline exited — one more cert.pem probe in case it landed right before exit.
+      if [ -f "${HOME}/.cloudflared/cert.pem" ]; then break; fi
+      phase_line setup-tunnel step=oauth-login result=error \
+        reason=cloudflared-exited-no-cert \
+        last_line="$(cat "${LAST_LINE_FILE}" 2>/dev/null || echo none)"
+      echo "ERROR: cloudflared exited before cert.pem landed." >&2
       exit 1
     fi
-    sleep 2
+    if [ "${LOGIN_WAIT}" -ge "${LOGIN_TIMEOUT}" ]; then
+      kill "${CF_PIPELINE_PID}" 2>/dev/null || true
+      phase_line setup-tunnel step=oauth-login result=error \
+        reason=timeout-waiting-cert waited="${LOGIN_WAIT}s" \
+        last_line="$(cat "${LAST_LINE_FILE}" 2>/dev/null || echo none)"
+      echo "ERROR: Timed out after ${LOGIN_WAIT}s waiting for cert.pem to land." >&2
+      exit 1
+    fi
+    sleep 1
+    LOGIN_WAIT=$((LOGIN_WAIT + 1))
   done
+
   mv "${HOME}/.cloudflared/cert.pem" "${CFG_DIR}/cert.pem"
-  echo "cert.pem moved to ${CFG_DIR}/cert.pem"
+  phase_line setup-tunnel step=oauth-login result=cert-received \
+    path="${CFG_DIR}/cert.pem" waited="${LOGIN_WAIT}s"
 fi
 
 # --------------------------------------------------------------------------

package/payload/platform/plugins/docs/references/plugins-guide.md

@@ -103,6 +103,8 @@ After this, every `console.error("[your-tool] ...")` from any tool in the plugin
 
 **How the tee decides which file to write to (Task 532):** the platform sets `STREAM_LOG_PATH` as an environment variable on every MCP server spawn, pointing to the conversation-scoped stream log. The MCP server does not know about conversations — it just trusts `STREAM_LOG_PATH`. Multiple concurrent conversations produce multiple concurrent MCP server processes, each teeing to its own file; no cross-conversation leakage.
 
+**`STREAM_LOG_PATH` reaches every Claude Code child (Task 556).** The platform now sets `STREAM_LOG_PATH` on the parent `claude` spawn env itself (not only on MCP server envs), so the bundled Bun runtime inherits it and every Bash-tool subprocess the CLI spawns sees it too. Opt-in shell scripts — currently `setup-tunnel.sh` and `reset-tunnel.sh` under `platform/plugins/cloudflare/scripts/` — read the variable, guard against a missing value with a loud exit, and tee subprocess output line-by-line into the same per-conversation file. Each spawn writes one `[spawn-env] STREAM_LOG_PATH=set pid=… conversationId=… site=…` line so the env-propagation is auditable per session. The chat UI tails the same file for lines matching `^\[[^]]+\] \[(setup-tunnel|reset-tunnel)(:[^]]+)?\] ` and emits them as `script_stream` SSE events; see `.docs/web-chat.md` for the contract.
+
 **Retrieve MCP diagnostic lines for a conversation:**
 
 - All servers: `logs-read { type: "system", conversationId: "..." }` → grep `[mcp:<name>]` on the returned stream log.