@rubytech/create-realagent-code 0.1.17 → 0.1.18

package/dist/__tests__/onboarding-state-readback.test.js

@@ -0,0 +1,61 @@
+// Task 033 — install-invariant for OnboardingState seed.
+//
+// The installer re-reads Neo4j after seed-neo4j.sh to verify the
+// OnboardingState node landed. The parser turns cypher-shell's plain-
+// format output into a tri-state outcome consumed by the loud-fail
+// branch in src/index.ts. These tests fence the three outcomes the
+// installer logs name: present / missing / unreachable.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { classifyOnboardingReadBack } from "../onboarding-readback.js";
+test("non-zero exit → unreachable, with stderr tail captured", () => {
+    const outcome = classifyOnboardingReadBack({
+        status: 1,
+        stdout: "",
+        stderr: "Connection refused: bolt://localhost:7687",
+    });
+    assert.equal(outcome.kind, "unreachable");
+    if (outcome.kind === "unreachable") {
+        assert.match(outcome.stderrTail, /Connection refused/);
+    }
+});
+test("header row only (no match) → missing", () => {
+    // cypher-shell --format plain emits the column header even when zero rows
+    // matched. The seed-or-fail contract treats header-only as the loud-fail.
+    const outcome = classifyOnboardingReadBack({
+        status: 0,
+        stdout: "currentStep\n",
+        stderr: "",
+    });
+    assert.equal(outcome.kind, "missing");
+});
+test("data row present → present, currentStep relayed verbatim", () => {
+    const outcome = classifyOnboardingReadBack({
+        status: 0,
+        stdout: "currentStep\n0\n",
+        stderr: "",
+    });
+    assert.equal(outcome.kind, "present");
+    if (outcome.kind === "present") {
+        assert.equal(outcome.currentStep, "0");
+    }
+});
+test("empty stdout + zero exit → missing (defensive: cypher-shell flushed nothing)", () => {
+    const outcome = classifyOnboardingReadBack({
+        status: 0,
+        stdout: "",
+        stderr: "",
+    });
+    assert.equal(outcome.kind, "missing");
+});
+test("trailing whitespace tolerated on present row", () => {
+    const outcome = classifyOnboardingReadBack({
+        status: 0,
+        stdout: "currentStep\n0  \n\n",
+        stderr: "",
+    });
+    assert.equal(outcome.kind, "present");
+    if (outcome.kind === "present") {
+        assert.equal(outcome.currentStep, "0");
+    }
+});

package/dist/index.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync, rmSync, rea
 import { resolve, join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 import { resolveInstallPortFromFs, buildMaxyUnitFile, buildClaudeSessionManagerUnitFile } from "./port-resolution.js";
+import { classifyOnboardingReadBack } from "./onboarding-readback.js";
 import { parseOsRelease, isUbuntuLike as isUbuntuLikePure, parseAptCacheCandidate, decideAptResolution, } from "./apt-resolve.js";
 import { findPeerBrandOnDefaultNeo4jPort } from "./peer-brand-detect.js";
 import { requireSupportedPlatform } from "./platform-detect.js";
@@ -2289,6 +2290,47 @@ function setupAccount() {
         logFile(`  [neo4j] passing NEO4J_URI=${neo4jUri} to seed`);
         shell("bash", [seedScript], { cwd: INSTALL_DIR, env: neo4jEnv });
     }
+    // Task 033 — install-invariant: OnboardingState must exist post-seed.
+    // Loud-fails (exit 1) on miss because the first admin session has nothing
+    // to read otherwise: loadOnboardingStep returns -1 (no node), the chat
+    // tries to drive the 9-step flow against missing state, and step
+    // advancements have nowhere to land. Symmetric to Task 904's
+    // [install-invariant] line — log-and-continue isn't enough here because
+    // the gap silently breaks every fresh install. Idempotent on re-runs:
+    // the seed's MERGE leaves the node untouched.
+    const accountId = resolveInstallAccountId();
+    if (accountId) {
+        assertOnboardingStateSeeded(accountId, neo4jUri, password);
+    }
+    else {
+        console.log("  [install-invariant] onboarding-state-check SKIPPED reason=no-account-discovered");
+    }
+}
+// Task 033 — Neo4j read-back assertion. Runs cypher-shell against the
+// brand's Neo4j and confirms an OnboardingState{accountId} node exists.
+// Loud-fail exit on miss / Neo4j unreachable so the installer logs name
+// the exact symptom the next run has to fix.
+function assertOnboardingStateSeeded(accountId, neo4jUri, password) {
+    const TAG = "[install-invariant]";
+    const cypher = `MATCH (o:OnboardingState {accountId: '${accountId}'}) RETURN o.currentStep AS currentStep;`;
+    const result = spawnSync("cypher-shell", ["-u", "neo4j", "-p", password, "-a", neo4jUri, "--format", "plain", cypher], { stdio: "pipe", encoding: "utf-8", timeout: 10_000 });
+    const outcome = classifyOnboardingReadBack({
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    });
+    if (outcome.kind === "unreachable") {
+        console.error(`  ${TAG} onboarding-state-UNREACHABLE accountId=${accountId} exit=${result.status} stderr=${JSON.stringify(outcome.stderrTail)}`);
+        logFile(`  ${TAG} onboarding-state-UNREACHABLE accountId=${accountId} stderr=${outcome.stderrTail}`);
+        throw new Error(`OnboardingState read-back failed: cypher-shell exit=${result.status}`);
+    }
+    if (outcome.kind === "missing") {
+        console.error(`  ${TAG} onboarding-state-MISSING accountId=${accountId}`);
+        logFile(`  ${TAG} onboarding-state-MISSING accountId=${accountId}`);
+        throw new Error(`OnboardingState missing for accountId=${accountId} after seed-neo4j.sh`);
+    }
+    console.log(`  ${TAG} onboarding-state-present accountId=${accountId} currentStep=${outcome.currentStep}`);
+    logFile(`  ${TAG} onboarding-state-present accountId=${accountId} currentStep=${outcome.currentStep}`);
 }
 // ---------------------------------------------------------------------------
 // Tunnel script shortcuts

package/dist/onboarding-readback.js

@@ -0,0 +1,27 @@
+// Task 033 — pure parser for the OnboardingState read-back assertion.
+//
+// Extracted into a dedicated module (not src/index.ts) so the test
+// suite can import it without triggering index's brand.json-at-load
+// side effect. The installer's loud-fail branches at
+// `assertOnboardingStateSeeded` consume the tri-state outcome.
+/**
+ * Classify cypher-shell --format plain output into one of three states:
+ *
+ * - `unreachable` — non-zero exit (auth, network, syntax). Stderr tail
+ *   (last 200 chars) is preserved so the install log carries the
+ *   symptom verbatim.
+ * - `missing` — exit 0 but no data row beyond the header. cypher-shell
+ *   prints the column name even on a zero-match query.
+ * - `present` — exit 0 with at least one data row. `currentStep` is the
+ *   first field on row 2.
+ */
+export function classifyOnboardingReadBack(input) {
+    if (input.status !== 0) {
+        return { kind: "unreachable", stderrTail: input.stderr.trim().slice(-200) };
+    }
+    const lines = input.stdout.trim().split("\n").filter((l) => l.length > 0);
+    if (lines.length < 2) {
+        return { kind: "missing" };
+    }
+    return { kind: "present", currentStep: lines[1].trim() };
+}

package/package.json

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

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

@@ -39,6 +39,29 @@ This installs all dependencies (Node.js, Neo4j, Cloudflare tunnel, Claude Code),
 6. Starts the {{productName}} web server on port 19200
 7. Configures systemd so everything restarts automatically if the Pi reboots
 
+## First admin session — onboarding handover
+
+After install, the first time you open the admin URL, {{productName}} walks you through a 9-step onboarding flow: plugin selection, output style, thinking-view, timezone, persona, Cloudflare, Anthropic API key, and the business-profile capture. The flow is gated on a single piece of Neo4j state, an `OnboardingState{accountId, currentStep}` node:
+
+- `seed-neo4j.sh` writes the node at install time with `currentStep=0`. The installer re-reads it before exiting; a missing node or an unreachable Neo4j fails the install loudly (`[install-invariant] onboarding-state-MISSING` or `onboarding-state-UNREACHABLE`).
+- Every admin session-create reads `currentStep`. Anything below 9 keeps `onboarding_complete=false` on `/api/health` and `/api/admin/session`, and the chat opens on the next step's component (multi-select, dropdown, etc.).
+- The first input on a freshly-spawned admin claude session is prepended with an `<onboarding-state currentStep="N">` directive that tells the agent to call `skill-load skillName=onboarding`. Resumed sessions skip this prepend so the agent doesn't re-ask the same step.
+- If Neo4j is unreachable at session-create, the prepend becomes a loud-fail block (`graphUnreachable="true"`) and `onboarding_complete` is reported false — never silently skipped.
+
+Diagnostic command on the Pi (substitute the brand's Neo4j port from `~/.maxy/.env` or `~/.realagent/.env`):
+
+```bash
+cypher-shell -a bolt://localhost:<brand-neo4j-port> \
+  "MATCH (o:OnboardingState) RETURN o.accountId, o.currentStep"
+```
+
+Failure signals to grep in `~/.maxy/logs/server.log` (or `~/.realagent/logs/server.log`):
+
+- missing `[onboarding-seed]` line in install output
+- `[install-invariant] onboarding-state-MISSING`
+- `[onboarding-gate] step=null complete=true` (the pre-Task-033 bug)
+- missing `[skill-load] name=onboarding` while `[onboarding-gate]` reports `complete=false`
+
 ## 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/seed-neo4j.sh

@@ -541,4 +541,39 @@ BACKFILL_EOF
   echo "  [backfill] $BACKFILL_RESULT"
 fi
 
+# ------------------------------------------------------------------
+# 4. Seed OnboardingState (Task 033 — maxy-code)
+# ------------------------------------------------------------------
+# The first admin session reads OnboardingState.currentStep to decide whether
+# the chat opens on step 1 of the 9-step onboarding flow or on a free-form
+# greeting. Pre-Task-033 the node was never written at seed, so the post-PIN
+# session-create's loadOnboardingStep returned -1 (no node) which used to
+# conflate with null (Neo4j unreachable) and silently report
+# onboardingComplete:true — the operator was dropped into the admin agent
+# with no plugin selection, output-style, timezone, SOUL, Cloudflare,
+# Anthropic-key, or business-profile setup.
+#
+# Keyed on accountId, not userId — fresh installs reach the seed before
+# users.json exists (PIN is set later by the onboarding flow itself).
+# MERGE is idempotent: re-runs leave currentStep untouched, refreshing only
+# updatedAt.
+SEED_NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+echo "==> Seeding OnboardingState for accountId=$ACCOUNT_ID"
+ONBOARDING_SEED_RESULT=$("$CYPHER_SHELL" -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" --format plain << CYPHER_EOF
+MERGE (o:OnboardingState {accountId: '$ACCOUNT_ID'})
+ON CREATE SET o.currentStep = 0,
+              o.createdAt = '$SEED_NOW',
+              o.updatedAt = '$SEED_NOW'
+ON MATCH SET o.updatedAt = '$SEED_NOW'
+RETURN o.currentStep AS currentStep, o.createdAt = '$SEED_NOW' AS created;
+CYPHER_EOF
+)
+ONBOARDING_STEP=$(echo "$ONBOARDING_SEED_RESULT" | awk 'NR==2 {print $1}')
+ONBOARDING_CREATED=$(echo "$ONBOARDING_SEED_RESULT" | awk 'NR==2 {print $2}')
+if [ "$ONBOARDING_CREATED" = "true" ]; then
+  echo "  [onboarding-seed] accountId=$ACCOUNT_ID currentStep=$ONBOARDING_STEP idempotent=false"
+else
+  echo "  [onboarding-seed] accountId=$ACCOUNT_ID currentStep=$ONBOARDING_STEP idempotent=true"
+fi
+
 echo "  Done."

package/payload/server/public/assets/{Checkbox-nrf4ISU0.js → Checkbox-BmlrSRF8.js}

@@ -1 +1 @@
-import{t as e}from"./jsx-runtime-Bz7aoCi7.js";var t=e();function n({checked:e,onChange:n,label:r,disabled:i}){return(0,t.jsxs)(`label`,{className:`maxy-checkbox${i?` maxy-checkbox--disabled`:``}`,children:[(0,t.jsx)(`input`,{type:`checkbox`,checked:e,onChange:e=>n(e.target.checked),disabled:i}),(0,t.jsx)(`span`,{className:`maxy-checkbox__box`,children:`✱`}),r&&(0,t.jsx)(`span`,{className:`maxy-checkbox__label`,children:r})]})}export{n as t};
+import{t as e}from"./jsx-runtime-BSJRynxp.js";var t=e();function n({checked:e,onChange:n,label:r,disabled:i}){return(0,t.jsxs)(`label`,{className:`maxy-checkbox${i?` maxy-checkbox--disabled`:``}`,children:[(0,t.jsx)(`input`,{type:`checkbox`,checked:e,onChange:e=>n(e.target.checked),disabled:i}),(0,t.jsx)(`span`,{className:`maxy-checkbox__box`,children:`✱`}),r&&(0,t.jsx)(`span`,{className:`maxy-checkbox__label`,children:r})]})}export{n as t};