@workit-dev/core 0.0.1 → 1.0.0

package/src/forge/types.ts

@@ -0,0 +1,242 @@
+// Forge-neutral shapes for the GitHub and GitLab adapters (design §2.0, S10).
+// Plain TS: the CLI verbs load this on their path.
+import type { ForgeKind } from "../git/rev";
+
+export type { ForgeKind };
+
+export type ForgeErrorCode =
+  | "unavailable"
+  | "not_found"
+  | "failed"
+  | "blocked"
+  | "busy"
+  | "invalid_input";
+
+export type ForgeResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; code: ForgeErrorCode; error: string; unblock?: string };
+
+export const success = <T>(data: T): ForgeResult<T> => ({ ok: true, data });
+
+export const failure = <T = never>(
+  code: ForgeErrorCode,
+  error: string,
+  unblock?: string,
+): ForgeResult<T> => ({ ok: false, code, error, ...(unblock ? { unblock } : {}) });
+
+export type PrState = "open" | "closed" | "merged";
+
+export type PrRef = {
+  number: number;
+  url: string;
+  state: PrState;
+  headBranch: string;
+  headSha: string | null;
+};
+
+/** How a branch-name lookup proves a PR is ours (M5): head owner/project or head sha. */
+export type PrMatch = {
+  /** GitHub: the head repository owner (the push repo's owner). */
+  owner: string | null;
+  /** GitLab: the source project id (the push project). */
+  projectId: number | null;
+  /** A PR whose head is exactly this commit is ours whatever its owner. */
+  sha: string | null;
+  /**
+   * Only a PR into this base: one head may have PRs into several bases (a
+   * git-flow release into main and its back-merge into develop).
+   */
+  base?: string | null;
+};
+
+/** One CI check (GitHub check run / commit status, GitLab job or bridge). */
+export type ForgeCheck = {
+  /** `<workflow> / <job>` on GitHub, `<stage> / <job>` on GitLab, or the status context. */
+  name: string;
+  /** The raw context/job name branch protection refers to. */
+  context: string;
+  state: "failing" | "pending" | "passing" | "skipped";
+  /** The forge's own verdict, lower-cased (failure, timed_out, failed, canceled…). */
+  conclusion: string | null;
+  url: string | null;
+  /** GitHub workflow run id / GitLab pipeline id. */
+  runId: number | null;
+  /** GitHub Actions job id / GitLab job id; null for external statuses and bridges. */
+  jobId: number | null;
+  /** GitLab: the project that owns the pipeline (forks run elsewhere). */
+  scope: string | null;
+  /** Required by branch protection (GitHub isRequired); null when the forge cannot say. */
+  required: boolean | null;
+};
+
+export type ForgeThread = {
+  id: string;
+  path: string | null;
+  line: number | null;
+  author: string | null;
+  isBot: boolean;
+  outdated: boolean;
+  url: string | null;
+  /** First comment, redacted and cut to 300 chars. Untrusted data. */
+  body: string;
+};
+
+export type ForgePrStatus = {
+  number: number;
+  url: string;
+  state: PrState;
+  draft: boolean;
+  base: string;
+  /** The current tip of the base branch, from the API. */
+  baseSha: string | null;
+  head: { branch: string; sha: string };
+  mergeable: "yes" | "no" | "unknown";
+  conflicts: boolean;
+  /** Branch protection requires the head to be up to date and it is not. */
+  rebaseRequired: boolean;
+  /** approved | changes_requested | review_required | null. */
+  reviewDecision: string | null;
+  /** GitHub mergeStateStatus / GitLab detailed_merge_status, lower-cased. */
+  mergeState: string | null;
+  inMergeQueue: boolean;
+  checks: ForgeCheck[];
+  /**
+   * Contexts branch protection requires (GitHub branch protection +
+   * rulesets); null when they could not be read.
+   */
+  requiredContexts: string[] | null;
+  threads: ForgeThread[];
+  /** True when a list was cut at the page cap (the counts are lower bounds). */
+  truncated: boolean;
+};
+
+/** The checks on the latest commit of a branch (the merge guard reads the base's). */
+export type RefChecks = {
+  /** The commit the checks belong to; null when the forge did not say. */
+  sha: string | null;
+  /** `required` is set from branch protection when `requiredKnown`; else it is null on GitHub. */
+  checks: ForgeCheck[];
+  /** True when the branch's required checks could be read (GitLab gates on the whole pipeline). */
+  requiredKnown: boolean;
+};
+
+export type JobRef = { jobId: number; scope: string | null };
+
+export type RerunTarget =
+  | { kind: "failed_in_run"; runId: number; scope: string | null }
+  | { kind: "job"; jobId: number; scope: string | null };
+
+export type Identity = {
+  login: string | null;
+  expected: string | null;
+  matches: boolean | null;
+  /** Why the login could not be checked (e.g. an app token without /user). */
+  note?: string;
+};
+
+export type MergeMethod = "squash" | "merge" | "rebase";
+
+/** What `workit pr create` asks the forge for (S11). */
+export type CreatePrInput = {
+  /** Source branch in the push (head) repository. */
+  head: string;
+  /** owner/name (GitHub) or group/project (GitLab) of the push repository. */
+  headRepo: string;
+  /** GitLab: the push project id (MRs from a fork are opened from it). */
+  headProjectId: number | null;
+  base: string;
+  title: string;
+  body: string;
+  draft: boolean;
+};
+
+export type MergeOptions = {
+  sha: string;
+  method: MergeMethod;
+  /** Squash only: the commit message the forge writes instead of its default. */
+  squashMessage?: { subject: string; body: string };
+};
+
+export type MergeResult = {
+  /** The merge (or squash/rebase tip) commit the forge reported, when it did. */
+  mergeSha: string | null;
+};
+
+/** The editable fields of a PR/MR (`workit pr ready|edit`). */
+export type PrMeta = {
+  number: number;
+  url: string;
+  state: PrState;
+  draft: boolean;
+  title: string;
+  base: string;
+  headBranch: string;
+  /** The author's login; null when the forge does not say. */
+  author: string | null;
+  /** The head comes from another repository than the PR's; null when unknown. */
+  fork: boolean | null;
+};
+
+/** What `workit pr edit` changes; unset fields are left alone. */
+export type PrEdit = {
+  title?: string;
+  body?: string;
+  base?: string;
+  addLabels: string[];
+  removeLabels: string[];
+  /** Logins; on GitHub `org/team` requests a team. */
+  addReviewers: string[];
+};
+
+/** A GitHub release or GitLab release for a tag. */
+export type ForgeRelease = { tag: string; url: string | null };
+
+/** What `workit release finish` asks the forge for: a release on an existing tag. */
+export type CreateReleaseInput = { tag: string; name: string; body: string };
+
+/** A repository as the forge sees it: id and the repo it was forked from. */
+export type RepoInfo = { id: number | null; parent: string | null };
+
+export interface Forge {
+  kind: ForgeKind;
+  apiHost: string;
+  /** The base repository PRs/MRs live in. */
+  repo: string;
+  identity(expected: string | null): ForgeResult<Identity>;
+  repoInfo(repo: string): ForgeResult<RepoInfo>;
+  findPr(head: string, match: PrMatch): ForgeResult<PrRef | null>;
+  prStatus(n: number): ForgeResult<ForgePrStatus>;
+  /** The checks on the head commit of branch `branch`; empty when CI has not reported for it. */
+  branchChecks(branch: string): ForgeResult<RefChecks>;
+  jobLogTail(job: JobRef, lines: number): ForgeResult<string[]>;
+  rerun(target: RerunTarget): ForgeResult<void>;
+  /** Open a PR/MR; `headSha` is the head the forge reports right after creation. */
+  createPr(input: CreatePrInput): ForgeResult<PrRef>;
+  /**
+   * Merge with the head guard: the forge refuses (`blocked`, head_moved) when
+   * the PR head is no longer `sha`.
+   */
+  merge(n: number, options: MergeOptions): ForgeResult<MergeResult>;
+  /** Retarget a PR/MR to another base branch (S12 stacks). */
+  updateBase(n: number, base: string): ForgeResult<void>;
+  /** Title, draft flag, base and state of one PR/MR. */
+  prMeta(n: number): ForgeResult<PrMeta>;
+  /** Numbers of the open PRs/MRs that target `branch` as their base (stack children). */
+  openPrsInto(branch: string): ForgeResult<number[]>;
+  /** Mark a draft ready (`draft: false`) or convert it back to a draft. */
+  setDraft(n: number, draft: boolean): ForgeResult<void>;
+  editPr(n: number, edit: PrEdit): ForgeResult<void>;
+  /** Reply to a review thread (GitHub review thread id, GitLab discussion id). */
+  replyThread(n: number, thread: string, body: string): ForgeResult<{ url: string | null }>;
+  resolveThread(n: number, thread: string): ForgeResult<void>;
+  /** One review thread of PR `n` read directly: null when it is not on that PR. */
+  threadState(n: number, thread: string): ForgeResult<"open" | "resolved" | null>;
+  /** The release for `tag`, or null when the forge has none. */
+  findRelease(tag: string): ForgeResult<ForgeRelease | null>;
+  /** Publish a release on an existing tag (never creates the tag). */
+  createRelease(input: CreateReleaseInput): ForgeResult<ForgeRelease>;
+  /** Bodies of the first page of comments on issue `n` of the base repository. */
+  issueComments(n: number): ForgeResult<string[]>;
+  /** Comment on issue `n` of the base repository (the PR backlink). */
+  commentIssue(n: number, body: string): ForgeResult<void>;
+}

package/src/forge/verify.ts

@@ -0,0 +1,398 @@
+// `workit verify-delivery` (design §2.1 S11): did the requested endpoint really
+// happen? Each answer is an observation of the remote, never of local state:
+// a local commit does not prove a push, a push does not prove a PR, and a
+// "merged" claim needs the forge to say so.
+//
+//   pushed    the push remote's branch tip equals the expected SHA (ls-remote)
+//   pr        the PR/MR exists, is open or merged, and its head is that SHA
+//   merged    the forge reports the PR/MR merged; when workit merged it, the
+//             recorded merge commit is reachable from the base's remote tip
+//   released  the tag exists on the remote (pointing at --sha when given),
+//             and the npm version is published (gitHead == the tag's commit)
+//
+// Read-only on the repository (fetches by object id move no ref). A delivered
+// answer is appended to the ledger as an observed `delivery.verified` row.
+import { spawnSync } from "node:child_process";
+import { findExecutable } from "./exec";
+import {
+  aheadBehind,
+  currentBranch,
+  fetchRefs,
+  hasCommit,
+  pushRemoteName,
+  pushUrl,
+  redactRemote,
+  remoteNames,
+  remoteRefTip,
+  resolveRef,
+} from "../git/rev";
+import { appendObserved, readLedger, type LedgerActor } from "../ledger";
+import { selectPr } from "./report";
+import type { ResolvedForge } from "./resolve";
+import { redactText } from "./redact";
+import { failure, success, type ForgeResult } from "./types";
+
+export type DeliveryEndpoint = "pushed" | "pr" | "merged" | "released";
+
+export type Observation = {
+  kind:
+    | "remote_tip"
+    | "pr_state"
+    | "pr_head"
+    | "merge_on_base"
+    | "tag"
+    | "npm_version"
+    | "npm_git_head";
+  expected: string | null;
+  observed: string | null;
+  ok: boolean;
+  note?: string;
+};
+
+export type DeliveryReport = {
+  expect: DeliveryEndpoint;
+  branch: string | null;
+  sha: string | null;
+  pr: number | null;
+  delivered: boolean;
+  observations: Observation[];
+  recorded?: { id: string } | { error: string };
+};
+
+/** Runs `npm view …` (injected in tests). */
+export type NpmRunner = (args: readonly string[]) => {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+};
+
+// npm package names (URL-safe, optional @scope/) and semver.
+// Both are checked before npm runs, so no argument can carry shell syntax.
+// Upper case is accepted: legacy packages (published before the lower-case
+// rule) are still installable, and this only looks them up.
+const NPM_NAME = /^(?:@[A-Za-z0-9~][A-Za-z0-9-._~]*\/)?[A-Za-z0-9~][A-Za-z0-9-._~]*$/u;
+const SEMVER =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+const SAFE_ARG = /^[0-9A-Za-z@/._~+-]+$/u;
+
+export const systemNpm: NpmRunner = (args) => {
+  // Windows ships npm as npm.cmd, which only runs through cmd.exe. Every
+  // argument is a fixed word or a validated name@semver (SAFE_ARG), so the
+  // shell has nothing to interpret; anything else is refused before spawning.
+  if (!args.every((arg) => SAFE_ARG.test(arg)))
+    return { status: 2, stdout: "", stderr: "refused: unsafe npm argument" };
+  const options = {
+    encoding: "utf8" as const,
+    timeout: 30_000,
+    killSignal: "SIGKILL" as const,
+    env: { ...process.env, NO_UPDATE_NOTIFIER: "1", npm_config_update_notifier: "false" },
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"] as ["ignore", "pipe", "pipe"],
+  };
+  // On Windows one pre-validated command string goes to cmd (no args array
+  // with shell: true, which is deprecated as DEP0190).
+  const found = process.platform === "win32" ? findExecutable("npm.cmd", process.env) : null;
+  // A path cmd would expand (%VAR%, !VAR!, ^, ") falls back to PATH lookup.
+  const npmCmd = found && !/["%!^]/u.test(found) ? `"${found}"` : "npm.cmd";
+  const result =
+    process.platform === "win32"
+      ? spawnSync(`${npmCmd} ${args.join(" ")}`, { ...options, shell: true })
+      : spawnSync("npm", [...args], options);
+  return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+};
+
+const short = (sha: string | null): string => (sha ? sha.slice(0, 12) : "(absent)");
+
+function finish(
+  cwd: string,
+  report: Omit<DeliveryReport, "delivered">,
+  actor: LedgerActor,
+): DeliveryReport {
+  const delivered =
+    report.observations.length > 0 && report.observations.every((entry) => entry.ok);
+  const out: DeliveryReport = { ...report, delivered };
+  if (delivered) {
+    const row = appendObserved(cwd, {
+      type: "delivery.verified",
+      actor,
+      branch: report.branch,
+      head: report.sha,
+      ...(report.pr === null ? {} : { pr: report.pr }),
+      expect: report.expect,
+      observations: report.observations.map((entry) => ({
+        kind: entry.kind,
+        observed: entry.observed,
+      })),
+    });
+    out.recorded = row.ok ? { id: String(row.value.id) } : { error: row.error };
+  }
+  return out;
+}
+
+/** The pushed-branch observation: remote tip vs the expected (default: local) SHA. */
+export function verifyPushed(
+  cwd: string,
+  input: { branch?: string | null; sha?: string | null; actor: LedgerActor },
+): ForgeResult<DeliveryReport> {
+  const branch = input.branch ?? currentBranch(cwd);
+  if (!branch) return failure("invalid_input", "HEAD is detached; pass --branch <name>");
+  const sha = input.sha ?? resolveRef(cwd, `refs/heads/${branch}`);
+  if (!sha) return failure("not_found", `branch ${branch} has no local commit; pass --sha <sha>`);
+  const remote = pushRemoteName(cwd, branch);
+  if (!remote) return failure("not_found", "no push remote is configured for this branch");
+  const url = pushUrl(cwd, remote);
+  if (!url) return failure("blocked", `remote "${remote}" has no single push URL`);
+  const tip = remoteRefTip(cwd, url, `refs/heads/${branch}`);
+  if (!tip.ok) return failure(tip.code, tip.error);
+  const observation: Observation = {
+    kind: "remote_tip",
+    expected: sha,
+    observed: tip.sha,
+    ok: tip.sha !== null && tip.sha.startsWith(sha),
+  };
+  if (!observation.ok) {
+    const counts = tip.sha && hasCommit(cwd, tip.sha) ? aheadBehind(cwd, tip.sha, sha) : null;
+    observation.note =
+      tip.sha === null
+        ? `${branch} does not exist on ${redactRemote(url)}: nothing was pushed`
+        : counts
+          ? `${counts.ahead} local commit(s) not on ${remote}/${branch}${counts.behind ? `, ${counts.behind} remote commit(s) not local` : ""}`
+          : `${remote}/${branch} is at ${short(tip.sha)}, expected ${short(sha)}`;
+  }
+  return success(
+    finish(
+      cwd,
+      { expect: "pushed", branch, sha, pr: null, observations: [observation] },
+      input.actor,
+    ),
+  );
+}
+
+/** The PR/MR exists, is open or merged, and its head is the expected SHA. */
+export function verifyPr(
+  cwd: string,
+  resolved: ResolvedForge,
+  input: { pr?: number | null; branch?: string | null; sha?: string | null; actor: LedgerActor },
+): ForgeResult<DeliveryReport> {
+  const number = selectPr(cwd, resolved, { pr: input.pr ?? null, branch: input.branch ?? null });
+  if (!number.ok) {
+    if (number.code !== "not_found") return number;
+    const branch = input.branch ?? currentBranch(cwd);
+    return success(
+      finish(
+        cwd,
+        {
+          expect: "pr",
+          branch,
+          sha: input.sha ?? null,
+          pr: null,
+          observations: [
+            { kind: "pr_state", expected: "open", observed: null, ok: false, note: number.error },
+          ],
+        },
+        input.actor,
+      ),
+    );
+  }
+  const status = resolved.forge.prStatus(number.data);
+  if (!status.ok) return status;
+  const pr = status.data;
+  const sha = input.sha ?? resolveRef(cwd, `refs/heads/${pr.head.branch}`) ?? pr.head.sha;
+  const observations: Observation[] = [
+    { kind: "pr_state", expected: "open|merged", observed: pr.state, ok: pr.state !== "closed" },
+    {
+      kind: "pr_head",
+      expected: sha,
+      observed: pr.head.sha,
+      ok: pr.head.sha.startsWith(sha),
+      ...(pr.head.sha.startsWith(sha)
+        ? {}
+        : { note: `the PR head is ${short(pr.head.sha)}; push ${short(sha)} (workit git push)` }),
+    },
+  ];
+  return success(
+    finish(
+      cwd,
+      { expect: "pr", branch: pr.head.branch, sha, pr: pr.number, observations },
+      input.actor,
+    ),
+  );
+}
+
+/** The forge reports the PR/MR merged, and a recorded merge commit is on the base. */
+export function verifyMerged(
+  cwd: string,
+  resolved: ResolvedForge,
+  input: { pr?: number | null; branch?: string | null; actor: LedgerActor },
+): ForgeResult<DeliveryReport> {
+  const number = selectPr(cwd, resolved, { pr: input.pr ?? null, branch: input.branch ?? null });
+  if (!number.ok) return number;
+  const status = resolved.forge.prStatus(number.data);
+  if (!status.ok) return status;
+  const pr = status.data;
+  const observations: Observation[] = [
+    { kind: "pr_state", expected: "merged", observed: pr.state, ok: pr.state === "merged" },
+  ];
+  if (pr.state === "merged") {
+    const ledger = readLedger(cwd);
+    const row = ledger.ok
+      ? ledger.value.rows.findLast(
+          (entry) =>
+            entry.type === "pr.merged" && entry.pr === pr.number && entry.observer === "workit_cli",
+        )
+      : undefined;
+    const mergeSha = typeof row?.mergeSha === "string" ? row.mergeSha : null;
+    if (mergeSha) {
+      const tip = remoteRefTip(cwd, resolved.baseRemote, `refs/heads/${pr.base}`);
+      if (!tip.ok) return failure(tip.code, tip.error);
+      let onBase = false;
+      let note: string | undefined;
+      if (tip.sha) {
+        for (const sha of [mergeSha, tip.sha])
+          if (!hasCommit(cwd, sha)) fetchRefs(cwd, resolved.baseRemote, [sha]);
+        const counts =
+          hasCommit(cwd, mergeSha) && hasCommit(cwd, tip.sha)
+            ? aheadBehind(cwd, tip.sha, mergeSha)
+            : null;
+        onBase = counts !== null && counts.ahead === 0;
+        if (!counts) note = "the merge commit or the base tip could not be fetched";
+      } else note = `${pr.base} does not exist on the remote`;
+      observations.push({
+        kind: "merge_on_base",
+        expected: mergeSha,
+        observed: tip.sha,
+        ok: onBase,
+        ...(note
+          ? { note }
+          : onBase
+            ? {}
+            : { note: `${short(mergeSha)} is not reachable from ${pr.base}` }),
+      });
+    }
+  }
+  return success(
+    finish(
+      cwd,
+      { expect: "merged", branch: pr.head.branch, sha: pr.head.sha, pr: pr.number, observations },
+      input.actor,
+    ),
+  );
+}
+
+/** `@scope/name@1.2.3` → name + version (version may be absent). */
+/**
+ * `@scope/name@1.2.3` → name + version (version may be absent). Null unless
+ * the name follows npm's naming rules and the version is exact semver.
+ */
+export function parsePackageSpec(spec: string): { name: string; version: string | null } | null {
+  const value = spec.trim();
+  const at = value.lastIndexOf("@");
+  const name = at > 0 ? value.slice(0, at) : value;
+  const version = at > 0 ? value.slice(at + 1) : null;
+  if (!name || name.length > 214 || !NPM_NAME.test(name)) return null;
+  if (version !== null && !SEMVER.test(version)) return null;
+  return { name, version };
+}
+
+type NpmView = { version?: unknown; gitHead?: unknown };
+
+const npmView = (stdout: string): NpmView | null => {
+  try {
+    const parsed = JSON.parse(stdout) as unknown;
+    const value = Array.isArray(parsed) ? parsed.at(-1) : parsed;
+    return value && typeof value === "object" ? (value as NpmView) : null;
+  } catch {
+    return null;
+  }
+};
+
+export function verifyReleased(
+  cwd: string,
+  input: { tag?: string | null; pkg?: string | null; sha?: string | null; actor: LedgerActor },
+  npm: NpmRunner = systemNpm,
+): ForgeResult<DeliveryReport> {
+  if (!input.tag && !input.pkg)
+    return failure("invalid_input", "released needs --tag <tag> and/or --package <name[@version]>");
+  if (input.tag && (input.tag.startsWith("-") || !/^[0-9A-Za-z._/+-]+$/u.test(input.tag)))
+    return failure("invalid_input", "--tag must be a plain tag name");
+  const observations: Observation[] = [];
+  let tagSha: string | null = null;
+  if (input.tag) {
+    const remote = remoteNames(cwd).includes("origin") ? "origin" : pushRemoteName(cwd);
+    if (!remote) return failure("not_found", "no remote is configured");
+    const tip = remoteRefTip(cwd, remote, `refs/tags/${input.tag}`);
+    if (!tip.ok) return failure(tip.code, tip.error);
+    tagSha = tip.sha;
+    const expected = input.sha ?? null;
+    observations.push({
+      kind: "tag",
+      expected: expected ?? input.tag,
+      observed: tip.sha,
+      ok: tip.sha !== null && (expected === null || tip.sha.startsWith(expected)),
+      ...(tip.sha === null ? { note: `tag ${input.tag} is not on ${remote}` } : {}),
+    });
+  }
+  if (input.pkg) {
+    const spec = parsePackageSpec(input.pkg);
+    if (!spec)
+      return failure(
+        "invalid_input",
+        "--package must be an npm package name, optionally @<semver> (e.g. @scope/pkg@1.2.3)",
+      );
+    const version = spec.version ?? (input.tag ? input.tag.replace(/^v(?=\d)/u, "") : null);
+    if (!version)
+      return failure("invalid_input", "--package needs a version (<name>@<version>) or --tag");
+    if (!SEMVER.test(version))
+      return failure(
+        "invalid_input",
+        `${version} (from --tag) is not a semver version; pass <name>@<version>`,
+      );
+    const viewed = npm(["view", `${spec.name}@${version}`, "version", "gitHead", "--json"]);
+    if (
+      viewed.status !== 0 &&
+      !/E404|404 Not Found|is not in this registry|No match found/iu.test(viewed.stderr)
+    )
+      return failure(
+        "unavailable",
+        `npm view ${spec.name}@${version} failed: ${redactText(viewed.stderr).trim().split("\n")[0]?.slice(0, 200) ?? ""}`,
+      );
+    const observed = viewed.status === 0 ? npmView(viewed.stdout) : null;
+    const observedVersion = typeof observed?.version === "string" ? observed.version : null;
+    observations.push({
+      kind: "npm_version",
+      expected: `${spec.name}@${version}`,
+      observed: observedVersion ? `${spec.name}@${observedVersion}` : null,
+      ok: observedVersion === version,
+      ...(observedVersion === version ? {} : { note: `${spec.name}@${version} is not published` }),
+    });
+    // A commit expectation (the tag's commit, else --sha) must be proven by
+    // the published gitHead; a package without one is unverifiable, not ok.
+    const gitHead = typeof observed?.gitHead === "string" ? observed.gitHead : null;
+    const commit = tagSha ?? input.sha ?? null;
+    if (commit && observedVersion === version)
+      observations.push({
+        kind: "npm_git_head",
+        expected: commit,
+        observed: gitHead,
+        ok: gitHead !== null && gitHead.startsWith(commit),
+        ...(gitHead === null
+          ? { note: `unverified: ${spec.name}@${version} was published without a gitHead` }
+          : gitHead.startsWith(commit)
+            ? {}
+            : { note: `${spec.name}@${version} was published from ${short(gitHead)}` }),
+      });
+  }
+  return success(
+    finish(
+      cwd,
+      {
+        expect: "released",
+        branch: null,
+        sha: tagSha ?? input.sha ?? null,
+        pr: null,
+        observations,
+      },
+      input.actor,
+    ),
+  );
+}