crewly 1.20.174 → 1.20.175

package/dist/backend/backend/src/services/system/system-control.service.d.ts

@@ -0,0 +1,337 @@
+/**
+ * System Control Service — the owner's Upgrade and Restart buttons.
+ *
+ * Jenkins-style "safe restart" for Crewly
+ * (specs/2026-10-01-upgrade-restart-controls.md):
+ *
+ * - **Status.** Running version, latest on npm, install kind, who relaunches
+ *   the backend, agents mid-turn, and the current / last action.
+ * - **Upgrade** (`when: idle | now`). npm global installs only. It reuses the
+ *   AutoUpdateService install path (same prefix, same npm, same verify), then
+ *   restarts. A source checkout is refused: it is updated with git.
+ * - **Restart** (`when: idle | now`). The graceful drained shutdown, exiting
+ *   with RESTART_REQUESTED. When nothing is known to relaunch the backend, a
+ *   detached launcher is started first so the machine never stays down.
+ * - **When idle** waits until no agent is mid-turn, capped (30 min), then
+ *   goes ahead. Asking again with `now` cuts the wait short.
+ * - **One at a time.** A second request while one is running is refused,
+ *   as is any request while a shutdown is already under way.
+ * - **Survives the restart.** Progress and outcome are kept in
+ *   `<crewlyHome>/system-action.json`; the next boot settles the record
+ *   ("Restarted at …", "Upgraded to x.y.z", or what went wrong), so the
+ *   dashboard can show it after it reconnects.
+ *
+ * All I/O goes through {@link SystemControlDeps}.
+ *
+ * @module services/system/system-control.service
+ */
+import { SYSTEM_CONTROL_CONSTANTS } from '../../constants.js';
+import type { InstallAttempt } from './auto-update.service.js';
+import type { InstallInfo } from './auto-update.utils.js';
+import type { SupervisorInfo } from './supervisor-detect.js';
+/** `when` choice of the buttons. */
+export type SystemActionWhen = (typeof SYSTEM_CONTROL_CONSTANTS.WHEN_VALUES)[number];
+/** Which button was pressed. */
+export type SystemActionKind = 'upgrade' | 'restart';
+/** Where an action is. */
+export type SystemActionStatus = 'waiting-idle' | 'installing' | 'restarting' | 'completed' | 'failed' | 'interrupted';
+/** Install kind as the dashboard sees it. */
+export type PublicInstallKind = 'npm-global' | 'dev-checkout' | 'other';
+/** How the backend comes back after it exits. */
+export type RelaunchMethod = 'supervisor' | 'replacement';
+/** One upgrade or restart, persisted across the restart. */
+export interface SystemActionRecord {
+    id: string;
+    kind: SystemActionKind;
+    when: SystemActionWhen;
+    status: SystemActionStatus;
+    /** Who pressed it (e.g. `dashboard from 192.168.1.20`) */
+    requestedBy: string;
+    requestedAt: string;
+    updatedAt: string;
+    /** Version running when requested */
+    fromVersion: string | null;
+    /** Upgrade target */
+    toVersion: string | null;
+    /** Process that accepted the request */
+    pid: number;
+    /** How the backend is brought back */
+    relaunch: RelaunchMethod | null;
+    /** Owner-readable progress / outcome */
+    message: string;
+    /** Agents mid-turn the last time the idle wait looked */
+    waitingFor?: string[];
+    /** When the idle wait ended and why */
+    idleWaitEndedBy?: 'idle' | 'cap' | 'now';
+    /** Settled at (completed / failed / interrupted) */
+    completedAt?: string;
+    /** Version running when settled */
+    resultVersion?: string | null;
+}
+/** An agent mid-turn. */
+export interface BusyAgentInfo {
+    session: string;
+    since?: string;
+    messagePreview?: string;
+}
+/** `GET /api/system/update-status` body. */
+export interface UpdateStatus {
+    currentVersion: string | null;
+    latestVersion: string | null;
+    updateAvailable: boolean;
+    installKind: PublicInstallKind;
+    packageRoot: string | null;
+    /** Upgrade possible right now */
+    canUpgrade: boolean;
+    /** Why the Upgrade button is disabled (null when enabled) */
+    upgradeBlockedReason: string | null;
+    /** Restart possible right now */
+    canRestart: boolean;
+    /** Why the Restart button is disabled (null when enabled) */
+    restartBlockedReason: string | null;
+    supervisor: SupervisorInfo;
+    relaunch: RelaunchMethod;
+    /** Agents mid-turn now */
+    busyAgents: BusyAgentInfo[];
+    /** Some upgrade / restart / shutdown is under way */
+    inProgress: boolean;
+    /** Current or last action */
+    action: SystemActionRecord | null;
+    /** Changes on every boot; the dashboard uses it to see the backend came back */
+    bootId: string;
+    startedAt: string;
+}
+/** Refusal from a request. */
+export interface SystemActionRefusal {
+    ok: false;
+    httpStatus: number;
+    code: string;
+    error: string;
+}
+/** Accepted request. */
+export interface SystemActionAccepted {
+    ok: true;
+    action: SystemActionRecord;
+    /** True when an "idle" wait was cut short by a later "now" */
+    escalated?: boolean;
+}
+/** The install half the service borrows from AutoUpdateService. */
+export interface UpgradeInstaller {
+    installVersion(version: string): Promise<InstallAttempt>;
+    writeUpgradeMarker(fromVersion: string, toVersion: string): void;
+    clearUpgradeMarker(): void;
+    isBusy(): boolean;
+    appendLogLine(line: string): void;
+}
+/** Minimal logger. */
+export interface SystemControlLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/** Everything the service touches outside itself. */
+export interface SystemControlDeps {
+    crewlyHome: string;
+    install: InstallInfo;
+    currentVersion: string | null;
+    pid: number;
+    bootId: string;
+    startedAt: string;
+    /** Who relaunches the backend (evaluated when needed) */
+    getSupervisor: () => SupervisorInfo;
+    /** Latest version on npm, accepting a cached answer younger than maxAgeMs */
+    fetchLatestVersion: (maxAgeMs: number) => Promise<string | null>;
+    /** Agents mid-turn */
+    getBusyAgents: () => BusyAgentInfo[];
+    /** A shutdown / drain is already under way */
+    isShutdownInProgress: () => boolean;
+    /** The AutoUpdateService install path (null when it did not start) */
+    getInstaller: () => UpgradeInstaller | null;
+    /** Run the graceful drained shutdown with RESTART_REQUESTED; false when no handler */
+    requestGracefulRestart: (reason: string) => boolean;
+    /** Last resort when no graceful handler exists */
+    exit: (code: number) => void;
+    /** Start the detached launcher that brings the backend back */
+    spawnReplacement: (supervisorUnknown: boolean) => void;
+    logger: SystemControlLogger;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/** Options for the two requests. */
+export interface SystemActionRequest {
+    when: SystemActionWhen;
+    actor: string;
+}
+/**
+ * Map the AutoUpdate install kind onto the public one.
+ *
+ * @param install - Install info
+ * @returns Public kind
+ */
+export declare function toPublicInstallKind(install: InstallInfo): PublicInstallKind;
+/**
+ * Read the persisted action record.
+ *
+ * @param file - State file
+ * @returns The record, or null when missing / malformed
+ */
+export declare function readActionRecord(file: string): SystemActionRecord | null;
+/**
+ * Write the action record atomically.
+ *
+ * @param file - State file
+ * @param record - Record
+ */
+export declare function writeActionRecord(file: string, record: SystemActionRecord): void;
+/**
+ * Upgrade / restart controller for the running backend.
+ */
+export declare class SystemControlService {
+    private readonly deps;
+    private static instance;
+    private action;
+    private readonly stateFile;
+    /** Resolves the current idle wait early ("now" pressed while waiting) */
+    private cutIdleWaitShort;
+    /**
+     * @param deps - Injected I/O
+     */
+    constructor(deps: SystemControlDeps);
+    /**
+     * Register the process-wide instance.
+     *
+     * @param service - Instance, or null to clear
+     */
+    static setInstance(service: SystemControlService | null): void;
+    /**
+     * The process-wide instance, when the server registered one.
+     *
+     * @returns The instance or null
+     */
+    static getInstance(): SystemControlService | null;
+    /**
+     * Boot: settle the record a previous process left behind, so the
+     * dashboard can say "Restarted at …" / "Upgraded to x.y.z" after it
+     * reconnects.
+     */
+    handleBoot(): void;
+    /**
+     * Whether an upgrade or restart from this process is still running.
+     *
+     * @returns True while one is
+     */
+    isActionInProgress(): boolean;
+    /**
+     * The current or last action (this boot, or the one settled at boot).
+     *
+     * @returns The record or null
+     */
+    getAction(): SystemActionRecord | null;
+    /**
+     * How the backend comes back after an exit.
+     *
+     * @param supervisor - Supervisor info
+     * @returns supervisor or replacement
+     */
+    private relaunchMethod;
+    /**
+     * Status for the dashboard.
+     *
+     * @param options - `refresh` re-asks the registry when the cached answer is over a minute old
+     * @returns Status
+     */
+    getStatus(options?: {
+        refresh?: boolean;
+    }): Promise<UpdateStatus>;
+    /**
+     * Why nothing new can start right now (null when it can).
+     *
+     * @returns Owner-readable reason or null
+     */
+    private inProgressReason;
+    /**
+     * Busy agents, never throwing.
+     *
+     * @returns Agents mid-turn
+     */
+    private safeBusyAgents;
+    /**
+     * Escalate a running "when idle" wait of the same kind to "now".
+     *
+     * @param kind - Requested kind
+     * @param request - Request
+     * @returns Accepted answer, or null when this is not an escalation
+     */
+    private tryEscalate;
+    /**
+     * Refusal for "something is already running", or null.
+     *
+     * @returns Refusal or null
+     */
+    private busyRefusal;
+    /**
+     * Owner pressed "Upgrade".
+     *
+     * @param request - When, and who
+     * @returns Accepted (work continues in the background) or a refusal
+     */
+    requestUpgrade(request: SystemActionRequest): Promise<SystemActionAccepted | SystemActionRefusal>;
+    /**
+     * Owner pressed "Restart".
+     *
+     * @param request - When, and who
+     * @returns Accepted (work continues in the background) or a refusal
+     */
+    requestRestart(request: SystemActionRequest): Promise<SystemActionAccepted | SystemActionRefusal>;
+    /**
+     * Create and persist a new action.
+     *
+     * @param kind - upgrade or restart
+     * @param request - Request
+     * @param toVersion - Upgrade target
+     * @returns The record
+     */
+    private begin;
+    /**
+     * Upgrade body: (wait for idle) → install → verify → marker → restart.
+     *
+     * @param installer - AutoUpdate install path
+     * @param version - Target
+     */
+    private runUpgrade;
+    /**
+     * Restart body: (wait for idle) → restart.
+     */
+    private runRestart;
+    /**
+     * Make sure something brings the backend back, then run the graceful
+     * restart.
+     *
+     * @param reason - Shutdown reason (logs)
+     * @param message - Owner-readable progress
+     * @returns False when the restart could not be started
+     */
+    private restartNow;
+    /**
+     * Wait until no agent is mid-turn, at most IDLE_WAIT_CAP_MS; a later "now"
+     * request ends the wait at once.
+     */
+    private waitForIdle;
+    /**
+     * Mark the current action failed.
+     *
+     * @param message - Owner-readable reason
+     */
+    private fail;
+    /**
+     * Merge a patch into the current action and persist it.
+     *
+     * @param patch - Fields to change
+     */
+    private update;
+    /**
+     * Write the current action (best-effort).
+     */
+    private persist;
+}
+//# sourceMappingURL=system-control.service.d.ts.map

package/dist/backend/backend/src/services/system/system-control.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-control.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/system/system-control.service.ts"],"names":[],"mappings":"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"}