@rubytech/create-maxy 1.0.745 → 1.0.747

package/dist/__tests__/peer-brand-detect.test.js

@@ -0,0 +1,103 @@
+// Task 800 — acceptance grid for findPeerBrandOnDefaultNeo4jPort.
+//
+// Each test exercises one branch of the matching rule. The wrapper in
+// index.ts owns fs reads + warning emission; this suite does not touch fs.
+//
+// Runs via Node's built-in test runner (matches apt-resolve.test.ts +
+// port-canonicalisation.test.ts). The brief asked for vitest, but the
+// package has no vitest dependency — node:test is the codebase convention
+// and ships with the toolchain.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { findPeerBrandOnDefaultNeo4jPort } from "../peer-brand-detect.js";
+const DEFAULT_PORT = 7687;
+const CURRENT = "realagent"; // installer is realagent; peer would be maxy
+test("no peer hostnames → null", () => {
+    const result = findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: CURRENT,
+        defaultNeo4jPort: DEFAULT_PORT,
+        peerEnvContents: [],
+    });
+    assert.equal(result, null);
+});
+test("peer with content=null (no .env on disk) → null", () => {
+    const result = findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: CURRENT,
+        defaultNeo4jPort: DEFAULT_PORT,
+        peerEnvContents: [["maxy", null]],
+    });
+    assert.equal(result, null);
+});
+test("peer pins NEO4J_URI=bolt://localhost:7687 → returns peer hostname", () => {
+    const env = `EMBED_MODEL=nomic-embed-text\nNEO4J_URI=bolt://localhost:7687\nACCOUNT_ID=abc\n`;
+    const result = findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: CURRENT,
+        defaultNeo4jPort: DEFAULT_PORT,
+        peerEnvContents: [["maxy", env]],
+    });
+    assert.equal(result, "maxy");
+});
+test("peer pins dedicated port 7688 (not the system unit) → null", () => {
+    const env = `NEO4J_URI=bolt://localhost:7688\n`;
+    const result = findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: CURRENT,
+        defaultNeo4jPort: DEFAULT_PORT,
+        peerEnvContents: [["maxy", env]],
+    });
+    assert.equal(result, null);
+});
+test("peer .env has no NEO4J_URI line → null", () => {
+    const env = `EMBED_MODEL=nomic-embed-text\nDISPLAY_MODE=hd\n`;
+    const result = findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: CURRENT,
+        defaultNeo4jPort: DEFAULT_PORT,
+        peerEnvContents: [["maxy", env]],
+    });
+    assert.equal(result, null);
+});
+test("peer .env is empty → null", () => {
+    const result = findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: CURRENT,
+        defaultNeo4jPort: DEFAULT_PORT,
+        peerEnvContents: [["maxy", ""]],
+    });
+    assert.equal(result, null);
+});
+test("multiple peers, second one matches → returns the matching hostname", () => {
+    const result = findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: CURRENT,
+        defaultNeo4jPort: DEFAULT_PORT,
+        peerEnvContents: [
+            ["future-brand", `NEO4J_URI=bolt://localhost:7689\n`],
+            ["maxy", `NEO4J_URI=bolt://localhost:7687\n`],
+        ],
+    });
+    assert.equal(result, "maxy");
+});
+test("only the current brand in iterable → filtered, returns null", () => {
+    // Caller may pass the full known-brand list; the helper filters self.
+    const result = findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: CURRENT,
+        defaultNeo4jPort: DEFAULT_PORT,
+        peerEnvContents: [[CURRENT, `NEO4J_URI=bolt://localhost:7687\n`]],
+    });
+    assert.equal(result, null);
+});
+test("URI with non-bolt scheme is not a match", () => {
+    const env = `NEO4J_URI=neo4j://localhost:7687\n`;
+    const result = findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: CURRENT,
+        defaultNeo4jPort: DEFAULT_PORT,
+        peerEnvContents: [["maxy", env]],
+    });
+    assert.equal(result, null);
+});
+test("URI with non-localhost host is not a match", () => {
+    const env = `NEO4J_URI=bolt://neo4j.example.com:7687\n`;
+    const result = findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: CURRENT,
+        defaultNeo4jPort: DEFAULT_PORT,
+        peerEnvContents: [["maxy", env]],
+    });
+    assert.equal(result, null);
+});

package/dist/index.js

@@ -5,6 +5,7 @@ import { resolve, join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 import { resolveInstallPortFromFs, buildMaxyUnitFile } from "./port-resolution.js";
 import { parseOsRelease, isUbuntuLike as isUbuntuLikePure, parseAptCacheCandidate, decideAptResolution, } from "./apt-resolve.js";
+import { findPeerBrandOnDefaultNeo4jPort } from "./peer-brand-detect.js";
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive all brand-specific installation values.
 // The bundler stamps brand.json into the payload at build time.
@@ -841,6 +842,48 @@ function installNeo4j() {
     shell("systemctl", ["start", "neo4j"], { sudo: true });
     console.log("  Neo4j started. Password stored securely.");
 }
+/**
+ * Task 800 — does any peer brand on this host pin `NEO4J_URI=bolt://localhost:<default>`
+ * in its `.env`? If yes, the apt-installed `neo4j.service` is its database and the
+ * dedicated-unit installer must NOT stop+disable it. Returns the first matching
+ * peer's hostname, or `null` when no peer pins the default port.
+ *
+ * Wraps the pure decision in `peer-brand-detect.ts` with the fs reads of
+ * `~/.<peer>/.env`. Bias on read errors: if `.env` exists but is unreadable
+ * (permissions, transient I/O), the wrapper treats that peer as a *potential*
+ * dependency and short-circuits to the kept-active path. Disabling the system
+ * unit on faulty evidence would silently kill the peer's database (the exact
+ * failure Task 800 prevents); a conservatively-skipped disable is recoverable
+ * because the dedicated-unit bind check at the end of `setupDedicatedNeo4j`
+ * fails loud if the system unit is actually free.
+ */
+function peerBrandUsingSystemUnit() {
+    const home = process.env.HOME ?? "/root";
+    const peerEnvContents = [];
+    for (const hostname of KNOWN_BRAND_HOSTNAMES) {
+        if (hostname === BRAND.hostname) {
+            peerEnvContents.push([hostname, null]);
+            continue;
+        }
+        const envPath = resolve(home, `.${hostname}`, ".env");
+        if (!existsSync(envPath)) {
+            peerEnvContents.push([hostname, null]);
+            continue;
+        }
+        try {
+            peerEnvContents.push([hostname, readFileSync(envPath, "utf-8")]);
+        }
+        catch (err) {
+            console.error(`  WARNING: unable to read peer brand .env at ${envPath} — treating as potential dependency to avoid data loss (Task 800): ${err instanceof Error ? err.message : String(err)}`);
+            return hostname;
+        }
+    }
+    return findPeerBrandOnDefaultNeo4jPort({
+        currentBrandHostname: BRAND.hostname,
+        defaultNeo4jPort: DEFAULT_NEO4J_PORT,
+        peerEnvContents,
+    });
+}
 /**
  * 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.
@@ -849,6 +892,10 @@ function installNeo4j() {
  * dedicated, start, verify) so a half-installed Pi recovers in-place without
  * manual systemctl. ensureNeo4jPassword() handles password verification on the
  * recovery path.
+ *
+ * Task 800: on multi-brand hosts where a peer brand still depends on the apt
+ * `neo4j.service` (port 7687), the stop+disable step is skipped — disabling
+ * the system unit would kill the peer's database.
  */
 function setupDedicatedNeo4j() {
     if (!NEO4J_DEDICATED)
@@ -952,10 +999,22 @@ WantedBy=multi-user.target
     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 });
+    // Task 800: skip stop+disable when a peer brand on this host still depends
+    // on the apt `neo4j.service` (port 7687). Disabling it would kill the peer's
+    // database — Task 797 reproducer on Neo's laptop. The kept-active path is
+    // mutually exclusive with the disable path: exactly one log line per install.
+    const peerOnSystemUnit = peerBrandUsingSystemUnit();
+    if (peerOnSystemUnit !== null) {
+        const keptActiveMsg = `  [neo4j] system unit kept active — peer brand ${peerOnSystemUnit} depends on port ${DEFAULT_NEO4J_PORT} (Task 800)`;
+        console.log(keptActiveMsg);
+        logFile(keptActiveMsg);
+    }
+    else {
+        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 });
+        shell("systemctl", ["disable", "neo4j"], { sudo: 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 });

package/dist/peer-brand-detect.js

@@ -0,0 +1,39 @@
+// Task 800 — pure peer-brand detection. Extracted from index.ts so the
+// "should we leave the system neo4j.service alone?" decision can be unit-
+// tested with concrete `.env` fixtures, no fs reads. Mirrors the apt-resolve
+// / port-resolution pattern: inputs in, decision out, no I/O.
+//
+// The installer's `setupDedicatedNeo4j()` wraps this with the fs reads of
+// `~/.<peer>/.env` and the `console.error` warning on read failure. This
+// module owns only the parsing + matching rule.
+/**
+ * Decide whether any peer brand on the same host depends on the apt-installed
+ * `neo4j.service` (port `defaultNeo4jPort`, conventionally 7687). Returns the
+ * first matching peer brand's hostname, or `null` if no peer pins that port.
+ *
+ * `peerEnvContents` is an iterable of `[hostname, envContent | null]` pairs.
+ * `null` content means the peer's `.env` is absent or unreadable — treated
+ * the same as "no evidence of dependency". The wrapper logs the read failure;
+ * this module stays decision-only.
+ *
+ * Matching rule: a peer pins the default port iff its `.env` contains a line
+ * matching `NEO4J_URI=bolt://localhost:<defaultNeo4jPort>` exactly. Any other
+ * scheme, host, or port → not a match. Self-references (peer hostname equal
+ * to the current install's hostname) are silently skipped so the caller can
+ * pass the full known-brand list without filtering first.
+ */
+export function findPeerBrandOnDefaultNeo4jPort(args) {
+    const { currentBrandHostname, defaultNeo4jPort, peerEnvContents } = args;
+    const expected = `bolt://localhost:${defaultNeo4jPort}`;
+    for (const [hostname, content] of peerEnvContents) {
+        if (hostname === currentBrandHostname)
+            continue;
+        if (content === null)
+            continue;
+        const match = content.match(/^NEO4J_URI=(.+)$/m);
+        if (match && match[1].trim() === expected) {
+            return hostname;
+        }
+    }
+    return null;
+}

package/package.json

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

package/payload/platform/neo4j/schema.cypher

@@ -848,3 +848,43 @@ FOR (c:Credential) REQUIRE (c.accountId, c.name, c.authority) IS UNIQUE;
 
 CREATE INDEX credential_account IF NOT EXISTS
 FOR (c:Credential) ON (c.accountId);
+
+// ----------------------------------------------------------
+// Provenance indexes (Task 800) — back the shim's per-write
+// orphan check. Task 797's `executeWrite` runs an unanchored
+// `MATCH (n) WHERE n.createdBySession = $autoSession AND
+// n.createdAt >= $autoStartTimestamp AND NOT (n)--()` after
+// every operator write. Without an index this is `AllNodesScan`
+// — sub-millisecond on the current ~10K-node graph, but a
+// per-write tax that grows with graph size.
+//
+// Neo4j 5 property indexes require a label clause; there is no
+// label-free range/text/point index. The orphan check is
+// unanchored, so the planner relies on `UnionNodeByLabelsScan`
+// (Neo4j 5.6+) to combine per-label seeks. If a future EXPLAIN
+// shows `AllNodesScan` despite these indexes, the orphan-check
+// Cypher in `cypher-shim-write.ts` should be anchored with an
+// explicit label union — that's the structural fallback.
+//
+// Coverage: the five labels written most often through the raw
+// Cypher write path (Person, Organization, KnowledgeDocument,
+// Section, Task). Other written labels (Project, Position,
+// Credential, ToolCall, Conversation, etc.) still hit
+// `AllNodesScan` for the orphan check; extending coverage is a
+// separate decision, not a default.
+// ----------------------------------------------------------
+
+CREATE INDEX person_created_by_session IF NOT EXISTS
+FOR (n:Person) ON (n.createdBySession);
+
+CREATE INDEX organization_created_by_session IF NOT EXISTS
+FOR (n:Organization) ON (n.createdBySession);
+
+CREATE INDEX knowledge_doc_created_by_session IF NOT EXISTS
+FOR (n:KnowledgeDocument) ON (n.createdBySession);
+
+CREATE INDEX section_created_by_session IF NOT EXISTS
+FOR (n:Section) ON (n.createdBySession);
+
+CREATE INDEX task_created_by_session IF NOT EXISTS
+FOR (n:Task) ON (n.createdBySession);

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

@@ -101,7 +101,7 @@ A single Pi or laptop can host more than one brand (for example Maxy and Real Ag
 
 - **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 peer brands running their own `neo4j-{brand}.service` are unaffected.
-- **Multi-brand-host caveat (Task 800):** on a host where the default brand keeps using the shared system `neo4j.service` per Task 659 V3 (e.g. a laptop running Maxy on default port 7687 alongside a branded build on a dedicated port), the Task 787 disable above kills the default brand's database when a branded installer runs. Symptom: default-brand admin server keeps running but bolt port 7687 has no listener; the branded install log contains `[neo4j] disabling system unit (brand-dedicated active on port <branded-port>)` immediately followed by `Stopping neo4j.service` in the systemd journal. Data on disk is intact (`disable` only removes the WantedBy symlink); recovery is `sudo systemctl enable neo4j && sudo systemctl start neo4j`. Task 800 adds a peer-brand guard so the disable is skipped when any `~/.<brand>/.env` pins `NEO4J_URI=bolt://localhost:7687`. Until Task 800 lands, repeat the recovery after each branded `create-{brand}` upgrade on a multi-brand host.
+- **Peer-aware system-unit guard (Task 800):** before stopping the system `neo4j.service`, the installer checks whether any other brand on the device still depends on it — that is, has `NEO4J_URI=bolt://localhost:7687` in its `~/.<peer>/.env`. If so, the system unit is left enabled and active, and the install log shows `[neo4j] system unit kept active — peer brand <name> depends on port 7687 (Task 800)` instead of the usual `[neo4j] disabling system unit` line. This prevents a `create-realagent` install from disabling Maxy's database on a host where Maxy still uses the shared system instance (the Task 797 reproducer on Neo's laptop, 2026-04-28). On single-brand hosts and on multi-brand hosts where every peer runs a dedicated port, behaviour is unchanged from Task 787.
 - **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: