summer-engine 4.3.0 → 4.5.0

package/dist/core/engine-install.js

@@ -218,3 +218,96 @@ export function findExtractedEngineBinary(files) {
     return (files.find((f) => /godot\.linuxbsd\..*editor|summer.*linux/i.test(basename(f))) ??
         null);
 }
+/** An install failure with its reason; the message ends in one next step. */
+export class EngineInstallError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = "EngineInstallError";
+        this.reason = reason;
+    }
+}
+/** The command every "try again" next step names. */
+export const INSTALL_RETRY = "npx -y summer-engine@latest install";
+/** The useful line of an error: for a failed shell command the last line of
+ *  its stderr ("cp: ...: Permission denied"), not "Command failed: ...". */
+export function errorDetail(err) {
+    const text = err instanceof Error ? err.message : String(err);
+    const lines = text.split("\n").map((line) => line.trim()).filter(Boolean);
+    return (lines.at(-1) ?? "unknown error").slice(0, 200);
+}
+/** A full disk and a refused write have their own reasons wherever they
+ *  happen; anything else is `fallback`. */
+export function installFailureReason(err, fallback) {
+    if (err instanceof EngineInstallError)
+        return err.reason;
+    const code = err?.code;
+    const text = err instanceof Error ? err.message : String(err);
+    if (code === "ENOSPC" || /no space left on device/i.test(text))
+        return "disk_space";
+    if (code === "EACCES" || code === "EPERM" || /permission denied|operation not permitted/i.test(text)) {
+        return "permission";
+    }
+    return fallback;
+}
+/** Turn an unexpected error into an EngineInstallError: disk_space and
+ *  permission get their own message, anything else `message(detail)`. */
+export function asInstallError(err, fallback, message) {
+    if (err instanceof EngineInstallError)
+        return err;
+    const reason = installFailureReason(err, fallback);
+    const detail = errorDetail(err);
+    if (reason === "disk_space") {
+        return new EngineInstallError(reason, `The disk ran out of space during the install (${detail}). Free up space, then run: ${INSTALL_RETRY}`);
+    }
+    if (reason === "permission") {
+        return new EngineInstallError(reason, `The install was not allowed to write a file (${detail}). Install into a folder you own: ${INSTALL_RETRY} --path <folder>`);
+    }
+    return new EngineInstallError(reason, message(detail));
+}
+/** The engine download when the server sends no content-length (the macOS DMG is about 660 MB). */
+export const DEFAULT_DOWNLOAD_BYTES = 700 * 1024 * 1024;
+/** The install folder needs about this many times the download: the unpacked
+ *  app plus the staged copy that replaces an existing one. */
+export const INSTALL_SPACE_FACTOR = 2.5;
+export function formatSize(bytes) {
+    return bytes >= 1024 ** 3 ? `${(bytes / 1024 ** 3).toFixed(1)} GB` : `${Math.round(bytes / 1024 ** 2)} MB`;
+}
+/**
+ * Refuse before the download fills the disk. Each need is a folder and the
+ * bytes it takes; needs on one volume add up (the default macOS temp folder
+ * and /Applications share the system volume). A volume whose free space
+ * cannot be read is skipped: the install tries, and ENOSPC still maps to
+ * disk_space.
+ */
+export function checkDiskSpace(needs, freeSpace) {
+    const volumes = new Map();
+    for (const need of needs) {
+        let space;
+        try {
+            space = freeSpace(need.path);
+        }
+        catch {
+            continue;
+        }
+        const entry = volumes.get(space.volume) ?? { path: need.path, bytes: 0, free: space.bytes };
+        entry.bytes += need.bytes;
+        volumes.set(space.volume, entry);
+    }
+    for (const volume of volumes.values()) {
+        if (volume.free < volume.bytes) {
+            throw new EngineInstallError("disk_space", `Not enough disk space on the volume with ${volume.path}: ${formatSize(volume.free)} free, ` +
+                `about ${formatSize(volume.bytes)} needed. Free up space, then run: ${INSTALL_RETRY}`);
+        }
+    }
+}
+/** Where the macOS engine goes: --path wins; otherwise /Applications/Summer.app,
+ *  or ~/Applications/Summer.app when this user cannot replace it there (a
+ *  standard, non-admin account). macEnginePaths looks there too, and the
+ *  install record puts it first. */
+export function chooseMacDestination(input) {
+    const destApp = macInstallDestination(input.customPath);
+    if (input.customPath?.trim() || input.canReplace(destApp))
+        return { destApp, fallback: false };
+    return { destApp: join(input.home, "Applications", "Summer.app"), fallback: true };
+}

package/dist/core/engine-installer.d.ts

@@ -0,0 +1,134 @@
+import { EngineInstallError, type FreeSpace, type InstallFailureReason } from "./engine-install.js";
+export { EngineInstallError, type InstallFailureReason };
+/** Guard a download URL from the releases endpoint. A missing/empty URL (an
+ *  outdated or misconfigured endpoint) otherwise becomes a cryptic
+ *  fetch(undefined) failure — surface it clearly with a manual fallback. */
+export declare function requireDownloadUrl(value: string | undefined, label: string): string;
+/** Verify a downloaded file's sha256 against the expected hash from the releases
+ *  endpoint. Skipped when no expected hash is published. Catches a truncated or
+ *  corrupted download (a ~700 MB install over a flaky network) before it becomes a
+ *  confusing DMG-mount / installer failure downstream. */
+export declare function verifyChecksum(actual: string, expected: string | undefined, label: string): void;
+import { parseMacBundleVersion, readMacBundleVersion } from "./launch-posture.js";
+export { parseMacBundleVersion, readMacBundleVersion };
+export declare function isSameVersion(installed: string | null, latest: string): boolean;
+export type MacInstallPlan = {
+    action: "install";
+} | {
+    action: "up-to-date";
+    version: string;
+} | {
+    action: "needs-confirmation";
+    installed: string | null;
+} | {
+    action: "refuse";
+    reason: string;
+};
+/** Decide what `summer install` may do about an existing /Applications/Summer.app.
+ *  Replacing an installed engine is destructive, so it needs --yes or a TTY
+ *  prompt; an equal version is a no-op success. */
+export declare function planMacInstall(input: {
+    exists: boolean;
+    installedVersion: string | null;
+    latestVersion: string;
+    yes: boolean;
+    isTTY: boolean;
+    /** The command that repeats this install (with its --path), for the refusal. */
+    retry?: string;
+}): MacInstallPlan;
+export type ShellExec = (command: string) => void;
+/** Replace destApp with the bundle on the mounted DMG WITHOUT a window where
+ *  no engine exists: copy to <destApp>.new first, and only after that
+ *  succeeds remove the old bundle and rename the staged copy into place. A
+ *  failed copy leaves the existing install untouched. */
+export declare function replaceMacApp(mountPoint: string, destApp: string, exec: ShellExec, staged?: string): void;
+/** The mount point hdiutil attach printed (the /Volumes/... column), or null. */
+export declare function parseMountPoint(hdiutilOutput: string): string | null;
+/** Mount the DMG and return its mount point; any failure is `mount`. */
+export declare function attachDmg(dmgPath: string, exec: (command: string) => string): string;
+/** Eject the DMG, best effort: a busy volume ("resource busy") gets one retry
+ *  with -force, and a failure here never fails an install that already
+ *  succeeded. Returns whether it ejected. */
+export declare function detachDmg(mountPoint: string, exec: (command: string) => unknown): boolean;
+/** Whether the engine executable at this path is running: pgrep on a pattern
+ *  anchored to the start of the command line, so a process that only mentions
+ *  the path in its arguments does not count. pgrep exits 1 on no match. */
+export declare function isEngineRunning(binary: string, execFile: (file: string, args: string[]) => string): boolean;
+/** Velopack Setup.exe install args. Velopack is NOT NSIS: silent install is
+ *  `--silent` and a custom directory is `--installto <dir>` (per Velopack's
+ *  setup.exe CLI). The old NSIS flags (/S, /D=) are rejected by the Velopack
+ *  installer with "unexpected argument '/S' found" — this is the wizard bug. */
+export declare function windowsInstallerArgs(customPath?: string): string;
+/** Printed after an install: the first start of a new engine is slow and silent. */
+export declare const FIRST_START_NOTE: string;
+/** Where the Velopack installer put Summer.exe: <dir>/current/Summer.exe for --path, else the default locations. */
+export declare function windowsInstalledBinary(customPath?: string, exists?: (path: string) => boolean): string | null;
+/**
+ * Download progress: rewrites one line on a terminal; elsewhere (an agent,
+ * a log file) one line per 10%, so a 700 MB download is about ten lines
+ * instead of hundreds of kilobytes.
+ */
+export declare function createProgressReporter(isTTY: boolean, write: (text: string) => void): (downloaded: number, total: number) => void;
+export interface InstallEngineOptions {
+    /** Custom install directory (macOS: <path>/Summer.app). */
+    path?: string;
+    /** Replace an older installed engine without asking. */
+    yes?: boolean;
+    /** Progress and result lines; console.log when not given. */
+    log?: (line: string) => void;
+    /** Whether a person can answer a prompt on stdin; no prompt unless true. */
+    isTTY?: boolean;
+}
+export interface InstallEngineResult {
+    /** The engine executable, or null when the Windows installer put it somewhere unknown. */
+    binary: string | null;
+    version: string | null;
+    /** The bundle (macOS) or folder the engine is in. */
+    destination: string;
+    /** Nothing was replaced: already up to date, an existing binary registered, or the update was declined. */
+    alreadyInstalled: boolean;
+}
+/** The machine around an install; tests replace any of it. */
+export interface InstallDeps {
+    platform: NodeJS.Platform;
+    arch: string;
+    /** Run a shell command and return stdout; throws with stderr in the message.
+     *  `inherit` hands the terminal to the command (the Windows installer). */
+    exec: (command: string, inherit?: boolean) => string;
+    /** Run a program without a shell (pgrep); throws on a non-zero exit. */
+    execFile: (file: string, args: string[]) => string;
+    fetch: typeof fetch;
+    freeSpace: FreeSpace;
+    canWrite: (path: string) => boolean;
+    tmpDir: string;
+    home: string;
+    env: NodeJS.ProcessEnv;
+    confirm: (question: string) => Promise<boolean>;
+    record: (binary: string, version: string | null) => Promise<void>;
+    /** Rewrite one progress line instead of printing one per 10%. */
+    stdoutIsTTY: boolean;
+}
+/**
+ * Install Summer Engine for this platform: `summer install`, and the engine
+ * step of `summer dev`. Never exits the process and asks on stdin only when
+ * `isTTY` is true; every failure is an EngineInstallError whose reason is the
+ * telemetry code and whose message ends in one next step.
+ */
+export declare function installEngine(opts: InstallEngineOptions, deps?: Partial<InstallDeps>): Promise<InstallEngineResult>;
+/** ~/.summer/install.lock: held while one install runs. A holder whose
+ *  process is gone, or that is hours old, is stale and removed. */
+export declare const INSTALL_LOCK_DIR = "install.lock";
+export type LockOwner = {
+    pid: number;
+    createdAt: number;
+};
+/**
+ * Remove a stale lock so that only one waiter wins: rename it aside (one
+ * rename of a folder succeeds), then check that the folder moved is still
+ * the stale one judged. If a live holder took the lock in between, put its
+ * lock back.
+ */
+export declare function takeOverStaleLock(lockDir: string, stale: LockOwner): void;
+export declare function downloadFile(url: string, dest: string): Promise<{
+    sha256: string;
+}>;