arelos 0.1.0

package/dist/install.js

@@ -0,0 +1,292 @@
+/**
+ * Interactive + non-interactive install flow (rlo-cli-spec.md §1).
+ * Steps are numbered in comments to match the spec exactly.
+ */
+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 { runStreaming } from "./exec.js";
+import { waitForHealthy } from "./health.js";
+import { checkInstallDir, defaultVaultPath, DEFAULTS, normalizeDisplayName, resolvePort, toArelConfig, } 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 } from "./paths.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;
+    p.intro(pc.bold("Arel OS — your personal life-OS, self-hosted on your Mac."));
+    if (!flags.yes) {
+        p.log.message("This installs Arel OS to a folder, runs two background services, and opens it in your browser.\nMIT licensed. Everything stays local on this Mac.");
+    }
+    const answers = await collectAnswers(flags);
+    if (answers === null) {
+        p.cancel("Install cancelled.");
+        return 1;
+    }
+    if (!flags.yes) {
+        p.note([
+            `Name:        ${answers.displayName}`,
+            `Install dir: ${answers.installDir}`,
+            `Vault path:  ${answers.vaultPath}`,
+            `Web port:    ${answers.webPort}`,
+            `Vault port:  ${answers.vaultPort}`,
+        ].join("\n"), "Summary");
+        const proceed = await p.confirm({ message: "Proceed with install?", initialValue: true });
+        if (p.isCancel(proceed) || !proceed) {
+            p.cancel("Install cancelled.");
+            return 1;
+        }
+    }
+    // Step 7 — Install Bun if missing.
+    const bunSpin = spinner(flags.yes);
+    bunSpin.start("Checking for Bun…");
+    const bunResult = await ensureBun();
+    if ("error" in bunResult) {
+        bunSpin.stop("Bun setup failed.");
+        console.error(pc.red(bunResult.error));
+        return 1;
+    }
+    bunSpin.stop(`Bun ready (${bunResult.bunBin}).`);
+    // Step 8 — Get the app source.
+    const installDir = answers.installDir;
+    if (isGitCheckout(installDir)) {
+        log(flags.yes, `Existing checkout found at ${installDir}; skipping clone.`);
+    }
+    else {
+        const cloneSpin = spinner(flags.yes);
+        cloneSpin.start(`Cloning app source into ${installDir}…`);
+        const cloneRes = await cloneRepo(installDir, { sourcePath: flags.localRepo ?? undefined });
+        if (cloneRes.code !== 0) {
+            cloneSpin.stop("Clone failed.");
+            console.error(pc.red(cloneRes.stderr));
+            return 1;
+        }
+        cloneSpin.stop("App source cloned.");
+    }
+    // Step 9 — Build + scaffold.
+    const buildSpin = spinner(flags.yes);
+    buildSpin.start("Installing dependencies (bun install)…");
+    const installRes = await runStreaming(bunResult.bunBin, ["install"], { cwd: installDir });
+    if (installRes.code !== 0) {
+        buildSpin.stop("bun install failed.");
+        return 1;
+    }
+    buildSpin.stop("Dependencies installed.");
+    const buildSpin2 = spinner(flags.yes);
+    buildSpin2.start("Building the app (bun run build)…");
+    const buildRes = await runStreaming(bunResult.bunBin, ["run", "build"], { cwd: installDir });
+    if (buildRes.code !== 0) {
+        buildSpin2.stop("Build failed — services will not be registered.");
+        return 1;
+    }
+    buildSpin2.stop("Build complete.");
+    try {
+        const scaffoldResult = scaffoldVault(installDir, answers.vaultPath);
+        log(flags.yes, scaffoldResult.copied
+            ? `Vault scaffolded at ${answers.vaultPath}.`
+            : `Vault at ${answers.vaultPath} already has content; left untouched.`);
+    }
+    catch (err) {
+        if (err instanceof TemplateVaultMissingError) {
+            console.error(pc.red(err.message));
+            return 1;
+        }
+        throw err;
+    }
+    ensureLogsDir(installDir);
+    const envResult = ensureEnvFile(installDir);
+    log(flags.yes, envResult.created ? "Wrote .env from .env.example." : ".env already present; left untouched.");
+    // Step 10 — Write config.
+    const config = toArelConfig(answers);
+    writeConfig(config);
+    log(flags.yes, `Config written to ${configPath()}.`);
+    if (flags.noService) {
+        log(flags.yes, "Skipping launchd bootstrap (--no-service).");
+        p.outro(pc.green("Dry-run install complete (no services started)."));
+        return 0;
+    }
+    // Step 11 — Generate + bootstrap launchd services.
+    const svcSpin = spinner(flags.yes);
+    svcSpin.start("Registering background services…");
+    installServiceFiles(installDir);
+    const bootstrapResult = await bootstrapAndStart();
+    if (bootstrapResult.errors.length > 0) {
+        svcSpin.stop("Service registration had errors.");
+        for (const e of bootstrapResult.errors)
+            console.error(pc.yellow(e));
+    }
+    else {
+        svcSpin.stop("Services registered and started.");
+    }
+    // Step 12 — Health check.
+    const healthSpin = spinner(flags.yes);
+    healthSpin.start("Waiting for the app to come up (building the dashboard…)");
+    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")}`));
+        return 1;
+    }
+    healthSpin.stop("App is up.");
+    // Step 13 — Open browser.
+    const url = `http://localhost:${config.webPort}`;
+    if (!flags.yes) {
+        try {
+            await runStreaming("open", [url]);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    p.outro([
+        pc.green(`Arel OS is running at ${url}`),
+        "Runs 24/7 in the background.",
+        "Next: arelos status · arelos logs · arelos update · arelos uninstall",
+    ].join("\n"));
+    return 0;
+}
+async function checkGit() {
+    const { commandExists } = await import("./exec.js");
+    if (commandExists("git"))
+        return true;
+    console.error("git is required but was not found. Install Xcode Command Line Tools:\n  xcode-select --install");
+    return false;
+}
+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 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,
+            installDir,
+            vaultPath,
+            webPort: web.resolved,
+            vaultPort: vault.resolved,
+        };
+    }
+    // Step 2 — Name your system.
+    const displayNameRaw = await p.text({
+        message: "What should we call your system?",
+        placeholder: DEFAULTS.displayName,
+        defaultValue: DEFAULTS.displayName,
+    });
+    if (p.isCancel(displayNameRaw))
+        return null;
+    // Step 3 — Install location.
+    let installDir = "";
+    for (;;) {
+        const raw = await p.text({
+            message: "Where should Arel OS be installed?",
+            placeholder: DEFAULTS.installDir,
+            defaultValue: DEFAULTS.installDir,
+        });
+        if (p.isCancel(raw))
+            return null;
+        const check = checkInstallDir(String(raw || DEFAULTS.installDir));
+        if (!check.parentWritable) {
+            p.log.error(`Cannot write to ${check.path} — choose another location.`);
+            continue;
+        }
+        if (check.nonEmpty && !check.isPriorArelosInstall) {
+            const proceed = await p.confirm({
+                message: `${check.path} exists and is not empty. Use it anyway?`,
+                initialValue: false,
+            });
+            if (p.isCancel(proceed) || !proceed)
+                continue;
+        }
+        installDir = 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,
+    };
+}
+async function promptPort(message, defaultPort) {
+    let candidate = defaultPort;
+    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))
+            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;
+            continue;
+        }
+        return parsed;
+    }
+}
+function spinner(quiet) {
+    if (quiet) {
+        return {
+            start: (msg) => console.log(msg),
+            stop: (msg) => console.log(msg),
+        };
+    }
+    return p.spinner();
+}
+function log(quiet, msg) {
+    if (quiet)
+        console.log(msg);
+    else
+        p.log.message(msg);
+}

package/dist/launchd.js

@@ -0,0 +1,46 @@
+/**
+ * launchctl wrapper (modern per-GUI-domain bootstrap/bootout/kickstart API).
+ * Every op is idempotent per spec §3.2: bootout-then-bootstrap never errors
+ * on "already loaded"; a --no-service dry run skips all of this.
+ */
+import { userInfo } from "node:os";
+import { runCapture } from "./exec.js";
+import { plistPath } from "./paths.js";
+function uid() {
+    return userInfo().uid;
+}
+function guiDomain() {
+    return `gui/${uid()}`;
+}
+export async function bootoutService(label) {
+    // Ignore errors — idempotent "unload if loaded".
+    await runCapture("launchctl", ["bootout", `${guiDomain()}/${label}`]);
+}
+export async function bootstrapService(label) {
+    await bootoutService(label);
+    const res = await runCapture("launchctl", ["bootstrap", guiDomain(), plistPath(label)]);
+    return { ok: res.code === 0, stderr: res.stderr };
+}
+export async function kickstartService(label) {
+    const res = await runCapture("launchctl", ["kickstart", "-k", `${guiDomain()}/${label}`]);
+    return { ok: res.code === 0, stderr: res.stderr };
+}
+/** Best-effort parse of `launchctl list | grep com.arelos`. */
+export async function getServiceStatus(label) {
+    const res = await runCapture("launchctl", ["list"]);
+    const line = res.stdout.split("\n").find((l) => l.trim().endsWith(label));
+    if (!line)
+        return { label, loaded: false, pid: null, lastExitCode: null };
+    const parts = line.trim().split(/\s+/);
+    const pidRaw = parts[0];
+    const exitRaw = parts[1];
+    return {
+        label,
+        loaded: true,
+        pid: pidRaw === "-" ? null : Number(pidRaw),
+        lastExitCode: exitRaw === "-" ? null : Number(exitRaw),
+    };
+}
+export function guiDomainForTest() {
+    return guiDomain();
+}

package/dist/logs.js

@@ -0,0 +1,42 @@
+/**
+ * `rlo logs` (spec §2). Tails <installDir>/logs/service/{web,vault}.log.
+ */
+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`);
+}
+export function lastLines(filePath, n) {
+    if (!existsSync(filePath))
+        return `(no log file at ${filePath})\n`;
+    const content = readFileSync(filePath, "utf8");
+    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.");
+        return 1;
+    }
+    const targets = flags.which === "both" ? ["web", "vault"] : [flags.which];
+    const paths = targets.map((t) => logPathFor(config.installDir, t));
+    if (flags.follow) {
+        const existing = paths.filter((p) => existsSync(p));
+        if (existing.length === 0) {
+            console.error("No log files found yet.");
+            return 1;
+        }
+        const child = spawn("tail", ["-f", ...existing], { stdio: "inherit" });
+        await new Promise((resolve) => child.on("close", resolve));
+        return 0;
+    }
+    for (const [i, target] of targets.entries()) {
+        if (targets.length > 1)
+            console.log(`\n==> ${target} <==`);
+        console.log(lastLines(paths[i], flags.lines));
+    }
+    return 0;
+}

package/dist/paths.js

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function configPath() {
+    return process.env.ARELOS_CONFIG_PATH ?? join(homedir(), ".arelos", "config.json");
+}
+export function configDir() {
+    return join(configPath(), "..");
+}
+export function launchAgentsDir() {
+    return join(homedir(), "Library", "LaunchAgents");
+}
+export const WEB_LABEL = "com.arelos.web";
+export const VAULT_LABEL = "com.arelos.vault";
+export function plistPath(label) {
+    return join(launchAgentsDir(), `${label}.plist`);
+}
+/** Expand a leading `~` to the user's home directory. */
+export function expandHome(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/"))
+        return join(homedir(), p.slice(2));
+    return p;
+}

package/dist/plist.js

@@ -0,0 +1,17 @@
+/**
+ * Plist template rendering (portability-contract.md §3.1). Templates ship at
+ * `scripts/service/com.arelos.{web,vault}.plist.tmpl` in the app repo and
+ * take a single {{INSTALL_DIR}} token — 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) {
+    return template.split("{{INSTALL_DIR}}").join(installDir);
+}
+/** 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) {
+    return (xml.includes("<?xml") &&
+        xml.includes("<!DOCTYPE plist") &&
+        xml.includes("<plist") &&
+        xml.includes("</plist>") &&
+        !xml.includes("{{"));
+}

package/dist/ports.js

@@ -0,0 +1,41 @@
+/**
+ * Zero-dependency free-port detection via node:net (spec §1 Step 5).
+ */
+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) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", (err) => {
+            server.close();
+            if (err.code === "EADDRINUSE" || err.code === "EACCES") {
+                resolve(false);
+            }
+            else {
+                // Unexpected error probing the port — treat conservatively as taken
+                // so we never suggest a port we can't actually validate.
+                resolve(false);
+            }
+        });
+        server.once("listening", () => {
+            server.close(() => resolve(true));
+        });
+        server.listen(port, "127.0.0.1");
+    });
+}
+/**
+ * Find the first free port at or above `start`, scanning upward. Stops at
+ * `start + maxScan` to avoid an unbounded loop.
+ */
+export async function findFreePort(start, maxScan = 200) {
+    for (let port = start; port < start + maxScan; port++) {
+        if (port <= 1023)
+            continue;
+        if (await isPortFree(port))
+            return port;
+    }
+    throw new Error(`No free port found in range ${start}-${start + maxScan}`);
+}
+export function isValidPort(port) {
+    return Number.isInteger(port) && port > 1023 && port <= 65535;
+}

package/dist/repair.js

@@ -0,0 +1,79 @@
+/**
+ * Existing-install repair/update menu (spec §1 Step 0, §3.1). Shown whenever
+ * ~/.arelos/config.json already exists so a re-run of `npx arelos` never
+ * silently reinstalls.
+ */
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { runUpdate } from "./update.js";
+import { waitForHealthy } from "./health.js";
+import { bootstrapAndStart, installServiceFiles } from "./services.js";
+import { runStreaming } from "./exec.js";
+import { ensureBun } from "./bun-setup.js";
+export async function runRepairMenu(existing) {
+    p.intro(pc.bold("Existing Arel OS install detected"));
+    p.note([
+        `Name:        ${existing.displayName}`,
+        `Install dir: ${existing.installDir}`,
+        `Vault path:  ${existing.vaultPath}`,
+        `Web port:    ${existing.webPort}`,
+        `Vault port:  ${existing.vaultPort}`,
+    ].join("\n"), "Detected install");
+    const choice = await p.select({
+        message: "What would you like to do?",
+        options: [
+            { value: "update", label: "Update", hint: "git pull + rebuild + restart" },
+            { value: "repair", label: "Repair", hint: "re-render services + rebuild, keep vault & config" },
+            { value: "reinstall", label: "Reinstall elsewhere", hint: "fresh install at a new location" },
+            { value: "cancel", label: "Cancel" },
+        ],
+    });
+    if (p.isCancel(choice) || choice === "cancel") {
+        p.cancel("Cancelled.");
+        return 1;
+    }
+    if (choice === "update") {
+        return runUpdate(existing);
+    }
+    if (choice === "repair") {
+        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.");
+        return 0;
+    }
+    return 1;
+}
+async function runRepair(existing) {
+    const s = p.spinner();
+    s.start("Ensuring Bun…");
+    const bunResult = await ensureBun();
+    if ("error" in bunResult) {
+        s.stop("Bun check failed.");
+        console.error(pc.red(bunResult.error));
+        return 1;
+    }
+    s.stop("Bun ready.");
+    s.start("Reinstalling dependencies and rebuilding…");
+    const installRes = await runStreaming(bunResult.bunBin, ["install"], { cwd: existing.installDir });
+    const buildRes = installRes.code === 0
+        ? await runStreaming(bunResult.bunBin, ["run", "build"], { cwd: existing.installDir })
+        : installRes;
+    if (buildRes.code !== 0) {
+        s.stop("Build failed.");
+        return 1;
+    }
+    s.stop("Rebuilt.");
+    s.start("Re-rendering and re-bootstrapping services…");
+    installServiceFiles(existing.installDir);
+    const bootstrap = await bootstrapAndStart();
+    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.");
+    return health.healthy ? 0 : 1;
+}

package/dist/repo.js

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { runCapture, runStreaming } from "./exec.js";
+export const DEFAULT_REPO_URL = "https://github.com/vishmathpati/arel-os";
+export const DEFAULT_BRANCH = "main";
+export function isGitCheckout(dir) {
+    return existsSync(join(dir, ".git"));
+}
+/**
+ * Get the app source into installDir. If installDir is already a git
+ * checkout (existing install / repair), this is a no-op — caller should use
+ * `pullLatest` instead. Otherwise clones fresh.
+ *
+ * `sourcePath` (the --local-repo override) copies a local working tree via
+ * `git clone <local path>` instead of hitting GitHub — this keeps `git`
+ * semantics (still a real .git checkout, `git pull` still works against the
+ * local origin) while avoiding a network dependency in dev/dry-run.
+ */
+export async function cloneRepo(installDir, opts = {}) {
+    const source = opts.sourcePath ?? opts.repoUrl ?? DEFAULT_REPO_URL;
+    const args = ["clone", "--depth", "1", "--branch", opts.branch ?? DEFAULT_BRANCH, source, installDir];
+    const res = await runStreaming("git", args);
+    return { code: res.code, stderr: res.stderr };
+}
+export async function pullLatest(installDir) {
+    const statusRes = await runCapture("git", ["-C", installDir, "status", "--porcelain"]);
+    const dirty = statusRes.stdout.trim().length > 0;
+    if (dirty) {
+        return { code: 1, dirty: true, stderr: "working tree has uncommitted changes" };
+    }
+    const res = await runStreaming("git", ["-C", installDir, "pull", "--ff-only"]);
+    return { code: res.code, dirty: false, stderr: res.stderr };
+}
+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). */
+export async function isBehindOrigin(installDir) {
+    const fetchRes = await runCapture("git", ["-C", installDir, "fetch", "--dry-run"]);
+    if (fetchRes.code !== 0)
+        return null;
+    const countRes = await runCapture("git", ["-C", installDir, "rev-list", "--count", "HEAD..@{u}"]);
+    if (countRes.code !== 0)
+        return null;
+    const count = Number(countRes.stdout.trim());
+    return Number.isFinite(count) ? count > 0 : null;
+}

package/dist/scaffold.js

@@ -0,0 +1,54 @@
+/**
+ * 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).
+ */
+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.`);
+        this.name = "TemplateVaultMissingError";
+    }
+}
+export function isDirEmpty(dir) {
+    if (!existsSync(dir))
+        return true;
+    return readdirSync(dir).length === 0;
+}
+/**
+ * Copy templates/vault/** from the cloned app repo into vaultPath, only if
+ * vaultPath is empty/absent. Throws TemplateVaultMissingError if the source
+ * template is absent in the repo (hard error per spec §3.3).
+ */
+export function scaffoldVault(installDir, vaultPath) {
+    const templateDir = join(installDir, "templates", "vault");
+    if (!existsSync(templateDir)) {
+        throw new TemplateVaultMissingError(templateDir);
+    }
+    if (!isDirEmpty(vaultPath)) {
+        return { copied: false };
+    }
+    mkdirSync(vaultPath, { recursive: true });
+    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");
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/** Write .env from .env.example if absent; never overwrite an existing .env. */
+export function ensureEnvFile(installDir) {
+    const envPath = join(installDir, ".env");
+    const examplePath = join(installDir, ".env.example");
+    if (existsSync(envPath))
+        return { created: false };
+    if (!existsSync(examplePath))
+        return { created: false };
+    cpSync(examplePath, envPath);
+    return { created: true };
+}