@frockbot/plugin-package-publisher 0.0.0 → 0.1.0

package/src/shared.ts

@@ -0,0 +1,309 @@
+export type PackageCheckStatus = "passed" | "failed";
+
+export interface PackageCheckV1 {
+  name: string;
+  status: PackageCheckStatus;
+}
+
+export interface PackageCandidateV1 {
+  source: string;
+  applicationArtifact: string;
+  checks: PackageCheckV1[];
+}
+
+export interface PublishPackageCommandV1 {
+  schemaVersion: 1;
+  commandId: string;
+  expectedRevision: number;
+  candidate: PackageCandidateV1;
+}
+
+export interface RollbackPackageCommandV1 {
+  schemaVersion: 1;
+  commandId: string;
+  expectedRevision: number;
+  packageRevision: number;
+}
+
+export interface PackageRevisionV1 {
+  packageRevision: number;
+  applicationHash: string;
+  publishedAt: string;
+  checks: PackageCheckV1[];
+}
+
+export interface PackageRevisionHistoryV1 {
+  schemaVersion: 1;
+  revision: number;
+  activePackageRevision?: number;
+  revisions: PackageRevisionV1[];
+}
+
+export interface PackagePublicationReceiptV1 {
+  schemaVersion: 1;
+  commandId: string;
+  status: "active" | "failed";
+  revision: number;
+  packageRevision?: number;
+  applicationHash?: string;
+  failure?: string;
+}
+
+export class PackagePublisherDecodeError extends Error {
+  override readonly name = "PackagePublisherDecodeError";
+}
+
+export class PackagePublisherConflictError extends Error {
+  override readonly name = "PackagePublisherConflictError";
+  constructor(readonly currentRevision: number) {
+    super(`package revision is ${currentRevision}`);
+  }
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new PackagePublisherDecodeError(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function exactKeys(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+  label: string,
+): void {
+  const expected = new Set(keys);
+  if (
+    Object.keys(value).length !== keys.length ||
+    Object.keys(value).some((key) => !expected.has(key))
+  ) {
+    throw new PackagePublisherDecodeError(
+      `${label} has unknown or missing fields`,
+    );
+  }
+}
+
+function identifier(value: unknown, label: string): string {
+  if (
+    typeof value !== "string" ||
+    value.length < 1 ||
+    value.length > 128 ||
+    !/^[A-Za-z0-9._:-]+$/.test(value)
+  ) {
+    throw new PackagePublisherDecodeError(`${label} is invalid`);
+  }
+  return value;
+}
+
+function revision(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new PackagePublisherDecodeError(`${label} is invalid`);
+  }
+  return value as number;
+}
+
+function decodeChecks(value: unknown): PackageCheckV1[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 100) {
+    throw new PackagePublisherDecodeError("checks must not be empty");
+  }
+  return value.map((entry, index) => {
+    const check = record(entry, `checks[${index}]`);
+    exactKeys(check, ["name", "status"], `checks[${index}]`);
+    const name = identifier(check.name, `checks[${index}].name`);
+    if (check.status !== "passed" && check.status !== "failed") {
+      throw new PackagePublisherDecodeError(
+        `checks[${index}].status is invalid`,
+      );
+    }
+    return { name, status: check.status };
+  });
+}
+
+export function decodePublishPackageCommandV1(
+  value: unknown,
+): PublishPackageCommandV1 {
+  const command = record(value, "publish command");
+  exactKeys(
+    command,
+    ["schemaVersion", "commandId", "expectedRevision", "candidate"],
+    "publish command",
+  );
+  if (command.schemaVersion !== 1) {
+    throw new PackagePublisherDecodeError("schemaVersion must be 1");
+  }
+  const candidate = record(command.candidate, "candidate");
+  exactKeys(
+    candidate,
+    ["source", "applicationArtifact", "checks"],
+    "candidate",
+  );
+  if (
+    typeof candidate.source !== "string" ||
+    candidate.source.length < 1 ||
+    candidate.source.length > 5_000_000
+  ) {
+    throw new PackagePublisherDecodeError("candidate source is invalid");
+  }
+  if (
+    typeof candidate.applicationArtifact !== "string" ||
+    candidate.applicationArtifact.length < 1 ||
+    candidate.applicationArtifact.length > 10_000_000
+  ) {
+    throw new PackagePublisherDecodeError(
+      "candidate application artifact is invalid",
+    );
+  }
+  return {
+    schemaVersion: 1,
+    commandId: identifier(command.commandId, "commandId"),
+    expectedRevision: revision(command.expectedRevision, "expectedRevision"),
+    candidate: {
+      source: candidate.source,
+      applicationArtifact: candidate.applicationArtifact,
+      checks: decodeChecks(candidate.checks),
+    },
+  };
+}
+
+export function decodePackageRevisionHistoryV1(
+  value: unknown,
+): PackageRevisionHistoryV1 {
+  const history = record(value, "package revision history");
+  const keys = Object.keys(history);
+  const allowed = new Set([
+    "schemaVersion",
+    "revision",
+    "activePackageRevision",
+    "revisions",
+  ]);
+  if (
+    keys.some((key) => !allowed.has(key)) ||
+    !keys.includes("schemaVersion") ||
+    !keys.includes("revision") ||
+    !keys.includes("revisions")
+  ) {
+    throw new PackagePublisherDecodeError(
+      "package revision history has unknown or missing fields",
+    );
+  }
+  if (history.schemaVersion !== 1 || !Array.isArray(history.revisions)) {
+    throw new PackagePublisherDecodeError(
+      "package revision history is invalid",
+    );
+  }
+  const revisions = history.revisions.map((entry, index) => {
+    const item = record(entry, `revisions[${index}]`);
+    exactKeys(
+      item,
+      ["packageRevision", "applicationHash", "publishedAt", "checks"],
+      `revisions[${index}]`,
+    );
+    if (
+      typeof item.applicationHash !== "string" ||
+      !item.applicationHash.startsWith("sha256:") ||
+      typeof item.publishedAt !== "string" ||
+      !Number.isFinite(Date.parse(item.publishedAt))
+    ) {
+      throw new PackagePublisherDecodeError(`revisions[${index}] is invalid`);
+    }
+    const packageRevision = revision(
+      item.packageRevision,
+      `revisions[${index}].packageRevision`,
+    );
+    if (packageRevision < 1) {
+      throw new PackagePublisherDecodeError(
+        `revisions[${index}].packageRevision is invalid`,
+      );
+    }
+    return {
+      packageRevision,
+      applicationHash: item.applicationHash,
+      publishedAt: item.publishedAt,
+      checks: decodeChecks(item.checks),
+    };
+  });
+  const activePackageRevision =
+    history.activePackageRevision === undefined
+      ? undefined
+      : revision(history.activePackageRevision, "activePackageRevision");
+  if (activePackageRevision !== undefined && activePackageRevision < 1) {
+    throw new PackagePublisherDecodeError("activePackageRevision is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    revision: revision(history.revision, "revision"),
+    ...(activePackageRevision === undefined ? {} : { activePackageRevision }),
+    revisions,
+  };
+}
+
+export function decodePackagePublicationReceiptV1(
+  value: unknown,
+): PackagePublicationReceiptV1 {
+  const receipt = record(value, "publication receipt");
+  const allowed = new Set([
+    "schemaVersion",
+    "commandId",
+    "status",
+    "revision",
+    "packageRevision",
+    "applicationHash",
+    "failure",
+  ]);
+  if (
+    Object.keys(receipt).some((key) => !allowed.has(key)) ||
+    receipt.schemaVersion !== 1 ||
+    (receipt.status !== "active" && receipt.status !== "failed")
+  ) {
+    throw new PackagePublisherDecodeError("publication receipt is invalid");
+  }
+  const result: PackagePublicationReceiptV1 = {
+    schemaVersion: 1,
+    commandId: identifier(receipt.commandId, "commandId"),
+    status: receipt.status,
+    revision: revision(receipt.revision, "revision"),
+  };
+  if (receipt.packageRevision !== undefined) {
+    result.packageRevision = revision(
+      receipt.packageRevision,
+      "packageRevision",
+    );
+  }
+  if (receipt.applicationHash !== undefined) {
+    if (typeof receipt.applicationHash !== "string") {
+      throw new PackagePublisherDecodeError("applicationHash is invalid");
+    }
+    result.applicationHash = receipt.applicationHash;
+  }
+  if (receipt.failure !== undefined) {
+    if (typeof receipt.failure !== "string") {
+      throw new PackagePublisherDecodeError("failure is invalid");
+    }
+    result.failure = receipt.failure;
+  }
+  return result;
+}
+
+export function decodeRollbackPackageCommandV1(
+  value: unknown,
+): RollbackPackageCommandV1 {
+  const command = record(value, "rollback command");
+  exactKeys(
+    command,
+    ["schemaVersion", "commandId", "expectedRevision", "packageRevision"],
+    "rollback command",
+  );
+  if (command.schemaVersion !== 1) {
+    throw new PackagePublisherDecodeError("schemaVersion must be 1");
+  }
+  const packageRevision = revision(command.packageRevision, "packageRevision");
+  if (packageRevision < 1) {
+    throw new PackagePublisherDecodeError("packageRevision is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    commandId: identifier(command.commandId, "commandId"),
+    expectedRevision: revision(command.expectedRevision, "expectedRevision"),
+    packageRevision,
+  };
+}

package/src/user.test.ts

@@ -0,0 +1,288 @@
+import { describe, expect, test } from "bun:test";
+import { createPackagePublisherUserContribution } from "./user.js";
+import type { PackagePublisherTransaction } from "./user.js";
+
+class MemoryStorage implements PackagePublisherTransaction {
+  readonly values = new Map<string, unknown>();
+  readonly alarmTransactions: boolean[] = [];
+  private transactionActive = false;
+
+  constructor(
+    private readonly onAlarm?: (scheduledTime: number | Date) => void,
+  ) {}
+
+  get<T>(key: string): Promise<T | undefined> {
+    return Promise.resolve(
+      structuredClone(this.values.get(key)) as T | undefined,
+    );
+  }
+
+  put<T>(key: string, value: T): Promise<void> {
+    this.values.set(key, structuredClone(value));
+    return Promise.resolve();
+  }
+
+  async transaction<T>(
+    callback: (storage: PackagePublisherTransaction) => Promise<T>,
+  ): Promise<T> {
+    this.transactionActive = true;
+    try {
+      return await callback(this);
+    } finally {
+      this.transactionActive = false;
+    }
+  }
+
+  setAlarm(scheduledTime: number | Date): Promise<void> {
+    this.alarmTransactions.push(this.transactionActive);
+    this.onAlarm?.(scheduledTime);
+    return Promise.resolve();
+  }
+}
+
+const candidate = {
+  source: "source archive",
+  applicationArtifact: "export default { fetch() {} }",
+  checks: [{ name: "test", status: "passed" as const }],
+};
+
+describe("Package Publisher User contribution", () => {
+  test("publishes a verified immutable revision and replays the command", async () => {
+    const effects: string[] = [];
+    const storage = new MemoryStorage((scheduledTime) => {
+      effects.push(`scheduled:${new Date(scheduledTime).toISOString()}`);
+    });
+    const contribution = createPackagePublisherUserContribution({
+      storage,
+      now: () => new Date("2026-09-01T00:00:00.000Z"),
+      hash: () => Promise.resolve("sha256:artifact-one"),
+      storeAndVerify: async ({ applicationHash }) => {
+        effects.push(applicationHash);
+      },
+    });
+
+    const command = {
+      schemaVersion: 1 as const,
+      commandId: "publish-1",
+      expectedRevision: 0,
+      candidate,
+    };
+    const first = await contribution.publish("user-1", command);
+    const replay = await contribution.publish("user-1", command);
+
+    expect(first).toEqual({
+      schemaVersion: 1,
+      commandId: "publish-1",
+      status: "active",
+      revision: 1,
+      packageRevision: 1,
+      applicationHash: "sha256:artifact-one",
+    });
+    expect(replay).toEqual(first);
+    expect(effects).toEqual([
+      "scheduled:2026-09-01T00:01:00.000Z",
+      "sha256:artifact-one",
+    ]);
+    expect(storage.alarmTransactions).toEqual([true]);
+    expect(await contribution.read()).toEqual({
+      schemaVersion: 1,
+      revision: 1,
+      activePackageRevision: 1,
+      revisions: [
+        {
+          packageRevision: 1,
+          applicationHash: "sha256:artifact-one",
+          publishedAt: "2026-09-01T00:00:00.000Z",
+          checks: [{ name: "test", status: "passed" }],
+        },
+      ],
+    });
+  });
+
+  test("resumes a durably pending publication after its host is reconstructed", async () => {
+    const storage = new MemoryStorage();
+    const order: string[] = [];
+    await storage.put("package-publisher:state:v1", {
+      schemaVersion: 1,
+      revision: 0,
+      revisions: [],
+      pending: {
+        userId: "user-1",
+        commandId: "publish-1",
+        fingerprint: "fingerprint",
+        packageRevision: 1,
+        applicationHash: "sha256:artifact-one",
+        publishedAt: "2026-09-01T00:00:00.000Z",
+        candidate,
+      },
+    });
+    const contribution = createPackagePublisherUserContribution({
+      storage,
+      hash: () => Promise.resolve("sha256:artifact-one"),
+      storeAndVerify: () => {
+        order.push("verified");
+        return Promise.resolve();
+      },
+    });
+
+    const receipt = await contribution.recover();
+
+    expect(order).toEqual(["verified"]);
+    expect(receipt).toMatchObject({ status: "active", packageRevision: 1 });
+    expect((await contribution.read()).activePackageRevision).toBe(1);
+    expect(await contribution.recover()).toBeUndefined();
+  });
+
+  test("deduplicates concurrent delivery of a pending publication effect", async () => {
+    const storage = new MemoryStorage();
+    let releaseVerification: (() => void) | undefined;
+    const verificationStarted = Promise.withResolvers<void>();
+    const verificationReleased = new Promise<void>((resolve) => {
+      releaseVerification = resolve;
+    });
+    let effects = 0;
+    const contribution = createPackagePublisherUserContribution({
+      storage,
+      hash: () => Promise.resolve("sha256:artifact-one"),
+      storeAndVerify: async () => {
+        effects += 1;
+        verificationStarted.resolve();
+        await verificationReleased;
+      },
+    });
+    const command = {
+      schemaVersion: 1 as const,
+      commandId: "publish-concurrent",
+      expectedRevision: 0,
+      candidate,
+    };
+
+    const publication = contribution.publish("user-1", command);
+    await verificationStarted.promise;
+    const recovery = contribution.recover();
+    releaseVerification?.();
+    const [published, recovered] = await Promise.all([publication, recovery]);
+
+    expect(recovered).toEqual(published);
+    expect(effects).toBe(1);
+  });
+
+  test("rejects malformed publication state at the durable storage seam", async () => {
+    const storage = new MemoryStorage();
+    await storage.put("package-publisher:state:v1", {
+      schemaVersion: 1,
+      revision: 0,
+      revisions: [],
+      unknown: true,
+    });
+    const contribution = createPackagePublisherUserContribution({
+      storage,
+      hash: () => Promise.resolve("sha256:unused"),
+      storeAndVerify: () => Promise.resolve(),
+    });
+
+    let failure: unknown;
+    try {
+      await contribution.read();
+    } catch (error) {
+      failure = error;
+    }
+    expect(failure).toBeInstanceOf(Error);
+    expect((failure as Error).message).toContain("unknown or missing fields");
+  });
+
+  test("records verification failure without replacing the active revision", async () => {
+    const storage = new MemoryStorage();
+    let shouldFail = false;
+    const contribution = createPackagePublisherUserContribution({
+      storage,
+      hash: ({ applicationArtifact }) =>
+        Promise.resolve(`sha256:${applicationArtifact.length}`),
+      storeAndVerify: () =>
+        shouldFail
+          ? Promise.reject(new Error("candidate did not become healthy"))
+          : Promise.resolve(),
+    });
+
+    await contribution.publish("user-1", {
+      schemaVersion: 1,
+      commandId: "publish-1",
+      expectedRevision: 0,
+      candidate,
+    });
+    shouldFail = true;
+    const failed = await contribution.publish("user-1", {
+      schemaVersion: 1,
+      commandId: "publish-2",
+      expectedRevision: 1,
+      candidate: {
+        ...candidate,
+        applicationArtifact: "broken application",
+      },
+    });
+
+    expect(failed.status).toBe("failed");
+    expect(failed.failure).toBe("candidate did not become healthy");
+    expect((await contribution.read()).activePackageRevision).toBe(1);
+  });
+
+  test("blocks failed checks and rolls every Bot back by changing the shared active revision", async () => {
+    const contribution = createPackagePublisherUserContribution({
+      storage: new MemoryStorage(),
+      hash: ({ applicationArtifact }) =>
+        Promise.resolve(`sha256:${applicationArtifact.length}`),
+      storeAndVerify: () => Promise.resolve(),
+    });
+
+    let checkFailure: unknown;
+    try {
+      await contribution.publish("user-1", {
+        schemaVersion: 1,
+        commandId: "publish-failed-tests",
+        expectedRevision: 0,
+        candidate: {
+          ...candidate,
+          checks: [{ name: "test", status: "failed" }],
+        },
+      });
+    } catch (error) {
+      checkFailure = error;
+    }
+    expect(checkFailure).toBeInstanceOf(Error);
+    expect((checkFailure as Error).message).toContain(
+      "all required checks must pass",
+    );
+
+    const first = await contribution.publish("user-1", {
+      schemaVersion: 1,
+      commandId: "publish-1",
+      expectedRevision: 0,
+      candidate,
+    });
+    await contribution.publish("user-1", {
+      schemaVersion: 1,
+      commandId: "publish-2",
+      expectedRevision: first.revision,
+      candidate: {
+        ...candidate,
+        applicationArtifact: "second artifact",
+      },
+    });
+    const rollback = await contribution.rollback({
+      schemaVersion: 1,
+      commandId: "rollback-1",
+      expectedRevision: 2,
+      packageRevision: 1,
+    });
+
+    expect(rollback).toEqual({
+      schemaVersion: 1,
+      commandId: "rollback-1",
+      status: "active",
+      revision: 3,
+      packageRevision: 1,
+      applicationHash: first.applicationHash,
+    });
+    expect((await contribution.read()).activePackageRevision).toBe(1);
+  });
+});