@rubytech/create-maxy-code 0.1.0

package/dist/__tests__/account-id-env.test.js

@@ -0,0 +1,48 @@
+// Task 955 — acceptance gate for ACCOUNT_ID stamping in the brand systemd unit.
+//
+// Two invariants this test protects:
+//   (a) buildMaxyUnitFile emits a literal `Environment=ACCOUNT_ID=<uuid>` line
+//       in the [Service] block when accountId is provided. Pi recovery via
+//       `npx -y @rubytech/create-maxy@latest` depends on this line landing —
+//       without it, process.env.ACCOUNT_ID is undefined and the
+//       writeNodeWithEdges gate rejects every CF-setup graph write at
+//       cloudflare-task-tracker.ts:187/326/347/559.
+//   (b) buildMaxyUnitFile throws on an empty accountId. Falling through with
+//       "" would emit a unit with no ACCOUNT_ID line; the boot validator at
+//       platform/ui/server/index.ts would then FATAL reason=missing on every
+//       restart, surfacing the same regression class behind a different log
+//       prefix. Throwing at build time aborts the install loud, before the
+//       broken unit is written.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildMaxyUnitFile } from "../port-resolution.js";
+const VALID_UUID = "12345678-9abc-def0-1234-56789abcdef0";
+function callBuildUnit(accountId) {
+    return buildMaxyUnitFile({
+        productName: "Maxy",
+        brandHostname: "maxy",
+        neo4jDedicated: false,
+        installDir: "/home/me/maxy",
+        persistDir: "/home/me/.maxy",
+        port: 19200,
+        maxyUiInternalPort: 19201,
+        vncDisplay: 99,
+        rfbPort: 5900,
+        websockifyPort: 6080,
+        cdpPort: 9222,
+        claudeSessionManagerPort: 19400,
+        chromiumBin: "/usr/bin/chromium",
+        accountId,
+    });
+}
+test("buildMaxyUnitFile emits Environment=ACCOUNT_ID=<uuid> for a valid accountId", () => {
+    const unit = callBuildUnit(VALID_UUID);
+    assert.match(unit, /^Environment=ACCOUNT_ID=12345678-9abc-def0-1234-56789abcdef0$/m, "ACCOUNT_ID line missing or malformed");
+    // Placement matters: identity (NODE_ENV → ACCOUNT_ID → PORT) so the most
+    // fundamental brand identity sits next to the env that selects the brand
+    // runtime. Anchored regex against the three adjacent lines.
+    assert.match(unit, /Environment=NODE_ENV=production\nEnvironment=ACCOUNT_ID=12345678-9abc-def0-1234-56789abcdef0\nEnvironment=PORT=19200/, "ACCOUNT_ID line is not placed between NODE_ENV and PORT");
+});
+test("buildMaxyUnitFile throws when accountId is empty", () => {
+    assert.throws(() => callBuildUnit(""), /accountId is required/, "expected throw on empty accountId, did not throw");
+});

package/dist/__tests__/apt-resolve.test.js

@@ -0,0 +1,179 @@
+// Task 638 — acceptance grid for apt-resolve.ts.
+//
+// Locks the four resolver branches from Task 637 plus the os-release parser
+// and Candidate-line extractor. Inputs are passed directly so no mocking is
+// needed — every test exercises pure logic with concrete fixtures captured
+// from real devices (Noble `apt-cache policy chromium`, Bookworm ditto,
+// Pop!_OS `/etc/os-release`).
+//
+// Runs via Node's built-in test runner; no vitest dependency. Compiles to
+// dist/__tests__/apt-resolve.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 { UBUNTU_ALIASES, parseOsRelease, isUbuntuLike, parseAptCacheCandidate, decideAptResolution, } from "../apt-resolve.js";
+// ---------------------------------------------------------------------------
+// Real fixtures — captured from devices the installer actually targets.
+// ---------------------------------------------------------------------------
+const UBUNTU_NOBLE_OS_RELEASE = `PRETTY_NAME="Ubuntu 24.04 LTS"
+NAME="Ubuntu"
+VERSION_ID="24.04"
+VERSION="24.04 LTS (Noble Numbat)"
+VERSION_CODENAME=noble
+ID=ubuntu
+ID_LIKE=debian
+HOME_URL="https://www.ubuntu.com/"
+UBUNTU_CODENAME=noble`;
+const DEBIAN_BOOKWORM_OS_RELEASE = `PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
+NAME="Debian GNU/Linux"
+VERSION_ID="12"
+VERSION="12 (bookworm)"
+VERSION_CODENAME=bookworm
+ID=debian
+HOME_URL="https://www.debian.org/"`;
+const POP_OS_OS_RELEASE = `NAME="Pop!_OS"
+VERSION="22.04 LTS"
+ID=pop
+ID_LIKE="ubuntu debian"
+PRETTY_NAME="Pop!_OS 22.04 LTS"
+VERSION_ID="22.04"
+VERSION_CODENAME=jammy
+UBUNTU_CODENAME=jammy`;
+// `apt-cache policy chromium` on Ubuntu Noble (the alias case Task 637 fixed).
+const NOBLE_CHROMIUM_POLICY = `chromium:
+  Installed: (none)
+  Candidate: (none)
+  Version table:`;
+// `apt-cache policy chromium` on Debian Bookworm (concrete .deb, no alias).
+const BOOKWORM_CHROMIUM_POLICY = `chromium:
+  Installed: (none)
+  Candidate: 120.0.6099.224-1~deb12u1
+  Version table:
+     120.0.6099.224-1~deb12u1 500
+        500 http://deb.debian.org/debian bookworm-security/main arm64 Packages`;
+// ---------------------------------------------------------------------------
+// parseOsRelease — every key/value pair lands, quoted values get unquoted.
+// ---------------------------------------------------------------------------
+test("parseOsRelease unquotes values and captures all keys", () => {
+    const noble = parseOsRelease(UBUNTU_NOBLE_OS_RELEASE);
+    assert.equal(noble.ID, "ubuntu");
+    assert.equal(noble.ID_LIKE, "debian");
+    assert.equal(noble.VERSION_CODENAME, "noble");
+    assert.equal(noble.NAME, "Ubuntu", "double-quoted values must be unquoted");
+    assert.equal(noble.PRETTY_NAME, "Ubuntu 24.04 LTS");
+});
+test("parseOsRelease handles space-separated ID_LIKE (Pop!_OS)", () => {
+    const pop = parseOsRelease(POP_OS_OS_RELEASE);
+    assert.equal(pop.ID, "pop");
+    assert.equal(pop.ID_LIKE, "ubuntu debian", "quoted multi-value must be preserved as a single string");
+});
+// ---------------------------------------------------------------------------
+// isUbuntuLike — Ubuntu, Pop!_OS pick up; Debian does not.
+// ---------------------------------------------------------------------------
+test("isUbuntuLike accepts Ubuntu directly and via ID_LIKE", () => {
+    assert.equal(isUbuntuLike(parseOsRelease(UBUNTU_NOBLE_OS_RELEASE)), true, "Ubuntu Noble: ID=ubuntu");
+    assert.equal(isUbuntuLike(parseOsRelease(POP_OS_OS_RELEASE)), true, "Pop!_OS: ID_LIKE contains ubuntu");
+    assert.equal(isUbuntuLike(parseOsRelease(DEBIAN_BOOKWORM_OS_RELEASE)), false, "Debian Bookworm: not Ubuntu-like");
+    assert.equal(isUbuntuLike({}), false, "empty os-release (read failed): not Ubuntu-like");
+});
+// ---------------------------------------------------------------------------
+// parseAptCacheCandidate — three states: real candidate, "(none)", absent.
+// ---------------------------------------------------------------------------
+test("parseAptCacheCandidate distinguishes real candidate, (none), and missing", () => {
+    assert.equal(parseAptCacheCandidate(BOOKWORM_CHROMIUM_POLICY), "120.0.6099.224-1~deb12u1");
+    assert.equal(parseAptCacheCandidate(NOBLE_CHROMIUM_POLICY), "(none)");
+    assert.equal(parseAptCacheCandidate(""), null, "empty stdout (spawn failed) → null");
+    assert.equal(parseAptCacheCandidate("totally unrelated text"), null, "no Candidate line → null");
+});
+// ---------------------------------------------------------------------------
+// decideAptResolution — the four resolver branches from Task 637.
+// ---------------------------------------------------------------------------
+test("decideAptResolution: dpkg-installed package returns pkg, no log", () => {
+    // Branch (1): dpkg -s exits 0 — name is concrete and installed.
+    const r = decideAptResolution({
+        pkg: "curl",
+        dpkgInstalled: true,
+        aptCandidate: null,
+        ubuntuLike: true,
+        distro: "ubuntu-noble",
+    });
+    assert.equal(r.resolved, "curl");
+    assert.equal(r.log, null);
+});
+test("decideAptResolution: real apt candidate returns pkg, no log (Bookworm chromium)", () => {
+    // Branch (2): apt-cache policy says there IS a real candidate — leave name
+    // alone, the post-check will use the same name.
+    const r = decideAptResolution({
+        pkg: "chromium",
+        dpkgInstalled: false,
+        aptCandidate: "120.0.6099.224-1~deb12u1",
+        ubuntuLike: false,
+        distro: "debian-bookworm",
+    });
+    assert.equal(r.resolved, "chromium");
+    assert.equal(r.log, null);
+});
+test("decideAptResolution: Noble chromium → chromium-browser with log line", () => {
+    // Branch (3): the load-bearing case Task 637 fixed.
+    const r = decideAptResolution({
+        pkg: "chromium",
+        dpkgInstalled: false,
+        aptCandidate: "(none)",
+        ubuntuLike: true,
+        distro: "ubuntu-noble",
+    });
+    assert.equal(r.resolved, "chromium-browser");
+    assert.match(r.log ?? "", /^  apt-resolve chromium → chromium-browser \(reason=candidate-none, distro=ubuntu-noble\)$/);
+});
+test("decideAptResolution: Bookworm + alias-keyed pkg + candidate-none returns pkg unchanged", () => {
+    // Branch (4) variant: not Ubuntu-like, so even an alias-keyed pkg falls
+    // through. Preserves Task 634's loud-failure contract — apt-get install
+    // will fail, post-check throws, operator sees the real diagnostic.
+    const r = decideAptResolution({
+        pkg: "chromium",
+        dpkgInstalled: false,
+        aptCandidate: "(none)",
+        ubuntuLike: false,
+        distro: "debian-bookworm",
+    });
+    assert.equal(r.resolved, "chromium");
+    assert.equal(r.log, null);
+});
+test("decideAptResolution: Ubuntu-like + non-aliased pkg + candidate-none returns pkg unchanged", () => {
+    // Branch (4) variant: Ubuntu-like host but the package isn't in the alias
+    // map. No invented mapping — fall through and let the post-check fail loudly.
+    const r = decideAptResolution({
+        pkg: "some-package-with-no-alias",
+        dpkgInstalled: false,
+        aptCandidate: "(none)",
+        ubuntuLike: true,
+        distro: "ubuntu-noble",
+    });
+    assert.equal(r.resolved, "some-package-with-no-alias");
+    assert.equal(r.log, null);
+});
+test("decideAptResolution: aptCandidate null (policy spawn failed) still allows alias resolution", () => {
+    // Edge case from Task 637: if `apt-cache policy` itself fails, we still want
+    // alias resolution on Ubuntu-like hosts. Treat null-candidate the same as
+    // candidate-none for the alias decision.
+    const r = decideAptResolution({
+        pkg: "chromium",
+        dpkgInstalled: false,
+        aptCandidate: null,
+        ubuntuLike: true,
+        distro: "ubuntu-noble",
+    });
+    assert.equal(r.resolved, "chromium-browser");
+    assert.match(r.log ?? "", /apt-resolve chromium → chromium-browser/);
+});
+// ---------------------------------------------------------------------------
+// UBUNTU_ALIASES — the alias map is the authoritative source. Locking its
+// shape so adding a new alias is a deliberate one-line PR, not a surprise.
+// ---------------------------------------------------------------------------
+test("UBUNTU_ALIASES contains chromium → chromium-browser and is the only entry", () => {
+    assert.equal(UBUNTU_ALIASES.chromium, "chromium-browser");
+    // If a future change adds another alias, this test fails loudly — the
+    // intent is "every new alias gets a deliberate test grid case", not silent
+    // expansion. Bump the count and add cases when adding a new alias.
+    assert.equal(Object.keys(UBUNTU_ALIASES).length, 1);
+});

package/dist/__tests__/brew-install.test.js

@@ -0,0 +1,141 @@
+// Task 839 — acceptance grid for brew-install.ts.
+//
+// Mirror of apt-resolve.test.ts shape: pure decision logic exercised against
+// fixture spawnSync results. The wrapper itself is a thin orchestration layer
+// over `brew list --versions <pkg>` (post-check) and `brew install <pkgs...>`
+// (install). Tests inject the spawn function so no real brew is invoked —
+// these run identically on Linux CI and Mac developer boxes.
+//
+// Branches covered:
+//   1. ensureBrewAvailable — `which brew` exits 0 → ok; non-zero → loud refusal.
+//   2. classifyBrewState — per-pkg installed/missing decision from
+//      `brew list --versions` exit codes + parsed versions.
+//   3. installAll — given a classification, decide what to feed `brew install`
+//      and what to log. Already-installed pkgs are skipped (no install line).
+//   4. verifyAll — post-install, every pkg must have at least one version token
+//      from `brew list --versions`. Partial-install case (exit 0 but pkg
+//      missing) throws with the install-still-missing diagnostic.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { ensureBrewAvailable, classifyBrewState, decideBrewInstallPlan, verifyBrewInstalled, } from "../brew-install.js";
+function ok(stdout) {
+    return { status: 0, stdout };
+}
+function fail(stdout = "") {
+    return { status: 1, stdout };
+}
+// ---------------------------------------------------------------------------
+// ensureBrewAvailable — pre-flight refusal.
+// ---------------------------------------------------------------------------
+test("ensureBrewAvailable: brew on PATH (which brew exits 0) → returns silently", () => {
+    let called = false;
+    ensureBrewAvailable((cmd, args) => {
+        called = true;
+        assert.equal(cmd, "which");
+        assert.deepEqual(args, ["brew"]);
+        return ok("/opt/homebrew/bin/brew\n");
+    });
+    assert.equal(called, true);
+});
+test("ensureBrewAvailable: brew not on PATH → throws loud refusal", () => {
+    assert.throws(() => ensureBrewAvailable(() => fail()), /Homebrew not found\. Install from https:\/\/brew\.sh and re-run\./);
+});
+// ---------------------------------------------------------------------------
+// classifyBrewState — per-pkg installed-vs-missing classification.
+// ---------------------------------------------------------------------------
+test("classifyBrewState: installed pkg with versions returns installed=true and version list", () => {
+    const r = classifyBrewState("node@22", ok("node@22 22.18.1 22.18.0\n"));
+    assert.equal(r.installed, true);
+    assert.deepEqual(r.versions, ["22.18.1", "22.18.0"]);
+});
+test("classifyBrewState: missing pkg (brew exit 1, empty stdout) returns installed=false", () => {
+    const r = classifyBrewState("neo4j", fail());
+    assert.equal(r.installed, false);
+    assert.deepEqual(r.versions, []);
+});
+test("classifyBrewState: name-only stdout (cellar half-uninstalled) treated as not-installed", () => {
+    // brew exited 0 but reported only the package name with no version tokens.
+    // Treat as uninstalled so the install pass re-runs and the post-check fails
+    // loudly if it still doesn't land — matches the apt-resolve fail-loud contract.
+    const r = classifyBrewState("node@22", ok("node@22\n"));
+    assert.equal(r.installed, false);
+    assert.deepEqual(r.versions, []);
+});
+// ---------------------------------------------------------------------------
+// decideBrewInstallPlan — given the apt-side input names + per-name installed
+// state, produce the resolved formula list to install plus per-pkg log lines.
+// ---------------------------------------------------------------------------
+test("decideBrewInstallPlan: all pkgs already installed → empty install list, only 'already installed' logs", () => {
+    const plan = decideBrewInstallPlan({
+        pkgs: [
+            { original: "nodejs", resolvedFormula: "node@22", installed: true, versions: ["22.18.1"] },
+            { original: "neo4j", resolvedFormula: "neo4j", installed: true, versions: ["5.20.0"] },
+        ],
+    });
+    assert.deepEqual(plan.toInstall, []);
+    assert.deepEqual(plan.logs, [
+        "  [homebrew] node@22 already installed (v22.18.1)",
+        "  [homebrew] neo4j already installed (v5.20.0)",
+    ]);
+});
+test("decideBrewInstallPlan: some missing → install list contains only missing formulas, install + already logs interleaved", () => {
+    const plan = decideBrewInstallPlan({
+        pkgs: [
+            { original: "nodejs", resolvedFormula: "node@22", installed: true, versions: ["22.18.1"] },
+            { original: "neo4j", resolvedFormula: "neo4j", installed: false, versions: [] },
+            { original: "cloudflared", resolvedFormula: "cloudflared", installed: false, versions: [] },
+        ],
+    });
+    assert.deepEqual(plan.toInstall, ["neo4j", "cloudflared"]);
+    assert.deepEqual(plan.logs, [
+        "  [homebrew] node@22 already installed (v22.18.1)",
+        "  [homebrew] installing neo4j …",
+        "  [homebrew] installing cloudflared …",
+    ]);
+});
+test("decideBrewInstallPlan: all missing → install list = every formula, only install logs", () => {
+    const plan = decideBrewInstallPlan({
+        pkgs: [
+            { original: "nodejs", resolvedFormula: "node@22", installed: false, versions: [] },
+            { original: "neo4j", resolvedFormula: "neo4j", installed: false, versions: [] },
+        ],
+    });
+    assert.deepEqual(plan.toInstall, ["node@22", "neo4j"]);
+    assert.deepEqual(plan.logs, [
+        "  [homebrew] installing node@22 …",
+        "  [homebrew] installing neo4j …",
+    ]);
+});
+// ---------------------------------------------------------------------------
+// verifyBrewInstalled — post-install check. Every formula must have ≥1 version
+// token from `brew list --versions`. Pure logic over an injected probe.
+// ---------------------------------------------------------------------------
+test("verifyBrewInstalled: every pkg present per brew list --versions → returns verified logs", () => {
+    const versionResults = {
+        "node@22": ok("node@22 22.18.1\n"),
+        "neo4j": ok("neo4j 5.20.0\n"),
+    };
+    const verified = verifyBrewInstalled(["node@22", "neo4j"], (pkg) => versionResults[pkg]);
+    assert.deepEqual(verified, [
+        "  [homebrew] node@22 verified post-install",
+        "  [homebrew] neo4j verified post-install",
+    ]);
+});
+test("verifyBrewInstalled: install returned 0 but pkg still missing → throws loud install-still-missing diagnostic", () => {
+    // The exact failure-mode mirror of installAptGroup — apt-get install exits 0
+    // but dpkg -s says the package isn't there. The brew analogue: brew install
+    // exits 0 but `brew list --versions` reports nothing.
+    const versionResults = {
+        "node@22": ok("node@22 22.18.1\n"),
+        "neo4j": fail(),
+    };
+    assert.throws(() => verifyBrewInstalled(["node@22", "neo4j"], (pkg) => versionResults[pkg]), /\[homebrew\] installing neo4j exited 0 but brew list --versions reports missing: neo4j/);
+});
+test("verifyBrewInstalled: multiple still-missing → all listed in diagnostic", () => {
+    const versionResults = {
+        "node@22": fail(),
+        "neo4j": ok("neo4j 5.20.0\n"),
+        "cloudflared": fail(),
+    };
+    assert.throws(() => verifyBrewInstalled(["node@22", "neo4j", "cloudflared"], (pkg) => versionResults[pkg]), /reports missing: node@22, cloudflared/);
+});

package/dist/__tests__/brew-resolve.test.js

@@ -0,0 +1,103 @@
+// Task 836 wedge — acceptance grid for brew-resolve.ts.
+//
+// Mirror of apt-resolve.test.ts: pure decision logic exercised against real
+// `brew list --versions` fixtures and the DARWIN_ALIASES seed map. Caller
+// supplies the brewInstalled boolean and the parsed package name; the resolver
+// returns the name to feed `brew install` and an optional log line for the
+// alias path. Runs identically on Linux CI and Mac developer boxes — no
+// spawnSync, no fs reads.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { DARWIN_ALIASES, parseBrewListVersions, decideBrewResolution, } from "../brew-resolve.js";
+// ---------------------------------------------------------------------------
+// Real fixtures — captured from `brew list --versions` on macOS.
+// ---------------------------------------------------------------------------
+// Multi-version line — Homebrew keeps prior versions in the cellar until
+// `brew cleanup`, so a `--versions` query against a long-lived install can
+// return more than one token after the package name. The resolver returns
+// every token; the caller decides which version is "current."
+const NODE22_MULTI_VERSION = "node@22 22.18.1 22.18.0\n";
+// Installed package, single version — the steady-state shape for a fresh install.
+const CLOUDFLARED_SINGLE_VERSION = "cloudflared 2025.1.4\n";
+// Missing package — `brew list --versions <pkg>` exits 1 with empty stdout.
+// The resolver still receives the empty string and must return [] without
+// throwing (the install caller decides whether absence is fatal).
+const MISSING_STDOUT = "";
+// Edge: only the package name with trailing newline (older Homebrew cellars
+// can produce this if a formula was uninstalled mid-sequence).
+const NAME_ONLY = "node@22\n";
+// Edge: whitespace-only stdout (caller piped a stale buffer, etc.).
+const WHITESPACE_ONLY = "   \n";
+// ---------------------------------------------------------------------------
+// parseBrewListVersions — split-and-skip-first-token semantics.
+// ---------------------------------------------------------------------------
+test("parseBrewListVersions: multi-version line returns every token after pkg name", () => {
+    assert.deepEqual(parseBrewListVersions(NODE22_MULTI_VERSION), ["22.18.1", "22.18.0"]);
+});
+test("parseBrewListVersions: single-version line returns one token", () => {
+    assert.deepEqual(parseBrewListVersions(CLOUDFLARED_SINGLE_VERSION), ["2025.1.4"]);
+});
+test("parseBrewListVersions: empty stdout (pkg missing) returns []", () => {
+    assert.deepEqual(parseBrewListVersions(MISSING_STDOUT), []);
+});
+test("parseBrewListVersions: name-only line returns []", () => {
+    assert.deepEqual(parseBrewListVersions(NAME_ONLY), []);
+});
+test("parseBrewListVersions: whitespace-only stdout returns []", () => {
+    // Trip on naïve `.split(' ')[1]` returning ''. Resolver must reject empty
+    // tokens, not return [''].
+    assert.deepEqual(parseBrewListVersions(WHITESPACE_ONLY), []);
+});
+// ---------------------------------------------------------------------------
+// decideBrewResolution — three branches.
+// ---------------------------------------------------------------------------
+test("decideBrewResolution: brew-installed pkg returns pkg, no log", () => {
+    // Branch 1: caller's brewInstalled probe came back true — name is concrete
+    // and present. Return as-is, follow-up's post-check uses the same name.
+    const r = decideBrewResolution({
+        pkg: "node@22",
+        brewInstalled: true,
+    });
+    assert.equal(r.resolved, "node@22");
+    assert.equal(r.log, null);
+});
+test("decideBrewResolution: alias-mapped pkg returns alias with log line", () => {
+    // Branch 2: pkg is in DARWIN_ALIASES — return the brew formula name and
+    // emit the diagnostic line installer logs grep on.
+    const r = decideBrewResolution({
+        pkg: "nodejs",
+        brewInstalled: false,
+    });
+    assert.equal(r.resolved, "node@22");
+    assert.match(r.log ?? "", /^  brew-resolve nodejs → node@22 \(reason=darwin-alias\)$/);
+});
+test("decideBrewResolution: unaliased pkg returns pkg unchanged, no log", () => {
+    // Branch 3: not installed AND not in alias map — return pkg unchanged.
+    // Preserves the apt-resolve.ts loud-failure contract: the install caller's
+    // post-check throws when the package genuinely doesn't exist.
+    const r = decideBrewResolution({
+        pkg: "cloudflared",
+        brewInstalled: false,
+    });
+    assert.equal(r.resolved, "cloudflared");
+    assert.equal(r.log, null);
+});
+test("decideBrewResolution: brewInstalled=true takes precedence over alias map", () => {
+    // Edge: pkg is in the alias map AND already installed under the alias name.
+    // brewInstalled=true means the post-check would already pass — return pkg
+    // unchanged so the caller doesn't double-resolve.
+    const r = decideBrewResolution({
+        pkg: "nodejs",
+        brewInstalled: true,
+    });
+    assert.equal(r.resolved, "nodejs");
+    assert.equal(r.log, null);
+});
+// ---------------------------------------------------------------------------
+// DARWIN_ALIASES — shape lock. Adding a new alias must be a deliberate edit
+// to this test grid, not a silent expansion.
+// ---------------------------------------------------------------------------
+test("DARWIN_ALIASES contains nodejs → node@22 and is the only entry", () => {
+    assert.equal(DARWIN_ALIASES.nodejs, "node@22");
+    assert.equal(Object.keys(DARWIN_ALIASES).length, 1);
+});

package/dist/__tests__/cdp-port-no-silent-fallback.test.js

@@ -0,0 +1,53 @@
+// Task 959 — structural gate against the recurrence-class
+// silent-fallback-masks-root-cause violation. The four runtime sites that
+// previously substituted `9222 + offset` for a missing brand.json.cdpPort
+// (paths.ts, admin/mcp/index.ts, vnc.sh, test-laptop-vnc-boot.sh) plus the
+// installer-side brand stamp at packages/create-maxy/src/index.ts have all
+// been swept to loud-fail. This test asserts the three greps from criterion
+// 2 of the task brief return zero matches; reintroducing any silent fallback
+// fails CI immediately.
+//
+// Compiles to dist/__tests__/cdp-port-no-silent-fallback.test.js and runs
+// via `node --test 'dist/__tests__/*.test.js'` per package.json's test
+// script. Greps run via `git grep` rooted at the repo top-level (resolved
+// relative to dist/__tests__/'s known offset) so the test is invariant to
+// the caller's cwd.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const SELF_DIR = fileURLToPath(new URL(".", import.meta.url));
+// dist/__tests__/ → repo root is four levels up
+// (packages/create-maxy/dist/__tests__ → packages/create-maxy → packages → repo).
+const REPO_ROOT = resolve(SELF_DIR, "..", "..", "..", "..");
+function grepReturns(pattern, includes) {
+    const args = ["-RnE", pattern];
+    for (const inc of includes)
+        args.push(`--include=${inc}`);
+    args.push("platform/", "packages/");
+    // Exclude this test file (it embeds the patterns as string literals,
+    // which would otherwise self-match) and exclude the gitignored payload
+    // mirror generated by `npm run bundle`.
+    args.push("--exclude-dir=payload");
+    args.push("--exclude=cdp-port-no-silent-fallback.test.*");
+    const out = spawnSync("grep", args, { cwd: REPO_ROOT, encoding: "utf8" });
+    // grep exit 1 = no matches (success for this test); exit 0 = matches found
+    // (failure); exit 2 = grep error (test infrastructure fault).
+    if (out.status !== 0 && out.status !== 1) {
+        throw new Error(`grep error (status=${out.status}): ${out.stderr}`);
+    }
+    return (out.stdout ?? "").trim();
+}
+test("Task 959 grep 1: no `9222 + offset` arithmetic in source files", () => {
+    const matches = grepReturns("9222\\s*\\+\\s*\\w*offset", ["*.ts", "*.tsx", "*.sh"]);
+    assert.equal(matches, "", `silent-fallback regression — '9222 + offset' arithmetic reintroduced:\n${matches}`);
+});
+test("Task 959 grep 2: no jq `cdpPort // 9222` fallback in shell or TS", () => {
+    const matches = grepReturns("cdpPort\\s*//\\s*9222", ["*.sh", "*.ts"]);
+    assert.equal(matches, "", `silent-fallback regression — jq cdpPort // 9222 fallback reintroduced:\n${matches}`);
+});
+test("Task 959 grep 3: no `?? 9222` or `|| 9222` nullish-coalesce in TS", () => {
+    const matches = grepReturns("\\?\\?\\s*9222|\\|\\|\\s*9222", ["*.ts"]);
+    assert.equal(matches, "", `silent-fallback regression — '?? 9222' or '|| 9222' coalesce reintroduced:\n${matches}`);
+});