@tikoci/rosetta 0.10.0 → 0.11.0-alpha.87

package/src/extract-skills.ts

@@ -14,6 +14,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { db, initDb } from "./db.ts";
+import { fetchGitHub, githubApiHeaders } from "./github.ts";
 
 // ── Configuration ──
 
@@ -22,7 +23,6 @@ const CACHE_DIR = join(PROJECT_ROOT, "skills");
 
 const GITHUB_REPO = "tikoci/routeros-skills";
 const GITHUB_API_BASE = `https://api.github.com/repos/${GITHUB_REPO}`;
-const GITHUB_RAW_BASE = `https://raw.githubusercontent.com/${GITHUB_REPO}`;
 
 const FROM_CACHE = process.argv.includes("--from-cache");
 
@@ -70,15 +70,8 @@ function countWords(text: string): number {
 
 // ── GitHub API fetching ──
 
-export function githubApiHeaders(): Record<string, string> {
-  const headers: Record<string, string> = { Accept: "application/vnd.github.v3+json" };
-  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
-  if (token) headers.Authorization = `Bearer ${token}`;
-  return headers;
-}
-
 async function getDefaultBranchSha(): Promise<string> {
-  const res = await fetch(`${GITHUB_API_BASE}/commits/HEAD`, {
+  const res = await fetchGitHub(`${GITHUB_API_BASE}/commits/HEAD`, {
     headers: githubApiHeaders(),
   });
   if (!res.ok) throw new Error(`Failed to get HEAD SHA: HTTP ${res.status}`);
@@ -87,7 +80,7 @@ async function getDefaultBranchSha(): Promise<string> {
 }
 
 async function listSkillDirs(sha: string): Promise<string[]> {
-  const res = await fetch(`${GITHUB_API_BASE}/contents/?ref=${sha}`, {
+  const res = await fetchGitHub(`${GITHUB_API_BASE}/contents/?ref=${sha}`, {
     headers: githubApiHeaders(),
   });
   if (!res.ok) throw new Error(`Failed to list repo contents: HTTP ${res.status}`);
@@ -98,8 +91,11 @@ async function listSkillDirs(sha: string): Promise<string[]> {
 }
 
 async function fetchRawFile(sha: string, path: string): Promise<string | null> {
-  const url = `${GITHUB_RAW_BASE}/${sha}/${path}`;
-  const res = await fetch(url);
+  const encodedPath = path.split("/").map(encodeURIComponent).join("/");
+  const url = `${GITHUB_API_BASE}/contents/${encodedPath}?ref=${sha}`;
+  const res = await fetchGitHub(url, {
+    headers: githubApiHeaders("application/vnd.github.v3.raw"),
+  });
   if (!res.ok) {
     if (res.status === 404) return null;
     throw new Error(`Failed to fetch ${path}: HTTP ${res.status}`);
@@ -108,7 +104,7 @@ async function fetchRawFile(sha: string, path: string): Promise<string | null> {
 }
 
 async function listReferences(sha: string, skillName: string): Promise<string[]> {
-  const res = await fetch(`${GITHUB_API_BASE}/contents/${skillName}/references?ref=${sha}`, {
+  const res = await fetchGitHub(`${GITHUB_API_BASE}/contents/${skillName}/references?ref=${sha}`, {
     headers: githubApiHeaders(),
   });
   if (!res.ok) {

package/src/github.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+import { defaultRetryDelayMs, shouldRetry } from "./github.ts";
+
+function fakeResponse(status: number, headers: Record<string, string> = {}): Response {
+  return new Response(null, { status, headers });
+}
+
+describe("shouldRetry", () => {
+  test("retries plain transient statuses", () => {
+    expect(shouldRetry(fakeResponse(429))).toBe(true);
+    expect(shouldRetry(fakeResponse(500))).toBe(true);
+    expect(shouldRetry(fakeResponse(502))).toBe(true);
+    expect(shouldRetry(fakeResponse(503))).toBe(true);
+    expect(shouldRetry(fakeResponse(504))).toBe(true);
+  });
+
+  test("retries 403 primary rate limit exhaustion", () => {
+    expect(shouldRetry(fakeResponse(403, { "x-ratelimit-remaining": "0" }))).toBe(true);
+  });
+
+  test("retries 403 secondary/abuse-detection limit even when quota remains", () => {
+    // GitHub secondary rate limits return 403 + Retry-After without touching
+    // x-ratelimit-remaining, since they're not tied to the primary quota.
+    expect(
+      shouldRetry(fakeResponse(403, { "retry-after": "30", "x-ratelimit-remaining": "42" })),
+    ).toBe(true);
+  });
+
+  test("does not retry plain permission-denied 403s", () => {
+    expect(shouldRetry(fakeResponse(403))).toBe(false);
+    expect(shouldRetry(fakeResponse(403, { "x-ratelimit-remaining": "42" }))).toBe(false);
+  });
+
+  test("does not retry success or not-found responses", () => {
+    expect(shouldRetry(fakeResponse(200))).toBe(false);
+    expect(shouldRetry(fakeResponse(404))).toBe(false);
+  });
+});
+
+describe("defaultRetryDelayMs", () => {
+  test("falls back to exponential backoff when x-ratelimit-reset header is missing", () => {
+    // Regression: Number(null) is 0 (finite), which previously made the reset
+    // branch return an immediate 0ms delay instead of falling through.
+    const delay = defaultRetryDelayMs(fakeResponse(403, { "x-ratelimit-remaining": "0" }), 2);
+    expect(delay).toBe(1000 * 2 ** 2);
+  });
+
+  test("uses x-ratelimit-reset when present and remaining is exhausted", () => {
+    const resetAt = Math.floor(Date.now() / 1000) + 5;
+    const delay = defaultRetryDelayMs(
+      fakeResponse(403, { "x-ratelimit-remaining": "0", "x-ratelimit-reset": String(resetAt) }),
+      0,
+    );
+    expect(delay).toBeGreaterThan(3000);
+    expect(delay).toBeLessThanOrEqual(5000);
+  });
+
+  test("prefers retry-after over rate-limit reset", () => {
+    const delay = defaultRetryDelayMs(
+      fakeResponse(403, { "retry-after": "10", "x-ratelimit-remaining": "0", "x-ratelimit-reset": "0" }),
+      0,
+    );
+    expect(delay).toBe(10_000);
+  });
+
+  test("falls back to exponential backoff with no relevant headers", () => {
+    expect(defaultRetryDelayMs(fakeResponse(500), 0)).toBe(1000);
+    expect(defaultRetryDelayMs(fakeResponse(500), 3)).toBe(8000);
+  });
+});

package/src/github.ts

@@ -0,0 +1,67 @@
+/**
+ * github.ts — Small helpers for authenticated GitHub HTTP calls.
+ *
+ * Release extraction runs from GitHub Actions shared runner IPs, so every
+ * GitHub API request should use GITHUB_TOKEN/GH_TOKEN when available and retry
+ * transient throttling responses.
+ */
+
+const DEFAULT_ACCEPT = "application/vnd.github.v3+json";
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+
+export function githubApiHeaders(accept = DEFAULT_ACCEPT): Record<string, string> {
+  const headers: Record<string, string> = { Accept: accept };
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return headers;
+}
+
+function retryAfterMs(value: string | null): number | null {
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  const dateMs = Date.parse(value);
+  if (Number.isFinite(dateMs)) return Math.max(0, dateMs - Date.now());
+  return null;
+}
+
+export function defaultRetryDelayMs(response: Response, attempt: number): number {
+  const retryAfter = retryAfterMs(response.headers.get("retry-after"));
+  if (retryAfter !== null) return retryAfter;
+
+  const resetSeconds = Number(response.headers.get("x-ratelimit-reset") ?? NaN);
+  const remaining = response.headers.get("x-ratelimit-remaining");
+  if (remaining === "0" && Number.isFinite(resetSeconds)) {
+    return Math.max(0, resetSeconds * 1000 - Date.now());
+  }
+
+  return 1000 * 2 ** attempt;
+}
+
+export function shouldRetry(response: Response): boolean {
+  if (RETRYABLE_STATUSES.has(response.status)) return true;
+  if (response.status !== 403) return false;
+  // Primary rate limit (remaining=0) or secondary/abuse-detection limit
+  // (Retry-After present even with quota remaining) are both retryable.
+  return response.headers.get("x-ratelimit-remaining") === "0" || response.headers.get("retry-after") !== null;
+}
+
+export async function fetchGitHub(
+  url: string,
+  options: RequestInit = {},
+  retries = 3,
+): Promise<Response> {
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const response = await fetch(url, options);
+    if (!shouldRetry(response) || attempt === retries) return response;
+
+    const delayMs = Math.min(defaultRetryDelayMs(response, attempt), 30_000);
+    console.warn(`GitHub request throttled (HTTP ${response.status}); retrying in ${Math.round(delayMs / 1000)}s`);
+    await Bun.sleep(delayMs);
+  }
+
+  // Unreachable in practice: every caller uses the default `retries`, and the
+  // loop always returns on its `attempt === retries` iteration. `fetch` is
+  // called once more here only so TypeScript sees every path return a Response.
+  return fetch(url, options);
+}

package/src/mcp-stdio-client.test.ts

@@ -11,13 +11,42 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { SCHEMA_VERSION } from "./paths.ts";
+import { probeDb } from "./setup.ts";
 
 const ROOT = path.resolve(import.meta.dirname, "..");
 const configuredDbPath = process.env.TEST_DB_PATH?.trim();
 const DB_PATH = configuredDbPath ? path.resolve(ROOT, configuredDbPath) : path.join(ROOT, "ros-help.db");
 const hasTestDb = existsSync(DB_PATH);
 const dbWasExplicitlyConfigured = Boolean(configuredDbPath);
-const skipReason = `No populated test database at ${DB_PATH}; set TEST_DB_PATH or place ros-help.db at repo root to run this integration test.`;
+
+// A schema-bumping change (e.g. adding pages.rosetta_id in schema v6) lands
+// in this repo before a matching DB is published to GitHub Releases — see
+// BACKLOG.md's "no release ships until the Docusaurus migration is solid"
+// sequencing gate. CI's "download latest published DB" step will keep
+// fetching a stale, lower-schema DB until that gate clears, and running the
+// real stdio server against it always fails the same way: ensureDbReady()
+// (correctly) detects the mismatch, tries to re-download, gets the same
+// stale DB back, and exits — which the client sees as "Connection closed"
+// with no useful diagnostic. Detect that specific, provable condition here
+// and skip with a clear reason instead of hard-failing CI on an artifact
+// that cannot exist yet.
+const schemaProbe = hasTestDb ? probeDb(DB_PATH) : null;
+const schemaMismatch = schemaProbe !== null && schemaProbe.schemaVersion !== SCHEMA_VERSION;
+// A file at DB_PATH that probeDb() can't read (empty, partial, or not SQLite) yields a
+// null probe. existsSync alone would let the test spawn the server against a broken DB
+// and fail with an opaque "Connection closed" — treat an unprobeable file as "no usable
+// DB" and skip with a clear reason instead (CodeRabbit, PR #13).
+const invalidTestDb = hasTestDb && schemaProbe === null;
+
+const skipReason = schemaMismatch
+  ? `Test database at ${DB_PATH} has schema_version=${schemaProbe?.schemaVersion}, but this build expects ` +
+    `${SCHEMA_VERSION}. This is expected when a schema-bumping change hasn't been published as a release yet ` +
+    `(see BACKLOG.md sequencing gate) — skipping rather than failing on a DB that cannot exist until then.`
+  : invalidTestDb
+    ? `Test database at ${DB_PATH} exists but is not a readable SQLite DB (empty, partial, or corrupt); ` +
+      `replace it or point TEST_DB_PATH at a valid ros-help.db to run this integration test.`
+    : `No populated test database at ${DB_PATH}; set TEST_DB_PATH or place ros-help.db at repo root to run this integration test.`;
 
 const EXPECTED_TOOLS = [
   "routeros_search",
@@ -76,10 +105,10 @@ function buildDiagnostics(errors: Error[], stderr: string[]): string {
   return sections.length > 0 ? `\n\n${sections.join("\n\n")}` : "";
 }
 
-describe.skipIf(!hasTestDb && !dbWasExplicitlyConfigured)(
-  hasTestDb || dbWasExplicitlyConfigured
-    ? "stdio transport: real MCP client"
-    : `stdio transport: real MCP client [skipped: ${skipReason}]`,
+const shouldSkip = (!hasTestDb && !dbWasExplicitlyConfigured) || schemaMismatch || invalidTestDb;
+
+describe.skipIf(shouldSkip)(
+  shouldSkip ? `stdio transport: real MCP client [skipped: ${skipReason}]` : "stdio transport: real MCP client",
   () => {
   let client: Client | undefined;
 

package/src/paths.ts

@@ -89,8 +89,11 @@ export function detectMode(srcDir: string): InvocationMode {
  * Bump history:
  *   v5 — added `db_meta` key/value table for release-tag provenance and
  *        atomic-download / version-pinned-URL update flow (2026-04-21).
+ *   v6 — added `pages.rosetta_id` (TEXT, unique-when-not-null) for
+ *        Docusaurus-sourced pages extracted by extract-docusaurus.ts; legacy
+ *        Confluence-sourced rows keep NULL (2026-07-07, T-0035).
  */
-export const SCHEMA_VERSION = 5;
+export const SCHEMA_VERSION = 6;
 
 /**
  * Resolve the version string.

package/src/release.test.ts

@@ -28,8 +28,11 @@ function mustIndex(haystack: string, needle: string): number {
 describe("package.json", () => {
   const pkg = JSON.parse(readText("package.json"));
 
-  test("version is valid semver", () => {
-    expect(pkg.version).toMatch(/^\d+\.\d+\.\d+$/);
+  test("version is valid semver, optionally with an alpha/beta/rc prerelease channel suffix", () => {
+    // release.yml's "Determine npm release channel" step reads this committed
+    // value as the single source of truth: a bare MAJOR.MINOR.PATCH means
+    // latest, a -<stage> or -<stage>.N suffix means a prerelease dist-tag.
+    expect(pkg.version).toMatch(/^\d+\.\d+\.\d+(-(alpha|beta|rc)(\.\d+)?)?$/);
   });
 
   test("name is @tikoci/rosetta", () => {
@@ -362,6 +365,32 @@ describe("Makefile", () => {
     expect(makefile).toMatch(/^extract-full:.*extract-dude-from-cache/m);
   });
 
+  test("has extract-docusaurus and extract-docusaurus-from-cache targets", () => {
+    expect(makefile).toContain("extract-docusaurus:");
+    expect(makefile).toContain("extract-docusaurus-from-cache:");
+  });
+
+  test("extract-docusaurus is in PHONY", () => {
+    const phonyStart = makefile.indexOf(".PHONY:");
+    const phonyEnd = makefile.indexOf("\n\n", phonyStart);
+    const phonyBlock = makefile.slice(phonyStart, phonyEnd);
+    expect(phonyBlock).toContain("extract-docusaurus");
+  });
+
+  test("extract/extract-full use extract-docusaurus, not the legacy Confluence pipeline", () => {
+    // T-0035: extract-docusaurus.ts replaces extract-html.ts's role in the default
+    // pipeline. extract-html.ts survives only via extract-legacy-confluence, for
+    // rebuilding historical pre-migration release DBs (DESIGN.md).
+    expect(makefile).toMatch(/^extract: extract-docusaurus\b/m);
+    expect(makefile).toMatch(/^extract-full: extract-docusaurus\b/m);
+    expect(makefile).not.toMatch(/^extract:.*extract-html\b/m);
+    expect(makefile).not.toMatch(/^extract-full:.*extract-html\b/m);
+  });
+
+  test("has extract-legacy-confluence target wrapping extract-html + extract-properties", () => {
+    expect(makefile).toMatch(/^extract-legacy-confluence:.*extract-html.*extract-properties/m);
+  });
+
   test("preflight checks dirty tree", () => {
     expect(makefile).toContain("git diff --quiet");
   });
@@ -380,22 +409,181 @@ describe("release.yml", () => {
 
   test("has required inputs", () => {
     const src = readText(".github/workflows/release.yml");
-    expect(src).toContain("html_url:");
+    expect(src).not.toContain("html_url:");
+    expect(src).not.toContain("extract-html.ts");
+    expect(src).not.toContain("extract-properties.ts");
     expect(src).toContain("version:");
     expect(src).toContain("republish_assets:");
     expect(src).not.toContain("inputs.force");
   });
 
-  test("tolerates Confluence zip with absolute path root entry", () => {
+  describe("npm prerelease channel", () => {
+    const src = readText(".github/workflows/release.yml");
+    const channelIdx = mustIndex(src, "Determine npm release channel");
+    const changelogGateIdx = mustIndex(
+      src,
+      "Verify CHANGELOG promotion for latest-channel release",
+    );
+    const preflightIdx = mustIndex(src, "Verify npm publish access");
+    const resolveVersionIdx = mustIndex(src, "Resolve release version");
+    const installIdx = mustIndex(src, "bun install");
+
+    test("channel detection runs before any preflight/publish step reads package.json's version", () => {
+      expect(installIdx).toBeLessThan(channelIdx);
+      expect(channelIdx).toBeLessThan(changelogGateIdx);
+      expect(channelIdx).toBeLessThan(preflightIdx);
+      expect(channelIdx).toBeLessThan(resolveVersionIdx);
+    });
+
+    test("parses a MAJOR.MINOR.PATCH-<stage> or -<stage>.N package.json version into channel/stage outputs", () => {
+      const channelBlock = src.slice(channelIdx, changelogGateIdx);
+      expect(channelBlock).toContain(
+        "^([0-9]+\\.[0-9]+\\.[0-9]+)-([A-Za-z]+)(\\.[0-9]+)?$",
+      );
+      expect(channelBlock).toContain("channel=prerelease");
+      expect(channelBlock).toContain("channel=latest");
+      expect(channelBlock).toContain("stage=$STAGE");
+    });
+
+    test("validates the parsed stage against the alpha/beta/rc allowlist, not arbitrary strings", () => {
+      const channelBlock = src.slice(channelIdx, changelogGateIdx);
+      expect(channelBlock).toContain("alpha|beta|rc) ;;");
+      expect(channelBlock).toMatch(/::error::Unrecognized prerelease stage/);
+      expect(channelBlock).toContain("exit 1");
+    });
+
+    test("a version matching neither the prerelease nor the bare-semver shape fails loudly instead of silently falling through to latest", () => {
+      const channelBlock = src.slice(channelIdx, changelogGateIdx);
+      // Bare-latest branch must be gated on a strict semver regex, not a bare `else`
+      // catch-all — otherwise a typo'd prerelease shape (e.g. "0.11.0-alpha1" with
+      // no separator, or a 4-part version) would silently publish as `latest`.
+      expect(channelBlock).toMatch(
+        /elif \[\[ "\$PKG_VERSION" =~ \^\[0-9\]\+\\\.\[0-9\]\+\\\.\[0-9\]\+\$ \]\]; then/,
+      );
+      expect(channelBlock).toMatch(
+        /::error::package\.json version '\$PKG_VERSION' doesn't match a recognized shape/,
+      );
+    });
+
+    test("rewrites package.json's version in-place with a run-number suffix for prerelease, workspace-only (not committed)", () => {
+      const channelBlock = src.slice(channelIdx, changelogGateIdx);
+      expect(channelBlock).toContain(`\${BASE}-\${STAGE}.\${GITHUB_RUN_NUMBER}`);
+      expect(channelBlock).toContain("fs.writeFileSync('package.json'");
+      expect(channelBlock).not.toContain("git add package.json");
+      expect(channelBlock).not.toContain("git commit");
+    });
+
+    test("republish_assets: true skips the package.json rewrite and requires an exact inputs.version for prerelease republishes", () => {
+      const channelBlock = src.slice(channelIdx, changelogGateIdx);
+      expect(channelBlock).toMatch(/if \[ "\$REPUBLISH_ASSETS" = "true" \]/);
+      expect(channelBlock).toMatch(
+        /republish_assets=true with a prerelease package\.json version.*requires inputs\.version/,
+      );
+      expect(channelBlock).toContain(
+        "package.json version left as committed",
+      );
+    });
+
+    test("republish_assets and version inputs are read via env:, not interpolated directly into the shell script (template-injection guard)", () => {
+      const channelBlock = src.slice(channelIdx, changelogGateIdx);
+      expect(channelBlock).toContain(`REPUBLISH_ASSETS: \${{ inputs.republish_assets }}`);
+      expect(channelBlock).toContain(`INPUT_VERSION: \${{ inputs.version }}`);
+      expect(channelBlock).not.toMatch(/\[ .*"\$\{\{ inputs\./);
+    });
+
+    test("latest-channel CHANGELOG gate fails without a matching [<version>] heading, skips for prerelease and republish", () => {
+      const gateIdx2 = mustIndex(src, "Verify npm publish access");
+      const gateBlock = src.slice(changelogGateIdx, gateIdx2);
+      expect(gateBlock).toContain('if: inputs.republish_assets != true');
+      expect(gateBlock).toContain('steps.channel.outputs.channel');
+      expect(gateBlock).toContain('grep -qF "## [$PKG_VERSION]" CHANGELOG.md');
+      expect(gateBlock).toMatch(/::error::CHANGELOG\.md has no/);
+    });
+
+    test("npm publish uses --tag <stage> for prerelease and adds a next dist-tag; latest is unchanged bare publish", () => {
+      const publishIdx = mustIndex(src, "Publish to npm");
+      const bunxSmokeIdx = mustIndex(src, "bunx-smoke:");
+      const publishBlock = src.slice(publishIdx, bunxSmokeIdx);
+      expect(publishBlock).toContain(
+        `npm publish --access public --tag "\${{ steps.channel.outputs.stage }}"`,
+      );
+      // Reads PKG_NAME from package.json dynamically rather than hardcoding
+      // the package name, so a rename can't silently drift out of sync.
+      expect(publishBlock).toContain(
+        "PKG_NAME=$(node -p \"require('./package.json').name\")",
+      );
+      expect(publishBlock).toContain(
+        `npm dist-tag add "\${PKG_NAME}@\${NPM_VERSION}" next`,
+      );
+      expect(publishBlock).toContain(
+        "npm publish --access public --registry https://registry.npmjs.org/",
+      );
+    });
+
+    test("OCI tags align with npm scheme: version+sha always, floating stage/next for prerelease, latest only for latest channel, republish never moves floating tags", () => {
+      const ociIdx = mustIndex(src, "Build and push OCI images");
+      const smokeIdx = mustIndex(src, "Smoke test published OCI images");
+      const ociBlock = src.slice(ociIdx, smokeIdx);
+      expect(ociBlock).toContain(`tags+=(--tag "\${registry}:\${VERSION}" --tag "\${registry}:sha-\${SHORT_SHA}")`);
+      expect(ociBlock).toContain(`tags+=(--tag "\${registry}:\${STAGE}" --tag "\${registry}:next")`);
+      expect(ociBlock).toContain(`tags+=(--tag "\${registry}:latest")`);
+      // republish_assets is read via env: (template-injection guard), not
+      // interpolated directly into the `if [ ... ]` shell test.
+      expect(ociBlock).toContain(`REPUBLISH_ASSETS: \${{ inputs.republish_assets }}`);
+      expect(ociBlock).toMatch(/if \[ "\$REPUBLISH_ASSETS" != "true" \]/);
+    });
+
+    test("GitHub Release is created with --prerelease for prerelease channel runs", () => {
+      const releaseIdx = mustIndex(src, "Create or update GitHub Release");
+      const publishIdx = mustIndex(src, "Publish to npm");
+      const releaseBlock = src.slice(releaseIdx, publishIdx);
+      expect(releaseBlock).toContain("PRERELEASE_FLAGS=(--prerelease)");
+      expect(releaseBlock).toContain('steps.channel.outputs.channel');
+      expect(releaseBlock).toContain(`"\${PRERELEASE_FLAGS[@]}"`);
+    });
+
+    test("docs_date and republish_assets inputs are read via env: in the GitHub Release step (template-injection guard)", () => {
+      const releaseIdx = mustIndex(src, "Create or update GitHub Release");
+      const publishIdx = mustIndex(src, "Publish to npm");
+      const releaseBlock = src.slice(releaseIdx, publishIdx);
+      expect(releaseBlock).toContain(`DOCS_DATE: \${{ inputs.docs_date }}`);
+      expect(releaseBlock).toContain(`REPUBLISH_ASSETS: \${{ inputs.republish_assets }}`);
+      expect(releaseBlock).toMatch(/if \[ "\$REPUBLISH_ASSETS" = "true" \]/);
+      expect(releaseBlock).not.toContain(`DOCS_DATE="\${{ inputs.docs_date }}"`);
+    });
+  });
+
+  test("runs test coverage in release CI and uploads it as a workflow artifact", () => {
+    const src = readText(".github/workflows/release.yml");
+    const fastFailIdx = mustIndex(src, "Run tests (fast-fail)");
+    const buildxIdx = mustIndex(src, "Set up Docker Buildx");
+    const coverageBlock = src.slice(fastFailIdx, buildxIdx);
+
+    expect(coverageBlock).toContain("bun test --coverage");
+    expect(coverageBlock).toContain("--coverage-reporter=lcov");
+    expect(coverageBlock).toContain("## Test coverage");
+    expect(coverageBlock).toContain("Upload coverage artifact");
+    expect(coverageBlock).toContain("coverage/lcov.info");
+  });
+
+  test("coverage step always closes its summary code fence, even when bun test fails (PIPESTATUS, not implicit pipefail)", () => {
     const src = readText(".github/workflows/release.yml");
-    // Confluence exports include a bare "/" entry → unzip exits 2
-    expect(src).toMatch(/unzip.*\|\|.*\$\?.*-eq.*2/);
+    const fastFailIdx = mustIndex(src, "Run tests (fast-fail)");
+    const uploadIdx = mustIndex(src, "Upload coverage artifact");
+    const coverageBlock = src.slice(fastFailIdx, uploadIdx);
+
+    expect(coverageBlock).toContain("set +e");
+    const statusIdx = mustIndex(coverageBlock, `status=\${PIPESTATUS[0]}`);
+    const closeFenceIdx = coverageBlock.lastIndexOf("echo '```'");
+    const exitIdx = mustIndex(coverageBlock, 'exit "$status"');
+
+    expect(statusIdx).toBeLessThan(closeFenceIdx);
+    expect(closeFenceIdx).toBeLessThan(exitIdx);
   });
 
   test("runs extraction pipeline", () => {
     const src = readText(".github/workflows/release.yml");
-    expect(src).toContain("extract-html.ts");
-    expect(src).toContain("extract-properties.ts");
+    expect(src).toContain("extract-docusaurus.ts");
     expect(src).toContain("extract-commands.ts");
     expect(src).toContain("extract-devices.ts");
     expect(src).toContain("extract-test-results.ts");
@@ -404,6 +592,15 @@ describe("release.yml", () => {
     expect(src).toContain("link-commands.ts");
   });
 
+  test("Docusaurus extraction step proves the docs-count invariant, not just a manual/local run", () => {
+    const src = readText(".github/workflows/release.yml");
+    const extractIdx = mustIndex(src, "Extract Docusaurus pages, properties, callouts");
+    const commandTreeIdx = mustIndex(src, "Extract command tree");
+    const extractBlock = src.slice(extractIdx, commandTreeIdx);
+
+    expect(extractBlock).toContain("extract-docusaurus.ts --check-counts --strict");
+  });
+
   test("imports Dude wiki from cache", () => {
     const src = readText(".github/workflows/release.yml");
     expect(src).toContain("extract-dude-from-cache");
@@ -428,30 +625,30 @@ describe("release.yml", () => {
     expect(src).toContain("bun run lint");
   });
 
-  test("runs early quality gate before downloading HTML export", () => {
+  test("runs early quality gate before Docusaurus extraction", () => {
     const src = readText(".github/workflows/release.yml");
     const installIdx = mustIndex(src, "bun install");
     const typecheckIdx = mustIndex(src, "Type check (fast-fail)");
     const lintIdx = mustIndex(src, "Lint (fast-fail)");
     const earlyTestIdx = mustIndex(src, "Run tests (fast-fail)");
-    const downloadIdx = mustIndex(src, "Download HTML export");
+    const extractIdx = mustIndex(src, "Extract Docusaurus pages, properties, callouts");
 
     expect(installIdx).toBeLessThan(typecheckIdx);
     expect(typecheckIdx).toBeLessThan(lintIdx);
     expect(lintIdx).toBeLessThan(earlyTestIdx);
-    expect(earlyTestIdx).toBeLessThan(downloadIdx);
+    expect(earlyTestIdx).toBeLessThan(extractIdx);
   });
 
   test("preflights npm publish access before release side effects", () => {
     const src = readText(".github/workflows/release.yml");
     const preflightIdx = mustIndex(src, "Verify npm publish access");
-    const downloadIdx = mustIndex(src, "Download HTML export");
+    const extractIdx = mustIndex(src, "Extract Docusaurus pages, properties, callouts");
     const ociIdx = mustIndex(src, "Build and push OCI images");
     const releaseIdx = mustIndex(src, "Create or update GitHub Release");
     const publishIdx = mustIndex(src, "Publish to npm");
-    const preflightBlock = src.slice(preflightIdx, downloadIdx);
+    const preflightBlock = src.slice(preflightIdx, extractIdx);
 
-    expect(preflightIdx).toBeLessThan(downloadIdx);
+    expect(preflightIdx).toBeLessThan(extractIdx);
     expect(preflightIdx).toBeLessThan(ociIdx);
     expect(preflightIdx).toBeLessThan(releaseIdx);
     expect(preflightIdx).toBeLessThan(publishIdx);
@@ -529,8 +726,10 @@ describe("release.yml", () => {
     expect(src).not.toContain("inputs.force");
     expect(src).not.toContain("force=true");
 
+    // republish_assets is read via an env-mapped $REPUBLISH_ASSETS, not
+    // interpolated directly into the shell script (template-injection guard).
     const republishBranchIdx = src.search(
-      /if \[ "\$\{\{ inputs\.republish_assets \}\}" = "true" \]; then/,
+      /if \[ "\$REPUBLISH_ASSETS" = "true" \]; then/,
     );
     expect(republishBranchIdx).toBeGreaterThanOrEqual(0);
     const clobberIdx = mustIndex(src, "gh release upload");
@@ -547,25 +746,14 @@ describe("release.yml", () => {
     expect(src).toMatch(
       /bunx-smoke:[\s\S]{0,120}if: inputs\.republish_assets != true/,
     );
-    expect(src).toMatch(
-      /bump-version:[\s\S]{0,120}if: inputs\.republish_assets != true/,
-    );
   });
 
-  test("bump-version fetches and rebases before retrying push", () => {
+  test("bump-version job and its auto-commit are gone entirely — version bumps are a manual step for every channel", () => {
     const src = readText(".github/workflows/release.yml");
-    const bumpIdx = mustIndex(src, "bump-version:");
-    const bumpBlock = src.slice(bumpIdx);
-    const loopIdx = mustIndex(bumpBlock, "for attempt in 1 2 3; do");
-    const fetchIdx = mustIndex(bumpBlock, "git fetch origin main");
-    const rebaseIdx = mustIndex(bumpBlock, "git rebase origin/main");
-    const pushIdx = mustIndex(bumpBlock, "git push origin HEAD:main");
-    const retryIdx = mustIndex(bumpBlock, "Push rejected on attempt");
-
-    expect(loopIdx).toBeLessThan(fetchIdx);
-    expect(fetchIdx).toBeLessThan(rebaseIdx);
-    expect(rebaseIdx).toBeLessThan(pushIdx);
-    expect(pushIdx).toBeLessThan(retryIdx);
+    expect(src).not.toContain("bump-version:");
+    expect(src).not.toContain("git push origin HEAD:main");
+    expect(src).not.toContain("Bumped version:");
+    expect(src).not.toContain("Promoted [Unreleased]");
   });
 
   test("publishes to npm", () => {
@@ -577,8 +765,7 @@ describe("release.yml", () => {
   test("bunx-smoke covers windows with bash steps and a runner temp log", () => {
     const src = readText(".github/workflows/release.yml");
     const bunxIdx = mustIndex(src, "bunx-smoke:");
-    const bumpIdx = mustIndex(src, "bump-version:");
-    const bunxBlock = src.slice(bunxIdx, bumpIdx);
+    const bunxBlock = src.slice(bunxIdx);
 
     expect(bunxBlock).toContain("windows-latest");
     expect(bunxBlock).toContain("shell: bash");

package/src/restraml.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = join(import.meta.dirname, "..");
+
+function readText(relPath: string): string {
+  return readFileSync(join(ROOT, relPath), "utf-8");
+}
+
+describe("restraml GitHub version discovery", () => {
+  test("uses authenticated GitHub helper for API version discovery", () => {
+    const src = readText("src/restraml.ts");
+
+    expect(src).toContain('from "./github.ts"');
+    expect(src).toContain("fetchGitHub(RESTRAML_API_CONTENTS_URL");
+    expect(src).toContain("headers: githubApiHeaders()");
+  });
+
+  test("release.yml passes GITHUB_TOKEN to extract-all-versions", () => {
+    const yml = readText(".github/workflows/release.yml");
+    const commandIdx = yml.indexOf("Extract command tree");
+    const devicesIdx = yml.indexOf("Extract devices");
+    expect(commandIdx).toBeGreaterThanOrEqual(0);
+    expect(devicesIdx).toBeGreaterThan(commandIdx);
+
+    const block = yml.slice(commandIdx, devicesIdx);
+    expect(block).toContain("GITHUB_TOKEN: $" + "{{ github.token }}");
+    expect(block).toContain("bun run src/extract-all-versions.ts");
+  });
+});