Admin server-side backfill (My Work sync button) + admin-gated update_plan

plugins/canopy/skills/update-plan/SKILL.md

@@ -69,6 +69,9 @@ Once confirmed, make **exactly one** call:
 
 ## Hard rules (invariants)
 
+- **Server-gated to `ADMIN_LOGINS`.** `update_plan` is only registered for admin principals — a
+  non-admin bearer doesn't have the tool at all (absent from `tools/list`, tool-not-found if called).
+  This skill's own instructions are a second layer, not the enforcement boundary.
 - **Explicit only.** Never fire without a direct admin ask.
 - **Read before write, every time** — step 1 is not optional, even for a small edit.
 - **Confirm the diff before writing** — no silent writes.

src/auth/principal.ts

@@ -9,6 +9,16 @@ export interface Principal {
 
 export type AppEnv = { Bindings: Env; Variables: { principal: Principal } };
 
+/**
+ * Is this login an admin? ADMIN_LOGINS is a comma-separated allowlist of GitHub
+ * logins permitted to run admin actions (e.g. the server-side backfill). An
+ * absent/empty var means nobody is an admin — fails closed.
+ */
+export function isAdmin(env: Env, login: string): boolean {
+  const allow = (env.ADMIN_LOGINS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  return allow.includes(login);
+}
+
 // The only routes reachable without a session. Everything else is gated.
 const PUBLIC_PATHS = new Set(["/auth/login", "/auth/callback"]);
 

src/auth/routes.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { setCookie, getCookie, deleteCookie } from "hono/cookie";
 import type { AppEnv } from "./principal";
+import { isAdmin } from "./principal";
 import { pkce, randomToken, hmacSeal, hmacUnseal } from "./crypto";
 import { buildAuthorizeUrl, exchangeCode, getUser, isActiveOrgMember } from "./github";
 import { createSession, setSessionCookie, readSessionCookie, deleteSession, clearSessionCookie } from "./session";
@@ -73,7 +74,7 @@ authApp.get("/callback", async (c) => {
 authApp.get("/me", async (c) => {
   const login = c.get("principal").login;
   const row = await first<{ name: string | null; avatar_url: string | null }>(c.env.DB, `SELECT name, avatar_url FROM users WHERE github_login = ?`, login);
-  return c.json({ login, name: row?.name ?? null, avatar_url: row?.avatar_url ?? null, org: SAPLING_ORG });
+  return c.json({ login, name: row?.name ?? null, avatar_url: row?.avatar_url ?? null, org: SAPLING_ORG, admin: isAdmin(c.env, login) });
 });
 
 // GATED (by sessionGate in src/routes.ts): revoke this session.

src/env.ts

@@ -9,4 +9,5 @@ export interface Env {
   DEV_LOGIN?: string;     // LOCAL DEV ONLY (set in .dev.vars): bypass OAuth, act as this seeded user. Never set in prod.
   AI?: Ai;                // Workers AI binding: capture-time completed-PR summaries only, never at render.
   GITHUB_SERVICE_TOKEN?: string; // app-level token for the scheduled progress-cache recompute backstop; absent → scheduled() no-ops
+  ADMIN_LOGINS?: string;  // comma-separated GitHub logins allowed to run admin actions (e.g. the server-side backfill)
 }

src/mcp.ts

@@ -3,6 +3,7 @@ import { createMcpHandler } from "agents/mcp";
 import { z } from "zod";
 import type { Env } from "./env";
 import type { Principal } from "./auth/principal";
+import { isAdmin } from "./auth/principal";
 import { get_doc, list_docs, get_feed, query } from "./tools/reads";
 import { getMyWork, list_events } from "./tools/mywork";
 import { ingestFeedEntry, ingestDocProposal, consume } from "./consumer";
@@ -145,23 +146,29 @@ export function buildCanopyMcpServer(env: Env, principal: Principal): McpServer
     async (payload) => runTool(() => consume(env.DB, IngestPayload.parse(payload), principal)),
   );
 
-  server.tool(
-    "update_plan",
-    "ADMIN plan write: replace the roadmap narrative and create/update milestones (including status 'done') in one direct, non-destructively versioned write — same authored-write class as promote, NOT the ingestion gate. Milestones not listed are untouched. Use via the update-plan skill.",
-    {
-      narrative: z.string(),
-      milestones: z.array(z.object({
-        id: z.number().int().optional(),
-        title: z.string(),
-        description: z.string().nullable().optional(),
-        phase: z.string().nullable().optional(),
-        target_date: z.string(),
-        status: z.enum(["upcoming", "in_progress", "done"]),
-        github_ref: z.union([z.number(), z.array(z.number())]).nullable().optional(),
-      })).default([]),
-    },
-    async (input) => runTool(() => write_plan(env.DB, input as PlanWrite, principal.login))
-  );
+  // ADMIN-only: the plan write surface — non-admin principals don't even see the tool
+  // (conditional registration means it's absent from tools/list and calling it by
+  // name errors tool-not-found, since a fresh server is built per request with the
+  // principal already in scope).
+  if (isAdmin(env, principal.login)) {
+    server.tool(
+      "update_plan",
+      "ADMIN plan write: replace the roadmap narrative and create/update milestones (including status 'done') in one direct, non-destructively versioned write — same authored-write class as promote, NOT the ingestion gate. Milestones not listed are untouched. Use via the update-plan skill.",
+      {
+        narrative: z.string(),
+        milestones: z.array(z.object({
+          id: z.number().int().optional(),
+          title: z.string(),
+          description: z.string().nullable().optional(),
+          phase: z.string().nullable().optional(),
+          target_date: z.string(),
+          status: z.enum(["upcoming", "in_progress", "done"]),
+          github_ref: z.union([z.number(), z.array(z.number())]).nullable().optional(),
+        })).default([]),
+      },
+      async (input) => runTool(() => write_plan(env.DB, input as PlanWrite, principal.login))
+    );
+  }
 
   return server;
 }

src/routes.ts

@@ -1,9 +1,10 @@
 import { Hono } from "hono";
 import { IngestPayload } from "@shared/contract";
 import type { AppEnv } from "./auth/principal";
-import { sessionGate } from "./auth/principal";
+import { sessionGate, isAdmin } from "./auth/principal";
 import { authApp } from "./auth/routes";
 import { consume } from "./consumer";
+import { runBackfill } from "./tools/backfill";
 import { get_doc, list_docs, get_feed, query, list_needs_triage, list_adrs, list_milestone_proposals, list_proposals } from "./tools/reads";
 import { promote_doc, ratify_adr, promote_milestone_proposal, reject_milestone_proposal, complete_milestone, reject_doc_version, reject_adr, resolve_triage, assign_triage, type AssignType } from "./tools/writes";
 import { get_plan } from "./tools/plan";
@@ -219,6 +220,18 @@ app.post("/milestone-proposals/:id/reject", async (c) => {
   }
 });
 
+// ADMIN action (session-gated + admin-gated): server-side GitHub backfill.
+// A computed/authored direct writer in the promote class — humans (admins)
+// trigger it — but every captured event still funnels through the ingestEvent
+// gate fn. Non-admins get 403; a missing service token/repo → 503 with the error.
+app.post("/admin/backfill", async (c) => {
+  const login = c.get("principal").login;
+  if (!isAdmin(c.env, login)) return c.json({ error: "admin only" }, 403);
+  const res = await runBackfill(c.env, login);
+  if (!res.ok) return c.json({ error: res.error }, 503);
+  return c.json(res);
+});
+
 // Human confirmation (session-gated): flip a live milestone to 'done'.
 app.post("/milestones/:id/complete", async (c) => {
   const id = Number(c.req.param("id"));

src/tools/backfill.ts

@@ -0,0 +1,220 @@
+import type { Env } from "../env";
+import { nowIso } from "../db";
+import { ingestEvent } from "../consumer";
+import { eventsFromDelivery } from "../webhook";
+import { type Summarizer, workersAiSummarizer, storePrSummary } from "./summarize";
+import { applyEventProgress } from "./progress";
+
+// Admin-triggered server-side GitHub backfill. Unlike scripts/backfill-events.mjs
+// (which signs synthetic webhook deliveries with the webhook secret), this runs
+// INSIDE the Worker with GITHUB_SERVICE_TOKEN — the same token the scheduled()
+// progress recompute uses — so it fetches GitHub REST directly, no webhook secret.
+//
+// It reconstructs the SAME deliveries the webhook would have received, reuses the
+// PURE eventsFromDelivery() derivation (never duplicated here), post-maps each
+// event's provenance to "backfill", and writes through the ONE gate fn ingestEvent
+// — but with the ADMIN principal as the writer (an authenticated identity), not
+// the fixed "github-webhook" string. Downstream projections (PR summaries, issue
+// progress) mirror handleGithubWebhook, hung off newly-written events only.
+
+const GH_API = "application/vnd.github+json";
+const USER_AGENT = "canopy";
+const DAYS_BACK = 14;
+
+export interface BackfillResult {
+  ok: boolean;
+  error?: string;
+  captured: number;
+  unchanged: number;
+  prs: number;
+  issues: number;
+}
+
+// Minimal typed views over the GitHub REST list items — only the fields the
+// delivery synthesizers below read are modeled; everything else is ignored.
+interface GhUserLite {
+  login: string;
+}
+interface GhMilestoneLite {
+  number: number;
+  open_issues?: number;
+  closed_issues?: number;
+}
+interface GhPrListItem {
+  number: number;
+  title: string;
+  body: string | null;
+  html_url: string;
+  merged_at: string | null;
+  closed_at: string | null;
+  updated_at: string;
+  user: GhUserLite;
+  milestone?: GhMilestoneLite | null;
+}
+interface GhIssueListItem {
+  number: number;
+  title: string;
+  html_url: string;
+  state: string;
+  updated_at: string;
+  user: GhUserLite;
+  assignees?: GhUserLite[];
+  assignee?: GhUserLite | null;
+  labels?: (string | { name: string })[];
+  milestone?: GhMilestoneLite | null;
+  pull_request?: unknown; // present only when the "issue" is really a PR
+}
+
+// The `rel="next"` URL from a GitHub Link header, or null when there is no next page.
+function nextLink(res: Response): string | null {
+  const link = res.headers.get("link");
+  const next = link?.split(",").find((part) => part.includes('rel="next"'));
+  return next ? (next.match(/<([^>]+)>/)?.[1] ?? null) : null;
+}
+
+// Synthesize the delivery bodies eventsFromDelivery reads — SAME raw slice shapes
+// as scripts/backfill-events.mjs (test/fixtures/*.json). PR list items carry no
+// `merged` boolean (that's single-PR-fetch only), so derive it from merged_at.
+function prClosedDelivery(pr: GhPrListItem) {
+  return {
+    action: "closed",
+    number: pr.number,
+    pull_request: {
+      number: pr.number,
+      title: pr.title,
+      body: pr.body,
+      html_url: pr.html_url,
+      merged: pr.merged_at != null,
+      merged_at: pr.merged_at,
+      closed_at: pr.closed_at,
+      user: { login: pr.user.login },
+      milestone: pr.milestone
+        ? { number: pr.milestone.number, open_issues: pr.milestone.open_issues, closed_issues: pr.milestone.closed_issues }
+        : null,
+    },
+  };
+}
+
+function issueDelivery(issue: GhIssueListItem) {
+  const assignee = issue.assignees?.[0] ?? issue.assignee ?? null;
+  const action = assignee ? "assigned" : "opened";
+  return {
+    action,
+    ...(assignee ? { assignee: { login: assignee.login } } : {}),
+    issue: {
+      number: issue.number,
+      title: issue.title,
+      html_url: issue.html_url,
+      state: issue.state,
+      updated_at: issue.updated_at,
+      user: { login: issue.user.login },
+      assignees: (issue.assignees ?? []).map((a) => ({ login: a.login })),
+      labels: issue.labels ?? [],
+      milestone: issue.milestone
+        ? { number: issue.milestone.number, open_issues: issue.milestone.open_issues, closed_issues: issue.milestone.closed_issues }
+        : null,
+    },
+  };
+}
+
+export async function runBackfill(
+  env: Env,
+  principalLogin: string,
+  opts?: { fetchImpl?: typeof fetch; summarizer?: Summarizer | null; now?: string }
+): Promise<BackfillResult> {
+  const token = env.GITHUB_SERVICE_TOKEN;
+  const repo = env.GITHUB_REPO;
+  if (!token || !repo) {
+    return { ok: false, error: "service token or repo not configured", captured: 0, unchanged: 0, prs: 0, issues: 0 };
+  }
+
+  const doFetch = opts?.fetchImpl ?? fetch;
+  const summarizer = opts?.summarizer ?? (env.AI ? workersAiSummarizer(env.AI) : null);
+  const headers = {
+    authorization: `Bearer ${token}`,
+    accept: GH_API,
+    "user-agent": USER_AGENT,
+    "x-github-api-version": "2022-11-28",
+  };
+  const cutoffMs = new Date(opts?.now ?? nowIso()).getTime() - DAYS_BACK * 24 * 60 * 60 * 1000;
+
+  // (a) Closed PRs updated in the last 14 days. Sorted updated-desc, so we stop
+  //     paginating at the first item whose updated_at predates the cutoff.
+  const prList: GhPrListItem[] = [];
+  {
+    let url: string | null = `https://api.github.com/repos/${repo}/pulls?state=closed&sort=updated&direction=desc&per_page=100`;
+    let done = false;
+    while (url && !done) {
+      const res: Response = await doFetch(url, { headers });
+      if (!res.ok) break;
+      const page = (await res.json()) as GhPrListItem[];
+      for (const pr of page) {
+        if (pr.updated_at && new Date(pr.updated_at).getTime() < cutoffMs) {
+          done = true;
+          break;
+        }
+        prList.push(pr);
+      }
+      url = done ? null : nextLink(res);
+    }
+  }
+
+  // (b) All open issues, paginated. The issues endpoint also returns PRs — those
+  //     carry a `pull_request` field and are not our surface, so skip them.
+  const issueList: GhIssueListItem[] = [];
+  {
+    let url: string | null = `https://api.github.com/repos/${repo}/issues?state=open&per_page=100`;
+    while (url) {
+      const res: Response = await doFetch(url, { headers });
+      if (!res.ok) break;
+      const page = (await res.json()) as GhIssueListItem[];
+      for (const issue of page) {
+        if (issue.pull_request) continue;
+        issueList.push(issue);
+      }
+      url = nextLink(res);
+    }
+  }
+
+  let captured = 0;
+  let unchanged = 0;
+
+  for (const pr of prList) {
+    const payload = prClosedDelivery(pr);
+    for (const base of eventsFromDelivery("pull_request", payload)) {
+      const ev = { ...base, provenance: "backfill" as const };
+      const res = await ingestEvent(env.DB, ev, principalLogin);
+      if (res.outcome === "written") {
+        captured++;
+        // Mirror handleGithubWebhook's summary seam: parse THIS PR's own raw and
+        // store a capture-time summary (storePrSummary never throws).
+        const parsed = JSON.parse(ev.raw) as { pr: { number: number; title: string; body: string | null } };
+        await storePrSummary(env.DB, summarizer, {
+          semantic_key: ev.semantic_key,
+          pr_number: parsed.pr.number,
+          title: parsed.pr.title,
+          body: parsed.pr.body ?? "",
+        });
+      } else {
+        unchanged++;
+      }
+    }
+  }
+
+  for (const issue of issueList) {
+    const payload = issueDelivery(issue);
+    for (const base of eventsFromDelivery("issues", payload)) {
+      const ev = { ...base, provenance: "backfill" as const };
+      const res = await ingestEvent(env.DB, ev, principalLogin);
+      if (res.outcome === "written") {
+        captured++;
+        // Mirror handleGithubWebhook's progress seam for newly-written issues.
+        await applyEventProgress(env.DB, payload);
+      } else {
+        unchanged++;
+      }
+    }
+  }
+
+  return { ok: true, captured, unchanged, prs: prList.length, issues: issueList.length };
+}