@rubytech/create-maxy 1.0.792 → 1.0.793

package/dist/brew-install.js

@@ -0,0 +1,175 @@
+// Task 839 — brew-side install wrapper, peer of installAptGroup() in index.ts.
+//
+// Mirrors the apt path's install + post-check shape: classify each requested
+// package against `brew list --versions` first, install the missing subset
+// via `brew install <pkgs...>`, then re-probe `brew list --versions` per
+// formula and throw loudly if any are still missing. Pure decision functions
+// live here so a unit test can exercise every branch without spawning real
+// brew — the wrapper accepts injected spawn-result probes.
+//
+// Why split classify / decide-plan / verify into three exports instead of one
+// `installAll(pkgs)`: the call sites in index.ts need fine-grained log lines
+// (`[homebrew] <pkg> already installed (v…)` vs `[homebrew] installing <pkg> …`
+// vs `[homebrew] <pkg> verified post-install`) and the operator surface for
+// each is distinct. Keeping them as separate pure functions also lets the
+// pre-flight `which brew` refusal (ensureBrewAvailable) live alongside the
+// install/verify primitives without coupling the test grid to spawnSync.
+import { spawnSync } from "node:child_process";
+import { decideBrewResolution, parseBrewListVersions } from "./brew-resolve.js";
+// ---------------------------------------------------------------------------
+// ensureBrewAvailable — pre-flight refusal when Homebrew is absent.
+// ---------------------------------------------------------------------------
+/**
+ * Throw the loud refusal documented in the task brief when `which brew`
+ * exits non-zero. The message is grep-able and operator-actionable; no silent
+ * `curl | bash` fallback (per the task brief's "no auto-installing Homebrew"
+ * out-of-scope item).
+ */
+export function ensureBrewAvailable(spawn) {
+    const r = spawn("which", ["brew"]);
+    if (r.status !== 0) {
+        throw new Error("[create-maxy] Homebrew not found. Install from https://brew.sh and re-run.");
+    }
+}
+// ---------------------------------------------------------------------------
+// classifyBrewState — turn a `brew list --versions <pkg>` probe into the
+// installed/missing decision the install plan consumes.
+// ---------------------------------------------------------------------------
+/**
+ * Pure: given the spawn result of `brew list --versions <pkg>`, decide whether
+ * the formula is installed. A formula counts as installed only when brew
+ * exited 0 AND the parsed version list is non-empty — the half-uninstalled
+ * cellar state (exit 0 with name-only stdout) is treated as missing so the
+ * install pass re-runs and the post-check fails loudly if it still doesn't
+ * land. Mirrors apt-resolve's loud-failure contract.
+ */
+export function classifyBrewState(_pkg, result) {
+    if (result.status !== 0)
+        return { installed: false, versions: [] };
+    const versions = parseBrewListVersions(result.stdout);
+    if (versions.length === 0)
+        return { installed: false, versions: [] };
+    return { installed: true, versions };
+}
+// ---------------------------------------------------------------------------
+// decideBrewInstallPlan — pure: which formulas to install + log lines.
+// ---------------------------------------------------------------------------
+/**
+ * Pure: given each package's resolved formula name + install state, produce
+ * the install list (only missing formulas) and the per-pkg log lines. Lines
+ * are emitted in input order:
+ *   - installed=true  → `  [homebrew] <formula> already installed (v<n>)`
+ *   - installed=false → `  [homebrew] installing <formula> …`
+ * The "already installed" line uses the first version token (the cellar's
+ * current head); subsequent tokens are older retained versions per
+ * brew-resolve.ts.
+ */
+export function decideBrewInstallPlan(input) {
+    const toInstall = [];
+    const logs = [];
+    for (const p of input.pkgs) {
+        if (p.installed) {
+            const head = p.versions[0] ?? "?";
+            logs.push(`  [homebrew] ${p.resolvedFormula} already installed (v${head})`);
+        }
+        else {
+            logs.push(`  [homebrew] installing ${p.resolvedFormula} …`);
+            toInstall.push(p.resolvedFormula);
+        }
+    }
+    return { toInstall, logs };
+}
+// ---------------------------------------------------------------------------
+// verifyBrewInstalled — post-install probe + loud-failure throw.
+// ---------------------------------------------------------------------------
+/**
+ * Run `brew list --versions <formula>` (via the injected probe) for every
+ * formula and throw if any are still missing. The error message mirrors
+ * installAptGroup's "returned 0 but packages are still not installed"
+ * contract. Returns the per-formula verified-log lines on success.
+ */
+export function verifyBrewInstalled(formulas, probe) {
+    const stillMissing = [];
+    const logs = [];
+    for (const f of formulas) {
+        const r = probe(f);
+        const state = classifyBrewState(f, r);
+        if (!state.installed) {
+            stillMissing.push(f);
+            continue;
+        }
+        logs.push(`  [homebrew] ${f} verified post-install`);
+    }
+    if (stillMissing.length > 0) {
+        throw new Error(`[homebrew] installing ${stillMissing.join(", ")} exited 0 but brew list --versions reports missing: ${stillMissing.join(", ")}`);
+    }
+    return logs;
+}
+// ---------------------------------------------------------------------------
+// installAll — orchestrating wrapper used by index.ts call sites. Production
+// path only; tests exercise the pure functions above with injected spawns.
+// ---------------------------------------------------------------------------
+/**
+ * Install every requested package via Homebrew, with the same install +
+ * post-check pattern installAptGroup() uses for apt. The flow:
+ *   1. ensureBrewAvailable — refuse loud if `which brew` fails.
+ *   2. Probe `brew list --versions <original>` → classify per pkg.
+ *   3. Resolve each original via decideBrewResolution (so `nodejs` → `node@22`).
+ *   4. decideBrewInstallPlan → produces toInstall list + per-pkg log lines.
+ *   5. `brew install <toInstall>` if non-empty.
+ *   6. verifyBrewInstalled re-probes every resolved formula; throws loud if any
+ *      formula is still missing post-install.
+ * `log` is the caller's logFile sink (timestamped install log line).
+ * Returns the resolved formula names so the caller can emit additional
+ * follow-up logging (e.g. `[neo4j] bolt://localhost:<port> reachable…`).
+ */
+export function installAllBrewPackages(pkgs, log) {
+    const spawn = (cmd, args) => {
+        const r = spawnSync(cmd, args, {
+            stdio: "pipe",
+            encoding: "utf-8",
+            timeout: 600_000,
+        });
+        return { status: r.status, stdout: r.stdout ?? "" };
+    };
+    ensureBrewAvailable(spawn);
+    const probed = pkgs.map((original) => {
+        // First probe: is the original name installed (e.g. is `node@22` already there)?
+        // We probe under the resolved formula because that's the cellar key.
+        const provisional = decideBrewResolution({ pkg: original, brewInstalled: false });
+        const initialFormula = provisional.resolved;
+        const probe = spawn("brew", ["list", "--versions", initialFormula]);
+        const state = classifyBrewState(initialFormula, probe);
+        // Second resolution pass: brewInstalled=true short-circuits the alias to
+        // the original name (matches brew-resolve's contract — concrete-and-installed
+        // wins). When the cellar is empty, the alias path takes effect.
+        const decision = decideBrewResolution({ pkg: original, brewInstalled: state.installed });
+        if (decision.log)
+            log(decision.log);
+        return {
+            original,
+            resolvedFormula: state.installed ? initialFormula : decision.resolved,
+            installed: state.installed,
+            versions: state.versions,
+        };
+    });
+    const plan = decideBrewInstallPlan({ pkgs: probed });
+    for (const line of plan.logs)
+        log(line);
+    if (plan.toInstall.length > 0) {
+        const r = spawnSync("brew", ["install", ...plan.toInstall], {
+            stdio: "inherit",
+            timeout: 1_800_000,
+        });
+        if (r.status !== 0) {
+            throw new Error(`brew install ${plan.toInstall.join(" ")} exited ${r.status}`);
+        }
+    }
+    const verified = verifyBrewInstalled(probed.map((p) => p.resolvedFormula), (formula) => {
+        const r = spawnSync("brew", ["list", "--versions", formula], { stdio: "pipe", encoding: "utf-8", timeout: 30_000 });
+        return { status: r.status, stdout: r.stdout ?? "" };
+    });
+    for (const line of verified)
+        log(line);
+    return probed.map((p) => p.resolvedFormula);
+}

package/dist/brew-resolve.js

@@ -0,0 +1,68 @@
+// Task 836 wedge — pure brew-name resolution, peer of apt-resolve.ts.
+//
+// Same shape as Task 638's apt-resolve.ts: pure decision function, explicit
+// input record, explicit output record, no spawnSync, no fs reads. The
+// installer wraps this with the actual `brew list --versions` and `brew
+// install` calls in follow-up Task 839; this module only decides which name
+// to feed to those calls and which diagnostic line to log when an alias is
+// applied.
+//
+// Brew's decision space is narrower than apt's — there is no apt-cache-policy
+// analogue (Homebrew tells you `brew install` failed, never that a package
+// is virtual), so the resolver collapses to two branches: alias-hit or
+// pass-through. The brewInstalled gate short-circuits both: if the package
+// is already on disk, the name is concrete and we return it unchanged.
+// Virtual-package aliases applied when an apt-side name (used in shared
+// installer call sites) needs to map to a brew formula name. Keyed by the
+// apt name the installer passes in, valued by the brew formula name. Add
+// entries here when a new shared name surfaces — every entry gets a
+// deliberate test grid case (see brew-resolve.test.ts shape lock).
+export const DARWIN_ALIASES = {
+    // Debian/Ubuntu ship Node.js as `nodejs`; Homebrew's pinned version is
+    // `node@22` (current Maxy floor — see pinned-binaries.ts). Mapping here
+    // lets follow-up tasks pass `nodejs` from the shared dep list and have
+    // the brew backend translate transparently.
+    nodejs: "node@22",
+};
+/**
+ * Parse the stdout of `brew list --versions <pkg>` into the version tokens
+ * after the package name. Output shape:
+ *
+ *   "node@22 22.18.1 22.18.0\n"  →  ["22.18.1", "22.18.0"]
+ *   "cloudflared 2025.1.4\n"     →  ["2025.1.4"]
+ *   "node@22\n"                  →  []   (cellar empty between uninstall + cleanup)
+ *   ""                           →  []   (pkg missing — brew exited 1)
+ *   "   \n"                      →  []   (whitespace-only — never a real version)
+ *
+ * The first whitespace-separated token is always the package name and is
+ * dropped. Caller filters by version-shape if needed; this resolver returns
+ * everything after the name unfiltered.
+ */
+export function parseBrewListVersions(stdout) {
+    const tokens = stdout.trim().split(/\s+/).filter((t) => t.length > 0);
+    if (tokens.length < 2)
+        return [];
+    return tokens.slice(1);
+}
+/**
+ * Pure decision: given the brew-installed fact, decide which package name to
+ * use. Resolution order:
+ *   1. brewInstalled true → name is concrete; return pkg unchanged, no log.
+ *   2. pkg is in DARWIN_ALIASES → return the alias and emit the log line.
+ *   3. Otherwise return pkg unchanged — caller's post-check will throw,
+ *      preserving the apt-resolve.ts fail-loud contract for genuinely missing
+ *      packages.
+ */
+export function decideBrewResolution(input) {
+    const { pkg, brewInstalled } = input;
+    if (brewInstalled)
+        return { resolved: pkg, log: null };
+    if (Object.prototype.hasOwnProperty.call(DARWIN_ALIASES, pkg)) {
+        const alias = DARWIN_ALIASES[pkg];
+        return {
+            resolved: alias,
+            log: `  brew-resolve ${pkg} → ${alias} (reason=darwin-alias)`,
+        };
+    }
+    return { resolved: pkg, log: null };
+}

package/dist/index.js

@@ -6,6 +6,10 @@ import { randomBytes } from "node:crypto";
 import { resolveInstallPortFromFs, buildMaxyUnitFile } from "./port-resolution.js";
 import { parseOsRelease, isUbuntuLike as isUbuntuLikePure, parseAptCacheCandidate, decideAptResolution, } from "./apt-resolve.js";
 import { findPeerBrandOnDefaultNeo4jPort } from "./peer-brand-detect.js";
+import { requireSupportedPlatform } from "./platform-detect.js";
+import { renderPlist } from "./launchd-plist.js";
+import { installAllBrewPackages } from "./brew-install.js";
+import { parseSwVers, isSupportedMacosVersion } from "./macos-version.js";
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive all brand-specific installation values.
 // The bundler stamps brand.json into the payload at build time.
@@ -359,10 +363,70 @@ function installAptGroup(label, pkgs) {
 // Installation steps
 // ---------------------------------------------------------------------------
 const TOTAL = "11";
+/**
+ * Task 840 — set macOS hostname via scutil. Three sequential `sudo scutil
+ * --set` calls (HostName, LocalHostName, ComputerName) — `hostnamectl` is
+ * Linux-only and `--hostname <h>` silently no-ops on darwin. All-or-nothing
+ * rollback within the 3-call batch: if any call fails, we restore the
+ * pre-batch values for the keys we already changed and re-throw. Full
+ * system-state rollback (avahi, /etc/hosts) is out of scope per the brief.
+ */
+function setMacosHostnameViaScutil(hostname) {
+    const keys = ["HostName", "LocalHostName", "ComputerName"];
+    // Capture pre-batch values for rollback. Empty string is a legitimate
+    // scutil --get value (the key was never set) — preserve that as "" so
+    // rollback writes empty back rather than failing.
+    const previous = {};
+    for (const k of keys) {
+        const r = spawnSync("scutil", ["--get", k], { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
+        previous[k] = (r.stdout ?? "").trim();
+    }
+    const applied = [];
+    for (const k of keys) {
+        const r = spawnSync("sudo", ["scutil", "--set", k, hostname], { encoding: "utf-8", stdio: "inherit", timeout: 30_000 });
+        if (r.status !== 0) {
+            // Roll back any keys we already changed within this batch.
+            for (const done of applied) {
+                spawnSync("sudo", ["scutil", "--set", done, previous[done] ?? ""], { stdio: "inherit", timeout: 30_000 });
+            }
+            const stderr = r.stderr ? `: ${r.stderr.toString().trim()}` : "";
+            console.error(`  [scutil] ${k} failed${stderr}`);
+            throw new Error(`scutil --set ${k} ${hostname} exited ${r.status}`);
+        }
+        applied.push(k);
+    }
+    console.log(`  [scutil] HostName=${hostname} LocalHostName=${hostname} ComputerName=${hostname} set ok`);
+}
 function installSystemDeps() {
     log("1", TOTAL, "System dependencies and network...");
-    if (!isLinux()) {
-        console.log("  Skipping Linux-specific setup (not on Linux).");
+    const platform = requireSupportedPlatform(process.platform);
+    if (platform === "darwin") {
+        // Task 840 — darwin hostname via scutil when --hostname is supplied,
+        // otherwise preserve the existing system hostname.
+        if (HOSTNAME_FLAG) {
+            console.log(`  Hostname: ${HOSTNAME_FLAG} (from --hostname flag)`);
+            try {
+                setMacosHostnameViaScutil(HOSTNAME_FLAG);
+                DEVICE_HOSTNAME = HOSTNAME_FLAG;
+            }
+            catch (err) {
+                console.error(`  WARNING: Failed to set hostname to '${HOSTNAME_FLAG}': ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else {
+            try {
+                DEVICE_HOSTNAME = execFileSync("hostname", [], { encoding: "utf-8" }).trim();
+                console.log(`  Hostname: ${DEVICE_HOSTNAME} (preserved — no --hostname flag on darwin)`);
+            }
+            catch { /* fallback to brand — set at declaration */ }
+        }
+        // Task 839 — macOS has no apt analogue for the VNC/WiFi-AP stacks
+        // (kiosk display + hostapd/dnsmasq are Pi-specific per Task 836's
+        // out-of-scope note). mDNS is provided by the OS, so avahi-* drop out.
+        // Translate the remaining apt names through decideBrewResolution and
+        // let installAllBrewPackages handle the install + verify pattern.
+        const DARWIN_BASE_DEPS = ["curl", "git", "unzip", "jq", "poppler", "ffmpeg"];
+        installAllBrewPackages(DARWIN_BASE_DEPS, logFile);
         return;
     }
     const BASE_DEPS = ["curl", "git", "unzip", "jq", "avahi-daemon", "avahi-utils", "poppler-utils", "ffmpeg"];
@@ -594,8 +658,13 @@ function installNodejs() {
         return;
     }
     log("2", TOTAL, "Installing Node.js...");
-    if (!isLinux()) {
-        throw new Error("Automatic Node.js installation is only supported on Linux. Install Node.js 20+ manually.");
+    const platform = requireSupportedPlatform(process.platform);
+    if (platform === "darwin") {
+        // Pass the apt-side `nodejs` name; decideBrewResolution maps it to
+        // `node@22` per DARWIN_ALIASES so the cellar formula matches Maxy's
+        // pinned-binaries floor (Task 836).
+        installAllBrewPackages(["nodejs"], logFile);
+        return;
     }
     spawnSync("bash", ["-c", "curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -"], { stdio: "inherit" });
     console.log("  [privileged] apt-get install");
@@ -817,8 +886,29 @@ function installNeo4j() {
         return;
     }
     log("4", TOTAL, "Installing Neo4j Community Edition 5...");
-    if (!isLinux()) {
-        throw new Error("Automatic Neo4j installation is only supported on Linux. Install Neo4j 5.11+ manually.");
+    const platform = requireSupportedPlatform(process.platform);
+    if (platform === "darwin") {
+        // Homebrew's neo4j formula declares openjdk as a runtime dependency, so
+        // Java is pulled in transitively — no separate openjdk install step.
+        // Process supervision (launchd LaunchAgent) is owned by Task 838; this
+        // step ends after `brew install neo4j` + initial-password seeding so the
+        // payload deploy step finds the shared password file.
+        installAllBrewPackages(["neo4j"], logFile);
+        // Generate strong random password — stored in persistent location (~/{configDir}/)
+        const password = randomBytes(24).toString("base64url");
+        const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+        mkdirSync(persistDir, { recursive: true });
+        writeFileSync(join(persistDir, ".neo4j-password"), password, { mode: 0o600 });
+        const configDir = resolve(INSTALL_DIR, "platform/config");
+        mkdirSync(configDir, { recursive: true });
+        writeFileSync(join(configDir, ".neo4j-password"), password, { mode: 0o600 });
+        // Persist Neo4j data under ~/.maxy/neo4j-data/ per the task brief, so a
+        // brew uninstall (which removes the cellar) does not destroy the graph.
+        const neo4jDataDir = resolve(process.env.HOME ?? "/root", BRAND.configDir, "neo4j-data");
+        mkdirSync(neo4jDataDir, { recursive: true });
+        shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { redact: true });
+        console.log("  Neo4j installed via Homebrew. Password stored securely.");
+        return;
     }
     // Neo4j 5.x supports Java 17 and 21. Debian Bookworm ships 17, Trixie ships 21.
     // apt-cache policy shows "Candidate: (none)" when no installable version exists.
@@ -1170,8 +1260,13 @@ function installCloudflared() {
         return;
     }
     log("6", TOTAL, "Installing cloudflared...");
-    if (!isLinux()) {
-        console.log("  Skipping — install manually for your platform.");
+    const platform = requireSupportedPlatform(process.platform);
+    if (platform === "darwin") {
+        // Homebrew's `cloudflared` formula tracks the Cloudflare release stream;
+        // tunnel-login flow stays unchanged (`feedback_no_api_token_route.md`).
+        // `cloudflared service install` is invoked by the launchd supervisor in
+        // Task 838 — out of scope here.
+        installAllBrewPackages(["cloudflared"], logFile);
         return;
     }
     const arch = isArm64() ? "arm64" : "amd64";
@@ -1274,23 +1369,30 @@ function deployPayload() {
     // follow the manual recovery paragraph in .docs/deployment.md.
     // Stop the running service before wiping directories (upgrade path).
     // The server holds open files in platform/ — rmSync fails with ENOTEMPTY if it's running.
-    // systemctl stop returns when the main process exits, but ExecStopPost (e.g. VNC cleanup)
-    // may still hold file handles. Poll is-active to wait for full deactivation.
-    const svcName = BRAND.serviceName.replace(".service", "");
-    spawnSync("systemctl", ["--user", "stop", svcName], { stdio: "pipe" });
-    const MAX_STOP_WAIT = 5;
-    for (let i = 0; i < MAX_STOP_WAIT; i++) {
-        const result = spawnSync("systemctl", ["--user", "is-active", svcName], { stdio: "pipe" });
-        const status = result.stdout?.toString().trim();
-        if (status !== "active" && status !== "deactivating") {
-            console.log(`  Service stopped (${status || "not found"}).`);
-            break;
-        }
-        if (i === MAX_STOP_WAIT - 1) {
-            console.log(`  [WARN] Service still ${status} after ${MAX_STOP_WAIT}s — proceeding with directory wipe.`);
-            break;
+    // Task 838 — darwin uses `launchctl bootout` instead of systemctl; bootout
+    // returns synchronously when the agent has exited.
+    if (requireSupportedPlatform(process.platform) === "darwin") {
+        spawnSync("launchctl", ["bootout", `${gui()}/${launchdLabel()}`], { stdio: "pipe", timeout: 15_000 });
+    }
+    else {
+        // systemctl stop returns when the main process exits, but ExecStopPost (e.g. VNC cleanup)
+        // may still hold file handles. Poll is-active to wait for full deactivation.
+        const svcName = BRAND.serviceName.replace(".service", "");
+        spawnSync("systemctl", ["--user", "stop", svcName], { stdio: "pipe" });
+        const MAX_STOP_WAIT = 5;
+        for (let i = 0; i < MAX_STOP_WAIT; i++) {
+            const result = spawnSync("systemctl", ["--user", "is-active", svcName], { stdio: "pipe" });
+            const status = result.stdout?.toString().trim();
+            if (status !== "active" && status !== "deactivating") {
+                console.log(`  Service stopped (${status || "not found"}).`);
+                break;
+            }
+            if (i === MAX_STOP_WAIT - 1) {
+                console.log(`  [WARN] Service still ${status} after ${MAX_STOP_WAIT}s — proceeding with directory wipe.`);
+                break;
+            }
+            spawnSync("sleep", ["1"]);
         }
-        spawnSync("sleep", ["1"]);
     }
     // Migrate user data to {installDir}/data/ — outside the platform/ wipe zone.
     // Runs after service stop to avoid copying files while the agent is writing.
@@ -1764,11 +1866,149 @@ function installCrons() {
 // provisions the ttyd binary, writes a tmux conf, or installs a ttyd
 // systemd unit. The corresponding admin UI (RemoteTerminal, TerminalOverlay,
 // xterm.js) was deleted in the same task.
+// Task 838 — reverse-DNS LaunchAgent label. Becomes both the plist's
+// <key>Label</key> value and the file basename
+// (`~/Library/LaunchAgents/com.rubytech.<hostname>.plist`). Per-brand so
+// installing brand B never displaces brand A's agent (mirrors the per-brand
+// systemd unit invariant from Task 662).
+function launchdLabel() {
+    return `com.rubytech.${BRAND.hostname}`;
+}
+function launchAgentsDir() {
+    return resolve(process.env.HOME ?? "/", "Library/LaunchAgents");
+}
+function plistPath() {
+    return join(launchAgentsDir(), `${launchdLabel()}.plist`);
+}
+function gui() {
+    // launchd's gui domain is keyed on the user's UID. process.getuid is only
+    // defined on POSIX (always present on darwin); typed conservatively.
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    return `gui/${uid}`;
+}
+// Task 838 — darwin LaunchAgent supervisor. Mirrors the systemd-user body
+// below at the success-criteria level: process registered with the user's
+// session manager, KeepAlive respawns on crash, RunAtLoad starts the agent
+// on every login. Out-of-scope today (Task 839): brew-resolved node path,
+// dedicated Neo4j on a non-default port. Falls back to /usr/local/bin/node
+// (homebrew Intel + manual Apple-silicon installs) — Task 839 will replace
+// this with the resolver.
+function installServiceDarwin() {
+    const persistDir = resolve(process.env.HOME ?? "/", BRAND.configDir);
+    const logsDir = join(persistDir, "logs");
+    mkdirSync(logsDir, { recursive: true });
+    // Write install-time config to .env (the server reads it directly on
+    // darwin; launchd does not have systemd's EnvironmentFile primitive).
+    const envPath = join(persistDir, ".env");
+    try {
+        let envContent = "";
+        try {
+            envContent = readFileSync(envPath, "utf-8");
+        }
+        catch { /* first install */ }
+        for (const [key, value] of [
+            ["DISPLAY_MODE", DISPLAY_MODE],
+            ["EMBED_MODEL", EMBED_MODEL],
+            ["EMBED_DIMENSIONS", String(EMBED_DIMS)],
+            ["NEO4J_URI", `bolt://localhost:${NEO4J_PORT}`],
+            ["PORT", String(PORT)],
+            ["MAXY_PLATFORM_ROOT", `${INSTALL_DIR}/platform`],
+        ]) {
+            const re = new RegExp(`^${key}=.*$`, "m");
+            if (re.test(envContent)) {
+                envContent = envContent.replace(re, `${key}=${value}`);
+            }
+            else {
+                envContent = envContent.trimEnd() + (envContent.length > 0 ? "\n" : "") + `${key}=${value}\n`;
+            }
+        }
+        writeFileSync(envPath, envContent);
+        logFile(`  .env: DISPLAY_MODE=${DISPLAY_MODE}, EMBED_MODEL=${EMBED_MODEL}, EMBED_DIMENSIONS=${EMBED_DIMS}, NEO4J_URI=bolt://localhost:${NEO4J_PORT}, PORT=${PORT}`);
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to write .env to ${envPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Render the plist. The wrapper shell script reads .env before exec'ing
+    // node so the runtime config (PORT, MAXY_PLATFORM_ROOT, NEO4J_URI) lands
+    // in the child env. Without this, ProgramArguments executes node directly
+    // and the .env values are unread — server binds the wrong port.
+    const wrapperPath = join(persistDir, "launchd-wrapper.sh");
+    // Resolve node binary at install time so the wrapper picks the right
+    // path on both Intel (/usr/local/bin/node) and Apple Silicon
+    // (/opt/homebrew/bin/node) — Homebrew's prefix differs by arch.
+    const nodeProbe = spawnSync("command", ["-v", "node"], { encoding: "utf-8", shell: true });
+    const nodeBin = (nodeProbe.stdout ?? "").trim() || "/usr/local/bin/node";
+    const wrapperBody = [
+        "#!/bin/bash",
+        "# Task 838 — generated by create-maxy installService(). Reads .env then",
+        "# execs node so launchd's child inherits PORT, NEO4J_URI, etc. Replaces",
+        "# the systemd EnvironmentFile= directive that has no launchd analogue.",
+        `set -a; [ -f "${envPath}" ] && . "${envPath}"; set +a`,
+        `cd "${INSTALL_DIR}/server"`,
+        `exec ${nodeBin} --require ./server-init.cjs server.js`,
+        "",
+    ].join("\n");
+    writeFileSync(wrapperPath, wrapperBody);
+    chmodSync(wrapperPath, 0o755);
+    const label = launchdLabel();
+    const plist = renderPlist({
+        label,
+        programArguments: ["/bin/bash", wrapperPath],
+        stdoutPath: join(logsDir, "server.log"),
+        stderrPath: join(logsDir, "server.log"),
+        keepAlive: true,
+        runAtLoad: true,
+        workingDirectory: `${INSTALL_DIR}/server`,
+    });
+    mkdirSync(launchAgentsDir(), { recursive: true });
+    const path = plistPath();
+    writeFileSync(path, plist);
+    logFile(`  ${path} written (${plist.length} bytes)`);
+    // Idempotent re-install: bootout the previous instance (if any) first so
+    // the second `bootstrap` does not exit 5 ("already loaded"). Best-effort —
+    // a missing service is the expected case on fresh installs.
+    spawnSync("launchctl", ["bootout", `${gui()}/${label}`], { stdio: "pipe" });
+    const bootstrap = spawnSync("launchctl", ["bootstrap", gui(), path], {
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: 15_000,
+    });
+    if (bootstrap.status === 0) {
+        console.log(`  [launchd] bootstrap ${gui()}/${label} ok`);
+        logFile(`  [launchd] bootstrap ${gui()}/${label} ok`);
+    }
+    else {
+        const stderr = (bootstrap.stderr ?? "").trim();
+        console.error(`  [launchd] bootstrap returned ${bootstrap.status}: ${stderr}`);
+        logFile(`  [launchd] bootstrap returned ${bootstrap.status}: ${stderr}`);
+        throw new Error(`launchctl bootstrap ${gui()} ${path} failed (exit ${bootstrap.status}): ${stderr}`);
+    }
+    // Wait for the server to come up.
+    console.log("  Waiting for web server...");
+    let webServerUp = false;
+    for (let i = 0; i < 20; i++) {
+        try {
+            execFileSync("curl", ["-sf", `http://localhost:${PORT}`, "-o", "/dev/null"], { timeout: 3000 });
+            webServerUp = true;
+            break;
+        }
+        catch {
+            spawnSync("sleep", ["2"]);
+        }
+    }
+    if (!webServerUp) {
+        console.log(`  Server may still be starting. Check http://localhost:${PORT} in a moment.`);
+    }
+}
 function installService() {
     log("11", TOTAL, `Starting ${BRAND.productName}...`);
-    if (!isLinux()) {
-        console.log("  Skipping systemd service (not Linux). Start manually with:");
-        console.log(`  cd ${INSTALL_DIR}/server && MAXY_PLATFORM_ROOT=${INSTALL_DIR}/platform PORT=${PORT} HOSTNAME=0.0.0.0 KEEP_ALIVE_TIMEOUT=61000 node --require ./server-init.cjs server.js`);
+    // Task 838 — branch on the Task 836 ternary instead of the legacy
+    // `isLinux()` boolean. Linux falls through to the systemd-user body
+    // below; darwin renders + bootstraps a LaunchAgent and returns;
+    // unsupported throws the literal refusal at requireSupportedPlatform.
+    const platform = requireSupportedPlatform(process.platform);
+    if (platform === "darwin") {
+        installServiceDarwin();
         return;
     }
     // Persist UDP buffer sizes for cloudflared QUIC stability (applied on every boot via sysctl.d)
@@ -2287,7 +2527,45 @@ const NEO4J_DEDICATED = NEO4J_PORT !== DEFAULT_NEO4J_PORT;
 // invocation. No TCP listener on the device needs to be reserved for an
 // interactive-shell surface any more.
 const PKG_VERSION = JSON.parse(readFileSync(resolve(import.meta.dirname, "../package.json"), "utf-8")).version;
+// ---------------------------------------------------------------------------
+// Task 840 — pre-flight platform refusal.
+//
+// Runs BEFORE initLogging() (LOG_DIR creation), port resolution, and any
+// brew/scutil/hostnamectl probe. Only Linux + darwin are supported (Task 836);
+// on darwin, macOS major must be ≥ 14 (the floor required by Tasks 838/839).
+// Older macOS partially succeeds, then breaks at the supervisor or brew-cellar
+// layer with cryptic errors — refusing loudly here is the contract.
+//
+// Platform-header line is emitted on every install start so operators can grep
+// `[create-maxy] platform=` to confirm pre-flight ran. On darwin the line also
+// carries `macos=<v>` (Task 840 token) so the macOS-14 floor check is visible.
+// ---------------------------------------------------------------------------
+const PLATFORM = requireSupportedPlatform(process.platform);
+let MACOS_VERSION = null;
+if (PLATFORM === "darwin") {
+    const swVers = spawnSync("sw_vers", [], { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
+    const parsed = parseSwVers(swVers.stdout ?? "");
+    if (!parsed) {
+        const head = (swVers.stdout ?? "").split("\n").slice(0, 2).join(" | ");
+        console.error(`[create-maxy] sw_vers stdout malformed: ${head}`);
+        console.error(`[create-maxy] platform=darwin macos=<unknown> — refusing: macOS 14+ required`);
+        process.exit(1);
+    }
+    MACOS_VERSION = parsed.version;
+    if (!isSupportedMacosVersion(MACOS_VERSION)) {
+        console.error(`[create-maxy] platform=darwin macos=${MACOS_VERSION} — refusing: macOS 14+ required`);
+        process.exit(1);
+    }
+}
+// Platform-header — first log line. Operators grep `[create-maxy] platform=`
+// to confirm pre-flight ran. The /* macos=<v> */ token is the Task 840 marker;
+// keep it on this same line so 3-way merges with parallel installer edits stay
+// mechanical (no rewrap, no split into two log lines).
+const PLATFORM_HEADER = `[create-maxy] platform=${PLATFORM} arch=${process.arch}` +
+    (MACOS_VERSION ? ` macos=${MACOS_VERSION}` : ``) +
+    ` version=${PKG_VERSION}`;
 initLogging();
+console.log(PLATFORM_HEADER);
 console.log("================================================================");
 console.log(`  ${BRAND.productName} — ${BRAND.tagline}.  (${BRAND.hostname} v${PKG_VERSION})`);
 console.log("================================================================");