@tikoci/rosetta 0.2.0

package/src/release.test.ts

@@ -0,0 +1,280 @@
+/**
+ * release.test.ts — Release readiness tests.
+ *
+ * Validates that project files are consistent and release artifacts
+ * will be built correctly. No network, no database — just file reads
+ * and structural checks.
+ */
+import { describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+const ROOT = path.resolve(import.meta.dirname, "..");
+
+function readText(relPath: string): string {
+  return readFileSync(path.join(ROOT, relPath), "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// package.json health
+// ---------------------------------------------------------------------------
+
+describe("package.json", () => {
+  const pkg = JSON.parse(readText("package.json"));
+
+  test("version is valid semver", () => {
+    expect(pkg.version).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+
+  test("name is @tikoci/rosetta", () => {
+    expect(pkg.name).toBe("@tikoci/rosetta");
+  });
+
+  test("repository URL contains tikoci/rosetta", () => {
+    expect(pkg.repository.url).toContain("tikoci/rosetta");
+  });
+
+  test("no duplicate scripts that Makefile owns", () => {
+    const makefileOwned = ["start", "extract", "assess", "search"];
+    for (const name of makefileOwned) {
+      expect(pkg.scripts[name]).toBeUndefined();
+    }
+  });
+
+  test("required scripts exist", () => {
+    expect(pkg.scripts.test).toBeDefined();
+    expect(pkg.scripts.typecheck).toBeDefined();
+    expect(pkg.scripts.lint).toBeDefined();
+  });
+
+  test("bin points to JS shim", () => {
+    expect(pkg.bin.rosetta).toBe("bin/rosetta.js");
+  });
+
+  test("files includes bin/, src/, matrix/", () => {
+    expect(pkg.files).toContain("bin/");
+    expect(pkg.files).toContain("src/");
+    expect(pkg.files).toContain("matrix/");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// npm bin shim
+// ---------------------------------------------------------------------------
+
+describe("bin/rosetta.js", () => {
+  test("shim exists", () => {
+    expect(existsSync(path.join(ROOT, "bin/rosetta.js"))).toBe(true);
+  });
+
+  test("has node shebang", () => {
+    const src = readText("bin/rosetta.js");
+    expect(src.startsWith("#!/usr/bin/env node")).toBe(true);
+  });
+
+  test("detects Bun runtime", () => {
+    const src = readText("bin/rosetta.js");
+    expect(src).toContain('typeof Bun !== "undefined"');
+  });
+
+  test("falls back to spawning bun for Node", () => {
+    const src = readText("bin/rosetta.js");
+    expect(src).toContain('spawn("bun"');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Build constants declarations
+// ---------------------------------------------------------------------------
+
+describe("build-time constants", () => {
+  test("mcp.ts declares VERSION", () => {
+    const src = readText("src/mcp.ts");
+    expect(src).toContain("declare const VERSION");
+  });
+
+  test("mcp.ts declares IS_COMPILED", () => {
+    const src = readText("src/mcp.ts");
+    expect(src).toContain("declare const IS_COMPILED");
+  });
+
+  test("db.ts declares IS_COMPILED", () => {
+    const src = readText("src/db.ts");
+    expect(src).toContain("declare const IS_COMPILED");
+  });
+
+  test("setup.ts declares REPO_URL and VERSION", () => {
+    const src = readText("src/setup.ts");
+    expect(src).toContain("declare const REPO_URL");
+    expect(src).toContain("declare const VERSION");
+  });
+
+  test("build script injects all three constants", () => {
+    const src = readText("scripts/build-release.ts");
+    expect(src).toContain("VERSION=");
+    expect(src).toContain("REPO_URL=");
+    expect(src).toContain("IS_COMPILED=");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Build script structure
+// ---------------------------------------------------------------------------
+
+describe("build-release.ts", () => {
+  test("script exists", () => {
+    expect(existsSync(path.join(ROOT, "scripts/build-release.ts"))).toBe(true);
+  });
+
+  test("defines all 4 platform targets", () => {
+    const src = readText("scripts/build-release.ts");
+    expect(src).toContain("macos-arm64");
+    expect(src).toContain("macos-x64");
+    expect(src).toContain("windows-x64");
+    expect(src).toContain("linux-x64");
+  });
+
+  test("uses bun build --compile", () => {
+    const src = readText("scripts/build-release.ts");
+    expect(src).toContain("--compile");
+  });
+
+  test("compresses database", () => {
+    const src = readText("scripts/build-release.ts");
+    expect(src).toContain("ros-help.db.gz");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// setup.ts URL consistency
+// ---------------------------------------------------------------------------
+
+describe("setup.ts", () => {
+  test("REPO_URL fallback matches package.json repository", () => {
+    const src = readText("src/setup.ts");
+    const pkg = JSON.parse(readText("package.json"));
+
+    // Extract the fallback repo string: `? REPO_URL : "tikoci/rosetta"`
+    const match = src.match(/REPO_URL\s*:\s*"([^"]+)"/);
+    expect(match).not.toBeNull();
+
+    const fallbackRepo = match?.[1];
+    expect(pkg.repository.url).toContain(fallbackRepo);
+  });
+
+  test("downloads from GitHub Releases URL", () => {
+    const src = readText("src/setup.ts");
+    expect(src).toContain("github.com/");
+    expect(src).toContain("/releases/latest/download/ros-help.db.gz");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Makefile has release targets
+// ---------------------------------------------------------------------------
+
+describe("Makefile", () => {
+  const makefile = readText("Makefile");
+
+  test("has preflight target", () => {
+    expect(makefile).toContain("preflight:");
+  });
+
+  test("has build-release target", () => {
+    expect(makefile).toContain("build-release:");
+  });
+
+  test("has release target", () => {
+    expect(makefile).toContain("release:");
+  });
+
+  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("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");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CI release workflow
+// ---------------------------------------------------------------------------
+
+describe("release.yml", () => {
+  test("workflow file exists", () => {
+    expect(existsSync(path.join(ROOT, ".github/workflows/release.yml"))).toBe(
+      true,
+    );
+  });
+
+  test("has required inputs", () => {
+    const src = readText(".github/workflows/release.yml");
+    expect(src).toContain("html_url:");
+    expect(src).toContain("version:");
+  });
+
+  test("tolerates Confluence zip with absolute path root entry", () => {
+    const src = readText(".github/workflows/release.yml");
+    // Confluence exports include a bare "/" entry → unzip exits 2
+    expect(src).toMatch(/unzip.*\|\|.*\$\?.*-eq.*2/);
+  });
+
+  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-commands.ts");
+    expect(src).toContain("extract-devices.ts");
+    expect(src).toContain("extract-changelogs.ts");
+    expect(src).toContain("link-commands.ts");
+  });
+
+  test("runs quality gate before release", () => {
+    const src = readText(".github/workflows/release.yml");
+    expect(src).toContain("bun run typecheck");
+    expect(src).toContain("bun test");
+    expect(src).toContain("bun run lint");
+  });
+
+  test("creates GitHub Release", () => {
+    const src = readText(".github/workflows/release.yml");
+    expect(src).toContain("gh release create");
+  });
+
+  test("publishes to npm", () => {
+    const src = readText(".github/workflows/release.yml");
+    expect(src).toContain("npm publish");
+    expect(src).toContain("NPM_TOKEN");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CLI flags in mcp.ts
+// ---------------------------------------------------------------------------
+
+describe("CLI flags", () => {
+  const src = readText("src/mcp.ts");
+
+  test("supports --version flag", () => {
+    expect(src).toContain("--version");
+  });
+
+  test("supports --help flag", () => {
+    expect(src).toContain("--help");
+  });
+
+  test("supports --setup flag", () => {
+    expect(src).toContain("--setup");
+  });
+});

package/src/restraml.ts

@@ -0,0 +1,65 @@
+/**
+ * restraml.ts — Shared helpers for fetching data from tikoci/restraml.
+ *
+ * restraml publishes inspect.json files to GitHub Pages. Version discovery
+ * uses the GitHub API (1 call), but all inspect.json fetches go through
+ * GitHub Pages (no rate limit).
+ */
+
+/** GitHub Pages base URL — inspect.json files served here (no rate limit) */
+export const RESTRAML_PAGES_URL = "https://tikoci.github.io/restraml";
+
+/** GitHub API endpoint for version directory listing (60 req/hr unauthenticated) */
+const RESTRAML_API_CONTENTS_URL = "https://api.github.com/repos/tikoci/restraml/contents/docs";
+
+export function isHttpUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+export function normalizeBaseUrl(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+interface GitHubContentEntry {
+  name: string;
+  type: "file" | "dir";
+}
+
+/**
+ * Discover available RouterOS versions from the restraml GitHub repo.
+ * Uses 1 GitHub API call to list the docs/ directory, returns version strings.
+ */
+export async function discoverRemoteVersions(): Promise<string[]> {
+  const response = await fetch(RESTRAML_API_CONTENTS_URL, {
+    headers: { Accept: "application/vnd.github.v3+json" },
+  });
+
+  if (!response.ok) {
+    const rateLimitRemaining = response.headers.get("x-ratelimit-remaining");
+    const detail = rateLimitRemaining === "0"
+      ? " (GitHub API rate limit exceeded — try again later or pass a local docs path)"
+      : "";
+    throw new Error(
+      `Failed to list restraml versions: HTTP ${response.status}${detail}`,
+    );
+  }
+
+  const entries = (await response.json()) as GitHubContentEntry[];
+  return entries
+    .filter((e) => e.type === "dir" && /^\d+\.\d+/.test(e.name))
+    .map((e) => e.name);
+}
+
+/**
+ * Load a JSON file from a URL or local path.
+ */
+export async function loadJson<T = unknown>(source: string): Promise<T> {
+  if (isHttpUrl(source)) {
+    const response = await fetch(source);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch ${source}: HTTP ${response.status}`);
+    }
+    return (await response.json()) as T;
+  }
+  return (await Bun.file(source).json()) as T;
+}

package/src/search.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env bun
+/**
+ * CLI search over RouterOS documentation database.
+ * Usage: bun run src/search.ts "firewall filter"
+ */
+
+import { db, initDb } from "./db.ts";
+
+const query = process.argv.slice(2).join(" ");
+if (!query) {
+  console.error("Usage: bun run src/search.ts <query>");
+  process.exit(1);
+}
+
+initDb();
+
+type SearchResult = {
+  id: number;
+  title: string;
+  path: string;
+  url: string;
+  word_count: number;
+  code_lines: number;
+  excerpt: string;
+};
+
+const results = db
+  .query<SearchResult, [string]>(
+    `SELECT s.id, s.title, s.path, s.url, s.word_count, s.code_lines,
+            snippet(pages_fts, 2, '>>>', '<<<', '...', 30) as excerpt
+     FROM pages_fts fts
+     JOIN pages s ON s.id = fts.rowid
+     WHERE pages_fts MATCH ?
+     ORDER BY bm25(pages_fts, 3.0, 2.0, 1.0, 0.5) LIMIT 10`,
+  )
+  .all(query);
+
+if (results.length === 0) {
+  console.log(`No results for "${query}"`);
+  process.exit(0);
+}
+
+console.log(`\n${results.length} results for "${query}":\n`);
+for (const r of results) {
+  console.log(`  [${r.id}] ${r.path}`);
+  console.log(`      ${r.word_count} words, ${r.code_lines} code lines`);
+  console.log(`      ${r.url}`);
+  console.log(`      ${r.excerpt}\n`);
+}

package/src/setup.ts

@@ -0,0 +1,224 @@
+/**
+ * setup.ts — Download the RouterOS documentation database and print MCP client config.
+ *
+ * Called by `rosetta --setup` (compiled binary) or `bun run src/setup.ts` (dev).
+ * Downloads ros-help.db.gz from the latest GitHub Release, decompresses it,
+ * validates the DB, and prints config snippets for each MCP client.
+ */
+
+import { existsSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { gunzipSync } from "bun";
+
+declare const REPO_URL: string;
+declare const VERSION: string;
+
+const GITHUB_REPO =
+  typeof REPO_URL !== "undefined" ? REPO_URL : "tikoci/rosetta";
+const RELEASE_VERSION =
+  typeof VERSION !== "undefined" ? VERSION : "dev";
+
+/** Where the binary (or dev project root) lives */
+function getBaseDir(): string {
+  // If IS_COMPILED is defined, use the executable's directory
+  // Otherwise use project root (one level up from src/)
+  try {
+    // @ts-expect-error IS_COMPILED defined at build time
+    if (typeof IS_COMPILED !== "undefined" && IS_COMPILED) {
+      return path.dirname(process.execPath);
+    }
+  } catch {
+    // not compiled
+  }
+  return path.resolve(import.meta.dirname, "..");
+}
+
+/** The binary/script path for MCP config */
+function getServerCommand(): string {
+  try {
+    // @ts-expect-error IS_COMPILED defined at build time
+    if (typeof IS_COMPILED !== "undefined" && IS_COMPILED) {
+      return process.execPath;
+    }
+  } catch {
+    // not compiled
+  }
+  // Dev mode — bun run src/mcp.ts
+  return path.resolve(import.meta.dirname, "mcp.ts");
+}
+
+/** Check if a DB file exists and has actual page data */
+function dbHasData(dbPath: string): boolean {
+  if (!existsSync(dbPath)) return false;
+  try {
+    const { default: sqlite } = require("bun:sqlite");
+    const check = new sqlite(dbPath, { readonly: true });
+    const row = check.prepare("SELECT COUNT(*) AS c FROM pages").get() as { c: number };
+    check.close();
+    return row.c > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Download ros-help.db.gz from GitHub Releases, decompress, and write to dbPath */
+export async function downloadDb(
+  dbPath: string,
+  log: (msg: string) => void = console.log,
+) {
+  const url = `https://github.com/${GITHUB_REPO}/releases/latest/download/ros-help.db.gz`;
+  log(`Downloading database from GitHub Releases...`);
+  log(`  ${url}`);
+
+  const response = await fetch(url, { redirect: "follow" });
+  if (!response.ok) {
+    throw new Error(`Download failed: ${response.status} ${response.statusText}`);
+  }
+
+  const contentLength = response.headers.get("content-length");
+  const totalMB = contentLength ? (Number(contentLength) / 1024 / 1024).toFixed(1) : "?";
+  log(`  Downloading ${totalMB} MB (compressed)...`);
+
+  const compressed = new Uint8Array(await response.arrayBuffer());
+  log(`  Decompressing...`);
+
+  const decompressed = gunzipSync(compressed);
+  writeFileSync(dbPath, decompressed);
+
+  const sizeMB = (decompressed.byteLength / 1024 / 1024).toFixed(1);
+  log(`  Wrote ${sizeMB} MB to ${dbPath}`);
+}
+
+export async function runSetup(force = false) {
+  const baseDir = getBaseDir();
+  const dbPath = path.join(baseDir, "ros-help.db");
+  const serverCmd = getServerCommand();
+  const isCompiled = serverCmd === process.execPath;
+
+  console.log(`rosetta ${RELEASE_VERSION}`);
+  console.log();
+
+  // ── Download DB if needed ──
+  const needsDownload = force || !dbHasData(dbPath);
+  if (!needsDownload) {
+    console.log(`Database already exists: ${dbPath}`);
+    console.log(`  (use --setup --force to re-download)`);
+  } else {
+    await downloadDb(dbPath);
+  }
+
+  // ── Validate DB ──
+  console.log();
+  try {
+    const { default: sqlite } = await import("bun:sqlite");
+    const db = new sqlite(dbPath, { readonly: true });
+    const row = db.prepare("SELECT COUNT(*) AS c FROM pages").get() as { c: number };
+    const cmdRow = db.prepare("SELECT COUNT(*) AS c FROM commands WHERE type='cmd'").get() as { c: number };
+    db.close();
+    console.log(`✓ Database ready (${row.c} pages, ${cmdRow.c} commands)`);
+  } catch (e) {
+    console.error(`✗ Database validation failed: ${e}`);
+    console.error(`  Try re-downloading with: ${isCompiled ? path.basename(serverCmd) : "bun run src/setup.ts"} --setup --force`);
+    process.exit(1);
+  }
+
+  // ── Print config snippets ──
+  console.log();
+  console.log("─".repeat(60));
+  console.log("Configure your MCP client:");
+  console.log("─".repeat(60));
+
+  if (isCompiled) {
+    printCompiledConfig(serverCmd);
+  } else {
+    printDevConfig(baseDir);
+  }
+}
+
+function printCompiledConfig(serverCmd: string) {
+  const cmdJson = JSON.stringify(serverCmd);
+
+  // Claude Desktop
+  const isMac = process.platform === "darwin";
+  const configPath = isMac
+    ? "~/Library/Application\\ Support/Claude/claude_desktop_config.json"
+    : "%APPDATA%\\Claude\\claude_desktop_config.json";
+
+  console.log();
+  console.log("▸ Claude Desktop");
+  console.log(`  Edit: ${configPath}`);
+  console.log();
+  console.log(`  {`);
+  console.log(`    "mcpServers": {`);
+  console.log(`      "rosetta": {`);
+  console.log(`        "command": ${cmdJson}`);
+  console.log(`      }`);
+  console.log(`    }`);
+  console.log(`  }`);
+  console.log();
+  console.log(`  Then restart Claude Desktop.`);
+
+  // Claude Code
+  console.log();
+  console.log("▸ Claude Code");
+  console.log(`  claude mcp add rosetta ${serverCmd}`);
+
+  // VS Code Copilot
+  console.log();
+  console.log("▸ VS Code Copilot (User Settings JSON)");
+  console.log();
+  console.log(`  "mcp": {`);
+  console.log(`    "servers": {`);
+  console.log(`      "rosetta": {`);
+  console.log(`        "command": ${cmdJson}`);
+  console.log(`      }`);
+  console.log(`    }`);
+  console.log(`  }`);
+  console.log();
+}
+
+function printDevConfig(baseDir: string) {
+  const cwdJson = JSON.stringify(baseDir);
+
+  // Claude Desktop
+  const isMac = process.platform === "darwin";
+  const configPath = isMac
+    ? "~/Library/Application\\ Support/Claude/claude_desktop_config.json"
+    : "%APPDATA%\\Claude\\claude_desktop_config.json";
+
+  console.log();
+  console.log("▸ Claude Desktop");
+  console.log(`  Edit: ${configPath}`);
+  console.log();
+  console.log(`  {`);
+  console.log(`    "mcpServers": {`);
+  console.log(`      "rosetta": {`);
+  console.log(`        "command": "bun",`);
+  console.log(`        "args": ["run", "src/mcp.ts"],`);
+  console.log(`        "cwd": ${cwdJson}`);
+  console.log(`      }`);
+  console.log(`    }`);
+  console.log(`  }`);
+  console.log();
+  console.log(`  Then restart Claude Desktop.`);
+
+  // Claude Code
+  console.log();
+  console.log("▸ Claude Code");
+  console.log(`  claude mcp add rosetta -- bun run src/mcp.ts`);
+
+  // VS Code Copilot
+  console.log();
+  console.log("▸ VS Code Copilot");
+  console.log(`  The repo includes .vscode/mcp.json — just open the folder in VS Code.`);
+  console.log();
+}
+
+// Run directly
+if (import.meta.main) {
+  const force = process.argv.includes("--force");
+  runSetup(force).catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}