arelos 0.1.2 → 0.2.1

package/dist/ports.js

@@ -1,24 +1,47 @@
 /**
  * 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.
+ * A port must be probed on every listener shape a process can occupy it
+ * with, not just the specific loopback addresses:
+ *
+ * - 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 server listening on the WILDCARD address (e.g. `Bun.serve()` with no
+ *   `hostname`, or `net.createServer().listen(port)` with no host) binds
+ *   every local address in that family, including both loopback addresses,
+ *   yet a bind-probe of 127.0.0.1/::1 alone can still report "free" on
+ *   macOS: binding a specific address with SO_REUSEADDR (Node's default) can
+ *   succeed even though a wildcard listener already holds the port. Real
+ *   incident: `isPortFree(5274)` reported free while a Bun server held
+ *   `*:5274`, and the installer wrote that occupied port into config.
+ *
+ * The fix probes both shapes with two independent techniques:
+ *   1. Bind-probes on the specific loopback addresses AND the wildcard
+ *      addresses for each family. A wildcard bind-probe fails with
+ *      EADDRINUSE whenever *any* listener (wildcard or specific) holds the
+ *      port in that family — it is the strongest bind test available.
+ *   2. A short-timeout TCP connect-probe to 127.0.0.1 and ::1. A successful
+ *      connection proves the port is occupied even in edge cases the bind
+ *      probes can't reach; ECONNREFUSED proves free for that family; a
+ *      timeout or other inconclusive result is never treated as occupied on
+ *      its own.
+ *
+ * A port counts as free only if every applicable bind probe succeeds AND no
+ * connect probe manages to connect.
  */
-import { createServer } from "node:net";
+import { createServer, connect as netConnect } from "node:net";
 /** 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. */
+/** Try to bind `port` on one host (specific address or wildcard) and report what happened. */
 function probeBind(port, host) {
     return new Promise((resolve) => {
         const server = createServer();
         server.once("error", (err) => {
             server.close();
             if (err.code && FAMILY_UNAVAILABLE.has(err.code)) {
-                // No IPv6 (or IPv4) loopback on this machine — nothing to conflict with.
+                // No IPv6 (or IPv4) support on this machine — nothing to conflict with.
                 resolve("family-unavailable");
             }
             else {
@@ -33,13 +56,58 @@ function probeBind(port, host) {
         server.listen(port, host);
     });
 }
+const CONNECT_PROBE_TIMEOUT_MS = 250;
+/**
+ * Try to TCP-connect to `host:port` with a short timeout. A successful
+ * connection means something is definitely listening there. ECONNREFUSED
+ * means nothing is listening (free, for that family). Anything else
+ * (timeout, unreachable, family unavailable) is inconclusive and must not be
+ * treated as proof of occupation by itself.
+ */
+function probeConnect(port, host) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let socket;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(result);
+        };
+        socket = netConnect({ port, host });
+        socket.setTimeout(CONNECT_PROBE_TIMEOUT_MS);
+        socket.once("connect", () => finish("occupied"));
+        socket.once("timeout", () => finish("inconclusive"));
+        socket.once("error", (err) => {
+            if (err.code === "ECONNREFUSED") {
+                finish("free");
+            }
+            else {
+                // EHOSTUNREACH, ENETUNREACH, family unavailable, etc. — inconclusive.
+                finish("inconclusive");
+            }
+        });
+    });
+}
 /**
- * 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.
+ * Resolve true if `port` is free on every probe: bind-probes on the specific
+ * loopback addresses and the wildcard addresses for both families, plus
+ * connect-probes to the loopback addresses. False if any bind probe reports
+ * "taken" or any connect probe successfully connects.
  */
 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";
+    const [v4Loopback, v6Loopback, v4Wildcard, v6Wildcard, v4Connect, v6Connect] = await Promise.all([
+        probeBind(port, "127.0.0.1"),
+        probeBind(port, "::1"),
+        probeBind(port, "0.0.0.0"),
+        probeBind(port, "::"),
+        probeConnect(port, "127.0.0.1"),
+        probeConnect(port, "::1"),
+    ]);
+    const bindsOk = [v4Loopback, v6Loopback, v4Wildcard, v6Wildcard].every((result) => result !== "taken");
+    const noConnectSucceeded = v4Connect !== "occupied" && v6Connect !== "occupied";
+    return bindsOk && noConnectSucceeded;
 }
 /**
  * Find the first free port at or above `start`, scanning upward. Stops at

package/dist/registry.js

@@ -0,0 +1,41 @@
+/**
+ * Global multi-install registry (~/.arelos/installs.json, or
+ * ARELOS_REGISTRY_PATH override). Each entry records one named, self-contained
+ * install so `arelos` can find/list/select among several installs on one Mac
+ * without any of them clobbering a shared config file (0.2.0 mission).
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { registryPath } from "./paths.js";
+export function readRegistry() {
+    const p = registryPath();
+    if (!existsSync(p))
+        return [];
+    const raw = JSON.parse(readFileSync(p, "utf8"));
+    if (!Array.isArray(raw)) {
+        throw new Error(`Invalid registry at ${p}: expected an array`);
+    }
+    return raw;
+}
+/** Atomic write: tmp file + rename, so a reader never sees a partial file. */
+function writeRegistry(entries) {
+    const p = registryPath();
+    mkdirSync(dirname(p), { recursive: true });
+    const tmp = `${p}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(entries, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, p);
+}
+/** Append (or replace, by matching root) an entry — a reinstall at the same root updates it in place. */
+export function addRegistryEntry(entry) {
+    const entries = readRegistry().filter((e) => e.root !== entry.root);
+    entries.push(entry);
+    writeRegistry(entries);
+}
+/** Remove the entry for a given root (uninstall). No-op if absent. */
+export function removeRegistryEntry(root) {
+    const entries = readRegistry().filter((e) => e.root !== root);
+    writeRegistry(entries);
+}
+export function findRegistryEntryByName(name) {
+    return readRegistry().find((e) => e.name === name || e.slug === name) ?? null;
+}

package/dist/repair.js

@@ -5,9 +5,10 @@
  */
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import { resolveServiceLabels } from "./config.js";
+import { resolveRoot, resolveServiceLabels } from "./config.js";
 import { runUpdate } from "./update.js";
-import { waitForHealthy } from "./health.js";
+import { formatHealthTimeoutDiagnostics, waitForHealthy } from "./health.js";
+import { lastLines, logPathFor } from "./logs.js";
 import { bootstrapAndStart, installServiceFiles } from "./services.js";
 import { runStreaming } from "./exec.js";
 import { ensureBun } from "./bun-setup.js";
@@ -40,9 +41,8 @@ export async function runRepairMenu(existing) {
         return runRepair(existing);
     }
     if (choice === "reinstall") {
-        p.log.message("Reinstall elsewhere is not automatic yet — run `arelos uninstall` first if you want to reuse this " +
-            "install dir/ports, or re-run `npx arelos --install-dir <new path> --web-port <n> --vault-port <n>` " +
-            "for a side-by-side install with a different ARELOS_CONFIG_PATH.");
+        p.log.message("Just re-run `npx arelos` with a different name — every install is self-contained, so a new name " +
+            "creates a fresh, independent install side-by-side with this one (see `arelos list`).");
         return 0;
     }
     return 1;
@@ -69,13 +69,17 @@ async function runRepair(existing) {
     s.stop("Rebuilt.");
     s.start("Re-rendering and re-bootstrapping services…");
     const labels = resolveServiceLabels(existing);
-    installServiceFiles(existing.installDir, labels);
+    installServiceFiles(existing.installDir, resolveRoot(existing), labels);
     const bootstrap = await bootstrapAndStart(labels);
     s.stop(bootstrap.errors.length ? "Services re-registered with warnings." : "Services re-registered.");
     for (const e of bootstrap.errors)
         console.error(pc.yellow(e));
     s.start("Health check…");
     const health = await waitForHealthy(existing.webPort, existing.vaultPort);
-    s.stop(health.healthy ? "Healthy." : "Health check timed out — see arelos logs.");
+    s.stop(health.healthy ? "Healthy." : "Health check timed out.");
+    if (!health.healthy) {
+        console.error(pc.red(formatHealthTimeoutDiagnostics(resolveRoot(existing), (p) => lastLines(p, 10), logPathFor)));
+        console.error(pc.dim("\nFull logs: arelos logs"));
+    }
     return health.healthy ? 0 : 1;
 }

package/dist/repo.js

@@ -1,7 +1,7 @@
 /**
- * Getting the app source onto disk (spec §1 Step 8) and keeping it updated
- * (spec §2 rlo update). Supports a `--local-repo <path>` override for
- * development/dry-run testing so we never have to hit GitHub in tests.
+ * Getting the app source onto disk and keeping it updated (`arelos update`).
+ * Supports a `--local-repo <path>` override for development/dry-run testing
+ * so we never have to hit GitHub in tests.
  */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -40,7 +40,7 @@ export async function currentRevision(installDir) {
     const res = await runCapture("git", ["-C", installDir, "rev-parse", "--short", "HEAD"]);
     return res.code === 0 ? res.stdout.trim() : null;
 }
-/** Best-effort "is the local branch behind origin" check (spec §2 rlo status). */
+/** Best-effort "is the local branch behind origin" check (`arelos status`). */
 export async function isBehindOrigin(installDir) {
     const fetchRes = await runCapture("git", ["-C", installDir, "fetch", "--dry-run"]);
     if (fetchRes.code !== 0)

package/dist/scaffold.js

@@ -1,14 +1,13 @@
 /**
- * Vault scaffolding + supporting install-dir setup (spec §1 Step 9).
- * Only copies the template vault when the destination is empty — never
- * overwrites user data (spec §3.2 idempotency rule).
+ * Vault scaffolding + supporting install-dir setup. Only copies the template
+ * vault when the destination is empty — never overwrites user data.
  */
 import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 export class TemplateVaultMissingError extends Error {
     constructor(templateDir) {
         super(`templates/vault/ is missing at ${templateDir}. This is a repo gap — ` +
-            `the app repo must ship a seed vault at templates/vault/ (see portability-contract.md / rlo-cli-spec.md §1 Step 9). Cannot scaffold a new vault without it.`);
+            `the app repo must ship a seed vault at templates/vault/. Cannot scaffold a new vault without it.`);
         this.name = "TemplateVaultMissingError";
     }
 }
@@ -34,10 +33,11 @@ export function scaffoldVault(installDir, vaultPath) {
     cpSync(templateDir, vaultPath, { recursive: true });
     return { copied: true };
 }
-/** Create <installDir>/logs/service/ — must exist before launchd bootstraps
- * the plists, since they reference it for stdout/stderr (spec, implementer notes). */
-export function ensureLogsDir(installDir) {
-    const dir = join(installDir, "logs", "service");
+/** Create <root>/logs/service/ — must exist before launchd bootstraps the
+ * plists, since they reference it for stdout/stderr. Logs live at the
+ * self-contained root, not inside the app checkout (0.2.0 layout). */
+export function ensureLogsDir(root) {
+    const dir = join(root, "logs", "service");
     mkdirSync(dir, { recursive: true });
     return dir;
 }

package/dist/services.js

@@ -1,14 +1,18 @@
 /**
- * Ties together plist rendering + writing + launchd bootstrap (spec §1 Step 11,
- * §3.1 Repair). Also used by `--no-service` dry runs, which stop before the
- * launchctl calls (see install.ts).
+ * Ties together plist rendering + writing + launchd bootstrap. Also used by
+ * `--no-service` dry runs, which stop before the launchctl calls (see
+ * install.ts).
+ *
+ * `installDir` is the app checkout (root/app); `root` is the self-contained
+ * install root that owns logs/ and config.json (0.2.0 layout). Both are
+ * needed because the plist bakes in both {{INSTALL_DIR}} and {{ROOT_DIR}}.
  */
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { bootstrapService, kickstartService } from "./launchd.js";
 import { deriveServiceLabels, launchAgentsDir, plistPath } from "./paths.js";
 import { renderPlistTemplate } from "./plist.js";
-export function renderServicePlists(installDir, labels = deriveServiceLabels(installDir)) {
+export function renderServicePlists(installDir, root, labels = deriveServiceLabels(root)) {
     const specs = [
         { label: labels.web, templateFile: "web.plist.tmpl" },
         { label: labels.vault, templateFile: "vault.plist.tmpl" },
@@ -19,22 +23,22 @@ export function renderServicePlists(installDir, labels = deriveServiceLabels(ins
             throw new Error(`Missing plist template: ${templatePath}`);
         }
         const template = readFileSync(templatePath, "utf8");
-        const xml = renderPlistTemplate(template, installDir, label);
+        const xml = renderPlistTemplate(template, installDir, root, label);
         return { label, templatePath, targetPath: plistPath(label), xml };
     });
 }
 /** Write rendered plists to ~/Library/LaunchAgents and chmod the run scripts. */
-export function installServiceFiles(installDir, labels = deriveServiceLabels(installDir)) {
+export function installServiceFiles(installDir, root, labels = deriveServiceLabels(root)) {
     mkdirSync(launchAgentsDir(), { recursive: true });
-    // The plists' StandardOutPath/StandardErrorPath point at <installDir>/logs/service/*.log;
+    // The plists' StandardOutPath/StandardErrorPath point at <root>/logs/service/*.log;
     // launchd needs that directory to exist before it can bootstrap the job (a
     // missing log dir is one confirmed cause of the "Bootstrap failed: 5:
     // Input/output error" field report — see launchd.ts docstring). install.ts
     // already calls ensureLogsDir before this, but repair/update funnel through
     // here too, so guarantee it unconditionally rather than relying on callers
     // to remember.
-    mkdirSync(join(installDir, "logs", "service"), { recursive: true });
-    const rendered = renderServicePlists(installDir, labels);
+    mkdirSync(join(root, "logs", "service"), { recursive: true });
+    const rendered = renderServicePlists(installDir, root, labels);
     for (const svc of rendered) {
         writeFileSync(svc.targetPath, svc.xml);
     }

package/dist/status.js

@@ -1,19 +1,24 @@
 /**
- * `rlo status` (spec §2). Config summary + service state + port probes +
- * git revision / behind-origin check.
+ * `arelos status`. Config summary + service state + port probes + git revision /
+ * behind-origin check. With multiple installs registered, resolves by name
+ * (or prompts/lists per resolveInstall's rule).
  */
 import pc from "picocolors";
-import { readConfig, resolveServiceLabels } from "./config.js";
+import { resolveServiceLabels } from "./config.js";
+import { resolveInstall } from "./cli-context.js";
 import { checkVaultHealth, checkWebHealth } from "./health.js";
 import { getServiceStatus } from "./launchd.js";
 import { currentRevision, isBehindOrigin } from "./repo.js";
-export async function statusCommand() {
-    const config = readConfig();
-    if (!config) {
-        console.error("No Arel OS install found. Run `npx arelos` to install.");
+export async function statusCommand(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;
     console.log(pc.bold(config.displayName));
+    if (config.root)
+        console.log(`  Root:        ${config.root}`);
     console.log(`  Install dir: ${config.installDir}`);
     console.log(`  Vault path:  ${config.vaultPath}`);
     console.log(`  Web port:    ${config.webPort}`);

package/dist/uninstall.js

@@ -1,31 +1,41 @@
 /**
- * `rlo uninstall` (spec §2). Vault deletion is gated behind confirm + a
- * literal typed "DELETE" — a single yes can never destroy notes (spec §3.2,
- * acceptance criterion 5). This module separates the pure decision logic
- * (shouldDeleteVault) from the destructive I/O (performUninstall) so the
- * gate can be unit tested without touching a filesystem.
+ * `arelos uninstall`. Vault deletion is gated behind confirm + a literal typed
+ * "DELETE" — a single yes can never destroy notes. This module separates the
+ * pure decision logic (shouldDeleteVault) from the destructive I/O
+ * (performUninstall) so the gate can be unit tested without touching a
+ * filesystem.
+ *
+ * 0.2.0 self-contained layout: installDir (root/app) and vaultPath (root/vault)
+ * are siblings under root, so removing installDir never touches the vault —
+ * the pre-0.2.0 "install dir vs vault" gate semantics carry over unchanged.
+ * Removing the registry entry is separate from folder/vault deletion (always
+ * done, since a stale registry entry pointing at a gone or kept-around
+ * install is never useful).
  */
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { existsSync, rmSync, unlinkSync } from "node:fs";
-import { readConfig, resolveServiceLabels } from "./config.js";
+import { resolveRoot, resolveServiceLabels } from "./config.js";
+import { resolveInstall } from "./cli-context.js";
 import { bootoutService } from "./launchd.js";
-import { plistPath, configPath } from "./paths.js";
+import { plistPath, installConfigPath, legacyConfigPath } from "./paths.js";
+import { removeRegistryEntry } from "./registry.js";
 /**
  * Pure gate: vault is deleted iff confirmed AND the typed word is exactly
  * "DELETE". Any other input (including case variants, whitespace, empty)
- * preserves the vault. This is the load-bearing safety rule from the spec —
- * kept as an isolated pure function so it's trivially unit-testable.
+ * preserves the vault. This is the load-bearing safety rule — kept as an
+ * isolated pure function so it's trivially unit-testable.
  */
 export function shouldDeleteVault(confirmed, typedWord) {
     return confirmed === true && typedWord === "DELETE";
 }
-export async function uninstallCommand() {
-    const config = readConfig();
-    if (!config) {
-        console.error("No Arel OS install found. Nothing to uninstall.");
+export async function uninstallCommand(name) {
+    const result = await resolveInstall({ name, interactive: process.stdout.isTTY === true });
+    if (!result.ok) {
+        console.error(result.message);
         return 1;
     }
+    const { config, root } = result.install;
     p.intro(pc.bold("Uninstall Arel OS"));
     const labels = resolveServiceLabels(config);
     await bootoutService(labels.web);
@@ -60,26 +70,37 @@ export async function uninstallCommand() {
         }
     }
     const removeConfig = await p.confirm({
-        message: "Remove the saved config (~/.arelos/config.json)? Keeping it lets a reinstall remember your settings.",
+        message: "Remove the saved config? Keeping it lets a reinstall remember your settings.",
         initialValue: false,
     });
-    performUninstall(config.installDir, config.vaultPath, {
+    performUninstall(config.installDir, config.vaultPath, resolveRoot(config), {
         removeInstallDir: !p.isCancel(removeInstallDir) && removeInstallDir,
         deleteVault,
         removeConfig: !p.isCancel(removeConfig) && removeConfig,
     });
+    if (root)
+        removeRegistryEntry(root);
     p.outro(pc.green("Arel OS uninstalled." + (deleteVault ? "" : " Your vault was preserved.")));
     return 0;
 }
-/** Destructive I/O, isolated from prompt flow for testability via direct calls with explicit choices. */
-export function performUninstall(installDir, vaultPath, choices) {
+/**
+ * Destructive I/O, isolated from prompt flow for testability via direct
+ * calls with explicit choices. `root` is passed separately from `installDir`
+ * so config.json (which lives at root, a parent of installDir) is removed
+ * correctly rather than assumed to live inside installDir.
+ */
+export function performUninstall(installDir, vaultPath, root, choices) {
     if (choices.deleteVault && existsSync(vaultPath)) {
         rmSync(vaultPath, { recursive: true, force: true });
     }
     if (choices.removeInstallDir && existsSync(installDir)) {
         rmSync(installDir, { recursive: true, force: true });
     }
-    if (choices.removeConfig && existsSync(configPath())) {
-        unlinkSync(configPath());
+    if (choices.removeConfig) {
+        const cfgPath = installConfigPath(root);
+        if (existsSync(cfgPath))
+            unlinkSync(cfgPath);
+        if (existsSync(legacyConfigPath()))
+            unlinkSync(legacyConfigPath());
     }
 }

package/dist/update.js

@@ -1,21 +1,23 @@
 /**
- * `rlo update` (spec §2). git pull --ff-only + bun install/build + restart +
- * re-health-check. Config file untouched.
+ * `arelos update`. git pull --ff-only + bun install/build + restart +
+ * re-health-check. Config file untouched. With multiple installs registered,
+ * resolves by name (or prompts/lists per resolveInstall's rule).
  */
 import pc from "picocolors";
 import { ensureBun } from "./bun-setup.js";
-import { readConfig, resolveServiceLabels } from "./config.js";
+import { resolveRoot, resolveServiceLabels } from "./config.js";
+import { resolveInstall } from "./cli-context.js";
 import { runStreaming } from "./exec.js";
 import { waitForHealthy } from "./health.js";
 import { pullLatest } from "./repo.js";
 import { bootstrapAndStart, installServiceFiles } from "./services.js";
-export async function updateCommand() {
-    const config = readConfig();
-    if (!config) {
-        console.error("No Arel OS install found. Run `npx arelos` to install.");
+export async function updateCommand(name) {
+    const result = await resolveInstall({ name, interactive: process.stdout.isTTY === true });
+    if (!result.ok) {
+        console.error(result.message);
         return 1;
     }
-    return runUpdate(config);
+    return runUpdate(result.install.config);
 }
 export async function runUpdate(config) {
     console.log(`Updating ${config.installDir}…`);
@@ -45,7 +47,7 @@ export async function runUpdate(config) {
         console.warn(pc.yellow("bun run build failed — keeping old dist/. The web service will keep serving it."));
     }
     const labels = resolveServiceLabels(config);
-    installServiceFiles(config.installDir, labels);
+    installServiceFiles(config.installDir, resolveRoot(config), labels);
     const bootstrap = await bootstrapAndStart(labels);
     for (const e of bootstrap.errors)
         console.error(pc.yellow(e));

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "arelos",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Installer and service manager for a self-hosted Arel OS on macOS.",
   "type": "module",
   "bin": {
-    "arelos": "dist/cli.js",
-    "rlo": "dist/cli.js"
+    "arelos": "dist/cli.js"
   },
   "files": [
     "dist"