Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

13.8 KB
Raw Blame
/**
 * The version routes and the update check behind the About page.
 *
 * - GET /api/version needs a session and serves exactly the report `penguin version --json`
 *   prints; a root with nothing pushed reports no harness, and a pushed one reports its store.
 * - The update check reports a newer release with its URL and date; an unreachable endpoint
 *   is still a 200, carrying `error: network` instead of a 5xx.
 * - A plain check is answered from the cache; `?force=1` (the manual check) bypasses it and
 *   the fresh outcome is what later plain checks see.
 * - A rate-limit answer reads as rate_limited, any other bad status or body as bad_response;
 *   a latest release that is not newer is no update.
 * - ADELIE_UPDATE_CHECK=off answers disabled and never dials out, forced or not.
 * - A success is cached for an hour and a failure for ten minutes.
 * - The update job is admin-only; before any run it is idle, and a server not launched through
 *   the CLI finishes it at once as unsupported, readable afterwards.
 * - A restart is admin-only and refused when nothing supervises the process.
 *
 * Nothing here touches the network or spawns a process: the release lookup is the fetch fake.
 */
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import fs from "node:fs/promises";
import path from "node:path";
import { VERSION } from "@adelie/core";
import { versionReport } from "../src/version-report.js";
import type {
  RestartResponse,
  UpdateCheckResponse,
  UpdateJobStatus,
  UpdateRunResponse,
  VersionResponse,
} from "../src/api/types.js";
import {
  FAILURE_TTL_MS,
  SUCCESS_TTL_MS,
  UpdateCheckService,
} from "../src/services/update-check-service.js";
import { fakeFetch } from "./fixtures/fetch.js";
import type { FetchScript } from "./fixtures/fetch.js";
import { apiClient, createTestApp, loginAdmin, provisionUser } from "./helpers.js";
import type { TestApp } from "./helpers.js";
import { wire } from "@adelie/core/kernel";

function releaseResponse(tag: string): Response {
  return new Response(
    JSON.stringify({
      tag_name: tag,
      html_url: `https://github.com/Prism-Shadow/penguin-harness/releases/tag/${tag}`,
      published_at: "2026-07-01T00:00:00Z",
    }),
    { status: 200, headers: { "content-type": "application/json" } },
  );
}

/** An update-check service over the fetch fake; `calls` counts the lookups that reached it. */
function updateCheck(
  script: FetchScript,
  env: Record<string, string> = {},
  now: () => Date = () => new Date(),
) {
  const releases = fakeFetch(script);
  const service = wire(UpdateCheckService, {
    http: { fetch: releases.fetch },
    env,
    clock: { now },
  });
  return { service, calls: () => releases.calls.length };
}

describe("GET /api/version", () => {
  let t: TestApp;
  beforeEach(async () => {
    t = await createTestApp();
  });
  afterEach(async () => {
    await t.cleanup();
  });

  it("requires auth and serves the version report unchanged", async () => {
    expect((await t.app.request("/api/version")).status).toBe(401);

    const admin = await loginAdmin(t.app);
    const res = await apiClient(t.app, admin.cookie).get("/api/version");
    expect(res.status).toBe(200);
    const body = (await res.json()) as VersionResponse;
    // Compared against the producer, never against literals. The release workflow STAMPS
    // core's constants before it builds and tests, so a hardcoded null passes everywhere
    // except the one job that matters — the npm publish — where it failed the release.
    // This is also the contract that `penguin version --json` prints the same record: the
    // route adds no field of its own and drops none.
    expect(body).toEqual(await versionReport(t.root));
    // Non-vacuous floor, in case the report itself ever comes back degenerate.
    expect(body.version).toBe(VERSION);
    // `v` and a digit is the whole guarantee: a tag description names the nearest reachable
    // tag, which is the PREVIOUS version throughout release preparation (VERSION is bumped
    // in its own commit, the tag follows), so pinning `v${VERSION}` would fail on exactly
    // the branch that cuts a release.
    expect(body.describe).toMatch(/^v\d/);
    expect(["release", "source"]).toContain(body.channel);
  });

  it("reports no harness for a root with nothing pushed, and the store's once there is", async () => {
    const admin = await loginAdmin(t.app);
    const get = async () =>
      (await (await apiClient(t.app, admin.cookie).get("/api/version")).json()) as VersionResponse;

    // A fresh test root has an empty HMR store: the build is packaged, not hot-updated.
    expect((await get()).harness).toBeNull();

    const hmrDir = path.join(t.root, "hmr");
    await fs.mkdir(hmrDir, { recursive: true });
    await fs.writeFile(
      path.join(hmrDir, "harness.json"),
      JSON.stringify({
        cli: { bundle: "store/cli/abc123.mjs" },
        source: { repo: "https://example.com/penguin.git", revision: "v0.2.3-7-gabc1234" },
        pushedAt: "2026-08-20T10:15:00.000Z",
      }),
    );

    expect((await get()).harness).toEqual({
      source: { repo: "https://example.com/penguin.git", revision: "v0.2.3-7-gabc1234" },
      pushedAt: "2026-08-20T10:15:00.000Z",
      bundles: { platform: null, cli: "store/cli/abc123.mjs", web: null },
    });
  });
});

describe("GET /api/version/update-check", () => {
  let t: TestApp;
  afterEach(async () => {
    await t.cleanup();
  });

  it("reports a newer release with its URL and publish date", async () => {
    t = await createTestApp({ updateCheck: updateCheck(() => releaseResponse("v99.0.0")).service });
    const admin = await loginAdmin(t.app);
    const res = await apiClient(t.app, admin.cookie).get("/api/version/update-check");
    expect(res.status).toBe(200);
    const body = (await res.json()) as UpdateCheckResponse;
    expect(body.currentVersion).toBe(VERSION);
    expect(body.latestVersion).toBe("99.0.0");
    expect(body.updateAvailable).toBe(true);
    expect(body.releaseUrl).toBe(
      "https://github.com/Prism-Shadow/penguin-harness/releases/tag/v99.0.0",
    );
    expect(body.publishedAt).toBe("2026-07-01T00:00:00Z");
    expect(body.error).toBeUndefined();
    expect(body.disabled).toBeUndefined();
  });

  it("answers an unreachable endpoint with a 200 carrying error=network, not a 5xx", async () => {
    const { service } = updateCheck(() => {
      throw new Error("getaddrinfo ENOTFOUND api.github.com");
    });
    t = await createTestApp({ updateCheck: service });
    const admin = await loginAdmin(t.app);
    const res = await apiClient(t.app, admin.cookie).get("/api/version/update-check");
    expect(res.status).toBe(200);
    const body = (await res.json()) as UpdateCheckResponse;
    expect(body.error).toBe("network");
    expect(body.latestVersion).toBeNull();
    expect(body.updateAvailable).toBe(false);
    expect(body.releaseUrl).toBeNull();
  });

  it("answers a plain check from the cache, and ?force=1 refetches and recaches", async () => {
    let tag = "v99.0.0";
    const check = updateCheck(() => releaseResponse(tag));
    t = await createTestApp({ updateCheck: check.service });
    const admin = await loginAdmin(t.app);
    const client = apiClient(t.app, admin.cookie);
    const latest = async (url: string) =>
      ((await (await client.get(url)).json()) as UpdateCheckResponse).latestVersion;

    // Warm the cache, then confirm a plain GET serves from it.
    expect(await latest("/api/version/update-check")).toBe("99.0.0");
    expect(await latest("/api/version/update-check")).toBe("99.0.0");
    expect(check.calls()).toBe(1);

    // The manual check refetches despite the fresh cache…
    tag = "v100.0.0";
    expect(await latest("/api/version/update-check?force=1")).toBe("100.0.0");
    expect(check.calls()).toBe(2);
    // …and stores what it found: the next plain check reuses it without a call.
    expect(await latest("/api/version/update-check")).toBe("100.0.0");
    expect(check.calls()).toBe(2);
  });
});

describe("UpdateCheckService", () => {
  it("reads 403/429 as rate_limited and any other bad status or body as bad_response", async () => {
    for (const [make, expected] of [
      [() => new Response("limited", { status: 403 }), "rate_limited"],
      [() => new Response("limited", { status: 429 }), "rate_limited"],
      [() => new Response("oops", { status: 500 }), "bad_response"],
      [() => new Response("not json", { status: 200 }), "bad_response"],
      [() => new Response(JSON.stringify({ name: "no tag" }), { status: 200 }), "bad_response"],
    ] as const) {
      const result = await updateCheck(make).service.check();
      expect(result.error).toBe(expected);
      expect(result.updateAvailable).toBe(false);
      expect(result.latestVersion).toBeNull();
    }
  });

  it("reports no update when the latest release is not newer", async () => {
    const result = await updateCheck(() => releaseResponse(`v${VERSION}`)).service.check();
    expect(result.error).toBeUndefined();
    expect(result.latestVersion).toBe(VERSION);
    expect(result.updateAvailable).toBe(false);
  });

  it("never dials out under ADELIE_UPDATE_CHECK=off, forced or not", async () => {
    const check = updateCheck(() => releaseResponse("v99.0.0"), { ADELIE_UPDATE_CHECK: "off" });
    for (const force of [false, true]) {
      const result = await check.service.check(force);
      expect(result.disabled).toBe(true);
      expect(result.updateAvailable).toBe(false);
      expect(result.latestVersion).toBeNull();
    }
    expect(check.calls()).toBe(0);
  });

  it("caches a success for an hour and a failure for ten minutes", async () => {
    let nowMs = 1_000_000_000;
    let fail = false;
    const check = updateCheck(
      () => {
        if (fail) throw new Error("down");
        return releaseResponse("v99.0.0");
      },
      {},
      () => new Date(nowMs),
    );
    const service = check.service;

    const first = await service.check();
    expect(first.latestVersion).toBe("99.0.0");
    expect(check.calls()).toBe(1);

    // Within the success TTL: served from cache, original checkedAt preserved.
    nowMs += SUCCESS_TTL_MS - 1;
    const cached = await service.check();
    expect(check.calls()).toBe(1);
    expect(cached.checkedAt).toBe(first.checkedAt);

    // Past the success TTL: refetched; the failure is itself cached, but only briefly.
    nowMs += 2;
    fail = true;
    const failed = await service.check();
    expect(check.calls()).toBe(2);
    expect(failed.error).toBe("network");

    nowMs += FAILURE_TTL_MS - 1;
    expect((await service.check()).error).toBe("network");
    expect(check.calls()).toBe(2);

    nowMs += 2;
    fail = false;
    const healed = await service.check();
    expect(check.calls()).toBe(3);
    expect(healed.error).toBeUndefined();
    expect(healed.latestVersion).toBe("99.0.0");
  });
});

describe("POST /api/version/update", () => {
  let t: TestApp;
  let savedEntry: string | undefined;
  let savedRenamed: string | undefined;
  beforeEach(async () => {
    // Both spellings: the route reads ADELIE_CLI_ENTRY first and PENGUIN_CLI_ENTRY after it
    // (core's state/boundary-env.ts), so clearing only one of them would leave the other
    // leaking in from the environment the test was started with.
    savedEntry = process.env.PENGUIN_CLI_ENTRY;
    savedRenamed = process.env.ADELIE_CLI_ENTRY;
    delete process.env.PENGUIN_CLI_ENTRY;
    delete process.env.ADELIE_CLI_ENTRY;
    t = await createTestApp();
  });
  afterEach(async () => {
    if (savedEntry === undefined) delete process.env.PENGUIN_CLI_ENTRY;
    else process.env.PENGUIN_CLI_ENTRY = savedEntry;
    if (savedRenamed === undefined) delete process.env.ADELIE_CLI_ENTRY;
    else process.env.ADELIE_CLI_ENTRY = savedRenamed;
    await t.cleanup();
  });

  it("is admin-only both ways, and idle before any run", async () => {
    const user = apiClient(t.app, (await provisionUser(t.app, "regular_user")).cookie);
    expect((await user.post("/api/version/update", {})).status).toBe(403);
    expect((await user.get("/api/version/update")).status).toBe(403);
    const admin = await loginAdmin(t.app);
    const res = await apiClient(t.app, admin.cookie).get("/api/version/update");
    expect(res.status).toBe(200);
    expect((await res.json()) as UpdateJobStatus).toEqual({
      state: "idle",
      targetVersion: null,
      output: "",
    });
  });

  it("reports unsupported when the server was not launched via the CLI", async () => {
    const admin = await loginAdmin(t.app);
    const res = await apiClient(t.app, admin.cookie).post("/api/version/update", {});
    expect(res.status).toBe(200);
    const body = (await res.json()) as UpdateJobStatus;
    expect(body.state).toBe("done");
    expect(body.result).toEqual({
      status: "unsupported",
      reason: "not_launched_via_cli",
      output: "",
      needsRestart: false,
    } satisfies UpdateRunResponse);
    // The finished status stays readable at GET until the next start.
    const again = await apiClient(t.app, admin.cookie).get("/api/version/update");
    expect(((await again.json()) as UpdateJobStatus).result?.status).toBe("unsupported");
  });
});

describe("POST /api/version/restart", () => {
  it("is admin-only, and refuses when nothing supervises the process", async () => {
    // Tests boot unsupervised (ADELIE_SUPERVISED unset): exiting would stop a service nobody
    // brings back, so the route says so instead of leaving.
    const t = await createTestApp();
    try {
      const user = await provisionUser(t.app, "regular_user");
      expect((await apiClient(t.app, user.cookie).post("/api/version/restart", {})).status).toBe(
        403,
      );
      const admin = await loginAdmin(t.app);
      const res = await apiClient(t.app, admin.cookie).post("/api/version/restart", {});
      expect(res.status).toBe(200);
      expect((await res.json()) as RestartResponse).toEqual({
        restarting: false,
        reason: "no_supervisor",
      });
    } finally {
      await t.cleanup();
    }
  });
});