zcode-acp-server 0.46.7 → 0.47.0

package/dist/settings/app-update.d.ts

@@ -0,0 +1,193 @@
+/**
+ * ZCode desktop app self-update.
+ *
+ * The desktop app updates itself through Electron's autoUpdater, which needs an
+ * Electron runtime this process does not have. The parts that DO work headless
+ * are the ones that decide WHAT to install: the release manifest
+ * (`/api/v1/releases/electron/manifest`), the platform/arch/channel spelling,
+ * and the CDN download. So this module reproduces those and hands the actual
+ * install back to the OS.
+ *
+ * Whether the bundle can be swapped is PROBED, never assumed (see
+ * `canWriteInstallLocation`): the obvious reading of `/Applications`'s
+ * `drwxrwxr-x root:admin` is that an admin user cannot write it, yet the
+ * installed `ZCode.app` is user-owned on the machine this was written for — so
+ * the code branches on `accessSync` and is correct either way, and no claim is
+ * made about which branch a given install takes. What is deliberately NOT done
+ * is privileged escalation (a password prompt, a Finder Apple Event, a shipped
+ * privileged helper): a long-lived daemon has no good place to ask, and the
+ * one-shot confirmation macOS raises when a user drags a bundle into place is
+ * already the right amount of trust.
+ *
+ * What the flow does NOT do is silently swap a running app. The app is replaced
+ * on disk while it may be running, and the user is told to quit and reopen —
+ * attempting to kill the app from here would be both rude and unsafe (it may
+ * have an in-flight session whose state lives in the app process).
+ */
+import { rename } from "node:fs/promises";
+/** Channel → the API's numeric spelling (manifestUpdateProvider.ts:41-42). */
+declare const CHANNEL_VALUES: {
+    readonly stable: 1;
+    readonly preview: 3;
+};
+export type ReleaseChannel = keyof typeof CHANNEL_VALUES;
+/** Node platform → the manifest's spelling (manifestUpdateProvider.ts:57-68). */
+export declare function releasePlatform(platform: NodeJS.Platform, arch: string): string;
+/** One downloadable artifact the manifest offers. */
+export interface ReleaseFile {
+    url: string;
+    sha512?: string;
+    size?: number;
+}
+export interface ReleaseManifest {
+    version: string;
+    releaseName?: string;
+    releaseNotes?: string;
+    releaseNotesByLocale?: Record<string, {
+        title?: string;
+        markdown?: string;
+    }>;
+    files: ReleaseFile[];
+    /** The single-artifact fallback electron-updater uses when no arch matches. */
+    path?: string;
+}
+export interface UpdateCheck {
+    /** True when the manifest offers a strictly newer version. */
+    updateAvailable: boolean;
+    currentVersion: string | null;
+    latestVersion: string | null;
+    channel: ReleaseChannel;
+    platform: string;
+    /** Populated only when an update is available. */
+    release?: ReleaseManifest;
+}
+/**
+ * Where the app is installed, or null when it is not found.
+ *
+ * `ZCODE_APP_PATH` overrides the whole lookup so a test (or a non-standard
+ * install) can point somewhere safe. The candidate list mirrors the table in
+ * `backend/resolve.ts`: /Applications first, then the per-user location, then
+ * the Linux prefixes.
+ */
+export declare function appBundlePath(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * The installed app's version, read from its bundle.
+ *
+ * macOS: `CFBundleShortVersionString` out of `Info.plist`, parsed without a
+ * plist library (the file is XML for these builds; a binary plist falls back to
+ * `defaults read`, which handles both). Windows: the file version of the .exe.
+ * Linux: null — there is no reliable in-bundle version.
+ */
+export declare function installedAppVersion(appPath: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): Promise<string | null>;
+/**
+ * Compare two version strings numerically, segment by segment.
+ *
+ * Local on purpose: `utils.compareVersions` is fine for semver-ish strings but
+ * the manifest can carry a build suffix (`3.14.1.7714`), and comparing
+ * `7714` against a missing segment must not flip the result.
+ */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+/**
+ * Parse the manifest YAML.
+ *
+ * The manifest is a small, fixed-shape document (version + files + release
+ * notes), so a real YAML parser would be a dependency for no benefit. This
+ * reader handles exactly the shapes the endpoint emits: a flat top level, a
+ * `files:` list of mappings, and the `releaseNotesByLocale` nesting. Block
+ * scalars (`|-`) are collected by indentation.
+ *
+ * Anything it does not understand throws rather than guessing — a misparsed
+ * manifest would install the wrong build.
+ */
+export declare function parseManifest(raw: string): ReleaseManifest;
+/**
+ * Pick the artifact to download for this platform.
+ *
+ * macOS prefers the zip (it extracts to a bundle directly and needs no mount);
+ * Windows takes the exe; Linux takes the distro package. Falls back to the
+ * manifest's top-level `path`, which is what electron-updater itself uses when
+ * no per-arch entry matches.
+ */
+export declare function pickReleaseFile(manifest: ReleaseManifest): ReleaseFile | null;
+/**
+ * Fetch and parse the release manifest.
+ *
+ * `fetchImpl` defaults to the module seam (not bare `fetch`) so a test that
+ * overrides the network also covers this path, not just `checkForAppUpdate`.
+ */
+export declare function fetchReleaseManifest(channel: ReleaseChannel, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch): Promise<ReleaseManifest>;
+/** Override the update network. Pass `fetch` to restore the default. */
+export declare function setManifestNetworkForTest(impl: typeof fetch): void;
+/** Override the platform the update flows run as (test seam). */
+export declare function setAppUpdatePlatformForTest(platform: NodeJS.Platform): void;
+/**
+ * Compare the installed app against the manifest.
+ *
+ * A missing install (the bridge running on a machine without the app) is not an
+ * error: `updateAvailable` stays false and `currentVersion` is null, so the
+ * client can hide the row instead of showing a failure.
+ */
+export declare function checkForAppUpdate(options?: {
+    channel?: ReleaseChannel;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+}): Promise<UpdateCheck>;
+export interface DownloadProgress {
+    receivedBytes: number;
+    totalBytes: number | null;
+}
+export interface DownloadResult {
+    file: string;
+    sha512: string;
+    sizeBytes: number;
+    /** True when the hash matched the manifest's `sha512`. */
+    verified: boolean;
+}
+/**
+ * Download an artifact into a temp directory, streaming and hashing as it goes.
+ *
+ * The hash is verified before anything is installed: a truncated or tampered
+ * download that failed here is a failed download, not a bad install.
+ *
+ * The body is consumed as a web `ReadableStream` (what `fetch` returns), not a
+ * Node stream — `pipe` does not exist on it.
+ */
+export declare function downloadRelease(file: ReleaseFile, options?: {
+    destDir?: string;
+    fetchImpl?: typeof fetch;
+    onProgress?: (p: DownloadProgress) => void;
+}): Promise<DownloadResult>;
+export type InstallStage = "idle" | "downloading" | "installing" | "done" | "needs-user-install" | "failed";
+export interface InstallState {
+    stage: InstallStage;
+    version: string | null;
+    receivedBytes: number;
+    totalBytes: number | null;
+    /**
+     * Where the verified bundle is, for `needs-user-install`. The client shows
+     * this path (or reveals it in Finder) so the user can finish the install
+     * themselves.
+     */
+    artifactPath?: string;
+    /** True on `done`: the new build is on disk and the app must be reopened. */
+    restartRequired?: boolean;
+    error?: string;
+}
+/** Current install state — the endpoint reports it verbatim. */
+export declare function appUpdateState(): InstallState;
+/** Override the unzip used by the installer (test seam). */
+export declare function setExtractForTest(impl: (zipPath: string, destDir: string) => Promise<void>): void;
+/** Restore the platform's own unzip (test seam). */
+export declare function resetExtractForTest(): void;
+/** Override the rename used by the installer (test seam). */
+export declare function setInstallRenameForTest(impl: typeof rename): void;
+export declare function startAppUpdate(file: ReleaseFile, version: string, options?: {
+    channel?: ReleaseChannel;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    fetchImpl?: typeof fetch;
+}): Promise<InstallState>;
+/** Clear the stored install state (test seam). */
+export declare function resetAppUpdateStateForTest(): void;
+export {};
+//# sourceMappingURL=app-update.d.ts.map

package/dist/settings/app-update.d.ts.map

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