@rubytech/create-siteoffice-code 0.1.256

package/dist/__tests__/launchd-plist.test.js

@@ -0,0 +1,195 @@
+// acceptance grid for launchd-plist.ts.
+//
+// Locks the plist render contract that the macOS supervisor branch in
+// installService() depends on: standard render, XML escaping of `<` `&` `"`
+// embedded in paths, array `programArguments`, and absence of optional fields.
+// Pure logic — no I/O, no launchctl invocation. The installer wraps this with
+// writeFileSync + spawnSync("launchctl", ...) calls.
+//
+// Compiles to dist/__tests__/launchd-plist.test.js alongside the rest of the
+// package so `node --test dist/__tests__/*.test.js` picks it up after build.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { renderPlist } from "../launchd-plist.js";
+// ---------------------------------------------------------------------------
+// Standard render — every required field present, no escaping needed.
+// ---------------------------------------------------------------------------
+test("renderPlist standard render — required fields and structure", () => {
+    const xml = renderPlist({
+        label: "com.rubytech.maxy",
+        programArguments: ["/usr/local/bin/node", "/Users/alice/maxy/server/server.js"],
+        stdoutPath: "/Users/alice/.maxy/logs/server.log",
+        stderrPath: "/Users/alice/.maxy/logs/server.err.log",
+        keepAlive: true,
+        runAtLoad: true,
+        workingDirectory: "/Users/alice/maxy/server",
+    });
+    // XML preamble + plist DOCTYPE — launchctl rejects plists missing either.
+    assert.match(xml, /^<\?xml version="1\.0" encoding="UTF-8"\?>\n/, "XML preamble required");
+    assert.match(xml, /<!DOCTYPE plist PUBLIC "-\/\/Apple\/\/DTD PLIST 1\.0\/\/EN"/, "PLIST DOCTYPE required");
+    assert.match(xml, /<plist version="1\.0">[\s\S]*<\/plist>\s*$/, "plist root element wraps the dict");
+    // Label, paths, working directory.
+    assert.match(xml, /<key>Label<\/key>\s*<string>com\.rubytech\.maxy<\/string>/);
+    assert.match(xml, /<key>StandardOutPath<\/key>\s*<string>\/Users\/alice\/\.maxy\/logs\/server\.log<\/string>/);
+    assert.match(xml, /<key>StandardErrorPath<\/key>\s*<string>\/Users\/alice\/\.maxy\/logs\/server\.err\.log<\/string>/);
+    assert.match(xml, /<key>WorkingDirectory<\/key>\s*<string>\/Users\/alice\/maxy\/server<\/string>/);
+    // Booleans render as <true/> / <false/> (launchd's documented form).
+    assert.match(xml, /<key>KeepAlive<\/key>\s*<true\/>/);
+    assert.match(xml, /<key>RunAtLoad<\/key>\s*<true\/>/);
+});
+test("renderPlist programArguments renders as <array> of <string> in order", () => {
+    // Order matters: launchd execs argv[0] with argv[1..] as positional args.
+    // The renderer must preserve input order verbatim.
+    const xml = renderPlist({
+        label: "com.rubytech.maxy",
+        programArguments: ["/usr/local/bin/node", "--enable-source-maps", "/Users/alice/maxy/server/server.js", "--port=19200"],
+        stdoutPath: "/dev/null",
+        stderrPath: "/dev/null",
+        keepAlive: true,
+        runAtLoad: true,
+    });
+    // Match the full ProgramArguments block — order must be exact.
+    const block = xml.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    assert.ok(block, "ProgramArguments array must be present");
+    const inner = block[1];
+    // Each <string> in the order supplied.
+    const strings = [...inner.matchAll(/<string>(.*?)<\/string>/g)].map((m) => m[1]);
+    assert.deepEqual(strings, [
+        "/usr/local/bin/node",
+        "--enable-source-maps",
+        "/Users/alice/maxy/server/server.js",
+        "--port=19200",
+    ]);
+});
+// ---------------------------------------------------------------------------
+// KeepAlive + RunAtLoad falsy paths — render as <false/>.
+// ---------------------------------------------------------------------------
+test("renderPlist keepAlive=false / runAtLoad=false render <false/>", () => {
+    const xml = renderPlist({
+        label: "com.rubytech.maxy",
+        programArguments: ["/usr/local/bin/node", "/srv/server.js"],
+        stdoutPath: "/dev/null",
+        stderrPath: "/dev/null",
+        keepAlive: false,
+        runAtLoad: false,
+    });
+    assert.match(xml, /<key>KeepAlive<\/key>\s*<false\/>/);
+    assert.match(xml, /<key>RunAtLoad<\/key>\s*<false\/>/);
+});
+// ---------------------------------------------------------------------------
+// XML escaping — `<`, `&`, `>`, `"`, `'` in any string field must be escaped
+// to the five XML predefined entities. Without this, a path with `&` (rare
+// but legal on macOS) produces a parse error: `launchctl bootstrap` exits
+// with "Bootstrap failed: 5: Input/output error" and the install completes
+// in a non-functional state.
+// ---------------------------------------------------------------------------
+test("renderPlist escapes <, &, >, \", ' in string fields", () => {
+    const xml = renderPlist({
+        label: 'com.rubytech.maxy & "test" <bracket>',
+        programArguments: ["/usr/local/bin/node", "/path/with & ampersand/server.js"],
+        stdoutPath: "/path/with <angle>/log.out",
+        stderrPath: "/path/with 'apostrophe'/log.err",
+        keepAlive: true,
+        runAtLoad: true,
+        workingDirectory: '/path/with "quote"/cwd',
+    });
+    // Label: every metacharacter escaped, none of the raw forms leak through.
+    assert.match(xml, /<key>Label<\/key>\s*<string>com\.rubytech\.maxy &amp; &quot;test&quot; &lt;bracket&gt;<\/string>/);
+    // None of the literal metacharacters survive inside the Label string slot.
+    assert.ok(!/<string>com\.rubytech\.maxy &(?!(amp|quot|lt|gt|apos);)/.test(xml), "raw & must not appear inside Label");
+    // ProgramArguments entry with `&`.
+    assert.match(xml, /<string>\/path\/with &amp; ampersand\/server\.js<\/string>/);
+    // StandardOutPath with `<` `>`.
+    assert.match(xml, /<key>StandardOutPath<\/key>\s*<string>\/path\/with &lt;angle&gt;\/log\.out<\/string>/);
+    // StandardErrorPath with `'` — escaped to &apos;.
+    assert.match(xml, /<key>StandardErrorPath<\/key>\s*<string>\/path\/with &apos;apostrophe&apos;\/log\.err<\/string>/);
+    // WorkingDirectory with `"` — escaped to &quot;.
+    assert.match(xml, /<key>WorkingDirectory<\/key>\s*<string>\/path\/with &quot;quote&quot;\/cwd<\/string>/);
+});
+test("renderPlist escapes `&` once, never double-escapes", () => {
+    // Regression guard: a naive escape that runs the replacements in the wrong
+    // order produces &amp;lt; for an input of `<`. Keep the order &-first so a
+    // raw `&` becomes `&amp;` and a raw `<` stays a single `&lt;`.
+    const xml = renderPlist({
+        label: "a&b<c",
+        programArguments: ["/x"],
+        stdoutPath: "/dev/null",
+        stderrPath: "/dev/null",
+        keepAlive: true,
+        runAtLoad: true,
+    });
+    assert.match(xml, /<string>a&amp;b&lt;c<\/string>/);
+    assert.ok(!/&amp;amp;|&amp;lt;/.test(xml), "no double-escaping");
+});
+// ---------------------------------------------------------------------------
+// Optional-field absence — workingDirectory is the only optional field. When
+// omitted, the corresponding <key>/<value> pair must not appear in the output.
+// Emitting `<key>WorkingDirectory</key><string></string>` would chdir launchd's
+// child to "" (current dir = launchd's cwd, /), which silently changes
+// behaviour from "stay where invoked" to "/" — a different bug than absence.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Brand-stamped labels — both shipping brands must render distinct labels so a
+// co-resident install does not collide on a single LaunchAgent file.
+// `launchdLabel()` in index.ts returns `com.rubytech.${BRAND.hostname}`; this
+// test pins the brand-input → label contract end-to-end against the renderer.
+// ---------------------------------------------------------------------------
+test("renderPlist maxy-code brand fields land in the plist verbatim", () => {
+    // BRAND.hostname=maxy-code, configDir=.maxy-code per brands/maxy-code/brand.json.
+    // installServiceDarwin builds ProgramArguments=["/bin/bash", wrapperPath],
+    // WorkingDirectory=`${INSTALL_DIR}/server`, std{out,err}Path=`<logsDir>/server.log`.
+    const xml = renderPlist({
+        label: "com.rubytech.maxy-code",
+        programArguments: ["/bin/bash", "/Users/alice/.maxy-code/launchd-wrapper.sh"],
+        stdoutPath: "/Users/alice/.maxy-code/logs/server.log",
+        stderrPath: "/Users/alice/.maxy-code/logs/server.log",
+        keepAlive: true,
+        runAtLoad: true,
+        workingDirectory: "/Users/alice/maxy-code/server",
+    });
+    assert.match(xml, /<key>Label<\/key>\s*<string>com\.rubytech\.maxy-code<\/string>/);
+    assert.match(xml, /<string>\/bin\/bash<\/string>/);
+    assert.match(xml, /<string>\/Users\/alice\/\.maxy-code\/launchd-wrapper\.sh<\/string>/);
+    assert.match(xml, /<key>WorkingDirectory<\/key>\s*<string>\/Users\/alice\/maxy-code\/server<\/string>/);
+    assert.match(xml, /<key>StandardOutPath<\/key>\s*<string>\/Users\/alice\/\.maxy-code\/logs\/server\.log<\/string>/);
+    assert.match(xml, /<key>KeepAlive<\/key>\s*<true\/>/);
+    assert.match(xml, /<key>RunAtLoad<\/key>\s*<true\/>/);
+});
+test("renderPlist realagent-code brand fields land in the plist verbatim", () => {
+    // BRAND.hostname=realagent-code, configDir=.realagent-code per brands/realagent-code/brand.json.
+    // The label must differ from the maxy-code label so a co-resident install
+    // produces two distinct ~/Library/LaunchAgents/<label>.plist files.
+    const xml = renderPlist({
+        label: "com.rubytech.realagent-code",
+        programArguments: ["/bin/bash", "/Users/alice/.realagent-code/launchd-wrapper.sh"],
+        stdoutPath: "/Users/alice/.realagent-code/logs/server.log",
+        stderrPath: "/Users/alice/.realagent-code/logs/server.log",
+        keepAlive: true,
+        runAtLoad: true,
+        workingDirectory: "/Users/alice/realagent-code/server",
+    });
+    assert.match(xml, /<key>Label<\/key>\s*<string>com\.rubytech\.realagent-code<\/string>/);
+    assert.match(xml, /<string>\/Users\/alice\/\.realagent-code\/launchd-wrapper\.sh<\/string>/);
+    assert.match(xml, /<key>WorkingDirectory<\/key>\s*<string>\/Users\/alice\/realagent-code\/server<\/string>/);
+    // Label collision guard — the maxy-code label must not appear in a realagent plist.
+    assert.ok(!/com\.rubytech\.maxy-code/.test(xml), "realagent plist must not carry maxy-code label");
+});
+test("renderPlist omits WorkingDirectory key when workingDirectory is absent", () => {
+    const xml = renderPlist({
+        label: "com.rubytech.maxy",
+        programArguments: ["/usr/local/bin/node", "/srv/server.js"],
+        stdoutPath: "/dev/null",
+        stderrPath: "/dev/null",
+        keepAlive: true,
+        runAtLoad: true,
+        // workingDirectory omitted on purpose
+    });
+    assert.ok(!/WorkingDirectory/.test(xml), "WorkingDirectory key must not appear when omitted");
+    // Required fields still present.
+    assert.match(xml, /<key>Label<\/key>/);
+    assert.match(xml, /<key>ProgramArguments<\/key>/);
+    assert.match(xml, /<key>StandardOutPath<\/key>/);
+    assert.match(xml, /<key>StandardErrorPath<\/key>/);
+    assert.match(xml, /<key>KeepAlive<\/key>/);
+    assert.match(xml, /<key>RunAtLoad<\/key>/);
+});

package/dist/__tests__/macos-darwin-branch.test.js

@@ -0,0 +1,85 @@
+// Static-grep contract for the darwin install branches in index.ts.
+//
+// Task 297 audited every `platform === "darwin"` block; this test pins the
+// shape so a future refactor that removes a darwin branch without an explicit
+// reason fails loudly here. The test reads src/index.ts at runtime (the
+// authoritative source) and regex-asserts the per-branch markers — keeping
+// the spec adjacent to the code rather than buried in a doc.
+//
+// Why static-grep, not behaviour: the install branches each spawn (sudo,
+// brew, launchctl), and end-to-end darwin reproduction belongs to the manual
+// smoke path in the task brief. The unit suite's job is to ensure the
+// branch points still exist after a refactor.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+// dist/__tests__/macos-darwin-branch.test.js → ../../src/index.ts
+const here = dirname(fileURLToPath(import.meta.url));
+const INDEX_TS = resolve(here, "../../src/index.ts");
+const SRC = readFileSync(INDEX_TS, "utf-8");
+test("installSystemDeps has darwin branch that calls setMacosHostnameViaScutil on --hostname and scutil --get LocalHostName without", () => {
+    // The hostname block at index.ts:installSystemDeps must:
+    //   - call setMacosHostnameViaScutil(HOSTNAME_FLAG) when HOSTNAME_FLAG is set
+    //   - call scutil --get LocalHostName when HOSTNAME_FLAG is absent
+    // The two paths are the contract Task 297 locks in.
+    assert.match(SRC, /setMacosHostnameViaScutil\(HOSTNAME_FLAG\)/, "scutil-set path on --hostname must call setMacosHostnameViaScutil");
+    assert.match(SRC, /scutil["']?,\s*\[["']--get["']\s*,\s*["']LocalHostName["']\]/, "scutil --get LocalHostName must be the no-flag default on darwin");
+    assert.match(SRC, /darwin-hostname-mode=scutil-get/, "scutil-get success path must emit observability log");
+    assert.match(SRC, /darwin-hostname-mode=scutil-set/, "scutil-set path must emit observability log");
+    assert.match(SRC, /darwin-hostname-mode=brand-fallback/, "brand-fallback path must emit observability log");
+});
+test("installSystemDeps darwin branch installs DARWIN_BASE_DEPS via brew", () => {
+    // The shared dep set the darwin path feeds to installAllBrewPackages. If
+    // this list shrinks or a name changes, brew-resolve.test.ts (DARWIN_BASE_DEPS_FIXTURE)
+    // must move in lockstep — the comment in brew-resolve.test.ts says so.
+    assert.match(SRC, /DARWIN_BASE_DEPS\s*=\s*\[\s*"curl"\s*,\s*"git"\s*,\s*"unzip"\s*,\s*"jq"\s*,\s*"poppler"\s*,\s*"ffmpeg"\s*,\s*"tesseract"\s*,\s*"ocrmypdf"\s*\]/);
+    assert.match(SRC, /installAllBrewPackages\(DARWIN_BASE_DEPS,\s*logFile\)/);
+});
+test("installCloudflared darwin branch logs the documented skip and brew-installs cloudflared", () => {
+    // Task 297 doctrine: skip tunnel provisioning entirely on darwin. The brew
+    // install puts the binary on PATH so the operator can opt in to `cloudflared
+    // tunnel login` post-install; the explicit log line is the diagnostic
+    // anchor for investigators grepping the install log.
+    assert.match(SRC, /darwin-cloudflare-skip=true/);
+    assert.match(SRC, /installAllBrewPackages\(\["cloudflared"\],\s*logFile\)/);
+    // No `cloudflared service install` or `cloudflared tunnel route dns`
+    // invocation in the installer surface — those are operator-driven,
+    // post-install steps. Match actual argv shapes (string-literal list to
+    // spawnSync/shell) rather than prose: argv arrays carry the args as
+    // quoted siblings inside `[...]`. Comment text is filtered by requiring
+    // a quote character immediately adjacent.
+    assert.ok(!/\[\s*["']cloudflared["'][^\]]*["']service["'][^\]]*["']install["']/.test(SRC), "installer must not invoke `cloudflared service install`");
+    assert.ok(!/\[\s*["']cloudflared["'][^\]]*["']tunnel["'][^\]]*["']route["'][^\]]*["']dns["']/.test(SRC), "installer must not invoke `cloudflared tunnel route dns`");
+});
+test("installService darwin branch delegates to installServiceDarwin (launchd path, not systemd)", () => {
+    // Two contracts: the platform switch routes darwin to installServiceDarwin,
+    // and installServiceDarwin writes the plist + bootstraps it via launchctl.
+    assert.match(SRC, /platform\s*===\s*"darwin"\s*\)\s*\{\s*installServiceDarwin\(\)/);
+    assert.match(SRC, /launchctl["']?,\s*\[["']bootstrap["']/);
+    assert.match(SRC, /launchd-plist=\$\{path\}\s+loaded=true/, "successful bootstrap must emit launchd-plist=…  loaded=true");
+    assert.match(SRC, /launchd-plist=\$\{path\}\s+loaded=false/, "failed bootstrap must emit launchd-plist=…  loaded=false");
+});
+test("installNodejs darwin branch brew-installs the `nodejs` alias name (resolver hops to node@22)", () => {
+    // The shared call site uses the apt-style `nodejs` name. brew-resolve.ts
+    // hops it to `node@22` via DARWIN_ALIASES — the alias is the deliberate
+    // wedge so a single dep name works across both backends.
+    assert.match(SRC, /platform\s*===\s*"darwin"[\s\S]{0,400}installAllBrewPackages\(\["nodejs"\]/);
+});
+test("installNeo4j darwin branch brew-installs `neo4j` (no alias hop)", () => {
+    // `neo4j` is the concrete brew formula name on darwin, no alias needed.
+    assert.match(SRC, /platform\s*===\s*"darwin"[\s\S]{0,800}installAllBrewPackages\(\["neo4j"\]/);
+});
+test("chromium binary-path file write skips darwin (Playwright-managed)", () => {
+    // writeChromiumBinaryPathFile early-returns on non-linux. The completion URL
+    // and VNC stack on darwin use Playwright/brew-managed Chromium instead of
+    // the linux per-brand chromium-binary.path file.
+    assert.match(SRC, /writeChromiumBinaryPathFile[\s\S]{0,200}process\.platform\s*!==\s*"linux"/);
+});
+test("uninstall darwin path bootsout the LaunchAgent and removes the plist", () => {
+    // The uninstall surface lives in uninstall.ts (separate file); this index.ts
+    // sanity check just confirms the launchdLabel helper still exists and is
+    // brand-keyed — install + uninstall both depend on the same label shape.
+    assert.match(SRC, /function launchdLabel\(\):\s*string\s*\{\s*return\s*`com\.rubytech\.\$\{BRAND\.hostname\}`/);
+});

package/dist/__tests__/macos-version.test.js

@@ -0,0 +1,96 @@
+// acceptance grid for macos-version.ts.
+//
+// Pure two-export module: parseSwVers extracts ProductName + ProductVersion
+// from `sw_vers` stdout; isSupportedMacosVersion checks whether the version's
+// major component is ≥ 14 (the floor Tasks 838/839 require for modern
+// `launchctl bootstrap gui/$UID …` and Apple-Silicon Homebrew). No I/O — the
+// caller spawns `sw_vers` and feeds stdout in, mirroring apt-resolve.ts.
+//
+// Runs via Node's built-in test runner; no vitest. Compiles to
+// dist/__tests__/macos-version.test.js so `node --test dist/__tests__/*.test.js`
+// picks it up after build.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseSwVers, isSupportedMacosVersion, } from "../macos-version.js";
+// ---------------------------------------------------------------------------
+// Real fixtures — captured from `sw_vers` on actual macOS hosts. The trailing
+// newline matches subprocess stdout exactly; parseSwVers must tolerate it.
+// ---------------------------------------------------------------------------
+const SW_VERS_MACOS_14_4_1 = `ProductName: macOS
+ProductVersion: 14.4.1
+BuildVersion: 23E224
+`;
+const SW_VERS_MACOS_13_7_1 = `ProductName: macOS
+ProductVersion: 13.7.1
+BuildVersion: 22H313
+`;
+const SW_VERS_MACOS_14_0 = `ProductName: macOS
+ProductVersion: 14.0
+BuildVersion: 23A344
+`;
+const SW_VERS_MACOS_15_2 = `ProductName: macOS
+ProductVersion: 15.2
+BuildVersion: 24C101
+`;
+const SW_VERS_MACOS_12_7_6 = `ProductName: macOS
+ProductVersion: 12.7.6
+BuildVersion: 21H1320
+`;
+// ---------------------------------------------------------------------------
+// parseSwVers — extracts ProductName + ProductVersion; null on malformed.
+// ---------------------------------------------------------------------------
+test("parseSwVers extracts product + version from macOS 14.4.1 fixture", () => {
+    const r = parseSwVers(SW_VERS_MACOS_14_4_1);
+    assert.deepEqual(r, { product: "macOS", version: "14.4.1" });
+});
+test("parseSwVers extracts product + version from macOS 13.7.1 fixture", () => {
+    const r = parseSwVers(SW_VERS_MACOS_13_7_1);
+    assert.deepEqual(r, { product: "macOS", version: "13.7.1" });
+});
+test("parseSwVers handles macOS 14.0 (no patch component)", () => {
+    const r = parseSwVers(SW_VERS_MACOS_14_0);
+    assert.deepEqual(r, { product: "macOS", version: "14.0" });
+});
+test("parseSwVers handles macOS 12.7.6 (legacy three-component)", () => {
+    const r = parseSwVers(SW_VERS_MACOS_12_7_6);
+    assert.deepEqual(r, { product: "macOS", version: "12.7.6" });
+});
+test("parseSwVers returns null on empty stdout (spawn failed)", () => {
+    assert.equal(parseSwVers(""), null);
+});
+test("parseSwVers returns null on stdout missing ProductVersion line", () => {
+    // Defensive: future `sw_vers` schema change must not silently produce
+    // `{ product: "macOS", version: undefined }` — we want a hard null so the
+    // caller refuses with the malformed-stdout diagnostic.
+    assert.equal(parseSwVers("ProductName: macOS\nBuildVersion: 23E224\n"), null);
+});
+test("parseSwVers returns null on stdout missing ProductName line", () => {
+    assert.equal(parseSwVers("ProductVersion: 14.4.1\nBuildVersion: 23E224\n"), null);
+});
+test("parseSwVers returns null on totally unrelated stdout", () => {
+    assert.equal(parseSwVers("hello world\n"), null);
+});
+// ---------------------------------------------------------------------------
+// isSupportedMacosVersion — boundary at major ≥ 14.
+// ---------------------------------------------------------------------------
+test("isSupportedMacosVersion: 14.0 → true (boundary, exactly the floor)", () => {
+    assert.equal(isSupportedMacosVersion("14.0"), true);
+});
+test("isSupportedMacosVersion: 14.4.1 → true (current shipping macOS 14)", () => {
+    assert.equal(isSupportedMacosVersion("14.4.1"), true);
+});
+test("isSupportedMacosVersion: 15.2 → true (future macOS 15)", () => {
+    assert.equal(isSupportedMacosVersion(parseSwVers(SW_VERS_MACOS_15_2)?.version ?? ""), true);
+});
+test("isSupportedMacosVersion: 13.7.1 → false (one minor below floor)", () => {
+    assert.equal(isSupportedMacosVersion("13.7.1"), false);
+});
+test("isSupportedMacosVersion: 12.7.6 → false (well below floor)", () => {
+    assert.equal(isSupportedMacosVersion("12.7.6"), false);
+});
+test("isSupportedMacosVersion: empty string → false (parse failure surrogate)", () => {
+    assert.equal(isSupportedMacosVersion(""), false);
+});
+test("isSupportedMacosVersion: garbage string → false (no leading integer)", () => {
+    assert.equal(isSupportedMacosVersion("not a version"), false);
+});

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/__tests__/peer-brand-detect.test.js

@@ -0,0 +1,103 @@
+// 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/__tests__/platform-detect.test.js

@@ -0,0 +1,50 @@
+// wedge — acceptance grid for platform-detect.ts.
+//
+// Pure two-export module: detectPlatform classifies any process.platform value
+// into the ternary the installer cares about; requireSupportedPlatform throws on
+// unsupported with the literal refusal message that follow-up tasks (838/839/840)
+// will surface in install logs. Caller injects the platform value so tests run
+// identically on Linux CI and Mac developer boxes — no process.platform reads
+// inside the module under test.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { detectPlatform, requireSupportedPlatform, } from "../platform-detect.js";
+// ---------------------------------------------------------------------------
+// detectPlatform — ternary classifier over Node's process.platform values.
+// ---------------------------------------------------------------------------
+test("detectPlatform: linux maps to linux", () => {
+    assert.equal(detectPlatform("linux"), "linux");
+});
+test("detectPlatform: darwin maps to darwin", () => {
+    assert.equal(detectPlatform("darwin"), "darwin");
+});
+test("detectPlatform: win32 maps to unsupported", () => {
+    assert.equal(detectPlatform("win32"), "unsupported");
+});
+test("detectPlatform: every other Node platform maps to unsupported", () => {
+    // Lock the set so a future Node version that adds a new platform string
+    // doesn't accidentally fall into 'linux' or 'darwin' via a typo.
+    for (const p of ["freebsd", "openbsd", "sunos", "aix", "cygwin", "netbsd", "android", "haiku"]) {
+        assert.equal(detectPlatform(p), "unsupported", `${p} must be unsupported`);
+    }
+});
+// ---------------------------------------------------------------------------
+// requireSupportedPlatform — return narrowed value or throw with literal msg.
+// ---------------------------------------------------------------------------
+test("requireSupportedPlatform: linux returns 'linux'", () => {
+    assert.equal(requireSupportedPlatform("linux"), "linux");
+});
+test("requireSupportedPlatform: darwin returns 'darwin'", () => {
+    assert.equal(requireSupportedPlatform("darwin"), "darwin");
+});
+test("requireSupportedPlatform: win32 throws with the literal refusal message", () => {
+    assert.throws(() => requireSupportedPlatform("win32"), {
+        message: "[create-maxy] platform=win32 — refusing: only linux and darwin are supported",
+    });
+});
+test("requireSupportedPlatform: refusal message embeds the actual platform string", () => {
+    // The platform token in the message is load-bearing for log-grep diagnostics
+    // spec calls out `[create-maxy] platform=darwin macos=<v> — refusing`
+    // as the failure signature for macOS-14 pre-flight. Pin the token verbatim.
+    assert.throws(() => requireSupportedPlatform("freebsd"), /^Error: \[create-maxy\] platform=freebsd — refusing: only linux and darwin are supported$/);
+});

package/dist/__tests__/platform-port-stamp.test.js

@@ -0,0 +1,28 @@
+// Task 142 — manager systemd unit must stamp PLATFORM_PORT equal to
+// MAXY_UI_INTERNAL_PORT so admin and whatsapp MCP servers inherit the
+// internal-loopback port. The producer-side gap closed in Task 142
+// after Task 139 removed every consumer-side fallback.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildClaudeSessionManagerUnitFile } from "../port-resolution.js";
+test("PLATFORM_PORT stamped on manager unit equal to MAXY_UI_INTERNAL_PORT", () => {
+    const unit = buildClaudeSessionManagerUnitFile({
+        productName: "Maxy",
+        brandHostname: "maxy",
+        installDir: "/opt/maxy",
+        persistDir: "/home/admin/.maxy",
+        claudeSessionManagerPort: 11200,
+        brandPort: 19200,
+        maxyUiInternalPort: 19201,
+        accountId: "00000000-0000-0000-0000-000000000000",
+        cdpPort: 9222,
+    });
+    assert.match(unit, /^Environment=PLATFORM_PORT=19201$/m);
+    assert.match(unit, /^Environment=MAXY_UI_INTERNAL_PORT=19201$/m);
+    assert.match(unit, /^Environment=MAXY_BRAND_PORT=19200$/m);
+    // Task 492 — CDP_PORT stamped so the browser plugin's MCP server can
+    // attach to the per-brand VNC Chromium.
+    assert.match(unit, /^Environment=CDP_PORT=9222$/m);
+    // Order is not asserted; coexistence with the existing brand-port and
+    // internal-port lines is what producers and consumers contract on.
+});