@rubytech/create-maxy 1.0.739 → 1.0.740

package/dist/index.js

@@ -138,14 +138,23 @@ function shell(command, args, options) {
         stdio: "inherit",
         timeout: options?.timeout ?? 300_000,
         cwd: options?.cwd,
+        env: options?.env,
     });
     const dur = ((Date.now() - start) / 1000).toFixed(1);
+    // bestEffort (Task 787): tear-down ops on units/state that may or may not
+    // exist (stop/disable a system service we may never have started, reset-failed
+    // a freshly-created unit) log the non-zero exit but do not throw. Reserved
+    // for the "may not exist" pattern only — never use for ops that must succeed.
     if (result.signal) {
         logFile(`  KILLED (${result.signal}) after ${dur}s`);
+        if (options?.bestEffort)
+            return;
         throw new Error(`Command killed (${result.signal}) after ${dur}s: ${cmd} ${cmdArgs.join(" ")}`);
     }
     if (result.status !== 0) {
-        logFile(`  FAILED (exit ${result.status}) after ${dur}s`);
+        logFile(`  ${options?.bestEffort ? "best-effort non-zero" : "FAILED"} (exit ${result.status}) after ${dur}s`);
+        if (options?.bestEffort)
+            return;
         throw new Error(`Command failed (exit ${result.status}) after ${dur}s: ${cmd} ${cmdArgs.join(" ")}`);
     }
     logFile(`  OK in ${dur}s`);
@@ -835,8 +844,11 @@ function installNeo4j() {
 /**
  * Create a dedicated Neo4j instance for this brand when NEO4J_DEDICATED is true.
  * Produces: separate config dir, data dir, log dir, systemd service, and password.
- * On upgrade (config already exists), skips setup — ensureNeo4jPassword() handles
- * password verification for existing instances.
+ * On upgrade (config already exists), skips conf creation — but always runs the
+ * Task 787 state-remediation block (stop/disable system unit, reset-failed
+ * dedicated, start, verify) so a half-installed Pi recovers in-place without
+ * manual systemctl. ensureNeo4jPassword() handles password verification on the
+ * recovery path.
  */
 function setupDedicatedNeo4j() {
     if (!NEO4J_DEDICATED)
@@ -847,49 +859,52 @@ function setupDedicatedNeo4j() {
     const logDir = `/var/log/neo4j-${brandSuffix}`;
     const serviceName = `neo4j-${brandSuffix}`;
     const httpPort = NEO4J_PORT - 213; // Preserve standard 7687/7474 offset
-    // Upgrade detection: if dedicated config already exists, skip setup entirely.
-    // ensureNeo4jPassword() will verify the password is correct for this instance.
-    const confCheck = spawnSync("test", ["-f", `${confDir}/neo4j.conf`], { stdio: "pipe" });
-    if (confCheck.status === 0) {
+    // Conf creation is gated on first install; everything below the if/else
+    // (state remediation + start + verify) runs on every install — Task 787
+    // closes the recovery gap where a half-installed Pi (failed prior install
+    // hit start-limit-hit, dedicated unit in failed state) returned here without
+    // the fix being applied.
+    const confExists = spawnSync("test", ["-f", `${confDir}/neo4j.conf`], { stdio: "pipe" }).status === 0;
+    if (confExists) {
         console.log(`  Dedicated Neo4j instance for ${BRAND.productName} already configured at ${confDir}`);
-        logFile(`  Neo4j dedicated: existing config at ${confDir}, skipping setup`);
-        return;
-    }
-    console.log(`  Setting up dedicated Neo4j instance for ${BRAND.productName} on bolt://localhost:${NEO4J_PORT}...`);
-    // Pre-check: neo4j user must exist (created by the apt package)
-    const neo4jUserCheck = spawnSync("id", ["neo4j"], { stdio: "pipe" });
-    if (neo4jUserCheck.status !== 0) {
-        throw new Error("Neo4j system user 'neo4j' not found. Is Neo4j installed via apt?");
-    }
-    // Pre-check: source config must exist
-    if (!existsSync("/etc/neo4j/neo4j.conf")) {
-        throw new Error("/etc/neo4j/neo4j.conf not found. Cannot create dedicated instance without base config.");
+        logFile(`  Neo4j dedicated: existing config at ${confDir}, skipping conf creation`);
     }
-    // 1. Copy base config
-    console.log("  [privileged] cp -r");
-    shell("cp", ["-r", "/etc/neo4j", confDir], { sudo: true });
-    // 2. Modify config for this instance: bolt port, HTTP port, data/log directories
-    console.log("  [privileged] sed -i");
-    shell("sed", ["-i", `s/^#\\?server\\.bolt\\.listen_address=.*/server.bolt.listen_address=:${NEO4J_PORT}/`, `${confDir}/neo4j.conf`], { sudo: true });
-    console.log("  [privileged] sed -i");
-    shell("sed", ["-i", `s/^#\\?server\\.http\\.listen_address=.*/server.http.listen_address=:${httpPort}/`, `${confDir}/neo4j.conf`], { sudo: true });
-    console.log("  [privileged] sed -i");
-    shell("sed", ["-i", `s|^#\\?server\\.directories\\.data=.*|server.directories.data=${dataDir}/data|`, `${confDir}/neo4j.conf`], { sudo: true });
-    console.log("  [privileged] sed -i");
-    shell("sed", ["-i", `s|^#\\?server\\.directories\\.logs=.*|server.directories.logs=${logDir}|`, `${confDir}/neo4j.conf`], { sudo: true });
-    // Verify config was updated — sed silently no-ops if the key format changed
-    const confContent = spawnSync("grep", [`server.bolt.listen_address=:${NEO4J_PORT}`, `${confDir}/neo4j.conf`], { stdio: "pipe" });
-    if (confContent.status !== 0) {
-        console.error(`  WARNING: neo4j.conf may not have been updated correctly — bolt port ${NEO4J_PORT} not found in config`);
-        logFile(`  WARNING: sed verification failed — bolt port ${NEO4J_PORT} not found in ${confDir}/neo4j.conf`);
-    }
-    // 3. Create data and log directories
-    console.log("  [privileged] mkdir -p");
-    shell("mkdir", ["-p", `${dataDir}/data`, logDir], { sudo: true });
-    console.log("  [privileged] chown -R");
-    shell("chown", ["-R", "neo4j:neo4j", dataDir, logDir, confDir], { sudo: true });
-    // 4. Create systemd service
-    const serviceContent = `[Unit]
+    else {
+        console.log(`  Setting up dedicated Neo4j instance for ${BRAND.productName} on bolt://localhost:${NEO4J_PORT}...`);
+        // Pre-check: neo4j user must exist (created by the apt package)
+        const neo4jUserCheck = spawnSync("id", ["neo4j"], { stdio: "pipe" });
+        if (neo4jUserCheck.status !== 0) {
+            throw new Error("Neo4j system user 'neo4j' not found. Is Neo4j installed via apt?");
+        }
+        // Pre-check: source config must exist
+        if (!existsSync("/etc/neo4j/neo4j.conf")) {
+            throw new Error("/etc/neo4j/neo4j.conf not found. Cannot create dedicated instance without base config.");
+        }
+        // 1. Copy base config
+        console.log("  [privileged] cp -r");
+        shell("cp", ["-r", "/etc/neo4j", confDir], { sudo: true });
+        // 2. Modify config for this instance: bolt port, HTTP port, data/log directories
+        console.log("  [privileged] sed -i");
+        shell("sed", ["-i", `s/^#\\?server\\.bolt\\.listen_address=.*/server.bolt.listen_address=:${NEO4J_PORT}/`, `${confDir}/neo4j.conf`], { sudo: true });
+        console.log("  [privileged] sed -i");
+        shell("sed", ["-i", `s/^#\\?server\\.http\\.listen_address=.*/server.http.listen_address=:${httpPort}/`, `${confDir}/neo4j.conf`], { sudo: true });
+        console.log("  [privileged] sed -i");
+        shell("sed", ["-i", `s|^#\\?server\\.directories\\.data=.*|server.directories.data=${dataDir}/data|`, `${confDir}/neo4j.conf`], { sudo: true });
+        console.log("  [privileged] sed -i");
+        shell("sed", ["-i", `s|^#\\?server\\.directories\\.logs=.*|server.directories.logs=${logDir}|`, `${confDir}/neo4j.conf`], { sudo: true });
+        // Verify config was updated — sed silently no-ops if the key format changed
+        const confContent = spawnSync("grep", [`server.bolt.listen_address=:${NEO4J_PORT}`, `${confDir}/neo4j.conf`], { stdio: "pipe" });
+        if (confContent.status !== 0) {
+            console.error(`  WARNING: neo4j.conf may not have been updated correctly — bolt port ${NEO4J_PORT} not found in config`);
+            logFile(`  WARNING: sed verification failed — bolt port ${NEO4J_PORT} not found in ${confDir}/neo4j.conf`);
+        }
+        // 3. Create data and log directories
+        console.log("  [privileged] mkdir -p");
+        shell("mkdir", ["-p", `${dataDir}/data`, logDir], { sudo: true });
+        console.log("  [privileged] chown -R");
+        shell("chown", ["-R", "neo4j:neo4j", dataDir, logDir, confDir], { sudo: true });
+        // 4. Create systemd service
+        const serviceContent = `[Unit]
 Description=Neo4j Graph Database (${BRAND.productName})
 After=network-online.target
 Wants=network-online.target
@@ -905,53 +920,73 @@ LimitNOFILE=60000
 [Install]
 WantedBy=multi-user.target
 `;
-    const tmpServicePath = `/tmp/${serviceName}.service`;
-    writeFileSync(tmpServicePath, serviceContent);
-    console.log("  [privileged] cp");
-    shell("cp", [tmpServicePath, `/etc/systemd/system/${serviceName}.service`], { sudo: true });
-    spawnSync("rm", ["-f", tmpServicePath]);
-    // 5. Set initial password before first start
-    const password = randomBytes(24).toString("base64url");
-    const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
-    mkdirSync(persistDir, { recursive: true });
-    writeFileSync(join(persistDir, ".neo4j-password"), password, { mode: 0o600 });
-    const configDir = resolve(INSTALL_DIR, "platform/config");
-    mkdirSync(configDir, { recursive: true });
-    writeFileSync(join(configDir, ".neo4j-password"), password, { mode: 0o600 });
-    // sudo env VAR=val passes NEO4J_CONF through sudo's env_reset policy
-    spawnSync("sudo", ["env", `NEO4J_CONF=${confDir}`, "neo4j-admin", "dbms", "set-initial-password", "--", password], {
-        stdio: "inherit",
-    });
-    // 6. Enable and start the dedicated service
+        const tmpServicePath = `/tmp/${serviceName}.service`;
+        writeFileSync(tmpServicePath, serviceContent);
+        console.log("  [privileged] cp");
+        shell("cp", [tmpServicePath, `/etc/systemd/system/${serviceName}.service`], { sudo: true });
+        spawnSync("rm", ["-f", tmpServicePath]);
+        // 5. Set initial password before first start
+        const password = randomBytes(24).toString("base64url");
+        const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+        mkdirSync(persistDir, { recursive: true });
+        writeFileSync(join(persistDir, ".neo4j-password"), password, { mode: 0o600 });
+        const configDir = resolve(INSTALL_DIR, "platform/config");
+        mkdirSync(configDir, { recursive: true });
+        writeFileSync(join(configDir, ".neo4j-password"), password, { mode: 0o600 });
+        // sudo env VAR=val passes NEO4J_CONF through sudo's env_reset policy
+        spawnSync("sudo", ["env", `NEO4J_CONF=${confDir}`, "neo4j-admin", "dbms", "set-initial-password", "--", password], {
+            stdio: "inherit",
+        });
+    }
+    // ============================================================================
+    // Task 787 — unified state remediation + start + verify.
+    //
+    // Runs on both fresh and recovery paths. The dedicated unit and the apt
+    // package's system unit both exec /usr/bin/neo4j console without overriding
+    // NEO4J_HOME, so server.directories.run resolves to /var/lib/neo4j/run for
+    // both — the launcher refuses with "Neo4j is already running (pid:N)" if
+    // the system unit holds the PID file. Stopping the system unit first frees
+    // the run-state; disabling prevents it returning at next boot. reset-failed
+    // clears any prior start-limit-hit from a half-installed Pi.
+    // ============================================================================
     spawnSync("sudo", ["systemctl", "daemon-reload"], { stdio: "inherit" });
     console.log("  [privileged] systemctl enable");
     shell("systemctl", ["enable", serviceName], { sudo: true });
+    console.log(`  [neo4j] disabling system unit (brand-dedicated active on port ${NEO4J_PORT})`);
+    logFile(`  [neo4j] disabling system unit (brand-dedicated active on port ${NEO4J_PORT})`);
+    shell("systemctl", ["stop", "neo4j"], { sudo: true, bestEffort: true });
+    shell("systemctl", ["disable", "neo4j"], { sudo: true, bestEffort: true });
+    console.log(`  [neo4j] reset-failed ${serviceName} before start`);
+    logFile(`  [neo4j] reset-failed ${serviceName} before start`);
+    shell("systemctl", ["reset-failed", serviceName], { sudo: true, bestEffort: true });
     console.log("  [privileged] systemctl start");
     shell("systemctl", ["start", serviceName], { sudo: true });
-    // 7. Verify connectivity — poll until cypher-shell can connect
+    // Verify the dedicated unit bound its port. Password verification is
+    // ensureNeo4jPassword()'s job (called next in the install pipeline) — that
+    // function tests the stored password against this port and resets auth if
+    // the password no longer matches the running instance.
     console.log(`  Waiting for dedicated Neo4j instance on port ${NEO4J_PORT}...`);
-    let connected = false;
+    let listening = false;
+    const portMatch = new RegExp(`:${NEO4J_PORT}\\b`);
     for (let i = 0; i < 15; i++) {
-        const check = spawnSync("cypher-shell", [
-            "-u", "neo4j", "-p", password,
-            "-a", `bolt://localhost:${NEO4J_PORT}`,
-            "RETURN 1",
-        ], { stdio: "pipe", timeout: 5000 });
-        if (check.status === 0) {
-            connected = true;
+        const portCheck = spawnSync("ss", ["-tln"], { stdio: "pipe", timeout: 5000 });
+        if (portMatch.test(portCheck.stdout?.toString() ?? "")) {
+            listening = true;
             break;
         }
         spawnSync("sleep", ["2"]);
     }
-    if (!connected) {
-        // Diagnostic: check what's on this port
+    if (!listening) {
+        // Loud failure — no silent fallback to the system instance (Task 787).
         const portCheck = spawnSync("ss", ["-tlnp"], { stdio: "pipe", timeout: 5000 });
-        const portLines = portCheck.stdout?.toString().split("\n").filter((l) => l.includes(String(NEO4J_PORT))) || [];
+        const portLines = (portCheck.stdout?.toString() ?? "").split("\n").filter((l) => l.includes(String(NEO4J_PORT)));
         const diagnostic = portLines.length > 0 ? portLines.join("; ") : "nothing listening on port";
-        console.error(`  WARNING: Dedicated Neo4j instance not responding on bolt://localhost:${NEO4J_PORT}`);
-        console.error(`  Port ${NEO4J_PORT} status: ${diagnostic}`);
-        logFile(`  Neo4j dedicated: connectivity check FAILED on port ${NEO4J_PORT} — ${diagnostic}`);
-        // Don't throw — ensureNeo4jPassword() will retry
+        const journal = spawnSync("journalctl", ["-u", serviceName, "--since", "5 min ago"], { stdio: "pipe", timeout: 5000 });
+        const journalTail = (journal.stdout?.toString() ?? "").split("\n").slice(-20).join("\n");
+        logFile(`  Neo4j dedicated: failed to bind port ${NEO4J_PORT} — ${diagnostic}`);
+        throw new Error(`Dedicated Neo4j instance ${serviceName} did not bind bolt://localhost:${NEO4J_PORT} within 30s.\n` +
+            `Port ${NEO4J_PORT}: ${diagnostic}\n` +
+            `journalctl -u ${serviceName} --since "5 min ago" | tail -20:\n${journalTail}`);
     }
     logFile(`  Neo4j dedicated: config=${confDir} data=${dataDir} service=${serviceName} bolt=:${NEO4J_PORT} http=:${httpPort}`);
     console.log(`  Dedicated Neo4j instance ready on bolt://localhost:${NEO4J_PORT}`);
@@ -1449,7 +1484,23 @@ function setupAccount() {
     log("10", TOTAL, "Setting up...");
     const seedScript = join(INSTALL_DIR, "platform/scripts/seed-neo4j.sh");
     if (existsSync(seedScript)) {
-        shell("bash", [seedScript], { cwd: INSTALL_DIR });
+        // Task 787 — explicit env to seed. The script no longer falls back to
+        // bolt://localhost:7687, so the installer is responsible for naming the
+        // brand-correct URI and providing the password. Missing password file is
+        // a hard error: ensureNeo4jPassword() ran upstream and would have thrown
+        // already if it couldn't reach the brand's Neo4j.
+        const passwordFile = join(INSTALL_DIR, "platform/config/.neo4j-password");
+        if (!existsSync(passwordFile)) {
+            throw new Error(`Neo4j password file missing at ${passwordFile} — required by seed step.`);
+        }
+        const password = readFileSync(passwordFile, "utf-8").trim();
+        const neo4jUri = `bolt://localhost:${NEO4J_PORT}`;
+        console.log(`  [neo4j] passing NEO4J_URI=${neo4jUri} to seed`);
+        logFile(`  [neo4j] passing NEO4J_URI=${neo4jUri} to seed`);
+        shell("bash", [seedScript], {
+            cwd: INSTALL_DIR,
+            env: { ...process.env, NEO4J_URI: neo4jUri, NEO4J_PASSWORD: password },
+        });
     }
     // Task 748 — universal embedding coverage backfill. Run after seed so the
     // entity_search index is in place and any pre-Task-748 nodes (e.g. the

package/package.json

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

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

@@ -100,6 +100,7 @@ systemctl --user daemon-reload
 A single Pi or laptop can host more than one brand (for example Maxy and Real Agent) side by side. Each brand runs as its own service on its own port, with its own install directory and its own data. Installing one brand does not touch the other.
 
 - **Separate:** each brand has its own install folder (`~/maxy/`, `~/realagent/`), its own config folder (`~/.maxy/`, `~/.realagent/`), its own web port, its own Cloudflare tunnel state, its own edge systemd unit (`maxy-edge.service` vs `realagent-edge.service`), and by default its own Neo4j database (Maxy on bolt port 7687, Real Agent on 7688). Action runner units are transient and per-invocation, not per-brand, so no naming conflict is possible.
+- **Brand-isolated Neo4j (Task 787):** when a brand provisions a dedicated Neo4j instance (any port other than 7687), the installer stops and disables the apt-package's system `neo4j.service` after enabling the brand-dedicated unit, so only one Neo4j process holds the shared `/var/lib/neo4j/run/` PID file. The seed step receives the brand-correct `NEO4J_URI` and `NEO4J_PASSWORD` as explicit environment variables — the seed script no longer carries a `bolt://localhost:7687` default. A failed dedicated start aborts the install loudly with a journalctl tail; there is no silent fallback to the system instance. Stop/disable targets the literal `neo4j.service` only, so re-running another brand's installer never touches a peer brand's `neo4j-{brand}.service`.
 - **Shared:** both brands share the system Chromium/VNC stack, the Ollama model server, and the `cloudflared` command itself. Browser automation is serialised — one admin session at a time across both brands.
 
 To install a second brand on a device that already runs the first, just run the other installer. No flags needed for isolation:

package/payload/platform/scripts/seed-neo4j.sh

@@ -16,7 +16,13 @@ INSTALL_DIR="$(dirname "$PROJECT_DIR")"
 ACCOUNTS_DIR="$INSTALL_DIR/data/accounts"
 NEO4J_DIR="$PROJECT_DIR/neo4j"
 
-NEO4J_URI="${NEO4J_URI:-bolt://localhost:7687}"
+# NEO4J_URI is hard-required (Task 787). The previous default
+# `bolt://localhost:7687` would silently route the seed to the wrong Neo4j on
+# any brand-dedicated install — masking every other defect downstream.
+if [ -z "${NEO4J_URI:-}" ]; then
+  echo "Error: NEO4J_URI required (no default — see Task 787)" >&2
+  exit 1
+fi
 NEO4J_USER="${NEO4J_USER:-neo4j}"
 
 # Read password from the file created during setup