@mrclrchtr/supi-web 1.5.0 → 1.7.0

package/README.md

@@ -20,73 +20,75 @@ After editing the source, run `/reload`.
 
 After install, pi gets three tools:
 
-- `web_fetch_md` — fetch a web page and convert it to Markdown
-- `web_docs_search` — search Context7 for a library ID
-- `web_docs_fetch` — fetch up-to-date documentation for a specific Context7 library
+| Tool | Purpose |
+|------|---------|
+| `web_fetch_md` | Fetch a web page and convert it to clean Markdown for LLM ingestion |
+| `web_docs_search` | Search Context7 for library IDs and metadata before fetching docs |
+| `web_docs_fetch` | Fetch up-to-date documentation for a known Context7 library |
 
-## Choose the right tool
+## `web_fetch_md`
 
-### `web_fetch_md`
+Fetches a public URL and returns clean Markdown.
 
-Use this for general web pages.
+### Parameters
 
-Important behavior:
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `url` | string | ✓ | — | `http://` or `https://` URL to fetch |
+| `output_mode` | `"auto"` \| `"inline"` \| `"file"` | — | `"auto"` | How to return the result |
+| `abs_links` | boolean | — | `true` | Absolutize relative links and images |
+| `timeout_ms` | number | — | `30000` | Fetch timeout in milliseconds |
 
-- accepts only real `http://` or `https://` URLs
-- defaults to `output_mode: auto`
-- returns Markdown inline when the result is at most **15,000 characters**
-- otherwise writes the Markdown to a temporary `.md` file and returns the file path
-- absolutizes links and image URLs by default
-- wraps plain-text responses as fenced code blocks instead of pretending they are prose
+### Output modes
 
-The fetch pipeline tries several strategies in order:
+- **`auto`** — returns Markdown inline if ≤15,000 characters; otherwise writes to a temporary file and returns the path
+- **`inline`** — always returns Markdown inline
+- **`file`** — always writes to a temporary file and returns the path
 
-1. Markdown-aware content negotiation
-2. content sniffing
-3. sibling `.md` / `.markdown` probing
-4. HTML fetch followed by Readability + Turndown conversion
+### Behavior
 
-### `web_docs_search`
+- Only accepts real `http://` or `https://` URLs
+- Access-controlled pages (login, paywall) should be skipped — ask the user for an allowed source instead
+- Plain-text responses are wrapped in fenced code blocks
+- Links and images are absolutized by default; set `abs_links: false` to keep them relative
 
-Use this when you need a Context7 library ID first.
+## `web_docs_search`
 
-It returns a Markdown table of matching libraries with fields such as:
+Searches Context7 for library IDs before fetching documentation.
 
-- ID
-- name
-- description
-- trust score
-- benchmark score
-- snippet count
-- versions
+### Parameters
 
-### `web_docs_fetch`
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `library_name` | string | ✓ | Library name to search for (e.g. `"react"`, `"next.js"`) |
+| `query` | string | ✓ | What you're trying to do — used for relevance ranking |
 
-Use this when you already know the Context7 library ID and want current docs or snippets for a specific question.
+Results return as a Markdown table with library ID, name, description, trust score, benchmark score, snippet count, and available versions.
 
-- `library_id` is required
-- `query` is required
-- `raw: true` returns JSON-serialized snippet objects instead of plain text Markdown
+## `web_docs_fetch`
 
-## Context7 notes
+Retrieves documentation context for a known Context7 library.
 
-`web_docs_search` and `web_docs_fetch` use Context7 through `@upstash/context7-sdk`.
+### Parameters
 
-If `CONTEXT7_API_KEY` is set, the SDK will use it automatically.
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `library_id` | string | ✓ | — | Context7 library ID (e.g. `/facebook/react`, `/vercel/next.js`) |
+| `query` | string | ✓ | — | Specific question about the library |
+| `raw` | boolean | — | `false` | When `true`, returns JSON-serialized snippet objects instead of Markdown |
 
-## Package surfaces
+Default mode returns pre-formatted Markdown. Set `raw: true` when you need structured JSON for programmatic use.
 
-- `@mrclrchtr/supi-web/api` — conversion helpers, fetch helpers, and extension exports
-- `@mrclrchtr/supi-web/extension` — extension entrypoint that registers all three tools
+## Typical workflow
 
-## Source
+1. **`web_docs_search`** — find the right library ID
+2. **Pick a `library_id`** from the results
+3. **`web_docs_fetch`** — retrieve focused, version-aware docs
 
-- `src/web.ts` — `web_fetch_md`
-- `src/docs.ts` — `web_docs_search` and `web_docs_fetch`
-- `src/fetch.ts` — HTTP fetching and negotiation
-- `src/convert.ts` — HTML-to-Markdown conversion
-- `src/context7-client.ts` — Context7 client wrapper
-- `src/temp-file.ts` — temp-file output helper
-- `src/tool/web-fetch-md-guidance.ts` — model-facing prompt surfaces for `web_fetch_md`
-- `src/tool/web-docs-search-guidance.ts` — model-facing prompt surfaces for `web_docs_search`
-- `src/tool/web-docs-fetch-guidance.ts` — model-facing prompt surfaces for `web_docs_fetch`
+Skip step 1 if you already know the exact Context7 `library_id`.
+
+## Context7 API key
+
+`web_docs_search` and `web_docs_fetch` use [Context7](https://context7.com/) through `@upstash/context7-sdk`.
+
+If `CONTEXT7_API_KEY` is set in your environment, the SDK uses it automatically for higher rate limits. Without a key, the tools still work with lower defaults.

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,8 @@
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -28,6 +29,9 @@
     },
     "@earendil-works/pi-tui": {
       "optional": true
+    },
+    "typebox": {
+      "optional": true
     }
   },
   "main": "src/api.ts",

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -1,11 +1,12 @@
 // supi-core — shared infrastructure for SuPi extensions.
 // Provides XML context tag wrapping, unified config system, context-message utilities,
-// and settings registry for supi-wide TUI settings.
+// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
 
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
+  readJsonFile,
   removeSupiConfigKey,
   writeSupiConfig,
 } from "./config/config.ts";
@@ -83,3 +84,13 @@ export {
   signalWaiting,
   WAITING_SYMBOL,
 } from "./terminal.ts";
+export type { SuiPiToolPromptSurface, SuiPiToolSpec, ToolExecuteFn } from "./tool-framework.ts";
+export {
+  CharacterParam,
+  derivePromptSurface,
+  FileParam,
+  LineParam,
+  MaxResultsParam,
+  registerSuiPiTools,
+  SymbolParam,
+} from "./tool-framework.ts";

package/node_modules/@mrclrchtr/supi-core/src/config/config.ts

@@ -20,7 +20,7 @@ function getProjectConfigPath(cwd: string): string {
   return path.join(cwd, PROJECT_CONFIG_DIR, CONFIG_FILE);
 }
 
-function readJsonFile(filePath: string): Record<string, unknown> | null {
+export function readJsonFile(filePath: string): Record<string, unknown> | null {
   let content: string;
   try {
     content = fs.readFileSync(filePath, "utf-8");

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -1,11 +1,12 @@
 // supi-core — shared infrastructure for SuPi extensions.
 // Provides XML context tag wrapping, unified config system, context-message utilities,
-// and settings registry for supi-wide TUI settings.
+// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
 
 export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
+  readJsonFile,
   removeSupiConfigKey,
   writeSupiConfig,
 } from "./config/config.ts";
@@ -83,3 +84,13 @@ export {
   signalWaiting,
   WAITING_SYMBOL,
 } from "./terminal.ts";
+export type { SuiPiToolPromptSurface, SuiPiToolSpec, ToolExecuteFn } from "./tool-framework.ts";
+export {
+  CharacterParam,
+  derivePromptSurface,
+  FileParam,
+  LineParam,
+  MaxResultsParam,
+  registerSuiPiTools,
+  SymbolParam,
+} from "./tool-framework.ts";

package/node_modules/@mrclrchtr/supi-core/src/tool-framework.ts

@@ -0,0 +1,116 @@
+// Shared tool framework for SuPi extensions.
+//
+// Provides a standard ToolSpec→PromptSurface→registerTool pipeline so
+// individual packages do not duplicate spec interfaces, guidance derivation,
+// registration loops, or common TypeBox parameter schemas.
+
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { type TSchema, Type } from "typebox";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Minimum contract for a SuPi tool definition. */
+export interface SuiPiToolSpec {
+  name: string;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+  parameters: TSchema;
+}
+
+/** Derived prompt surface — what pi flattens into the system prompt. */
+export interface SuiPiToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Guidance derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Static derivation: copies spec fields into a prompt surface.
+ *
+ * Packages that need dynamic guidance (e.g. server-coverage injection) should
+ * build their own surfaces, optionally starting from the output of this helper.
+ */
+export function derivePromptSurface(spec: SuiPiToolSpec): SuiPiToolPromptSurface {
+  return {
+    description: spec.description,
+    promptSnippet: spec.promptSnippet,
+    promptGuidelines: [...spec.promptGuidelines],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+// biome-ignore lint/complexity/useMaxParams: matches pi ToolDefinition.execute signature
+export type ToolExecuteFn = (
+  toolCallId: string,
+  params: unknown,
+  signal: AbortSignal | undefined,
+  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
+  ctx: ExtensionContext,
+) => Promise<AgentToolResult<Record<string, unknown>>>;
+
+/**
+ * Register a set of tools from specs + pre-derived surfaces.
+ *
+ * `createExecute` receives the spec and returns a pi-compatible execute
+ * function.  This keeps execute-logic package-local while the framework owns
+ * the declarative surface and registration boilerplate.
+ */
+export function registerSuiPiTools(
+  pi: ExtensionAPI,
+  specs: readonly SuiPiToolSpec[],
+  surfaces: Record<string, SuiPiToolPromptSurface>,
+  createExecute: (spec: SuiPiToolSpec) => ToolExecuteFn,
+): void {
+  for (const spec of specs) {
+    const surface = surfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface?.description ?? spec.description,
+      promptSnippet: surface?.promptSnippet ?? spec.promptSnippet,
+      promptGuidelines: surface?.promptGuidelines ?? [...spec.promptGuidelines],
+      parameters: spec.parameters,
+      execute: createExecute(spec),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared parameter builders
+// ---------------------------------------------------------------------------
+
+/** File path (relative or absolute). */
+export const FileParam = Type.String({ description: "File path (relative or absolute)" });
+
+/** 1-based line number. */
+export const LineParam = Type.Number({ description: "1-based line number", minimum: 1 });
+
+/** 1-based character column (UTF-16). */
+export const CharacterParam = Type.Number({
+  description: "1-based column number (UTF-16)",
+  minimum: 1,
+});
+
+/** Symbol name for discovery-based resolution. */
+export const SymbolParam = Type.String({
+  description: "Symbol name for discovery-based resolution",
+});
+
+/** Maximum results to return. */
+export const MaxResultsParam = Type.Number({ description: "Maximum results to return" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-web",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "SuPi Web extension — fetch web pages as clean Markdown (web_fetch_md) and library docs via Context7 (web_docs_search, web_docs_fetch)",
   "license": "MIT",
   "repository": {
@@ -25,7 +25,7 @@
     "@mozilla/readability": "^0.6.0",
     "turndown": "^7.2.0",
     "turndown-plugin-gfm": "^1.0.2",
-    "@mrclrchtr/supi-core": "1.5.0"
+    "@mrclrchtr/supi-core": "1.7.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"