@ouro.bot/cli 0.1.0-alpha.83 → 0.1.0-alpha.831

package/dist/repertoire/unraid-restart.js

@@ -0,0 +1,339 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SANCTUARY_RESTART_MUTATION = void 0;
+exports.createApprovedUnraidRestartExecutor = createApprovedUnraidRestartExecutor;
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+const unraid_client_1 = require("./unraid-client");
+const router_1 = require("../heart/external-events/router");
+exports.SANCTUARY_RESTART_MUTATION = `mutation SanctuaryRestart($id: PrefixedID!) {
+  docker { restart(id: $id) { id names state status autoStart } }
+}`;
+class RoutineActionReceiptError extends Error {
+    constructor(cause) {
+        super("routine action receipt persistence failed", { cause });
+        this.name = "RoutineActionReceiptError";
+    }
+}
+function failure(code, message) {
+    return { ok: false, error: { code, message: message.slice(0, 500), degraded: true } };
+}
+function exactTarget(result, name) {
+    if (!result.ok)
+        return failure("invalid_response", result.error.message);
+    const matches = result.data.containers.filter((container) => container.name === name);
+    if (matches.length === 0)
+        return failure("not_found", `container '${name}' was not found`);
+    if (matches.length !== 1)
+        return failure("ambiguous", `container '${name}' is ambiguous`);
+    return matches[0];
+}
+function validArgument(value) {
+    return typeof value === "string" && value.length > 0 && Buffer.byteLength(value, "utf8") <= 128 && !value.includes("\uFFFD");
+}
+async function currentRoutineAuthorization(authority) {
+    let authorization;
+    try {
+        authorization = await authority.reauthorize();
+    }
+    catch {
+        throw new Error("routine relationship authorization is unavailable");
+    }
+    if (!authorization.allowed)
+        throw new Error(authorization.reason);
+    if (!authorization.receiptId.trim() || !Number.isInteger(authorization.profileVersion) || authorization.profileVersion < 1) {
+        throw new Error("routine relationship authorization is not versioned");
+    }
+    return { receiptId: authorization.receiptId, profileVersion: authorization.profileVersion };
+}
+function acknowledgedIdentity(data, target) {
+    const docker = data.docker;
+    if (!docker || typeof docker !== "object" || Array.isArray(docker))
+        return false;
+    const restart = docker.restart;
+    if (!restart || typeof restart !== "object" || Array.isArray(restart))
+        return false;
+    const record = restart;
+    return record.id === target.id && Array.isArray(record.names)
+        && record.names.length === 1 && String(record.names[0]).replace(/^\//u, "") === target.name;
+}
+function createApprovedUnraidRestartExecutor(options) {
+    const createClient = options.createClient ?? ((input) => new unraid_client_1.UnraidClient(input));
+    const sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    const now = options.now ?? (() => new Date());
+    const observationTimeoutMs = options.observationTimeoutMs ?? 30_000;
+    const transitionRoutine = (input) => {
+        try {
+            options.transitionRoutineAction?.(input);
+        }
+        catch (error) {
+            throw new RoutineActionReceiptError(error);
+        }
+    };
+    return async (args, execution) => {
+        if (!validArgument(args.container))
+            return failure("invalid_response", "container must be one bounded exact name");
+        const routine = execution?.routine;
+        const approvalInput = execution?.approval;
+        if (execution && Object.hasOwn(execution, "approval") && (!approvalInput || typeof approvalInput.reauthorize !== "function"
+            || !validArgument(approvalInput.target?.id) || approvalInput.target.id !== approvalInput.target.id.trim()
+            || approvalInput.target.name !== args.container))
+            return failure("invalid_response", "restart approval authority is invalid");
+        const approvalAuthority = approvalInput && { target: { ...approvalInput.target }, reauthorize: approvalInput.reauthorize };
+        if (approvalAuthority && routine)
+            return failure("invalid_response", "restart has conflicting approval and routine authority");
+        const resolved = exactTarget(await options.listContainers(), args.container);
+        if ("ok" in resolved)
+            return resolved;
+        const fresh = exactTarget(await options.listContainers(), args.container);
+        if ("ok" in fresh)
+            return fresh;
+        if (fresh.id !== resolved.id)
+            return failure("stale_target", "container identity changed before restart");
+        let routineAuthorization = null;
+        if (routine) {
+            try {
+                routineAuthorization = await currentRoutineAuthorization(routine);
+            }
+            catch (error) {
+                return failure("stale_target", error instanceof Error ? error.message : "routine relationship authorization is unavailable");
+            }
+        }
+        const scenarioHandleDigest = options.acceptanceScenarioHandleDigest?.();
+        const approval = options.acceptanceApproval?.();
+        const attempt = {
+            container: { id: fresh.id, name: fresh.name },
+            beforeState: fresh.state,
+            observedAt: now().toISOString(),
+            actionDigest: (0, node_crypto_1.createHash)("sha256").update(JSON.stringify({ operation: "restart", container: { id: fresh.id, name: fresh.name } })).digest("hex"),
+            argumentDigest: (0, node_crypto_1.createHash)("sha256").update(JSON.stringify({ container: args.container })).digest("hex"),
+            ...(scenarioHandleDigest ? { scenarioHandleDigest } : {}),
+            ...(approval ? { approvalId: approval.approvalId } : {}),
+            attemptId: (0, node_crypto_1.randomUUID)(),
+            mutationAcknowledged: false,
+            afterState: null,
+        };
+        let routineReceipt = null;
+        const routineState = { current: null };
+        if (routine) {
+            if (!options.reserveRoutineAction || !options.transitionRoutineAction || !options.withRoutineActionAttempt)
+                return failure("invalid_response", "routine action ledger is unavailable");
+            try {
+                routineReceipt = structuredClone(options.reserveRoutineAction({
+                    key: routine.key,
+                    expectedPolicyVersion: routine.expectedPolicyVersion,
+                    expectedDesiredStateVersion: routine.expectedDesiredStateVersion,
+                    expectedGrantVersion: routine.expectedGrantVersion,
+                    requester: routine.requester,
+                    authorizationReceiptId: routineAuthorization.receiptId,
+                    authorizationVersion: routineAuthorization.profileVersion,
+                    action: "unraid.container.restart",
+                    target: fresh.name,
+                    attemptId: attempt.attemptId,
+                    expectedBeforeState: fresh.state,
+                    resolvedTarget: { id: fresh.id, name: fresh.name },
+                    effect: { operation: "restart", targetId: fresh.id },
+                }));
+                routineState.current = "reserved";
+            }
+            catch (error) {
+                return failure("stale_target", error instanceof Error ? error.message : "routine action authority changed");
+            }
+        }
+        const failReserved = () => {
+            if (routineReceipt && routineState.current === "reserved") {
+                transitionRoutine({ id: routineReceipt.id, expectedState: "reserved", state: "failed", recoveryState: { state: "completed", compensation: "none" } });
+                routineState.current = null;
+            }
+        };
+        if (approval && approval.argumentDigest !== attempt.argumentDigest)
+            return failure("stale_target", "approval arguments changed before restart");
+        await options.persistAttempt?.({ ...attempt, observedAt: now().toISOString(), state: "attempt_not_started" });
+        let apiKey;
+        try {
+            apiKey = await options.loadWriteApiKey();
+        }
+        catch (error) {
+            failReserved();
+            throw error;
+        }
+        if (!apiKey.trim()) {
+            failReserved();
+            return failure("invalid_response", "Unraid write credential is unavailable");
+        }
+        let client;
+        try {
+            client = createClient({ endpoint: options.endpoint, apiKey });
+        }
+        catch (error) {
+            failReserved();
+            throw error;
+        }
+        const persistTerminal = async (terminal) => {
+            try {
+                await options.persistAttempt?.(terminal);
+                return true;
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({ level: "error", component: "repertoire", event: "repertoire.unraid_restart_error", message: "approved Unraid restart terminal receipt persistence failed", meta: { containerId: fresh.id, category: error instanceof Error ? error.name : "unknown" } });
+                return false;
+            }
+        };
+        let acknowledged = false;
+        const performMutation = async (signal) => {
+            signal?.throwIfAborted();
+            if (routineReceipt && routineState.current === "reserved") {
+                transitionRoutine({ id: routineReceipt.id, expectedState: "reserved", state: "attempting" });
+                routineState.current = "attempting";
+            }
+            await options.persistAttempt?.({ ...attempt, observedAt: now().toISOString(), state: "attempting" });
+            (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.unraid_restart_start", message: "approved Unraid restart started", meta: { containerId: fresh.id, containerName: fresh.name } });
+            let mutation = null;
+            try {
+                signal?.throwIfAborted();
+                mutation = signal
+                    ? await client.mutate(exports.SANCTUARY_RESTART_MUTATION, { id: fresh.id }, signal)
+                    : await client.mutate(exports.SANCTUARY_RESTART_MUTATION, { id: fresh.id });
+                acknowledged = acknowledgedIdentity(mutation, fresh);
+                if (!acknowledged)
+                    throw new Error("restart response identity was invalid");
+            }
+            catch {
+                acknowledged = false;
+            }
+            if (acknowledged && mutation && routineReceipt && routineState.current === "attempting") {
+                transitionRoutine({ id: routineReceipt.id, expectedState: "attempting", state: "effect_acknowledged", effectReceipt: (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(mutation)).digest("hex") });
+                routineState.current = "effect_acknowledged";
+            }
+            else if (routineReceipt && routineState.current === "attempting") {
+                transitionRoutine({ id: routineReceipt.id, expectedState: "attempting", state: "indeterminate", recoveryState: { state: "manual_inspection_required", compensation: "none" } });
+                routineState.current = "indeterminate";
+                await persistTerminal({ ...attempt, observedAt: now().toISOString(), state: "attempted_or_indeterminate", mutationAcknowledged: false });
+            }
+        };
+        if (routineReceipt && routine) {
+            const authority = routine;
+            const reservation = routineReceipt;
+            const event = reservation.requester?.kind === "owner_event" ? reservation.requester.event : null;
+            const runFinalAttempt = (signal) => options.withRoutineActionAttempt(reservation, async () => {
+                const reauthorize = async () => {
+                    signal?.throwIfAborted();
+                    const authorization = await currentRoutineAuthorization(authority);
+                    if (authorization.profileVersion !== routineAuthorization.profileVersion)
+                        throw new Error("routine relationship profile version changed");
+                    signal?.throwIfAborted();
+                };
+                await reauthorize();
+                const listed = signal ? await options.listContainers(signal) : await options.listContainers();
+                signal?.throwIfAborted();
+                if (!listed.ok)
+                    throw new Error(listed.error.message);
+                const final = exactTarget(listed, args.container);
+                if ("ok" in final)
+                    throw new Error(final.error.message);
+                if (listed.data.truncated || final.degraded || final.id !== fresh.id || final.name !== fresh.name
+                    || Object.keys(args).length !== 1 || args.container !== fresh.name)
+                    throw new Error("routine action final container or arguments changed");
+                if (event && final.state !== "exited")
+                    throw new Error("current health event target is no longer exactly stopped");
+                await reauthorize();
+            }, () => performMutation(signal));
+            try {
+                if (event) {
+                    await (0, router_1.renewExternalEventClaim)(event.recordPath, { owner: event.claimOwner, expectedGeneration: event.generation }, (_record, signal) => runFinalAttempt(signal));
+                }
+                else {
+                    await runFinalAttempt();
+                }
+            }
+            catch (error) {
+                if (error instanceof RoutineActionReceiptError || routineState.current !== "reserved")
+                    throw error;
+                failReserved();
+                return failure("stale_target", error instanceof Error ? error.message : "routine action authority changed");
+            }
+        }
+        else if (approvalAuthority) {
+            if (!options.withApprovalPolicyLease)
+                return failure("invalid_response", "restart approval policy lease is unavailable");
+            let attemptStarted = false;
+            try {
+                await options.withApprovalPolicyLease(async () => {
+                    const listed = await options.listContainers();
+                    if (!listed.ok)
+                        throw new Error(listed.error.message);
+                    const final = exactTarget(listed, args.container);
+                    if ("ok" in final)
+                        throw new Error(final.error.message);
+                    if (listed.data.truncated || final.degraded || final.id !== fresh.id || final.name !== fresh.name
+                        || final.id !== approvalAuthority.target.id || final.name !== approvalAuthority.target.name
+                        || Object.keys(args).length !== 1 || args.container !== fresh.name)
+                        throw new Error("restart approval final container or arguments changed");
+                    const authorization = await approvalAuthority.reauthorize();
+                    if (authorization?.allowed !== true)
+                        throw new Error(authorization?.allowed === false && typeof authorization.reason === "string" && authorization.reason.trim()
+                            ? authorization.reason : "restart approval authorization is unavailable");
+                    attemptStarted = true;
+                    await performMutation();
+                });
+            }
+            catch (error) {
+                if (attemptStarted)
+                    throw error;
+                return failure("stale_target", error instanceof Error ? error.message : "restart approval authority changed");
+            }
+        }
+        else {
+            await performMutation();
+        }
+        const startedAt = now().getTime();
+        let sawRestarting = false;
+        try {
+            do {
+                const observed = exactTarget(await options.listContainers(), args.container);
+                if (!("ok" in observed)) {
+                    if (observed.id !== fresh.id) {
+                        await persistTerminal({ ...attempt, observedAt: now().toISOString(), state: "attempted_or_indeterminate", mutationAcknowledged: acknowledged });
+                        if (routineReceipt && routineState.current)
+                            transitionRoutine({ id: routineReceipt.id, expectedState: routineState.current, state: "indeterminate", recoveryState: { state: "manual_inspection_required", compensation: "none" } });
+                        return failure("ambiguous", "container identity changed after restart attempt");
+                    }
+                    sawRestarting ||= observed.state === "restarting";
+                    if (observed.state === "running" && !observed.degraded && (acknowledged || sawRestarting)) {
+                        if (!await persistTerminal({ ...attempt, observedAt: now().toISOString(), state: "succeeded", mutationAcknowledged: acknowledged, afterState: observed.state })) {
+                            return failure("ambiguous", "restart succeeded but its terminal receipt could not be persisted; it was not retried");
+                        }
+                        if (routineReceipt && (routineState.current === "attempting" || routineState.current === "indeterminate")) {
+                            transitionRoutine({ id: routineReceipt.id, expectedState: routineState.current, state: "effect_acknowledged", effectReceipt: (0, node_crypto_1.createHash)("sha256").update(JSON.stringify({ observation: "restarting", target: fresh.id })).digest("hex") });
+                            routineState.current = "effect_acknowledged";
+                        }
+                        if (routineReceipt && routineState.current === "effect_acknowledged") {
+                            transitionRoutine({ id: routineReceipt.id, expectedState: "effect_acknowledged", state: "verified", verifiedAfterState: observed.state, recoveryState: { state: "completed", compensation: "none" } });
+                            routineState.current = null;
+                        }
+                        (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.unraid_restart_end", message: "approved Unraid restart completed", meta: { containerId: fresh.id, observedRestart: true } });
+                        // One routine receipt owns both the effect and its verified after-state.
+                        return { ok: true, data: { container: { id: fresh.id, name: fresh.name }, beforeState: fresh.state, afterState: observed.state, observedRestart: true, degraded: false, ...(routineReceipt ? { actionRefs: [routineReceipt.id], verificationRefs: [routineReceipt.id] } : {}) } };
+                    }
+                }
+                if (now().getTime() - startedAt >= observationTimeoutMs)
+                    break;
+                await sleep(1_000);
+            } while (true);
+        }
+        catch (error) {
+            if (error instanceof RoutineActionReceiptError)
+                throw error;
+            await persistTerminal({ ...attempt, observedAt: now().toISOString(), state: "attempted_or_indeterminate", mutationAcknowledged: acknowledged });
+            if (routineReceipt && routineState.current)
+                transitionRoutine({ id: routineReceipt.id, expectedState: routineState.current, state: "indeterminate", recoveryState: { state: "manual_inspection_required", compensation: "none" } });
+            (0, runtime_1.emitNervesEvent)({ level: "error", component: "repertoire", event: "repertoire.unraid_restart_error", message: "approved Unraid restart observation failed", meta: { containerId: fresh.id, acknowledged } });
+            return failure("ambiguous", "restart was attempted but observation failed; it was not retried");
+        }
+        await persistTerminal({ ...attempt, observedAt: now().toISOString(), state: "attempted_or_indeterminate", mutationAcknowledged: acknowledged });
+        if (routineReceipt && routineState.current)
+            transitionRoutine({ id: routineReceipt.id, expectedState: routineState.current, state: "indeterminate", recoveryState: { state: "manual_inspection_required", compensation: "none" } });
+        (0, runtime_1.emitNervesEvent)({ level: "error", component: "repertoire", event: "repertoire.unraid_restart_error", message: "approved Unraid restart outcome was ambiguous", meta: { containerId: fresh.id, acknowledged } });
+        return failure("ambiguous", "restart was attempted but could not be proven; it was not retried");
+    };
+}

package/dist/repertoire/user-profile.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * User profile model and vault storage.
+ *
+ * Profiles are stored as secure notes in the agent's Vaultwarden vault,
+ * keyed by friend ID: `user-profile/{friendId}`.
+ *
+ * The storage layer uses the existing CredentialStore interface — the profile
+ * JSON is stored in the `password` field of a login item (the vault's most
+ * reliable field for arbitrary data). Field-level access ensures the full
+ * profile is never dumped to model context unnecessarily.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storeUserProfile = storeUserProfile;
+exports.getUserProfile = getUserProfile;
+exports.getUserProfileField = getUserProfileField;
+exports.deleteUserProfile = deleteUserProfile;
+exports.updateUserProfileFields = updateUserProfileFields;
+const runtime_1 = require("../nerves/runtime");
+// ---------------------------------------------------------------------------
+// Storage key
+// ---------------------------------------------------------------------------
+function profileKey(friendId) {
+    return `user-profile/${friendId}`;
+}
+function isMissingUserProfileError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return /no credential found/i.test(message) || /field "password" not found/i.test(message);
+}
+// ---------------------------------------------------------------------------
+// CRUD operations
+// ---------------------------------------------------------------------------
+/**
+ * Store a complete user profile in the vault.
+ * Overwrites any existing profile for the given friend ID.
+ */
+async function storeUserProfile(friendId, profile, store) {
+    (0, runtime_1.emitNervesEvent)({
+        event: "repertoire.user_profile_store",
+        component: "repertoire",
+        message: `storing user profile for ${friendId}`,
+        meta: { friendId },
+    });
+    const key = profileKey(friendId);
+    /* v8 ignore start -- platform-dependent v8 branch counting on await @preserve */
+    await store.store(key, {
+        password: JSON.stringify(profile),
+        notes: "user-profile",
+    });
+    /* v8 ignore stop */
+}
+/**
+ * Retrieve the full user profile for a friend.
+ * Returns null if no profile exists. Throws if the stored data is malformed
+ * or the vault cannot be read.
+ */
+async function getUserProfile(friendId, store) {
+    (0, runtime_1.emitNervesEvent)({
+        event: "repertoire.user_profile_get",
+        component: "repertoire",
+        message: `getting user profile for ${friendId}`,
+        meta: { friendId },
+    });
+    try {
+        const raw = await store.getRawSecret(profileKey(friendId), "password");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`stored user profile for ${friendId} is malformed`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            throw new Error(`stored user profile for ${friendId} is malformed`);
+        }
+        if (isMissingUserProfileError(err)) {
+            return null;
+        }
+        throw err;
+    }
+}
+/**
+ * Retrieve a specific field from a user profile.
+ * Returns undefined if the profile doesn't exist or the field is not set.
+ */
+async function getUserProfileField(friendId, field, store) {
+    const profile = await getUserProfile(friendId, store);
+    if (!profile)
+        return undefined;
+    return profile[field];
+}
+/**
+ * Delete a user profile from the vault.
+ * Returns true if the profile was deleted, false if it didn't exist.
+ */
+async function deleteUserProfile(friendId, store) {
+    (0, runtime_1.emitNervesEvent)({
+        event: "repertoire.user_profile_delete",
+        component: "repertoire",
+        message: `deleting user profile for ${friendId}`,
+        meta: { friendId },
+    });
+    return store.delete(profileKey(friendId));
+}
+/**
+ * Update specific fields on a user profile, merging with existing data.
+ * Creates the profile if it doesn't exist.
+ * Preferences are merged (not replaced) at the key level.
+ */
+async function updateUserProfileFields(friendId, fields, store) {
+    (0, runtime_1.emitNervesEvent)({
+        event: "repertoire.user_profile_update",
+        component: "repertoire",
+        message: `updating user profile fields for ${friendId}`,
+        meta: { friendId, fieldCount: Object.keys(fields).length },
+    });
+    const existing = await getUserProfile(friendId, store);
+    let merged;
+    if (existing) {
+        // Merge preferences at key level
+        const mergedPreferences = {
+            ...existing.preferences,
+            ...(fields.preferences ?? {}),
+        };
+        merged = { ...existing, ...fields, preferences: mergedPreferences };
+    }
+    else {
+        merged = fields;
+    }
+    await storeUserProfile(friendId, merged, store);
+}