arelos 0.2.0 → 0.2.2

package/dist/cli-args.js

@@ -43,6 +43,17 @@ export function parseInstallFlags(argv) {
     }
     return flags;
 }
+export function parsePortsFlags(argv) {
+    const flags = { webPort: null, vaultPort: null };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--web-port")
+            flags.webPort = Number(argv[++i]);
+        else if (arg === "--vault-port")
+            flags.vaultPort = Number(argv[++i]);
+    }
+    return flags;
+}
 export function parseLogsFlags(argv) {
     let which = "both";
     let follow = false;

package/dist/cli.js

@@ -9,10 +9,11 @@ if (process.platform !== "darwin") {
     console.error("Arel OS currently supports macOS only.");
     process.exit(1);
 }
-import { parseInstallFlags, parseLogsFlags } from "./cli-args.js";
+import { parseInstallFlags, parseLogsFlags, parsePortsFlags } from "./cli-args.js";
 import { runInstall } from "./install.js";
 import { listCommand } from "./list.js";
 import { logsCommand } from "./logs.js";
+import { portsCommand } from "./ports-command.js";
 import { statusCommand } from "./status.js";
 import { uninstallCommand } from "./uninstall.js";
 import { updateCommand } from "./update.js";
@@ -26,7 +27,7 @@ async function main() {
     // rather than a subcommand name — both mean "install". Anything else in
     // the known set consumes its name as the subcommand; everything after it
     // is passed through as that subcommand's own args.
-    const knownSubcommands = new Set(["install", "status", "update", "uninstall", "logs", "list"]);
+    const knownSubcommands = new Set(["install", "status", "update", "uninstall", "logs", "list", "ports"]);
     const firstIsFlag = argv.length === 0 || argv[0].startsWith("-");
     const firstIsKnown = argv.length > 0 && knownSubcommands.has(argv[0]);
     if (!firstIsFlag && !firstIsKnown) {
@@ -50,6 +51,8 @@ async function main() {
             return uninstallCommand(nameArgFrom(rest));
         case "logs":
             return logsCommand(parseLogsFlags(rest), logsNameArgFrom(rest));
+        case "ports":
+            return portsCommand(parsePortsFlags(rest), nameArgFrom(rest));
         default:
             console.error(`Unknown command: ${subcommand}\n`);
             printHelp();
@@ -89,6 +92,7 @@ Usage:
   arelos update [name]             git pull + rebuild + restart
   arelos uninstall [name]          Stop services, optionally remove install dir / vault
   arelos logs [name] [web|vault]   Tail service logs (-f to follow, -n <N> for line count)
+  arelos ports [name]              Change the web/vault ports (interactive, or via flags below)
 
 [name] is only needed when you have more than one install; omit it with a
 single install, or you'll be prompted to choose interactively.
@@ -102,6 +106,10 @@ Install flags (non-interactive):
   --vault-port <port>
   --no-service              Skip launchd bootstrap (for dry runs / development)
   --local-repo <path>       Use a local path instead of cloning from GitHub
+
+Ports flags (non-interactive):
+  --web-port <port>         New web port (omit to keep current)
+  --vault-port <port>       New vault port (omit to keep current)
 `);
 }
 main()

package/dist/ports-command.js

@@ -0,0 +1,158 @@
+/**
+ * `arelos ports [name]`. Change an existing install's web/vault ports:
+ * interactive prompt (default = keep current) or non-interactive
+ * `--web-port`/`--vault-port` flags. Registry-aware like status/update/logs
+ * (see cli-context.ts resolveInstall).
+ *
+ * On change: rewrite <root>/config.json atomically, then restart both
+ * launchd services (kickstart -k — the web service's run-web.sh rebuilds and
+ * re-bakes VITE_VAULT_API from config.json on every start, so a kickstart
+ * alone is enough to pick up new ports; see scripts/service/run-web.sh), then
+ * health-check both new ports with the existing health/diagnostics machinery.
+ *
+ * The restart+health-check step is expressed as an injectable "effects"
+ * object (RestartEffects) so tests can assert the exact call sequence
+ * without ever touching real launchctl or the network.
+ */
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { resolveRoot, resolveServiceLabels, writeConfig } from "./config.js";
+import { resolveInstall } from "./cli-context.js";
+import { formatHealthTimeoutDiagnostics, waitForHealthy } from "./health.js";
+import { lastLines, logPathFor } from "./logs.js";
+import { installConfigPath } from "./paths.js";
+import { resolvePort } from "./install-plan.js";
+import { bootstrapAndStart } from "./services.js";
+/**
+ * Resolve one requested port against its current value: null (or equal to
+ * current) means "keep, no validation needed" — re-validating the port
+ * you're already bound to would spuriously fail once services are up and
+ * holding it. A genuinely different request must resolve to itself exactly
+ * (hard-fail on occupied) — `resolvePortFn` is injected so tests can stub it
+ * without touching real sockets, and the real caller passes the hardened
+ * `resolvePort` from install-plan.ts.
+ */
+async function resolveOneField(field, current, requested, resolvePortFn) {
+    if (requested === null || requested === current) {
+        return { field, current, requested: null, resolution: null, changed: false };
+    }
+    const resolution = await resolvePortFn(requested);
+    return { field, current, requested, resolution, changed: resolution.resolved === requested };
+}
+/**
+ * Build and validate a port-change plan from the install's current config
+ * and the caller's requested new ports (null = keep current). Both fields
+ * are validated independently; a requested port that's occupied (and thus
+ * would resolve to something other than itself) is a hard failure — ports is
+ * a deliberate, exact change, unlike install's "pick something nearby".
+ */
+export async function buildPortChangePlan(current, requested, resolvePortFn = resolvePort) {
+    if (requested.webPort !== null && requested.vaultPort !== null && requested.webPort === requested.vaultPort) {
+        return { ok: false, message: `Web port and vault port must differ (both were ${requested.webPort}).` };
+    }
+    const web = await resolveOneField("webPort", current.webPort, requested.webPort, resolvePortFn);
+    if (web.requested !== null && web.resolution && !web.resolution.wasFree) {
+        return {
+            ok: false,
+            message: `Port ${web.requested} is already in use — choose a free port for the web service.`,
+        };
+    }
+    const vault = await resolveOneField("vaultPort", current.vaultPort, requested.vaultPort, resolvePortFn);
+    if (vault.requested !== null && vault.resolution && !vault.resolution.wasFree) {
+        return {
+            ok: false,
+            message: `Port ${vault.requested} is already in use — choose a free port for the vault service.`,
+        };
+    }
+    // Cross-field collision: e.g. new web port == current (unchanged) vault port.
+    const finalWeb = web.changed ? web.requested : current.webPort;
+    const finalVault = vault.changed ? vault.requested : current.vaultPort;
+    if (finalWeb === finalVault) {
+        return { ok: false, message: `Web port and vault port must differ (both would be ${finalWeb}).` };
+    }
+    return { ok: true, plan: { web, vault, anyChange: web.changed || vault.changed } };
+}
+/** Apply a resolved plan to a config object, returning the updated config (pure — no I/O). */
+export function applyPlanToConfig(config, plan) {
+    return {
+        ...config,
+        webPort: plan.web.changed ? plan.web.requested : config.webPort,
+        vaultPort: plan.vault.changed ? plan.vault.requested : config.vaultPort,
+    };
+}
+export const realRestartEffects = {
+    restartServices: async (labels) => {
+        const result = await bootstrapAndStart(labels);
+        return { errors: result.errors };
+    },
+    waitForHealthy,
+};
+export async function portsCommand(flags, name, effects = realRestartEffects) {
+    const result = await resolveInstall({ name, interactive: process.stdout.isTTY === true });
+    if (!result.ok) {
+        console.error(result.message);
+        return 1;
+    }
+    const { config, root } = result.install;
+    const interactive = process.stdout.isTTY === true && flags.webPort === null && flags.vaultPort === null;
+    console.log(pc.bold(config.displayName));
+    console.log(`  Web port:    ${config.webPort}`);
+    console.log(`  Vault port:  ${config.vaultPort}`);
+    console.log("");
+    let requestedWeb = flags.webPort;
+    let requestedVault = flags.vaultPort;
+    if (interactive) {
+        p.intro(pc.bold("Change ports"));
+        const webRaw = await p.text({
+            message: "New web port (blank = keep current):",
+            placeholder: String(config.webPort),
+            defaultValue: String(config.webPort),
+        });
+        if (p.isCancel(webRaw)) {
+            p.cancel("Cancelled.");
+            return 1;
+        }
+        const vaultRaw = await p.text({
+            message: "New vault port (blank = keep current):",
+            placeholder: String(config.vaultPort),
+            defaultValue: String(config.vaultPort),
+        });
+        if (p.isCancel(vaultRaw)) {
+            p.cancel("Cancelled.");
+            return 1;
+        }
+        const webNum = Number(webRaw);
+        const vaultNum = Number(vaultRaw);
+        requestedWeb = Number.isFinite(webNum) ? webNum : null;
+        requestedVault = Number.isFinite(vaultNum) ? vaultNum : null;
+    }
+    const planOutcome = await buildPortChangePlan({ webPort: config.webPort, vaultPort: config.vaultPort }, { webPort: requestedWeb, vaultPort: requestedVault });
+    if (!planOutcome.ok) {
+        console.error(pc.red(planOutcome.message));
+        return 1;
+    }
+    const { plan } = planOutcome;
+    if (!plan.anyChange) {
+        console.log("No change — ports are already what was requested.");
+        return 0;
+    }
+    const updatedConfig = applyPlanToConfig(config, plan);
+    const cfgRoot = resolveRoot(config);
+    const cfgPath = installConfigPath(cfgRoot);
+    writeConfig(updatedConfig, cfgPath);
+    console.log(pc.green(`Config updated: web ${config.webPort} -> ${updatedConfig.webPort}, vault ${config.vaultPort} -> ${updatedConfig.vaultPort}.`));
+    const labels = resolveServiceLabels(updatedConfig);
+    console.log("Restarting services…");
+    const restart = await effects.restartServices(labels);
+    for (const e of restart.errors)
+        console.error(pc.yellow(e));
+    console.log("Waiting for the app to come back up…");
+    const health = await effects.waitForHealthy(updatedConfig.webPort, updatedConfig.vaultPort);
+    if (!health.healthy) {
+        console.error(pc.red(formatHealthTimeoutDiagnostics(cfgRoot, (path) => lastLines(path, 10), logPathFor)));
+        console.error(pc.dim("\nFull logs: arelos logs"));
+        return 1;
+    }
+    console.log(pc.green("Ports changed and Arel OS is healthy again."));
+    return 0;
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arelos",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Installer and service manager for a self-hosted Arel OS on macOS.",
   "type": "module",
   "bin": {