crewly 1.20.143 → 1.20.145

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

@@ -0,0 +1,292 @@
+/**
+ * Auto-Update Service
+ *
+ * Keeps an npm-installed Crewly on the latest release with nobody at the
+ * keyboard (specs/auto-update.md):
+ *
+ * 1. about 10 min after boot, then every 3 h, ask the npm registry for the
+ *    latest `crewly`;
+ * 2. when it is newer and auto-update is on, wait for a quiet window — no
+ *    agent in_progress and no turn in flight, seen twice ~60 s apart;
+ * 3. `npm install -g --prefix <the running copy's prefix> crewly@<version>`;
+ * 4. verify the installed package.json says `<version>`;
+ * 5. write a marker and ask for the graceful restart (drain, exit 120, the
+ *    `crewly start` parent respawns the backend from the new files);
+ * 6. on the next boot, read the marker and DM the owner once.
+ *
+ * Failures (install error, verify mismatch, no restart path) back off 6 h
+ * and never restart onto a broken install. Dev checkouts, non-npm installs
+ * and backends without a respawning parent are skipped.
+ *
+ * All I/O goes through {@link AutoUpdateDeps} so the rules are unit-testable
+ * with a mocked registry, npm and clock; {@link createAutoUpdateService}
+ * wires the real ones.
+ *
+ * @module services/system/auto-update.service
+ */
+import { type AutoUpdateOutcome, type AutoUpdateState, type InstallInfo } from './auto-update.utils.js';
+/** Result of one `npm install` run. */
+export interface InstallRunResult {
+    /** True when npm exited 0 */
+    ok: boolean;
+    /** Exit code (null when killed) */
+    code: number | null;
+    /** Tail of the combined output, for the failure reason */
+    outputTail: string;
+}
+/** What is keeping the machine busy right now. */
+export interface BusySnapshot {
+    /** Sessions with a turn in flight (InFlightTurnTracker) */
+    midTurn: string[];
+    /** Active agents whose workingStatus is in_progress */
+    inProgress: string[];
+}
+/** Minimal logger. */
+export interface AutoUpdateLogger {
+    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 AutoUpdateDeps {
+    /** Crewly home (state, marker and log live here) */
+    crewlyHome: string;
+    /** Where/how the running copy is installed */
+    install: InstallInfo;
+    /** Version this process is running (read at boot, before any install) */
+    currentVersion: string | null;
+    /** `settings.general.autoUpdate` (undefined = default on) */
+    getSettingEnabled: () => Promise<boolean | undefined>;
+    /** Environment (for CREWLY_AUTO_UPDATE) */
+    env: NodeJS.ProcessEnv;
+    /** Whether a parent will respawn the backend after exit 120 */
+    hasSupervisor: () => boolean;
+    /** Latest version on npm (null on failure) */
+    fetchLatestVersion: (currentVersion: string) => Promise<string | null>;
+    /** True when a shutdown / restart is already under way */
+    isRestartInProgress: () => boolean;
+    /** Busy agents and turns */
+    getBusy: () => Promise<BusySnapshot>;
+    /** Run npm; resolves when it exits */
+    runInstall: (command: string, args: string[]) => Promise<InstallRunResult>;
+    /** npm executable */
+    npmCommand: string;
+    /** Read the installed version from disk */
+    readInstalledVersion: (packageRoot: string) => string | null;
+    /** Ask for the graceful restart; false when nothing can restart us */
+    requestRestart: (reason: string) => boolean;
+    /** Whether the owner channel (Slack) is up */
+    isNotifyReady: () => boolean;
+    /** Send one owner notification */
+    notifyOwner: (title: string, message: string) => Promise<void>;
+    /** This machine's display name */
+    getDeviceName: () => Promise<string>;
+    /** Called after a successful install, before the restart (e.g. re-anchor the cwd) */
+    afterInstall: (packageRoot: string) => void;
+    /** Append a line to auto-update.log */
+    appendLog: (line: string) => void;
+    /** Logger */
+    logger: AutoUpdateLogger;
+    /** Clock */
+    now: () => number;
+    /** Sleep */
+    sleep: (ms: number) => Promise<void>;
+    /** Schedule a callback (returns a handle for cancel) */
+    schedule: (fn: () => void, ms: number) => unknown;
+    /** Cancel a scheduled callback */
+    cancel: (handle: unknown) => void;
+}
+/** Result of one {@link AutoUpdateService.runCycle}. */
+export interface CycleResult {
+    /** How it ended */
+    outcome: AutoUpdateOutcome | 'backoff';
+    /** Detail for logs/tests */
+    detail?: string;
+    /** Target version, when one was chosen */
+    version?: string;
+}
+/**
+ * Periodically upgrades the running npm install and restarts into it.
+ */
+export declare class AutoUpdateService {
+    private readonly deps;
+    private static instance;
+    private timer;
+    private running;
+    private stopped;
+    private lastLoggedMode;
+    private busySince;
+    private pendingNotice;
+    private readonly statePath;
+    private readonly markerPath;
+    /**
+     * @param deps - Injected I/O
+     */
+    constructor(deps: AutoUpdateDeps);
+    /**
+     * Register the process-wide instance (index.ts).
+     *
+     * @param service - Instance, or null to clear
+     */
+    static setInstance(service: AutoUpdateService | null): void;
+    /**
+     * The process-wide instance, when one was registered.
+     *
+     * @returns The instance or null
+     */
+    static getInstance(): AutoUpdateService | null;
+    /**
+     * Boot: consume the pending-upgrade marker (and report it), log the mode,
+     * and schedule the first check.
+     */
+    start(): void;
+    /**
+     * Stop scheduling (shutdown).
+     */
+    stop(): void;
+    /**
+     * Whether this boot is the result of an auto-upgrade whose notice is still
+     * owed — the generic "back online" announcement is skipped then, so the
+     * owner gets one message per upgrade, not two.
+     *
+     * @returns True while the upgrade notice is pending or was just sent
+     */
+    isUpgradeBoot(): boolean;
+    /**
+     * Current persisted status.
+     *
+     * @returns The state
+     */
+    getState(): AutoUpdateState;
+    /**
+     * The on/off/skip mode as a short string (also what update-status shows).
+     *
+     * @returns e.g. `enabled`, `dev-checkout`, `disabled-env`
+     */
+    describeMode(): Promise<string>;
+    /**
+     * One check → (maybe) install → verify → restart pass.
+     *
+     * @returns How it ended
+     */
+    runCycle(): Promise<CycleResult>;
+    /**
+     * Body of {@link runCycle}.
+     *
+     * @returns How it ended
+     */
+    private runCycleInner;
+    /**
+     * Whether nothing is busy. A stale in_progress flag stops blocking after
+     * MAX_BUSY_DEFER_MS; a turn in flight always blocks.
+     *
+     * @returns ok, or the reason it is not
+     */
+    private isQuiet;
+    /**
+     * Record a busy deferral.
+     *
+     * @param version - Target version
+     * @param reason - What is busy
+     * @returns Cycle result
+     */
+    private deferBusy;
+    /**
+     * Record a failure, back off, and tell the owner once per target version
+     * after repeated failures.
+     *
+     * @param outcome - Failure kind
+     * @param version - Target version
+     * @param reason - Why
+     * @returns Cycle result
+     */
+    private recordFailure;
+    /**
+     * Boot half of the upgrade: consume the marker; when this process runs the
+     * version it names, record success and DM the owner.
+     */
+    private handleBootMarker;
+    /**
+     * Send an owner notice once the channel is up (waits up to NOTIFY_WAIT_MS).
+     *
+     * @param compose - Builds the notice from the device name
+     * @returns True when sent
+     */
+    private notify;
+    /**
+     * Schedule the next cycle.
+     *
+     * @param ms - Delay
+     */
+    private scheduleNext;
+    /**
+     * Timer body: run a cycle and pick the next delay from its outcome.
+     */
+    private tick;
+    /**
+     * Log the mode when it changes (so "dev checkout — auto-update off" is
+     * said once, not every 3 hours).
+     *
+     * @param mode - Current mode
+     */
+    private logModeOnce;
+    /**
+     * Merge a patch into the status file (best-effort).
+     *
+     * @param patch - Fields to change
+     */
+    private updateState;
+    /**
+     * Append a timestamped line to auto-update.log.
+     *
+     * @param line - Text
+     */
+    private log;
+}
+/**
+ * Human-readable line for a mode.
+ *
+ * @param mode - Mode from {@link AutoUpdateService.describeMode}
+ * @param install - Install info
+ * @returns Log line
+ */
+export declare function describeModeLine(mode: string, install: InstallInfo): string;
+/**
+ * Run npm, appending its output to the log, killing it after the timeout.
+ *
+ * @param command - npm executable
+ * @param args - Arguments
+ * @param appendLog - Log sink
+ * @param timeoutMs - Kill after this long
+ * @returns Exit status and output tail
+ */
+export declare function runNpmInstall(command: string, args: string[], appendLog: (line: string) => void, timeoutMs?: number): Promise<InstallRunResult>;
+/** Live hooks the server provides to {@link createAutoUpdateService}. */
+export interface AutoUpdateWiring {
+    /** Crewly home */
+    crewlyHome: string;
+    /** `settings.general.autoUpdate` */
+    getSettingEnabled: () => Promise<boolean | undefined>;
+    /** Latest version on npm */
+    fetchLatestVersion: (currentVersion: string) => Promise<string | null>;
+    /** Restart already under way */
+    isRestartInProgress: () => boolean;
+    /** Busy snapshot */
+    getBusy: () => Promise<BusySnapshot>;
+    /** Graceful restart with RESTART_REQUESTED */
+    requestRestart: (reason: string, exitCode: number) => boolean;
+    /** Owner channel up */
+    isNotifyReady: () => boolean;
+    /** Owner notification */
+    notifyOwner: (title: string, message: string) => Promise<void>;
+    /** Device name */
+    getDeviceName: () => Promise<string>;
+}
+/**
+ * Build the service with the real filesystem, npm, clock and timers.
+ *
+ * @param wiring - Server hooks
+ * @returns The service (not started)
+ */
+export declare function createAutoUpdateService(wiring: AutoUpdateWiring): AutoUpdateService;
+//# sourceMappingURL=auto-update.service.d.ts.map

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

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