@rubytech/create-maxy 1.0.792 → 1.0.794

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__/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__/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$/);
+});