@frockbot/plugin-flock 0.0.0 → 0.1.1

package/src/backend.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, test } from "bun:test";
+import { createFlockBackendContribution } from "./backend.js";
+import { randomSheepRecipeV1 } from "./shared.js";
+
+const sheep = randomSheepRecipeV1(() => 0);
+function request(path: string, body?: unknown) {
+  return new Request(`https://bot.example${path}`, {
+    method: body ? "POST" : "GET",
+    headers: body ? { "content-type": "application/json" } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+}
+
+describe("Flock gateway Contribution", () => {
+  test("maps RPC-serialized decode failures to definitive requests", async () => {
+    const contribution = createFlockBackendContribution({
+      listBots: () =>
+        Promise.resolve({ schemaVersion: 1, revision: 0, bots: [] }),
+      createBot: () =>
+        Promise.reject({ name: "FlockDecodeError", message: "collision" }),
+      listBotLifecycles: () =>
+        Promise.resolve({ schemaVersion: 1, lifecycles: [] }),
+      executeBotLifecycle: () => Promise.reject(new Error("not used")),
+      readSheep: () => Promise.reject(new Error("not used")),
+      updateSheep: () => Promise.reject(new Error("not used")),
+      listBotIdentities: () =>
+        Promise.resolve({ schemaVersion: 1 as const, identities: [] }),
+      listBotUnread: () =>
+        Promise.resolve({ schemaVersion: 1 as const, unread: [] }),
+      listBotNotifications: () =>
+        Promise.resolve({ schemaVersion: 1 as const, notifications: [] }),
+      executeBotUnreadCommand: () => Promise.reject(new Error("not used")),
+    });
+    const response = await contribution.route(
+      request("/api/bots", {
+        schemaVersion: 1,
+        type: "bot/create",
+        commandId: "create-1",
+        expectedRevision: 0,
+        botId: "alpha",
+        name: "Alpha",
+        sheep,
+      }),
+      new URL("https://bot.example/api/bots"),
+      { userId: "user-1", client: "browser" },
+    );
+    expect(response?.status).toBe(400);
+    expect(await response?.json()).toEqual({
+      error: "Flock request is invalid",
+      code: "invalid-request",
+      definitive: true,
+    });
+  });
+
+  test("routes exact authenticated create/read/update DTOs", async () => {
+    const contribution = createFlockBackendContribution({
+      listBots: () =>
+        Promise.resolve({ schemaVersion: 1, revision: 0, bots: [] }),
+      createBot: (_user, command) =>
+        Promise.resolve({
+          schemaVersion: 1,
+          commandId: command.commandId,
+          status: "applied",
+          revision: 1,
+        }),
+      listBotLifecycles: () =>
+        Promise.resolve({
+          schemaVersion: 1,
+          lifecycles: [
+            { schemaVersion: 1, botId: "alpha", status: "active", revision: 0 },
+          ],
+        }),
+      executeBotLifecycle: (_user, command) =>
+        Promise.resolve({
+          schemaVersion: 1,
+          commandId: command.commandId,
+          botId: command.botId,
+          status: "applied",
+          lifecycle: {
+            schemaVersion: 1,
+            botId: command.botId,
+            status: command.type === "bot/archive" ? "archived" : "active",
+            revision: 1,
+          },
+        }),
+      readSheep: (_user, botId) =>
+        Promise.resolve({ schemaVersion: 1, botId, revision: 0, sheep }),
+      updateSheep: (_user, _bot, command) =>
+        Promise.resolve({
+          schemaVersion: 1,
+          commandId: command.commandId,
+          status: "applied",
+          revision: 1,
+        }),
+      listBotIdentities: () =>
+        Promise.resolve({
+          schemaVersion: 1 as const,
+          identities: [
+            {
+              schemaVersion: 1 as const,
+              botId: "alpha",
+              name: "Alpha",
+              namedBy: "user" as const,
+              hiddenFromSidebar: false,
+            },
+          ],
+        }),
+      listBotUnread: () =>
+        Promise.resolve({ schemaVersion: 1 as const, unread: [] }),
+      listBotNotifications: () =>
+        Promise.resolve({ schemaVersion: 1 as const, notifications: [] }),
+      executeBotUnreadCommand: (_user, botId, command) =>
+        Promise.resolve({
+          schemaVersion: 1 as const,
+          commandId: command.commandId,
+          status: "applied" as const,
+          unread: {
+            schemaVersion: 1 as const,
+            botId,
+            count: 0,
+            capped: false,
+            unread: command.type === "bot/mark-unread",
+            manuallyUnread: command.type === "bot/mark-unread",
+          },
+        }),
+    });
+    const context = { userId: "user-1", client: "browser" as const };
+    expect(
+      (
+        await contribution.route(
+          request("/api/bots"),
+          new URL("https://bot.example/api/bots"),
+          context,
+        )
+      )?.status,
+    ).toBe(200);
+    const create = {
+      schemaVersion: 1,
+      type: "bot/create",
+      commandId: "create-1",
+      expectedRevision: 0,
+      botId: "alpha",
+      name: "Alpha",
+      sheep,
+    };
+    expect(
+      (
+        await contribution.route(
+          request("/api/bots", create),
+          new URL("https://bot.example/api/bots"),
+          context,
+        )
+      )?.status,
+    ).toBe(201);
+    const archive = await contribution.route(
+      request("/api/bots/alpha/lifecycle", {
+        schemaVersion: 1,
+        type: "bot/archive",
+        commandId: "archive-1",
+        botId: "alpha",
+      }),
+      new URL("https://bot.example/api/bots/alpha/lifecycle"),
+      context,
+    );
+    expect(archive?.status).toBe(200);
+    expect(await archive?.json()).toMatchObject({
+      status: "applied",
+      lifecycle: { status: "archived" },
+    });
+    const invalid = await contribution.route(
+      request("/api/bots", { ...create, extra: true }),
+      new URL("https://bot.example/api/bots"),
+      context,
+    );
+    expect(invalid?.status).toBe(400);
+    expect(await invalid?.json()).toMatchObject({ definitive: true });
+    const invalidBotId = await contribution.route(
+      request("/api/bots", { ...create, botId: "bad@bot" }),
+      new URL("https://bot.example/api/bots"),
+      context,
+    );
+    expect(invalidBotId?.status).toBe(400);
+    expect(await invalidBotId?.json()).toMatchObject({
+      code: "invalid-request",
+      definitive: true,
+    });
+    expect(
+      await contribution.route(
+        request("/api/bots"),
+        new URL("https://bot.example/api/bots"),
+        { client: "browser" },
+      ),
+    ).toBeUndefined();
+
+    const identities = await contribution.route(
+      request("/api/bots/identities"),
+      new URL("https://bot.example/api/bots/identities"),
+      context,
+    );
+    expect(identities?.status).toBe(200);
+    expect(await identities?.json()).toMatchObject({
+      identities: [{ botId: "alpha", name: "Alpha", namedBy: "user" }],
+    });
+  });
+});

package/src/backend.ts

@@ -0,0 +1,283 @@
+import type { Plugin } from "cordis";
+import {
+  BotNotFoundError,
+  FlockConflictError,
+  isFlockIdentifier,
+  FlockDecodeError,
+  decodeBotLifecycleCommandV1,
+  decodeCreateBotCommandV1,
+  decodeUpdateSheepCommandV1,
+  type BotDirectoryViewV1,
+  type BotIdentityDirectoryViewV1,
+  type BotLifecycleCommandV1,
+  type BotLifecycleDirectoryViewV1,
+  type BotLifecycleReceiptV1,
+  type CreateBotCommandV1,
+  type FlockReceiptV1,
+  type SheepIdentityViewV1,
+  type UpdateSheepCommandV1,
+} from "./shared.js";
+import {
+  decodeBotUnreadCommandV1,
+  UnreadDecodeError,
+  type BotNotificationDirectoryViewV1,
+  type BotUnreadCommandV1,
+  type BotUnreadDirectoryViewV1,
+  type BotUnreadReceiptV1,
+} from "@frockbot/plugin-shell/unread";
+
+export interface FlockGatewayHost {
+  listBots(userId: string): Promise<BotDirectoryViewV1>;
+  createBot(
+    userId: string,
+    command: CreateBotCommandV1,
+  ): Promise<FlockReceiptV1>;
+  listBotLifecycles(userId: string): Promise<BotLifecycleDirectoryViewV1>;
+  executeBotLifecycle(
+    userId: string,
+    command: BotLifecycleCommandV1,
+  ): Promise<BotLifecycleReceiptV1>;
+  readSheep(userId: string, botId: string): Promise<SheepIdentityViewV1>;
+  updateSheep(
+    userId: string,
+    botId: string,
+    command: UpdateSheepCommandV1,
+  ): Promise<FlockReceiptV1>;
+  /** The live identity of every registered Bot, read through to its owner. */
+  listBotIdentities(userId: string): Promise<BotIdentityDirectoryViewV1>;
+  /**
+   * Unread state for every non-archived Bot, through the same bounded fan-out
+   * the identity directory uses: one round trip for the whole sidebar.
+   */
+  listBotUnread(userId: string): Promise<BotUnreadDirectoryViewV1>;
+  /**
+   * Pending notification intents across every non-archived Bot, so a
+   * completion on a Bot the User is not looking at still surfaces.
+   */
+  listBotNotifications(userId: string): Promise<BotNotificationDirectoryViewV1>;
+  /** `bot/mark-read` / `bot/mark-unread`, applied by the Bot Durable Object. */
+  executeBotUnreadCommand(
+    userId: string,
+    botId: string,
+    command: BotUnreadCommandV1,
+  ): Promise<BotUnreadReceiptV1>;
+}
+export interface FlockBackendRouteContribution {
+  packageId: string;
+  route(
+    request: Request,
+    url: URL,
+    context: { userId?: string; client: "browser" | "desktop" },
+  ): Promise<Response | undefined>;
+}
+function errorResponse(error: unknown): Response {
+  if (
+    error instanceof FlockDecodeError ||
+    error instanceof UnreadDecodeError ||
+    (typeof error === "object" &&
+      error !== null &&
+      "name" in error &&
+      (error.name === "FlockDecodeError" || error.name === "UnreadDecodeError"))
+  )
+    return Response.json(
+      {
+        error:
+          error instanceof Error ? error.message : "Flock request is invalid",
+        code: "invalid-request",
+        definitive: true,
+      },
+      { status: 400 },
+    );
+  if (
+    error instanceof BotNotFoundError ||
+    (typeof error === "object" &&
+      error !== null &&
+      "name" in error &&
+      error.name === "BotNotFoundError")
+  )
+    return Response.json(
+      {
+        error: error instanceof Error ? error.message : "Bot not found",
+        code: "bot-not-found",
+        definitive: true,
+      },
+      { status: 404 },
+    );
+  if (
+    error instanceof FlockConflictError ||
+    (typeof error === "object" &&
+      error !== null &&
+      "name" in error &&
+      error.name === "FlockConflictError")
+  ) {
+    const currentRevision =
+      typeof error === "object" &&
+      error !== null &&
+      "currentRevision" in error &&
+      typeof error.currentRevision === "number"
+        ? error.currentRevision
+        : 0;
+    return Response.json(
+      {
+        error: `flock revision is ${currentRevision}`,
+        code: "revision-conflict",
+        currentRevision,
+        definitive: true,
+      },
+      { status: 409 },
+    );
+  }
+  return Response.json(
+    { error: error instanceof Error ? error.message : "Flock request failed" },
+    { status: 500 },
+  );
+}
+function decodePathId(value: string): string {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    throw new FlockDecodeError("botId is invalid");
+  }
+  if (!isFlockIdentifier(decoded))
+    throw new FlockDecodeError("botId is invalid");
+  return decoded;
+}
+
+export function createFlockBackendContribution(
+  host: FlockGatewayHost,
+): FlockBackendRouteContribution {
+  return {
+    packageId: "flock",
+    async route(request, url, context) {
+      if (!context.userId) return undefined;
+      const sheep = url.pathname.match(/^\/api\/bots\/([^/]+)\/sheep$/);
+      const unread = url.pathname.match(/^\/api\/bots\/([^/]+)\/unread$/);
+      const lifecycle = url.pathname.match(/^\/api\/bots\/([^/]+)\/lifecycle$/);
+      if (
+        url.pathname !== "/api/bots" &&
+        url.pathname !== "/api/bots/lifecycles" &&
+        url.pathname !== "/api/bots/identities" &&
+        url.pathname !== "/api/bots/unread" &&
+        url.pathname !== "/api/bots/notifications" &&
+        !sheep &&
+        !unread &&
+        !lifecycle
+      )
+        return undefined;
+      try {
+        if (url.pathname === "/api/bots/identities") {
+          if (request.method !== "GET")
+            return Response.json(
+              { error: "method not allowed" },
+              { status: 405 },
+            );
+          return Response.json(await host.listBotIdentities(context.userId));
+        }
+        if (url.pathname === "/api/bots/unread") {
+          if (request.method !== "GET")
+            return Response.json(
+              { error: "method not allowed" },
+              { status: 405 },
+            );
+          return Response.json(await host.listBotUnread(context.userId));
+        }
+        if (url.pathname === "/api/bots/notifications") {
+          if (request.method !== "GET")
+            return Response.json(
+              { error: "method not allowed" },
+              { status: 405 },
+            );
+          return Response.json(await host.listBotNotifications(context.userId));
+        }
+        if (unread) {
+          const botId = decodePathId(unread[1]!);
+          if (request.method !== "POST")
+            return Response.json(
+              { error: "method not allowed" },
+              { status: 405 },
+            );
+          const command = decodeBotUnreadCommandV1(await request.json());
+          if (command.botId !== botId)
+            throw new FlockDecodeError(
+              "unread command does not match request path",
+            );
+          return Response.json(
+            await host.executeBotUnreadCommand(context.userId, botId, command),
+          );
+        }
+        if (url.pathname === "/api/bots/lifecycles") {
+          if (request.method !== "GET")
+            return Response.json(
+              { error: "method not allowed" },
+              { status: 405 },
+            );
+          return Response.json(await host.listBotLifecycles(context.userId));
+        }
+        if (url.pathname === "/api/bots") {
+          if (request.method === "GET")
+            return Response.json(await host.listBots(context.userId));
+          if (request.method !== "POST")
+            return Response.json(
+              { error: "method not allowed" },
+              { status: 405 },
+            );
+          return Response.json(
+            await host.createBot(
+              context.userId,
+              decodeCreateBotCommandV1(await request.json()),
+            ),
+            { status: 201 },
+          );
+        }
+        if (lifecycle) {
+          const botId = decodePathId(lifecycle[1]!);
+          if (request.method !== "POST")
+            return Response.json(
+              { error: "method not allowed" },
+              { status: 405 },
+            );
+          const command = decodeBotLifecycleCommandV1(await request.json());
+          if (command.botId !== botId)
+            throw new FlockDecodeError(
+              "lifecycle command does not match request path",
+            );
+          const receipt = await host.executeBotLifecycle(
+            context.userId,
+            command,
+          );
+          return Response.json(receipt, {
+            status: receipt.status === "pending" ? 202 : 200,
+          });
+        }
+        const botId = decodePathId(sheep![1]!);
+        if (request.method === "GET")
+          return Response.json(await host.readSheep(context.userId, botId));
+        if (request.method !== "POST")
+          return Response.json(
+            { error: "method not allowed" },
+            { status: 405 },
+          );
+        const command = decodeUpdateSheepCommandV1(await request.json());
+        if (command.botId !== botId)
+          throw new FlockDecodeError(
+            "sheep command does not match request path",
+          );
+        return Response.json(
+          await host.updateSheep(context.userId, botId, command),
+        );
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  };
+}
+
+export namespace createFlockBackendContribution {
+  export function plugin(
+    host: FlockGatewayHost,
+    lifecycle: { mount(value: FlockBackendRouteContribution): () => void },
+  ): Plugin {
+    return () => lifecycle.mount(createFlockBackendContribution(host));
+  }
+}

package/src/bot.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test } from "bun:test";
+import { createFlockBotBackendContribution } from "./bot.js";
+import { FlockConflictError, randomSheepRecipeV1 } from "./shared.js";
+
+class MemoryStorage {
+  values = new Map<string, unknown>();
+  get<T>(key: string): Promise<T | undefined> {
+    return Promise.resolve(
+      structuredClone(this.values.get(key)) as T | undefined,
+    );
+  }
+  put<T>(key: string | Record<string, unknown>, value?: T): Promise<void> {
+    if (typeof key === "string") this.values.set(key, structuredClone(value));
+    else
+      for (const [name, entry] of Object.entries(key))
+        this.values.set(name, structuredClone(entry));
+    return Promise.resolve();
+  }
+  transaction<T>(callback: (storage: MemoryStorage) => Promise<T>): Promise<T> {
+    return callback(this);
+  }
+  list<T>({ prefix }: { prefix: string }): Promise<Map<string, T>> {
+    return Promise.resolve(
+      new Map(
+        [...this.values.entries()].filter(([key]) =>
+          key.startsWith(prefix),
+        ) as Array<[string, T]>,
+      ),
+    );
+  }
+}
+const registration = {
+  schemaVersion: 1 as const,
+  botId: "alpha",
+  registeredAt: "2026-08-29T00:00:00.000Z",
+  initialName: "Alpha",
+  sheep: randomSheepRecipeV1(() => 0),
+};
+
+describe("Flock Bot contribution", () => {
+  test("materializes once and replays sheep updates after reconstruction", async () => {
+    const storage = new MemoryStorage();
+    let settingsMaterializations = 0;
+    const create = () =>
+      createFlockBotBackendContribution({
+        storage,
+        materializeSettings: () => {
+          settingsMaterializations += 1;
+          return Promise.resolve();
+        },
+        archiveEligible: () => Promise.resolve(true),
+      });
+    expect(await create().read(registration, "user-1")).toMatchObject({
+      botId: "alpha",
+      revision: 0,
+    });
+    const nextSheep = randomSheepRecipeV1(() => 0.8);
+    const command = {
+      schemaVersion: 1 as const,
+      type: "bot/update-sheep" as const,
+      commandId: "sheep-1",
+      expectedRevision: 0,
+      botId: "alpha",
+      sheep: nextSheep,
+    };
+    const first = await create().update(registration, "user-1", command);
+    expect(await create().update(registration, "user-1", command)).toEqual(
+      first,
+    );
+    expect(await create().read(registration, "user-1")).toMatchObject({
+      revision: 1,
+      sheep: nextSheep,
+    });
+    await expect(
+      create().update(registration, "user-1", {
+        ...command,
+        commandId: "stale",
+        expectedRevision: 0,
+      }),
+    ).rejects.toBeInstanceOf(FlockConflictError);
+    await expect(
+      create().update(registration, "user-1", {
+        ...command,
+        sheep: registration.sheep,
+      }),
+    ).rejects.toThrow("command ID collision");
+    expect(settingsMaterializations).toBeGreaterThan(0);
+  });
+
+  test("archives idempotently, fences mutations, rejects active work, and restores data", async () => {
+    const storage = new MemoryStorage();
+    let eligible = true;
+    const create = () =>
+      createFlockBotBackendContribution({
+        storage,
+        materializeSettings: () => Promise.resolve(),
+        archiveEligible: () => Promise.resolve(eligible),
+      });
+    const contribution = create();
+    await contribution.read(registration, "user-1");
+    const archive = {
+      schemaVersion: 1 as const,
+      type: "bot/archive" as const,
+      commandId: "archive-1",
+      botId: "alpha",
+    };
+    eligible = false;
+    expect(
+      await contribution.executeLifecycle(registration, "user-1", archive),
+    ).toMatchObject({ status: "rejected", lifecycle: { status: "active" } });
+    eligible = true;
+    const applied = await contribution.executeLifecycle(
+      registration,
+      "user-1",
+      {
+        ...archive,
+        commandId: "archive-2",
+      },
+    );
+    expect(applied).toMatchObject({
+      status: "applied",
+      lifecycle: { status: "archived" },
+    });
+    expect(
+      await contribution.executeLifecycle(registration, "user-1", {
+        ...archive,
+        commandId: "archive-2",
+      }),
+    ).toEqual(applied);
+    const reconstructed = create();
+    expect(
+      await reconstructed.readLifecycle(registration, "user-1"),
+    ).toMatchObject({ status: "archived" });
+    await expect(
+      reconstructed.update(registration, "user-1", {
+        schemaVersion: 1,
+        type: "bot/update-sheep",
+        commandId: "sheep-archived",
+        expectedRevision: 0,
+        botId: "alpha",
+        sheep: registration.sheep,
+      }),
+    ).rejects.toThrow("archived");
+    await reconstructed.executeLifecycle(registration, "user-1", {
+      schemaVersion: 1,
+      type: "bot/restore",
+      commandId: "restore-1",
+      botId: "alpha",
+    });
+    expect(await contribution.read(registration, "user-1")).toMatchObject({
+      revision: 0,
+      sheep: registration.sheep,
+    });
+  });
+
+  test("rejects malformed durable sheep identity and receipt records", async () => {
+    const storage = new MemoryStorage();
+    const contribution = createFlockBotBackendContribution({
+      storage,
+      materializeSettings: () => Promise.resolve(),
+      archiveEligible: () => Promise.resolve(true),
+    });
+    await storage.put("flock:sheep:v1", {
+      schemaVersion: 1,
+      botId: "alpha",
+      revision: 0,
+      sheep: registration.sheep,
+      unknown: true,
+    });
+    await expect(contribution.read(registration, "user-1")).rejects.toThrow(
+      "unknown or missing field",
+    );
+    storage.values.delete("flock:sheep:v1");
+    await contribution.read(registration, "user-1");
+    await storage.put("flock:sheep-receipt:sheep-1", {
+      fingerprint: "{}",
+      receipt: { schemaVersion: 1, status: "applied" },
+    });
+    await expect(
+      contribution.update(registration, "user-1", {
+        schemaVersion: 1,
+        type: "bot/update-sheep",
+        commandId: "sheep-1",
+        expectedRevision: 0,
+        botId: "alpha",
+        sheep: registration.sheep,
+      }),
+    ).rejects.toThrow("unknown or missing field");
+  });
+});