crewly 1.20.173 → 1.20.175

package/dist/backend/backend/src/services/system/supervisor-detect.js

@@ -0,0 +1,171 @@
+/**
+ * Who brings the backend back after it exits?
+ *
+ * The owner's Restart / Upgrade buttons must never leave a machine down, so
+ * before exiting the backend needs to know whether something will relaunch
+ * it (specs/2026-10-01-upgrade-restart-controls.md):
+ *
+ * - `crewly start` (the CLI restart loop) respawns the backend when it exits
+ *   with RESTART_REQUESTED (120). That is the parent in every supported run
+ *   mode: foreground, the macOS login item (`~/.crewly/crewly-start.command`),
+ *   the systemd user unit (`crewly.service`) and the desktop app. The outer
+ *   layer is reported too, because it decides what happens if the CLI itself
+ *   dies.
+ * - PM2 restarts the app on exit by default.
+ * - A backend started some other way (directly under systemd or launchd,
+ *   a bare `node dist/...`) may or may not come back; that is "unknown", and
+ *   "none" when there is clearly no supervisor at all.
+ *
+ * Pure: the environment and process lookups are injected.
+ *
+ * @module services/system/supervisor-detect
+ */
+import { execFileSync } from 'child_process';
+import { SYSTEM_CONTROL_CONSTANTS } from '../../constants.js';
+import { hasRestartSupervisor, readProcessCommandLine } from './auto-update.utils.js';
+/**
+ * Whether the environment says we run inside a systemd unit.
+ *
+ * @param env - Environment
+ * @param commandLines - Parent / grandparent command lines
+ * @returns True under systemd
+ */
+function isUnderSystemd(env, commandLines) {
+    if (env.INVOCATION_ID)
+        return true;
+    return commandLines.some((c) => !!c && c.includes(SYSTEM_CONTROL_CONSTANTS.SYSTEMD_UNIT));
+}
+/**
+ * Whether launchd started us as a job (not via Terminal). launchd sets
+ * XPC_SERVICE_NAME to the job label; shells in Terminal get `0` or an
+ * `application.*` name.
+ *
+ * @param env - Environment
+ * @param platform - Platform
+ * @returns True for a launchd job
+ */
+function isLaunchdJob(env, platform) {
+    if (platform !== 'darwin')
+        return false;
+    const label = env.XPC_SERVICE_NAME;
+    return !!label && label !== '0' && !label.startsWith('application.');
+}
+/**
+ * Work out what relaunches the backend.
+ *
+ * @param probe - Environment and process lookups
+ * @returns Supervisor info
+ *
+ * @example
+ * ```ts
+ * detectSupervisor({ env: { CREWLY_RESTART_SUPERVISOR: 'cli-start', INVOCATION_ID: 'x' }, platform: 'linux',
+ *   parentCommandLine: () => null, grandparentCommandLine: () => null });
+ * // { kind: 'crewly-start', outer: 'systemd', willRelaunch: 'yes', ... }
+ * ```
+ */
+export function detectSupervisor(probe) {
+    const { env, platform } = probe;
+    let parent;
+    let grandparent;
+    const readParent = () => (parent === undefined ? (parent = probe.parentCommandLine()) : parent);
+    const readGrandparent = () => grandparent === undefined ? (grandparent = probe.grandparentCommandLine()) : grandparent;
+    const cliStart = hasRestartSupervisor(env, readParent);
+    if (cliStart) {
+        const gp = readGrandparent();
+        let outer = null;
+        if (isUnderSystemd(env, [gp]))
+            outer = 'systemd';
+        else if (gp && gp.includes(SYSTEM_CONTROL_CONSTANTS.LOGIN_WRAPPER_SCRIPT))
+            outer = 'login-wrapper';
+        else if (isLaunchdJob(env, platform))
+            outer = 'launchd';
+        const outerText = outer === 'systemd'
+            ? ' systemd keeps crewly start itself running.'
+            : outer === 'login-wrapper'
+                ? ` The ${SYSTEM_CONTROL_CONSTANTS.LOGIN_WRAPPER_SCRIPT} login item keeps crewly start itself running.`
+                : outer === 'launchd'
+                    ? ' launchd keeps crewly start itself running.'
+                    : '';
+        return {
+            kind: 'crewly-start',
+            outer,
+            willRelaunch: 'yes',
+            detail: `crewly start restarts the backend when it exits.${outerText}`,
+        };
+    }
+    // PM2 (the legacy ecosystem.config.js) restarts the app on exit by default.
+    if (env.pm_id !== undefined || env.PM2_HOME !== undefined) {
+        return {
+            kind: 'pm2',
+            outer: null,
+            willRelaunch: 'yes',
+            detail: 'PM2 restarts the backend when it exits.',
+        };
+    }
+    const p = readParent();
+    if (isUnderSystemd(env, [p])) {
+        return {
+            kind: 'systemd',
+            outer: null,
+            willRelaunch: 'unknown',
+            detail: 'Runs directly under systemd; it comes back only if the unit has Restart= set.',
+        };
+    }
+    if (isLaunchdJob(env, platform)) {
+        return {
+            kind: 'launchd',
+            outer: null,
+            willRelaunch: 'unknown',
+            detail: 'Runs directly under launchd; it comes back only if the job has KeepAlive set.',
+        };
+    }
+    if (p === null) {
+        return {
+            kind: 'unknown',
+            outer: null,
+            willRelaunch: 'unknown',
+            detail: 'Could not tell what started Crewly.',
+        };
+    }
+    return {
+        kind: 'none',
+        outer: null,
+        willRelaunch: 'no',
+        detail: 'Nothing will relaunch Crewly on its own; a restart starts a new copy before this one exits.',
+    };
+}
+/**
+ * Parent pid of a process (POSIX, via `ps`).
+ *
+ * @param pid - Process id
+ * @returns The parent pid, or null
+ */
+export function readParentPid(pid) {
+    if (process.platform === 'win32' || !Number.isInteger(pid) || pid <= 1)
+        return null;
+    try {
+        const out = execFileSync('ps', ['-o', 'ppid=', '-p', String(pid)], { encoding: 'utf-8', timeout: 2000 }).trim();
+        const ppid = Number.parseInt(out, 10);
+        return Number.isInteger(ppid) && ppid > 1 ? ppid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect the supervisor of the running process.
+ *
+ * @returns Supervisor info
+ */
+export function detectRunningSupervisor() {
+    return detectSupervisor({
+        env: process.env,
+        platform: process.platform,
+        parentCommandLine: () => readProcessCommandLine(process.ppid),
+        grandparentCommandLine: () => {
+            const gp = readParentPid(process.ppid);
+            return gp ? readProcessCommandLine(gp) : null;
+        },
+    });
+}
+//# sourceMappingURL=supervisor-detect.js.map

package/dist/backend/backend/src/services/system/supervisor-detect.js.map

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

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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"}