@rubytech/create-maxy-code 0.1.0

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

@@ -0,0 +1,149 @@
+// Task 838 — 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.
+// ---------------------------------------------------------------------------
+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-version.test.js

@@ -0,0 +1,96 @@
+// Task 840 — 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__/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/__tests__/platform-detect.test.js

@@ -0,0 +1,50 @@
+// Task 836 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
+    // — Task 836 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__/port-canonicalisation.test.js

@@ -0,0 +1,200 @@
+// Task 666 — acceptance gate for the port writer + drift-recovery flow.
+//
+// Three invariants this test protects:
+//   (a) PORT stays public across install → upgrade on a fresh fs fixture.
+//       Without this, each upgrade re-inherits the internal port as if it
+//       were public — the exact regression this task fixes.
+//   (b) Drift-recovery logs fire EXACTLY once when a pre-task maxy.service
+//       with a drifted PORT meets a post-task installer. A second upgrade
+//       on the same device must be silent.
+//   (c) MAXY_UI_INTERNAL_PORT is PORT + 1 in every written unit file, so
+//       maxy-ui binds the internal port while the tunnel still hits edge.
+//
+// Runs via Node's built-in test runner; no vitest dependency. Compiles to
+// dist/__tests__/port-canonicalisation.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 { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveInstallPort, resolveInstallPortFromFs, buildMaxyUnitFile, } from "../port-resolution.js";
+function makeUnitFile(port, internal) {
+    return buildMaxyUnitFile({
+        productName: "Maxy",
+        brandHostname: "maxy",
+        neo4jDedicated: false,
+        installDir: "/home/me/maxy",
+        persistDir: "/home/me/.maxy",
+        port,
+        maxyUiInternalPort: internal,
+        vncDisplay: 99,
+        rfbPort: 5900,
+        websockifyPort: 6080,
+        cdpPort: 9222,
+        claudeSessionManagerPort: 19400,
+        chromiumBin: "/usr/bin/chromium",
+        accountId: "00000000-0000-0000-0000-000000000001",
+    });
+}
+function makeEdgeFile(edgePort) {
+    return `[Unit]\nDescription=Edge\n\n[Service]\nEnvironment=EDGE_PORT=${edgePort}\nEnvironment=MAXY_UI_PORT=${edgePort + 1}\n`;
+}
+// ---------------------------------------------------------------------------
+// (a) Fresh install writes PORT=public + MAXY_UI_INTERNAL_PORT=public+1 —
+// and a subsequent upgrade reads the SAME public value back. No drift.
+// ---------------------------------------------------------------------------
+test("fresh install then upgrade keeps PORT public (no drift)", () => {
+    const PUBLIC = 19200;
+    const INTERNAL = PUBLIC + 1;
+    // Fresh install: no existing service file, no .env → default.
+    const first = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: null,
+        edgeServiceContent: null,
+    });
+    assert.equal(first.port, PUBLIC);
+    assert.equal(first.source, "default");
+    assert.equal(first.driftLogs.length, 0);
+    // Installer writes the unit files with PORT=public, MAXY_UI_INTERNAL_PORT=+1.
+    const maxyUnit = makeUnitFile(first.port, first.port + 1);
+    const edgeUnit = makeEdgeFile(first.port);
+    // Upgrade reads them back. Same public value, no drift.
+    const second = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: maxyUnit,
+        edgeServiceContent: edgeUnit,
+    });
+    assert.equal(second.port, PUBLIC, "upgrade must not drift the public port");
+    assert.equal(second.source, "running service");
+    assert.equal(second.driftLogs.length, 0, "no drift expected on clean device");
+    // And one more upgrade for good measure — still silent.
+    const third = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: maxyUnit,
+        edgeServiceContent: edgeUnit,
+    });
+    assert.equal(third.port, PUBLIC);
+    assert.equal(third.driftLogs.length, 0);
+    // Unit file literal invariants (c): PORT is the public, INTERNAL is +1.
+    assert.match(maxyUnit, /^Environment=PORT=19200$/m);
+    assert.match(maxyUnit, /^Environment=MAXY_UI_INTERNAL_PORT=19201$/m);
+});
+// ---------------------------------------------------------------------------
+// (b) Drifted device: pre-task maxy.service has the INTERNAL port (19201) in
+// the PORT slot, edge has the canonical public (19200). Recovery logs once,
+// pins at edge, and the next pass on the rewritten files is silent.
+// ---------------------------------------------------------------------------
+test("drifted device recovers in one pass, subsequent upgrade is silent", () => {
+    const TRUE_PUBLIC = 19200;
+    // Pre-task unit: Environment=PORT=<internal>. Edge correctly carries public.
+    const driftedMaxy = makeUnitFile(TRUE_PUBLIC + 1, TRUE_PUBLIC + 2); // drifted
+    const edgeAtTruth = makeEdgeFile(TRUE_PUBLIC);
+    const recovery = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: driftedMaxy,
+        edgeServiceContent: edgeAtTruth,
+    });
+    assert.equal(recovery.port, TRUE_PUBLIC, "edge wins over drifted maxy");
+    assert.equal(recovery.source, "edge-recovery");
+    assert.equal(recovery.driftLogs.length, 1, "exactly one drift line");
+    assert.match(recovery.driftLogs[0], /\[port-recovery\] detected drift maxy=19201 edge=19200 — pinning at 19200/);
+    // After recovery, the installer writes a corrected maxy.service.
+    const rewritten = makeUnitFile(recovery.port, recovery.port + 1);
+    // Next upgrade on the same device: both files agree, no log line.
+    const silent = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: rewritten,
+        edgeServiceContent: edgeAtTruth,
+    });
+    assert.equal(silent.port, TRUE_PUBLIC);
+    assert.equal(silent.source, "running service");
+    assert.equal(silent.driftLogs.length, 0, "post-recovery upgrade must be silent");
+});
+// ---------------------------------------------------------------------------
+// --port flag short-circuits every source, including drift recovery (the
+// operator is asserting a port explicitly).
+// ---------------------------------------------------------------------------
+test("--port flag short-circuits drift recovery", () => {
+    const driftedMaxy = makeUnitFile(20001, 20002);
+    const edge = makeEdgeFile(19200);
+    const result = resolveInstallPort({
+        portFlag: 31000,
+        envContent: null,
+        maxyServiceContent: driftedMaxy,
+        edgeServiceContent: edge,
+    });
+    assert.equal(result.port, 31000);
+    assert.equal(result.source, "--port flag");
+    assert.equal(result.driftLogs.length, 0);
+});
+// ---------------------------------------------------------------------------
+// Legacy pre-647 device (no edge unit): reader uses maxy.service's PORT value,
+// no drift log emitted.
+// ---------------------------------------------------------------------------
+test("pre-647 device without edge unit reads maxy PORT, no drift log", () => {
+    const legacyMaxy = `[Service]\nEnvironment=PORT=19200\n`;
+    const result = resolveInstallPort({
+        envContent: null,
+        maxyServiceContent: legacyMaxy,
+        edgeServiceContent: null,
+    });
+    assert.equal(result.port, 19200);
+    assert.equal(result.source, "running service");
+    assert.equal(result.driftLogs.length, 0);
+});
+// ---------------------------------------------------------------------------
+// .env override takes priority over the service file; drift recovery still
+// runs against whatever was computed.
+// ---------------------------------------------------------------------------
+test(".env override wins over service file; drift recovery still runs", () => {
+    const env = "PORT=19500\nEMBED_MODEL=nomic\n";
+    const maxy = makeUnitFile(19200, 19201);
+    const edge = makeEdgeFile(19500);
+    // .env says 19500, maxy.service says 19200, edge says 19500. Reader
+    // picks .env (19500), edge confirms (19500) — no drift.
+    const resolved = resolveInstallPort({
+        envContent: env,
+        maxyServiceContent: maxy,
+        edgeServiceContent: edge,
+    });
+    assert.equal(resolved.port, 19500);
+    assert.equal(resolved.source, ".env override");
+    assert.equal(resolved.driftLogs.length, 0);
+    // Now the .env says 19202 (drifted), edge says 19500 — drift recovery wins.
+    const driftedEnv = "PORT=19202\nEMBED_MODEL=nomic\n";
+    const recovered = resolveInstallPort({
+        envContent: driftedEnv,
+        maxyServiceContent: maxy,
+        edgeServiceContent: edge,
+    });
+    assert.equal(recovered.port, 19500);
+    assert.equal(recovered.source, "edge-recovery");
+    assert.equal(recovered.driftLogs.length, 1);
+});
+// ---------------------------------------------------------------------------
+// fs wrapper end-to-end: real tmpdir fixture, verifies the file-reading path.
+// ---------------------------------------------------------------------------
+test("fs wrapper reads real fixture files end-to-end", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "maxy-port-test-"));
+    try {
+        const persistDir = join(tmp, ".maxy");
+        const serviceDir = join(tmp, ".config", "systemd", "user");
+        mkdirSync(persistDir, { recursive: true });
+        mkdirSync(serviceDir, { recursive: true });
+        writeFileSync(join(serviceDir, "maxy.service"), makeUnitFile(19300, 19301));
+        writeFileSync(join(serviceDir, "maxy-edge.service"), makeEdgeFile(19300));
+        const result = resolveInstallPortFromFs({
+            persistDir,
+            serviceDir,
+            brandServiceFileName: "maxy.service",
+            brandEdgeServiceFileName: "maxy-edge.service",
+        });
+        assert.equal(result.port, 19300);
+        assert.equal(result.source, "running service");
+        assert.equal(result.driftLogs.length, 0);
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+});