arelos 0.1.1 → 0.2.0

package/dist/install.js

@@ -1,37 +1,30 @@
 /**
- * Interactive + non-interactive install flow (rlo-cli-spec.md §1).
- * Steps are numbered in comments to match the spec exactly.
+ * Interactive + non-interactive install flow. 0.2.0 owner-directed redesign:
+ * one required question (name), an optional location override (default: your
+ * home directory), silent auto-picked ports, then a summary + confirm. Every
+ * install is self-contained under `<parent>/<slug>` — see install-plan.ts.
  */
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import { join } from "node:path";
 import { ensureBun } from "./bun-setup.js";
-import { readConfig, writeConfig } from "./config.js";
+import { readConfigAt, writeConfig } from "./config.js";
 import { runStreaming } from "./exec.js";
-import { waitForHealthy } from "./health.js";
-import { checkInstallDir, defaultVaultPath, DEFAULTS, normalizeDisplayName, resolvePort, toArelConfig, } from "./install-plan.js";
+import { formatHealthTimeoutDiagnostics, waitForHealthy } from "./health.js";
+import { lastLines, logPathFor } from "./logs.js";
+import { appDirFor, checkRootDir, DEFAULTS, defaultParentDir, normalizeDisplayName, resolvePort, rootFor, slugOrFallback, TCC_PROTECTED_PATH_MESSAGE, toArelConfig, vaultPathFor, } from "./install-plan.js";
 import { bootstrapAndStart, installServiceFiles } from "./services.js";
 import { cloneRepo, isGitCheckout } from "./repo.js";
 import { ensureEnvFile, ensureLogsDir, scaffoldVault, TemplateVaultMissingError } from "./scaffold.js";
 import { runRepairMenu } from "./repair.js";
-import { configPath, deriveServiceLabels } from "./paths.js";
+import { installConfigPath, isTccProtectedPath } from "./paths.js";
 import { listLoadedArelosLabels } from "./launchd.js";
+import { addRegistryEntry } from "./registry.js";
 export async function runInstall(argv, flags) {
     // Step 0 — Preflight & existing-install detection.
     if (process.platform !== "darwin") {
         console.error("Arel OS currently supports macOS only.");
         return 1;
     }
-    const existing = readConfig();
-    if (existing && !flags.yes) {
-        return runRepairMenu(existing);
-    }
-    if (existing && flags.yes) {
-        // Non-interactive re-run against an existing install: treat as repair to
-        // stay consistent with "never silently reinstall" (spec §3.1), unless the
-        // caller explicitly pointed at a fresh installDir/config.
-        console.log(pc.yellow(`Existing install detected at ${existing.installDir}; repairing.`));
-    }
     const gitOk = flags.localRepo ? true : await checkGit();
     if (!gitOk)
         return 1;
@@ -44,11 +37,26 @@ export async function runInstall(argv, flags) {
         p.cancel("Install cancelled.");
         return 1;
     }
+    // A prior install of the *same name* (same resolved root, already a git
+    // checkout at root/app) is a repair, not a fresh install — never silently
+    // reinstall over it.
+    const rootCheck = checkRootDir(answers.root);
+    if (rootCheck.isPriorArelosInstall) {
+        const existingConfig = readConfigAt(answers.root);
+        if (existingConfig) {
+            if (!flags.yes) {
+                return runRepairMenu(existingConfig);
+            }
+            console.log(pc.yellow(`Existing install detected at ${answers.root}; repairing.`));
+        }
+    }
     if (!flags.yes) {
         p.note([
             `Name:        ${answers.displayName}`,
-            `Install dir: ${answers.installDir}`,
-            `Vault path:  ${answers.vaultPath}`,
+            `Location:    ${answers.root}`,
+            `  app:       ${answers.installDir}`,
+            `  vault:     ${answers.vaultPath}`,
+            `  logs:      ${answers.root}/logs/service`,
             `Web port:    ${answers.webPort}`,
             `Vault port:  ${answers.vaultPort}`,
         ].join("\n"), "Summary");
@@ -68,7 +76,7 @@ export async function runInstall(argv, flags) {
         return 1;
     }
     bunSpin.stop(`Bun ready (${bunResult.bunBin}).`);
-    // Step 8 — Get the app source.
+    // Step 8 — Get the app source into root/app.
     const installDir = answers.installDir;
     if (isGitCheckout(installDir)) {
         log(flags.yes, `Existing checkout found at ${installDir}; skipping clone.`);
@@ -114,13 +122,21 @@ export async function runInstall(argv, flags) {
         }
         throw err;
     }
-    ensureLogsDir(installDir);
+    // Logs live at the self-contained root, not inside the app checkout.
+    ensureLogsDir(answers.root);
     const envResult = ensureEnvFile(installDir);
     log(flags.yes, envResult.created ? "Wrote .env from .env.example." : ".env already present; left untouched.");
-    // Step 10 — Write config.
+    // Step 10 — Write per-install config to <root>/config.json + register.
     const config = toArelConfig(answers);
-    writeConfig(config);
-    log(flags.yes, `Config written to ${configPath()}.`);
+    const cfgPath = installConfigPath(config.root);
+    writeConfig(config, cfgPath);
+    log(flags.yes, `Config written to ${cfgPath}.`);
+    addRegistryEntry({
+        name: answers.displayName,
+        slug: slugOrFallback(answers.displayName),
+        root: config.root,
+        createdAt: new Date().toISOString(),
+    });
     if (flags.noService) {
         log(flags.yes, "Skipping launchd bootstrap (--no-service).");
         p.outro(pc.green("Dry-run install complete (no services started)."));
@@ -128,12 +144,12 @@ export async function runInstall(argv, flags) {
     }
     // Step 10.5 — Preflight: check for a same-slug reinstall vs. an unrelated
     // Arel OS install already holding other com.arelos.* labels.
-    const labels = config.serviceLabels ?? deriveServiceLabels(installDir);
+    const labels = config.serviceLabels;
     const loadedLabels = await listLoadedArelosLabels();
     const oursAlreadyLoaded = loadedLabels.filter((l) => l === labels.web || l === labels.vault);
     const othersLoaded = loadedLabels.filter((l) => l !== labels.web && l !== labels.vault);
     if (oursAlreadyLoaded.length > 0) {
-        log(flags.yes, `Services for this install dir are already loaded (${oursAlreadyLoaded.join(", ")}) — will bootout and re-bootstrap.`);
+        log(flags.yes, `Services for this install are already loaded (${oursAlreadyLoaded.join(", ")}) — will bootout and re-bootstrap.`);
     }
     if (othersLoaded.length > 0) {
         console.error(pc.yellow(`Another Arel OS install is already running with its own services (${othersLoaded.join(", ")}). ` +
@@ -142,7 +158,7 @@ export async function runInstall(argv, flags) {
     // Step 11 — Generate + bootstrap launchd services.
     const svcSpin = spinner(flags.yes);
     svcSpin.start("Registering background services…");
-    installServiceFiles(installDir, labels);
+    installServiceFiles(installDir, config.root, labels);
     const bootstrapResult = await bootstrapAndStart(labels);
     if (bootstrapResult.errors.length > 0) {
         svcSpin.stop("Service registration had errors.");
@@ -158,7 +174,8 @@ export async function runInstall(argv, flags) {
     const health = await waitForHealthy(config.webPort, config.vaultPort);
     if (!health.healthy) {
         healthSpin.stop("Health check timed out.");
-        console.error(pc.red(`App did not come up in time. Check logs:\n  arelos logs\n  ${join(installDir, "logs/service/web.log")}\n  ${join(installDir, "logs/service/vault.log")}`));
+        console.error(pc.red(formatHealthTimeoutDiagnostics(config.root, (p) => lastLines(p, 10), logPathFor)));
+        console.error(pc.dim("\nFull logs: arelos logs"));
         return 1;
     }
     healthSpin.stop("App is up.");
@@ -173,7 +190,7 @@ export async function runInstall(argv, flags) {
         }
     }
     p.outro([
-        pc.green(`Arel OS is running at ${url}`),
+        pc.green(`${answers.displayName} is running at ${url}`),
         "Runs 24/7 in the background.",
         "Next: arelos status · arelos logs · arelos update · arelos uninstall",
     ].join("\n"));
@@ -189,21 +206,32 @@ async function checkGit() {
 async function collectAnswers(flags) {
     if (flags.yes) {
         const displayName = normalizeDisplayName(flags.displayName ?? DEFAULTS.displayName);
-        const installDir = flags.installDir ?? DEFAULTS.installDir;
-        const vaultPath = flags.vaultPath ?? defaultVaultPath(installDir);
+        const root = flags.root ?? rootFor(flags.parentDir ?? defaultParentDir(), displayName);
+        if (isTccProtectedPath(root)) {
+            console.error(pc.red(`Install location ${root} is not safe to use: ${TCC_PROTECTED_PATH_MESSAGE}`));
+            return null;
+        }
+        const check = checkRootDir(root);
+        if (check.nonEmpty && !check.isPriorArelosInstall) {
+            console.error(pc.red(`${check.path} already has files in it and isn't a prior Arel OS install — choose a different name or location.`));
+            return null;
+        }
+        const installDir = appDirFor(root);
+        const vaultPath = vaultPathFor(root);
         const webPortReq = flags.webPort ?? DEFAULTS.webPort;
         const vaultPortReq = flags.vaultPort ?? DEFAULTS.vaultPort;
         const web = await resolvePort(webPortReq);
         const vault = await resolvePort(vaultPortReq === web.resolved ? vaultPortReq + 1 : vaultPortReq);
         return {
             displayName,
+            root,
             installDir,
             vaultPath,
             webPort: web.resolved,
             vaultPort: vault.resolved,
         };
     }
-    // Step 2 — Name your system.
+    // Step 2 — Name your system (the single required question).
     const displayNameRaw = await p.text({
         message: "What should we call your system?",
         placeholder: DEFAULTS.displayName,
@@ -211,84 +239,116 @@ async function collectAnswers(flags) {
     });
     if (p.isCancel(displayNameRaw))
         return null;
-    // Step 3 — Install location.
-    let installDir = "";
-    for (;;) {
+    const displayName = normalizeDisplayName(String(displayNameRaw));
+    const slug = slugOrFallback(displayName);
+    p.log.message(`We'll create everything in ~/${slug} — the app, your vault, and logs all live inside this one folder.`);
+    // Step 3 — Change location? (default No — we always create <parent>/<slug>, never install loose.)
+    let parentDir = defaultParentDir();
+    const changeLocation = await p.confirm({ message: "Change location?", initialValue: false });
+    if (p.isCancel(changeLocation))
+        return null;
+    if (changeLocation) {
         const raw = await p.text({
-            message: "Where should Arel OS be installed?",
-            placeholder: DEFAULTS.installDir,
-            defaultValue: DEFAULTS.installDir,
+            message: "Parent folder to install into (we'll create the app's folder inside it):",
+            placeholder: defaultParentDir(),
+            defaultValue: defaultParentDir(),
         });
         if (p.isCancel(raw))
             return null;
-        const check = checkInstallDir(String(raw || DEFAULTS.installDir));
+        parentDir = String(raw || defaultParentDir());
+    }
+    let root = "";
+    for (;;) {
+        const candidateRoot = rootFor(parentDir, displayName);
+        const check = checkRootDir(candidateRoot);
+        if (check.isTccProtected) {
+            p.log.error(`${TCC_PROTECTED_PATH_MESSAGE} (suggested: ${rootFor(defaultParentDir(), displayName)})`);
+            const raw = await p.text({
+                message: "Parent folder to install into:",
+                placeholder: defaultParentDir(),
+                defaultValue: defaultParentDir(),
+            });
+            if (p.isCancel(raw))
+                return null;
+            parentDir = String(raw || defaultParentDir());
+            continue;
+        }
         if (!check.parentWritable) {
             p.log.error(`Cannot write to ${check.path} — choose another location.`);
+            const raw = await p.text({ message: "Parent folder to install into:" });
+            if (p.isCancel(raw))
+                return null;
+            parentDir = String(raw);
             continue;
         }
         if (check.nonEmpty && !check.isPriorArelosInstall) {
-            const proceed = await p.confirm({
-                message: `${check.path} exists and is not empty. Use it anyway?`,
-                initialValue: false,
+            const choice = await p.select({
+                message: `${check.path} already has files in it and isn't a prior install named "${displayName}".`,
+                options: [
+                    { value: "name", label: "Choose a different name" },
+                    { value: "location", label: "Choose a different location" },
+                    { value: "cancel", label: "Cancel install" },
+                ],
             });
-            if (p.isCancel(proceed) || !proceed)
+            if (p.isCancel(choice) || choice === "cancel")
+                return null;
+            if (choice === "location") {
+                const raw = await p.text({ message: "Parent folder to install into:" });
+                if (p.isCancel(raw))
+                    return null;
+                parentDir = String(raw);
                 continue;
+            }
+            // choice === "name": re-ask for a name, keep the same parentDir.
+            const nameRaw = await p.text({
+                message: "What should we call your system?",
+                placeholder: DEFAULTS.displayName,
+                defaultValue: DEFAULTS.displayName,
+            });
+            if (p.isCancel(nameRaw))
+                return null;
+            return collectAnswersFromName(normalizeDisplayName(String(nameRaw)), parentDir);
         }
-        installDir = check.path;
+        root = check.path;
         break;
     }
-    // Step 4 — Vault location.
-    const vaultRaw = await p.text({
-        message: "Where's your vault (notes/tasks/quests)?",
-        placeholder: defaultVaultPath(installDir),
-        defaultValue: defaultVaultPath(installDir),
-    });
-    if (p.isCancel(vaultRaw))
-        return null;
-    // Step 5 — Ports.
-    const webPort = await promptPort("Web port?", DEFAULTS.webPort);
-    if (webPort === null)
-        return null;
-    const vaultPort = await promptPort("Vault port?", DEFAULTS.vaultPort === webPort ? DEFAULTS.vaultPort + 1 : DEFAULTS.vaultPort);
-    if (vaultPort === null)
-        return null;
-    return {
-        displayName: normalizeDisplayName(String(displayNameRaw)),
-        installDir,
-        vaultPath: String(vaultRaw || defaultVaultPath(installDir)),
-        webPort,
-        vaultPort,
-    };
+    return finalizeAnswers(displayName, root);
 }
-async function promptPort(message, defaultPort) {
-    let candidate = defaultPort;
+/** Re-entry point when the user picks "choose a different name" mid-flow (avoids re-asking location). */
+async function collectAnswersFromName(displayName, parentDir) {
     for (;;) {
-        const resolution = await resolvePort(candidate);
-        let suggested = resolution.resolved;
-        if (!resolution.wasFree) {
-            p.log.warn(`Port ${resolution.requested} is in use — suggesting ${suggested}.`);
-        }
-        const raw = await p.text({
-            message,
-            placeholder: String(suggested),
-            defaultValue: String(suggested),
-        });
-        if (p.isCancel(raw))
+        const candidateRoot = rootFor(parentDir, displayName);
+        const check = checkRootDir(candidateRoot);
+        if (check.isTccProtected) {
+            p.log.error(TCC_PROTECTED_PATH_MESSAGE);
             return null;
-        const parsed = Number(raw || suggested);
-        if (!Number.isInteger(parsed) || parsed <= 1023) {
-            p.log.error("Enter a valid port number above 1023.");
-            candidate = suggested;
-            continue;
         }
-        const check = await resolvePort(parsed);
-        if (!check.wasFree) {
-            candidate = check.resolved;
+        if (check.nonEmpty && !check.isPriorArelosInstall) {
+            p.log.error(`${check.path} also already has files in it — try a different name.`);
+            const nameRaw = await p.text({ message: "What should we call your system?" });
+            if (p.isCancel(nameRaw))
+                return null;
+            displayName = normalizeDisplayName(String(nameRaw));
             continue;
         }
-        return parsed;
+        return finalizeAnswers(displayName, check.path);
     }
 }
+/** Auto-pick free ports silently and assemble the final InstallAnswers. */
+async function finalizeAnswers(displayName, root) {
+    const installDir = appDirFor(root);
+    const vaultPath = vaultPathFor(root);
+    const web = await resolvePort(DEFAULTS.webPort);
+    const vault = await resolvePort(DEFAULTS.vaultPort === web.resolved ? DEFAULTS.vaultPort + 1 : DEFAULTS.vaultPort);
+    return {
+        displayName,
+        root,
+        installDir,
+        vaultPath,
+        webPort: web.resolved,
+        vaultPort: vault.resolved,
+    };
+}
 function spinner(quiet) {
     if (quiet) {
         return {

package/dist/list.js

@@ -0,0 +1,57 @@
+/**
+ * `arelos list`. Table of every registered install (name, root, ports, service
+ * status) — the multi-install discovery surface (0.2.0).
+ */
+import pc from "picocolors";
+import { readConfig, readConfigAt, resolveServiceLabels } from "./config.js";
+import { getServiceStatus } from "./launchd.js";
+import { readRegistry } from "./registry.js";
+import { existsSync } from "node:fs";
+import { legacyConfigPath } from "./paths.js";
+export async function listCommand() {
+    const entries = readRegistry();
+    const rows = [];
+    for (const entry of entries) {
+        const config = readConfigAt(entry.root);
+        if (!config) {
+            rows.push({ name: entry.name, root: entry.root, webPort: "?", vaultPort: "?", status: pc.red("config missing") });
+            continue;
+        }
+        const labels = resolveServiceLabels(config);
+        const [webSvc, vaultSvc] = await Promise.all([getServiceStatus(labels.web), getServiceStatus(labels.vault)]);
+        const status = webSvc.loaded && vaultSvc.loaded ? pc.green("running") : pc.yellow("stopped");
+        rows.push({
+            name: entry.name,
+            root: entry.root,
+            webPort: String(config.webPort),
+            vaultPort: String(config.vaultPort),
+            status,
+        });
+    }
+    if (existsSync(legacyConfigPath())) {
+        const legacy = readConfig();
+        if (legacy) {
+            const labels = resolveServiceLabels(legacy);
+            const [webSvc, vaultSvc] = await Promise.all([getServiceStatus(labels.web), getServiceStatus(labels.vault)]);
+            const status = webSvc.loaded && vaultSvc.loaded ? pc.green("running") : pc.yellow("stopped");
+            rows.push({
+                name: "(unnamed — legacy install)",
+                root: legacy.installDir,
+                webPort: String(legacy.webPort),
+                vaultPort: String(legacy.vaultPort),
+                status,
+            });
+        }
+    }
+    if (rows.length === 0) {
+        console.log("No Arel OS installs found. Run `npx arelos` to install.");
+        return 0;
+    }
+    const nameWidth = Math.max(4, ...rows.map((r) => r.name.length));
+    const rootWidth = Math.max(4, ...rows.map((r) => r.root.length));
+    console.log(`${"NAME".padEnd(nameWidth)}  ${"ROOT".padEnd(rootWidth)}  WEB    VAULT  STATUS`);
+    for (const row of rows) {
+        console.log(`${row.name.padEnd(nameWidth)}  ${row.root.padEnd(rootWidth)}  ${row.webPort.padEnd(5)}  ${row.vaultPort.padEnd(5)}  ${row.status}`);
+    }
+    return 0;
+}

package/dist/logs.js

@@ -1,12 +1,16 @@
 /**
- * `rlo logs` (spec §2). Tails <installDir>/logs/service/{web,vault}.log.
+ * `arelos logs`. Tails <root>/logs/service/{web,vault}.log (0.2.0 self-contained
+ * layout — logs live at the install root, not inside the app checkout).
+ * Legacy (pre-0.2.0) installs have no `root`; their logs live under
+ * installDir directly, matching the layout their plists were rendered with.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
-import { readConfig } from "./config.js";
-export function logPathFor(installDir, which) {
-    return join(installDir, "logs", "service", `${which}.log`);
+import { resolveInstall } from "./cli-context.js";
+import { resolveRoot } from "./config.js";
+export function logPathFor(root, which) {
+    return join(root, "logs", "service", `${which}.log`);
 }
 export function lastLines(filePath, n) {
     if (!existsSync(filePath))
@@ -15,14 +19,15 @@ export function lastLines(filePath, n) {
     const lines = content.split("\n");
     return lines.slice(Math.max(0, lines.length - n - 1)).join("\n");
 }
-export async function logsCommand(flags) {
-    const config = readConfig();
-    if (!config) {
-        console.error("No Arel OS install found. Run `npx arelos` to install.");
+export async function logsCommand(flags, name) {
+    const result = await resolveInstall({ name, interactive: process.stdout.isTTY === true });
+    if (!result.ok) {
+        console.error(result.message);
         return 1;
     }
+    const config = result.install.config;
     const targets = flags.which === "both" ? ["web", "vault"] : [flags.which];
-    const paths = targets.map((t) => logPathFor(config.installDir, t));
+    const paths = targets.map((t) => logPathFor(resolveRoot(config), t));
     if (flags.follow) {
         const existing = paths.filter((p) => existsSync(p));
         if (existing.length === 0) {

package/dist/paths.js

@@ -1,16 +1,42 @@
 /**
- * Central place for the fixed, well-known paths `rlo` reads/writes.
- * Everything here honors ARELOS_CONFIG_PATH so tests/dry-runs never touch
- * the real ~/.arelos.
+ * Central place for the fixed, well-known paths `arelos` reads/writes.
+ * Everything here honors ARELOS_CONFIG_PATH / ARELOS_REGISTRY_PATH so
+ * tests/dry-runs never touch the real ~/.arelos.
  */
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
-export function configPath() {
-    return process.env.ARELOS_CONFIG_PATH ?? join(homedir(), ".arelos", "config.json");
+/**
+ * Per-install config now lives at <root>/config.json (0.2.0 self-contained
+ * layout). ARELOS_CONFIG_PATH remains the escape hatch for tests/dry-runs and
+ * for pointing a command at a specific install's config directly. There is no
+ * single well-known default anymore — callers that need "the" config either
+ * have a root in hand (installConfigPath(root)) or go through the registry.
+ */
+export function installConfigPath(root) {
+    return join(root, "config.json");
+}
+/**
+ * Pre-0.2.0 fixed config location. Still read as a fallback "unnamed install"
+ * so 0.1.x installs remain manageable after upgrading the CLI.
+ */
+export function legacyConfigPath() {
+    return join(homedir(), ".arelos", "config.json");
+}
+/** Explicit override honored everywhere a single config path is needed directly. */
+export function configPathOverride() {
+    return process.env.ARELOS_CONFIG_PATH ?? null;
 }
 export function configDir() {
-    return join(configPath(), "..");
+    return join(homedir(), ".arelos");
+}
+/**
+ * Global multi-install registry: ~/.arelos/installs.json, listing every named
+ * install on this Mac ({name, slug, root, createdAt}). ARELOS_REGISTRY_PATH
+ * overrides the location for tests so they never touch the real file.
+ */
+export function registryPath() {
+    return process.env.ARELOS_REGISTRY_PATH ?? join(homedir(), ".arelos", "installs.json");
 }
 export function launchAgentsDir() {
     return join(homedir(), "Library", "LaunchAgents");
@@ -50,3 +76,49 @@ export function expandHome(p) {
         return join(homedir(), p.slice(2));
     return p;
 }
+/**
+ * Folders macOS TCC privacy protection blocks background (launchd-spawned)
+ * processes from accessing without an interactive grant: Desktop, Documents,
+ * Downloads, and iCloud Drive (~/Library/Mobile Documents). A service that
+ * installs into one of these will register fine but crash-loop forever on
+ * start with `Operation not permitted` (field bug: exit 126). Checked against
+ * the *resolved* (home-expanded) path so `~/Desktop/foo` and
+ * `/Users/x/Desktop/foo` are both caught.
+ */
+const TCC_PROTECTED_SUFFIXES = ["Desktop", "Documents", "Downloads", "Library/Mobile Documents"];
+/**
+ * True if `rawPath` resolves to inside (or exactly at) one of the TCC-protected
+ * directories under `home`. Pure string/path logic — no filesystem access —
+ * so it can be unit tested without touching disk.
+ *
+ * - Exact home root (`~`) is safe.
+ * - Sibling names that merely start with the same string (e.g. `~/Desktopx`)
+ *   are safe — matched by path segment, not string prefix.
+ * - Nested arbitrarily deep paths inside a protected dir are caught.
+ * - Case-insensitive, matching macOS's default case-insensitive APFS/HFS+.
+ */
+export function isTccProtectedPath(rawPath, home = homedir()) {
+    const resolved = expandHomeWith(rawPath, home);
+    const normalizedHome = normalizeForCompare(home);
+    const normalizedResolved = normalizeForCompare(resolved);
+    for (const suffix of TCC_PROTECTED_SUFFIXES) {
+        const protectedDir = normalizeForCompare(join(normalizedHome, suffix));
+        if (normalizedResolved === protectedDir || normalizedResolved.startsWith(`${protectedDir}/`)) {
+            return true;
+        }
+    }
+    return false;
+}
+function expandHomeWith(p, home) {
+    if (p === "~")
+        return home;
+    if (p.startsWith("~/"))
+        return join(home, p.slice(2));
+    return p;
+}
+function normalizeForCompare(p) {
+    // Collapse any trailing slash and lowercase for macOS's default
+    // case-insensitive filesystem semantics.
+    const withoutTrailingSlash = p.length > 1 && p.endsWith("/") ? p.slice(0, -1) : p;
+    return withoutTrailingSlash.toLowerCase();
+}

package/dist/plist.js

@@ -1,12 +1,24 @@
 /**
- * Plist template rendering (portability-contract.md §3.1). Templates ship at
- * `scripts/service/{web,vault}.plist.tmpl` in the app repo and take two
- * tokens — {{INSTALL_DIR}} and {{LABEL}} (the per-install launchd label from
- * paths.ts deriveServiceLabels). Ports/vaultPath are read from config at
- * process start by the run-*.sh scripts / server, never baked into the plist.
+ * Plist template rendering. Templates ship at
+ * `scripts/service/{web,vault}.plist.tmpl` in the app repo and take three
+ * tokens:
+ *   - {{INSTALL_DIR}} — the app checkout (root/app): where run-*.sh lives and
+ *     the job's WorkingDirectory.
+ *   - {{ROOT_DIR}} — the self-contained install root: where logs/service/
+ *     lives (0.2.0 self-contained layout — logs are a root-level concern, not
+ *     nested inside the app checkout).
+ *   - {{LABEL}} — the per-install launchd label from paths.ts deriveServiceLabels.
+ * Ports/vaultPath are read from config at process start by the run-*.sh
+ * scripts / server, never baked into the plist.
  */
-export function renderPlistTemplate(template, installDir, label) {
-    return template.split("{{INSTALL_DIR}}").join(installDir).split("{{LABEL}}").join(label);
+export function renderPlistTemplate(template, installDir, rootDir, label) {
+    return template
+        .split("{{INSTALL_DIR}}")
+        .join(installDir)
+        .split("{{ROOT_DIR}}")
+        .join(rootDir)
+        .split("{{LABEL}}")
+        .join(label);
 }
 /** Basic structural sanity check without shelling out to `plutil` (used in unit tests; `plutil -lint` is used in the dry-run for the real macOS check). */
 export function looksLikeValidPlist(xml) {

package/dist/ports.js

@@ -1,28 +1,46 @@
 /**
  * Zero-dependency free-port detection via node:net (spec §1 Step 5).
+ *
+ * A port must be probed on BOTH loopback families: a server listening only on
+ * [::1] (IPv6) leaves 127.0.0.1 bindable, so an IPv4-only probe reports the
+ * port "free" while browsers (which resolve localhost to ::1 first) hit the
+ * other process. Field-tested: a Node dev server on [::1]:1347 made the
+ * installer pre-fill an occupied port. A port counts as free only if every
+ * loopback family available on this machine can bind it.
  */
 import { createServer } from "node:net";
-/** Resolve true if `port` is free to bind on 127.0.0.1, false if taken. */
-export function isPortFree(port) {
+/** Error codes meaning "this address family isn't available on this machine". */
+const FAMILY_UNAVAILABLE = new Set(["EADDRNOTAVAIL", "EAFNOSUPPORT", "EINVAL"]);
+/** Try to bind `port` on one loopback host and report what happened. */
+function probeBind(port, host) {
     return new Promise((resolve) => {
         const server = createServer();
         server.once("error", (err) => {
             server.close();
-            if (err.code === "EADDRINUSE" || err.code === "EACCES") {
-                resolve(false);
+            if (err.code && FAMILY_UNAVAILABLE.has(err.code)) {
+                // No IPv6 (or IPv4) loopback on this machine — nothing to conflict with.
+                resolve("family-unavailable");
             }
             else {
-                // Unexpected error probing the port — treat conservatively as taken
-                // so we never suggest a port we can't actually validate.
-                resolve(false);
+                // EADDRINUSE/EACCES, or anything unexpected — treat conservatively as
+                // taken so we never suggest a port we can't actually validate.
+                resolve("taken");
             }
         });
         server.once("listening", () => {
-            server.close(() => resolve(true));
+            server.close(() => resolve("free"));
         });
-        server.listen(port, "127.0.0.1");
+        server.listen(port, host);
     });
 }
+/**
+ * Resolve true if `port` is free to bind on ALL applicable loopback families
+ * (127.0.0.1 and ::1), false if any listener holds it on either family.
+ */
+export async function isPortFree(port) {
+    const [v4, v6] = await Promise.all([probeBind(port, "127.0.0.1"), probeBind(port, "::1")]);
+    return v4 !== "taken" && v6 !== "taken";
+}
 /**
  * Find the first free port at or above `start`, scanning upward. Stops at
  * `start + maxScan` to avoid an unbounded loop.