@tikoci/rosetta 0.8.9 → 0.8.10

package/src/gc-versions.test.ts

@@ -0,0 +1,201 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+import {
+  compareRouterOsVersions,
+  computeActiveChannelHeads,
+  gcSchemaNodePresence,
+} from "./gc-versions.ts";
+
+function createTestDb(): Database {
+  const db = new Database(":memory:");
+  db.run("PRAGMA foreign_keys=ON;");
+
+  db.run(`CREATE TABLE ros_versions (
+    version TEXT NOT NULL,
+    arch TEXT NOT NULL DEFAULT 'x86',
+    channel TEXT,
+    extra_packages INTEGER NOT NULL DEFAULT 0,
+    extracted_at TEXT NOT NULL,
+    PRIMARY KEY (version, arch)
+  );`);
+
+  db.run(`CREATE TABLE schema_nodes (
+    id INTEGER PRIMARY KEY,
+    path TEXT NOT NULL,
+    name TEXT NOT NULL,
+    type TEXT NOT NULL,
+    UNIQUE(path, type)
+  );`);
+
+  db.run(`CREATE TABLE schema_node_presence (
+    node_id INTEGER NOT NULL REFERENCES schema_nodes(id),
+    version TEXT NOT NULL,
+    PRIMARY KEY (node_id, version)
+  );`);
+
+  db.run(`CREATE TABLE command_versions (
+    command_path TEXT NOT NULL,
+    ros_version TEXT NOT NULL,
+    PRIMARY KEY (command_path, ros_version)
+  );`);
+
+  for (let i = 1; i <= 3; i++) {
+    db.run("INSERT INTO schema_nodes (id, path, name, type) VALUES (?, ?, ?, 'cmd')", [
+      i,
+      `/node-${i}`,
+      `node-${i}`,
+    ]);
+  }
+
+  return db;
+}
+
+function insertVersion(db: Database, version: string, channel: string | null, arch = "x86"): void {
+  db.run(
+    `INSERT INTO ros_versions (version, arch, channel, extra_packages, extracted_at)
+     VALUES (?, ?, ?, 1, '2026-04-26T00:00:00Z')`,
+    [version, arch, channel],
+  );
+}
+
+function insertPresence(db: Database, version: string, nodeIds = [1, 2]): void {
+  for (const nodeId of nodeIds) {
+    db.run("INSERT INTO schema_node_presence (node_id, version) VALUES (?, ?)", [nodeId, version]);
+  }
+}
+
+function insertCommandVersion(db: Database, version: string): void {
+  db.run("INSERT INTO command_versions (command_path, ros_version) VALUES (?, ?)", ["/ip/address/add", version]);
+}
+
+function count(db: Database, sql: string): number {
+  return (db.prepare(sql).get() as { c: number }).c;
+}
+
+describe("RouterOS semantic version sorting", () => {
+  test("sorts numeric releases and prereleases semantically", () => {
+    const versions = ["7.23", "7.9", "7.23rc1", "7.10", "7.23beta2", "7.23beta10", "7.22.1"];
+
+    expect(versions.sort(compareRouterOsVersions)).toEqual([
+      "7.9",
+      "7.10",
+      "7.22.1",
+      "7.23beta2",
+      "7.23beta10",
+      "7.23rc1",
+      "7.23",
+    ]);
+  });
+});
+
+describe("computeActiveChannelHeads", () => {
+  test("keeps the newest version per recognized active channel", () => {
+    const heads = computeActiveChannelHeads([
+      { version: "7.9", channel: "stable" },
+      { version: "7.10", channel: "stable" },
+      { version: "7.22", channel: "long-term" },
+      { version: "7.23beta2", channel: "testing" },
+      { version: "7.23rc1", channel: "testing" },
+      { version: "7.24beta1", channel: "development" },
+      { version: "9.99", channel: "legacy" },
+      { version: "10.0", channel: null },
+    ]);
+
+    expect(heads).toEqual({
+      stable: "7.10",
+      "long-term": "7.22",
+      testing: "7.23rc1",
+      development: "7.24beta1",
+    });
+  });
+});
+
+describe("gcSchemaNodePresence", () => {
+  test("dry-run reports candidates without mutating schema_node_presence", () => {
+    const db = createTestDb();
+    try {
+      insertVersion(db, "7.9", "stable");
+      insertVersion(db, "7.10", "stable");
+      insertPresence(db, "7.9");
+      insertPresence(db, "7.10");
+
+      const stats = gcSchemaNodePresence(db, { dryRun: true });
+
+      expect(stats.dry_run).toBe(true);
+      expect(stats.before_count).toBe(4);
+      expect(stats.after_count).toBe(4);
+      expect(stats.deleted_rows).toBe(0);
+      expect(stats.would_delete_rows).toBe(2);
+      expect(stats.kept_versions).toEqual(["7.10"]);
+      expect(stats.pruned_versions).toEqual(["7.9"]);
+      expect(count(db, "SELECT COUNT(*) AS c FROM schema_node_presence")).toBe(4);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("de-duplicates ros_versions by version when arches differ", () => {
+    const db = createTestDb();
+    try {
+      insertVersion(db, "7.21", "stable", "x86");
+      insertVersion(db, "7.22", "stable", "x86");
+      insertVersion(db, "7.22", "stable", "arm64");
+      insertPresence(db, "7.21");
+      insertPresence(db, "7.22");
+
+      const stats = gcSchemaNodePresence(db);
+
+      expect(stats.kept_versions).toEqual(["7.22"]);
+      expect(stats.pruned_versions).toEqual(["7.21"]);
+      expect(stats.deleted_rows).toBe(2);
+      expect(count(db, "SELECT COUNT(*) AS c FROM schema_node_presence WHERE version = '7.22'")).toBe(2);
+      expect(count(db, "SELECT COUNT(*) AS c FROM schema_node_presence WHERE version = '7.21'")).toBe(0);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("skips safely when no recognized channel heads can be computed", () => {
+    const db = createTestDb();
+    try {
+      insertVersion(db, "7.9", "legacy");
+      insertVersion(db, "7.10", null);
+      insertPresence(db, "7.9");
+      insertPresence(db, "7.10");
+
+      const stats = gcSchemaNodePresence(db);
+
+      expect(stats.skipped).toBe(true);
+      expect(stats.deleted_rows).toBe(0);
+      expect(stats.kept_versions).toEqual([]);
+      expect(stats.note).toContain("skipped");
+      expect(count(db, "SELECT COUNT(*) AS c FROM schema_node_presence")).toBe(4);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("prunes only schema_node_presence and leaves command_versions untouched", () => {
+    const db = createTestDb();
+    try {
+      insertVersion(db, "7.20", "stable");
+      insertVersion(db, "7.22", "stable");
+      insertVersion(db, "7.23beta1", "development");
+      for (const version of ["7.20", "7.22", "7.23beta1"]) {
+        insertPresence(db, version);
+        insertCommandVersion(db, version);
+      }
+
+      const stats = gcSchemaNodePresence(db);
+
+      expect(stats.kept_versions).toEqual(["7.22", "7.23beta1"]);
+      expect(stats.pruned_versions).toEqual(["7.20"]);
+      expect(stats.deleted_rows).toBe(2);
+      expect(count(db, "SELECT COUNT(*) AS c FROM schema_node_presence")).toBe(4);
+      expect(count(db, "SELECT COUNT(*) AS c FROM command_versions")).toBe(3);
+      expect(count(db, "SELECT COUNT(*) AS c FROM command_versions WHERE ros_version = '7.20'")).toBe(1);
+    } finally {
+      db.close();
+    }
+  });
+});

package/src/gc-versions.ts

@@ -0,0 +1,230 @@
+#!/usr/bin/env bun
+
+/**
+ * gc-versions.ts — prune schema_node_presence to active RouterOS channel heads.
+ *
+ * The GC is intentionally narrow: it deletes only schema_node_presence rows.
+ * command_versions, changelogs, schema_nodes, commands, and ros_versions keep
+ * their full extracted history.
+ */
+
+import type { SQLQueryBindings } from "bun:sqlite";
+import { Database } from "bun:sqlite";
+import { resolveDbPath } from "./paths.ts";
+
+export const ACTIVE_CHANNELS = ["stable", "long-term", "testing", "development"] as const;
+export type ActiveChannel = (typeof ACTIVE_CHANNELS)[number];
+
+export interface VersionChannelRow {
+  version: string;
+  channel: string | null;
+}
+
+export interface SchemaPresenceGcOptions {
+  dryRun?: boolean;
+}
+
+export interface SchemaPresenceGcStats {
+  before_count: number;
+  after_count: number;
+  deleted_rows: number;
+  would_delete_rows: number;
+  kept_versions: string[];
+  pruned_versions: string[];
+  channel_heads: Partial<Record<ActiveChannel, string>>;
+  dry_run: boolean;
+  skipped: boolean;
+  note?: string;
+}
+
+interface ParsedVersion {
+  valid: boolean;
+  major: number;
+  minor: number;
+  patch: number;
+  phase: number;
+  phaseNumber: number;
+}
+
+function normalizeChannel(channel: string | null): ActiveChannel | null {
+  if (!channel) return null;
+  const normalized = channel.trim().toLowerCase();
+  return ACTIVE_CHANNELS.includes(normalized as ActiveChannel) ? (normalized as ActiveChannel) : null;
+}
+
+function parseRouterOsVersion(version: string): ParsedVersion {
+  const match = version.match(/^(\d+)\.(\d+)(?:\.(\d+))?(?:(beta|rc)(\d+))?$/);
+  if (!match) {
+    return { valid: false, major: 0, minor: 0, patch: 0, phase: -3, phaseNumber: 0 };
+  }
+
+  const phase = match[4] === "beta" ? -2 : match[4] === "rc" ? -1 : 0;
+  return {
+    valid: true,
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3] ?? 0),
+    phase,
+    phaseNumber: Number(match[5] ?? 0),
+  };
+}
+
+/** Compare RouterOS versions semantically: 7.9 < 7.10 < 7.23beta2 < 7.23rc1 < 7.23. */
+export function compareRouterOsVersions(a: string, b: string): number {
+  const av = parseRouterOsVersion(a);
+  const bv = parseRouterOsVersion(b);
+
+  if (!av.valid || !bv.valid) {
+    if (av.valid !== bv.valid) return av.valid ? 1 : -1;
+    return a.localeCompare(b, undefined, { numeric: true });
+  }
+
+  for (const key of ["major", "minor", "patch", "phase", "phaseNumber"] as const) {
+    const diff = av[key] - bv[key];
+    if (diff !== 0) return diff;
+  }
+
+  return 0;
+}
+
+export function computeActiveChannelHeads(rows: VersionChannelRow[]): Partial<Record<ActiveChannel, string>> {
+  const heads: Partial<Record<ActiveChannel, string>> = {};
+
+  for (const row of rows) {
+    const channel = normalizeChannel(row.channel);
+    if (!channel) continue;
+
+    const current = heads[channel];
+    if (!current || compareRouterOsVersions(row.version, current) > 0) {
+      heads[channel] = row.version;
+    }
+  }
+
+  return heads;
+}
+
+function countRows(db: Database, sql: string, params: SQLQueryBindings[] = []): number {
+  return (db.prepare(sql).get(...params) as { c: number }).c;
+}
+
+function distinctVersions(db: Database, sql: string): string[] {
+  const rows = db.prepare(sql).all() as Array<{ version: string }>;
+  return rows.map((row) => row.version).sort(compareRouterOsVersions);
+}
+
+function countPresenceVersions(db: Database, versions: string[]): number {
+  if (versions.length === 0) return 0;
+  const placeholders = versions.map(() => "?").join(", ");
+  return countRows(db, `SELECT COUNT(*) AS c FROM schema_node_presence WHERE version IN (${placeholders})`, versions);
+}
+
+export function gcSchemaNodePresence(
+  db: Database,
+  options: SchemaPresenceGcOptions = {},
+): SchemaPresenceGcStats {
+  const dryRun = options.dryRun ?? false;
+  const beforeCount = countRows(db, "SELECT COUNT(*) AS c FROM schema_node_presence");
+  const versionRows = db.prepare("SELECT DISTINCT version, channel FROM ros_versions").all() as VersionChannelRow[];
+  const channelHeads = computeActiveChannelHeads(versionRows);
+  const keptVersions = Array.from(new Set(Object.values(channelHeads))).sort(compareRouterOsVersions);
+
+  if (keptVersions.length === 0) {
+    return {
+      before_count: beforeCount,
+      after_count: beforeCount,
+      deleted_rows: 0,
+      would_delete_rows: 0,
+      kept_versions: [],
+      pruned_versions: [],
+      channel_heads: channelHeads,
+      dry_run: dryRun,
+      skipped: true,
+      note: "No recognized ros_versions channel heads found; schema_node_presence GC skipped.",
+    };
+  }
+
+  const keptSet = new Set(keptVersions);
+  const presenceVersions = distinctVersions(db, "SELECT DISTINCT version FROM schema_node_presence");
+  const prunedVersions = presenceVersions.filter((version) => !keptSet.has(version));
+  const wouldDeleteRows = countPresenceVersions(db, prunedVersions);
+
+  if (!dryRun && prunedVersions.length > 0) {
+    const placeholders = prunedVersions.map(() => "?").join(", ");
+    db.run(`DELETE FROM schema_node_presence WHERE version IN (${placeholders})`, prunedVersions);
+  }
+
+  const afterCount = countRows(db, "SELECT COUNT(*) AS c FROM schema_node_presence");
+  const deletedRows = dryRun ? 0 : beforeCount - afterCount;
+
+  return {
+    before_count: beforeCount,
+    after_count: afterCount,
+    deleted_rows: deletedRows,
+    would_delete_rows: wouldDeleteRows,
+    kept_versions: keptVersions,
+    pruned_versions: prunedVersions,
+    channel_heads: channelHeads,
+    dry_run: dryRun,
+    skipped: false,
+    note: dryRun ? "Dry run only; schema_node_presence was not modified." : undefined,
+  };
+}
+
+function getArgValue(name: string): string | undefined {
+  const eq = process.argv.find((arg) => arg.startsWith(`${name}=`));
+  if (eq) return eq.slice(name.length + 1);
+
+  const idx = process.argv.indexOf(name);
+  return idx !== -1 && idx + 1 < process.argv.length ? process.argv[idx + 1] : undefined;
+}
+
+function usage(): string {
+  return [
+    "Usage: bun run src/gc-versions.ts [--dry-run] [--verbose] [--db <path>]",
+    "",
+    "Prunes only schema_node_presence to active RouterOS channel heads.",
+    "Conservative fallback: if no stable/long-term/testing/development heads exist, nothing is deleted.",
+  ].join("\n");
+}
+
+function printStats(stats: SchemaPresenceGcStats, verbose: boolean): void {
+  const action = stats.dry_run ? "would delete" : "deleted";
+  console.log(
+    `schema_node_presence GC: before=${stats.before_count} after=${stats.after_count} ${action}=${stats.dry_run ? stats.would_delete_rows : stats.deleted_rows}`,
+  );
+  console.log(`kept_versions=${stats.kept_versions.length ? stats.kept_versions.join(",") : "(none)"}`);
+
+  if (stats.note) console.log(`note=${stats.note}`);
+
+  if (verbose) {
+    console.log(`pruned_versions=${stats.pruned_versions.length ? stats.pruned_versions.join(",") : "(none)"}`);
+    console.log(`channel_heads=${JSON.stringify(stats.channel_heads)}`);
+  }
+}
+
+async function main(): Promise<void> {
+  if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    console.log(usage());
+    return;
+  }
+
+  const dryRun = process.argv.includes("--dry-run");
+  const verbose = process.argv.includes("--verbose");
+  const dbPath = getArgValue("--db") ?? resolveDbPath(import.meta.dirname);
+  const db = new Database(dbPath);
+
+  try {
+    db.run("PRAGMA foreign_keys=ON;");
+    const stats = gcSchemaNodePresence(db, { dryRun });
+    printStats(stats, verbose);
+  } finally {
+    db.close();
+  }
+}
+
+if (import.meta.main) {
+  main().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/src/mcp-contract.test.ts

@@ -2,7 +2,7 @@
  * mcp-contract.test.ts — MCP tool surface contract tests (Phase 2).
  *
  * Guards against silent breaking changes to the MCP tool registry:
- * - Block A: Frozen 13-tool list + workflow-arrow (→) convention in descriptions
+ * - Block A: Frozen 14-tool list + workflow-arrow (→) convention in descriptions
  * - Block B: Token-budget guardrails for 10 canonical queries (rough chars/4)
  * - Block C: Shape snapshots — fingerprint the *contract* (keys, counts,
  *           classifier output), NOT the corpus. Deliberately omits page IDs
@@ -54,6 +54,7 @@ describe("Frozen tool registry", () => {
     "routeros_search",
     "routeros_get_page",
     "routeros_lookup_property",
+    "routeros_explain_command",
     "routeros_command_tree",
     "routeros_stats",
     "routeros_search_changelogs",
@@ -66,23 +67,19 @@ describe("Frozen tool registry", () => {
     "routeros_current_versions",
   ];
 
-  test("exactly 13 tools registered", () => {
+  test("exactly 14 tools registered", () => {
     const mcpSrc = readFileSync(path.join(ROOT, "src/mcp.ts"), "utf-8");
     // Extract tool names from server.registerTool("<name>", patterns
     const toolMatches = mcpSrc.matchAll(/server\.registerTool\(\s*["']([^"']+)["']/g);
     const foundTools = Array.from(toolMatches, (m) => m[1]);
 
-    expect(foundTools.length).toBe(13);
+    expect(foundTools.length).toBe(14);
     expect(foundTools.sort()).toEqual(EXPECTED_TOOLS.sort());
   });
 
   test("all tools have workflow arrow (→) in description", () => {
     const mcpSrc = readFileSync(path.join(ROOT, "src/mcp.ts"), "utf-8");
 
-    // Terminal/informational tools that don't have natural follow-ups
-    // (identified during Phase 2 implementation as missing workflow arrows)
-    const KNOWN_EXCEPTIONS = ["routeros_stats", "routeros_current_versions"];
-
     // Extract each complete registerTool block (tool name to closing paren before next registerTool)
     // Split on registerTool calls, then extract name + description from each block
     const toolBlocks = mcpSrc.split(/(?=server\.registerTool\()/);
@@ -105,14 +102,14 @@ describe("Frozen tool registry", () => {
         if (!altMatch) continue;
 
         const description = altMatch[1];
-        if (!description.includes("→") && !KNOWN_EXCEPTIONS.includes(toolName)) {
+        if (!description.includes("→")) {
           toolsWithoutArrow.push(toolName);
         }
         continue;
       }
 
       const description = descMatch[1];
-      if (!description.includes("→") && !KNOWN_EXCEPTIONS.includes(toolName)) {
+      if (!description.includes("→")) {
         toolsWithoutArrow.push(toolName);
       }
     }
@@ -127,7 +124,7 @@ describe("Frozen tool registry", () => {
     const totalFound = Array.from(
       mcpSrc.matchAll(/server\.registerTool\(\s*["']([^"']+)["']/g),
     ).length;
-    expect(totalFound).toBe(13);
+    expect(totalFound).toBe(14);
   });
 });
 

package/src/mcp-http.test.ts

@@ -322,7 +322,7 @@ describe("HTTP transport: session lifecycle", () => {
     expect(serverInfo.name).toBe("rosetta");
   });
 
-  test("tools/list returns all 13 tools after initialization", async () => {
+  test("tools/list returns all 14 tools after initialization", async () => {
     const { sessionId } = await mcpInitialize(server.url);
 
     // Send initialized notification first (required by protocol)
@@ -333,12 +333,13 @@ describe("HTTP transport: session lifecycle", () => {
 
     const result = (messages[0] as Record<string, unknown>).result as Record<string, unknown>;
     const tools = result.tools as Array<{ name: string }>;
-    expect(tools.length).toBe(13);
+    expect(tools.length).toBe(14);
 
     const toolNames = tools.map((t) => t.name).sort();
     expect(toolNames).toContain("routeros_search");
     expect(toolNames).toContain("routeros_get_page");
     expect(toolNames).toContain("routeros_lookup_property");
+    expect(toolNames).toContain("routeros_explain_command");
     expect(toolNames).toContain("routeros_command_tree");
     expect(toolNames).toContain("routeros_search_changelogs");
     expect(toolNames).toContain("routeros_command_version_check");
@@ -555,8 +556,8 @@ describe("HTTP transport: multi-session", () => {
     const tools1 = ((msgs1[0] as Record<string, unknown>).result as Record<string, unknown>).tools as unknown[];
     const tools2 = ((msgs2[0] as Record<string, unknown>).result as Record<string, unknown>).tools as unknown[];
 
-    expect(tools1.length).toBe(13);
-    expect(tools2.length).toBe(13);
+    expect(tools1.length).toBe(14);
+    expect(tools2.length).toBe(14);
   });
 
   test("deleting one session does not affect another", async () => {
@@ -578,7 +579,7 @@ describe("HTTP transport: multi-session", () => {
     // Client2 still works
     const msgs = await mcpRequest(server.url, client2.sessionId, "tools/list", 2);
     const tools = ((msgs[0] as Record<string, unknown>).result as Record<string, unknown>).tools as unknown[];
-    expect(tools.length).toBe(13);
+    expect(tools.length).toBe(14);
 
     // Client1 is gone
     const resp = await fetch(server.url, {