@opum-ai/lore 0.1.0 → 0.2.0

package/src/scripts/upstream-backlog-watch.ts

@@ -1,288 +0,0 @@
-#!/usr/bin/env bun
-/**
- * upstream-backlog-watch.ts — LORE-254.
- *
- * Repo-maintenance script, **not** part of the `lore` CLI surface (no `--json` envelope, no
- * exit-code contract, not reachable through `lore <command>` at all). It is invoked directly by
- * `.github/workflows/upstream-backlog-watch.yml` on a schedule.
- *
- * Why this exists: MrLesk/Backlog.md merged commit 22a091b (PR #790 / BACK-545, stable `--json`
- * output on `task list`/`task view`/`search`) to `main` on 2026-07-16, but has not yet **tagged**
- * a release that contains it (the latest tag as of writing, v1.48.0, predates the merge). LORE-253
- * — the adapter migration that unblocks lore's own first npm release — is blocked on that tag
- * existing, and nothing upstream notifies lore when it ships. This script polls MrLesk/Backlog.md's
- * Releases API and, the first time it finds a release whose commit history actually **contains**
- * 22a091b (not merely a release numbered higher than v1.48.0 — a newer tag could still predate the
- * merge), opens a tracking issue in THIS repo labeled `upstream-watch` so the maintainer can pick up
- * LORE-253. See `docs/runbooks/upstream-backlog-md-json-tag-watch.md` for the full runbook (where the signal
- * lands, who acts on it) and `docs/runbooks/backlog-json-patch.md` §8.1 for what LORE-253 does once
- * unblocked.
- *
- * Kept stateless by design: rather than persisting "already scanned up to tag X", it re-derives
- * "already surfaced" by asking GitHub whether a tracking issue carrying TRACKING_LABEL already
- * exists (open OR closed) before doing any upstream work. Once a qualifying release is found and
- * reported once, every later upstream release also contains 22a091b in its history forever after
- * (commits don't leave history) — so the existing-issue check is what stops this from re-notifying
- * on every future upstream release, not a per-tag dedupe.
- */
-
-const UPSTREAM_REPO = "MrLesk/Backlog.md";
-const TARGET_COMMIT = "22a091b570d44c4f302ca47e7fd36fa28ad8bcb0";
-const TARGET_COMMIT_PR_URL = "https://github.com/MrLesk/Backlog.md/pull/790";
-// PR #790 merged 2026-07-16 (docs/runbooks/backlog-json-patch.md §8.1) -- any release published
-// strictly before this cannot possibly contain the commit, so it bounds the scan to real
-// candidates instead of walking MrLesk/Backlog.md's entire release history on every run.
-const TARGET_COMMIT_MERGED_AT = "2026-07-16T00:00:00Z";
-export const TRACKING_LABEL = "upstream-watch";
-const TRACKING_LABEL_COLOR = "6f42c1";
-const TRACKING_LABEL_DESCRIPTION = "MrLesk/Backlog.md shipped a --json-capable tag (LORE-254); see the linked issue.";
-
-export interface ReleaseInfo {
-  tagName: string;
-  publishedAt: string;
-}
-
-export interface QualifyingRelease {
-  tagName: string;
-  sha: string;
-}
-
-export type WatchResult =
-  | { action: "already-surfaced" }
-  | { action: "no-match" }
-  | { action: "opened"; tagName: string; issueUrl: string };
-
-/**
- * Keep only releases that could possibly contain {@link TARGET_COMMIT}: everything published
- * at/after {@link TARGET_COMMIT_MERGED_AT}. GitHub's Releases API list order is `created_at` desc
- * (not guaranteed `published_at` order — a release drafted before the cutoff but published after
- * it can sort below an older-published release), so this is a plain filter rather than a
- * newest-first prefix-take: the list is already capped at `per_page=100` in memory, so a full
- * scan costs nothing extra and doesn't risk silently dropping a qualifying release.
- */
-export function candidateReleases(releases: ReleaseInfo[], cutoffIso: string = TARGET_COMMIT_MERGED_AT): ReleaseInfo[] {
-  return releases.filter((release) => release.publishedAt >= cutoffIso);
-}
-
-/**
- * GitHub's compare API (`/compare/{base}...{head}`) `status` field: `"identical"` or `"ahead"`
- * (head ahead of base) both mean `base` is an ancestor of (or equal to) `head` — i.e. the tag's
- * history actually contains the commit. This is what distinguishes a real `--json`-capable tag
- * from one that is merely numbered newer (`"behind"` / `"diverged"`).
- */
-export function isAncestorCompareStatus(status: string): boolean {
-  return status === "identical" || status === "ahead";
-}
-
-/** The tracking issue body for a release confirmed to contain {@link TARGET_COMMIT}. */
-export function renderIssueBody(release: QualifyingRelease): string {
-  const releaseUrl = `https://github.com/${UPSTREAM_REPO}/releases/tag/${release.tagName}`;
-  return [
-    `MrLesk/Backlog.md tag [\`${release.tagName}\`](${releaseUrl}) (commit \`${release.sha}\`) is the first`,
-    `tagged release whose history contains commit \`${TARGET_COMMIT}\``,
-    `([PR #790](${TARGET_COMMIT_PR_URL}) / BACK-545 — stable \`--json\` output on \`task list\`/\`task view\`/\`search\`),`,
-    "confirmed via the GitHub compare API (not merely a tag numbered newer than v1.48.0).",
-    "",
-    'This is the external event **LORE-253** ("Migrate backlog adapter to the released --json',
-    "Backlog.md...\") and `docs/runbooks/release-publishing.md`'s release Prerequisites were both",
-    "waiting on — it is also the last gate on lore's own first npm release.",
-    "",
-    "**Next step:** `backlog task view LORE-253 --plain`, then follow",
-    "`docs/runbooks/backlog-json-patch.md` §8.1 step 4 to point `src/adapters/backlog.ts` at the",
-    "published package instead of the interim pinned-commit build.",
-    "",
-    "Detected by `.github/workflows/upstream-backlog-watch.yml` (LORE-254); see",
-    "`docs/runbooks/upstream-backlog-md-json-tag-watch.md` for how this signal works and who acts on it.",
-  ].join("\n");
-}
-
-// ── I/O boundary ─────────────────────────────────────────────────────────────
-// Everything below talks to the GitHub REST API. Every function threads through an injectable
-// `fetcher` (defaulting to the real global `fetch` only at the `watchOnce` boundary) so the whole
-// orchestration can be exercised in tests against a stub instead of the network.
-
-type Fetcher = typeof fetch;
-
-class GithubApiError extends Error {
-  constructor(
-    method: string,
-    url: string,
-    readonly status: number,
-    body: string,
-  ) {
-    super(`GitHub API ${method} ${url} -> ${status}: ${body}`);
-  }
-}
-
-async function githubApi<T>(fetcher: Fetcher, token: string, method: string, path: string, body?: unknown): Promise<T> {
-  const url = path.startsWith("http") ? path : `https://api.github.com${path}`;
-  const response = await fetcher(url, {
-    method,
-    headers: {
-      Accept: "application/vnd.github+json",
-      Authorization: `Bearer ${token}`,
-      "X-GitHub-Api-Version": "2022-11-28",
-      "User-Agent": "lore-upstream-backlog-watch (LORE-254)",
-      ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
-    },
-    body: body !== undefined ? JSON.stringify(body) : undefined,
-  });
-  if (!response.ok) {
-    throw new GithubApiError(method, url, response.status, await response.text());
-  }
-  return (await response.json()) as T;
-}
-
-interface UpstreamReleaseApiRow {
-  tag_name: string;
-  published_at: string | null;
-  draft: boolean;
-}
-
-async function listUpstreamReleases(fetcher: Fetcher, token: string): Promise<ReleaseInfo[]> {
-  const rows = await githubApi<UpstreamReleaseApiRow[]>(
-    fetcher,
-    token,
-    "GET",
-    `/repos/${UPSTREAM_REPO}/releases?per_page=100`,
-  );
-  return rows
-    .filter((row): row is UpstreamReleaseApiRow & { published_at: string } => !row.draft && row.published_at !== null)
-    .map((row) => ({ tagName: row.tag_name, publishedAt: row.published_at }));
-}
-
-async function resolveTagSha(fetcher: Fetcher, token: string, tag: string): Promise<string> {
-  const commit = await githubApi<{ sha: string }>(fetcher, token, "GET", `/repos/${UPSTREAM_REPO}/commits/${tag}`);
-  return commit.sha;
-}
-
-async function compareAgainstTarget(fetcher: Fetcher, token: string, sha: string): Promise<string> {
-  const comparison = await githubApi<{ status: string }>(
-    fetcher,
-    token,
-    "GET",
-    `/repos/${UPSTREAM_REPO}/compare/${TARGET_COMMIT}...${sha}`,
-  );
-  return comparison.status;
-}
-
-/**
- * The first candidate release, in GitHub's Releases API list order (`created_at` desc — not
- * necessarily `published_at` order), whose history contains {@link TARGET_COMMIT}, if any.
- */
-async function findQualifyingRelease(fetcher: Fetcher, token: string): Promise<QualifyingRelease | null> {
-  const releases = await listUpstreamReleases(fetcher, token);
-  for (const candidate of candidateReleases(releases)) {
-    const sha = await resolveTagSha(fetcher, token, candidate.tagName);
-    const status = await compareAgainstTarget(fetcher, token, sha);
-    if (isAncestorCompareStatus(status)) {
-      return { tagName: candidate.tagName, sha };
-    }
-  }
-  return null;
-}
-
-interface OwnIssueApiRow {
-  pull_request?: unknown;
-}
-
-async function trackingIssueAlreadyExists(fetcher: Fetcher, token: string, repoSlug: string): Promise<boolean> {
-  const rows = await githubApi<OwnIssueApiRow[]>(
-    fetcher,
-    token,
-    "GET",
-    `/repos/${repoSlug}/issues?labels=${TRACKING_LABEL}&state=all&per_page=100`,
-  );
-  // The issues endpoint also returns pull requests carrying the label; a real hit must be an
-  // actual issue.
-  return rows.some((row) => !row.pull_request);
-}
-
-async function ensureTrackingLabelExists(fetcher: Fetcher, token: string, repoSlug: string): Promise<void> {
-  try {
-    await githubApi(fetcher, token, "POST", `/repos/${repoSlug}/labels`, {
-      name: TRACKING_LABEL,
-      color: TRACKING_LABEL_COLOR,
-      description: TRACKING_LABEL_DESCRIPTION,
-    });
-  } catch (error) {
-    // 422 = the label already exists; anything else is a real failure.
-    if (!(error instanceof GithubApiError && error.status === 422)) {
-      throw error;
-    }
-  }
-}
-
-interface CreatedIssueApiRow {
-  html_url: string;
-}
-
-async function openTrackingIssue(
-  fetcher: Fetcher,
-  token: string,
-  repoSlug: string,
-  release: QualifyingRelease,
-): Promise<string> {
-  const created = await githubApi<CreatedIssueApiRow>(fetcher, token, "POST", `/repos/${repoSlug}/issues`, {
-    title: `Upstream Backlog.md ${release.tagName} is --json-capable — LORE-253 is unblocked`,
-    body: renderIssueBody(release),
-    labels: [TRACKING_LABEL],
-  });
-  return created.html_url;
-}
-
-/**
- * Run one check: skip entirely if already surfaced, otherwise probe upstream and open the
- * tracking issue on a hit. `fetcher` defaults to the real global `fetch` — tests pass a stub.
- */
-export async function watchOnce(
-  env: { repoSlug: string; token: string },
-  fetcher: Fetcher = fetch,
-): Promise<WatchResult> {
-  if (await trackingIssueAlreadyExists(fetcher, env.token, env.repoSlug)) {
-    return { action: "already-surfaced" };
-  }
-  const found = await findQualifyingRelease(fetcher, env.token);
-  if (!found) {
-    return { action: "no-match" };
-  }
-  await ensureTrackingLabelExists(fetcher, env.token, env.repoSlug);
-  const issueUrl = await openTrackingIssue(fetcher, env.token, env.repoSlug, found);
-  return { action: "opened", tagName: found.tagName, issueUrl };
-}
-
-async function main(): Promise<number> {
-  const repoSlug = process.env.GITHUB_REPOSITORY;
-  const token = process.env.GITHUB_TOKEN;
-  if (!repoSlug || !token) {
-    console.error("GITHUB_REPOSITORY and GITHUB_TOKEN must both be set (this script runs under GitHub Actions).");
-    return 1;
-  }
-  const result = await watchOnce({ repoSlug, token });
-  switch (result.action) {
-    case "already-surfaced":
-      console.log(`A "${TRACKING_LABEL}" tracking issue already exists in ${repoSlug}; nothing to do.`);
-      break;
-    case "no-match":
-      console.log(`No MrLesk/Backlog.md release yet contains ${TARGET_COMMIT}.`);
-      break;
-    case "opened":
-      console.log(`Opened ${result.issueUrl} for upstream tag ${result.tagName}.`);
-      break;
-  }
-  return 0;
-}
-
-// Same shape as cli.ts's own entrypoint guard (LORE-70): set `process.exitCode` rather than call
-// `process.exit()` so pending stdout/stderr writes flush before the process actually ends.
-if (import.meta.main) {
-  Promise.resolve(main()).then(
-    (code) => {
-      process.exitCode = code;
-    },
-    (error) => {
-      console.error(error);
-      process.exitCode = 1;
-    },
-  );
-}