@caelo-cms/shared 0.10.22 → 0.10.24

package/src/page-log.test.ts

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #264 — unit coverage for the per-page log's pure logic: the shared
+ * append-input schema (the same one the op + tool validate against) and the
+ * `formatPageLogBlock` context-block renderer (non-empty gate, entry cap,
+ * <2 KB budget).
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  formatPageLogBlock,
+  type PageLogEntry,
+  pageLogAppendInputSchema,
+  pageLogEntrySchema,
+} from "./page-log.js";
+
+const PAGE = "11111111-1111-4111-8111-aaaaaaaaaaaa";
+
+function entry(over: Partial<PageLogEntry>): PageLogEntry {
+  return {
+    id: "22222222-2222-4222-8222-bbbbbbbbbbbb",
+    pageId: PAGE,
+    chatSessionId: null,
+    actorKind: "ai",
+    entryKind: "decision",
+    summary: "Chose a two-column hero to match the source layout.",
+    detail: null,
+    createdAt: "2026-07-13T10:00:00.000Z",
+    ...over,
+  };
+}
+
+describe("pageLogAppendInputSchema", () => {
+  it("accepts a minimal valid payload (no detail)", () => {
+    const r = pageLogAppendInputSchema.safeParse({
+      pageId: PAGE,
+      entryKind: "operator_answer",
+      summary: "Operator said keep the original blue, not the refreshed teal.",
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("accepts an object detail and every entry kind", () => {
+    for (const entryKind of [
+      "edited",
+      "decision",
+      "operator_answer",
+      "open_question",
+      "rebuilt",
+      "note",
+    ] as const) {
+      const r = pageLogAppendInputSchema.safeParse({
+        pageId: PAGE,
+        entryKind,
+        summary: "x",
+        detail: { chosen: "blue", operatorWords: "keep the blue" },
+      });
+      expect(r.success).toBe(true);
+    }
+  });
+
+  it("rejects an unknown entry kind, an empty summary, and a bad page id", () => {
+    expect(
+      pageLogAppendInputSchema.safeParse({ pageId: PAGE, entryKind: "deleted", summary: "x" })
+        .success,
+    ).toBe(false);
+    expect(
+      pageLogAppendInputSchema.safeParse({ pageId: PAGE, entryKind: "note", summary: "" }).success,
+    ).toBe(false);
+    expect(
+      pageLogAppendInputSchema.safeParse({ pageId: "not-a-uuid", entryKind: "note", summary: "x" })
+        .success,
+    ).toBe(false);
+  });
+
+  it("rejects unknown keys (strict) and a non-object detail", () => {
+    expect(
+      pageLogAppendInputSchema.safeParse({
+        pageId: PAGE,
+        entryKind: "note",
+        summary: "x",
+        extra: 1,
+      }).success,
+    ).toBe(false);
+    expect(
+      pageLogAppendInputSchema.safeParse({
+        pageId: PAGE,
+        entryKind: "note",
+        summary: "x",
+        detail: "a bare string",
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("formatPageLogBlock", () => {
+  it("returns null for an empty log so the header is omitted", () => {
+    expect(formatPageLogBlock([])).toBeNull();
+  });
+
+  it("renders the header, primer, and one line per entry newest-first", () => {
+    const block = formatPageLogBlock([
+      entry({ entryKind: "rebuilt", summary: "Rebuilt from the imported source." }),
+      entry({ entryKind: "operator_answer", summary: "Keep the blue.", actorKind: "human" }),
+    ]);
+    expect(block).not.toBeNull();
+    const b = block as string;
+    expect(b).toContain("## Page log");
+    expect(b).toContain("log_page_edit");
+    expect(b).toContain("- [rebuilt] Rebuilt from the imported source. (AI, 2026-07-13)");
+    expect(b).toContain("- [operator_answer] Keep the blue. (operator, 2026-07-13)");
+  });
+
+  it("caps the entry list and stays under 2 KB even with long summaries", () => {
+    const many: PageLogEntry[] = Array.from({ length: 40 }, (_, i) =>
+      entry({ id: `id-${i}`, summary: "Q".repeat(500) }),
+    );
+    const block = formatPageLogBlock(many) as string;
+    // 8 shown + a truncation notice line.
+    expect(block).toContain("32 older entries omitted.");
+    expect((block.match(/^- \[/gm) ?? []).length).toBe(8);
+    expect(Buffer.byteLength(block, "utf8")).toBeLessThan(2048);
+  });
+
+  it("uses the singular form when exactly one older entry is omitted", () => {
+    const nine: PageLogEntry[] = Array.from({ length: 9 }, (_, i) => entry({ id: `id-${i}` }));
+    const block = formatPageLogBlock(nine) as string;
+    expect(block).toContain("1 older entry omitted.");
+    expect(block).not.toContain("entries omitted");
+  });
+});
+
+describe("pageLogEntrySchema", () => {
+  // This is the contract `page_log.list` re-validates every DB row against,
+  // so schema-drift shapes (non-ISO timestamp, unknown enum value) must fail.
+  const valid = entry({});
+
+  it("accepts a well-formed row", () => {
+    expect(pageLogEntrySchema.safeParse(valid).success).toBe(true);
+  });
+
+  it("rejects a createdAt that is not an ISO datetime", () => {
+    for (const createdAt of ["2026-07-13", "yesterday", "1720900000000"]) {
+      expect(pageLogEntrySchema.safeParse({ ...valid, createdAt }).success).toBe(false);
+    }
+  });
+
+  it("rejects an unknown actorKind or entryKind (enum drift)", () => {
+    expect(pageLogEntrySchema.safeParse({ ...valid, actorKind: "robot" }).success).toBe(false);
+    expect(pageLogEntrySchema.safeParse({ ...valid, entryKind: "deleted" }).success).toBe(false);
+  });
+
+  it("rejects a non-uuid id and unknown keys (strict)", () => {
+    expect(pageLogEntrySchema.safeParse({ ...valid, id: "row-1" }).success).toBe(false);
+    expect(pageLogEntrySchema.safeParse({ ...valid, extra: 1 }).success).toBe(false);
+  });
+
+  it("rejects a non-object detail but accepts null", () => {
+    expect(pageLogEntrySchema.safeParse({ ...valid, detail: "corrupt" }).success).toBe(false);
+    expect(pageLogEntrySchema.safeParse({ ...valid, detail: null }).success).toBe(true);
+  });
+});

package/src/page-log.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #264 — the per-page edit LOG: durable, append-only work history so a
+ * later chat or a fresh subagent that touches a page knows WHY it was edited,
+ * what decisions were taken, and which operator answers shaped it — without
+ * dragging the originating chat's full transcript through its context.
+ *
+ * This is FACT (what happened), not learned BEHAVIOUR — so, unlike
+ * `site_ai_memory`, it is ungated: any actor appends directly. The shared
+ * Zod schemas here are the single source of truth for the `page_log.append`
+ * op input, the `log_page_edit` tool schema, and the `page_log.list` output.
+ * `formatPageLogBlock` renders the `## Page log` context block the AI reads
+ * before touching a page.
+ */
+
+import { z } from "zod";
+import type { ActorKind } from "./context.js";
+
+/**
+ * The kinds of log entry, in the order the AI should reach for them:
+ * - `edited` — a substantive content/module change was made.
+ * - `decision` — a design/structure call the AI made and its rationale.
+ * - `operator_answer` — an answer the operator gave that shaped the page.
+ * - `open_question` — something still unresolved a future turn must settle.
+ * - `rebuilt` — the page was rebuilt from scratch (e.g. migration rebuild).
+ * - `note` — anything else worth preserving for a future editor.
+ */
+export const pageLogEntryKinds = [
+  "edited",
+  "decision",
+  "operator_answer",
+  "open_question",
+  "rebuilt",
+  "note",
+] as const;
+
+export const pageLogEntryKindSchema = z.enum(pageLogEntryKinds);
+export type PageLogEntryKind = (typeof pageLogEntryKinds)[number];
+
+/**
+ * Optional structured context beyond the one-line summary — an OBJECT, never
+ * a bare scalar or array, so the jsonb column stores queryable keys (chosen
+ * option, operator's exact words, affected module ids). Writes go through
+ * `jsonbParam()` in the op handler to avoid the double-encode trap (issue
+ * #68).
+ */
+export const pageLogDetailSchema = z.record(z.string(), z.unknown());
+export type PageLogDetail = z.infer<typeof pageLogDetailSchema>;
+
+/** Input shape shared by `page_log.append` and the `log_page_edit` tool. */
+export const pageLogAppendInputSchema = z
+  .object({
+    pageId: z.string().uuid(),
+    entryKind: pageLogEntryKindSchema,
+    summary: z.string().min(1).max(2000),
+    detail: pageLogDetailSchema.optional(),
+  })
+  .strict();
+export type PageLogAppendInput = z.infer<typeof pageLogAppendInputSchema>;
+
+/** One row as returned by `page_log.list`. */
+export const pageLogEntrySchema = z
+  .object({
+    id: z.string().uuid(),
+    pageId: z.string().uuid(),
+    chatSessionId: z.string().uuid().nullable(),
+    actorKind: z.enum(["human", "ai", "plugin", "system"]),
+    entryKind: pageLogEntryKindSchema,
+    summary: z.string(),
+    detail: pageLogDetailSchema.nullable(),
+    // ISO datetime, not just any string: the value is `created_at` sliced to a
+    // date and rendered into the AI context block — a real contract catches
+    // drift (a raw pg timestamp, a number) at the op boundary instead of
+    // producing a garbled `## Page log` line.
+    createdAt: z.string().datetime(),
+  })
+  .strict();
+export type PageLogEntry = z.infer<typeof pageLogEntrySchema>;
+
+const ACTOR_LABEL: Record<ActorKind, string> = {
+  human: "operator",
+  ai: "AI",
+  plugin: "plugin",
+  system: "system",
+};
+
+/**
+ * Render the `## Page log` context block for a single page's recent entries
+ * (newest first). Returns `null` when there is nothing to show, so the
+ * caller omits the header entirely (CLAUDE.md §11 — render only when
+ * non-empty). Kept well under 2 KB: entries are capped and each summary is
+ * clamped, because the block rides in the system prompt on every turn that
+ * touches the page.
+ *
+ * @param entries page log rows, expected newest-first (as `page_log.list`
+ *   returns them). The renderer does not re-sort.
+ */
+export function formatPageLogBlock(entries: readonly PageLogEntry[]): string | null {
+  if (entries.length === 0) return null;
+  // Capped + clamped to stay comfortably under 2 KB: the block rides in the
+  // system prompt on every turn that touches the page.
+  const MAX_ENTRIES = 8;
+  const MAX_SUMMARY = 160;
+  const shown = entries.slice(0, MAX_ENTRIES);
+  const lines: string[] = [
+    "## Page log",
+    "",
+    "Prior work on THIS page — read it before you change the page so you build on settled decisions instead of re-litigating them. After a meaningful change, append your own entry with `log_page_edit`.",
+    "",
+  ];
+  for (const e of shown) {
+    const who = ACTOR_LABEL[e.actorKind] ?? e.actorKind;
+    const when = e.createdAt.slice(0, 10);
+    const summary =
+      e.summary.length > MAX_SUMMARY ? `${e.summary.slice(0, MAX_SUMMARY - 3)}...` : e.summary;
+    lines.push(`- [${e.entryKind}] ${summary} (${who}, ${when})`);
+  }
+  if (entries.length > MAX_ENTRIES) {
+    const omitted = entries.length - MAX_ENTRIES;
+    lines.push(`- ${omitted} older ${omitted === 1 ? "entry" : "entries"} omitted.`);
+  }
+  return lines.join("\n");
+}