@tikoci/rosetta 0.6.7 → 0.6.9

package/src/query.test.ts

@@ -34,6 +34,9 @@ const {
   searchVideos,
   searchDude,
   getDudePage,
+  listSkills,
+  getSkill,
+  getSkillReference,
 } = await import("./query.ts");
 const { parseChangelog } = await import("./extract-changelogs.ts");
 const { parseVtt, segmentTranscript } = await import("./extract-videos.ts");
@@ -92,6 +95,18 @@ beforeAll(() => {
     (id, path, name, type, parent_path, page_id, description, ros_version)
     VALUES (2, '/ip/dhcp-server', 'dhcp-server', 'dir', '/ip', 1, 'DHCP Server configuration', '7.22')`);
 
+  // schema_nodes for arch-filter tests: shared + x86-only child of /ip
+  db.run(`INSERT INTO schema_nodes (path, name, type, parent_path, dir_role, _arch)
+    VALUES ('/ip', 'ip', 'dir', NULL, 'namespace', NULL)`);
+  db.run(`INSERT INTO schema_nodes (path, name, type, parent_path, dir_role, _arch)
+    VALUES ('/ip/dhcp-server', 'dhcp-server', 'dir', '/ip', 'list', NULL)`);
+  db.run(`INSERT INTO schema_nodes (path, name, type, parent_path, dir_role, _arch)
+    VALUES ('/ip/x86-feature', 'x86-feature', 'cmd', '/ip', NULL, 'x86')`);
+  // Also insert a commands row for x86-feature so it participates in browseCommands
+  db.run(`INSERT INTO commands
+    (id, path, name, type, parent_path, page_id, description, ros_version)
+    VALUES (99, '/ip/x86-feature', 'x86-feature', 'cmd', '/ip', NULL, 'x86-only', '7.22')`);
+
   db.run(`INSERT INTO command_versions (command_path, ros_version)
     VALUES ('/ip/dhcp-server', '7.22')`);
   db.run(`INSERT INTO command_versions (command_path, ros_version)
@@ -765,6 +780,28 @@ describe("browseCommands", () => {
     const dhcp = children.find((c) => c.path === "/ip/dhcp-server");
     expect(dhcp?.page_title).toBe("DHCP Server");
   });
+
+  test("arch param binds correctly — x86-only node gets NULL enrichment when arch=arm64", () => {
+    // /ip/x86-feature has _arch='x86' in schema_nodes; browsing with arch='arm64'
+    // should still return the command (LEFT JOIN from commands), but schema enrichment
+    // (dir_role) should be NULL since the x86 schema_nodes row doesn't match arm64 filter.
+    const children = browseCommands("/ip", "arm64");
+    const x86Feature = children.find((c) => c.path === "/ip/x86-feature");
+    expect(x86Feature).toBeDefined(); // command still in results (from commands table)
+    expect(x86Feature?.dir_role).toBeNull(); // schema enrichment absent for other-arch node
+
+    // dhcp-server (_arch=NULL = shared) still gets enrichment
+    const dhcp = children.find((c) => c.path === "/ip/dhcp-server");
+    expect(dhcp?.dir_role).toBe("list"); // schema enrichment present for shared node
+  });
+
+  test("arch param binds correctly — x86 filter enriches x86-only node", () => {
+    const children = browseCommands("/ip", "x86");
+    const x86Feature = children.find((c) => c.path === "/ip/x86-feature");
+    expect(x86Feature).toBeDefined();
+    // x86-feature has _arch='x86', matches the arch='x86' filter, so _arch is populated
+    expect(x86Feature?._arch).toBe("x86");
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -1494,6 +1531,7 @@ describe("schema", () => {
       "commands", "command_versions", "ros_versions",
       "devices", "device_test_results", "changelogs", "schema_migrations",
       "videos", "video_segments",
+      "skills", "skill_references",
     ];
     for (const table of expected) {
       expect(names).toContain(table);
@@ -1502,7 +1540,7 @@ describe("schema", () => {
 
   test("all FTS5 virtual tables exist", () => {
     const names = tableNames();
-    const expected = ["pages_fts", "properties_fts", "callouts_fts", "devices_fts", "changelogs_fts", "videos_fts", "video_segments_fts"];
+    const expected = ["pages_fts", "properties_fts", "callouts_fts", "devices_fts", "changelogs_fts", "videos_fts", "video_segments_fts", "skills_fts"];
     for (const fts of expected) {
       expect(names).toContain(fts);
     }
@@ -1564,6 +1602,13 @@ describe("schema", () => {
     expect(triggers).toContain("dude_pages_au");
   });
 
+  test("content-sync triggers exist for skills", () => {
+    const triggers = triggerNames();
+    expect(triggers).toContain("skills_ai");
+    expect(triggers).toContain("skills_ad");
+    expect(triggers).toContain("skills_au");
+  });
+
   test("PRAGMA user_version matches SCHEMA_VERSION", () => {
     const result = checkSchemaVersion();
     expect(result.ok).toBe(true);
@@ -1583,6 +1628,88 @@ describe("getDbStats", () => {
     expect(stats.ros_version_min).toBe("7.9");
     expect(stats.ros_version_max).toBe("7.22");
   });
+
+  test("includes skills count", () => {
+    const stats = getDbStats();
+    expect(stats).toHaveProperty("skills");
+    expect(typeof stats.skills).toBe("number");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Skills: agent guides from tikoci/routeros-skills
+// ---------------------------------------------------------------------------
+
+describe("skills", () => {
+  // Insert fixture data for skills tests
+  beforeAll(() => {
+    db.run("DELETE FROM skill_references");
+    db.run("DELETE FROM skills");
+
+    db.run(`INSERT INTO skills (name, description, content, source_repo, source_sha, source_url, word_count, extracted_at)
+      VALUES ('routeros-test-skill', 'Test skill for unit tests', 'This is test content for the skill.', 'tikoci/routeros-skills', 'abc123', 'https://github.com/tikoci/routeros-skills/blob/abc123/routeros-test-skill/SKILL.md', 7, '2025-01-01T00:00:00Z')`);
+
+    const row = db.prepare("SELECT id FROM skills WHERE name = 'routeros-test-skill'").get() as { id: number };
+
+    db.run(`INSERT INTO skill_references (skill_id, path, filename, content, word_count)
+      VALUES (${row.id}, 'references/test-ref.md', 'test-ref.md', 'Reference content here.', 3)`);
+  });
+
+  test("listSkills returns all skills", () => {
+    const skills = listSkills();
+    expect(skills.length).toBeGreaterThanOrEqual(1);
+    const testSkill = skills.find(s => s.name === "routeros-test-skill");
+    expect(testSkill).toBeDefined();
+    if (!testSkill) throw new Error("Expected test skill to exist");
+    expect(testSkill.description).toBe("Test skill for unit tests");
+    expect(testSkill.word_count).toBe(7);
+    expect(testSkill.ref_count).toBe(1);
+  });
+
+  test("getSkill returns full skill with provenance and references", () => {
+    const skill = getSkill("routeros-test-skill");
+    expect(skill).not.toBeNull();
+    if (!skill) throw new Error("Expected skill details to exist");
+    expect(skill.name).toBe("routeros-test-skill");
+    expect(skill.content).toBe("This is test content for the skill.");
+    expect(skill.provenance).toContain("PROVENANCE");
+    expect(skill.provenance).toContain("tikoci/routeros-skills");
+    expect(skill.source_sha).toBe("abc123");
+    expect(skill.references).toHaveLength(1);
+    expect(skill.references[0]?.filename).toBe("test-ref.md");
+  });
+
+  test("getSkill is case-insensitive", () => {
+    const skill = getSkill("ROUTEROS-TEST-SKILL");
+    expect(skill).not.toBeNull();
+    if (!skill) throw new Error("Expected case-insensitive skill lookup to work");
+    expect(skill.name).toBe("routeros-test-skill");
+  });
+
+  test("getSkill returns null for nonexistent skill", () => {
+    const skill = getSkill("nonexistent-skill");
+    expect(skill).toBeNull();
+  });
+
+  test("getSkillReference returns a specific reference file", () => {
+    const ref = getSkillReference("routeros-test-skill", "test-ref.md");
+    expect(ref).not.toBeNull();
+    if (!ref) throw new Error("Expected skill reference to exist");
+    expect(ref.content).toBe("Reference content here.");
+    expect(ref.word_count).toBe(3);
+  });
+
+  test("getSkillReference returns null for nonexistent reference", () => {
+    const ref = getSkillReference("routeros-test-skill", "nonexistent.md");
+    expect(ref).toBeNull();
+  });
+
+  test("FTS5 indexes skill content via triggers", () => {
+    const results = db.prepare(
+      "SELECT rowid FROM skills_fts WHERE skills_fts MATCH 'test'"
+    ).all();
+    expect(results.length).toBeGreaterThanOrEqual(1);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/query.ts

@@ -475,9 +475,29 @@ export function lookupProperty(
     .all(name) as typeof lookupProperty extends (...a: unknown[]) => infer R ? R : never;
 }
 
+/** Parse _attrs JSON and extract completion, stripping _attrs from output. */
+function enrichWithCompletion(row: unknown): Record<string, unknown> {
+  const r = row as Record<string, unknown>;
+  const attrs = r._attrs as string | null;
+  const result = { ...r };
+  delete result._attrs;
+  if (attrs) {
+    try {
+      const parsed = JSON.parse(attrs);
+      result.completion = parsed.completion ?? null;
+    } catch {
+      result.completion = null;
+    }
+  } else {
+    result.completion = null;
+  }
+  return result;
+}
+
 /** Browse the command tree at a given path. */
 export function browseCommands(
   cmdPath: string,
+  arch?: string,
 ): Array<{
   path: string;
   name: string;
@@ -485,17 +505,29 @@ export function browseCommands(
   description: string | null;
   page_title: string | null;
   page_url: string | null;
+  dir_role: string | null;
+  data_type: string | null;
+  enum_values: string | null;
+  _arch: string | null;
+  completion: Record<string, { style: string; preference: number; desc?: string }> | null;
 }> {
+  const archFilter = arch ? " AND (sn._arch IS NULL OR sn._arch = ?)" : "";
+  // arch placeholder is in the JOIN clause (before WHERE), so it must come first
+  const params: string[] = [...(arch ? [arch] : []), cmdPath];
+
   return db
     .prepare(
       `SELECT c.path, c.name, c.type, c.description,
-              p.title as page_title, p.url as page_url
+              p.title as page_title, p.url as page_url,
+              sn.dir_role, sn.data_type, sn.enum_values, sn._arch, sn._attrs
        FROM commands c
        LEFT JOIN pages p ON c.page_id = p.id
+       LEFT JOIN schema_nodes sn ON sn.path = c.path AND sn.type = c.type${archFilter}
        WHERE c.parent_path = ?
        ORDER BY c.type DESC, c.name`,
     )
-    .all(cmdPath) as typeof browseCommands extends (...a: unknown[]) => infer R ? R : never;
+    .all(...params)
+    .map(enrichWithCompletion) as ReturnType<typeof browseCommands>;
 }
 
 /** Search properties by FTS query. */
@@ -663,6 +695,7 @@ export function diffCommandVersions(
   fromVersion: string,
   toVersion: string,
   pathPrefix?: string,
+  arch?: string,
 ): CommandDiffResult {
   const allVersionRows = db
     .prepare("SELECT DISTINCT version FROM ros_versions")
@@ -682,31 +715,46 @@ export function diffCommandVersions(
   const prefixFilter = prefix ? " AND (command_path = ? OR command_path LIKE ? || '/%')" : "";
   const prefixParams = (v: string) => prefix ? [v, prefix, prefix] : [v];
 
+  // When arch is specified, exclude paths belonging to the other arch
+  const otherArch = arch === "x86" ? "arm64" : arch === "arm64" ? "x86" : null;
+  const archExclude = otherArch
+    ? " AND cv_to.command_path NOT IN (SELECT path FROM schema_nodes WHERE _arch = ?)"
+    : "";
+  const archExcludeFrom = otherArch
+    ? " AND cv_from.command_path NOT IN (SELECT path FROM schema_nodes WHERE _arch = ?)"
+    : "";
+
   type Row = { command_path: string };
 
+  const addedParams = [...prefixParams(toVersion), ...(otherArch ? [otherArch] : []), ...prefixParams(fromVersion)];
   const addedRows = db
     .prepare(
       `SELECT DISTINCT cv_to.command_path
        FROM command_versions cv_to
-       WHERE cv_to.ros_version = ?${prefixFilter}
+       WHERE cv_to.ros_version = ?${prefixFilter}${archExclude}
          AND cv_to.command_path NOT IN (
            SELECT command_path FROM command_versions WHERE ros_version = ?${prefixFilter}
          )
        ORDER BY cv_to.command_path`,
     )
-    .all(...prefixParams(toVersion), ...prefixParams(fromVersion)) as Row[];
+    .all(...addedParams) as Row[];
 
+  const removedParams = [...prefixParams(fromVersion), ...(otherArch ? [otherArch] : []), ...prefixParams(toVersion)];
   const removedRows = db
     .prepare(
       `SELECT DISTINCT cv_from.command_path
        FROM command_versions cv_from
-       WHERE cv_from.ros_version = ?${prefixFilter}
+       WHERE cv_from.ros_version = ?${prefixFilter}${archExcludeFrom}
          AND cv_from.command_path NOT IN (
            SELECT command_path FROM command_versions WHERE ros_version = ?${prefixFilter}
          )
        ORDER BY cv_from.command_path`,
     )
-    .all(...prefixParams(fromVersion), ...prefixParams(toVersion)) as Row[];
+    .all(...removedParams) as Row[];
+
+  if (arch) {
+    notes.push(`Filtered to ${arch} architecture (excluding ${otherArch}-only paths).`);
+  }
 
   return {
     from_version: fromVersion,
@@ -789,6 +837,7 @@ export function compareVersions(a: string, b: string): number {
 export function browseCommandsAtVersion(
   cmdPath: string,
   version: string,
+  arch?: string,
 ): Array<{
   path: string;
   name: string;
@@ -796,18 +845,30 @@ export function browseCommandsAtVersion(
   description: string | null;
   page_title: string | null;
   page_url: string | null;
+  dir_role: string | null;
+  data_type: string | null;
+  enum_values: string | null;
+  _arch: string | null;
+  completion: Record<string, { style: string; preference: number; desc?: string }> | null;
 }> {
+  const archFilter = arch ? " AND (sn._arch IS NULL OR sn._arch = ?)" : "";
+  // arch placeholder is in the JOIN clause (before WHERE), so it must come first
+  const params: string[] = [...(arch ? [arch] : []), cmdPath, version];
+
   return db
     .prepare(
       `SELECT c.path, c.name, c.type, c.description,
-              p.title as page_title, p.url as page_url
+              p.title as page_title, p.url as page_url,
+              sn.dir_role, sn.data_type, sn.enum_values, sn._arch, sn._attrs
        FROM commands c
        LEFT JOIN pages p ON c.page_id = p.id
        JOIN command_versions cv ON cv.command_path = c.path
+       LEFT JOIN schema_nodes sn ON sn.path = c.path AND sn.type = c.type${archFilter}
        WHERE c.parent_path = ? AND cv.ros_version = ?
        ORDER BY c.type DESC, c.name`,
     )
-    .all(cmdPath, version) as Array<{ path: string; name: string; type: string; description: string | null; page_title: string | null; page_url: string | null }>;
+    .all(...params)
+    .map(enrichWithCompletion) as ReturnType<typeof browseCommandsAtVersion>;
 }
 
 // ── Device lookup and search ──
@@ -1648,7 +1709,94 @@ export function getDudePage(idOrTitle: number | string, maxLength?: number): Dud
   return page;
 }
 
-// ── Current versions (live fetch) ──
+// ── Skills (agent guides from tikoci/routeros-skills) ──
+
+const SKILLS_PROVENANCE = `⚠️ PROVENANCE: Community-created content from tikoci/routeros-skills —
+NOT official MikroTik documentation. AI-generated, human-reviewed. May contain errors.
+Verify claims using routeros_search and routeros_get_page for official documentation.`;
+
+export type SkillSummary = {
+  name: string;
+  description: string;
+  word_count: number;
+  ref_count: number;
+  source_url: string;
+};
+
+export type SkillReference = {
+  path: string;
+  filename: string;
+  content: string;
+  word_count: number;
+};
+
+export type SkillDetail = {
+  name: string;
+  description: string;
+  content: string;
+  provenance: string;
+  source_repo: string;
+  source_sha: string | null;
+  source_url: string;
+  word_count: number;
+  extracted_at: string | null;
+  references: SkillReference[];
+};
+
+/** List all available skills with reference counts. */
+export function listSkills(): SkillSummary[] {
+  return db
+    .prepare(
+      `SELECT s.name, s.description, s.word_count, s.source_url,
+              (SELECT COUNT(*) FROM skill_references sr WHERE sr.skill_id = s.id) as ref_count
+       FROM skills s
+       ORDER BY s.name`,
+    )
+    .all() as SkillSummary[];
+}
+
+/** Get a single skill by name, including its references and provenance header. */
+export function getSkill(name: string): SkillDetail | null {
+  const row = db
+    .prepare("SELECT * FROM skills WHERE name = ? COLLATE NOCASE")
+    .get(name) as Record<string, unknown> | null;
+  if (!row) return null;
+
+  const refs = db
+    .prepare(
+      `SELECT path, filename, content, word_count
+       FROM skill_references
+       WHERE skill_id = ?
+       ORDER BY path`,
+    )
+    .all(row.id as number) as SkillReference[];
+
+  return {
+    name: row.name as string,
+    description: row.description as string,
+    content: row.content as string,
+    provenance: `${SKILLS_PROVENANCE}\nSource: ${row.source_url as string}`,
+    source_repo: row.source_repo as string,
+    source_sha: row.source_sha as string | null,
+    source_url: row.source_url as string,
+    word_count: row.word_count as number,
+    extracted_at: row.extracted_at as string | null,
+    references: refs,
+  };
+}
+
+/** Get a single reference file from a skill. */
+export function getSkillReference(skillName: string, refFilename: string): SkillReference | null {
+  const row = db
+    .prepare(
+      `SELECT sr.path, sr.filename, sr.content, sr.word_count
+       FROM skill_references sr
+       JOIN skills s ON s.id = sr.skill_id
+       WHERE s.name = ? COLLATE NOCASE AND sr.filename = ? COLLATE NOCASE`,
+    )
+    .get(skillName, refFilename) as SkillReference | null;
+  return row;
+}
 
 const VERSION_BASE_URL = "https://upgrade.mikrotik.com/routeros/NEWESTa7";
 

package/src/release.test.ts

@@ -210,6 +210,21 @@ describe("Makefile", () => {
     expect(makefile).toContain("extract-dude-from-cache:");
   });
 
+  test("has extract-skills target", () => {
+    expect(makefile).toContain("extract-skills:");
+  });
+
+  test("has extract-skills-from-cache target", () => {
+    expect(makefile).toContain("extract-skills-from-cache:");
+  });
+
+  test("extract-skills 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-skills");
+  });
+
   test("extract-dude is in PHONY", () => {
     const phonyStart = makefile.indexOf(".PHONY:");
     const phonyEnd = makefile.indexOf("\n\n", phonyStart);
@@ -225,6 +240,14 @@ describe("Makefile", () => {
     expect(makefile).toMatch(/^release:.*build-release/m);
   });
 
+  test("extract target includes skills", () => {
+    expect(makefile).toMatch(/^extract:.*extract-skills/m);
+  });
+
+  test("extract-full target includes skills", () => {
+    expect(makefile).toMatch(/^extract-full:.*extract-skills/m);
+  });
+
   test("extract target includes Dude cache import", () => {
     expect(makefile).toMatch(/^extract:.*extract-dude-from-cache/m);
   });
@@ -275,6 +298,7 @@ describe("release.yml", () => {
     expect(src).toContain("extract-devices.ts");
     expect(src).toContain("extract-test-results.ts");
     expect(src).toContain("extract-changelogs.ts");
+    expect(src).toContain("extract-skills.ts");
     expect(src).toContain("link-commands.ts");
   });
 
@@ -283,6 +307,11 @@ describe("release.yml", () => {
     expect(src).toContain("extract-dude-from-cache");
   });
 
+  test("extracts agent skills in CI", () => {
+    const src = readText(".github/workflows/release.yml");
+    expect(src).toContain("extract-skills.ts");
+  });
+
   test("runs quality gate before release", () => {
     const src = readText(".github/workflows/release.yml");
     expect(src).toContain("bun run typecheck");