add routing for skills

Author: LadyBluenotes

packages/skillc/src/buildTopics.ts

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+
+type SourceDoc = {
+  id: string;
+  relPath: string;
+  ext: "md" | "mdx";
+  size: number;
+  sha256: string;
+  sha256_normalized: string;
+  frontmatter_keys: string[];
+  title?: string;
+  headings: Array<{ depth: number; text: string }>;
+  text: string;
+};
+
+type TopicsIndex = {
+  schema: 1;
+  library: string;
+  version: string;            // for now: ref (main) or commit short sha
+  docs_hash: string;
+  revision: any;
+  topics: Array<{
+    slug: string;
+    title: string;
+    kind: "page" | "section";
+    relPath: string;
+    anchor?: string;
+    sourceIds: string[];      // doc ids from sources.jsonl
+  }>;
+};
+
+function slugify(s: string) {
+  return s
+    .toLowerCase()
+    .replace(/['"]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+function makeAnchor(text: string) {
+  // Keep consistent with GitHub-ish anchors (roughly)
+  return slugify(text);
+}
+
+export function buildTopicsIndex(args: {
+  library: string;
+  sourceRoot: string;     // build/sources/<lib>/<owner>__<repo>/<ref>
+  indexRoot: string;      // build/index/<lib>/<owner>__<repo>/<ref>
+  version: string;        // e.g. "main"
+  outDir: string;         // registry/skills/<lib>/<version>
+}) {
+  const docsIndexPath = path.join(args.indexRoot, "docs.index.json");
+  const sourcesPath = path.join(args.indexRoot, "docs.sources.jsonl");
+  const revisionPath = path.join(args.sourceRoot, "REVISION.json");
+
+  if (!fs.existsSync(docsIndexPath)) throw new Error(`Missing ${docsIndexPath}`);
+  if (!fs.existsSync(sourcesPath)) throw new Error(`Missing ${sourcesPath}`);
+  if (!fs.existsSync(revisionPath)) throw new Error(`Missing ${revisionPath}`);
+
+  const docsIndex = JSON.parse(fs.readFileSync(docsIndexPath, "utf8"));
+  const revision = JSON.parse(fs.readFileSync(revisionPath, "utf8"));
+  const docs_hash: string = docsIndex.docs_hash;
+
+  const lines = fs.readFileSync(sourcesPath, "utf8").split("\n").filter(Boolean);
+  const docs: SourceDoc[] = lines.map((l) => JSON.parse(l));
+
+  const topics: TopicsIndex["topics"] = [];
+
+  for (const doc of docs) {
+    const pageTitle = doc.title ?? doc.relPath.replace(/^docs\//, "");
+    topics.push({
+      slug: `page:${slugify(doc.relPath)}`,
+      title: pageTitle,
+      kind: "page",
+      relPath: doc.relPath,
+      sourceIds: [doc.id],
+    });
+
+    // Add section topics for h2/h3 only (keeps index tight)
+    for (const h of doc.headings) {
+      if (h.depth !== 2 && h.depth !== 3) continue;
+      const anchor = makeAnchor(h.text);
+      topics.push({
+        slug: `sec:${slugify(doc.relPath)}#${anchor}`,
+        title: `${pageTitle} → ${h.text}`,
+        kind: "section",
+        relPath: doc.relPath,
+        anchor,
+        sourceIds: [doc.id],
+      });
+    }
+  }
+
+  // stable order
+  topics.sort((a, b) => a.slug.localeCompare(b.slug));
+
+  const out: TopicsIndex = {
+    schema: 1,
+    library: args.library,
+    version: args.version,
+    docs_hash,
+    revision,
+    topics,
+  };
+
+  fs.mkdirSync(args.outDir, { recursive: true });
+  fs.writeFileSync(path.join(args.outDir, "index.json"), JSON.stringify(out, null, 2) + "\n");
+}

packages/skillc/src/cli.ts

@@ -3,6 +3,10 @@ import path from "node:path";
 import process from "node:process";
 import { fetchDocsFromRepo } from "./fetchDocs.js";
 import { indexDocsSnapshot } from "./indexDocs.js";
+import { buildTopicsIndex } from "./buildTopics.js";
+import { renderSkillMd } from "./renderSkill.js";
+import { renderLibraryAgent } from "./renderLibraryAgent.js";
+import { renderTanstackAgent } from "./renderTanstackAgent.js";
 
 function arg(name: string) {
   const idx = process.argv.indexOf(`--${name}`);
@@ -55,6 +59,41 @@ async function main() {
     return;
   }
 
+  if (cmd === "build-topics") {
+    const lib = arg("lib");
+    const repo = arg("repo");
+    const ref = arg("ref") ?? "main";
+    if (!lib) throw new Error("--lib is required");
+    if (!repo) throw new Error("--repo is required");
+
+    const m = repo.match(/github\.com\/([^/]+)\/([^/]+)(?:\.git)?$/);
+    if (!m) throw new Error(`bad repo: ${repo}`);
+    const owner = m[1];
+    const repoName = m[2].replace(/\.git$/, "");
+
+    const sourceRoot = path.join("build", "sources", lib, `${owner}__${repoName}`, ref);
+    const indexRoot = path.join("build", "index", lib, `${owner}__${repoName}`, ref);
+
+    const version = ref; // temporary policy (will change to npm version)
+    const outDir = path.join("registry", "skills", lib, version);
+
+    buildTopicsIndex({ library: lib, sourceRoot, indexRoot, version, outDir });
+    renderSkillMd({ library: lib, version, outDir });
+
+    // agents
+    renderTanstackAgent({ outDir: path.join("registry", "agents") });
+    if (lib === "query" || lib === "router") {
+      renderLibraryAgent({
+        library: lib,
+        version,
+        skillPath: path.join("registry", "skills", lib, version, "SKILL.md").replace(/\\/g, "/"),
+        outDir: path.join("registry", "agents"),
+      });
+    }
+
+    return;
+  }
+
   throw new Error(`Unknown command: ${cmd}`);
 }
 

packages/skillc/src/renderLibraryAgent.ts

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function renderLibraryAgent(args: {
+  library: "query" | "router";
+  version: string;
+  skillPath: string;   // registry/skills/<lib>/<version>/SKILL.md
+  outDir: string;      // registry/agents
+}) {
+  fs.mkdirSync(args.outDir, { recursive: true });
+
+  const name = `tanstack-${args.library}`;
+  const lines: string[] = [];
+
+  lines.push(`# ${name}`);
+  lines.push(``);
+  lines.push(`Routes requests to TanStack **${args.library}** skills using progressive disclosure.`);
+  lines.push(``);
+  lines.push(`## When to use`);
+  lines.push(`Use when the user asks about TanStack ${args.library} concepts, APIs, patterns, or troubleshooting.`);
+  lines.push(``);
+  lines.push(`## Routing algorithm`);
+  lines.push(`1) If the request is not about TanStack ${args.library}, stop.`);
+  lines.push(`2) Otherwise, open: \`${args.skillPath}\``);
+  lines.push(`3) Use its Routing table to pick a topic slug, then open the referenced doc section/file.`);
+  lines.push(``);
+  lines.push(`## Boundaries`);
+  lines.push(`- Do not load unrelated skills.`);
+  lines.push(`- Do not infer behavior not present in the docs snapshot.`);
+  lines.push(``);
+
+  fs.writeFileSync(path.join(args.outDir, `${name}.md`), lines.join("\n") + "\n");
+}

packages/skillc/src/renderSkill.ts

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function renderSkillMd(args: {
+  library: string;
+  version: string;
+  outDir: string;          // registry/skills/<lib>/<version>
+}) {
+  const indexPath = path.join(args.outDir, "index.json");
+  if (!fs.existsSync(indexPath)) throw new Error(`Missing ${indexPath}`);
+
+  const idx = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+  const topics: Array<{ slug: string; title: string; kind: string }> = idx.topics;
+
+  const lines: string[] = [];
+  lines.push(`# TanStack ${args.library} skill`);
+  lines.push(``);
+  lines.push(`**Version:** \`${args.version}\``);
+  lines.push(``);
+  lines.push(`## What this skill is for`);
+  lines.push(`Use this skill to route TanStack ${args.library} questions to the right docs topic.`);
+  lines.push(``);
+  lines.push(`## Boundaries`);
+  lines.push(`- Do not run builds, tests, or repo automation.`);
+  lines.push(`- Do not guess behavior that is not in the docs snapshot.`);
+  lines.push(``);
+  lines.push(`## Routing`);
+  lines.push(`Pick the closest topic slug below, then open the referenced doc file/section.`);
+  lines.push(``);
+  lines.push(`| Topic | Slug |`);
+  lines.push(`|---|---|`);
+
+  // keep the table compact: show pages + sections
+  for (const t of topics.slice(0, 250)) {
+    lines.push(`| ${t.title.replace(/\|/g, "\\|")} | \`${t.slug}\` |`);
+  }
+
+  if (topics.length > 250) {
+    lines.push(``);
+    lines.push(`(Index truncated in this view; see \`index.json\` for full list.)`);
+  }
+
+  fs.writeFileSync(path.join(args.outDir, "SKILL.md"), lines.join("\n") + "\n");
+}

packages/skillc/src/renderTanstackAgent.ts

@@ -0,0 +1,24 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function renderTanstackAgent(args: {
+  outDir: string; // registry/agents
+}) {
+  fs.mkdirSync(args.outDir, { recursive: true });
+
+  const lines: string[] = [];
+  lines.push(`# tanstack`);
+  lines.push(``);
+  lines.push(`Top-level router for TanStack libraries. Uses progressive disclosure.`);
+  lines.push(``);
+  lines.push(`## Routing algorithm`);
+  lines.push(`1) Determine the library: query vs router/start.`);
+  lines.push(`2) If query: use \`tanstack-query\`.`);
+  lines.push(`3) If router or start: use \`tanstack-router\`.`);
+  lines.push(``);
+  lines.push(`## Boundaries`);
+  lines.push(`- Do not open library skills unless the library applies.`);
+  lines.push(``);
+
+  fs.writeFileSync(path.join(args.outDir, `tanstack.md`), lines.join("\n") + "\n");
+}

registry/agents/tanstack-query.md

@@ -0,0 +1,16 @@
+# tanstack-query
+
+Routes requests to TanStack **query** skills using progressive disclosure.
+
+## When to use
+Use when the user asks about TanStack query concepts, APIs, patterns, or troubleshooting.
+
+## Routing algorithm
+1) If the request is not about TanStack query, stop.
+2) Otherwise, open: `registry/skills/query/main/SKILL.md`
+3) Use its Routing table to pick a topic slug, then open the referenced doc section/file.
+
+## Boundaries
+- Do not load unrelated skills.
+- Do not infer behavior not present in the docs snapshot.
+

registry/agents/tanstack-router.md

@@ -0,0 +1,16 @@
+# tanstack-router
+
+Routes requests to TanStack **router** skills using progressive disclosure.
+
+## When to use
+Use when the user asks about TanStack router concepts, APIs, patterns, or troubleshooting.
+
+## Routing algorithm
+1) If the request is not about TanStack router, stop.
+2) Otherwise, open: `registry/skills/router/main/SKILL.md`
+3) Use its Routing table to pick a topic slug, then open the referenced doc section/file.
+
+## Boundaries
+- Do not load unrelated skills.
+- Do not infer behavior not present in the docs snapshot.
+

registry/agents/tanstack.md

@@ -0,0 +1,12 @@
+# tanstack
+
+Top-level router for TanStack libraries. Uses progressive disclosure.
+
+## Routing algorithm
+1) Determine the library: query vs router/start.
+2) If query: use `tanstack-query`.
+3) If router or start: use `tanstack-router`.
+
+## Boundaries
+- Do not open library skills unless the library applies.
+