@tikoci/rosetta 0.8.12 → 0.9.1

package/matrix/CLAUDE.md

@@ -2,6 +2,6 @@
 
 Per-device hardware specs from mikrotik.com/products/matrix. Date-stamped snapshots stored in git.
 
-See main [CLAUDE.md](../CLAUDE.md) → "Product Matrix (CSV)" under Source Details for full schema, download instructions, and column documentation.
+See [DESIGN.md](../DESIGN.md) for product-matrix provenance and naming caveats, and [MANUAL.md](../MANUAL.md) for the re-extraction workflow.
 
-Extraction: `bun run src/extract-devices.ts` (or `make extract-devices`). Idempotent — deletes and re-inserts all rows.
+Extraction: `bun run src/extract-devices.ts` (or `make extract-devices`). Idempotent — deletes and re-inserts all rows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/rosetta",
-  "version": "0.8.12",
+  "version": "0.9.1",
   "description": "RouterOS documentation as SQLite FTS5 — RAG search + command glossary via MCP",
   "type": "module",
   "license": "MIT",

package/src/browse-parity.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { EXPECTED_TOOLS } from "./mcp-contract.test.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 parity check.`;
+
+function stripAnsi(s: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape matching requires control chars
+  return s.replace(/\x1b\][^\x07]*\x07/g, "").replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function runBrowseHelp(): string {
+  if (!existsSync(DB_PATH)) {
+    throw new Error(`Expected populated test database at ${DB_PATH}.`);
+  }
+
+  const proc = Bun.spawnSync(["bun", "src/browse.ts", "--once", ".help"], {
+    cwd: ROOT,
+    env: { ...process.env, DB_PATH },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (proc.exitCode !== 0) {
+    throw new Error(
+      `browse --once .help failed (exit ${proc.exitCode})\nstdout:\n${proc.stdout.toString()}\n\nstderr:\n${proc.stderr.toString()}`,
+    );
+  }
+
+  return proc.stdout.toString();
+}
+
+function extractToolDotCommands(helpOutput: string): string[] {
+  const seen = new Set<string>();
+  for (const line of stripAnsi(helpOutput).split("\n")) {
+    const match = line.match(/^\s*\.(routeros_[a-z_]+)\b/);
+    if (match) seen.add(match[1]);
+  }
+  return [...seen].sort();
+}
+
+describe.skipIf(!hasTestDb && !dbWasExplicitlyConfigured)(
+  hasTestDb || dbWasExplicitlyConfigured
+    ? "browse TUI ↔ MCP parity"
+    : `browse TUI ↔ MCP parity [skipped: ${skipReason}]`,
+  () => {
+  test("browse .help lists a dot-command for every MCP tool", () => {
+    const actual = extractToolDotCommands(runBrowseHelp());
+    expect(actual).toEqual([...EXPECTED_TOOLS].sort());
+  });
+});

package/src/cli-help.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const ROOT = path.resolve(import.meta.dirname, "..");
+const INTENTIONAL_OMISSIONS = new Set<string>();
+
+function readText(relPath: string): string {
+  return readFileSync(path.join(ROOT, relPath), "utf-8");
+}
+
+function normalizeEntry(value: string): string {
+  const trimmed = value.trim().replace(/^`|`$/g, "");
+  return trimmed === "*(none)*" ? "(none)" : trimmed;
+}
+
+function readManualCliFlags(): string[] {
+  const manual = readText("MANUAL.md");
+  const sectionMatch = manual.match(/## CLI Flags\n\n([\s\S]*?)\n## /);
+  if (!sectionMatch) {
+    throw new Error("Could not locate CLI Flags table in MANUAL.md.");
+  }
+
+  const entries = new Set<string>();
+  for (const line of sectionMatch[1].split("\n")) {
+    if (!line.startsWith("|")) continue;
+    const cells = line.split("|").map((cell) => cell.trim()).filter(Boolean);
+    if (cells.length < 2) continue;
+    if (cells[0] === "Flag" || /^-+$/.test(cells[0])) continue;
+    entries.add(normalizeEntry(cells[0]));
+  }
+  return [...entries].sort();
+}
+
+function runHelp(): string {
+  const proc = Bun.spawnSync(["bun", "src/mcp.ts", "--help"], {
+    cwd: ROOT,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (proc.exitCode !== 0) {
+    throw new Error(
+      `src/mcp.ts --help failed (exit ${proc.exitCode})\nstdout:\n${proc.stdout.toString()}\n\nstderr:\n${proc.stderr.toString()}`,
+    );
+  }
+
+  return proc.stdout.toString();
+}
+
+function readHelpCliEntries(helpText: string): string[] {
+  const entries = new Set<string>();
+
+  for (const line of helpText.split("\n")) {
+    const usageMatch = line.match(/^\s*rosetta(?:\s+(.*?))?\s{2,}\S/);
+    if (usageMatch) {
+      const command = usageMatch[1]?.trim() ?? "";
+      entries.add(command === "" ? "(none)" : command);
+      continue;
+    }
+
+    const optionMatch = line.match(/^\s*(--[a-z-]+(?: <[^>]+>)?)\s{2,}\S/);
+    if (optionMatch) {
+      entries.add(optionMatch[1]);
+    }
+  }
+
+  return [...entries].sort();
+}
+
+describe("CLI help ↔ MANUAL flag parity", () => {
+  test("MANUAL CLI Flags table matches src/mcp.ts --help", () => {
+    const documented = readManualCliFlags().filter((entry) => !INTENTIONAL_OMISSIONS.has(entry));
+    const fromHelp = readHelpCliEntries(runHelp()).filter((entry) => !INTENTIONAL_OMISSIONS.has(entry));
+
+    expect(fromHelp).toEqual(documented);
+  });
+});

package/src/extract-skills.test.ts

@@ -0,0 +1,39 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+process.env.DB_PATH = ":memory:";
+
+const { githubApiHeaders } = await import("./extract-skills.ts");
+
+describe("extract-skills GitHub API headers", () => {
+  afterEach(() => {
+    delete process.env.GITHUB_TOKEN;
+    delete process.env.GH_TOKEN;
+  });
+
+  test("keeps unauthenticated headers when no token is configured", () => {
+    delete process.env.GITHUB_TOKEN;
+    delete process.env.GH_TOKEN;
+
+    expect(githubApiHeaders()).toEqual({
+      Accept: "application/vnd.github.v3+json",
+    });
+  });
+
+  test("uses GITHUB_TOKEN for authenticated API requests", () => {
+    process.env.GITHUB_TOKEN = "test-token";
+
+    expect(githubApiHeaders()).toEqual({
+      Accept: "application/vnd.github.v3+json",
+      Authorization: "Bearer test-token",
+    });
+  });
+
+  test("falls back to GH_TOKEN for local authenticated runs", () => {
+    process.env.GH_TOKEN = "gh-token";
+
+    expect(githubApiHeaders()).toEqual({
+      Accept: "application/vnd.github.v3+json",
+      Authorization: "Bearer gh-token",
+    });
+  });
+});

package/src/extract-skills.ts

@@ -70,9 +70,16 @@ 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`, {
-    headers: { Accept: "application/vnd.github.v3+json" },
+    headers: githubApiHeaders(),
   });
   if (!res.ok) throw new Error(`Failed to get HEAD SHA: HTTP ${res.status}`);
   const data = (await res.json()) as { sha: string };
@@ -81,7 +88,7 @@ async function getDefaultBranchSha(): Promise<string> {
 
 async function listSkillDirs(sha: string): Promise<string[]> {
   const res = await fetch(`${GITHUB_API_BASE}/contents/?ref=${sha}`, {
-    headers: { Accept: "application/vnd.github.v3+json" },
+    headers: githubApiHeaders(),
   });
   if (!res.ok) throw new Error(`Failed to list repo contents: HTTP ${res.status}`);
   const entries = (await res.json()) as Array<{ name: string; type: string }>;
@@ -102,7 +109,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}`, {
-    headers: { Accept: "application/vnd.github.v3+json" },
+    headers: githubApiHeaders(),
   });
   if (!res.ok) {
     if (res.status === 404) return [];
@@ -387,4 +394,6 @@ async function main() {
   populateDb(skills, sha);
 }
 
-await main();
+if (import.meta.main) {
+  await main();
+}

package/src/mcp-contract.test.ts

@@ -9,7 +9,8 @@
  *           and titles so DB refreshes don't churn snapshots.
  *
  * These are fast, deterministic, CI-runnable structural tests. No LLM calls,
- * no network. Use the real local DB (ros-help.db) for stable FTS results.
+ * no network. Block A always runs; set ROSETTA_REAL_DB_TESTS=1 to exercise
+ * Blocks B/C against a real populated DB for stable FTS results.
  *
  * When adding/removing/renaming a tool: update EXPECTED_TOOLS below AND add
  * a CHANGELOG entry under [Unreleased] → Added/Changed/Removed. The test is
@@ -20,52 +21,67 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 
 const ROOT = path.resolve(import.meta.dirname, "..");
+const runRealDbBlocks = process.env.ROSETTA_REAL_DB_TESTS === "1";
 
 // Block A (static file parse) runs unconditionally. Blocks B and C need the
-// real populated DB singleton. When another test file (extract-videos,
-// query, etc.) has already pinned the db.ts singleton to :memory:, we skip
-// the DB-dependent blocks — running `bun test src/mcp-contract.test.ts`
-// alone exercises them, and CI's `bun test` still gets Block A coverage.
-const { searchAll } = await import("./query.ts");
-const { DB_PATH, getDbStats } = await import("./db.ts");
-
-// getDbStats() throws if tables don't exist (clean checkout before any DB build).
-// Guard defensively: any failure → treat as "DB not usable" and skip B/C.
-function dbPagesOrZero(): number {
+// real populated DB singleton, but opening db.ts during the main `bun test`
+// suite can poison query.test.ts's DB-wipe guard. Keep the real-DB imports
+// behind an explicit opt-in so the shared suite stays on `:memory:` and the
+// dedicated release/real-DB runs can still exercise Blocks B/C.
+let searchAll: typeof import("./query.ts").searchAll | undefined;
+let realDbPath = ":memory:";
+let dbPages = 0;
+
+if (runRealDbBlocks) {
+  const queryModule = await import("./query.ts");
+  const dbModule = await import("./db.ts");
+  searchAll = queryModule.searchAll;
+  realDbPath = dbModule.DB_PATH;
   try {
-    return getDbStats().pages;
+    dbPages = dbModule.getDbStats().pages;
   } catch {
-    return 0;
+    dbPages = 0;
   }
 }
 
-const dbPages = dbPagesOrZero();
-const dbIsReal = DB_PATH !== ":memory:" && dbPages > 100;
+function requireSearchAll(): typeof import("./query.ts").searchAll {
+  if (!searchAll) {
+    throw new Error(
+      "searchAll unavailable; set ROSETTA_REAL_DB_TESTS=1 to enable real-DB contract blocks.",
+    );
+  }
+  return searchAll;
+}
+
+const dbIsReal = runRealDbBlocks && realDbPath !== ":memory:" && dbPages > 100;
 const skipReason = dbIsReal
   ? ""
-  : `DB singleton is "${DB_PATH}" (pages=${dbPages}); run \`bun test src/mcp-contract.test.ts\` solo against a populated DB for Blocks B/C.`;
+  : runRealDbBlocks
+    ? `DB singleton is "${realDbPath}" (pages=${dbPages}); run \`ROSETTA_REAL_DB_TESTS=1 bun test src/mcp-contract.test.ts\` against a populated DB for Blocks B/C.`
+    : "real-DB blocks are opt-in; set ROSETTA_REAL_DB_TESTS=1 and run this file against a populated DB for Blocks B/C.";
 
 // ---------------------------------------------------------------------------
 // Block A: Frozen tool registry
 // ---------------------------------------------------------------------------
 
+export const EXPECTED_TOOLS = [
+  "routeros_search",
+  "routeros_get_page",
+  "routeros_lookup_property",
+  "routeros_explain_command",
+  "routeros_command_tree",
+  "routeros_stats",
+  "routeros_search_changelogs",
+  "routeros_dude_search",
+  "routeros_dude_get_page",
+  "routeros_command_version_check",
+  "routeros_command_diff",
+  "routeros_device_lookup",
+  "routeros_search_tests",
+  "routeros_current_versions",
+] as const;
+
 describe("Frozen tool registry", () => {
-  const EXPECTED_TOOLS = [
-    "routeros_search",
-    "routeros_get_page",
-    "routeros_lookup_property",
-    "routeros_explain_command",
-    "routeros_command_tree",
-    "routeros_stats",
-    "routeros_search_changelogs",
-    "routeros_dude_search",
-    "routeros_dude_get_page",
-    "routeros_command_version_check",
-    "routeros_command_diff",
-    "routeros_device_lookup",
-    "routeros_search_tests",
-    "routeros_current_versions",
-  ];
 
   test("exactly 14 tools registered", () => {
     const mcpSrc = readFileSync(path.join(ROOT, "src/mcp.ts"), "utf-8");
@@ -74,7 +90,7 @@ describe("Frozen tool registry", () => {
     const foundTools = Array.from(toolMatches, (m) => m[1]);
 
     expect(foundTools.length).toBe(14);
-    expect(foundTools.sort()).toEqual(EXPECTED_TOOLS.sort());
+    expect(foundTools.sort()).toEqual([...EXPECTED_TOOLS].sort());
   });
 
   test("all tools have workflow arrow (→) in description", () => {
@@ -156,7 +172,7 @@ describe.skipIf(!dbIsReal)(`Token-budget guardrails${dbIsReal ? "" : ` [skipped:
 
   for (const { query, limit, budget } of QUERIES) {
     test(`"${query}" (limit=${limit}) ≤ ${budget} tokens`, () => {
-      const result = searchAll(query, limit);
+      const result = requireSearchAll()(query, limit);
       const tokens = estimateTokens(result);
 
       if (tokens > budget) {
@@ -216,7 +232,7 @@ describe.skipIf(!dbIsReal)(`Response-shape invariants${dbIsReal ? "" : ` [skippe
 
   for (const { query, limit, classifier_expected } of INVARIANTS) {
     test(`shape: "${query}"`, () => {
-      const result = searchAll(query, limit);
+      const result = requireSearchAll()(query, limit);
 
       // Top-level keys
       expect(result).toHaveProperty("query", query);

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

@@ -0,0 +1,170 @@
+/**
+ * mcp-stdio-client.test.ts — Integration test for the real MCP stdio path.
+ *
+ * Spawns `bun src/mcp.ts` via the SDK's StdioClientTransport and exercises the
+ * real client handshake, tool listing, tool calling, resource listing, and
+ * shutdown flow. This catches stdout pollution and JSON-RPC framing bugs that
+ * in-process tests cannot.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+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.`;
+
+const EXPECTED_TOOLS = [
+  "routeros_search",
+  "routeros_get_page",
+  "routeros_lookup_property",
+  "routeros_explain_command",
+  "routeros_command_tree",
+  "routeros_stats",
+  "routeros_search_changelogs",
+  "routeros_dude_search",
+  "routeros_dude_get_page",
+  "routeros_command_version_check",
+  "routeros_command_diff",
+  "routeros_device_lookup",
+  "routeros_search_tests",
+  "routeros_current_versions",
+];
+
+const FIXED_RESOURCE_URIS = [
+  "rosetta://datasets/device-test-results.csv",
+  "rosetta://datasets/devices.csv",
+  "rosetta://schema-guide.md",
+  "rosetta://schema.sql",
+  "rosetta://skills",
+];
+
+function asRecord(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Expected ${label} to be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function parseJsonToolResult(value: unknown): Record<string, unknown> {
+  const result = asRecord(value, "tool result");
+  if (!Array.isArray(result.content) || result.content.length === 0) {
+    throw new Error("Expected tool result content[0] to exist.");
+  }
+
+  const firstContent = asRecord(result.content[0], "tool result content[0]");
+  if (firstContent.type !== "text" || typeof firstContent.text !== "string") {
+    throw new Error("Expected tool result content[0] to be text.");
+  }
+
+  return asRecord(JSON.parse(firstContent.text), "parsed tool JSON");
+}
+
+function buildDiagnostics(errors: Error[], stderr: string[]): string {
+  const sections: string[] = [];
+  if (errors.length > 0) {
+    sections.push(`transport/client errors:\n${errors.map((error) => error.stack ?? error.message).join("\n\n")}`);
+  }
+  if (stderr.length > 0) {
+    sections.push(`server stderr:\n${stderr.join("")}`);
+  }
+  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}]`,
+  () => {
+  let client: Client | undefined;
+
+  afterEach(async () => {
+    if (client) {
+      await client.close().catch(() => undefined);
+      client = undefined;
+    }
+  });
+
+  test("real stdio client lists tools, calls routeros_search, lists resources, and closes cleanly", async () => {
+    if (!hasTestDb) {
+      throw new Error(`Expected populated test database at ${DB_PATH}.`);
+    }
+
+    const transport = new StdioClientTransport({
+      command: "bun",
+      args: ["src/mcp.ts"],
+      cwd: ROOT,
+      env: { ...process.env, DB_PATH },
+      stderr: "pipe",
+    });
+
+    const stderrChunks: string[] = [];
+    transport.stderr?.on("data", (chunk) => {
+      stderrChunks.push(chunk.toString());
+    });
+
+    const transportErrors: Error[] = [];
+    let resolveClosed!: () => void;
+    const closeSeen = new Promise<void>((resolve) => {
+      resolveClosed = resolve;
+    });
+    let closeCount = 0;
+
+    client = new Client({ name: "stdio-test-client", version: "1.0.0" });
+    client.onerror = (error) => {
+      transportErrors.push(error);
+    };
+    client.onclose = () => {
+      closeCount += 1;
+      resolveClosed();
+    };
+
+    await client.connect(transport);
+    expect(client.getServerVersion()?.name).toBe("rosetta");
+
+    const tools = await client.listTools();
+    const toolNames = tools.tools.map((tool) => tool.name).sort();
+    expect(toolNames).toEqual([...EXPECTED_TOOLS].sort());
+
+    const searchPayload = parseJsonToolResult(await client.callTool({
+      name: "routeros_search",
+      arguments: { query: "/ip/firewall/filter", limit: 3 },
+    }));
+    expect(Array.isArray(searchPayload.pages)).toBe(true);
+    expect((searchPayload.pages as unknown[]).length).toBeGreaterThan(0);
+    expect(searchPayload.related).toBeDefined();
+    expect(typeof searchPayload.related).toBe("object");
+    expect(Array.isArray(searchPayload.related)).toBe(false);
+    expect(Object.keys(asRecord(searchPayload.related, "routeros_search.related")).length).toBeGreaterThan(0);
+
+    const resources = await client.listResources();
+    const fixedResourceUris = resources.resources
+      .map((resource) => resource.uri)
+      .filter((uri) => !uri.startsWith("rosetta://skills/"))
+      .sort();
+    expect(fixedResourceUris).toEqual([...FIXED_RESOURCE_URIS].sort());
+
+    if (transportErrors.length > 0) {
+      throw new Error(`Unexpected stdio transport/client error before close.${buildDiagnostics(transportErrors, stderrChunks)}`);
+    }
+
+    await client.close();
+    client = undefined;
+    await Promise.race([
+      closeSeen,
+      Bun.sleep(2_000).then(() => {
+        throw new Error(`Timed out waiting for stdio client/server close.${buildDiagnostics(transportErrors, stderrChunks)}`);
+      }),
+    ]);
+
+    expect(closeCount).toBe(1);
+    if (transportErrors.length > 0) {
+      throw new Error(`Unexpected stdio transport/client error during close.${buildDiagnostics(transportErrors, stderrChunks)}`);
+    }
+  }, 60_000);
+});

package/src/mcp.ts

@@ -139,6 +139,8 @@ if (args.includes("--help") || args.includes("-h")) {
   console.log("  rosetta              Start MCP server (stdio transport)");
   console.log("  rosetta --http       Start with Streamable HTTP transport");
   console.log("  rosetta browse       Interactive terminal browser");
+  console.log("  rosetta browse <cmd> [args]  Run any TUI command once, then open REPL");
+  console.log("  rosetta browse --once <cmd>  Execute any TUI command and exit");
   console.log("  rosetta --setup      Download database + print MCP client config");
   console.log("  rosetta --setup --force  Re-download database");
   console.log("  rosetta --refresh    Shortcut for --setup --force");
@@ -155,6 +157,8 @@ if (args.includes("--help") || args.includes("-h")) {
   console.log("  DB_PATH  Absolute path to ros-help.db (optional)");
   console.log("  PORT     HTTP listen port (lower precedence than --port)");
   console.log("  HOST     HTTP bind address (lower precedence than --host)");
+  console.log("  TLS_CERT_PATH  TLS certificate path (lower precedence than --tls-cert)");
+  console.log("  TLS_KEY_PATH   TLS private key path (lower precedence than --tls-key)");
   console.log();
   console.log(`Quick start:  bunx @tikoci/rosetta --setup`);
   console.log(`Project:      ${link("https://github.com/tikoci/rosetta")}`);

package/src/release.test.ts

@@ -288,12 +288,8 @@ describe("Makefile", () => {
     expect(makefile).toContain("preflight:");
   });
 
-  test("has build-release target", () => {
-    expect(makefile).toContain("build-release:");
-  });
-
-  test("has release target", () => {
-    expect(makefile).toContain("release:");
+  test("has verify target", () => {
+    expect(makefile).toContain("verify:");
   });
 
   test("has extract-videos target", () => {
@@ -350,12 +346,8 @@ describe("Makefile", () => {
     expect(phonyBlock).toContain("extract-dude");
   });
 
-  test("release depends on preflight", () => {
-    expect(makefile).toMatch(/^release:.*preflight/m);
-  });
-
-  test("release depends on build-release", () => {
-    expect(makefile).toMatch(/^release:.*build-release/m);
+  test("extract target includes Dude cache import", () => {
+    expect(makefile).toMatch(/^extract:.*extract-dude-from-cache/m);
   });
 
   test("extract target includes skills", () => {
@@ -366,10 +358,6 @@ describe("Makefile", () => {
     expect(makefile).toMatch(/^extract-full:.*extract-skills/m);
   });
 
-  test("extract target includes Dude cache import", () => {
-    expect(makefile).toMatch(/^extract:.*extract-dude-from-cache/m);
-  });
-
   test("extract-full target includes Dude cache import", () => {
     expect(makefile).toMatch(/^extract-full:.*extract-dude-from-cache/m);
   });
@@ -377,12 +365,6 @@ describe("Makefile", () => {
   test("preflight checks dirty tree", () => {
     expect(makefile).toContain("git diff --quiet");
   });
-
-  test("FORCE flag controls tag behavior", () => {
-    expect(makefile).toContain("FORCE");
-    expect(makefile).toContain("git tag -f");
-    expect(makefile).toContain("--clobber");
-  });
 });
 
 // ---------------------------------------------------------------------------
@@ -429,7 +411,13 @@ describe("release.yml", () => {
 
   test("extracts agent skills in CI", () => {
     const src = readText(".github/workflows/release.yml");
-    expect(src).toContain("extract-skills.ts");
+    const skillsIdx = mustIndex(src, "Extract agent skills from GitHub");
+    const linkIdx = mustIndex(src, "Link commands to pages");
+    const skillsBlock = src.slice(skillsIdx, linkIdx);
+
+    expect(skillsBlock).toContain("extract-skills.ts");
+    expect(skillsBlock).toContain("GITHUB_TOKEN");
+    expect(skillsBlock).toContain("$" + "{{ github.token }}");
   });
 
   test("runs quality gate before release", () => {
@@ -454,6 +442,26 @@ describe("release.yml", () => {
     expect(earlyTestIdx).toBeLessThan(downloadIdx);
   });
 
+  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 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);
+
+    expect(preflightIdx).toBeLessThan(downloadIdx);
+    expect(preflightIdx).toBeLessThan(ociIdx);
+    expect(preflightIdx).toBeLessThan(releaseIdx);
+    expect(preflightIdx).toBeLessThan(publishIdx);
+    expect(preflightBlock).toContain("NODE_AUTH_TOKEN");
+    expect(preflightBlock).toContain("npm whoami");
+    expect(preflightBlock).toContain("npm access list collaborators");
+    expect(preflightBlock).toContain("read-write access");
+    expect(preflightBlock).toContain("npm view");
+  });
+
   test("keeps post-extraction DB-wipe guard after extraction", () => {
     const src = readText(".github/workflows/release.yml");
     const linkIdx = mustIndex(src, "Link commands to pages");
@@ -481,13 +489,34 @@ describe("release.yml", () => {
   test("runs MCP contract tests against the real built DB before eval/release", () => {
     const src = readText(".github/workflows/release.yml");
     const contractIdx = src.indexOf("bun test src/mcp-contract.test.ts");
-    const evalIdx = src.indexOf("MCP retrieval eval (Phase 0, non-blocking)");
+    const evalIdx = src.indexOf("MCP retrieval eval (Phase 0)");
     const buildIdx = src.indexOf("Build release artifacts");
     expect(contractIdx).toBeGreaterThan(0);
     expect(contractIdx).toBeLessThan(evalIdx);
     expect(contractIdx).toBeLessThan(buildIdx);
   });
 
+  test("runs Phase 1 self-supervised eval against the built DB and appends a summary result", () => {
+    const src = readText(".github/workflows/release.yml");
+    const phase0Idx = mustIndex(src, "MCP retrieval eval (Phase 0)");
+    const phase1Idx = mustIndex(
+      src,
+      "MCP retrieval eval (Phase 1, self-supervised, non-blocking)",
+    );
+    const buildIdx = mustIndex(src, "Build release artifacts");
+    const phase1Block = src.slice(phase1Idx, buildIdx);
+
+    expect(phase1Idx).toBeGreaterThan(phase0Idx);
+    expect(phase1Idx).toBeLessThan(buildIdx);
+    expect(phase1Block).toContain("continue-on-error: true");
+    expect(phase1Block).toContain("bun run src/eval/self-supervised.ts");
+    expect(phase1Block).toContain(
+      "## Phase 1 retrieval eval (self-supervised)",
+    );
+    expect(phase1Block).toContain("Result: ✅ pass");
+    expect(phase1Block).toContain("Result: ⚠️ non-blocking failure");
+  });
+
   test("creates GitHub Release", () => {
     const src = readText(".github/workflows/release.yml");
     expect(src).toContain("gh release create");
@@ -507,6 +536,8 @@ describe("release.yml", () => {
     const clobberIdx = mustIndex(src, "gh release upload");
     expect(src.slice(clobberIdx, clobberIdx + 120)).toContain("--clobber");
     expect(republishBranchIdx).toBeLessThan(clobberIdx);
+    expect(src).toContain('elif gh release view "$VERSION"');
+    expect(src).toContain("updated before npm publish retry");
 
     expect(src).toContain("if: inputs.republish_assets != true");
     expect(src).toContain("if: inputs.republish_assets == true");
@@ -539,10 +570,22 @@ describe("release.yml", () => {
 
   test("publishes to npm", () => {
     const src = readText(".github/workflows/release.yml");
-    expect(src).toContain("npm publish");
+    expect(src).toContain("npm publish --access public --registry https://registry.npmjs.org/");
     expect(src).toContain("NPM_TOKEN");
   });
 
+  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);
+
+    expect(bunxBlock).toContain("windows-latest");
+    expect(bunxBlock).toContain("shell: bash");
+    expect(bunxBlock).toContain("RUNNER_TEMP");
+    expect(bunxBlock).not.toContain("mktemp");
+  });
+
   test("validates DB content before publishing (regression: v0.7.6 shipped 3 pages)", () => {
     const src = readText(".github/workflows/release.yml");
     // Hard guard step that hard-fails the workflow if the built DB is degenerate.
@@ -551,7 +594,7 @@ describe("release.yml", () => {
     const validateIdx = src.indexOf("Validate DB has expected content");
     const buildIdx = src.indexOf("Build release artifacts");
     const releaseIdx = src.indexOf("gh release create");
-    const npmIdx = src.indexOf("npm publish");
+    const npmIdx = src.indexOf("Publish to npm");
     expect(validateIdx).toBeGreaterThan(0);
     expect(validateIdx).toBeLessThan(buildIdx);
     expect(validateIdx).toBeLessThan(releaseIdx);