Download manager phase 0: job model, persisted store, broadcast plumbing

Prep work for a durable, resumable model download queue (full spec:
persistent download center, shard-aware handling, checksum verification,
retry/backoff, bandwidth controls). This phase lays the foundation the rest
builds on:

- New app/src/download-jobs-store.ts: DownloadJob/DownloadShard records
  with a full lifecycle state machine (queued -> resolving -> downloading
  -> verifying -> installing -> ready, plus paused/failed/cancelled),
  persisted the same way every other *-store.ts in this app is
  (json-store.ts's readJson/writeJson, flat-array-per-file).

- New app/src/download-verification.ts: computeSha256 (streamed, never
  buffers a whole file — same discipline the download path itself already
  follows), hasGgufMagic (catches the case where a Range request into a CDN
  error page still matches the expected size), getDiskSpace (Node's
  fs.statfsSync, no new dependency).

- New app/src/download-queue.ts: broadcast plumbing and startup resume.
  Uses a getWindow() closure rather than a captured event.sender — the
  same pattern menu.ts/updater.ts already use, since a job needs to push
  progress at times disconnected from any single IPC invoke, potentially
  after the window that started it was replaced. resumeInterruptedJobs()
  requeues anything left in "downloading"/"resolving" state from a
  previous session (an actual restart-mid-download, not a deliberate
  pause) back to "queued" — wired into app.whenReady() after
  ollama.start() and createWindow(), fire-and-forget like the existing
  connectEnabledMcpServers() call.

The actual download worker (concurrency, retry, verification pipeline)
lands in the next phase — this one is deliberately just the durable state
+ plumbing skeleton.

30 new tests across the three new modules.

Author: voidstackloop

app/src/download-jobs-store.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from "vitest";
+import { listJobs, getJob, createJob, updateJob, deleteJob, type DownloadShard } from "./download-jobs-store";
+
+function shard(overrides: Partial<DownloadShard> = {}): DownloadShard {
+    return {
+        filename: "model.gguf",
+        path: "/models/model.gguf",
+        expectedBytes: 1000,
+        receivedBytes: 0,
+        state: "queued",
+        ...overrides,
+    };
+}
+
+describe("download-jobs-store", () => {
+    it("starts with an empty list", () => {
+        expect(listJobs()).toEqual([]);
+    });
+
+    it("creates a job with generated id, default state, and timestamps", () => {
+        const job = createJob({
+            kind: "huggingface",
+            modelName: "Test Model",
+            publisher: "test-org",
+            backend: "llamacpp",
+            destinationDir: "/models",
+            modelId: "test-org/test-model",
+            shards: [shard()],
+        });
+        expect(job.id).toBeTruthy();
+        expect(job.state).toBe("queued");
+        expect(job.retryCount).toBe(0);
+        expect(job.createdAt).toBeTruthy();
+        expect(job.updatedAt).toBe(job.createdAt);
+        expect(listJobs().map((j) => j.id)).toContain(job.id);
+    });
+
+    it("round-trips a job through getJob", () => {
+        const created = createJob({
+            kind: "huggingface",
+            modelName: "Another Model",
+            publisher: "org",
+            backend: "llamacpp",
+            destinationDir: "/models",
+            modelId: "org/another-model",
+            shards: [shard()],
+        });
+        expect(getJob(created.id)).toEqual(created);
+    });
+
+    it("returns null for an unknown job id", () => {
+        expect(getJob("does-not-exist")).toBeNull();
+    });
+
+    it("updates state, error, retryCount, and shards while bumping updatedAt", async () => {
+        const created = createJob({
+            kind: "huggingface",
+            modelName: "M",
+            publisher: "org",
+            backend: "llamacpp",
+            destinationDir: "/models",
+            modelId: "org/m",
+            shards: [shard()],
+        });
+        await new Promise((r) => setTimeout(r, 5));
+        const updatedShards = [shard({ receivedBytes: 500 })];
+        const updated = updateJob(created.id, { state: "downloading", shards: updatedShards, retryCount: 1 });
+        expect(updated?.state).toBe("downloading");
+        expect(updated?.shards).toEqual(updatedShards);
+        expect(updated?.retryCount).toBe(1);
+        expect(updated?.updatedAt).not.toBe(created.updatedAt);
+    });
+
+    it("returns null when updating an unknown job", () => {
+        expect(updateJob("does-not-exist", { state: "ready" })).toBeNull();
+    });
+
+    it("sets a typed error with kind and retryable flags", () => {
+        const created = createJob({
+            kind: "huggingface",
+            modelName: "M",
+            publisher: "org",
+            backend: "llamacpp",
+            destinationDir: "/models",
+            modelId: "org/m",
+            shards: [shard()],
+        });
+        const updated = updateJob(created.id, {
+            state: "failed",
+            error: { message: "Gated repo — accept the license first.", kind: "license_required", retryable: false },
+        });
+        expect(updated?.error).toEqual({ message: "Gated repo — accept the license first.", kind: "license_required", retryable: false });
+    });
+
+    it("deletes a job", () => {
+        const created = createJob({
+            kind: "huggingface",
+            modelName: "M",
+            publisher: "org",
+            backend: "llamacpp",
+            destinationDir: "/models",
+            modelId: "org/m",
+            shards: [shard()],
+        });
+        deleteJob(created.id);
+        expect(getJob(created.id)).toBeNull();
+    });
+
+    it("deleting an unknown job is a harmless no-op", () => {
+        expect(() => deleteJob("does-not-exist")).not.toThrow();
+    });
+});

app/src/download-jobs-store.ts

@@ -0,0 +1,110 @@
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { app } from "electron";
+import { readJson, writeJson } from "./json-store";
+
+export type DownloadJobState =
+    | "queued"
+    | "resolving"
+    | "downloading"
+    | "paused"
+    | "verifying"
+    | "installing"
+    | "ready"
+    | "failed"
+    | "cancelled";
+
+export type DownloadErrorKind =
+    | "auth_required"
+    | "license_required"
+    | "not_found"
+    | "disk_space"
+    | "permission"
+    | "verification_failed"
+    | "network"
+    | "unknown";
+
+export interface DownloadJobError {
+    message: string;
+    kind: DownloadErrorKind;
+    retryable: boolean;
+}
+
+export interface DownloadShard {
+    filename: string;
+    path: string;
+    expectedBytes: number;
+    receivedBytes: number;
+    sha256?: string;
+    etag?: string;
+    state: DownloadJobState;
+}
+
+export interface DownloadJob {
+    id: string;
+    kind: "huggingface" | "ollama";
+    modelName: string;
+    publisher: string;
+    quantization?: string;
+    backend: "llamacpp" | "mlx" | "vllm" | "ollama";
+    destinationDir: string;
+    modelId: string;
+    shards: DownloadShard[];
+    state: DownloadJobState;
+    error?: DownloadJobError;
+    retryCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+
+function filePath(): string {
+    return path.join(app.getPath("userData"), "download-jobs.json");
+}
+
+export function listJobs(): DownloadJob[] {
+    return readJson<DownloadJob[]>(filePath(), []);
+}
+
+export function getJob(id: string): DownloadJob | null {
+    return listJobs().find((j) => j.id === id) ?? null;
+}
+
+export function createJob(
+    partial: Pick<DownloadJob, "kind" | "modelName" | "publisher" | "backend" | "destinationDir" | "modelId" | "shards"> &
+        Partial<Pick<DownloadJob, "quantization">>
+): DownloadJob {
+    const now = new Date().toISOString();
+    const job: DownloadJob = {
+        id: randomUUID(),
+        state: "queued",
+        retryCount: 0,
+        createdAt: now,
+        updatedAt: now,
+        ...partial,
+    };
+    const all = listJobs();
+    all.push(job);
+    writeJson(filePath(), all);
+    return job;
+}
+
+// Callers pass whole replacement `shards` arrays rather than patching one
+// shard in place — the queue worker always has the full up-to-date shard
+// list in memory already (it's the one mutating it), so round-tripping a
+// single shard's delta through this API would just add complexity for no
+// benefit.
+export function updateJob(
+    id: string,
+    partial: Partial<Pick<DownloadJob, "state" | "error" | "retryCount" | "shards">>
+): DownloadJob | null {
+    const all = listJobs();
+    const idx = all.findIndex((j) => j.id === id);
+    if (idx === -1) return null;
+    all[idx] = { ...all[idx], ...partial, updatedAt: new Date().toISOString() };
+    writeJson(filePath(), all);
+    return all[idx];
+}
+
+export function deleteJob(id: string): void {
+    writeJson(filePath(), listJobs().filter((j) => j.id !== id));
+}

app/src/download-queue.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi } from "vitest";
+import { createJob, updateJob, listJobs, type DownloadShard, type DownloadJobState } from "./download-jobs-store";
+import { init, broadcast, resumeInterruptedJobs } from "./download-queue";
+
+function shard(overrides: Partial<DownloadShard> = {}): DownloadShard {
+    return {
+        filename: "model.gguf",
+        path: "/models/model.gguf",
+        expectedBytes: 1000,
+        receivedBytes: 0,
+        state: "queued",
+        ...overrides,
+    };
+}
+
+function makeJob(state: DownloadJobState) {
+    const job = createJob({
+        kind: "huggingface",
+        modelName: "M",
+        publisher: "org",
+        backend: "llamacpp",
+        destinationDir: "/models",
+        modelId: "org/m",
+        shards: [shard()],
+    });
+    updateJob(job.id, { state });
+    return job.id;
+}
+
+describe("download-queue: broadcast plumbing", () => {
+    it("does nothing when no window has been registered via init()", () => {
+        expect(() => broadcast()).not.toThrow();
+    });
+
+    it("sends the current job list to the registered window's webContents on broadcast", () => {
+        const send = vi.fn();
+        init(() => ({ webContents: { send } }) as never);
+        broadcast();
+        expect(send).toHaveBeenCalledWith("downloads:update", listJobs());
+    });
+});
+
+describe("resumeInterruptedJobs", () => {
+    it("requeues jobs stuck in downloading or resolving back to queued", () => {
+        const downloadingId = makeJob("downloading");
+        const resolvingId = makeJob("resolving");
+
+        resumeInterruptedJobs();
+
+        expect(listJobs().find((j) => j.id === downloadingId)?.state).toBe("queued");
+        expect(listJobs().find((j) => j.id === resolvingId)?.state).toBe("queued");
+    });
+
+    it("leaves jobs in paused, ready, failed, or cancelled untouched", () => {
+        const pausedId = makeJob("paused");
+        const readyId = makeJob("ready");
+
+        resumeInterruptedJobs();
+
+        expect(listJobs().find((j) => j.id === pausedId)?.state).toBe("paused");
+        expect(listJobs().find((j) => j.id === readyId)?.state).toBe("ready");
+    });
+});

app/src/download-queue.ts

@@ -0,0 +1,37 @@
+import type { BrowserWindow } from "electron";
+import { listJobs, updateJob } from "./download-jobs-store";
+
+// Deliberately a getWindow() closure, not a captured event.sender from one
+// ipcMain.handle invocation — jobs push progress at times disconnected from
+// any single IPC call (a download keeps running long after the request that
+// started it returned), and the window that started a job may have since
+// been closed/reopened (e.g. macOS activate-with-no-windows). Mirrors the
+// same pattern menu.ts and updater.ts already use for this exact reason.
+let windowGetter: () => BrowserWindow | null = () => null;
+
+export function init(getWindow: () => BrowserWindow | null): void {
+    windowGetter = getWindow;
+}
+
+// The one broadcast channel in the app that isn't scoped to a requestId —
+// every open window gets the full current job list whenever anything
+// changes, so the download center reflects live state regardless of which
+// page is open or when it mounted.
+export function broadcast(): void {
+    windowGetter()?.webContents.send("downloads:update", listJobs());
+}
+
+// Called once at app startup. A job left in "downloading" or "resolving"
+// can only mean the app was killed mid-download last session — not a
+// deliberate pause — so it goes back to "queued" for the worker to pick up
+// again (the underlying .part file and its recorded progress are untouched;
+// resuming is exactly what downloadGgufFile's Range-request logic already
+// does for a partial file, whatever caused the interruption).
+export function resumeInterruptedJobs(): void {
+    for (const job of listJobs()) {
+        if (job.state === "downloading" || job.state === "resolving") {
+            updateJob(job.id, { state: "queued" });
+        }
+    }
+    broadcast();
+}

app/src/download-verification.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { computeSha256, hasGgufMagic, getDiskSpace } from "./download-verification";
+
+describe("computeSha256", () => {
+    let dir: string;
+
+    beforeEach(() => {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), "download-verification-test-"));
+    });
+
+    it("matches Node's own synchronous hash of the same content", async () => {
+        const file = path.join(dir, "data.bin");
+        const content = Buffer.from("hello world".repeat(1000));
+        fs.writeFileSync(file, content);
+        const expected = createHash("sha256").update(content).digest("hex");
+        expect(await computeSha256(file)).toBe(expected);
+    });
+
+    it("rejects when the file doesn't exist", async () => {
+        await expect(computeSha256(path.join(dir, "missing.bin"))).rejects.toThrow();
+    });
+});
+
+describe("hasGgufMagic", () => {
+    let dir: string;
+
+    beforeEach(() => {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), "download-verification-test-"));
+    });
+
+    it("returns true for a file starting with the GGUF magic bytes", () => {
+        const file = path.join(dir, "model.gguf");
+        fs.writeFileSync(file, Buffer.concat([Buffer.from("GGUF"), Buffer.from([3, 0, 0, 0])]));
+        expect(hasGgufMagic(file)).toBe(true);
+    });
+
+    it("returns false for a file without the magic bytes (e.g. an HTML error page)", () => {
+        const file = path.join(dir, "not-a-model.gguf");
+        fs.writeFileSync(file, "<html><body>404</body></html>");
+        expect(hasGgufMagic(file)).toBe(false);
+    });
+
+    it("returns false for a file too short to contain the magic bytes", () => {
+        const file = path.join(dir, "tiny.gguf");
+        fs.writeFileSync(file, "GG");
+        expect(hasGgufMagic(file)).toBe(false);
+    });
+
+    it("returns false when the file doesn't exist", () => {
+        expect(hasGgufMagic(path.join(dir, "missing.gguf"))).toBe(false);
+    });
+});
+
+describe("getDiskSpace", () => {
+    it("reports positive free and total bytes for a real directory", () => {
+        const { freeBytes, totalBytes } = getDiskSpace(os.tmpdir());
+        expect(totalBytes).toBeGreaterThan(0);
+        expect(freeBytes).toBeGreaterThan(0);
+        expect(freeBytes).toBeLessThanOrEqual(totalBytes);
+    });
+});