@rubytech/create-realagent-code 0.1.19 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent-code",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent-code": "./dist/index.js"

package/payload/platform/plugins/docs/references/deployment.md

@@ -62,6 +62,10 @@ Failure signals to grep in `~/.maxy/logs/server.log` (or `~/.realagent/logs/serv
 - `[onboarding-gate] step=null complete=true` (the pre-Task-033 bug)
 - missing `[skill-load] name=onboarding` while `[onboarding-gate]` reports `complete=false`
 
+### QA regression replay
+
+`platform/scripts/qa/onboarding-fresh-install.sh <brand> [--watch]` replays the success chain end-to-end on a freshly-installed Pi. It exits zero only when every line above lands, and exits non-zero with the missing line named verbatim on any miss — so a future regression in this chain is caught by replay instead of by a customer. Pass `--watch` to keep polling Neo4j while the operator drives steps 1–9 in the UI; each `currentStep` advance asserts the matching `stepNCompletedAt` is persisted before the next step renders. Provide the admin PIN via `MAXY_ADMIN_PIN`.
+
 ## Service Management
 
 {{productName}} runs via systemd and starts automatically on boot. You don't need to start it manually. To check if it's running, ask {{productName}} "Check system status."

package/payload/platform/scripts/qa/onboarding-fresh-install.sh

@@ -0,0 +1,435 @@
+#!/usr/bin/env bash
+# Task 035 — Onboarding fresh-install Pi integration script.
+#
+# Replays the Task 033 success chain against a freshly-installed brand on
+# this Pi (Maxy Code or Real Agent Code). Exit zero ↔ the entire chain is
+# observable end-to-end. Any miss exits non-zero with the failing
+# observability line named verbatim.
+#
+# Success chain (fresh install, currentStep=0):
+#   [onboarding-seed] currentStep=0
+#     → installer log
+#   [install-invariant] onboarding-state-present
+#     → installer log
+#   [onboarding-gate] step=0 complete=false phase=create
+#     → server.log, fires on POST /api/admin/session
+#   [onboarding-inject] agent=admin step=0 injected=true
+#     → server.log, fires on first POST /api/admin/claude-sessions/:id/input
+#   [skill-load] skillName=onboarding result=unique
+#     → server.log, fires when admin MCP serves skill-load for the agent
+#
+# CONTRACT
+#   Exit 0 — every chain link landed; --watch (if set) walked 9 steps.
+#   Exit 1 — at least one chain assertion failed; missing line(s) named
+#            verbatim in the final report.
+#   Exit 2 — environment fault (cypher-shell unreachable, brand.json
+#            missing, refused-as-non-fresh-install, etc.) — never PASS.
+#
+# USAGE
+#   $ onboarding-fresh-install.sh <brand> [--watch]
+#
+#   <brand>   maxy-code | realagent-code (matches brands/<brand>/brand.json).
+#   --watch   After the fresh-install chain passes, poll Neo4j every 2s.
+#             For every observed currentStep advance N→N+1, assert that
+#             step(N+1)CompletedAt is non-null at the same moment. Exits 0
+#             when currentStep reaches 9 or the operator presses Ctrl-C
+#             after at least one advance.
+#
+# ENV
+#   MAXY_ADMIN_PIN   Admin PIN (required for the session-mint step).
+#                    May also be passed as the 2nd positional argument.
+#   MAXY_NEO4J_PASSWORD
+#                    Neo4j password (default: read from <installDir>/platform/config/.neo4j-password if present).
+#   MAXY_QA_TIMEOUT  Seconds to wait for the runtime log lines to appear
+#                    after the first /input call (default 30).
+#   MAXY_QA_HOST     Admin host (default 127.0.0.1).
+#
+# OUT-OF-SCOPE (per task 035)
+#   * Multi-Pi orchestration — one brand per invocation.
+#   * CI pipeline gating.
+#   * Driving steps 1–9 by curl. Steps 7 (Cloudflare OAuth), 8 (Anthropic
+#     API key paste), and 9 (free-form business profile data) cannot be
+#     deterministically scripted on a fresh install; the operator drives
+#     each step in the UI under --watch while this script polls Neo4j.
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Argv + env
+# ---------------------------------------------------------------------------
+
+if [ $# -lt 1 ]; then
+  echo "usage: $0 <brand> [--watch] [pin]" >&2
+  echo "       <brand> = maxy-code | realagent-code" >&2
+  exit 2
+fi
+
+BRAND=""
+WATCH=0
+PIN_POSITIONAL=""
+for arg in "$@"; do
+  case "$arg" in
+    --watch) WATCH=1 ;;
+    -*) echo "unknown flag: $arg" >&2; exit 2 ;;
+    *) if [ -z "$BRAND" ]; then BRAND="$arg"; else PIN_POSITIONAL="$arg"; fi ;;
+  esac
+done
+
+if [ -z "$BRAND" ]; then
+  echo "error: brand argument required" >&2
+  exit 2
+fi
+
+PIN="${MAXY_ADMIN_PIN:-$PIN_POSITIONAL}"
+if [ -z "$PIN" ]; then
+  echo "error: PIN required — set MAXY_ADMIN_PIN env or pass as second positional argument" >&2
+  exit 2
+fi
+
+HOST="${MAXY_QA_HOST:-127.0.0.1}"
+TIMEOUT="${MAXY_QA_TIMEOUT:-30}"
+
+# ---------------------------------------------------------------------------
+# Brand resolution — read live brand.json on the Pi for ports + paths.
+# ---------------------------------------------------------------------------
+
+INSTALL_DIR="$HOME/$BRAND"
+BRAND_JSON="$INSTALL_DIR/platform/config/brand.json"
+LOG_DIR="$HOME/.$BRAND/logs"
+SERVER_LOG="$LOG_DIR/server.log"
+
+if [ ! -f "$BRAND_JSON" ]; then
+  echo "error: brand.json not found at $BRAND_JSON" >&2
+  echo "hint: this script expects a brand installed via @rubytech/create-${BRAND}" >&2
+  exit 2
+fi
+
+# jq is on the deployment-doctrine list; if it's absent, the script must
+# loud-fail rather than fall back to a regex parse of brand.json.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "error: jq required but not installed" >&2
+  exit 2
+fi
+
+NEO4J_PORT="$(jq -r '.neo4jPort' "$BRAND_JSON")"
+if [ -z "$NEO4J_PORT" ] || [ "$NEO4J_PORT" = "null" ]; then
+  echo "error: brand.json at $BRAND_JSON has no neo4jPort field" >&2
+  exit 2
+fi
+
+# Admin server PORT is set by the installer as a systemd Environment var, not
+# in brand.json (verified packages/create-maxy-code/src/port-resolution.ts).
+# Resolution order: MAXY_QA_PORT env → systemctl --user show <serviceName>
+# → fail loud (never a hard-coded default — silent-fallback masks root cause).
+ADMIN_PORT="${MAXY_QA_PORT:-}"
+if [ -z "$ADMIN_PORT" ]; then
+  SERVICE_NAME="$(jq -r '.serviceName' "$BRAND_JSON")"
+  if [ -n "$SERVICE_NAME" ] && [ "$SERVICE_NAME" != "null" ] && command -v systemctl >/dev/null 2>&1; then
+    ADMIN_PORT="$(systemctl --user show "$SERVICE_NAME" -p Environment 2>/dev/null \
+      | tr ' ' '\n' \
+      | grep -E '^PORT=' \
+      | head -n 1 \
+      | cut -d= -f2)"
+  fi
+fi
+if [ -z "$ADMIN_PORT" ]; then
+  echo "error: admin PORT not resolvable — set MAXY_QA_PORT env (e.g. MAXY_QA_PORT=19200)" >&2
+  exit 2
+fi
+
+NEO4J_URI="bolt://localhost:$NEO4J_PORT"
+ADMIN_BASE="http://$HOST:$ADMIN_PORT"
+
+NEO4J_PASSWORD="${MAXY_NEO4J_PASSWORD:-}"
+NEO4J_PASSWORD_FILE="$INSTALL_DIR/platform/config/.neo4j-password"
+if [ -z "$NEO4J_PASSWORD" ] && [ -r "$NEO4J_PASSWORD_FILE" ]; then
+  NEO4J_PASSWORD="$(cat "$NEO4J_PASSWORD_FILE")"
+fi
+if [ -z "$NEO4J_PASSWORD" ]; then
+  echo "error: Neo4j password required — set MAXY_NEO4J_PASSWORD env or place it at $NEO4J_PASSWORD_FILE" >&2
+  exit 2
+fi
+
+for tool in cypher-shell curl grep tail; do
+  if ! command -v "$tool" >/dev/null 2>&1; then
+    echo "error: $tool not on PATH" >&2
+    exit 2
+  fi
+done
+
+# ---------------------------------------------------------------------------
+# Cypher helper — exit 2 on unreachable, captures stderr tail for the report.
+# ---------------------------------------------------------------------------
+
+cypher() {
+  local query="$1"
+  cypher-shell -u neo4j -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" --format plain "$query"
+}
+
+cypher_or_die() {
+  local query="$1"
+  local out
+  if ! out="$(cypher "$query" 2>&1)"; then
+    echo "error: cypher-shell unreachable at $NEO4J_URI" >&2
+    echo "$out" | tail -n 5 >&2
+    exit 2
+  fi
+  printf '%s' "$out"
+}
+
+# ---------------------------------------------------------------------------
+# Assertion bookkeeping — every assertion appends one row to the report so
+# the final block names every link verbatim, pass or fail.
+# ---------------------------------------------------------------------------
+
+REPORT=()
+FAIL_COUNT=0
+
+record() {
+  # record <status> <label> <detail>
+  REPORT+=("$1|$2|$3")
+  if [ "$1" = "FAIL" ]; then
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+  fi
+}
+
+print_report() {
+  echo ""
+  echo "## onboarding fresh-install — final report"
+  echo ""
+  printf '| %-4s | %-50s | %s\n' "Step" "Assertion" "Detail"
+  printf '|------|----------------------------------------------------|-----\n'
+  local i=1
+  for row in "${REPORT[@]}"; do
+    local status="${row%%|*}"
+    local rest="${row#*|}"
+    local label="${rest%%|*}"
+    local detail="${rest#*|}"
+    local marker
+    case "$status" in
+      PASS) marker="PASS" ;;
+      FAIL) marker="FAIL" ;;
+      *)    marker="$status" ;;
+    esac
+    printf '| %-4s | %-50s | %s\n' "$marker" "$label" "$detail"
+    i=$((i + 1))
+  done
+  echo ""
+  echo "brand=$BRAND neo4j=$NEO4J_URI logs=$LOG_DIR"
+}
+
+# ---------------------------------------------------------------------------
+# Step 1 — Pre-flight: refuse if not a fresh install.
+# ---------------------------------------------------------------------------
+
+echo "[1/6] Pre-flight: assert OnboardingState{currentStep:0}"
+PREFLIGHT_OUT="$(cypher_or_die 'MATCH (o:OnboardingState) RETURN o.accountId AS accountId, o.currentStep AS currentStep, o.createdAt AS createdAt')"
+ROW_COUNT="$(printf '%s' "$PREFLIGHT_OUT" | tail -n +2 | grep -c . || true)"
+
+if [ "$ROW_COUNT" -eq 0 ]; then
+  echo "error: not a fresh install — no OnboardingState row exists" >&2
+  echo "hint: the installer's [install-invariant] onboarding-state-MISSING line would have fired; check ~/.${BRAND}/logs/install-*.log" >&2
+  exit 2
+fi
+if [ "$ROW_COUNT" -gt 1 ]; then
+  echo "error: not a fresh install — $ROW_COUNT OnboardingState rows exist (expected 1)" >&2
+  printf '%s\n' "$PREFLIGHT_OUT" >&2
+  exit 2
+fi
+
+CURRENT_STEP="$(printf '%s' "$PREFLIGHT_OUT" | tail -n 1 | awk -F', ' '{print $2}')"
+ACCOUNT_ID="$(printf '%s' "$PREFLIGHT_OUT" | tail -n 1 | awk -F', ' '{print $1}' | tr -d '"')"
+CREATED_AT="$(printf '%s' "$PREFLIGHT_OUT" | tail -n 1 | awk -F', ' '{print $3}' | tr -d '"')"
+
+if [ "$CURRENT_STEP" != "0" ]; then
+  echo "error: not a fresh install — currentStep=$CURRENT_STEP (refusing to drive on top of completed state)" >&2
+  echo "expected: currentStep=0" >&2
+  echo "actual:   $PREFLIGHT_OUT" >&2
+  exit 2
+fi
+record PASS "pre-flight: OnboardingState{currentStep:0}" "accountId=${ACCOUNT_ID:0:8} createdAt=$CREATED_AT"
+
+# ---------------------------------------------------------------------------
+# Step 2 — Installer log: [onboarding-seed] currentStep=0 + [install-invariant] onboarding-state-present.
+#
+# Installer logs live in $LOG_DIR/install-*.log (separate from server.log).
+# Both lines fire once per install run; pin to the newest install log so a
+# stale prior install on the same Pi cannot produce a false PASS.
+# ---------------------------------------------------------------------------
+
+echo "[2/6] Installer log: [onboarding-seed] + [install-invariant] onboarding-state-present"
+LATEST_INSTALL_LOG="$(ls -t "$LOG_DIR"/install-*.log 2>/dev/null | head -n 1 || true)"
+if [ -z "$LATEST_INSTALL_LOG" ]; then
+  record FAIL "[onboarding-seed] currentStep=0" "no install log under $LOG_DIR"
+  record FAIL "[install-invariant] onboarding-state-present" "no install log under $LOG_DIR"
+else
+  if grep -qF "[onboarding-seed] accountId=$ACCOUNT_ID currentStep=0" "$LATEST_INSTALL_LOG"; then
+    record PASS "[onboarding-seed] currentStep=0" "$(basename "$LATEST_INSTALL_LOG")"
+  else
+    record FAIL "[onboarding-seed] currentStep=0" "missing from $(basename "$LATEST_INSTALL_LOG")"
+  fi
+  if grep -qF "[install-invariant] onboarding-state-present accountId=$ACCOUNT_ID" "$LATEST_INSTALL_LOG"; then
+    record PASS "[install-invariant] onboarding-state-present" "$(basename "$LATEST_INSTALL_LOG")"
+  else
+    record FAIL "[install-invariant] onboarding-state-present" "missing from $(basename "$LATEST_INSTALL_LOG")"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Step 3 — POST /api/admin/session: assert onboardingComplete:false in response,
+# then assert [onboarding-gate] step=0 complete=false in server.log.
+# ---------------------------------------------------------------------------
+
+echo "[3/6] Mint admin session via PIN and assert [onboarding-gate] step=0 complete=false"
+TURN_MARKER_BEFORE="$(wc -l < "$SERVER_LOG" 2>/dev/null | tr -d ' ' || echo 0)"
+TURN_MARKER_BEFORE="${TURN_MARKER_BEFORE:-0}"
+SESSION_RESPONSE="$(curl -sS -X POST "$ADMIN_BASE/api/admin/session" \
+  -H 'content-type: application/json' \
+  -d "{\"pin\":\"$PIN\"}")" || {
+    record FAIL "POST /api/admin/session" "curl failed against $ADMIN_BASE"
+    print_report
+    exit 1
+  }
+
+if ! printf '%s' "$SESSION_RESPONSE" | jq -e '.onboardingComplete == false' >/dev/null 2>&1; then
+  record FAIL "POST /api/admin/session onboardingComplete:false" "response=$SESSION_RESPONSE"
+  print_report
+  exit 1
+fi
+SESSION_KEY="$(printf '%s' "$SESSION_RESPONSE" | jq -r '.session_key')"
+if [ -z "$SESSION_KEY" ] || [ "$SESSION_KEY" = "null" ]; then
+  record FAIL "session_key" "absent in /api/admin/session response"
+  print_report
+  exit 1
+fi
+record PASS "POST /api/admin/session onboardingComplete:false" "session minted"
+
+# Tail server.log from the byte offset captured before the call. grep -F
+# matches the substring literally — the gate phrasing in session.ts:193 is
+# `[onboarding-gate] session=... accountId=... step=0 complete=false phase=create`.
+if tail -n +"$TURN_MARKER_BEFORE" "$SERVER_LOG" 2>/dev/null | grep -qF "[onboarding-gate]"  \
+  && tail -n +"$TURN_MARKER_BEFORE" "$SERVER_LOG" 2>/dev/null | grep -F "[onboarding-gate]" | grep -qF "step=0 complete=false"; then
+  record PASS "[onboarding-gate] step=0 complete=false" "phase=create"
+else
+  record FAIL "[onboarding-gate] step=0 complete=false" "not found in $SERVER_LOG since session-mint"
+fi
+
+# ---------------------------------------------------------------------------
+# Step 4 — Spawn an admin claude-session so the next /input is injection-eligible.
+# ---------------------------------------------------------------------------
+
+echo "[4/6] Spawn admin claude-session and capture sessionId"
+SPAWN_RESPONSE="$(curl -sS -X POST "$ADMIN_BASE/api/admin/claude-sessions/?session_key=$SESSION_KEY" \
+  -H 'content-type: application/json' \
+  -d '{"channel":"browser"}')" || {
+    record FAIL "POST /api/admin/claude-sessions/" "curl failed"
+    print_report
+    exit 1
+  }
+SESSION_ID="$(printf '%s' "$SPAWN_RESPONSE" | jq -r '.sessionId // empty')"
+if [ -z "$SESSION_ID" ]; then
+  record FAIL "POST /api/admin/claude-sessions/" "no sessionId in response: $SPAWN_RESPONSE"
+  print_report
+  exit 1
+fi
+record PASS "spawn claude-session" "sessionId=${SESSION_ID:0:8}"
+
+# ---------------------------------------------------------------------------
+# Step 5 — First /input call. This triggers buildOnboardingPromptBlock,
+# which logs [onboarding-inject] step=0 injected=true. The agent then runs
+# the prepended skill-load directive, which logs [skill-load] skillName=onboarding.
+# ---------------------------------------------------------------------------
+
+echo "[5/6] Submit first admin input and wait up to ${TIMEOUT}s for [onboarding-inject] and [skill-load]"
+INPUT_MARKER_BEFORE="$(wc -l < "$SERVER_LOG" 2>/dev/null | tr -d ' ' || echo 0)"
+INPUT_MARKER_BEFORE="${INPUT_MARKER_BEFORE:-0}"
+INPUT_RESPONSE="$(curl -sS -X POST "$ADMIN_BASE/api/admin/claude-sessions/$SESSION_ID/input?session_key=$SESSION_KEY" \
+  -H 'content-type: application/json' \
+  -d '{"text":"hello"}')" || {
+    record FAIL "POST /api/admin/claude-sessions/:id/input" "curl failed"
+    print_report
+    exit 1
+  }
+# Status-only check — the manager owns the per-input contract.
+record PASS "POST first /input" "(skill-load arrives async)"
+
+# Poll-tail server.log for the two remaining lines.
+deadline=$(( $(date +%s) + TIMEOUT ))
+inject_seen=0
+skill_seen=0
+while [ "$(date +%s)" -lt "$deadline" ]; do
+  if [ "$inject_seen" -eq 0 ] \
+    && tail -n +"$INPUT_MARKER_BEFORE" "$SERVER_LOG" 2>/dev/null | grep -F "[onboarding-inject]" | grep -qF "step=0 injected=true"; then
+    inject_seen=1
+  fi
+  if [ "$skill_seen" -eq 0 ] \
+    && tail -n +"$INPUT_MARKER_BEFORE" "$SERVER_LOG" 2>/dev/null | grep -F "[skill-load]" | grep -qF "skillName=onboarding"; then
+    skill_seen=1
+  fi
+  if [ "$inject_seen" -eq 1 ] && [ "$skill_seen" -eq 1 ]; then break; fi
+  sleep 1
+done
+
+if [ "$inject_seen" -eq 1 ]; then
+  record PASS "[onboarding-inject] step=0 injected=true" "server.log"
+else
+  record FAIL "[onboarding-inject] step=0 injected=true" "not found within ${TIMEOUT}s"
+fi
+if [ "$skill_seen" -eq 1 ]; then
+  record PASS "[skill-load] skillName=onboarding" "server.log"
+else
+  record FAIL "[skill-load] skillName=onboarding" "not found within ${TIMEOUT}s"
+fi
+
+# ---------------------------------------------------------------------------
+# Step 6 — --watch mode: poll Neo4j and assert step-advance + timestamp.
+#
+# The operator drives steps 1–9 in the UI. For every observed currentStep
+# transition N→N+1, assert step(N+1)CompletedAt is non-null at the same
+# moment. The script never advances steps itself — steps 7 (Cloudflare
+# OAuth), 8 (Anthropic API key paste), and 9 (free-form business profile)
+# require operator-side inputs that cannot be forged from a script.
+# ---------------------------------------------------------------------------
+
+if [ "$FAIL_COUNT" -gt 0 ]; then
+  print_report
+  echo "Fresh-install chain failed before --watch could start." >&2
+  exit 1
+fi
+
+if [ "$WATCH" -eq 1 ]; then
+  echo "[6/6] --watch: polling Neo4j every 2s. Drive steps 1-9 in the UI now. Ctrl-C to abort."
+  last_step="$CURRENT_STEP"
+  while :; do
+    sleep 2
+    WATCH_OUT="$(cypher_or_die 'MATCH (o:OnboardingState) RETURN o.currentStep AS s, o.step1CompletedAt AS s1, o.step2CompletedAt AS s2, o.step3CompletedAt AS s3, o.step4CompletedAt AS s4, o.step5CompletedAt AS s5, o.step6CompletedAt AS s6, o.step7CompletedAt AS s7, o.step8CompletedAt AS s8, o.step9CompletedAt AS s9')"
+    NOW_STEP="$(printf '%s' "$WATCH_OUT" | tail -n 1 | awk -F', ' '{print $1}')"
+    if [ "$NOW_STEP" = "$last_step" ]; then continue; fi
+    # Advance observed. Check the timestamp for the new step.
+    new_step="$NOW_STEP"
+    if [ "$new_step" -le "$last_step" ]; then
+      record FAIL "step regression" "last=$last_step now=$new_step"
+      print_report
+      exit 1
+    fi
+    ts_field=$(( new_step + 1 ))  # awk fields are 1-indexed; currentStep is field 1, stepNCompletedAt is field N+1.
+    stamp="$(printf '%s' "$WATCH_OUT" | tail -n 1 | awk -F', ' "{print \$$ts_field}" | tr -d '"')"
+    if [ -z "$stamp" ] || [ "$stamp" = "NULL" ] || [ "$stamp" = "null" ]; then
+      record FAIL "step$new_step advanced without timestamp" "step${new_step}CompletedAt is NULL"
+      print_report
+      exit 1
+    fi
+    record PASS "step $new_step advance" "step${new_step}CompletedAt=$stamp"
+    last_step="$new_step"
+    if [ "$new_step" -ge 9 ]; then
+      echo "  currentStep=9 — onboarding complete"
+      break
+    fi
+  done
+fi
+
+print_report
+if [ "$FAIL_COUNT" -gt 0 ]; then
+  exit 1
+fi
+exit 0