arelos 0.1.1 → 0.2.0

package/dist/cli-args.js

@@ -4,8 +4,8 @@ export function parseInstallFlags(argv) {
         noService: false,
         localRepo: null,
         displayName: null,
-        installDir: null,
-        vaultPath: null,
+        root: null,
+        parentDir: null,
         webPort: null,
         vaultPort: null,
     };
@@ -25,11 +25,11 @@ export function parseInstallFlags(argv) {
             case "--display-name":
                 flags.displayName = argv[++i] ?? null;
                 break;
-            case "--install-dir":
-                flags.installDir = argv[++i] ?? null;
+            case "--root":
+                flags.root = argv[++i] ?? null;
                 break;
-            case "--vault-path":
-                flags.vaultPath = argv[++i] ?? null;
+            case "--parent-dir":
+                flags.parentDir = argv[++i] ?? null;
                 break;
             case "--web-port":
                 flags.webPort = Number(argv[++i]);

package/dist/cli-context.js

@@ -0,0 +1,80 @@
+/**
+ * Shared "which install does this command target" resolution for
+ * status/update/logs/uninstall (0.2.0 multi-install support).
+ *
+ * Rule: no name arg + exactly one known install -> that one. No name arg +
+ * multiple installs -> interactive select (or, non-interactively, an error
+ * listing the options). A name arg always resolves by exact registry
+ * name/slug match. "Known installs" = registry entries, plus the legacy
+ * fixed ~/.arelos/config.json as an "(unnamed)" install when present and not
+ * already superseded by a registry entry at the same root.
+ */
+import * as p from "@clack/prompts";
+import { readConfigAt, readConfig } from "./config.js";
+import { legacyConfigPath } from "./paths.js";
+import { existsSync } from "node:fs";
+import { readRegistry } from "./registry.js";
+function listCandidates() {
+    const entries = readRegistry();
+    const candidates = entries.map((e) => ({ name: e.name, root: e.root }));
+    if (existsSync(legacyConfigPath())) {
+        candidates.push({ name: "(unnamed — legacy install)", root: null });
+    }
+    return candidates;
+}
+function loadCandidate(candidate) {
+    const config = candidate.root ? readConfigAt(candidate.root) : readConfig();
+    if (!config)
+        return null;
+    return { name: candidate.name, root: candidate.root, config };
+}
+/** Resolve which install a status/update/logs/uninstall invocation targets. */
+export async function resolveInstall(opts) {
+    const candidates = listCandidates();
+    if (opts.name) {
+        const match = candidates.find((c) => c.name === opts.name);
+        if (!match) {
+            const known = candidates.map((c) => c.name).join(", ") || "(none)";
+            return { ok: false, message: `No install named "${opts.name}" found. Known installs: ${known}` };
+        }
+        const resolved = loadCandidate(match);
+        if (!resolved) {
+            return { ok: false, message: `Install "${opts.name}" is registered but its config could not be read.` };
+        }
+        return { ok: true, install: resolved };
+    }
+    if (candidates.length === 0) {
+        return { ok: false, message: "No Arel OS install found. Run `npx arelos` to install." };
+    }
+    if (candidates.length === 1) {
+        const resolved = loadCandidate(candidates[0]);
+        if (!resolved) {
+            return { ok: false, message: "Install is registered but its config could not be read." };
+        }
+        return { ok: true, install: resolved };
+    }
+    // Multiple installs, no name given.
+    if (!opts.interactive) {
+        const known = candidates.map((c) => c.name).join(", ");
+        return {
+            ok: false,
+            message: `Multiple Arel OS installs found — pass a name. Known installs: ${known}`,
+        };
+    }
+    const choice = await p.select({
+        message: "Which install?",
+        options: candidates.map((c) => ({ value: c.name, label: c.name })),
+    });
+    if (p.isCancel(choice)) {
+        return { ok: false, message: "Cancelled." };
+    }
+    const match = candidates.find((c) => c.name === choice);
+    const resolved = match ? loadCandidate(match) : null;
+    if (!resolved) {
+        return { ok: false, message: "Selected install's config could not be read." };
+    }
+    return { ok: true, install: resolved };
+}
+export function listInstallNames() {
+    return listCandidates().map((c) => c.name);
+}

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 /**
  * arelos — the Arel OS installer/service manager. `npx arelos` with no subcommand
- * runs the interactive install flow (rlo-cli-spec.md §1).
+ * runs the interactive install flow. 0.2.0 supports multiple named,
+ * self-contained installs on one Mac — status/update/logs/uninstall accept an
+ * optional install name/slug (see cli-context.ts for the resolution rule).
  */
 if (process.platform !== "darwin") {
     console.error("Arel OS currently supports macOS only.");
@@ -9,6 +11,7 @@ if (process.platform !== "darwin") {
 }
 import { parseInstallFlags, parseLogsFlags } from "./cli-args.js";
 import { runInstall } from "./install.js";
+import { listCommand } from "./list.js";
 import { logsCommand } from "./logs.js";
 import { statusCommand } from "./status.js";
 import { uninstallCommand } from "./uninstall.js";
@@ -23,7 +26,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"]);
+    const knownSubcommands = new Set(["install", "status", "update", "uninstall", "logs", "list"]);
     const firstIsFlag = argv.length === 0 || argv[0].startsWith("-");
     const firstIsKnown = argv.length > 0 && knownSubcommands.has(argv[0]);
     if (!firstIsFlag && !firstIsKnown) {
@@ -37,35 +40,64 @@ async function main() {
     switch (subcommand) {
         case "install":
             return runInstall(rest, parseInstallFlags(rest));
+        case "list":
+            return listCommand();
         case "status":
-            return statusCommand();
+            return statusCommand(nameArgFrom(rest));
         case "update":
-            return updateCommand();
+            return updateCommand(nameArgFrom(rest));
         case "uninstall":
-            return uninstallCommand();
+            return uninstallCommand(nameArgFrom(rest));
         case "logs":
-            return logsCommand(parseLogsFlags(rest));
+            return logsCommand(parseLogsFlags(rest), logsNameArgFrom(rest));
         default:
             console.error(`Unknown command: ${subcommand}\n`);
             printHelp();
             return 1;
     }
 }
+/** The first non-flag positional arg, if any — the optional install name/slug. */
+function nameArgFrom(args) {
+    return args.find((a) => !a.startsWith("-")) ?? null;
+}
+/**
+ * `logs` has two possible positionals — the install name and the web/vault
+ * target — in either order. The target is a fixed keyword, so anything else
+ * non-flag (and not `-n`'s own value) is the name.
+ */
+function logsNameArgFrom(args) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith("-")) {
+            if (arg === "-n")
+                i++; // skip -n's value
+            continue;
+        }
+        if (arg === "web" || arg === "vault")
+            continue;
+        return arg;
+    }
+    return null;
+}
 function printHelp() {
     console.log(`arelos — install and manage a self-hosted Arel OS
 
 Usage:
-  npx arelos              Install (interactive)
-  arelos status            Show install + service status
-  arelos update             git pull + rebuild + restart
-  arelos uninstall          Stop services, optionally remove install dir / vault
-  arelos logs [web|vault]   Tail service logs (-f to follow, -n <N> for line count)
+  npx arelos                     Install (interactive)
+  arelos list                     List every install (name, root, ports, status)
+  arelos status [name]            Show install + service status
+  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)
+
+[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.
 
 Install flags (non-interactive):
   --yes, --defaults        Skip prompts, use defaults/flags below
   --display-name <name>
-  --install-dir <path>
-  --vault-path <path>
+  --root <path>             Full override of the resolved install root
+  --parent-dir <path>       Override the parent dir the app's folder is created in
   --web-port <port>
   --vault-port <port>
   --no-service              Skip launchd bootstrap (for dry runs / development)

package/dist/config.js

@@ -1,13 +1,16 @@
 /**
- * rlo's own config read/write helpers — mirrors the shape read by
- * server/config.ts (portability-contract.md §1.1/§1.2). rlo is the writer,
- * the app is the reader; this is the one contract between them.
+ * arelos's own config read/write helpers — mirrors the shape read by
+ * server/config.ts. arelos is the writer, the app is the reader; this is the
+ * one contract between them.
+ *
+ * 0.2.0: config is per-install, at <root>/config.json (see paths.ts
+ * installConfigPath). The old single fixed ~/.arelos/config.json is kept as
+ * a read-only legacy fallback ("unnamed install") for 0.1.x installs.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { configPath, LEGACY_VAULT_LABEL, LEGACY_WEB_LABEL } from "./paths.js";
-export function readConfig() {
-    const p = configPath();
+import { configPathOverride, installConfigPath, legacyConfigPath, LEGACY_VAULT_LABEL, LEGACY_WEB_LABEL, } from "./paths.js";
+function parseConfigFile(p) {
     if (!existsSync(p))
         return null;
     const raw = JSON.parse(readFileSync(p, "utf8"));
@@ -16,13 +19,30 @@ export function readConfig() {
     }
     return raw;
 }
+/** Read the config at a specific known root's config.json. */
+export function readConfigAt(root) {
+    return parseConfigFile(installConfigPath(root));
+}
+/**
+ * Read a single config with no registry context: honors ARELOS_CONFIG_PATH
+ * if set (tests / pointing at one install directly), else falls back to the
+ * legacy fixed ~/.arelos/config.json (pre-0.2.0 "unnamed install"). Used by
+ * callers that haven't gone through the registry (e.g. a bare `arelos status`
+ * when there's exactly one legacy install and no registry entries).
+ */
+export function readConfig() {
+    const override = configPathOverride();
+    if (override)
+        return parseConfigFile(override);
+    return parseConfigFile(legacyConfigPath());
+}
 /**
  * Write config atomically: write to a .tmp sibling then rename over the
- * target. Guarantees a reader never observes a partially written file
- * (spec §3.2 "Config write is last-writer-wins; never partially written").
+ * target. Guarantees a reader never observes a partially written file —
+ * config write is last-writer-wins; never partially written.
  */
-export function writeConfig(config) {
-    const p = configPath();
+export function writeConfig(config, targetPath) {
+    const p = targetPath ?? configPathOverride() ?? (config.root ? installConfigPath(config.root) : legacyConfigPath());
     mkdirSync(dirname(p), { recursive: true });
     const tmp = `${p}.tmp`;
     writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
@@ -31,8 +51,17 @@ export function writeConfig(config) {
 /**
  * The labels to actually operate on for an existing install: config.serviceLabels
  * when present (installs made after this fix), else the legacy fixed labels
- * (installs made before it — backward compat per spec).
+ * (installs made before it — backward compat).
  */
 export function resolveServiceLabels(config) {
     return config.serviceLabels ?? { web: LEGACY_WEB_LABEL, vault: LEGACY_VAULT_LABEL };
 }
+/**
+ * The self-contained root that owns this install's logs/service/ and
+ * config.json (0.2.0 layout). Legacy (pre-0.2.0) configs have no `root` field
+ * — for those, installDir *was* the root (logs lived at installDir/logs),
+ * so fall back to it.
+ */
+export function resolveRoot(config) {
+    return config.root ?? config.installDir;
+}

package/dist/health.js

@@ -1,6 +1,6 @@
 /**
  * HTTP health probes for the vault (`/config`) and web (`/`) services
- * (spec §1 Step 12, §2 rlo status). Pure fetch-based, no deps.
+ * (used by `arelos install` and `arelos status`). Pure fetch-based, no deps.
  */
 async function fetchWithTimeout(url, timeoutMs) {
     const controller = new AbortController();
@@ -56,3 +56,64 @@ export async function waitForHealthy(webPort, vaultPort, opts = {}) {
     }
     return { healthy: false, vault, web };
 }
+export const LOG_SIGNATURE_HINTS = [
+    {
+        pattern: "operation not permitted",
+        hint: "This looks like macOS's TCC privacy protection: background services can't run from " +
+            "Desktop, Documents, Downloads, or iCloud Drive. Move the install to a folder in your home " +
+            "directory (e.g. ~/arelos) and reinstall.",
+    },
+    {
+        pattern: "eaddrinuse",
+        hint: "This looks like a port conflict: another process is already using the configured port. " +
+            "Free the port or re-run install with a different --web-port/--vault-port.",
+    },
+    {
+        pattern: "address already in use",
+        hint: "This looks like a port conflict: another process is already using the configured port. " +
+            "Free the port or re-run install with a different --web-port/--vault-port.",
+    },
+    {
+        pattern: "command not found",
+        hint: "This looks like a missing dependency on PATH inside the launchd environment. Check the service's shebang/interpreter is installed and resolvable without a login shell.",
+    },
+];
+/**
+ * Match a log tail against known failure signatures. Pure string matching,
+ * no I/O — unit-testable without touching disk. Returns null when nothing
+ * recognized matches, so callers can fall back to a generic message.
+ */
+export function matchLogSignature(logTail) {
+    const lower = logTail.toLowerCase();
+    for (const entry of LOG_SIGNATURE_HINTS) {
+        if (lower.includes(entry.pattern))
+            return entry;
+    }
+    return null;
+}
+/**
+ * Build the full health-timeout diagnostic message: last N lines of both
+ * service logs, plus a targeted hint when a known failure signature is
+ * found in either. `readTail` is injected so this stays pure/testable
+ * (no direct fs access) while install.ts/repair.ts wire in the real reader.
+ */
+export function formatHealthTimeoutDiagnostics(logsRoot, readTail, logPathFor) {
+    const webLogPath = logPathFor(logsRoot, "web");
+    const vaultLogPath = logPathFor(logsRoot, "vault");
+    const webTail = readTail(webLogPath);
+    const vaultTail = readTail(vaultLogPath);
+    const hint = matchLogSignature(webTail) ?? matchLogSignature(vaultTail);
+    const lines = [
+        "App did not come up in time.",
+        "",
+        `-- last lines of ${webLogPath} --`,
+        webTail.trim() || "(empty)",
+        "",
+        `-- last lines of ${vaultLogPath} --`,
+        vaultTail.trim() || "(empty)",
+    ];
+    if (hint) {
+        lines.push("", hint.hint);
+    }
+    return lines.join("\n");
+}

package/dist/install-plan.js

@@ -1,17 +1,23 @@
 /**
  * Pure planning/validation logic for the install flow, factored out of the
  * interactive prompt wiring in install.ts so it can be unit tested without
- * a TTY. Each function here validates one prompt's answer per rlo-cli-spec §1.
+ * a TTY. Each function here validates one prompt's answer.
+ *
+ * 0.2.0 self-contained layout: everything for one install lives under a
+ * single `root` folder (`<parent>/<slug>`) — `root/app` (the git checkout),
+ * `root/vault`, `root/logs/service`, and `root/config.json`. `installDir` in
+ * this module and in ArelConfig now specifically means the app checkout
+ * (`root/app`), not the root — see toArelConfig.
  */
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { accessSync, constants } from "node:fs";
-import { dirname } from "node:path";
-import { deriveServiceLabels, expandHome } from "./paths.js";
+import { dirname, join } from "node:path";
+import { deriveServiceLabels, expandHome, isTccProtectedPath } from "./paths.js";
 import { findFreePort, isValidPort } from "./ports.js";
 export const DEFAULTS = {
     displayName: "Arel OS",
-    installDir: "~/ArelOS",
-    vaultPathSuffix: "vault",
+    parentDir: "~",
+    slugFallback: "arelos",
     webPort: 1347,
     vaultPort: 5274,
 };
@@ -19,7 +25,58 @@ export function normalizeDisplayName(input) {
     const trimmed = input.trim();
     return trimmed.length > 0 ? trimmed : DEFAULTS.displayName;
 }
-export function checkInstallDir(rawPath) {
+/**
+ * Slugify a chosen display name into a safe directory-name fragment:
+ * lowercase, spaces/unsafe chars -> dashes, collapsed and trimmed. Falls back
+ * to the fixed default install dir's basename when the slug would be empty
+ * (e.g. a name made entirely of emoji/punctuation).
+ */
+export function slugifyName(input) {
+    return input
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/** Slug fallback when the chosen name slugifies to empty (e.g. all emoji/punctuation). */
+export function slugOrFallback(displayName) {
+    const slug = slugifyName(displayName);
+    return slug || DEFAULTS.slugFallback;
+}
+/** Default parent dir offered for "change location?" — always the home directory. */
+export function defaultParentDir() {
+    return DEFAULTS.parentDir;
+}
+/**
+ * The self-contained root for this install: always `<parent>/<slug>` — we
+ * never install loose into an existing folder, so the slug subfolder is
+ * appended unconditionally, even when the user changes the parent.
+ */
+export function rootFor(parentDir, displayName) {
+    return join(expandHome(parentDir), slugOrFallback(displayName));
+}
+/** installDir (the app checkout) and vaultPath are fixed children of root. */
+export function appDirFor(root) {
+    return join(root, "app");
+}
+export function vaultPathFor(root) {
+    return join(root, "vault");
+}
+/**
+ * Plain-English explanation shown (and re-prompted with) when the chosen
+ * root or vault path resolves to inside a macOS TCC-protected folder
+ * (field bug: launchd-spawned services get `Operation not permitted`,
+ * exit 126, and crash-loop forever from Desktop/Documents/Downloads/iCloud
+ * Drive — see paths.ts isTccProtectedPath).
+ */
+export const TCC_PROTECTED_PATH_MESSAGE = "macOS blocks background services from running in Desktop, Documents, Downloads, or iCloud Drive. Pick a folder in your home directory instead.";
+/**
+ * Validate a candidate self-contained root folder (`<parent>/<slug>`). A
+ * "prior arelos install of the same name" is recognized by the self-contained
+ * layout's own marker — root/app is a git checkout — so re-running the
+ * installer against the same root is a repair, not a collision.
+ */
+export function checkRootDir(rawPath) {
     const path = expandHome(rawPath);
     const parent = dirname(path);
     let parentWritable = true;
@@ -35,12 +92,11 @@ export function checkInstallDir(rawPath) {
     if (exists && statSync(path).isDirectory()) {
         const entries = readdirSync(path);
         nonEmpty = entries.length > 0;
-        isPriorArelosInstall = entries.includes(".git") && entries.includes("package.json");
+        const appDir = join(path, "app");
+        isPriorArelosInstall =
+            existsSync(join(appDir, ".git")) && existsSync(join(appDir, "package.json"));
     }
-    return { path, parentWritable, exists, nonEmpty, isPriorArelosInstall };
-}
-export function defaultVaultPath(installDir) {
-    return `${expandHome(installDir)}/${DEFAULTS.vaultPathSuffix}`;
+    return { path, parentWritable, exists, nonEmpty, isPriorArelosInstall, isTccProtected: isTccProtectedPath(path) };
 }
 /** Validate a chosen port and, if it's taken, propose the next free one. */
 export async function resolvePort(requested) {
@@ -55,14 +111,19 @@ export async function resolvePort(requested) {
     return { requested, resolved: suggestion, wasFree: false };
 }
 export function toArelConfig(answers) {
+    const root = expandHome(answers.root);
     const installDir = expandHome(answers.installDir);
     return {
         version: 1,
         displayName: answers.displayName,
+        root,
         installDir,
         vaultPath: expandHome(answers.vaultPath),
         webPort: answers.webPort,
         vaultPort: answers.vaultPort,
-        serviceLabels: deriveServiceLabels(installDir),
+        // Labels are derived from root, not installDir: root is what's unique
+        // per named install; installDir (root/app) would collide in derivation
+        // only coincidentally, but keying off root is the more direct contract.
+        serviceLabels: deriveServiceLabels(root),
     };
 }