@frockbot/plugin-search 0.0.0 → 0.1.1

package/src/client/styles.css

@@ -0,0 +1,225 @@
+/* The Search surface and its sidebar control. */
+
+/*
+ * The shell gives the search control the flexible half of the sidebar's top
+ * row; the Flock's create button occupies the fixed half.
+ */
+.search-box {
+  display: flex;
+  width: 100%;
+  height: var(--frock-control-md);
+  min-width: 0;
+  -webkit-app-region: no-drag;
+  gap: 8px;
+  align-items: center;
+  padding: 0 10px;
+  color: var(--frock-text-muted);
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+  background: var(--frock-surface-subtle);
+  border: 1px solid var(--frock-border);
+  border-radius: var(--frock-radius-control);
+}
+
+.search-box:hover {
+  color: var(--frock-text);
+  background: var(--frock-fill-hover);
+}
+
+.search-box:focus-visible {
+  outline: var(--frock-focus-ring);
+}
+
+.search-box-label {
+  overflow: hidden;
+  flex: 1 1 auto;
+  font-size: var(--frock-text-sm);
+  white-space: nowrap;
+}
+
+/*
+ * On a phone the control is the magnifier and nothing else. The word and the
+ * shortcut cost about a third of the topbar, which is the room the Bot's name
+ * needs — and a keyboard shortcut is a promise a touch device cannot keep. The
+ * button keeps its accessible name either way.
+ */
+@media (max-width: 640px) {
+  .search-box {
+    padding: 6px;
+  }
+
+  .search-box-label,
+  .search-box-shortcut {
+    display: none;
+  }
+}
+
+.search-surface {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.search-input-row {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  padding: 8px 10px;
+  color: var(--frock-text-muted);
+  background: var(--frock-surface-subtle);
+  border: 1px solid var(--frock-border-strong);
+  border-radius: var(--frock-radius-control);
+}
+
+.search-input {
+  flex: 1 1 auto;
+  min-width: 0;
+  font-size: var(--frock-text-base);
+  color: var(--frock-text);
+  background: transparent;
+  border: 0;
+}
+
+.search-input:focus {
+  outline: none;
+}
+
+.search-filters {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+}
+
+.search-filter {
+  display: inline-flex;
+  gap: 6px;
+  align-items: center;
+  font-size: var(--frock-text-sm);
+  color: var(--frock-text-muted);
+}
+
+.search-rebuild {
+  margin-left: auto;
+}
+
+.search-note {
+  padding: 8px 10px;
+  font-size: var(--frock-text-sm);
+  color: var(--frock-text-muted);
+  background: var(--frock-surface-subtle);
+  border-radius: var(--frock-radius-control);
+}
+
+.search-error {
+  padding: 8px 10px;
+  font-size: var(--frock-text-sm);
+  color: var(--frock-danger-text);
+  background: var(--frock-danger-surface);
+  border: 1px solid var(--frock-danger-border);
+  border-radius: var(--frock-radius-control);
+}
+
+.search-empty {
+  padding: 24px 8px;
+  font-size: var(--frock-text-sm);
+  color: var(--frock-text-subtle);
+  text-align: center;
+}
+
+.search-groups,
+.search-hits {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+.search-group {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.search-group-head {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.search-group-avatar {
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+  width: var(--frock-avatar-sm);
+  height: var(--frock-avatar-sm);
+  overflow: hidden;
+  object-fit: cover;
+  border-radius: 9px;
+}
+
+.search-group-monogram {
+  font-size: var(--frock-text-sm);
+  color: var(--frock-accent-text);
+  background: var(--frock-surface-accent);
+}
+
+.search-group-name {
+  font-size: var(--frock-text-sm);
+  color: var(--frock-text);
+}
+
+.search-tag {
+  padding: 1px 6px;
+  font-size: var(--frock-text-xs);
+  color: var(--frock-text-subtle);
+  background: var(--frock-surface-subtle);
+  border: 1px solid var(--frock-border);
+  border-radius: 999px;
+}
+
+.search-group-count {
+  margin-left: auto;
+  font-size: var(--frock-text-xs);
+  color: var(--frock-text-subtle);
+}
+
+.search-hit {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  width: 100%;
+  padding: 8px 10px;
+  text-align: left;
+  cursor: pointer;
+  background: var(--frock-surface-subtle);
+  border: 1px solid var(--frock-border);
+  border-radius: var(--frock-radius-control);
+}
+
+.search-hit:hover {
+  background: var(--frock-fill-hover);
+}
+
+.search-hit:focus-visible {
+  outline: var(--frock-focus-ring);
+}
+
+.search-hit-meta {
+  display: flex;
+  gap: 8px;
+  font-size: var(--frock-text-xs);
+  color: var(--frock-text-subtle);
+}
+
+.search-hit-kind {
+  color: var(--frock-text-muted);
+}
+
+.search-hit-snippet {
+  font-size: var(--frock-text-sm);
+  color: var(--frock-text);
+}

package/src/env.d.ts

@@ -0,0 +1,5 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent<object, object, unknown>;
+  export default component;
+}

package/src/groups.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, test } from "bun:test";
+import { groupSearchHitsV1, type SearchBotDescriptorV1 } from "./groups.ts";
+import {
+  decodeClientSearchResultsV1,
+  type SearchIndexResultsV1,
+} from "./shared.ts";
+
+const AT = "2026-08-31T00:00:00.000Z";
+
+function results(
+  hits: Array<{ botId: string; runId: string }>,
+  overrides: Partial<SearchIndexResultsV1> = {},
+): SearchIndexResultsV1 {
+  return {
+    schemaVersion: 1,
+    query: "gym",
+    hits: hits.map((hit) => ({
+      botId: hit.botId,
+      runId: hit.runId,
+      kind: "user" as const,
+      at: AT,
+      snippet: "the gym build",
+    })),
+    truncated: false,
+    indexState: "ready",
+    ...overrides,
+  };
+}
+
+const DIRECTORY: SearchBotDescriptorV1[] = [
+  { botId: "bot-a", name: "Site foreman", archived: false, hidden: false },
+  { botId: "bot-b", name: "Bookkeeper", archived: false, hidden: true },
+  { botId: "bot-c", name: "Old hand", archived: true, hidden: false },
+];
+
+describe("grouping hits by Bot", () => {
+  test("keeps rank order for groups and for hits inside a group", () => {
+    const grouped = groupSearchHitsV1(
+      results([
+        { botId: "bot-b", runId: "run-1" },
+        { botId: "bot-a", runId: "run-2" },
+        { botId: "bot-b", runId: "run-3" },
+      ]),
+      DIRECTORY,
+    );
+    expect(grouped.groups.map((group) => group.botId)).toEqual([
+      "bot-b",
+      "bot-a",
+    ]);
+    expect(grouped.groups[0]!.hits.map((hit) => hit.runId)).toEqual([
+      "run-1",
+      "run-3",
+    ]);
+    expect(grouped.groups[0]!.totalHits).toBe(2);
+  });
+
+  test("names each Bot from the live directory and labels hidden and archived", () => {
+    const grouped = groupSearchHitsV1(
+      results([
+        { botId: "bot-b", runId: "run-1" },
+        { botId: "bot-c", runId: "run-2" },
+      ]),
+      DIRECTORY,
+    );
+    expect(grouped.groups[0]).toMatchObject({
+      botName: "Bookkeeper",
+      hidden: true,
+      archived: false,
+    });
+    expect(grouped.groups[1]).toMatchObject({
+      botName: "Old hand",
+      archived: true,
+    });
+  });
+
+  test("builds the deep link so no client assembles one", () => {
+    const grouped = groupSearchHitsV1(
+      results([{ botId: "bot-a", runId: "run-2" }]),
+      DIRECTORY,
+    );
+    expect(grouped.groups[0]!.hits[0]!.deepLink).toBe("/?bot=bot-a#turn-run-2");
+  });
+
+  test("keeps a hit whose Bot the directory no longer describes", () => {
+    const grouped = groupSearchHitsV1(
+      results([{ botId: "bot-gone", runId: "run-9" }]),
+      DIRECTORY,
+    );
+    expect(grouped.groups[0]).toMatchObject({
+      botId: "bot-gone",
+      botName: "bot-gone",
+      archived: false,
+      hidden: false,
+    });
+  });
+
+  test("carries the page and index state through", () => {
+    const grouped = groupSearchHitsV1(
+      results([{ botId: "bot-a", runId: "run-1" }], {
+        truncated: true,
+        nextCursor: "p50",
+        indexState: "truncated",
+      }),
+      DIRECTORY,
+    );
+    expect(grouped.page).toEqual({ truncated: true, nextCursor: "p50" });
+    expect(grouped.indexState).toBe("truncated");
+  });
+
+  test("produces a value the client decoder accepts unchanged", () => {
+    const grouped = groupSearchHitsV1(
+      results([
+        { botId: "bot-a", runId: "run-1" },
+        { botId: "bot-c", runId: "run-2" },
+      ]),
+      [
+        ...DIRECTORY,
+        {
+          botId: "bot-a",
+          name: "Site foreman",
+          archived: false,
+          hidden: false,
+        },
+      ],
+    );
+    expect(
+      decodeClientSearchResultsV1(JSON.parse(JSON.stringify(grouped))),
+    ).toEqual(grouped);
+  });
+});

package/src/groups.ts

@@ -0,0 +1,78 @@
+// Hits, grouped into the shape a person reads.
+//
+// The index answers with a flat, ranked list of `(botId, runId)` hits and
+// knows nothing about Bots beyond their ids — deliberately, because Bot
+// identity is the Flock Contribution's authority and a name copied into a row
+// would be stale the moment a Bot is renamed. This module is the join: it
+// reads the live directory and turns hits into groups the WebUI renders.
+//
+// Pure, so it is its own test surface. It is the only place a deep link is
+// built, so a client never assembles one from parts it might get wrong.
+import {
+  searchDeepLinkV1,
+  SEARCH_MAX_GROUPS_V1,
+  type ClientSearchBotGroupV1,
+  type ClientSearchResultsV1,
+  type SearchIndexResultsV1,
+} from "./shared.js";
+
+/** One Bot, as the live directory describes it at query time. */
+export interface SearchBotDescriptorV1 {
+  botId: string;
+  name: string;
+  archived: boolean;
+  /** A Bot its own settings keep out of the sidebar. Searchable, and labelled. */
+  hidden: boolean;
+}
+
+/**
+ * Groups a page of hits by Bot, newest-ranked group first.
+ *
+ * Rank order is preserved twice over: groups appear in the order their best
+ * hit did, and hits keep their order inside a group. A Bot the directory no
+ * longer describes still gets a group, labelled by its id: the alternative is
+ * dropping a hit the index legitimately holds because a rename raced a query.
+ */
+export function groupSearchHitsV1(
+  results: SearchIndexResultsV1,
+  directory: readonly SearchBotDescriptorV1[],
+): ClientSearchResultsV1 {
+  const described = new Map(directory.map((bot) => [bot.botId, bot]));
+  const groups = new Map<string, ClientSearchBotGroupV1>();
+  for (const hit of results.hits) {
+    let group = groups.get(hit.botId);
+    if (!group) {
+      if (groups.size >= SEARCH_MAX_GROUPS_V1) continue;
+      const bot = described.get(hit.botId);
+      group = {
+        botId: hit.botId,
+        botName: bot?.name ?? hit.botId,
+        archived: bot?.archived ?? false,
+        hidden: bot?.hidden ?? false,
+        hits: [],
+        totalHits: 0,
+      };
+      groups.set(hit.botId, group);
+    }
+    group.hits.push({
+      runId: hit.runId,
+      kind: hit.kind,
+      at: hit.at,
+      snippet: hit.snippet,
+      deepLink: searchDeepLinkV1(hit.botId, hit.runId),
+    });
+    group.totalHits += 1;
+  }
+  return {
+    schemaVersion: 1,
+    query: results.query,
+    groups: [...groups.values()],
+    page: {
+      truncated: results.truncated,
+      ...(results.nextCursor === undefined
+        ? {}
+        : { nextCursor: results.nextCursor }),
+    },
+    indexState: results.indexState,
+  };
+}

package/src/index-store.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, test } from "bun:test";
+import { SearchIndexV1, searchMatchExpressionV1 } from "./index-store.ts";
+import { FakeSearchSql } from "./testing.ts";
+import type { SearchRowV1 } from "./shared.ts";
+
+function row(overrides: Partial<SearchRowV1> = {}): SearchRowV1 {
+  return {
+    botId: "bot-a",
+    runId: "run-1",
+    seq: 0,
+    kind: "user",
+    at: "2026-08-31T00:00:00.000Z",
+    body: "the gym build in Wollongong",
+    ...overrides,
+  };
+}
+
+function index(maxRows?: number) {
+  const sql = new FakeSearchSql();
+  return {
+    sql,
+    index: new SearchIndexV1({
+      sql,
+      ...(maxRows === undefined ? {} : { maxRows }),
+    }),
+  };
+}
+
+const NO_ARCHIVED = { archivedBotIds: [] as string[] };
+
+describe("the FTS5 match expression", () => {
+  test("quotes every token, so FTS5 syntax is searched for and never executed", () => {
+    expect(searchMatchExpressionV1("gym build")).toBe('"gym" "build"*');
+    // `NEAR`, `OR`, `-`, `^` and a column filter are all literal text here.
+    expect(searchMatchExpressionV1("NEAR(a b) OR -c^")).toBe(
+      '"NEAR" "a" "b" "OR" "c"*',
+    );
+  });
+
+  test("a query with no word characters matches nothing at all", () => {
+    expect(searchMatchExpressionV1("   *  ")).toBeUndefined();
+  });
+});
+
+describe("the transcript index", () => {
+  test("indexes a row and finds it", () => {
+    const { index: store } = index();
+    expect(store.insert([row()])).toBe(1);
+    const results = store.query(
+      { schemaVersion: 1, query: "wollongong" },
+      NO_ARCHIVED,
+    );
+    expect(results.hits).toHaveLength(1);
+    expect(results.hits[0]).toMatchObject({ botId: "bot-a", runId: "run-1" });
+    expect(results.indexState).toBe("ready");
+  });
+
+  test("is idempotent on (botId, runId, seq)", () => {
+    const { index: store } = index();
+    expect(store.insert([row(), row()])).toBe(1);
+    expect(store.insert([row()])).toBe(0);
+    expect(store.count()).toBe(1);
+  });
+
+  test("excludes tool rows by default and returns them when asked", () => {
+    const { index: store } = index();
+    store.insert([
+      row({ seq: 0, kind: "user", body: "run the deploy" }),
+      row({ seq: 1, kind: "tool", body: "shell\ndeploy token abc" }),
+    ]);
+    expect(
+      store.query({ schemaVersion: 1, query: "deploy" }, NO_ARCHIVED).hits,
+    ).toHaveLength(1);
+    expect(
+      store.query(
+        { schemaVersion: 1, query: "deploy", kinds: ["tool"] },
+        NO_ARCHIVED,
+      ).hits,
+    ).toHaveLength(1);
+  });
+
+  test("hides an archived Bot's rows unless they are opted in", () => {
+    const { index: store } = index();
+    store.insert([row({ botId: "bot-archived" })]);
+    const directory = { archivedBotIds: ["bot-archived"] };
+    expect(
+      store.query({ schemaVersion: 1, query: "wollongong" }, directory).hits,
+    ).toHaveLength(0);
+    expect(
+      store.query(
+        { schemaVersion: 1, query: "wollongong", includeArchived: true },
+        directory,
+      ).hits,
+    ).toHaveLength(1);
+  });
+
+  test("filters to one Bot", () => {
+    const { index: store } = index();
+    store.insert([row({ botId: "bot-a" }), row({ botId: "bot-b" })]);
+    const results = store.query(
+      { schemaVersion: 1, query: "wollongong", botId: "bot-b" },
+      NO_ARCHIVED,
+    );
+    expect(results.hits.map((hit) => hit.botId)).toEqual(["bot-b"]);
+  });
+
+  test("refuses a cursor it did not mint", () => {
+    const { index: store } = index();
+    expect(() =>
+      store.query(
+        { schemaVersion: 1, query: "gym", before: "'; DROP TABLE" },
+        NO_ARCHIVED,
+      ),
+    ).toThrow("cursor is invalid");
+  });
+
+  test("evicts the oldest rows over quota and records a durable marker", () => {
+    const { index: store } = index(2);
+    store.insert([
+      row({ runId: "run-1", at: "2026-08-01T00:00:00.000Z" }),
+      row({ runId: "run-2", at: "2026-08-02T00:00:00.000Z" }),
+      row({ runId: "run-3", at: "2026-08-03T00:00:00.000Z" }),
+    ]);
+    expect(store.count()).toBe(2);
+    expect(store.state()).toBe("truncated");
+    const results = store.query(
+      { schemaVersion: 1, query: "wollongong" },
+      NO_ARCHIVED,
+    );
+    expect(results.hits.map((hit) => hit.runId)).toEqual(["run-2", "run-3"]);
+    expect(results.indexState).toBe("truncated");
+  });
+
+  test("purges one Bot and leaves the others", () => {
+    const { index: store } = index();
+    store.insert([row({ botId: "bot-a" }), row({ botId: "bot-b" })]);
+    expect(store.purge("bot-a")).toBe(1);
+    expect(store.count()).toBe(1);
+    expect(
+      store.query({ schemaVersion: 1, query: "gym" }, NO_ARCHIVED).hits[0]
+        ?.botId,
+    ).toBe("bot-b");
+  });
+
+  test("a rebuild from an emptied table reproduces the identical result set", async () => {
+    const { index: store } = index();
+    const rows = [
+      row({ botId: "bot-a", runId: "run-1", seq: 0 }),
+      row({
+        botId: "bot-a",
+        runId: "run-1",
+        seq: 1,
+        kind: "assistant",
+        body: "Wollongong noted.",
+      }),
+      row({ botId: "bot-b", runId: "run-2", seq: 0, body: "the gym roster" }),
+    ];
+    store.insert(rows);
+    const before = store.query({ schemaVersion: 1, query: "gym" }, NO_ARCHIVED);
+
+    const outcome = await store.rebuild([
+      {
+        botId: "bot-a",
+        page: async (cursor) =>
+          cursor
+            ? { rows: rows.slice(1, 2) }
+            : { rows: rows.slice(0, 1), nextCursor: "page-2" },
+      },
+      { botId: "bot-b", page: async () => ({ rows: rows.slice(2) }) },
+    ]);
+
+    expect(outcome).toEqual({ indexedRows: 3, bots: 2, indexState: "ready" });
+    expect(
+      store.query({ schemaVersion: 1, query: "gym" }, NO_ARCHIVED),
+    ).toEqual(before);
+  });
+
+  test("a rebuild clears a truncation marker it no longer needs", async () => {
+    const { index: store } = index(1);
+    store.insert([
+      row({ runId: "run-1", at: "2026-08-01T00:00:00.000Z" }),
+      row({ runId: "run-2", at: "2026-08-02T00:00:00.000Z" }),
+    ]);
+    expect(store.state()).toBe("truncated");
+    await store.rebuild([
+      {
+        botId: "bot-a",
+        page: async () => ({ rows: [row({ runId: "run-9" })] }),
+      },
+    ]);
+    expect(store.state()).toBe("ready");
+  });
+
+  test("a rebuild refuses rows a Bot offers on another Bot's behalf", async () => {
+    const { index: store } = index();
+    await store.rebuild([
+      {
+        botId: "bot-a",
+        page: async () => ({
+          rows: [row({ botId: "bot-a" }), row({ botId: "bot-elsewhere" })],
+        }),
+      },
+    ]);
+    expect(store.count()).toBe(1);
+  });
+});