refactor: day-2 hotspot hardening with parser/context modules and tests

Author: timothytlewis

.github/workflows/ci.yml

@@ -18,4 +18,5 @@ jobs:
           cache: npm
           cache-dependency-path: package-lock.json
       - run: npm ci
-      - run: npx tsc --noEmit
+      - run: npm run typecheck
+      - run: npm test

command-line.test.ts

@@ -0,0 +1,21 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+import { parseCommandLine } from "./command-line";
+
+test("parseCommandLine handles quoted arguments", () => {
+  const [cmd, args] = parseCommandLine('npx "foo bar" --x');
+  assert.equal(cmd, "npx");
+  assert.deepEqual(args, ["foo bar", "--x"]);
+});
+
+test("parseCommandLine handles escaped spaces", () => {
+  const [cmd, args] = parseCommandLine("tool foo\\ bar baz");
+  assert.equal(cmd, "tool");
+  assert.deepEqual(args, ["foo bar", "baz"]);
+});
+
+test("parseCommandLine returns empty tuple for empty input", () => {
+  const [cmd, args] = parseCommandLine("");
+  assert.equal(cmd, "");
+  assert.deepEqual(args, []);
+});

command-line.ts

@@ -0,0 +1,47 @@
+export function parseCommandLine(cmd: string): [string, string[]] {
+  const args: string[] = [];
+  let current = "";
+  let inQuote = false;
+  let quoteChar = "";
+
+  for (let i = 0; i < cmd.length; i++) {
+    const char = cmd[i];
+
+    if (char === "\\" && i + 1 < cmd.length) {
+      current += cmd[++i];
+      continue;
+    }
+
+    if ((char === '"' || char === "'") && !inQuote) {
+      inQuote = true;
+      quoteChar = char;
+      continue;
+    }
+
+    if (char === quoteChar && inQuote) {
+      inQuote = false;
+      quoteChar = "";
+      continue;
+    }
+
+    if (char === " " && !inQuote) {
+      if (current) {
+        args.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (current) {
+    args.push(current);
+  }
+
+  if (args.length === 0) {
+    return ["", []];
+  }
+
+  return [args[0], args.slice(1)];
+}

context7.test.ts

@@ -0,0 +1,11 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+import { normaliseContext7LibraryId } from "./context7";
+
+test("normaliseContext7LibraryId keeps leading slash", () => {
+  assert.equal(normaliseContext7LibraryId("/reactjs/react.dev"), "/reactjs/react.dev");
+});
+
+test("normaliseContext7LibraryId adds leading slash", () => {
+  assert.equal(normaliseContext7LibraryId("reactjs/react.dev"), "/reactjs/react.dev");
+});

context7.ts

@@ -0,0 +1,45 @@
+const CONTEXT7_API_BASE_URL = "https://context7.com/api/v2";
+
+type Context7Endpoint = "libs/search" | "context";
+
+function getContext7Headers(): Record<string, string> {
+  const token = process.env.CONTEXT7_API_KEY?.trim();
+  const headers: Record<string, string> = {};
+
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+
+  return headers;
+}
+
+export async function callContext7Api(
+  endpoint: Context7Endpoint,
+  params: Record<string, string | number>,
+): Promise<string> {
+  const url = new URL(`${CONTEXT7_API_BASE_URL}/${endpoint}`);
+  for (const [key, value] of Object.entries(params)) {
+    url.searchParams.set(key, String(value));
+  }
+
+  const response = await fetch(url, {
+    headers: getContext7Headers(),
+  });
+
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(
+      `Context7 API error (${response.status} ${response.statusText}): ${text}`,
+    );
+  }
+
+  return text;
+}
+
+export function normaliseContext7LibraryId(libraryId: string): string {
+  const normalised = libraryId.trim();
+  if (normalised.startsWith("/")) {
+    return normalised;
+  }
+  return `/${normalised}`;
+}

main.ts

@@ -8,6 +8,8 @@ import { platform, tmpdir } from "os";
 import { spawn } from "child_process";
 import { join } from "path";
 import { z } from "zod";
+import { parseCommandLine } from "./command-line";
+import { callContext7Api, normaliseContext7LibraryId } from "./context7";
 
 const tmp = join(tmpdir(), "pkgx-mcp");
 
@@ -110,60 +112,6 @@ async function runPkgxCommand(program: string, args: string[], cwd?: string): Pr
   }
 }
 
-// Parse command line with proper quote handling
-function parseCommandLine(cmd: string): [string, string[]] {
-  const args: string[] = [];
-  let current = '';
-  let inQuote = false;
-  let quoteChar = '';
-
-  for (let i = 0; i < cmd.length; i++) {
-    const char = cmd[i];
-
-    if (char === '\\' && i + 1 < cmd.length) {
-      // Handle escaped characters
-      current += cmd[++i];
-      continue;
-    }
-
-    if ((char === '"' || char === "'") && !inQuote) {
-      // Start of quoted section
-      inQuote = true;
-      quoteChar = char;
-      continue;
-    }
-
-    if (char === quoteChar && inQuote) {
-      // End of quoted section
-      inQuote = false;
-      quoteChar = '';
-      continue;
-    }
-
-    if (char === ' ' && !inQuote) {
-      // Space outside quotes - split argument
-      if (current) {
-        args.push(current);
-        current = '';
-      }
-      continue;
-    }
-
-    current += char;
-  }
-
-  // Add the last argument if there is one
-  if (current) {
-    args.push(current);
-  }
-
-  if (args.length === 0) {
-    return ['', []];
-  }
-
-  return [args[0], args.slice(1)];
-}
-
 server.tool(
   "run-command-line",
   `
@@ -297,3 +245,102 @@ async function get_pkgx() {
     return filePath;
   }
 }
+
+server.tool(
+  "resolve-library-id",
+  `
+    Resolve a library name to Context7-compatible library IDs.
+    This can be used before querying documentation.
+  `,
+  {
+    libraryName: z.string().describe("The library name to search for, for example: react"),
+    query: z.string().describe("The question or task to rank matches by relevance"),
+  },
+  async ({ libraryName, query }) => {
+    try {
+      const responseText = await callContext7Api("libs/search", {
+        libraryName,
+        query,
+      });
+      return {
+        content: [{
+          type: "text",
+          text: responseText,
+        }],
+      };
+    } catch (error: any) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `resolve-library-id failed: ${error.message}` }],
+      };
+    }
+  }
+);
+
+server.tool(
+  "query-docs",
+  `
+    Fetch context-aware docs snippets for a Context7 library.
+    You must pass a Context7-compatible library ID, e.g. /reactjs/react.dev
+  `,
+  {
+    libraryId: z.string().describe("Context7 library ID, e.g. /reactjs/react.dev"),
+    query: z.string().describe("The question or task to fetch relevant docs for"),
+  },
+  async ({ libraryId, query }) => {
+    try {
+      const responseText = await callContext7Api("context", {
+        libraryId: normaliseContext7LibraryId(libraryId),
+        query,
+      });
+      return {
+        content: [{
+          type: "text",
+          text: responseText,
+        }],
+      };
+    } catch (error: any) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `query-docs failed: ${error.message}` }],
+      };
+    }
+  }
+);
+
+server.tool(
+  "get-library-docs",
+  `
+    Legacy Context7-compatible docs tool.
+    Fetch documentation for a Context7-compatible library ID.
+    Use resolve-library-id first unless you already have an ID.
+  `,
+  {
+    context7CompatibleLibraryID: z.string().describe("Context7-compatible library ID, e.g. /reactjs/react.dev"),
+    topic: z.string().default("").describe("Optional topic to focus docs lookup"),
+    tokens: z.number().int().min(1).default(10000).describe("Retained for compatibility; currently ignored"),
+    page: z.number().int().min(1).default(1).describe("Retained for compatibility; currently ignored"),
+  },
+  async ({ context7CompatibleLibraryID, topic }) => {
+    const requestedTopic = topic?.trim();
+    const query = requestedTopic ? `${requestedTopic} documentation` : "library documentation";
+
+    try {
+      const responseText = await callContext7Api("context", {
+        libraryId: normaliseContext7LibraryId(context7CompatibleLibraryID),
+        query,
+      });
+      return {
+        content: [{
+          type: "text",
+          text: responseText,
+        }],
+      };
+    } catch (error: any) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `get-library-docs failed: ${error.message}` }],
+      };
+    }
+  }
+);