@cydm/happy-elves 0.1.0-beta.68 → 0.1.0-beta.69

package/README.md

@@ -5,7 +5,13 @@ Public beta CLI for Happy Elves.
 ## Hosted relay
 
 ```bash
-happy-elves account create --relay https://relay.happyelves.ai --device-name "CLI" --json
+happy-elves start
+```
+
+Existing workspace recovery uses a one-time invite from Settings → Browsers → Add:
+
+```bash
+happy-elves remote join-controller --url "<invite-url>" --recover-controller --json
 ```
 
 ## Self-host relay

package/apps/cli/dist/commands/account.js

@@ -2,9 +2,10 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
-import { CliError, configDir, configPath, generateAccountSecret, ok, parsePairingStartResponse, randomId, readRelayJson, requireRelayUrl, stopLocalDaemon, throwRelayHttpError, writeConfig } from "./lib/index.js";
+import { CliError, configDir, configPath, generateAccountSecret, ok, parsePairingStartResponse, randomId, readRelayJson, requireRelayUrl, stopLocalDaemon, throwRelayHttpError, withAccountConfigTransaction } from "./lib/index.js";
 const daemonConfigPath = path.join(configDir, "daemon.json");
 const accountConfigFiles = ["config.json", "daemon.json"];
+const accountCreateRelayTimeoutMs = 15_000;
 function accountConfigTarget(file) {
     return file === "config.json" ? configPath : daemonConfigPath;
 }
@@ -83,8 +84,21 @@ async function copyConfigIfPresent(source, target) {
 }
 async function backupAccountConfig(prefix = "account-reset") {
     const stamp = new Date().toISOString().replace(/[:.]/gu, "-");
-    const backupPath = path.join(configDir, "backups", `${prefix}-${stamp}`);
-    await fs.mkdir(backupPath, { recursive: true, mode: 0o700 });
+    const backupsRoot = path.join(configDir, "backups");
+    try {
+        await fs.mkdir(backupsRoot, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const backupsStat = await fs.lstat(backupsRoot);
+    if (!backupsStat.isDirectory() || backupsStat.isSymbolicLink()) {
+        throw new CliError("Refusing to write an account backup through an unsafe backups path.", "CONFIG_BACKUP_UNSAFE");
+    }
+    await fs.chmod(backupsRoot, 0o700);
+    const backupPath = path.join(backupsRoot, `${prefix}-${stamp}-${randomId("backup")}`);
+    await fs.mkdir(backupPath, { mode: 0o700 });
     await fs.chmod(backupPath, 0o700);
     const files = [];
     if (await copyConfigIfPresent(configPath, path.join(backupPath, "config.json")))
@@ -231,43 +245,65 @@ async function applyAccountRestore(staged) {
 }
 export async function handleAccount({ domain, action, flags }) {
     if (domain === "account" && action === "create") {
-        const relayUrl = requireRelayUrl(flags);
-        const deviceId = typeof flags["device-id"] === "string" ? flags["device-id"] : randomId("dev");
-        const deviceName = typeof flags["device-name"] === "string" ? flags["device-name"] : os.hostname();
-        const accountSecret = generateAccountSecret();
-        const response = await fetch(`${relayUrl}/api/pairing/start`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ deviceId, deviceName }),
-        });
-        if (!response.ok) {
-            await throwRelayHttpError(response, "Account creation failed");
-        }
-        const paired = parsePairingStartResponse(await readRelayJson(response, "Account creation response is not valid JSON"));
-        const config = {
-            relayUrl,
-            controllerToken: paired.controllerToken,
-            accountSecret,
-        };
-        await writeConfig(config);
-        ok("account.create", {
-            accountId: paired.accountId,
-            configPath,
-            relayUrl,
-            deviceId,
-            controllerToken: paired.controllerToken,
-            accountSecret,
-            pairingCode: paired.pairingCode,
-            expiresAt: paired.expiresAt,
+        const created = await withAccountConfigTransaction(async (transaction) => {
+            // This check intentionally precedes every relay request. Holding the
+            // account-wide lease through pairing prevents concurrent creators from
+            // producing an orphan remote account and racing the local credential.
+            if (await transaction.controllerExists() || await transaction.daemonExists()) {
+                throw new CliError("Happy Elves account configuration already exists. Use an invite to recover the existing account; account create never replaces credentials.", "CONFIG_EXISTS");
+            }
+            const relayUrl = requireRelayUrl(flags);
+            const deviceId = typeof flags["device-id"] === "string" ? flags["device-id"] : randomId("dev");
+            const deviceName = typeof flags["device-name"] === "string" ? flags["device-name"] : os.hostname();
+            const accountSecret = generateAccountSecret();
+            let response;
+            try {
+                response = await fetch(`${relayUrl}/api/pairing/start`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ deviceId, deviceName }),
+                    signal: AbortSignal.timeout(accountCreateRelayTimeoutMs),
+                });
+            }
+            catch (error) {
+                if (error.name === "TimeoutError") {
+                    throw new CliError("Timed out creating the account at the relay. No local configuration was written.", "RELAY_TIMEOUT");
+                }
+                throw error;
+            }
+            if (!response.ok) {
+                await throwRelayHttpError(response, "Account creation failed");
+            }
+            const paired = parsePairingStartResponse(await readRelayJson(response, "Account creation response is not valid JSON"));
+            const config = {
+                relayUrl,
+                controllerToken: paired.controllerToken,
+                accountSecret,
+            };
+            await transaction.writeController(config, "create");
+            return {
+                accountId: paired.accountId,
+                configPath,
+                relayUrl,
+                deviceId,
+                controllerToken: paired.controllerToken,
+                accountSecret,
+                pairingCode: paired.pairingCode,
+                expiresAt: paired.expiresAt,
+            };
         });
+        ok("account.create", created);
         return true;
     }
     if (domain === "account" && action === "reset") {
         await confirmReset(flags);
         const stop = await requireDaemonStopped();
-        const backup = await backupAccountConfig();
-        await fs.rm(configPath, { force: true });
-        await fs.rm(daemonConfigPath, { force: true });
+        const backup = await withAccountConfigTransaction(async () => {
+            const result = await backupAccountConfig();
+            await fs.rm(configPath, { force: true });
+            await fs.rm(daemonConfigPath, { force: true });
+            return result;
+        });
         ok("account.reset", {
             removed: [configPath, daemonConfigPath],
             backup,
@@ -301,8 +337,11 @@ export async function handleAccount({ domain, action, flags }) {
             const existing = await currentAccountConfigFiles();
             await confirmRestore(flags, files.length === 0 || existing.length > 0);
             const stop = await requireDaemonStopped();
-            const preRestoreBackup = await backupAccountConfig("account-pre-restore");
-            const restored = await applyAccountRestore({ path: staged.path, files });
+            const { preRestoreBackup, restored } = await withAccountConfigTransaction(async () => {
+                const preRestoreBackup = await backupAccountConfig("account-pre-restore");
+                const restored = await applyAccountRestore({ path: staged.path, files });
+                return { preRestoreBackup, restored };
+            });
             ok("account.restore", {
                 backupPath,
                 ...restored,

package/apps/cli/dist/commands/config.js

@@ -1,4 +1,4 @@
-import { configPath, ok, readConfig, redactedControllerConfig, redactedRelayUrl, requireRelayUrl, requireString, wantsJson, writeConfig } from "./lib/index.js";
+import { CliError, configPath, ok, readConfig, redactedControllerConfig, redactedRelayUrl, requireRelayUrl, requireString, wantsJson, withAccountConfigTransaction } from "./lib/index.js";
 export async function handleConfig({ domain, action, flags }) {
     if (domain === "config" && action === "init") {
         const config = {
@@ -6,7 +6,15 @@ export async function handleConfig({ domain, action, flags }) {
             controllerToken: requireString(flags, "token"),
             accountSecret: requireString(flags, "secret"),
         };
-        await writeConfig(config);
+        await withAccountConfigTransaction(async (transaction) => {
+            if (await transaction.controllerExists()) {
+                throw new CliError("Controller configuration already exists. config init never replaces credentials.", "CONFIG_EXISTS");
+            }
+            if (await transaction.daemonExists()) {
+                throw new CliError("A daemon configuration already exists. Recover a controller with a same-account invite instead of creating an unverifiable split configuration.", "CONFIG_SPLIT_BRAIN");
+            }
+            await transaction.writeController(config, "create");
+        });
         ok("config.init", { path: configPath, relayUrl: redactedRelayUrl(config.relayUrl) });
         return true;
     }

package/apps/cli/dist/commands/daemon.js

@@ -1,6 +1,7 @@
+import { createHash, timingSafeEqual } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
-import { assertLocalDaemonVerified, CliError, compactText, ControllerClient, configDir, configPath, daemonPidPath, deriveOrchestration, idleSessionStatuses, localDaemonStatus, ok, parsePairingClaimResponse, randomId, readConfig, readDaemonConfig, readLocalAuditLog, readRelayJson, redactedDaemonConfig, requirePositional, requireRelayUrl, requireString, showMachine, spawnDaemonStart, stopLocalDaemon, throwRelayHttpError, wantsJson, writeDaemonConfig } from "./lib/index.js";
+import { assertLocalDaemonVerified, cliErrorFromFetch, CliError, compactText, ControllerClient, configDir, configPath, daemonPidPath, deriveOrchestration, diagnoseInstallation, emitDoctorResult, idleSessionStatuses, localDaemonStatus, normalizeRelayUrl, ok, parsePairingClaimResponse, randomId, readConfig, readDaemonConfig, readLocalAuditLog, readRelayJson, redactedDaemonConfig, requirePositional, requireRelayUrl, requireString, showMachine, spawnDaemonStart, stopLocalDaemon, throwRelayHttpError, wantsJson, withAccountConfigTransaction } from "./lib/index.js";
 function positiveLimit(flags, fallback) {
     const value = flags.limit;
     if (value === undefined)
@@ -96,58 +97,57 @@ export async function handleDaemon({ domain, action, flags }) {
         const accountSecret = requireString(flags, "secret");
         const machineName = typeof flags.name === "string" && flags.name.trim() ? flags.name.trim() : os.hostname();
         const machineId = typeof flags["machine-id"] === "string" ? flags["machine-id"] : randomId("mach");
-        const response = await fetch(`${relayUrl}/api/pairing/claim`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ code, machineId }),
+        let daemonConfig;
+        await withAccountConfigTransaction(async (transaction) => {
+            if (await transaction.daemonExists()) {
+                throw new CliError(`Daemon configuration already exists at ${transaction.daemonPath}. Pairing never replaces an existing machine identity; use an explicit account recovery or migration flow.`, "CONFIG_EXISTS");
+            }
+            const existingController = await transaction.readController();
+            if (existingController && (canonicalPairRelay(existingController.relayUrl) !== canonicalPairRelay(relayUrl) ||
+                !pairSecretsEqual(existingController.accountSecret, accountSecret))) {
+                throw new CliError("Daemon pairing does not match the existing controller relay/account. No relay request was sent and no configuration was changed.", "CONFIG_SPLIT_BRAIN");
+            }
+            let response;
+            try {
+                response = await fetch(`${relayUrl}/api/pairing/claim`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ code, machineId }),
+                    signal: AbortSignal.timeout(10_000),
+                });
+            }
+            catch (error) {
+                if (error.name === "TimeoutError" || error.name === "AbortError") {
+                    throw new CliError("Pairing claim timed out; daemon configuration was not changed.", "PAIRING_TIMEOUT");
+                }
+                throw cliErrorFromFetch(error, "RELAY_UNREACHABLE", `Could not reach relay while pairing ${relayUrl}`);
+            }
+            if (!response.ok) {
+                await throwRelayHttpError(response, "Pairing failed");
+            }
+            const claimed = parsePairingClaimResponse(await readRelayJson(response, "Pairing response is not valid JSON"));
+            daemonConfig = {
+                relayUrl,
+                accountId: claimed.accountId,
+                machineId: claimed.machineId,
+                machineName,
+                machineToken: claimed.machineToken,
+                accountSecret,
+            };
+            await transaction.writeDaemon(daemonConfig, "create");
         });
-        if (!response.ok) {
-            await throwRelayHttpError(response, "Pairing failed");
-        }
-        const claimed = parsePairingClaimResponse(await readRelayJson(response, "Pairing response is not valid JSON"));
-        const daemonConfig = {
-            relayUrl,
-            accountId: claimed.accountId,
-            machineId: claimed.machineId,
-            machineName,
-            machineToken: claimed.machineToken,
-            accountSecret,
-        };
-        const daemonConfigPath = await writeDaemonConfig(daemonConfig);
+        if (!daemonConfig)
+            throw new CliError("Pairing did not produce daemon configuration", "PAIRING_FAILED");
         ok("daemon.pair", {
-            path: daemonConfigPath,
+            path: path.join(configDir, "daemon.json"),
             config: redactedDaemonConfig(daemonConfig),
         });
         return true;
     }
     if (domain === "daemon" && action === "doctor") {
-        const checks = [];
-        let config;
-        try {
-            config = await readConfig(flags);
-            checks.push({ name: "config", ok: true, message: configPath });
-        }
-        catch (error) {
-            checks.push({ name: "config", ok: false, message: error instanceof Error ? error.message : String(error) });
-        }
-        if (config) {
-            try {
-                const response = await fetch(`${config.relayUrl}/health`);
-                checks.push({ name: "relay", ok: response.ok, message: response.ok ? "reachable" : await response.text() });
-            }
-            catch (error) {
-                checks.push({ name: "relay", ok: false, message: error instanceof Error ? error.message : String(error) });
-            }
-        }
-        const data = { ok: checks.every((check) => check.ok), checks };
-        if (!wantsJson(flags)) {
-            console.log(`Daemon doctor: ${data.ok ? "ok" : "issues found"}`);
-            for (const check of checks) {
-                console.log(`${check.ok ? "ok" : "fail"} ${check.name}: ${check.message}`);
-            }
-            return true;
-        }
-        ok("daemon.doctor", data);
+        const requestedRelay = typeof flags.relay === "string" ? flags.relay : undefined;
+        const data = await diagnoseInstallation("daemon", requestedRelay);
+        emitDoctorResult("daemon.doctor", "Daemon doctor", data, flags);
         return true;
     }
     if (domain === "daemon" && action === "config") {
@@ -203,13 +203,21 @@ export async function handleDaemon({ domain, action, flags }) {
         const status = await localDaemonStatus();
         assertLocalDaemonVerified(status);
         if (status.running) {
-            ok("daemon.start", { ...status, started: false });
+            const data = { ...status, started: false };
+            if (wantsJson(flags))
+                ok("daemon.start", data);
+            else
+                writeHumanDaemonStartOutput(data);
             return true;
         }
         await readDaemonConfig();
         const startArgs = typeof flags.relay === "string" ? ["--relay", flags.relay] : [];
         const pid = spawnDaemonStart(startArgs);
-        ok("daemon.start", { pid, pidPath: daemonPidPath, started: true });
+        const data = { pid, pidPath: daemonPidPath, started: true };
+        if (wantsJson(flags))
+            ok("daemon.start", data);
+        else
+            writeHumanDaemonStartOutput(data);
         return true;
     }
     if (domain === "daemon" && action === "stop") {
@@ -338,3 +346,23 @@ export async function handleDaemon({ domain, action, flags }) {
     }
     return false;
 }
+function canonicalPairRelay(value) {
+    const url = new URL(value);
+    url.hash = "";
+    return normalizeRelayUrl(url.toString());
+}
+function pairSecretsEqual(left, right) {
+    const leftDigest = createHash("sha256").update(left).digest();
+    const rightDigest = createHash("sha256").update(right).digest();
+    return timingSafeEqual(leftDigest, rightDigest);
+}
+function writeHumanDaemonStartOutput(data) {
+    if (data.started) {
+        console.log(`Daemon start requested${data.pid ? ` (pid ${data.pid})` : ""}.`);
+    }
+    else {
+        console.log(`Daemon is already running${data.pid ? ` (pid ${data.pid})` : ""}.`);
+    }
+    console.log("This command manages only the paired background daemon; it does not open a browser page.");
+    console.log("For setup or browser onboarding, run: happy-elves start");
+}

package/apps/cli/dist/commands/lib/args.js

@@ -127,6 +127,7 @@ const booleanFlags = new Set([
     "repair-head",
     "reaction-disabled",
     "reaction-enabled",
+    "recover-controller",
     "require-mention",
     "respond-all",
     "summary",

package/apps/cli/dist/commands/lib/bootstrap-config.d.ts

@@ -1,28 +1,41 @@
 import type { CliConfig, DaemonConfig } from "./types.js";
-export type ConfigBackup = {
-    path: string;
-    backupPath: string;
-    reason: string;
+import { type AccountConfigTransaction } from "./config.js";
+export type StartConfigPreflight = {
+    kind: "fresh" | "controller-only" | "ready";
+    relayUrl: string;
+    explicitRelay: boolean;
+    controller?: CliConfig;
+    daemon?: DaemonConfig;
 };
+/**
+ * Read and classify both local identities before `start` performs any network
+ * request or mutates either config. A controller and daemon are one workspace
+ * only when both their relay and account secret match; `start` is deliberately
+ * not an account-migration command.
+ */
+export declare function readStartConfigPreflight(flags: Record<string, string | boolean>, transaction?: AccountConfigTransaction): Promise<StartConfigPreflight>;
+export declare function classifyStartConfig(params: {
+    controller?: CliConfig;
+    daemon?: DaemonConfig;
+    explicitRelayUrl?: string;
+}): StartConfigPreflight;
 export declare function ensureControllerConfig(params: {
     relayUrl: string;
     explicitRelay: boolean;
     deviceName: string;
+    existing?: CliConfig;
+    transaction: AccountConfigTransaction;
+    deferWrite?: boolean;
+    signal?: AbortSignal;
 }): Promise<{
     config: CliConfig;
     created: boolean;
     accountId?: string;
-    backup?: ConfigBackup;
-    reconfigured: boolean;
+    reconfigured: false;
 }>;
-export declare function ensureDaemonPaired(config: CliConfig, machineName: string): Promise<{
+export declare function ensureDaemonPaired(config: CliConfig, machineName: string, existing: DaemonConfig | undefined, transaction: AccountConfigTransaction, deferWrite?: boolean, signal?: AbortSignal, expectedAccountId?: string): Promise<{
     config: DaemonConfig;
     created: boolean;
-    backup?: ConfigBackup;
-    reconfigured: boolean;
+    reconfigured: false;
 }>;
 export declare function controllerBaseUrl(flags: Record<string, string | boolean>): string;
-export declare function startRelayUrl(flags: Record<string, string | boolean>, existing?: CliConfig): {
-    relayUrl: string;
-    explicit: boolean;
-};