@vzn/vx-ci 0.0.0 → 0.0.519

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vx contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
 # @vzn/vx-ci
 
-Placeholder. See https://github.com/vznjs/vx.
+GitHub Actions integration for [`@vzn/vx`](https://github.com/vznjs/vx) — a
+telemetry plugin that writes every `vx run` as a **job summary** on the
+workflow run page.
+
+```sh
+npm install -D @vzn/vx @vzn/vx-ci   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
+```
+
+```ts
+// vx.workspace.ts
+import { defineWorkspace } from '@vzn/vx/config'
+import { github } from '@vzn/vx-ci'
+
+export default defineWorkspace({
+  plugins: [github()],
+})
+```
+
+That's the whole setup. On a GitHub Actions runner (`GITHUB_STEP_SUMMARY`
+set) every `vx run` appends a summary block, on its own line after
+anything already written in the step: verdict headline, stats
+(tasks / executed / cache hits / duration), failures called out above the
+per-task table with their exit code, the signal an exit above 128
+stands for (`exit 137 (128 + SIGKILL)`, as the run's own frame and
+`vx last` say it), a timeout as `timed out, exit 143`, a persistent task
+that never became ready as `never ready (timed out)`, a sandboxed task's
+violation count, and the tasks each failure blocked. A footer line
+names the vx version, the command (what follows `--` counted, not
+quoted), tasks passed and outputs restored.
+Anywhere else — laptops, other CI — the plugin **declines** and costs
+nothing, so declaring it unconditionally is safe.
+
+## Options
+
+The options type is `GithubPluginOptions`; `renderJobSummary` renders the
+summary lines the plugin posts (the site's CI guide sample is rendered from it).
+The package exports `github`, `renderJobSummary` and the types `GithubPluginOptions`
+and `FetchFn`; nothing else. `fetchFn`, `append` and `sizeOf` are test seams:
+they replace the Checks API transport, the summary writer and its size probe.
+
+```ts
+github({
+  summaryFile: '/path/override.md', // default: $GITHUB_STEP_SUMMARY
+  title: 'build & test', // default: 'vx run'
+  checks: true, // default: on with GITHUB_TOKEN; true warns when it is missing, false opts out
+  checkName: 'ci', // default: 'vx', the check run's name
+  cacheScope: false, // default: on; scope remote cache writes by ref
+})
+```
+
+## Cache scope
+
+On Actions (`GITHUB_ACTIONS=true`), when `vx.workspace.ts` sets no `cacheScope`, the plugin's
+`config` stage sets it from the ref (`GITHUB_REF`, `GITHUB_REF_NAME`, and
+the default branch from the `GITHUB_EVENT_PATH` payload): a push to the default branch stays
+trusted (reads and writes the task keys), a pull request becomes
+`pr-<n>` and any other branch or tag `ref-<name>`, which read their
+own keys, then the trusted ones, and write only their own. A PR never writes what main
+reads. `VX_CACHE_SCOPE` or a `cacheScope` in `vx.workspace.ts` overrides it. This is a client-side convention: the real boundary is a cache
+token the server limits, so give PR jobs one that cannot write the
+trusted keys (`docs/security.md` § Cache poisoning).
+
+## How it works
+
+`github()` contributes one observe-only telemetry sink through vx's
+`telemetry` seam. It receives the versioned `RunSummaryRecord` at run end
+and renders + appends the markdown in `flush()` — it holds no run handle,
+streams no per-event records (`wants: []`), and a slow or failing write can
+never fail or stall the run (core's crash-isolation + flush deadline).
+
+Core's manual path still exists without this plugin:
+`vx run --report=markdown --report-file "$GITHUB_STEP_SUMMARY"` writes a
+plain table. The plugin's summary is richer (verdict, stats, failure
+callouts) and automatic on every run.
+
+## The PR check run
+
+With `GITHUB_TOKEN` in the environment (plus `GITHUB_REPOSITORY` /
+`GITHUB_SHA`, both set by the runner) the plugin also creates one
+**completed check-run** on the built commit — conclusion `success`,
+`failure`, or `cancelled` for a run a signal stopped with nothing
+failed (a cancelled job), its output the same summary markdown — so the verdict shows in
+the PR's checks list, not just the workflow page. The workflow must grant
+the permission:
+
+```yaml
+permissions:
+  checks: write
+```
+
+Without the token the check is silently skipped (the job summary still
+writes); pass `checks: true` to warn instead, or `checks: false` to opt
+out entirely; a value that is not a boolean is refused. GitHub's own blips (`502`, `503`, `504`, a dropped
+connection) are retried twice, 200 then 800 ms apart, until the flush deadline, which warns the last answer. A failed POST warns and never fails the run — a `403` says
+to check `permissions: checks: write`, a rate limit (`429`, or a `403`
+saying so) says so and is not retried — and a slow API costs the run
+nothing past core's end-of-run flush deadline. On `pull_request` events
+`GITHUB_SHA` is the merge commit; GitHub still surfaces the check on the
+PR.
+
+On GitHub Enterprise Server the POST goes to `GITHUB_API_URL`. A host
+behind a private CA is trusted through `NODE_EXTRA_CA_CERTS` (a PEM
+file of the CA); an untrusted certificate is not retried and its warning
+names that variable.
+
+Both artifacts are bounded by GitHub's own limits, because exceeding
+either loses the whole thing rather than its tail: the check-run output
+at 65 535 bytes, the job summary at 1 MiB counted in bytes (about 19 000 task rows; fewer when task names are not ASCII), cut on a character boundary. GitHub's cap is the step's whole summary file, so the page fits in what earlier writers in the step left; with no room it is skipped with a warning.
+Past either, what is written ends with a line saying it was truncated.

package/index.ts

@@ -0,0 +1,4 @@
+// Root entry shim: Bun 1.4.0's `--compile` binaries resolve an on-disk
+// package by `<pkg>/index.ts` and ignore package.json `exports` / `main`
+// (see packages/vx/index.ts). Same module as the exports map names.
+export * from './src/index.js'

package/package.json

@@ -1,7 +1,45 @@
 {
   "name": "@vzn/vx-ci",
-  "version": "0.0.0",
-  "description": "Placeholder. The real package is published by vx's release workflow.",
+  "version": "0.0.519",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/vznjs/vx.git" }
+  "description": "GitHub Actions integration for vx — a telemetry plugin that writes the run as a GitHub Actions job summary.",
+  "keywords": [
+    "vx",
+    "vx-plugin",
+    "monorepo",
+    "github-actions",
+    "job-summary",
+    "checks"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@vzn/vx": "^0.0.519"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vznjs/vx.git",
+    "directory": "packages/vx-ci"
+  },
+  "homepage": "https://github.com/vznjs/vx/tree/main/packages/vx-ci#readme",
+  "bugs": "https://github.com/vznjs/vx/issues"
 }

package/src/cache-scope.ts

@@ -0,0 +1,36 @@
+// The cache scope a GitHub Actions run gets when the workspace names none:
+// the default branch is trusted, anything else writes to its own scope.
+import { readFile } from 'node:fs/promises'
+
+/**
+ * `undefined` (leave the workspace's default, trusted) on a push to the
+ * default branch, outside Actions, or when the ref is unknown; else
+ * `pr-<n>` for a pull request and `ref-<name>` for any other branch or tag.
+ */
+export async function githubCacheScope(
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<string | undefined> {
+  if (env['GITHUB_ACTIONS'] !== 'true') return undefined
+  const ref = env['GITHUB_REF'] ?? ''
+  const pr = /^refs\/pull\/(\d+)\//.exec(ref)
+  if (pr !== null) return `pr-${pr[1]}`
+  const name = env['GITHUB_REF_NAME']
+  if (ref === '' || name === undefined || name === '') return undefined
+  if (ref === `refs/heads/${await defaultBranch(env['GITHUB_EVENT_PATH'])}`) return undefined
+  // `cacheScope` takes letters, digits and . _ - / @; a ref may hold more.
+  return `ref-${name.replace(/[^\w.@/-]/g, '_').slice(0, 124)}`
+}
+
+/** The repository's default branch, from the event payload the runner writes. */
+async function defaultBranch(eventPath: string | undefined): Promise<string | undefined> {
+  if (eventPath === undefined || eventPath === '') return undefined
+  try {
+    const event = JSON.parse(await readFile(eventPath, 'utf8')) as {
+      repository?: { default_branch?: unknown }
+    }
+    const branch = event.repository?.default_branch
+    return typeof branch === 'string' && branch !== '' ? branch : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/checks.ts

@@ -0,0 +1,201 @@
+// The Checks API half: one completed `check-run` on the built commit, whose
+// output is the same summary markdown the job summary shows. Needs
+// `GITHUB_TOKEN` with `checks: write`; the plugin declines the check (not
+// the whole sink) without one, so the summary still works token-less.
+import type { RunSummaryRecord } from '@vzn/vx'
+
+export type FetchFn = (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal },
+) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>
+
+export interface CheckRunEnv {
+  token: string
+  repository: string
+  /** The commit the check attaches to. On `pull_request` events
+   *  `GITHUB_SHA` is the MERGE commit; GitHub still renders the check on
+   *  the PR, so that is the documented default. */
+  sha: string
+  apiUrl: string
+}
+
+/** Read the Actions environment; `null` when any piece is missing. */
+export function resolveCheckRunEnv(env: Record<string, string | undefined>): CheckRunEnv | null {
+  const token = env['GITHUB_TOKEN']
+  const repository = env['GITHUB_REPOSITORY']
+  const sha = env['GITHUB_SHA']
+  // All three treated alike: an EMPTY var is as absent as a missing one.
+  // Only the token used to be checked for empty, so `GITHUB_REPOSITORY=''`
+  // built a POST to `/repos//check-runs` and `GITHUB_SHA=''` sent
+  // `head_sha: ''` — a 404 or 422 warning where a clean decline was meant.
+  if (
+    token === undefined ||
+    token === '' ||
+    repository === undefined ||
+    repository === '' ||
+    sha === undefined ||
+    sha === ''
+  ) {
+    return null
+  }
+  // The same for the API URL: `??` kept an empty one, and the POST went to a
+  // relative URL fetch refuses (item 924).
+  const apiUrl = env['GITHUB_API_URL']
+  return {
+    token,
+    repository,
+    sha,
+    apiUrl: apiUrl === undefined || apiUrl === '' ? 'https://api.github.com' : apiUrl,
+  }
+}
+
+/** fetch refused the server's certificate (untrusted, expired, wrong name). */
+function isCertificateRefusal(err: unknown): boolean {
+  const code = (err as { code?: unknown } | null)?.code
+  return (
+    typeof code === 'string' &&
+    (code.includes('CERT') || code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE')
+  )
+}
+
+/**
+ * GitHub caps `output.summary` at 65535 characters; truncate with a tell.
+ * Counted in UTF-8 bytes, which is never fewer than the characters, so
+ * the page fits whichever unit GitHub counts. The cut was in UTF-16 units
+ * and split an emoji (the aborted label 🛑) into a lone surrogate the JSON
+ * body carried (item 924); it now backs off a continuation byte, as the job
+ * summary's does.
+ */
+export function clampSummary(markdown: string): string {
+  const MAX = 65_535
+  if (markdown.length * 3 <= MAX) return markdown
+  const bytes = new TextEncoder().encode(markdown)
+  if (bytes.byteLength <= MAX) return markdown
+  const suffix = '\n\n…truncated by @vzn/vx-ci (65535-char Checks API limit)'
+  let end = MAX - new TextEncoder().encode(suffix).byteLength
+  while (end > 0 && (bytes[end]! & 0xc0) === 0x80) end--
+  return new TextDecoder().decode(bytes.subarray(0, end)) + suffix
+}
+
+export function buildCheckRunPayload(args: {
+  summary: RunSummaryRecord
+  markdown: string
+  name: string
+  sha: string
+}): Record<string, unknown> {
+  const ok = args.summary.exitOk
+  // Stopped, not broken: a cancelled CI job's run has aborted tasks and
+  // nothing failed, and GitHub has a conclusion for exactly that.
+  const cancelled = !ok && args.summary.failedCount === 0 && args.summary.abortedCount > 0
+  return {
+    name: args.name,
+    head_sha: args.sha,
+    status: 'completed',
+    conclusion: ok ? 'success' : cancelled ? 'cancelled' : 'failure',
+    started_at: new Date(args.summary.startedAt).toISOString(),
+    completed_at: new Date(args.summary.endedAt).toISOString(),
+    output: {
+      title: ok
+        ? `${args.summary.taskCount} task${args.summary.taskCount === 1 ? '' : 's'} · ${args.summary.hitCount} cached` +
+          (args.summary.hitCount > 0
+            ? ` (${args.summary.upToDateCount} up-to-date, ${args.summary.restoredLocalCount + args.summary.restoredRemoteCount} restored)`
+            : '')
+        : cancelled
+          ? `cancelled · ${args.summary.abortedCount} aborted`
+          : `${args.summary.failedCount} failed`,
+      summary: clampSummary(args.markdown),
+    },
+  }
+}
+
+/** Resolves true when `signal` ended the wait. */
+function sleepUnless(ms: number, signal: AbortSignal | undefined): Promise<boolean> {
+  return new Promise((resolve) => {
+    const done = (): void => {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', done)
+      resolve(signal?.aborted === true)
+    }
+    const timer = setTimeout(done, ms)
+    signal?.addEventListener('abort', done, { once: true })
+  })
+}
+
+const CHECK_RETRY_DELAYS_MS = [200, 800] as const
+const CHECK_RETRY_STATUS = new Set([502, 503, 504])
+
+/**
+ * POST the check run. Failures are REPORTED via `warn`, never thrown —
+ * observability must never break a run. `signal` is core's flush deadline:
+ * the deadline alone abandoned the request, and a hanging API kept the
+ * process alive with no end (item 1055).
+ */
+export async function postCheckRun(args: {
+  env: CheckRunEnv
+  payload: Record<string, unknown>
+  fetchFn: FetchFn
+  warn: (m: string) => void
+  signal?: AbortSignal
+}): Promise<void> {
+  const url = `${args.env.apiUrl}/repos/${args.env.repository}/check-runs`
+  const post = () =>
+    args.fetchFn(url, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${args.env.token}`,
+        accept: 'application/vnd.github+json',
+        'content-type': 'application/json',
+        'x-github-api-version': '2022-11-28',
+        'user-agent': 'vzn-vx-ci',
+      },
+      body: JSON.stringify(args.payload),
+      ...(args.signal === undefined ? {} : { signal: args.signal }),
+    })
+  try {
+    // GitHub's own blips (502, 503, 504, a dropped connection) are retried
+    // twice, 200 then 800 ms apart, inside the flush deadline: one of them
+    // cost the run its check (F-29). A retry after a 502 that GitHub did
+    // process adds a second run of the same name, which GitHub shows as one.
+    let res: Awaited<ReturnType<FetchFn>> | undefined
+    for (let attempt = 0; ; attempt++) {
+      const delay = CHECK_RETRY_DELAYS_MS[attempt]
+      try {
+        res = await post()
+        if (!CHECK_RETRY_STATUS.has(res.status) || delay === undefined) break
+      } catch (err) {
+        // A refused certificate (a GHES host behind a private CA) fails the
+        // same way every time: not retried (F-40).
+        if (delay === undefined || args.signal?.aborted === true || isCertificateRefusal(err)) {
+          throw err
+        }
+      }
+      if (args.signal?.aborted === true) break
+      // The deadline ended the wait: GitHub's last answer is what to tell,
+      // not the AbortError a further POST would throw (F-46).
+      if (await sleepUnless(delay, args.signal)) break
+    }
+    if (res === undefined) throw new Error('the flush deadline passed before it could be retried')
+    if (!res.ok) {
+      const body = await res.text().catch(() => '')
+      // GitHub answers a rate limit (primary or secondary) with 403 as often
+      // as 429, and the permissions hint sent every such run to its workflow
+      // file. Not retried: its retry-after is seconds to minutes, past core's
+      // flush deadline (F-13).
+      const limited = res.status === 429 || /rate limit/i.test(body)
+      const hint = limited
+        ? ' — rate-limited by GitHub; this run has no check'
+        : res.status === 403
+          ? ' — does the workflow grant `permissions: checks: write`?'
+          : ''
+      args.warn(`vx-ci: check-run POST failed (${res.status})${hint}: ${body.slice(0, 200)}`)
+    }
+  } catch (err) {
+    // A GHES host behind a private CA: Bun's fetch trusts a CA named there.
+    const hint = isCertificateRefusal(err)
+      ? " — for a host behind a private CA, set NODE_EXTRA_CA_CERTS to its CA's PEM file"
+      : ''
+    args.warn(
+      `vx-ci: check-run POST failed: ${err instanceof Error ? err.message : String(err)}${hint}`,
+    )
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// Public API for @vzn/vx-ci — the GitHub Actions integration plugin.
+//
+// Usage in vx.workspace.ts:
+//   import { defineWorkspace } from '@vzn/vx'
+//   import { github } from '@vzn/vx-ci'
+//   export default defineWorkspace({ plugins: [github()] })
+//
+// On a GitHub Actions runner (GITHUB_STEP_SUMMARY set) every `vx run`
+// appends a job summary: verdict, stats, failures, and the per-task table.
+// Anywhere else the plugin declines and costs nothing.
+export { github, type GithubPluginOptions } from './plugin.js'
+export { renderJobSummary } from './summary.js'
+// The Checks API helpers are the plugin's own; only the transport type
+// the options name is public (1.0 freezes what this file exports).
+export { type FetchFn } from './checks.js'

package/src/plugin.ts

@@ -0,0 +1,208 @@
+// The `github()` telemetry plugin. Contributes one observe-only sink that
+// writes the run as a GitHub Actions job summary. Declines (returns
+// undefined) outside GitHub Actions — no `GITHUB_STEP_SUMMARY` file to write
+// and no cost — so declaring `github()` is safe in every environment, the
+// same decline pattern as `otel()`.
+import { appendFile, stat } from 'node:fs/promises'
+import {
+  refuseUnknownOptions,
+  type PluginOptionKinds,
+  definePlugin,
+  type RunSummaryRecord,
+  type TelemetrySink,
+  type VxPlugin,
+} from '@vzn/vx'
+import {
+  buildCheckRunPayload,
+  postCheckRun,
+  resolveCheckRunEnv,
+  type CheckRunEnv,
+  type FetchFn,
+} from './checks.js'
+import { githubCacheScope } from './cache-scope.js'
+import { clampJobSummary, MAX_JOB_SUMMARY_BYTES, renderJobSummary } from './summary.js'
+
+export interface GithubPluginOptions {
+  /**
+   * Target file for the summary markdown. Falls back to
+   * `GITHUB_STEP_SUMMARY` (set by the Actions runner); with neither, the
+   * plugin declines.
+   */
+  summaryFile?: string
+  /** Heading for the summary block. Default: `'vx run'`. */
+  title?: string
+  /**
+   * Also create a completed check-run on the built commit (Checks API).
+   * Default: on when the environment carries `GITHUB_TOKEN` +
+   * `GITHUB_REPOSITORY` + `GITHUB_SHA` (the workflow must grant
+   * `permissions: checks: write`); set `false` to opt out, `true` to warn
+   * when the environment is missing instead of silently skipping.
+   */
+  checks?: boolean
+  /** Check-run name. Default: `'vx'`. */
+  checkName?: string
+  /**
+   * Set the workspace's `cacheScope` from the run's ref when it names none:
+   * a push to the default branch stays trusted, a pull request writes to
+   * `pr-<n>`, any other ref to `ref-<name>`. Default: on; `false` opts out.
+   */
+  cacheScope?: boolean
+  /** Test seam — inject the append. Defaults to fs appendFile. */
+  append?: (file: string, markdown: string) => Promise<void>
+  /** Test seam — inject the Checks API transport. Defaults to fetch. */
+  fetchFn?: FetchFn
+  /**
+   * Test seam — bytes the summary file already holds. Defaults to its size
+   * on disk; with `append` injected, 0 (that writer owns the file).
+   */
+  sizeOf?: (file: string) => Promise<number>
+}
+
+export class GithubSummarySink implements TelemetrySink {
+  readonly name = 'github-job-summary'
+  /** Summary-only: no streaming records at all — zero per-event cost. */
+  readonly wants: [] = []
+  private summary: RunSummaryRecord | undefined
+
+  constructor(
+    private readonly file: string,
+    private readonly title: string,
+    private readonly append: (file: string, markdown: string) => Promise<void>,
+    private readonly warn: (m: string) => void,
+    private readonly check?: { env: CheckRunEnv; name: string; fetchFn: FetchFn },
+    /** Bytes the summary file already holds. */
+    private readonly sizeOf: (file: string) => Promise<number> = async () => 0,
+  ) {}
+
+  onRunSummary(summary: RunSummaryRecord): void {
+    // MUST return promptly (contract): stash, render + write in flush().
+    this.summary = summary
+  }
+
+  async flush(signal?: AbortSignal): Promise<void> {
+    if (this.summary === undefined) return
+    const markdown = renderJobSummary(this.summary, this.title)
+    // The two artifacts are INDEPENDENT, and the plugin already says so in
+    // one direction: it declines the check-run without a token and still
+    // writes the summary. The reverse has to hold, or a full disk on the
+    // runner costs the PR its check — the more visible of the two. Reported,
+    // not thrown: a telemetry sink may never break a run.
+    try {
+      // Clamped: past GitHub's 1 MiB cap the runner drops the summary whole,
+      // so a bounded page beats none. The cap covers the step's whole file,
+      // and a page clamped to 1 MiB after another writer's output lost both
+      // (F-42): the room is what is left. The check-run payload has its own,
+      // smaller cap and is clamped where it is built.
+      const used = await this.sizeOf(this.file)
+      // After another writer the page starts on its own line: one that left
+      // no final newline ran vx's heading into its paragraph (F-51).
+      const lead = used > 0 ? '\n' : ''
+      const page = clampJobSummary(markdown, MAX_JOB_SUMMARY_BYTES - used - lead.length)
+      if (page === '') {
+        this.warn(
+          `vx-ci: ${this.file} already holds ${used} bytes of GitHub's 1 MiB job summary cap — no room for vx's page`,
+        )
+      } else {
+        await this.append(this.file, lead + page)
+      }
+    } catch (err) {
+      this.warn(
+        `vx-ci: could not write the job summary to ${this.file}: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+    if (this.check !== undefined) {
+      await postCheckRun({
+        env: this.check.env,
+        payload: buildCheckRunPayload({
+          summary: this.summary,
+          markdown,
+          name: this.check.name,
+          sha: this.check.env.sha,
+        }),
+        fetchFn: this.check.fetchFn,
+        warn: this.warn,
+        ...(signal === undefined ? {} : { signal }),
+      })
+    }
+  }
+}
+
+/**
+ * Why a string cannot be an HTTP header value, or null. Bun's `fetch`
+ * refuses a line break, a NUL or a character past Latin-1 once it has
+ * trimmed the ends (measured on 1.4.2), and quotes the value in its error.
+ */
+function headerValueFault(value: string): string | null {
+  let past = false
+  for (const ch of value.trim()) {
+    const c = ch.codePointAt(0)!
+    if (c === 0x0a || c === 0x0d || c === 0) return 'a line break or NUL'
+    if (c > 0xff) past = true
+  }
+  return past ? 'a character past Latin-1' : null
+}
+
+/** Each option `GithubPluginOptions` names, with its kind: derived from the type, so the two cannot drift. */
+const GITHUB_PLUGIN_KEYS: PluginOptionKinds<GithubPluginOptions> = {
+  summaryFile: 'string',
+  title: 'string',
+  checks: 'boolean',
+  checkName: 'string',
+  cacheScope: 'boolean',
+  append: 'function',
+  fetchFn: 'function',
+  sizeOf: 'function',
+}
+
+export function github(options: GithubPluginOptions = {}): VxPlugin {
+  refuseUnknownOptions('github()', options, GITHUB_PLUGIN_KEYS)
+  return definePlugin(import.meta, {
+    async config(workspace) {
+      if (options.cacheScope === false || workspace.cacheScope !== undefined) return
+      const scope = await githubCacheScope(process.env)
+      if (scope !== undefined) workspace.cacheScope = scope
+    },
+    telemetry(ctx) {
+      const file = options.summaryFile ?? process.env['GITHUB_STEP_SUMMARY']
+      if (file === undefined || file === '') return undefined
+      const append = options.append ?? (async (f: string, md: string) => appendFile(f, md, 'utf8'))
+      let check: ConstructorParameters<typeof GithubSummarySink>[4]
+      if (options.checks !== false) {
+        const env = resolveCheckRunEnv(process.env)
+        // fetch refuses a token no header can carry and QUOTES it in its
+        // error, which the check-run warning printed (item 928).
+        const fault = env === null ? null : headerValueFault(env.token)
+        if (fault !== null) {
+          ctx.warn(
+            `vx-ci: GITHUB_TOKEN holds ${fault}, which no HTTP header can carry — no check-run will be created (the token is not printed)`,
+          )
+        } else if (env !== null) {
+          check = {
+            env,
+            name: options.checkName ?? 'vx',
+            fetchFn: options.fetchFn ?? (fetch as unknown as FetchFn),
+          }
+        } else if (options.checks === true) {
+          ctx.warn(
+            'vx-ci: checks requested but GITHUB_TOKEN / GITHUB_REPOSITORY / GITHUB_SHA are not all set — no check-run will be created',
+          )
+        }
+      }
+      return new GithubSummarySink(
+        file,
+        options.title ?? 'vx run',
+        append,
+        (m) => ctx.warn(m),
+        check,
+        options.sizeOf ??
+          (options.append !== undefined
+            ? async () => 0
+            : (f: string) =>
+                stat(f).then(
+                  (st) => st.size,
+                  () => 0,
+                )),
+      )
+    },
+  })
+}

package/src/summary.ts

@@ -0,0 +1,175 @@
+// Pure markdown rendering: RunSummaryRecord -> a GitHub Actions job summary.
+// Purpose-built for the job-summary surface (verdict headline, stats line,
+// failures called out above the table) rather than reusing core's
+// `--report=markdown` table — a job summary is a landing page, not a cell
+// grid. `escapeMarkdownCell` comes from core's façade: task names are the
+// same unvalidated strings core renders, and the old cloud job summary
+// shipped without the escape once already.
+import {
+  escapeMarkdownCell,
+  exitSignal,
+  isCacheHit,
+  isPassStatus,
+  type RunSummaryRecord,
+  type TaskTelemetry,
+} from '@vzn/vx'
+
+const STATUS_LABEL: Record<string, string> = {
+  success: '✅ ran',
+  'cache-hit': '⚡ restored',
+  'cache-hit-remote': '☁️ restored remote',
+  failed: '❌ failed',
+  skipped: '⏭️ skipped',
+  aborted: '🛑 aborted',
+}
+
+// Rounded once, then split: rounding the remainder after flooring the
+// minutes printed 119.7 s as `1m 60s`. The tier is chosen by the rounded
+// value: 59.96 s printed `60.0s` and 999.6 ms `1000ms` (F-51).
+function fmtMs(ms: number): string {
+  if (Math.round(ms) < 1000) return `${Math.round(ms)}ms`
+  if (Math.round(ms / 100) < 600) return `${(ms / 1000).toFixed(1)}s`
+  const s = Math.round(ms / 1000)
+  return `${Math.floor(s / 60)}m ${s % 60}s`
+}
+
+function statusLabel(t: TaskTelemetry): string {
+  // A hit that found its outputs in place restored nothing: up to date,
+  // whichever layer answered, as vx's own summary says it.
+  if (isCacheHit(t.status) && t.restored !== true) return '✔️ up-to-date'
+  return STATUS_LABEL[t.status] ?? t.status
+}
+
+/** `(3 up-to-date, 2 restored)`, with the remote share when any came from there. */
+function hitSplit(s: RunSummaryRecord): string {
+  const restored = s.restoredLocalCount + s.restoredRemoteCount
+  const remote = s.restoredRemoteCount > 0 ? `, ${s.restoredRemoteCount} from remote` : ''
+  return `(${s.upToDateCount} up-to-date, ${restored} restored${remote})`
+}
+
+/**
+ * GitHub caps a step's job summary at 1 MiB and REJECTS the upload past it,
+ * so an unbounded summary costs the whole page rather than its tail. At the
+ * measured ~55 bytes a row that is about 19 000 tasks — a scale this repo's
+ * own bench generates (5 000 projects × four tasks), so it is reachable
+ * rather than theoretical. Cut from the END: the verdict, the stats line and
+ * the Failures section are rendered first, and they are what a reader needs.
+ * The cap is the step's whole file, so the room is what other writers in
+ * the step have left (F-42).
+ */
+export const MAX_JOB_SUMMARY_BYTES = 1024 * 1024
+
+export function clampJobSummary(markdown: string, room = MAX_JOB_SUMMARY_BYTES): string {
+  // The cap is BYTES, and the page is not ASCII: every status label is an
+  // emoji (4 bytes, 2 UTF-16 units) and every separator a `·` or a `—`
+  // (2 and 3 bytes, 1 unit). Measured in `.length`, a clamped page of those
+  // rows came out past 1 MiB and GitHub refused it whole (item 806). A unit
+  // is at most 3 bytes, so a short page skips the encode.
+  if (markdown.length * 3 <= room) return markdown
+  const bytes = new TextEncoder().encode(markdown)
+  if (bytes.byteLength <= room) return markdown
+  const suffix = '\n\n…truncated by @vzn/vx-ci (GitHub caps a job summary at 1 MiB)\n'
+  let end = room - new TextEncoder().encode(suffix).byteLength
+  if (end <= 0) return ''
+  // Back up off a continuation byte, so the cut never splits a character.
+  while (end > 0 && (bytes[end]! & 0xc0) === 0x80) end--
+  return new TextDecoder().decode(bytes.subarray(0, end)) + suffix
+}
+
+/**
+ * A task id as inline markdown: `a#*x*` rendered as `a#` and an italic
+ * `x` (item 1058). Table cells escape their pipes on top of this.
+ */
+function escapeInline(s: string): string {
+  return s.replace(/[\\`*_[\]<>]/g, '\\$&')
+}
+
+/**
+ * A code span that holds any text: its fence is one backtick longer than
+ * the longest run inside, padded when the text starts or ends with one.
+ * The footer cell-escaped the command instead, which is for tables: a `|`
+ * showed as `\|`, and a backtick ended the span early (item 1058).
+ */
+function codeSpan(raw: string): string {
+  // A lone CR is a line ending too (CommonMark), and broke the span (F-51).
+  const s = raw.replace(/\r\n?|\n/g, ' ')
+  const longest = Math.max(0, ...(s.match(/`+/g) ?? []).map((r) => r.length))
+  const fence = '`'.repeat(longest + 1)
+  const pad = s.startsWith('`') || s.endsWith('`') ? ' ' : ''
+  return `${fence}${pad}${s}${pad}${fence}`
+}
+
+/** Render the whole job summary. Deterministic for a given record. */
+export function renderJobSummary(summary: RunSummaryRecord, title = 'vx run'): string {
+  const failed = summary.tasks.filter((t) => t.status === 'failed')
+  const cancelled = !summary.exitOk && summary.failedCount === 0 && summary.abortedCount > 0
+  const verdict = summary.exitOk ? '✅' : cancelled ? '⏹️' : '❌'
+  const lines: string[] = []
+  lines.push(`## ${verdict} ${title}`)
+  lines.push('')
+  const executed = summary.tasks.filter(
+    (t) => t.status === 'success' || t.status === 'failed',
+  ).length
+  const stats = [
+    `**${summary.taskCount}** task${summary.taskCount === 1 ? '' : 's'}`,
+    `**${executed}** executed`,
+    `**${summary.hitCount}** cache hit${summary.hitCount === 1 ? '' : 's'}` +
+      (summary.hitCount > 0 ? ` ${hitSplit(summary)}` : ''),
+    ...(summary.failedCount > 0 ? [`**${summary.failedCount}** failed`] : []),
+    ...(summary.abortedCount > 0 ? [`**${summary.abortedCount}** aborted`] : []),
+    fmtMs(summary.totalDurationMs),
+  ]
+  lines.push(stats.join(' · '))
+  lines.push('')
+
+  if (failed.length > 0) {
+    // What each failure cost: the tasks that never started because of it
+    // (the record's `blockedBy` names the root of each block). Grouped once:
+    // a scan of every task per failure took 1.3 s for 10 000 failures of
+    // 20 000 tasks (F-38).
+    const blockedBy = new Map<string, string[]>()
+    for (const s of summary.tasks) {
+      if (s.status !== 'skipped' || s.blockedBy === undefined) continue
+      const list = blockedBy.get(s.blockedBy)
+      const id = escapeMarkdownCell(escapeInline(s.taskId))
+      if (list === undefined) blockedBy.set(s.blockedBy, [id])
+      else list.push(id)
+    }
+    lines.push('### Failures')
+    lines.push('')
+    for (const t of failed) {
+      // The signal an exit above 128 stands for, as the frame and `vx last`
+      // say it (the shell's convention, so a command exiting 137 on its
+      // own reads the same).
+      const signal = exitSignal(t.exitCode)
+      const blocked = blockedBy.get(t.taskId) ?? []
+      lines.push(
+        `- **${escapeMarkdownCell(escapeInline(t.taskId))}** — ${t.notReady !== undefined ? `never ready (${t.notReady === 'timeout' ? 'timed out' : t.notReady === 'exited' ? 'exited' : 'spawn failed'}), exit ${t.exitCode}` : t.timedOut === true ? `timed out, exit ${t.exitCode}` : `exit ${t.exitCode}${signal === undefined ? '' : ` (128 + ${signal})`}`}${t.sandboxViolations !== undefined && t.sandboxViolations > 0 ? ` · ${t.sandboxViolations} sandbox violation${t.sandboxViolations === 1 ? '' : 's'}` : ''}${blocked.length > 0 ? ` · blocked ${blocked.join(', ')}` : ''}`,
+      )
+    }
+    lines.push('')
+  }
+
+  const header = ['Task', 'Status', 'Duration']
+  lines.push(`| ${header.join(' | ')} |`)
+  lines.push(`|${header.map(() => ' --- ').join('|')}|`)
+  // Failures first (the eye lands on the table's top rows), then execution
+  // order as delivered.
+  const ordered = [...failed, ...summary.tasks.filter((t) => t.status !== 'failed')]
+  for (const t of ordered) {
+    const cells = [escapeMarkdownCell(escapeInline(t.taskId)), statusLabel(t), fmtMs(t.durationMs)]
+    lines.push(`| ${cells.join(' | ')} |`)
+  }
+  lines.push('')
+
+  // A one-line footer so a page with several vx runs stays attributable.
+  // `restored` counts only the hits that wrote outputs; it once counted
+  // every hit, up-to-date ones included.
+  const restored = summary.restoredLocalCount + summary.restoredRemoteCount
+  const passed = summary.tasks.filter((t) => isPassStatus(t.status)).length
+  lines.push(
+    `<sub>vx ${summary.run.vxVersion} · ${codeSpan(summary.run.command)} · ${passed}/${summary.taskCount} passed · ${summary.upToDateCount} up-to-date · ${restored} restored</sub>`,
+  )
+  lines.push('')
+  return lines.join('\n')
+}