@checkstack/script-packages-backend 0.2.0

package/src/install-controller.test.ts

@@ -0,0 +1,257 @@
+import { describe, expect, test } from "bun:test";
+import type { ManifestEntry } from "@checkstack/script-packages-common";
+import { runInstallNow, type InstallControllerDeps } from "./install-controller";
+import type {
+  InstallStateStore,
+  InstallerLock,
+} from "./install-state-store";
+
+const entry: ManifestEntry = { name: "a", version: "1.0.0", integrity: "sha-a" };
+
+function fakeState(): {
+  store: InstallStateStore;
+  calls: string[];
+} {
+  const calls: string[] = [];
+  return {
+    calls,
+    store: {
+      load: async () => ({
+        status: "idle",
+        lockfileHash: null,
+        manifest: [],
+        totalSizeBytes: 0,
+        lastInstalledAt: null,
+        errorMessage: null,
+      }),
+      setInstalling: async () => void calls.push("installing"),
+      setReady: async () => void calls.push("ready"),
+      setError: async (m) => void calls.push(`error:${m}`),
+    },
+  };
+}
+
+/**
+ * SHARED single-token installer-election lock — a faithful in-memory model
+ * of the Postgres advisory lock guarding installer election across pods.
+ * ONE boolean (`heldBy`) is shared across every caller wired to the same
+ * instance, mirroring `advisory-lock.test.ts`'s `heldBy` model:
+ *
+ *   - `tryInstallerLock` grants ONLY if the token is free; it then binds the
+ *     token to the acquiring handle and returns a `release()` that frees it.
+ *   - A concurrent caller against the SAME instance gets `null` while held.
+ *
+ * `calls?.push("released")` records releases so the always-frees invariant
+ * stays observable for the single-caller suite.
+ */
+function makeSharedInstallerLock(calls?: string[]): InstallerLock {
+  // `null` = free; otherwise the id of the holding handle.
+  const state: { heldBy: number | null } = { heldBy: null };
+  let nextHandleId = 0;
+  return {
+    tryInstallerLock: async () => {
+      if (state.heldBy !== null) return null;
+      const handleId = nextHandleId++;
+      state.heldBy = handleId;
+      let released = false;
+      return {
+        release: async () => {
+          if (released) return;
+          released = true;
+          // Only the holder frees the shared token (no-op otherwise).
+          if (state.heldBy === handleId) state.heldBy = null;
+          calls?.push("released");
+        },
+      };
+    },
+  };
+}
+
+function baseDeps(
+  overrides: Partial<InstallControllerDeps> = {},
+): { deps: InstallControllerDeps; emitted: string[]; stateCalls: string[] } {
+  const emitted: string[] = [];
+  const { store, calls } = fakeState();
+  const deps: InstallControllerDeps = {
+    installState: store,
+    installerLock: makeSharedInstallerLock(calls),
+    resolver: { resolve: async () => [{ entry, blob: new Uint8Array(10) }] },
+    blobStore: {
+      id: "postgres",
+      has: async () => false,
+      put: async () => {},
+    },
+    blobIndex: { record: async () => {} },
+    loadInstallInputs: async () => ({
+      packages: [{ name: "a", version: "1.0.0", enabled: true }],
+      ignoreScripts: true,
+    }),
+    sizeCap: async () => ({
+      warnBytes: 150 * 1024 * 1024,
+      blockBytes: 300 * 1024 * 1024,
+    }),
+    isMigrationInFlight: async () => false,
+    emitChanged: async ({ lockfileHash }) => void emitted.push(lockfileHash),
+    ...overrides,
+  };
+  return { deps, emitted, stateCalls: calls };
+}
+
+describe("runInstallNow", () => {
+  test("installs, records ready, and emits changed", async () => {
+    const { deps, emitted, stateCalls } = baseDeps();
+    const out = await runInstallNow(deps);
+    expect(out.started).toBe(true);
+    expect(stateCalls).toContain("installing");
+    expect(stateCalls).toContain("ready");
+    expect(stateCalls).toContain("released");
+    expect(emitted).toHaveLength(1);
+  });
+
+  test("refuses while a storage migration is in flight", async () => {
+    const { deps } = baseDeps({ isMigrationInFlight: async () => true });
+    const out = await runInstallNow(deps);
+    expect(out.started).toBe(false);
+    expect(out.reason).toMatch(/migration/i);
+  });
+
+  test("refuses when the installer lock is held by another instance", async () => {
+    const emitted: string[] = [];
+    // Model "another instance holds it": pre-acquire the shared token so the
+    // controller's own attempt is refused.
+    const sharedLock = makeSharedInstallerLock();
+    const held = await sharedLock.tryInstallerLock();
+    expect(held).not.toBeNull();
+    const { deps } = baseDeps({ installerLock: sharedLock });
+    deps.emitChanged = async ({ lockfileHash }) =>
+      void emitted.push(lockfileHash);
+    const out = await runInstallNow(deps);
+    expect(out.started).toBe(false);
+    expect(out.reason).toMatch(/another instance/i);
+    expect(emitted).toHaveLength(0);
+  });
+
+  test("two concurrent installers against the SAME shared lock: exactly one wins", async () => {
+    // ── Multi-instance election contention ──
+    // One shared single-token lock across BOTH callers (two pods racing
+    // `installNow`). Each pod gets its own deps/state, but they contend on
+    // the SAME advisory lock — exactly one may proceed.
+    const sharedLock = makeSharedInstallerLock();
+
+    // Widen the acquire→install→release window with a real async gap so the
+    // loser genuinely attempts acquire while the winner still holds the
+    // token (the interleaving that would double-install without a shared
+    // lock).
+    const slowResolver = {
+      resolve: async () => {
+        await new Promise((r) => setTimeout(r, 10));
+        return [{ entry, blob: new Uint8Array(10) }];
+      },
+    };
+
+    const a = baseDeps({ installerLock: sharedLock, resolver: slowResolver });
+    const b = baseDeps({ installerLock: sharedLock, resolver: slowResolver });
+
+    const [outA, outB] = await Promise.all([
+      runInstallNow(a.deps),
+      runInstallNow(b.deps),
+    ]);
+
+    const started = [outA, outB].filter((o) => o.started);
+    const refused = [outA, outB].filter((o) => !o.started);
+    expect(started).toHaveLength(1);
+    expect(refused).toHaveLength(1);
+    expect(refused[0]!.reason).toMatch(/another instance/i);
+
+    // The winner recorded installing → ready exactly once; the loser never
+    // touched its install state (no installing/ready) and never emitted.
+    const winner = outA.started ? a : b;
+    const loser = outA.started ? b : a;
+    expect(winner.stateCalls.filter((c) => c === "installing")).toHaveLength(1);
+    expect(winner.stateCalls.filter((c) => c === "ready")).toHaveLength(1);
+    expect(winner.emitted).toHaveLength(1);
+    expect(loser.stateCalls).not.toContain("installing");
+    expect(loser.stateCalls).not.toContain("ready");
+    expect(loser.emitted).toHaveLength(0);
+  });
+
+  test("blocks + records error when over the size cap", async () => {
+    const { deps, emitted, stateCalls } = baseDeps({
+      resolver: {
+        resolve: async () => [
+          { entry, blob: new Uint8Array(400 * 1024 * 1024) },
+        ],
+      },
+    });
+    const out = await runInstallNow(deps);
+    expect(out.started).toBe(false);
+    expect(out.reason).toMatch(/exceeds/i);
+    expect(stateCalls.some((c) => c.startsWith("error:"))).toBe(true);
+    expect(stateCalls).toContain("released");
+    expect(emitted).toHaveLength(0);
+  });
+
+  test("on a thrown install error, persists the message but logs the full stack", async () => {
+    const logged: string[] = [];
+    const boom = new Error("kaboom");
+    const { deps, stateCalls } = baseDeps({
+      resolver: {
+        resolve: async () => {
+          throw boom;
+        },
+      },
+      logger: { debug: () => {}, error: (m) => void logged.push(m) },
+    });
+    const out = await runInstallNow(deps);
+
+    expect(out.started).toBe(false);
+    // The persisted, user-facing install-state message is just the message.
+    expect(stateCalls).toContain("error:kaboom");
+    // The log carries the full stack so a non-reproducible failure is
+    // pinpointable to its throw site (not merely the message).
+    expect(logged).toHaveLength(1);
+    expect(logged[0]).toBe(`Script package install failed: ${boom.stack}`);
+    expect(logged[0]).toContain("install-controller.test");
+    expect(stateCalls).toContain("released");
+  });
+
+  test("records lockfile history on a successful install", async () => {
+    const recorded: string[] = [];
+    const { deps } = baseDeps({
+      recordHistory: async ({ lockfileHash }) =>
+        void recorded.push(lockfileHash),
+    });
+    const out = await runInstallNow(deps);
+    expect(out.started).toBe(true);
+    expect(recorded).toHaveLength(1);
+  });
+
+  test("a history-record failure does NOT fail an otherwise-successful install", async () => {
+    const { deps, emitted } = baseDeps({
+      recordHistory: async () => {
+        throw new Error("history table missing");
+      },
+    });
+    const out = await runInstallNow(deps);
+    expect(out.started).toBe(true);
+    // The change hook still fires; the install succeeded.
+    expect(emitted).toHaveLength(1);
+  });
+
+  test("records error + releases lock on a resolve failure", async () => {
+    const { deps, stateCalls } = baseDeps({
+      resolver: {
+        resolve: async () => {
+          throw new Error("registry unreachable");
+        },
+      },
+    });
+    const out = await runInstallNow(deps);
+    expect(out.started).toBe(false);
+    expect(out.reason).toBe("registry unreachable");
+    expect(stateCalls.some((c) => c.includes("registry unreachable"))).toBe(
+      true,
+    );
+    expect(stateCalls).toContain("released");
+  });
+});

package/src/install-controller.ts

@@ -0,0 +1,144 @@
+import { extractErrorMessage } from "@checkstack/common";
+import type {
+  ManifestEntry,
+  PackageSpec,
+  SizeCapConfig,
+} from "@checkstack/script-packages-common";
+import {
+  performInstall,
+  type BlobIndex,
+  type BlobPublisher,
+  type Resolver,
+} from "./install-service";
+import type { InstallStateStore, InstallerLock } from "./install-state-store";
+import { evaluateSizeCap } from "./size-cap";
+
+/**
+ * Coordinates one `installNow`: installer election (advisory lock), resolve
+ * + publish, size-cap enforcement, install-state persistence, and emitting
+ * `script-packages.changed`. Refuses to run while a storage migration is in
+ * flight.
+ *
+ * All collaborators are injected so the orchestration is unit-testable
+ * without a DB, a registry, or a real blob store.
+ */
+
+export interface InstallControllerDeps {
+  installState: InstallStateStore;
+  installerLock: InstallerLock;
+  resolver: Resolver;
+  blobStore: BlobPublisher;
+  blobIndex: BlobIndex;
+  /** Enabled allowlist + registry ignore-scripts flag at install time. */
+  loadInstallInputs(): Promise<{
+    packages: PackageSpec[];
+    ignoreScripts: boolean;
+  }>;
+  sizeCap(): Promise<SizeCapConfig>;
+  /** True while a storage migration is in flight (blocks installs). */
+  isMigrationInFlight(): Promise<boolean>;
+  /** Emit `script-packages.changed { lockfileHash }` after a successful install. */
+  emitChanged(input: { lockfileHash: string }): Promise<void>;
+  /**
+   * Record the just-installed manifest in lockfile history so the blob GC can
+   * compute its retained set (current + previous N). Best-effort: a failure
+   * here must not fail the install, but it must not silently throw either.
+   */
+  recordHistory?(input: {
+    lockfileHash: string;
+    manifest: ManifestEntry[];
+  }): Promise<void>;
+  logger?: { debug(msg: string): void; error(msg: string): void };
+}
+
+export interface InstallOutcome {
+  started: boolean;
+  reason?: string;
+}
+
+/**
+ * Run an install if eligible. Returns `{ started: false, reason }` when
+ * refused (migration in flight, another installer holds the lock, or the
+ * resolved size exceeds the block threshold). The advisory lock is always
+ * released.
+ */
+export async function runInstallNow(
+  deps: InstallControllerDeps,
+): Promise<InstallOutcome> {
+  if (await deps.isMigrationInFlight()) {
+    return {
+      started: false,
+      reason: "A storage migration is in progress; try again once it completes.",
+    };
+  }
+
+  const lock = await deps.installerLock.tryInstallerLock();
+  if (!lock) {
+    return {
+      started: false,
+      reason: "Another instance is currently installing.",
+    };
+  }
+
+  try {
+    await deps.installState.setInstalling();
+
+    const { packages, ignoreScripts } = await deps.loadInstallInputs();
+    const result = await performInstall({
+      packages,
+      ignoreScripts,
+      resolver: deps.resolver,
+      blobStore: deps.blobStore,
+      blobIndex: deps.blobIndex,
+    });
+
+    const cap = await deps.sizeCap();
+    const verdict = evaluateSizeCap({
+      totalSizeBytes: result.totalSizeBytes,
+      cap,
+    });
+    if (verdict.level === "block") {
+      await deps.installState.setError(verdict.message);
+      return { started: false, reason: verdict.message };
+    }
+
+    await deps.installState.setReady({
+      lockfileHash: result.lockfileHash,
+      manifest: result.manifest,
+      totalSizeBytes: result.totalSizeBytes,
+    });
+    // Record the manifest in lockfile history so the blob GC's retained set
+    // (current + previous N) is computable. Best-effort: a history failure
+    // must not fail an otherwise-successful install.
+    try {
+      await deps.recordHistory?.({
+        lockfileHash: result.lockfileHash,
+        manifest: result.manifest,
+      });
+    } catch (error) {
+      deps.logger?.error(
+        `Failed to record lockfile history for ${result.lockfileHash}: ${extractErrorMessage(error)}`,
+      );
+    }
+    await deps.emitChanged({ lockfileHash: result.lockfileHash });
+
+    deps.logger?.debug(
+      `Script packages installed: ${result.manifest.length} package(s), lockfile ${result.lockfileHash}.`,
+    );
+    return { started: true };
+  } catch (error) {
+    const message = extractErrorMessage(error);
+    await deps.installState.setError(message);
+    // The persisted install-state message stays user-facing (just the
+    // message), but log the full stack so a non-reproducible failure can be
+    // pinned to its exact throw site instead of guessed at.
+    const detail =
+      error !== null && typeof error === "object" && "stack" in error
+        ? String((error as { stack: unknown }).stack)
+        : message;
+    deps.logger?.error(`Script package install failed: ${detail}`);
+    return { started: false, reason: message };
+  } finally {
+    await lock.release();
+  }
+}

package/src/install-service.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+import type { ManifestEntry } from "@checkstack/script-packages-common";
+import {
+  performInstall,
+  type BlobIndex,
+  type BlobPublisher,
+  type Resolver,
+  type ResolvedPackage,
+} from "./install-service";
+import { computeLockfileHash } from "./lockfile";
+
+function resolved(entry: ManifestEntry, blobLen: number): ResolvedPackage {
+  return { entry, blob: new Uint8Array(blobLen) };
+}
+
+function fakeResolver(packages: ResolvedPackage[]): Resolver {
+  return { resolve: async () => packages };
+}
+
+function fakeBlobStore(seed: string[] = []): {
+  store: BlobPublisher;
+  puts: string[];
+} {
+  const present = new Set(seed);
+  const puts: string[] = [];
+  return {
+    puts,
+    store: {
+      id: "postgres",
+      has: async ({ integrity }) => present.has(integrity),
+      put: async ({ integrity }) => {
+        present.add(integrity);
+        puts.push(integrity);
+      },
+    },
+  };
+}
+
+function fakeIndex(): { index: BlobIndex; records: string[] } {
+  const records: string[] = [];
+  return {
+    records,
+    index: {
+      record: async ({ integrity }) => {
+        records.push(integrity);
+      },
+    },
+  };
+}
+
+const a: ManifestEntry = { name: "a", version: "1.0.0", integrity: "sha-a" };
+const b: ManifestEntry = { name: "b", version: "2.0.0", integrity: "sha-b" };
+
+describe("performInstall", () => {
+  test("publishes all blobs on a fresh store and records the index", async () => {
+    const { store, puts } = fakeBlobStore();
+    const { index, records } = fakeIndex();
+    const res = await performInstall({
+      packages: [],
+      ignoreScripts: true,
+      resolver: fakeResolver([resolved(a, 100), resolved(b, 200)]),
+      blobStore: store,
+      blobIndex: index,
+    });
+    expect(puts.sort()).toEqual(["sha-a", "sha-b"]);
+    expect(records.sort()).toEqual(["sha-a", "sha-b"]);
+    expect(res.totalSizeBytes).toBe(300);
+    expect(res.manifest).toHaveLength(2);
+    expect(res.lockfileHash).toBe(computeLockfileHash([a, b]));
+    expect(res.publishedIntegrities.sort()).toEqual(["sha-a", "sha-b"]);
+  });
+
+  test("skips publishing blobs already in the store (delta), still in the manifest", async () => {
+    const { store, puts } = fakeBlobStore(["sha-a"]);
+    const { index, records } = fakeIndex();
+    const res = await performInstall({
+      packages: [],
+      ignoreScripts: true,
+      resolver: fakeResolver([resolved(a, 100), resolved(b, 200)]),
+      blobStore: store,
+      blobIndex: index,
+    });
+    expect(puts).toEqual(["sha-b"]); // only the new one
+    expect(records).toEqual(["sha-b"]);
+    expect(res.manifest).toHaveLength(2); // both still in the manifest
+    expect(res.totalSizeBytes).toBe(300);
+    expect(res.publishedIntegrities).toEqual(["sha-b"]);
+  });
+
+  test("empty allowlist yields an empty, deterministic manifest", async () => {
+    const { store } = fakeBlobStore();
+    const { index } = fakeIndex();
+    const res = await performInstall({
+      packages: [],
+      ignoreScripts: true,
+      resolver: fakeResolver([]),
+      blobStore: store,
+      blobIndex: index,
+    });
+    expect(res.manifest).toEqual([]);
+    expect(res.totalSizeBytes).toBe(0);
+    expect(res.lockfileHash).toBe(computeLockfileHash([]));
+  });
+});

package/src/install-service.ts

@@ -0,0 +1,116 @@
+import type {
+  ManifestEntry,
+  PackageSpec,
+} from "@checkstack/script-packages-common";
+import { computeLockfileHash } from "./lockfile";
+import { blobSha256 } from "./blob-hash";
+
+/**
+ * Orchestrates a single install: resolve the pinned allowlist into a
+ * manifest, publish any new content-addressed blobs to the active blob
+ * store, and return the manifest + lockfile hash + total size.
+ *
+ * The registry-facing parts (writing package.json/.npmrc, running
+ * `bun install`, parsing the lockfile, archiving cache entries) are
+ * injected as a {@link Resolver} so this orchestration is fully
+ * unit-testable without a network or a Bun subprocess. The concrete
+ * resolver lives alongside the reconciler (it shares the cache-archive
+ * logic).
+ */
+
+export interface ResolvedPackage {
+  entry: ManifestEntry;
+  /** Compressed, content-addressed blob bytes for this package. */
+  blob: Uint8Array;
+}
+
+export interface Resolver {
+  /**
+   * Run the registry-facing resolve+install for the enabled allowlist and
+   * return the resolved packages (manifest entry + blob per package).
+   */
+  resolve(input: {
+    packages: PackageSpec[];
+    ignoreScripts: boolean;
+  }): Promise<ResolvedPackage[]>;
+}
+
+/** Minimal blob-store surface the installer needs (publish-only). */
+export interface BlobPublisher {
+  has(input: { integrity: string }): Promise<boolean>;
+  put(input: { integrity: string; bytes: Uint8Array }): Promise<void>;
+  /** Active backend id, recorded in the blob index. */
+  readonly id: string;
+}
+
+/** Records a published blob in the content-addressed index. */
+export interface BlobIndex {
+  record(input: {
+    integrity: string;
+    name: string;
+    version: string;
+    backend: string;
+    sizeBytes: number;
+  }): Promise<void>;
+}
+
+export interface InstallResult {
+  lockfileHash: string;
+  manifest: ManifestEntry[];
+  totalSizeBytes: number;
+  /** Integrities that were newly published (not already in the store). */
+  publishedIntegrities: string[];
+}
+
+/**
+ * Perform the resolve + publish step. Idempotent at the blob level: a blob
+ * already present in the active store (and any other backend, per the
+ * `has` check) is not re-published. Total size is the sum of resolved blob
+ * sizes - the figure the size guardrail checks.
+ */
+export async function performInstall({
+  packages,
+  ignoreScripts,
+  resolver,
+  blobStore,
+  blobIndex,
+}: {
+  packages: PackageSpec[];
+  ignoreScripts: boolean;
+  resolver: Resolver;
+  blobStore: BlobPublisher;
+  blobIndex: BlobIndex;
+}): Promise<InstallResult> {
+  const resolved = await resolver.resolve({ packages, ignoreScripts });
+
+  const manifest: ManifestEntry[] = [];
+  const publishedIntegrities: string[] = [];
+  let totalSizeBytes = 0;
+
+  for (const { entry, blob } of resolved) {
+    // Stamp the distributed-blob hash so every host can verify the
+    // transported bytes before extraction (the SRI `integrity` hashes the
+    // npm tarball, not our archive).
+    manifest.push({ ...entry, blobSha256: blobSha256(blob) });
+    totalSizeBytes += blob.byteLength;
+
+    if (!(await blobStore.has({ integrity: entry.integrity }))) {
+      await blobStore.put({ integrity: entry.integrity, bytes: blob });
+      await blobIndex.record({
+        integrity: entry.integrity,
+        name: entry.name,
+        version: entry.version,
+        backend: blobStore.id,
+        sizeBytes: blob.byteLength,
+      });
+      publishedIntegrities.push(entry.integrity);
+    }
+  }
+
+  return {
+    lockfileHash: computeLockfileHash(manifest),
+    manifest,
+    totalSizeBytes,
+    publishedIntegrities,
+  };
+}