@frockbot/plugin-flock 0.0.0 → 0.1.0

package/src/bot.ts

@@ -0,0 +1,255 @@
+import type { Plugin } from "cordis";
+import {
+  FlockConflictError,
+  FlockDecodeError,
+  decodeBotLifecycleCommandV1,
+  decodeBotLifecycleReceiptV1,
+  decodeBotLifecycleViewV1,
+  decodeBotRegistrationV1,
+  decodeSheepIdentityViewV1,
+  decodeStoredBotLifecycleReceiptV1,
+  decodeStoredFlockReceiptV1,
+  flockCommandFingerprint,
+  type BotLifecycleCommandV1,
+  type BotLifecycleReceiptV1,
+  type BotLifecycleViewV1,
+  type BotRegistrationV1,
+  type FlockReceiptV1,
+  type SheepIdentityViewV1,
+  type UpdateSheepCommandV1,
+} from "./shared.js";
+
+const IDENTITY_KEY = "flock:sheep:v1";
+const RECEIPT_PREFIX = "flock:sheep-receipt:";
+const LIFECYCLE_KEY = "flock:lifecycle:v1";
+const LIFECYCLE_RECEIPT_PREFIX = "flock:lifecycle-receipt:";
+export interface FlockBotTransaction {
+  get<T>(key: string): Promise<T | undefined>;
+  list<T>(options: { prefix: string }): Promise<Map<string, T>>;
+  put<T>(key: string, value: T): Promise<void>;
+  put(entries: Record<string, unknown>): Promise<void>;
+}
+interface Storage extends FlockBotTransaction {
+  transaction<T>(
+    callback: (storage: FlockBotTransaction) => Promise<T>,
+  ): Promise<T>;
+}
+export interface FlockBotBackendHost {
+  storage: Storage;
+  materializeSettings(
+    registration: BotRegistrationV1,
+    userId: string,
+  ): Promise<void>;
+  archiveEligible(storage: FlockBotTransaction): Promise<boolean>;
+}
+
+export class BotArchivedError extends Error {
+  constructor(readonly botId: string) {
+    super(`Bot "${botId}" is archived`);
+    this.name = "BotArchivedError";
+  }
+}
+
+export class FlockBotBackendContribution {
+  constructor(private readonly host: FlockBotBackendHost) {}
+
+  async materialize(
+    registrationInput: BotRegistrationV1,
+    userId: string,
+  ): Promise<SheepIdentityViewV1> {
+    const registration = decodeBotRegistrationV1(registrationInput);
+    await this.host.materializeSettings(registration, userId);
+    return this.host.storage.transaction(async (storage) => {
+      const existingValue = await storage.get<unknown>(IDENTITY_KEY);
+      const lifecycleValue = await storage.get<unknown>(LIFECYCLE_KEY);
+      const lifecycle =
+        lifecycleValue === undefined
+          ? {
+              schemaVersion: 1 as const,
+              botId: registration.botId,
+              status: "active" as const,
+              revision: 0,
+            }
+          : decodeBotLifecycleViewV1(lifecycleValue);
+      if (lifecycle.botId !== registration.botId)
+        throw new Error("Bot lifecycle does not match Bot registration");
+      const existing =
+        existingValue === undefined
+          ? undefined
+          : decodeSheepIdentityViewV1(existingValue);
+      if (existing) {
+        if (existing.botId !== registration.botId)
+          throw new Error("sheep identity does not match Bot registration");
+        if (lifecycleValue === undefined)
+          await storage.put(LIFECYCLE_KEY, lifecycle);
+        return existing;
+      }
+      const initial = {
+        schemaVersion: 1,
+        botId: registration.botId,
+        revision: 0,
+        sheep: structuredClone(registration.sheep),
+      } satisfies SheepIdentityViewV1;
+      await storage.put({
+        [IDENTITY_KEY]: initial,
+        [LIFECYCLE_KEY]: lifecycle,
+      });
+      return initial;
+    });
+  }
+
+  async read(
+    registration: BotRegistrationV1,
+    userId: string,
+  ): Promise<SheepIdentityViewV1> {
+    return structuredClone(await this.materialize(registration, userId));
+  }
+
+  async update(
+    registration: BotRegistrationV1,
+    userId: string,
+    command: UpdateSheepCommandV1,
+  ): Promise<FlockReceiptV1> {
+    if (registration.botId !== command.botId)
+      throw new Error("sheep command does not match Bot registration");
+    await this.materialize(registration, userId);
+    const fingerprint = flockCommandFingerprint(command);
+    return this.host.storage.transaction(async (storage) => {
+      await this.assertActive(storage, registration.botId);
+      const receiptKey = `${RECEIPT_PREFIX}${command.commandId}`;
+      const storedValue = await storage.get<unknown>(receiptKey);
+      const stored =
+        storedValue === undefined
+          ? undefined
+          : decodeStoredFlockReceiptV1(storedValue);
+      if (stored) {
+        if (stored.fingerprint !== fingerprint)
+          throw new FlockDecodeError(
+            `command ID collision: ${command.commandId}`,
+          );
+        return structuredClone(stored.receipt);
+      }
+      const currentValue = await storage.get<unknown>(IDENTITY_KEY);
+      if (currentValue === undefined)
+        throw new Error("sheep identity was not materialized");
+      const current = decodeSheepIdentityViewV1(currentValue);
+      if (current.revision !== command.expectedRevision)
+        throw new FlockConflictError(current.revision);
+      const next = {
+        ...current,
+        revision: current.revision + 1,
+        sheep: structuredClone(command.sheep),
+      } satisfies SheepIdentityViewV1;
+      const receipt = {
+        schemaVersion: 1,
+        commandId: command.commandId,
+        status: "applied",
+        revision: next.revision,
+      } satisfies FlockReceiptV1;
+      await storage.put({
+        [IDENTITY_KEY]: next,
+        [receiptKey]: { fingerprint, receipt },
+      });
+      return receipt;
+    });
+  }
+
+  async readLifecycle(
+    registration: BotRegistrationV1,
+    userId: string,
+  ): Promise<BotLifecycleViewV1> {
+    await this.materialize(registration, userId);
+    const stored = await this.host.storage.get<unknown>(LIFECYCLE_KEY);
+    if (stored === undefined)
+      throw new Error("Bot lifecycle was not materialized");
+    return structuredClone(decodeBotLifecycleViewV1(stored));
+  }
+
+  async executeLifecycle(
+    registration: BotRegistrationV1,
+    userId: string,
+    input: unknown,
+  ): Promise<BotLifecycleReceiptV1> {
+    const command = decodeBotLifecycleCommandV1(input);
+    if (registration.botId !== command.botId)
+      throw new Error("lifecycle command does not match Bot registration");
+    await this.materialize(registration, userId);
+    const fingerprint = flockCommandFingerprint(command);
+    return this.host.storage.transaction(async (storage) => {
+      const receiptKey = `${LIFECYCLE_RECEIPT_PREFIX}${command.commandId}`;
+      const storedReceipt = await storage.get<unknown>(receiptKey);
+      if (storedReceipt !== undefined) {
+        const decoded = decodeStoredBotLifecycleReceiptV1(storedReceipt);
+        if (decoded.fingerprint !== fingerprint)
+          throw new FlockDecodeError(
+            `command ID collision: ${command.commandId}`,
+          );
+        return structuredClone(decoded.receipt);
+      }
+      const currentValue = await storage.get<unknown>(LIFECYCLE_KEY);
+      if (currentValue === undefined)
+        throw new Error("Bot lifecycle was not materialized");
+      const current = decodeBotLifecycleViewV1(currentValue);
+      const target = command.type === "bot/archive" ? "archived" : "active";
+      let receipt: BotLifecycleReceiptV1;
+      if (
+        target === "archived" &&
+        current.status !== "archived" &&
+        !(await this.host.archiveEligible(storage))
+      ) {
+        receipt = {
+          schemaVersion: 1,
+          commandId: command.commandId,
+          botId: command.botId,
+          status: "rejected",
+          lifecycle: current,
+          failure: "Bot has active or reconciling work",
+        };
+      } else {
+        const lifecycle =
+          current.status === target
+            ? current
+            : ({
+                ...current,
+                status: target,
+                revision: current.revision + 1,
+              } satisfies BotLifecycleViewV1);
+        receipt = {
+          schemaVersion: 1,
+          commandId: command.commandId,
+          botId: command.botId,
+          status: "applied",
+          lifecycle,
+        };
+        await storage.put(LIFECYCLE_KEY, lifecycle);
+      }
+      await storage.put(receiptKey, { fingerprint, receipt });
+      return decodeBotLifecycleReceiptV1(receipt);
+    });
+  }
+
+  async assertActive(
+    storage: FlockBotTransaction,
+    botId: string,
+  ): Promise<void> {
+    const value = await storage.get<unknown>(LIFECYCLE_KEY);
+    if (value === undefined) return;
+    const lifecycle = decodeBotLifecycleViewV1(value);
+    if (lifecycle.botId !== botId)
+      throw new Error("Bot lifecycle identity does not match");
+    if (lifecycle.status === "archived") throw new BotArchivedError(botId);
+  }
+}
+
+export function createFlockBotBackendContribution(
+  host: FlockBotBackendHost,
+): FlockBotBackendContribution {
+  return new FlockBotBackendContribution(host);
+}
+
+export function createFlockBotBackendPlugin(
+  host: FlockBotBackendHost,
+  lifecycle: { mount(value: FlockBotBackendContribution): () => void },
+): Plugin {
+  return () => lifecycle.mount(createFlockBotBackendContribution(host));
+}

package/src/client/BotAvatar.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+/**
+ * What a Bot looks like. The Flock's generated sheep recipe is the avatar.
+ */
+import SheepAvatar from "./SheepAvatar.vue";
+import type { SheepRecipeV1 } from "../shared.js";
+
+const props = withDefaults(
+  defineProps<{
+    botId: string;
+    sheep: SheepRecipeV1;
+    label?: string;
+    size?: "mini" | "small" | "large";
+  }>(),
+  { label: "Bot avatar", size: "small" },
+);
+</script>
+<template>
+  <SheepAvatar :sheep="sheep" :label="label" :size="size" />
+</template>

package/src/client/FlockAvatar.vue

@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import { computed, inject } from "vue";
+import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
+import { flockWebDataKey } from "./state.js";
+import BotAvatar from "./BotAvatar.vue";
+
+/**
+ * The active Bot's sheep, rendered beside each assistant message. The shell
+ * owns the slot and the animation; the Flock Package owns what a Bot looks
+ * like, so the shell never imports this Package.
+ */
+const flock = inject(flockWebDataKey);
+const shell = inject(frockBotWebDataKey);
+if (!flock || !shell) throw new Error("Flock client data was not provided");
+const identity = computed(() =>
+  shell.value.activeBotId
+    ? flock.value.identities[shell.value.activeBotId]
+    : undefined,
+);
+const name = computed(
+  () => shell.value.botSettings?.profile.name ?? "This Bot",
+);
+</script>
+
+<template>
+  <BotAvatar
+    v-if="identity && shell.activeBotId"
+    :bot-id="shell.activeBotId"
+    :sheep="identity.sheep"
+    size="mini"
+    :label="name"
+  />
+</template>

package/src/client/FlockAvatarEditor.vue

@@ -0,0 +1,44 @@
+<script setup lang="ts">
+import { UiButton } from "@frockbot/client-ui";
+import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
+import { computed, inject } from "vue";
+import BotAvatar from "./BotAvatar.vue";
+import { flockWebDataKey } from "./state.js";
+
+const flock = inject(flockWebDataKey);
+const shell = inject(frockBotWebDataKey);
+if (!flock || !shell) throw new Error("Flock client data was not provided");
+flock.value.bindShell(shell);
+
+const identity = computed(() =>
+  shell.value.activeBotId
+    ? flock.value.identities[shell.value.activeBotId]
+    : undefined,
+);
+const label = computed(
+  () => `${shell.value.botSettings?.profile.name ?? "This Bot"} avatar`,
+);
+</script>
+
+<template>
+  <div v-if="identity && shell.activeBotId" class="flock-avatar-editor">
+    <BotAvatar
+      :bot-id="shell.activeBotId"
+      :sheep="identity.sheep"
+      :label="label"
+      size="large"
+    />
+    <UiButton type="button" variant="ghost" @click="flock.openEdit">
+      Change
+    </UiButton>
+  </div>
+</template>
+
+<style scoped>
+.flock-avatar-editor {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 12px;
+}
+</style>

package/src/client/FlockCreateButton.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+import { UiIconButton } from "@frockbot/client-ui";
+import { inject } from "vue";
+import { flockWebDataKey } from "./state.js";
+
+const flock = inject(flockWebDataKey);
+if (!flock) throw new Error("Flock client data was not provided");
+</script>
+
+<template>
+  <UiIconButton
+    class="flock-create-button"
+    icon="plus"
+    label="Create Bot"
+    size="md"
+    @click="flock.openCreate"
+  />
+</template>

package/src/client/FlockIdentity.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { computed, inject } from "vue";
+import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
+import { flockWebDataKey } from "./state.js";
+import BotAvatar from "./BotAvatar.vue";
+const flock = inject(flockWebDataKey);
+const shell = inject(frockBotWebDataKey);
+if (!flock || !shell) throw new Error("Flock client data was not provided");
+flock.value.bindShell(shell);
+const identity = computed(() =>
+  shell.value.activeBotId
+    ? flock.value.identities[shell.value.activeBotId]
+    : undefined,
+);
+</script>
+<template>
+  <button
+    v-if="identity"
+    class="flock-identity-button"
+    type="button"
+    title="Tailor sheep"
+    aria-label="Tailor sheep"
+    @click="flock.openEdit"
+  >
+    <BotAvatar
+      :bot-id="shell.activeBotId!"
+      :sheep="identity.sheep"
+      :label="`${shell.botSettings?.profile.name ?? 'This Bot'} avatar`"
+    /></button
+  ><span v-else>⌁</span>
+</template>

package/src/client/FlockOverlay.vue

@@ -0,0 +1,209 @@
+<script setup lang="ts">
+import { inject, nextTick, onBeforeUnmount, ref, watch } from "vue";
+import { sheepCatalog } from "../shared.js";
+import { flockWebDataKey } from "./state.js";
+import { dialogFocusWrapTarget } from "./dialog-focus.js";
+import SheepAvatar from "./SheepAvatar.vue";
+const providedFlock = inject(flockWebDataKey);
+if (!providedFlock) throw new Error("Flock client data was not provided");
+const flock = providedFlock;
+
+const dialog = ref<HTMLElement>();
+let restoreFocus: HTMLElement | undefined;
+const focusable =
+  'button:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+watch(
+  () => flock.value.overlay,
+  async (overlay, previous) => {
+    if (overlay && !previous) {
+      restoreFocus =
+        document.activeElement instanceof HTMLElement
+          ? document.activeElement
+          : undefined;
+      await nextTick();
+      dialog.value
+        ?.querySelector<HTMLElement>("[autofocus], " + focusable)
+        ?.focus();
+    } else if (!overlay && previous) {
+      restoreFocus?.focus();
+      restoreFocus = undefined;
+    }
+  },
+  { flush: "post" },
+);
+
+function onDialogKeydown(event: KeyboardEvent): void {
+  if (event.key === "Escape") {
+    event.preventDefault();
+    flock.value.closeOverlay();
+    return;
+  }
+  if (event.key !== "Tab" || !dialog.value) return;
+  const controls = [...dialog.value.querySelectorAll<HTMLElement>(focusable)];
+  if (controls.length === 0) return;
+  const target = dialogFocusWrapTarget(
+    controls,
+    document.activeElement as HTMLElement | null,
+    event.shiftKey,
+  );
+  if (!target) return;
+  event.preventDefault();
+  target.focus();
+}
+
+onBeforeUnmount(() => restoreFocus?.focus());
+</script>
+<template>
+  <div
+    v-if="flock.overlay"
+    class="flock-backdrop"
+    @click.self="flock.closeOverlay"
+  >
+    <section
+      ref="dialog"
+      class="flock-dialog"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="flock-title"
+      @keydown="onDialogKeydown"
+    >
+      <div v-if="flock.overlay === 'archive'" class="flock-form">
+        <span class="flock-eyebrow">Archive Bot</span>
+        <h1 id="flock-title">Archive this Bot?</h1>
+        <p>
+          Archiving stops new work and hides the Bot from your active flock.
+          History, settings, and Assignments are preserved for restoration.
+        </p>
+        <p
+          v-if="flock.error"
+          class="flock-error"
+          role="alert"
+          aria-live="assertive"
+        >
+          {{ flock.error }}
+        </p>
+        <div class="flock-actions">
+          <button type="button" @click="flock.closeOverlay">Cancel</button>
+          <button class="primary" type="button" @click="flock.archive">
+            Archive Bot
+          </button>
+        </div>
+      </div>
+      <template v-else>
+        <div class="flock-preview">
+          <SheepAvatar
+            :sheep="flock.draftSheep"
+            :label="
+              flock.draftName
+                ? `${flock.draftName} sheep preview`
+                : 'Sheep preview'
+            "
+            size="large"
+          />
+          <h2>Meet your sheep</h2>
+          <p>Randomly tailored. Entirely yours.</p>
+          <button type="button" class="flock-reroll" @click="flock.reroll">
+            ↻ Surprise me
+          </button>
+        </div>
+        <form
+          class="flock-form"
+          @submit.prevent="
+            flock.overlay === 'create' ? flock.create() : flock.saveSheep()
+          "
+        >
+          <span class="flock-eyebrow">{{
+            flock.overlay === "create" ? "Create a Bot" : "Tailor your Bot"
+          }}</span>
+          <h1 id="flock-title">
+            {{
+              flock.overlay === "create"
+                ? "Add to your flock"
+                : "Change the look"
+            }}
+          </h1>
+          <p>
+            Keep this look or tailor each layer. Your choice is saved with the
+            Bot.
+          </p>
+          <label v-if="flock.overlay === 'create'" class="flock-name"
+            >Bot name<input
+              v-model.trim="flock.draftName"
+              autofocus
+              maxlength="100"
+              required
+              autocomplete="off"
+          /></label>
+          <fieldset>
+            <legend>Sheep wardrobe</legend>
+            <div class="flock-select-grid">
+              <label
+                >Background<select v-model="flock.draftSheep.background">
+                  <option
+                    v-for="item in sheepCatalog.backgrounds"
+                    :key="item.id"
+                    :value="item.id"
+                  >
+                    {{ item.label }}
+                  </option>
+                </select></label
+              >
+              <label
+                >Headwear<select v-model="flock.draftSheep.upper">
+                  <option
+                    v-for="item in sheepCatalog.trees.upper"
+                    :key="item.id"
+                    :value="item.id"
+                  >
+                    {{ item.label }}
+                  </option>
+                </select></label
+              >
+              <label
+                >Face<select v-model="flock.draftSheep.middle">
+                  <option
+                    v-for="item in sheepCatalog.trees.middle"
+                    :key="item.id"
+                    :value="item.id"
+                  >
+                    {{ item.label }}
+                  </option>
+                </select></label
+              >
+              <label
+                >Neckwear<select v-model="flock.draftSheep.lower">
+                  <option
+                    v-for="item in sheepCatalog.trees.lower"
+                    :key="item.id"
+                    :value="item.id"
+                  >
+                    {{ item.label }}
+                  </option>
+                </select></label
+              >
+            </div>
+          </fieldset>
+          <div class="flock-note">
+            This identity is durable. Refreshing or switching devices won’t
+            re-roll it.
+          </div>
+          <p
+            v-if="flock.error"
+            class="flock-error"
+            role="alert"
+            aria-live="assertive"
+          >
+            {{ flock.error }}
+          </p>
+          <div class="flock-actions">
+            <button type="button" @click="flock.closeOverlay">Cancel</button
+            ><button class="primary" type="submit">
+              {{ flock.overlay === "create" ? "Create Bot" : "Save look" }}
+            </button>
+          </div>
+        </form>
+      </template>
+    </section>
+  </div>
+</template>