@fungi.computer/bonsai 0.0.0-stage → 0.0.1

package/shared/contract.ts

@@ -0,0 +1,404 @@
+/**
+ * The Bonsai HTTP contract. The Worker produces these shapes and the web UI
+ * (or any other client) parses them at its boundary. Nothing here knows about
+ * Cloudflare, Fungi or React.
+ */
+import * as z from "zod";
+import {
+  gitRepositoryNameSchema as repoName,
+  gitSha1Schema as hash,
+} from "@fungi.computer/puffball/git-representation";
+import { commit } from "@fungi.computer/agar/roles/files";
+
+export const productName = "Bonsai";
+
+/** Any JSON value: App method inputs and results travel as JSON. */
+export const jsonValue = z.json();
+export type JsonValue = z.infer<typeof jsonValue>;
+
+const agent = z.strictObject({
+  id: z.string(),
+  name: z.string(),
+  color: z.string(),
+  kind: z.enum(["agent", "human"]),
+  createdAt: z.number(),
+});
+export type Agent = z.infer<typeof agent>;
+
+export const ref = z.strictObject({
+  name: z.string(),
+  hash,
+});
+export type Ref = z.infer<typeof ref>;
+
+export const repoSummary = z.strictObject({
+  name: repoName,
+  description: z.string().nullable(),
+  parent: repoName.nullable(),
+  owner: z.string().nullable(),
+  createdAt: z.number(),
+  lastPushAt: z.number().nullable(),
+  forks: z.array(repoName),
+  /** Locally stored open or merging Changes; canonical summaries include their family. */
+  openChanges: z.number().int().nonnegative(),
+  /** Pushes per hour bucket for the last 24 hours, oldest first. */
+  activity: z.array(z.number()),
+});
+export type RepoSummary = z.infer<typeof repoSummary>;
+
+export const repoDetail = z.strictObject({
+  repo: repoSummary,
+  defaultBranch: z.string(),
+  refs: z.array(ref),
+  cloneUrl: z.string(),
+  empty: z.boolean(),
+});
+export type RepoDetail = z.infer<typeof repoDetail>;
+
+const fileDiff = z.strictObject({
+  path: z.string(),
+  oldPath: z.string().nullable(),
+  status: z.enum(["added", "removed", "modified"]),
+  additions: z.number(),
+  deletions: z.number(),
+  binary: z.boolean(),
+  /** True when the file was too large to show. */
+  truncated: z.boolean(),
+  /** Both sides in full, for the diff viewer; null when binary or too large. */
+  oldText: z.string().nullable(),
+  newText: z.string().nullable(),
+});
+export type FileDiff = z.infer<typeof fileDiff>;
+
+const diff = z.strictObject({
+  files: z.array(fileDiff),
+  additions: z.number(),
+  deletions: z.number(),
+  /** Files beyond the response limit, counted but not listed. */
+  omittedFiles: z.number(),
+});
+export type Diff = z.infer<typeof diff>;
+
+export const commitDetail = z.strictObject({
+  commit,
+  agent: z.string().nullable(),
+  diff,
+});
+export type CommitDetail = z.infer<typeof commitDetail>;
+
+export const readCopyPageInput = z.strictObject({
+  limit: z.number().int().min(1).max(100).default(100),
+  after: z.string().optional(),
+});
+export type ReadCopyPageInput = z.input<typeof readCopyPageInput>;
+
+/** One lane of the network graph: a branch in the canonical repo or a fork. */
+const graphLane = z.strictObject({
+  id: z.string(),
+  repo: repoName,
+  ref: z.string(),
+  owner: z.string().nullable(),
+  head: hash,
+  canonical: z.boolean(),
+});
+export type GraphLane = z.infer<typeof graphLane>;
+
+const graphNode = z.strictObject({
+  hash,
+  parents: z.array(hash),
+  message: z.string(),
+  author: z.string(),
+  agent: z.string().nullable(),
+  /** The repository the commit was first pushed to, when Bonsai saw the push. */
+  origin: repoName.nullable(),
+  committedAt: z.number(),
+  /** Lanes whose history contains this commit, canonical lanes first. */
+  lanes: z.array(z.string()),
+});
+export type GraphNode = z.infer<typeof graphNode>;
+
+export const graph = z.strictObject({
+  lanes: z.array(graphLane),
+  nodes: z.array(graphNode),
+});
+export type Graph = z.infer<typeof graph>;
+
+const refUpdate = z.strictObject({
+  ref: z.string(),
+  before: hash,
+  after: hash,
+});
+
+/** Identity included in every Change event, pinned to the proposed head. */
+export const changeIdentity = z.strictObject({
+  repo: repoName,
+  number: z.number().int().positive(),
+  sourceRepo: repoName,
+  sourceRef: z.string(),
+  targetRef: z.string(),
+  head: hash,
+});
+
+/** Activity recorded by Bonsai. Hook deliveries carry the same events. */
+export const activity = z.discriminatedUnion("type", [
+  z.strictObject({
+    id: z.number(),
+    at: z.number(),
+    type: z.enum([
+      "change.opened",
+      "change.updated",
+      "change.approved",
+      "change.checks_requested",
+      "change.checked",
+      "change.closed",
+    ]),
+    repo: repoName,
+    actor: z.string(),
+    data: z.strictObject({
+      change: changeIdentity,
+      before: hash.optional(),
+      after: hash.optional(),
+      name: z.string().optional(),
+      status: z.enum(["queued", "running", "passed", "failed"]).optional(),
+      names: z.array(z.string()).optional(),
+    }),
+  }),
+  z.strictObject({
+    id: z.number(),
+    at: z.number(),
+    type: z.literal("push"),
+    repo: repoName,
+    actor: z.string(),
+    data: z.strictObject({
+      updates: z.array(refUpdate),
+      commits: z.array(z.strictObject({ hash, message: z.string() })),
+      paths: z.array(z.string()),
+    }),
+  }),
+  z.strictObject({
+    id: z.number(),
+    at: z.number(),
+    type: z.literal("fork"),
+    repo: repoName,
+    actor: z.string(),
+    data: z.strictObject({ fork: repoName }),
+  }),
+  z.strictObject({
+    id: z.number(),
+    at: z.number(),
+    type: z.literal("repo.created"),
+    repo: repoName,
+    actor: z.string(),
+    data: z.strictObject({}),
+  }),
+  z.strictObject({
+    id: z.number(),
+    at: z.number(),
+    type: z.literal("merge"),
+    repo: repoName,
+    actor: z.string(),
+    data: z.strictObject({
+      change: changeIdentity,
+      from: repoName,
+      ref: z.string(),
+      before: hash,
+      after: hash,
+    }),
+  }),
+  z.strictObject({
+    id: z.number(),
+    at: z.number(),
+    type: z.literal("merge.conflict"),
+    repo: repoName,
+    actor: z.string(),
+    data: z.strictObject({
+      change: changeIdentity,
+      from: repoName,
+      ref: z.string(),
+      paths: z.array(z.string()),
+    }),
+  }),
+]);
+export type Activity = z.infer<typeof activity>;
+
+/** Stored proposal identity; review facts are pinned to its head. */
+export const changeRecord = z.strictObject({
+  repo: repoName,
+  number: z.number().int().positive(),
+  sourceRepo: repoName,
+  sourceRef: z.string(),
+  targetRef: z.string(),
+  title: z.string().min(1).max(200),
+  body: z.string().max(20_000),
+  openedBy: z.string(),
+  openedKind: z.enum(["human", "agent"]),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  state: z.enum(["open", "merging", "merged", "closed"]),
+  head: hash,
+  target: hash,
+  revision: z.number().int().nonnegative(),
+  conflict: z
+    .strictObject({ head: hash, target: hash, paths: z.array(z.string()) })
+    .nullable(),
+  lease: z
+    .strictObject({
+      id: z.string(),
+      by: z.string(),
+      head: hash,
+      at: z.number(),
+    })
+    .nullable(),
+  mergedCommit: hash.nullable(),
+  mergedBy: z.string().nullable(),
+  closedBy: z.string().nullable(),
+  /** Present only after a queued merge could not complete. */
+  mergeFailure: z
+    .enum(["access_changed", "sync_failed", "head_moved"])
+    .optional(),
+});
+export type ChangeRecord = z.infer<typeof changeRecord>;
+/** Project the exact identity repeated in every Change delivery. */
+export function changeIdentityOf(row: ChangeRecord) {
+  return {
+    repo: row.repo,
+    number: row.number,
+    sourceRepo: row.sourceRepo,
+    sourceRef: row.sourceRef,
+    targetRef: row.targetRef,
+    head: row.head,
+  };
+}
+const policyReason = z.enum([
+  "not-open",
+  "merging",
+  "moved",
+  "conflict",
+  "needs-approval",
+  "self-approval",
+  "checks-failed",
+  "checks-running",
+  "not-maintainer",
+  "agents-cannot-merge",
+  "agents-cannot-approve",
+  "not-source-writer",
+  "not-authorized",
+]);
+export const policyDecision = z.discriminatedUnion("allowed", [
+  z.strictObject({ allowed: z.literal(true) }),
+  z.strictObject({ allowed: z.literal(false), reason: policyReason }),
+]);
+export type PolicyDecision = z.infer<typeof policyDecision>;
+const changeStatus = z.enum([
+  "conflict",
+  "checks-failed",
+  "checks-running",
+  "needs-approval",
+  "ready",
+  "merging",
+  "merged",
+  "closed",
+]);
+/** `self` is a sole Team member's approval of their own work. */
+export const approval = z.strictObject({
+  actor: z.string(),
+  kind: z.enum(["human", "agent", "self"]),
+  head: hash,
+  at: z.number(),
+});
+export type Approval = z.infer<typeof approval>;
+export const check = z.strictObject({
+  head: hash,
+  name: z.string().min(1).max(100),
+  status: z.enum(["queued", "running", "passed", "failed"]),
+  reporter: z.string(),
+  attemptId: z.string().min(1).max(512),
+  runUrl: z.url().nullable(),
+  summary: z.string().max(4000).nullable(),
+  updatedAt: z.number(),
+});
+export type Check = z.infer<typeof check>;
+const change = changeRecord.extend({
+  status: changeStatus,
+  mergeable: policyDecision,
+  base: hash.nullable(),
+  ahead: z.number(),
+  behind: z.number(),
+});
+export type Change = z.infer<typeof change>;
+export const changePage = z.strictObject({
+  changes: z.array(change),
+  next: z.string().optional(),
+});
+export type ChangePage = z.infer<typeof changePage>;
+export const changeDetail = z.strictObject({
+  change,
+  actions: z.strictObject({ approve: policyDecision, close: policyDecision }),
+  commits: z.array(z.strictObject({ commit, agent: z.string().nullable() })),
+  diff,
+  review: z.strictObject({
+    approvals: z.array(approval),
+    checks: z.array(check),
+  }),
+});
+export type ChangeDetail = z.infer<typeof changeDetail>;
+export const mergeResult = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("merging") }),
+  z.strictObject({ kind: z.literal("merged"), before: hash, after: hash }),
+  z.strictObject({ kind: z.literal("moved"), head: hash }),
+  z.strictObject({
+    kind: z.literal("conflict"),
+    paths: z.array(z.string()),
+    head: hash,
+  }),
+  z.strictObject({ kind: z.literal("refused"), reason: policyReason }),
+]);
+export type MergeResult = z.infer<typeof mergeResult>;
+
+export const approvalResult = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("approved") }),
+  z.strictObject({ kind: z.literal("moved"), head: hash }),
+  z.strictObject({ kind: z.literal("refused"), reason: policyReason }),
+]);
+export const checkRequestResult = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("requested"), attemptId: z.string() }),
+  z.strictObject({ kind: z.literal("moved"), head: hash }),
+  z.strictObject({ kind: z.literal("refused"), reason: policyReason }),
+]);
+export const checkReportResult = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("recorded") }),
+  z.strictObject({ kind: z.literal("moved"), head: hash }),
+  z.strictObject({ kind: z.literal("settled") }),
+  z.strictObject({ kind: z.literal("refused"), reason: policyReason }),
+]);
+export type ApprovalResult = z.infer<typeof approvalResult>;
+export type CheckRequestResult = z.infer<typeof checkRequestResult>;
+export type CheckReportResult = z.infer<typeof checkReportResult>;
+
+export const activityPage = z.strictObject({ events: z.array(activity) });
+
+export const agentPage = z.strictObject({ agents: z.array(agent) });
+
+/** The Markdown files under issues/, keyed by path relative to issues/. */
+export const issueFiles = z.strictObject({
+  ref: z.string(),
+  commit,
+  files: z.record(z.string(), z.string()),
+  truncated: z.boolean(),
+});
+export type IssueFiles = z.infer<typeof issueFiles>;
+export const repoPage = z.strictObject({ repos: z.array(repoSummary) });
+
+/** One App build job as its owner sees it; a settled success carries its Release. */
+export const appBuildView = z.strictObject({
+  jobId: z.string().min(1).max(256),
+  appId: z.string().min(1).max(256),
+  releaseId: z.string().min(1).max(256),
+  sourceRevision: z.string().min(1).max(256),
+  status: z.enum(["running", "succeeded", "failed", "revoked"]),
+  detail: z.string().max(65_536).nullable(),
+  /** The recorded Release, parsed by its owner where it is installed. */
+  release: z.unknown(),
+});
+
+export const errorBody = z.strictObject({ error: z.string() });

package/shared/hooks.ts

@@ -0,0 +1,208 @@
+/**
+ * Bonsai's events: the public, versioned envelope Bonsai emits through its host
+ * (the Oyster EVENTS binding) and the signatures that prove a delivery came
+ * from Bonsai. Runtime-neutral (Web Crypto only), so any consumer can import it
+ * to verify and parse a delivery.
+ *
+ * The body follows the Standard Webhooks payload shape (type, timestamp and
+ * data). A standalone host delivers it as an HTTP POST signed with Standard
+ * Webhooks headers (webhook-id, webhook-timestamp, webhook-signature) and,
+ * for receivers built for other git hosts, X-Hub-Signature-256 (sha256=HEX of
+ * the body), X-GitHub-Delivery and X-GitHub-Event. Bonsai-Signature
+ * (t=SECONDS,v1=HEX of "SECONDS.BODY") is checked by `verifyHook` below.
+ * A subscriber answers 2xx to accept; anything else is retried with backoff.
+ */
+import * as z from "zod";
+import { activity, changeIdentity, type Activity } from "./contract.js";
+
+export const hookSpec = "bonsai.event/v1";
+
+/** Every Change delivery carries its stored proposal identity. */
+const changeTypes = [
+  "change.opened",
+  "change.updated",
+  "change.approved",
+  "change.checks_requested",
+  "change.checked",
+  "change.merged",
+  "change.conflicted",
+  "change.closed",
+] as const;
+const gitTypes = ["git.push", "git.fork", "repo.created"] as const;
+const eventData = z.strictObject({
+  spec: z.literal(hookSpec),
+  eventId: z.string(),
+  repository: z.strictObject({
+    name: z.string(),
+    canonical: z.string(),
+    cloneUrl: z.url(),
+  }),
+  actor: z.string(),
+  activity,
+});
+const gitEnvelope = z.strictObject({
+  type: z.enum(gitTypes),
+  timestamp: z.iso.datetime(),
+  data: eventData,
+});
+const changeEnvelope = z.strictObject({
+  type: z.enum(changeTypes),
+  timestamp: z.iso.datetime(),
+  data: eventData.extend({ change: changeIdentity }),
+});
+export const hookEvent = z.discriminatedUnion("type", [
+  gitEnvelope,
+  changeEnvelope,
+]);
+export type HookEvent = z.infer<typeof hookEvent>;
+export type HookEventType = HookEvent["type"];
+/** The precise declared event schema comes from the same envelope owner. */
+export function hookEventFor(type: HookEventType) {
+  return type.startsWith("change.")
+    ? changeEnvelope.extend({ type: z.literal(type) })
+    : gitEnvelope.extend({ type: z.literal(type) });
+}
+
+const eventTypes = {
+  push: "git.push",
+  fork: "git.fork",
+  merge: "change.merged",
+  "merge.conflict": "change.conflicted",
+  "repo.created": "repo.created",
+  "change.opened": "change.opened",
+  "change.updated": "change.updated",
+  "change.approved": "change.approved",
+  "change.checks_requested": "change.checks_requested",
+  "change.checked": "change.checked",
+  "change.closed": "change.closed",
+} as const satisfies Record<Activity["type"], HookEventType>;
+/** Build stable envelopes from committed activity; Change links identify the source repo. */
+export function activityEnvelope(
+  stored: Activity,
+  repository: HookEvent["data"]["repository"],
+): HookEvent {
+  const identity = "change" in stored.data ? stored.data.change : null;
+  const payload = {
+    type: eventTypes[stored.type],
+    timestamp: new Date(stored.at).toISOString(),
+    data: {
+      spec: hookSpec,
+      eventId: `evt_${String(stored.id)}`,
+      repository,
+      actor: stored.actor,
+      activity: stored,
+    },
+  };
+  if (identity === null) return hookEvent.parse(payload);
+  return hookEvent.parse({
+    ...payload,
+    data: { ...payload.data, change: identity },
+  });
+}
+
+const MAX_SKEW_SECONDS = 300;
+
+const encoder = new TextEncoder();
+
+async function hmac(secret: string, message: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(message),
+  );
+  return [...new Uint8Array(signature)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function secretBytes(secret: string): Uint8Array<ArrayBuffer> {
+  if (!secret.startsWith("whsec_")) return encoder.encode(secret);
+  try {
+    return Uint8Array.from(atob(secret.slice(6)), (char) => char.charCodeAt(0));
+  } catch {
+    return encoder.encode(secret);
+  }
+}
+
+/**
+ * The Standard Webhooks signature header value (`v1,<base64>`): HMAC-SHA256
+ * of "id.timestamp.body", keyed by the decoded `whsec_` secret.
+ */
+export async function signStandardWebhook(
+  secret: string,
+  id: string,
+  timestamp: number,
+  body: string,
+): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    secretBytes(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(`${id}.${String(timestamp)}.${body}`),
+  );
+  return `v1,${btoa(String.fromCharCode(...new Uint8Array(signature)))}`;
+}
+
+/** The Bonsai-Signature header value for a body sent at `timestamp` (seconds). */
+export async function signHook(
+  secret: string,
+  body: string,
+  timestamp: number,
+): Promise<string> {
+  return `t=${String(timestamp)},v1=${await hmac(secret, `${String(timestamp)}.${body}`)}`;
+}
+
+function constantTimeEqual(left: string, right: string): boolean {
+  if (left.length !== right.length) return false;
+  let difference = 0;
+  for (let index = 0; index < left.length; index += 1)
+    difference |= left.charCodeAt(index) ^ right.charCodeAt(index);
+  return difference === 0;
+}
+
+const signatureParts = /^t=(\d+),v1=([0-9a-f]{64})$/u;
+
+export type HookVerification =
+  | Readonly<{ ok: true; event: HookEvent }>
+  | Readonly<{ ok: false; reason: "signature" | "stale" | "shape" }>;
+
+/** Verify a delivery's signature and freshness, then parse its body. */
+export async function verifyHook(
+  secret: string,
+  body: string,
+  header: string | null,
+  now = Math.floor(Date.now() / 1000),
+): Promise<HookVerification> {
+  const match = signatureParts.exec(header ?? "");
+  if (!match) return { ok: false, reason: "signature" };
+  const [, stamp = "", digest = ""] = match;
+  const timestamp = Number.parseInt(stamp, 10);
+  if (Math.abs(now - timestamp) > MAX_SKEW_SECONDS)
+    return { ok: false, reason: "stale" };
+  const expected = await hmac(secret, `${stamp}.${body}`);
+  if (!constantTimeEqual(expected, digest))
+    return { ok: false, reason: "signature" };
+  let json: unknown;
+  try {
+    json = JSON.parse(body);
+  } catch {
+    return { ok: false, reason: "shape" };
+  }
+  const parsed = hookEvent.safeParse(json);
+  return parsed.success
+    ? { ok: true, event: parsed.data }
+    : { ok: false, reason: "shape" };
+}

package/shared/insights.ts

@@ -0,0 +1,90 @@
+import * as z from "zod";
+
+export const tileId = z.enum([
+  "contributors",
+  "actors",
+  "ages",
+  "churn",
+  "calendar",
+  "network",
+  "live",
+  "changes",
+  "next",
+  "readme",
+]);
+export type TileId = z.infer<typeof tileId>;
+export const tileTitles = {
+  contributors: "Contributors",
+  actors: "Agents & people",
+  ages: "Code age",
+  churn: "File churn",
+  calendar: "Contribution calendar",
+  network: "Network",
+  live: "Live",
+  changes: "Changes",
+  next: "Next up",
+  readme: "README",
+} satisfies Record<TileId, string>;
+const placement = z.strictObject({
+  id: tileId,
+  col: z.int().min(0).max(3),
+  row: z.int().min(0).max(48),
+  w: z.int().min(1).max(4),
+  h: z.int().min(1).max(4),
+});
+export const insightLayout = z.strictObject({
+  view: z.literal("overview"),
+  placements: z
+    .array(placement)
+    .max(10)
+    .refine(
+      (tiles) => new Set(tiles.map((tile) => tile.id)).size === tiles.length,
+      "Each tile appears once",
+    ),
+});
+export type InsightLayout = z.infer<typeof insightLayout>;
+export const defaultLayout: InsightLayout = {
+  view: "overview",
+  placements: [
+    { id: "network", col: 0, row: 0, w: 3, h: 2 },
+    { id: "live", col: 3, row: 0, w: 1, h: 2 },
+    { id: "changes", col: 0, row: 2, w: 2, h: 1 },
+    { id: "actors", col: 2, row: 2, w: 1, h: 1 },
+    { id: "next", col: 3, row: 2, w: 1, h: 1 },
+    { id: "contributors", col: 0, row: 3, w: 2, h: 1 },
+    { id: "readme", col: 2, row: 3, w: 2, h: 1 },
+    { id: "calendar", col: 0, row: 4, w: 4, h: 1 },
+  ],
+};
+export const savedLayout = z.strictObject({ tiles: insightLayout.nullable() });
+
+export const ageBandLabels = [
+  "Under a week",
+  "1–4 weeks",
+  "1–3 months",
+  "Over 3 months",
+  "Before sample / unknown",
+] as const;
+
+export const codeInsights = z.strictObject({
+  head: z.string().nullable(),
+  commits: z.int().nonnegative(),
+  /** First-parent history and a bounded sample of current text files. */
+  files: z.array(
+    z.strictObject({
+      path: z.string(),
+      lines: z.int().nonnegative(),
+      changes: z.int().nonnegative(),
+    }),
+  ),
+  /** Oldest-first first-parent snapshots, then today; current sampled paths only. */
+  ageHistory: z.array(
+    z.strictObject({
+      at: z.number(),
+      lines: z.array(z.int().nonnegative()).length(ageBandLabels.length),
+    }),
+  ),
+  omittedFiles: z.int().nonnegative(),
+  partial: z.boolean(),
+});
+export type CodeInsights = z.infer<typeof codeInsights>;