@xfey/tutti 0.1.60 → 0.1.62

package/dist/server-shell/local-console/package-update-record.js

@@ -0,0 +1,180 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { ID_PREFIXES, isPrefixedId } from "@tutti/shared/ids";
+import { compareExactSemver, parseExactSemver } from "../package-installation/index.js";
+const DEFAULT_MAX_RECORD_AGE_MS = 24 * 60 * 60 * 1_000;
+const RECORD_KEYS = [
+    "failure_reason_code",
+    "phase",
+    "restart_failure_count",
+    "restore_project_ids",
+    "schema_version",
+    "source_version",
+    "started_at",
+    "target_version",
+    "updated_at",
+    "updater_pid",
+];
+export function packageUpdateRuntimeRecordPath(tuttiHome) {
+    return join(tuttiHome, "runtime", "package-update.json");
+}
+function isIsoTimestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function isStableReason(value) {
+    return typeof value === "string" && /^[a-z][a-z0-9_]{0,79}$/u.test(value);
+}
+function parseRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return null;
+    }
+    const candidate = value;
+    if (Object.keys(candidate).some((key) => !RECORD_KEYS.includes(key))) {
+        return null;
+    }
+    const source = parseExactSemver(candidate.source_version);
+    const target = parseExactSemver(candidate.target_version);
+    const phases = [
+        "preparing",
+        "stopping_hosts",
+        "installing",
+        "restarting",
+        "failed",
+    ];
+    if (candidate.schema_version !== 1 ||
+        source === null ||
+        target === null ||
+        compareExactSemver(target, source) <= 0 ||
+        !phases.includes(candidate.phase) ||
+        !Array.isArray(candidate.restore_project_ids) ||
+        !candidate.restore_project_ids.every((projectId) => typeof projectId === "string" && isPrefixedId(projectId, ID_PREFIXES.project)) ||
+        new Set(candidate.restore_project_ids).size !== candidate.restore_project_ids.length ||
+        !Number.isInteger(candidate.updater_pid) ||
+        candidate.updater_pid <= 0 ||
+        !isIsoTimestamp(candidate.started_at) ||
+        !isIsoTimestamp(candidate.updated_at) ||
+        Date.parse(candidate.updated_at) < Date.parse(candidate.started_at) ||
+        (candidate.failure_reason_code !== undefined &&
+            !isStableReason(candidate.failure_reason_code)) ||
+        (candidate.restart_failure_count !== undefined &&
+            (!Number.isInteger(candidate.restart_failure_count) ||
+                candidate.restart_failure_count < 0))) {
+        return null;
+    }
+    return {
+        schema_version: 1,
+        source_version: source,
+        target_version: target,
+        phase: candidate.phase,
+        restore_project_ids: [...candidate.restore_project_ids].sort(),
+        updater_pid: candidate.updater_pid,
+        started_at: candidate.started_at,
+        updated_at: candidate.updated_at,
+        ...(candidate.failure_reason_code === undefined
+            ? {}
+            : { failure_reason_code: candidate.failure_reason_code }),
+        ...(candidate.restart_failure_count === undefined
+            ? {}
+            : { restart_failure_count: candidate.restart_failure_count }),
+    };
+}
+export function readPackageUpdateRuntimeRecord(options) {
+    const path = packageUpdateRuntimeRecordPath(options.tuttiHome);
+    if (!existsSync(path)) {
+        return { status: "missing" };
+    }
+    try {
+        const record = parseRecord(JSON.parse(readFileSync(path, "utf8")));
+        if (record === null ||
+            (options.now ?? Date.now)() - Date.parse(record.updated_at) >
+                (options.maxAgeMs ?? DEFAULT_MAX_RECORD_AGE_MS)) {
+            return { status: "invalid" };
+        }
+        return { status: "valid", record };
+    }
+    catch {
+        return { status: "invalid" };
+    }
+}
+export function writePackageUpdateRuntimeRecord(tuttiHome, record) {
+    const parsed = parseRecord(record);
+    if (parsed === null) {
+        throw new Error("Package update runtime record is invalid.");
+    }
+    const path = packageUpdateRuntimeRecordPath(tuttiHome);
+    const directory = dirname(path);
+    const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    chmodSync(directory, 0o700);
+    try {
+        writeFileSync(temporaryPath, `${JSON.stringify(parsed)}\n`, { encoding: "utf8", mode: 0o600 });
+        chmodSync(temporaryPath, 0o600);
+        renameSync(temporaryPath, path);
+        chmodSync(path, 0o600);
+    }
+    finally {
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch {
+            // Atomic rename normally removes the temporary path.
+        }
+    }
+}
+export function deletePackageUpdateRuntimeRecord(options) {
+    const read = readPackageUpdateRuntimeRecord({ tuttiHome: options.tuttiHome });
+    if (read.status === "missing") {
+        return true;
+    }
+    if (read.status !== "valid" ||
+        (options.expectedTargetVersion !== undefined &&
+            read.record.target_version !== options.expectedTargetVersion) ||
+        (options.expectedUpdaterPid !== undefined &&
+            read.record.updater_pid !== options.expectedUpdaterPid)) {
+        return false;
+    }
+    try {
+        unlinkSync(packageUpdateRuntimeRecordPath(options.tuttiHome));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function updatePackageUpdateRuntimeRecord(options) {
+    const updated = {
+        ...options.current,
+        phase: options.phase,
+        updater_pid: options.updaterPid ?? options.current.updater_pid,
+        updated_at: (options.now ?? (() => new Date()))().toISOString(),
+        ...(options.failureReasonCode === undefined
+            ? {}
+            : { failure_reason_code: options.failureReasonCode }),
+        ...(options.restartFailureCount === undefined
+            ? {}
+            : { restart_failure_count: options.restartFailureCount }),
+    };
+    writePackageUpdateRuntimeRecord(options.tuttiHome, updated);
+    return updated;
+}
+export function consumePackageUpdateCompletion(options) {
+    const read = readPackageUpdateRuntimeRecord({ tuttiHome: options.tuttiHome });
+    if (read.status !== "valid" ||
+        read.record.phase !== "restarting" ||
+        read.record.target_version !== options.currentVersion ||
+        read.record.restart_failure_count === undefined) {
+        return undefined;
+    }
+    if (!deletePackageUpdateRuntimeRecord({
+        tuttiHome: options.tuttiHome,
+        expectedTargetVersion: read.record.target_version,
+    })) {
+        return undefined;
+    }
+    return {
+        source_version: read.record.source_version,
+        target_version: read.record.target_version,
+        restart_failure_count: read.record.restart_failure_count,
+    };
+}
+//# sourceMappingURL=package-update-record.js.map

package/dist/server-shell/local-console/package-update-recovery.d.ts

@@ -0,0 +1,34 @@
+import type { ProjectId } from "@tutti/shared/ids";
+import { type PackageUpdateLockAcquisition, type PackageUpdateLockInspection } from "./package-update-lock.js";
+import { type PackageUpdateRuntimeRecord, type PackageUpdateRuntimeRecordRead } from "./package-update-record.js";
+export type PackageUpdateStartupRecoveryResult = {
+    status: "continue";
+} | {
+    status: "completed";
+    url: string;
+    restart_failure_count: number;
+};
+type HostRestoreResult = {
+    restored_project_ids: ProjectId[];
+    failed_project_ids: ProjectId[];
+};
+export declare function recoverPackageUpdateForConsoleStartup(options: {
+    tuttiHome: string;
+    cliEntrypoint: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    source: "terminal" | "desktop";
+    currentVersion?: string;
+    readRecord?: () => PackageUpdateRuntimeRecordRead;
+    inspectLock?: () => PackageUpdateLockInspection;
+    removeRecoverableLock?: () => boolean;
+    acquireLock?: () => PackageUpdateLockAcquisition;
+    restoreHosts?: (record: PackageUpdateRuntimeRecord) => Promise<HostRestoreResult>;
+    deleteRecord?: (record: PackageUpdateRuntimeRecord) => boolean;
+    ensureConsole?: () => Promise<{
+        url: string;
+    }>;
+    now?: () => Date;
+}): Promise<PackageUpdateStartupRecoveryResult>;
+export {};
+//# sourceMappingURL=package-update-recovery.d.ts.map

package/dist/server-shell/local-console/package-update-recovery.js

@@ -0,0 +1,140 @@
+import { readCliVersion } from "../cli/version.js";
+import { ensureLocalConsole } from "./managed-console.js";
+import { runPackageUpdateCompletion } from "./package-update-completion.js";
+import { restorePackageUpdateHosts } from "./package-update-hosts.js";
+import { inspectPackageUpdateLock, removeRecoverablePackageUpdateLock, tryAcquirePackageUpdateLock, } from "./package-update-lock.js";
+import { PackageUpdateLogger } from "./package-update-log.js";
+import { deletePackageUpdateRuntimeRecord, readPackageUpdateRuntimeRecord, updatePackageUpdateRuntimeRecord, } from "./package-update-record.js";
+export async function recoverPackageUpdateForConsoleStartup(options) {
+    const currentVersion = options.currentVersion ?? readCliVersion();
+    const readRecord = options.readRecord ?? (() => readPackageUpdateRuntimeRecord({ tuttiHome: options.tuttiHome }));
+    const initialRecord = readRecord();
+    if (initialRecord.status !== "valid" || initialRecord.record.phase === "failed") {
+        return { status: "continue" };
+    }
+    const inspectLock = options.inspectLock ?? (() => inspectPackageUpdateLock({ tuttiHome: options.tuttiHome }));
+    const lockState = inspectLock();
+    if (lockState.status === "active") {
+        return { status: "continue" };
+    }
+    if (lockState.status === "recovery_required") {
+        const removed = (options.removeRecoverableLock ??
+            (() => removeRecoverablePackageUpdateLock({ tuttiHome: options.tuttiHome })))();
+        if (!removed) {
+            return { status: "continue" };
+        }
+    }
+    const acquisition = (options.acquireLock ?? (() => tryAcquirePackageUpdateLock({ tuttiHome: options.tuttiHome })))();
+    if (acquisition.status !== "acquired") {
+        return { status: "continue" };
+    }
+    const logger = new PackageUpdateLogger({
+        tuttiHome: options.tuttiHome,
+        privatePaths: [options.tuttiHome],
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    const log = (entry) => {
+        try {
+            logger.append(entry);
+        }
+        catch {
+            // Recovery correctness must not depend on the diagnostic log.
+        }
+    };
+    let lockReleased = false;
+    const releaseLock = () => {
+        if (!lockReleased) {
+            lockReleased = true;
+            acquisition.lease.release();
+        }
+        return true;
+    };
+    const current = readRecord();
+    if (current.status !== "valid" || current.record.phase === "failed") {
+        releaseLock();
+        return { status: "continue" };
+    }
+    const record = current.record;
+    const restoreHosts = options.restoreHosts ??
+        ((value) => restorePackageUpdateHosts({
+            tuttiHome: options.tuttiHome,
+            projectIds: value.restore_project_ids,
+            env: options.env,
+        }));
+    if (record.source_version === currentVersion) {
+        let restored;
+        try {
+            restored = await restoreHosts(record);
+        }
+        catch {
+            restored = {
+                restored_project_ids: [],
+                failed_project_ids: [...record.restore_project_ids],
+            };
+        }
+        const deleted = (options.deleteRecord ??
+            ((value) => deletePackageUpdateRuntimeRecord({
+                tuttiHome: options.tuttiHome,
+                expectedTargetVersion: value.target_version,
+                expectedUpdaterPid: value.updater_pid,
+            })))(record);
+        releaseLock();
+        const recoveryIncomplete = restored.failed_project_ids.length > 0 || !deleted;
+        log({
+            level: restored.failed_project_ids.length === 0 && deleted ? "info" : "warn",
+            message: restored.failed_project_ids.length === 0 && deleted
+                ? "Recovered an interrupted package update using the source CLI."
+                : "Package update source recovery requires follow-up.",
+            ...(recoveryIncomplete ? { reasonCode: "update_recovery_required" } : {}),
+        });
+        return { status: "continue" };
+    }
+    if (record.target_version !== currentVersion) {
+        releaseLock();
+        return { status: "continue" };
+    }
+    const completionRecord = updatePackageUpdateRuntimeRecord({
+        tuttiHome: options.tuttiHome,
+        current: record,
+        phase: "restarting",
+        updaterPid: process.pid,
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    let consoleUrl;
+    try {
+        const completion = await runPackageUpdateCompletion({
+            tuttiHome: options.tuttiHome,
+            cliEntrypoint: options.cliEntrypoint,
+            env: options.env,
+            currentVersion,
+            logger,
+            restoreHosts: async () => await restoreHosts(completionRecord),
+            ensureConsole: async () => {
+                const result = await (options.ensureConsole ??
+                    (() => ensureLocalConsole({
+                        cwd: options.cwd,
+                        env: options.env,
+                        source: options.source,
+                    })))();
+                consoleUrl = result.url;
+                return result;
+            },
+            openBrowser: () => false,
+            releaseLock,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        });
+        if (consoleUrl === undefined) {
+            throw new Error("Recovered package update did not start a Local Console.");
+        }
+        return {
+            status: "completed",
+            url: consoleUrl,
+            restart_failure_count: completion.restart_failure_count,
+        };
+    }
+    catch {
+        releaseLock();
+        return { status: "continue" };
+    }
+}
+//# sourceMappingURL=package-update-recovery.js.map

package/dist/server-shell/local-console/package-update-service.d.ts

@@ -0,0 +1,72 @@
+import type { ProjectId } from "@tutti/shared/ids";
+import { type MachineProjectInspection } from "../cli/machine-project-inspector.js";
+import { type GlobalPackageInstallation, type GlobalPackageInstallationResolution, type PackageInstallationUnavailableReason, type PackageUpdateDiscovery, type PublishedPackageTarget } from "../package-installation/index.js";
+import { LocalConsoleOperationCoordinator } from "./operation-coordinator.js";
+import { type PackageUpdateLockAcquisition, type PackageUpdateLockInspection } from "./package-update-lock.js";
+import { type PackageUpdateRuntimeRecordRead } from "./package-update-record.js";
+export type LocalConsolePackageUpdateReason = PackageInstallationUnavailableReason | "registry_unavailable" | "console_busy" | "host_busy" | "host_identity_unverified" | "host_update_unsupported" | "update_in_progress" | "update_recovery_required" | "npm_install_failed" | "post_install_validation_failed" | "completion_start_failed" | "completion_failed" | "worker_crashed" | "host_restore_failed";
+export type LocalConsolePackageUpdateStatus = {
+    current_version: string;
+    latest_version?: string;
+    status: "up_to_date" | "ready" | "blocked" | "updating" | "failed";
+    can_update: boolean;
+    reason_code?: LocalConsolePackageUpdateReason;
+    phase?: "preparing" | "stopping_hosts" | "installing" | "restarting";
+};
+export type PackageUpdateHostReadiness = {
+    status: "ready";
+    restore_project_ids: ProjectId[];
+} | {
+    status: "blocked";
+    reason_code: "host_busy" | "host_identity_unverified" | "host_update_unsupported";
+};
+export type PackageUpdatePreparationLease = {
+    handoffTo: (pid: number) => void;
+    release: () => void;
+    cancel: () => void;
+};
+export type LocalConsolePackageUpdatePreparation = {
+    installation: GlobalPackageInstallation;
+    target: PublishedPackageTarget;
+    restore_project_ids: ProjectId[];
+    lease: PackageUpdatePreparationLease;
+};
+export type BeginLocalConsolePackageUpdateResult = {
+    status: "ready";
+    preparation: LocalConsolePackageUpdatePreparation;
+} | {
+    status: "blocked";
+    update: LocalConsolePackageUpdateStatus;
+};
+type HostReadinessReader = (inspection: MachineProjectInspection) => Promise<"ready" | "busy" | "unsupported">;
+export declare function inspectPackageUpdateHosts(options: {
+    projects: readonly MachineProjectInspection[];
+    readReadiness: HostReadinessReader;
+}): Promise<PackageUpdateHostReadiness>;
+export declare class LocalConsolePackageUpdateService {
+    #private;
+    constructor(options: {
+        tuttiHome: string;
+        env?: NodeJS.ProcessEnv;
+        currentVersion?: string;
+        operations?: LocalConsoleOperationCoordinator;
+        resolveInstallation?: () => GlobalPackageInstallationResolution;
+        discover?: (resolution: GlobalPackageInstallationResolution, options: {
+            refresh?: boolean;
+        }) => Promise<PackageUpdateDiscovery>;
+        inspectProjects?: () => Promise<MachineProjectInspection[]>;
+        readReadiness?: HostReadinessReader;
+        inspectLock?: () => PackageUpdateLockInspection;
+        acquireLock?: () => PackageUpdateLockAcquisition;
+        readRecord?: () => PackageUpdateRuntimeRecordRead;
+        clearFailedRecord?: (record: Extract<PackageUpdateRuntimeRecordRead, {
+            status: "valid";
+        }>["record"]) => boolean;
+    });
+    getStatus(options?: {
+        refresh?: boolean;
+    }): Promise<LocalConsolePackageUpdateStatus>;
+    beginUpdate(): Promise<BeginLocalConsolePackageUpdateResult>;
+}
+export {};
+//# sourceMappingURL=package-update-service.d.ts.map