veryfront 0.1.49 → 0.1.51

package/src/src/errors/logging.ts

@@ -6,6 +6,7 @@
  */
 
 import { isProduction } from "../build/config/environment.js";
+import { serverLogger } from "../utils/logger/logger.js";
 import { VeryfrontError } from "./types.js";
 
 export interface ErrorLogEntry {
@@ -50,23 +51,24 @@ export function logError(
   };
 
   if (isProduction()) {
-    // Structured JSON for log aggregation systems
+    // Direct JSON output — this module owns its own structured format
+    // (slug, category, status, docs) which differs from the logger envelope.
     console.error(JSON.stringify(entry));
   } else {
     // Human-readable format for development
-    console.error(`[ERROR] ${error.slug} (${error.category}) — ${error.title}`);
+    serverLogger.error(`[ERROR] ${error.slug} (${error.category}) — ${error.title}`);
     if (error.detail) {
-      console.error(`  Detail: ${error.detail}`);
+      serverLogger.error(`  Detail: ${error.detail}`);
     }
     if (error.suggestion) {
-      console.error(`  💡 Suggestion: ${error.suggestion}`);
+      serverLogger.error(`  💡 Suggestion: ${error.suggestion}`);
     }
-    console.error(`  📚 Docs: ${entry.docs}`);
+    serverLogger.error(`  📚 Docs: ${entry.docs}`);
     const mergedContext = context
       ? { ...(error.context as Record<string, unknown> ?? {}), ...context }
       : error.context;
     if (mergedContext) {
-      console.error(`  Context: ${JSON.stringify(mergedContext, null, 2)}`);
+      serverLogger.error(`  Context: ${JSON.stringify(mergedContext, null, 2)}`);
     }
   }
 }

package/src/src/errors/types.ts

@@ -43,6 +43,8 @@ export interface ErrorDefinition {
  * Options for creating an error instance
  */
 export interface ErrorCreateOptions {
+  /** Override the error message (defaults to detail or definition title) */
+  message?: string;
   detail?: string;
   cause?: unknown;
   instance?: string;
@@ -65,7 +67,7 @@ export function defineError(definition: ErrorDefinition): RegisteredError {
   return {
     ...definition,
     create(options?: ErrorCreateOptions): VeryfrontError {
-      return new VeryfrontError(options?.detail || definition.title, {
+      return new VeryfrontError(options?.message || options?.detail || definition.title, {
         slug: definition.slug,
         category: definition.category,
         status: options?.status ?? definition.status,

package/src/src/errors/veryfront-error.ts

@@ -54,7 +54,7 @@ export interface FileContext {
   permissions?: string;
 }
 
-export interface NetworkContext {
+interface NetworkContext {
   url?: string;
   timeout?: number;
   retryCount?: number;
@@ -93,7 +93,6 @@ export const isBuildError = isErrorType("build");
 export const isAPIError = isErrorType("api");
 export const isRenderError = isErrorType("render");
 export const isConfigError = isErrorType("config");
-export const isAgentError = isErrorType("agent");
 export const isFileError = isErrorType("file");
 export const isNetworkError = isErrorType("network");
 

package/src/src/html/dev-scripts.ts

@@ -52,7 +52,7 @@ export function getProdScripts(slug: string, nonce?: string): string {
   <script type="module" src="/_veryfront/hydrate.js?slug=${encodedSlug}"${nonceAttr}></script>`;
 }
 
-export interface StudioScriptOptions {
+interface StudioScriptOptions {
   projectId: string;
   pageId: string;
   pagePath?: string;

package/src/src/html/hydration-script-builder/dev-error-logger.ts

@@ -21,7 +21,7 @@ export function generateDevErrorLoggerScript(nonce?: string): string {
               timestamp: new Date().toISOString()
             })
           }).catch(() => {});
-        } catch {}
+        } catch (_) { /* expected: fire-and-forget log, network errors ignored */ }
       };
 
       window.addEventListener('error', (event) => {

package/src/src/html/hydration-script-builder/dev-scripts.ts

@@ -16,7 +16,7 @@ function generateHMRScript(
   return `<script type="module" src="/_veryfront/hmr.js"${nonceAttr}></script>`;
 }
 
-export interface DevScriptsOptions {
+interface DevScriptsOptions {
   /** Skip hmr.js when preview-hmr.js will be used (proxy mode) */
   skipDevHMR?: boolean;
   /** Skip error logger when endpoint is not available (preview mode) */

package/src/src/html/hydration-script-builder/templates/renderer.ts

@@ -6,7 +6,8 @@ export const getRendererScript = () => `
         const input = typeof pathname === 'string' ? pathname : window.location.pathname;
         try {
           return new URL(input, window.location.origin).pathname || '/';
-        } catch {
+        } catch (_) {
+          /* expected: invalid URL input, fall back to string splitting */
           const [pathOnly] = String(input || '/').split(/[?#]/);
           return pathOnly || '/';
         }
@@ -155,8 +156,8 @@ export const getRendererScript = () => `
           window.history.replaceState({ pageData, scrollY: 0 }, '', window.location.href);
           log('Stored initial page data in history state');
         }
-      } catch {
-        // ignore parse errors
+      } catch (_) {
+        /* expected: hydration data JSON parse errors are non-critical */
       }
     }
 

package/src/src/html/hydration-script-builder/templates/router.ts

@@ -522,10 +522,10 @@ export const getRouterScript = () => `
       domain: window.location.origin,
       path: window.location.pathname,
       push: (path) => {
-        navigateSPA(path, true);
+        void navigateSPA(path, true);
       },
       replace: (path) => {
-        navigateSPA(path, false);
+        void navigateSPA(path, false);
       },
       back: () => {
         window.history.back();
@@ -608,7 +608,7 @@ export const getRouterScript = () => `
       }
 
       e.preventDefault();
-      navigateSPA(href, true);
+      void navigateSPA(href, true);
     });
 
     let currentHoverLink = null;
@@ -662,7 +662,8 @@ export const getRouterScript = () => `
     window.useRouter = () => {
       try {
         return useRouterFromModule();
-      } catch {
+      } catch (_) {
+        /* expected: useRouterFromModule may not be available, fall back to global router */
         return window.__veryfrontRouter;
       }
     };

package/src/src/html/styles-builder/css-hash-cache.ts

@@ -44,7 +44,7 @@ export interface CSSCacheEntry {
  * CSS inputs cache entry - stores the inputs needed to regenerate CSS.
  * Keyed by CSS hash, stores candidates and stylesheet for JIT regeneration.
  */
-export interface CSSInputsCacheEntry {
+interface CSSInputsCacheEntry {
   candidates: string[];
   stylesheet: string;
 }
@@ -78,27 +78,28 @@ interface DistributedCacheInitOptions {
   initFailureLog: string;
 }
 
-function getOrInitializeDistributedCache(
+async function getOrInitializeDistributedCache(
   options: DistributedCacheInitOptions,
 ): Promise<CacheBackend> {
   const existing = options.getCache();
-  if (existing) return Promise.resolve(existing);
+  if (existing) return existing;
 
   const pending = options.getCacheInitPromise();
   if (pending) return pending;
 
-  const initPromise = createCacheBackend({ keyPrefix: options.keyPrefix })
-    .then((backend) => {
+  const initPromise = (async () => {
+    try {
+      const backend = await createCacheBackend({ keyPrefix: options.keyPrefix });
       options.setCache(backend);
       logger.debug(options.initializedLog, { type: backend.type });
       return backend;
-    })
-    .catch((error) => {
+    } catch (error) {
       logger.warn(options.initFailureLog, { error });
       const fallback = new MemoryCacheBackend(options.localFallbackSize);
       options.setCache(fallback);
       return fallback;
-    });
+    }
+  })();
 
   options.setCacheInitPromise(initPromise);
   return initPromise;

package/src/src/html/styles-builder/css-pregeneration.ts

@@ -11,7 +11,7 @@ import { extractCandidatesFromFiles, getProjectCSS } from "./tailwind-compiler.j
 
 const logger = serverLogger.component("css-pregeneration");
 
-export interface CSSPregenerationOptions {
+interface CSSPregenerationOptions {
   /** Project slug for cache keying */
   projectSlug: string;
   /** List of files with content to extract candidates from */

package/src/src/html/styles-builder/index.ts

@@ -11,7 +11,6 @@ export {
   extractCandidates,
   extractCandidatesFromFiles,
   formatCSSError,
-  generateTailwind4CSS,
   generateTailwindCSS,
   getCSSByHash,
   getProjectCSS,

package/src/src/html/styles-builder/plugin-loader.ts

@@ -13,14 +13,20 @@ import plugin from "tailwindcss/plugin";
 import defaultTheme from "tailwindcss/defaultTheme";
 import colors from "tailwindcss/colors";
 import { serverLogger } from "../../utils/index.js";
+import {
+  type ErrorSlug,
+  getErrorBySlug,
+  IMPORT_RESOLUTION_ERROR,
+  NETWORK_ERROR,
+  VeryfrontError,
+} from "../../errors/index.js";
 
 const logger = serverLogger.component("tailwind");
 
 // Provide localStorage shim for plugins that use util-deprecate (which checks localStorage)
 // This prevents "LocalStorage is not supported in this context" errors in Deno.
 try {
-  // deno-lint-ignore no-explicit-any
-  const _test = (dntShim.dntGlobalThis as any).localStorage;
+  void (dntShim.dntGlobalThis as Record<string, unknown>).localStorage;
 } catch {
   const localStorageShim = {
     getItem: () => null,
@@ -107,13 +113,15 @@ export async function loadModuleFromEsmSh(packageName: string): Promise<unknown>
 
   const stubResponse = await dntShim.fetch(stubUrl);
   if (!stubResponse.ok) {
-    throw new Error(`Failed to fetch stub: ${stubResponse.status}`);
+    throw NETWORK_ERROR.create({ detail: `Failed to fetch stub: ${stubResponse.status}` });
   }
   const stubCode = await stubResponse.text();
 
   const bundleMatch = stubCode.match(/from\s*["'](\/[^"']+\.bundle\.mjs)["']/);
   if (!bundleMatch) {
-    throw new Error(`Could not find bundle path in esm.sh response: ${stubCode.substring(0, 200)}`);
+    throw IMPORT_RESOLUTION_ERROR.create({
+      detail: `Could not find bundle path in esm.sh response: ${stubCode.substring(0, 200)}`,
+    });
   }
 
   const bundleUrl = `https://esm.sh${bundleMatch[1]}`;
@@ -121,13 +129,15 @@ export async function loadModuleFromEsmSh(packageName: string): Promise<unknown>
 
   const bundleResponse = await dntShim.fetch(bundleUrl);
   if (!bundleResponse.ok) {
-    throw new Error(`Failed to fetch bundle: ${bundleResponse.status}`);
+    throw NETWORK_ERROR.create({ detail: `Failed to fetch bundle: ${bundleResponse.status}` });
   }
   let code = await bundleResponse.text();
 
   // Step 3: Verify it's actually JavaScript (not an HTML error page)
   if (code.trimStart().startsWith("<!") || code.trimStart().startsWith("<html")) {
-    throw new Error(`esm.sh returned HTML instead of JavaScript for ${packageName}`);
+    throw IMPORT_RESOLUTION_ERROR.create({
+      detail: `esm.sh returned HTML instead of JavaScript for ${packageName}`,
+    });
   }
 
   // Step 4: Rewrite tailwindcss imports to use global shims
@@ -160,11 +170,12 @@ export async function loadModuleFromEsmSh(packageName: string): Promise<unknown>
 export async function loadPlugin(
   id: string,
   pluginCache: Map<string, unknown>,
-  pluginErrors: Map<string, string>,
+  pluginErrors: Map<string, Error>,
 ): Promise<unknown> {
+  const cachedError = pluginErrors.get(id);
+  if (cachedError) throw cachedError;
+
   if (pluginCache.has(id)) {
-    const errorMsg = pluginErrors.get(id);
-    if (errorMsg) throw new Error(errorMsg);
     return pluginCache.get(id);
   }
 
@@ -180,20 +191,9 @@ export async function loadPlugin(
       logger.debug("Loading plugin from node_modules", { id });
       try {
         mod = await import(id);
-      } catch (importError) {
+      } catch {
         logger.debug("Plugin not found in node_modules, falling back to esm.sh", { id });
-        try {
-          mod = await loadModuleFromEsmSh(id);
-        } catch {
-          const errorMsg = `Failed to load plugin "${id}": plugin not installed`;
-          logger.warn("Plugin not installed", {
-            id,
-            error: importError instanceof Error ? importError.message : String(importError),
-          });
-          pluginErrors.set(id, errorMsg);
-          pluginCache.set(id, null);
-          throw new Error(errorMsg);
-        }
+        mod = await loadModuleFromEsmSh(id);
       }
     }
 
@@ -201,11 +201,31 @@ export async function loadPlugin(
     pluginCache.set(id, pluginExport);
     return pluginExport;
   } catch (error) {
-    const errorMsg = `Failed to load plugin "${id}": ${
-      error instanceof Error ? error.message : String(error)
-    }`;
-    logger.warn(`${errorMsg}`);
-    pluginErrors.set(id, errorMsg);
-    throw new Error(errorMsg);
+    const wrappedError = wrapPluginError(id, error);
+    logger.warn(wrappedError.message);
+    pluginErrors.set(id, wrappedError);
+    throw wrappedError;
+  }
+}
+
+function wrapPluginError(id: string, error: unknown): Error {
+  const detail = `Failed to load plugin "${id}": ${
+    error instanceof Error ? error.message : String(error)
+  }`;
+
+  if (error instanceof VeryfrontError) {
+    return getErrorBySlug(error.slug as ErrorSlug).create({
+      detail,
+      cause: error.cause,
+      context: error.context,
+      instance: error.instance,
+      status: error.status,
+    });
   }
+
+  if (error instanceof Error) {
+    return new Error(detail, { cause: error });
+  }
+
+  return IMPORT_RESOLUTION_ERROR.create({ detail });
 }

package/src/src/html/styles-builder/project-css-cache.ts

@@ -27,7 +27,7 @@ const tailwindLog = logger.component("tailwind");
 // Types
 // ============================================================================
 
-export interface ProjectCSSCacheEntry {
+interface ProjectCSSCacheEntry {
   css: string;
   hash: string;
   candidatesHash: string;
@@ -37,7 +37,7 @@ interface ProjectCSSLocalEntry extends ProjectCSSCacheEntry {
   expiresAt: number;
 }
 
-export interface ProjectCSSRequestContext {
+interface ProjectCSSRequestContext {
   projectSlug: string;
   stylesheet: string;
   candidatesHash: string;
@@ -46,7 +46,7 @@ export interface ProjectCSSRequestContext {
   cacheKey: string;
 }
 
-export interface ProjectCSSProfile {
+interface ProjectCSSProfile {
   minify?: boolean;
   environment?: string;
   buildMode?: "development" | "production";

package/src/src/html/styles-builder/tailwind-compiler-cache.ts

@@ -12,6 +12,7 @@ import * as dntShim from "../../../_dnt.shims.js";
 
 import { compile } from "tailwindcss";
 import { serverLogger } from "../../utils/index.js";
+import { DEPENDENCY_MISSING, NETWORK_ERROR } from "../../errors/index.js";
 import { getTailwindCSSUrl } from "../../utils/constants/cdn.js";
 import { registerCache } from "../../utils/memory/index.js";
 import { hashString } from "./candidate-extractor.js";
@@ -27,7 +28,7 @@ interface CompilerCacheEntry {
   compiler: Awaited<ReturnType<typeof compile>>;
   createdAt: number;
   pluginCache: Map<string, unknown>;
-  pluginErrors: Map<string, string>;
+  pluginErrors: Map<string, Error>;
 }
 
 const compilerCache = new Map<string, CompilerCacheEntry>();
@@ -50,7 +51,9 @@ async function getTailwindBaseCSS(): Promise<string> {
   try {
     const response = await dntShim.fetch(url);
     if (!response.ok) {
-      throw new Error(`Failed to fetch Tailwind CSS: ${response.status} ${response.statusText}`);
+      throw NETWORK_ERROR.create({
+        detail: `Failed to fetch Tailwind CSS: ${response.status} ${response.statusText}`,
+      });
     }
     tailwindBaseCSS = await response.text();
   } catch (error) {
@@ -97,7 +100,7 @@ export async function getCompiler(
 
   const tailwindBase = await getTailwindBaseCSS();
   const pluginCache = new Map<string, unknown>();
-  const pluginErrors = new Map<string, string>();
+  const pluginErrors = new Map<string, Error>();
 
   const newCompiler = await compile(stylesheet, {
     base: "/",
@@ -110,8 +113,12 @@ export async function getCompiler(
     },
     loadModule: async (id: string) => {
       const loaded = await loadPlugin(id, pluginCache, pluginErrors);
-      if (!loaded) throw new Error(`Failed to load plugin "${id}": plugin not installed`);
-      // deno-lint-ignore no-explicit-any
+      if (!loaded) {
+        throw DEPENDENCY_MISSING.create({
+          detail: `Failed to load plugin "${id}": plugin not installed`,
+        });
+      }
+      // deno-lint-ignore no-explicit-any -- dynamically loaded plugin cannot be statically verified against Tailwind's Plugin | Config type
       return { module: loaded as any, base: "/", path: "/" };
     },
   });

package/src/src/html/styles-builder/tailwind-compiler-utils.ts

@@ -2,25 +2,25 @@
  * Pure helper utilities for Tailwind compiler cache parsing and error classification.
  */
 
-export interface ParsedCSSCacheEntry {
+interface ParsedCSSCacheEntry {
   css: string;
   candidates: string[];
   stylesheet: string;
 }
 
-export interface ParsedProjectCSSCacheEntry {
+interface ParsedProjectCSSCacheEntry {
   css: string;
   hash: string;
   candidatesHash: string;
 }
 
-export interface CSSErrorDescriptor {
+interface CSSErrorDescriptor {
   title: string;
   message: string;
   suggestion: string;
 }
 
-export type ProjectCSSLocalCacheState = "miss" | "expired" | "mismatch" | "hit";
+type ProjectCSSLocalCacheState = "miss" | "expired" | "mismatch" | "hit";
 
 interface RawCSSCacheEntry {
   css?: unknown;
@@ -89,7 +89,8 @@ function tryParseStructuredCSSCacheEntry(
       candidates: isStringArray(parsed.candidates) ? parsed.candidates : [],
       stylesheet: typeof parsed.stylesheet === "string" ? parsed.stylesheet : defaultStylesheet,
     };
-  } catch {
+  } catch (_) {
+    /* expected: malformed JSON in CSS cache entry */
     return undefined;
   }
 }
@@ -110,7 +111,8 @@ export function parseProjectCSSCacheEntry(raw: string): ParsedProjectCSSCacheEnt
       hash: parsed.hash,
       candidatesHash: parsed.candidatesHash,
     };
-  } catch {
+  } catch (_) {
+    /* expected: malformed JSON in project CSS cache entry */
     return undefined;
   }
 }

package/src/src/html/styles-builder/tailwind-compiler.ts

@@ -1,8 +1,9 @@
 import { serverLogger } from "../../utils/index.js";
+import { COMPILATION_ERROR } from "../../errors/index.js";
 import { withSpan } from "../../observability/tracing/otlp-setup.js";
 import { SpanNames } from "../../observability/tracing/span-names.js";
 import { minifyCSS } from "../../build/asset-pipeline/tailwind-processor/css-utils.js";
-import { extractCandidates, hashCSS } from "./candidate-extractor.js";
+import { hashCSS } from "./candidate-extractor.js";
 import { formatCSSErrorMessage } from "./tailwind-compiler-utils.js";
 import { getCompiler } from "./tailwind-compiler-cache.js";
 import {
@@ -112,9 +113,10 @@ export async function getProjectCSS(
         error: formatted.message,
         suggestion: formatted.suggestion,
       });
-      throw new Error(
-        `[tailwind] ${formatted.title}: ${formatted.message} Suggestion: ${formatted.suggestion}`,
-      );
+      throw COMPILATION_ERROR.create({
+        detail:
+          `[tailwind] ${formatted.title}: ${formatted.message} Suggestion: ${formatted.suggestion}`,
+      });
     }
 
     const hash = hashCSS(result.css);
@@ -264,10 +266,3 @@ export function formatCSSError(error: Error | string): CSSErrorInfo {
   const message = typeof error === "string" ? error : error.message;
   return formatCSSErrorMessage(message);
 }
-
-/** @deprecated Use generateTailwindCSS with explicit candidates instead */
-export async function generateTailwind4CSS(html: string): Promise<string> {
-  const candidates = extractCandidates(html);
-  const result = await generateTailwindCSS(undefined, candidates);
-  return result.css;
-}

package/src/src/html/utils.ts

@@ -222,15 +222,15 @@ async function resolveVersions(
       if (deps.veryfront) {
         veryfrontVersion = stripSemverRange(deps.veryfront);
       }
-    } catch {
-      // Fall through to default
+    } catch (_) {
+      /* expected: package.json may not exist or be unreadable */
     }
   }
 
   return { react: reactVersion, veryfront: veryfrontVersion };
 }
 
-export interface BuildImportMapOptions {
+interface BuildImportMapOptions {
   projectDir?: string;
   config?: VeryfrontConfig;
   customImports?: Record<string, string>;

package/src/src/integrations/endpoint-executor.ts

@@ -10,6 +10,7 @@ import * as dntShim from "../../_dnt.shims.js";
 
 import { logger } from "../utils/index.js";
 import type { IntegrationEndpoint } from "./types.js";
+import { INVALID_ARGUMENT } from "../errors/index.js";
 
 interface ExecutionContext {
   integration: string;
@@ -35,7 +36,9 @@ async function executeGraphQL(
   ctx: ExecutionContext,
 ): Promise<{ result: unknown; status: number }> {
   if (!endpoint.query) {
-    throw new Error(`GraphQL endpoint for ${ctx.integration}:${ctx.toolId} missing query`);
+    throw INVALID_ARGUMENT.create({
+      detail: `GraphQL endpoint for ${ctx.integration}:${ctx.toolId} missing query`,
+    });
   }
 
   // Build variables from params
@@ -100,7 +103,7 @@ async function executeRest(
     if (def.in === "path") {
       const value = args[key];
       if (value === undefined) {
-        throw new Error(`Missing required path parameter: ${key}`);
+        throw INVALID_ARGUMENT.create({ detail: `Missing required path parameter: ${key}` });
       }
       url = url.replace(`{${key}}`, encodeURIComponent(String(value)));
     }

package/src/src/integrations/types.ts

@@ -12,7 +12,7 @@ export interface IntegrationEndpointParam {
   default?: unknown;
 }
 
-export interface IntegrationEndpointBodyField {
+interface IntegrationEndpointBodyField {
   type: "string" | "number" | "boolean" | "object" | "array";
   description: string;
   required?: boolean;

package/src/src/issues/core.ts

@@ -156,7 +156,8 @@ export function parseIssue(content: string, path: string): Issue | null {
   try {
     const metadata = validateMetadata(parseYaml(parsed.frontmatter));
     return { metadata, body: parsed.body, path };
-  } catch {
+  } catch (_) {
+    // expected: invalid or unparseable frontmatter metadata
     return null;
   }
 }
@@ -200,8 +201,8 @@ export class IssuesManager {
         const id = entry.name.replace(/\.md$/, "");
         if (ISSUE_ID_PATTERN.test(id)) ids.push(id);
       }
-    } catch {
-      // Directory doesn't exist yet
+    } catch (_) {
+      // expected: directory doesn't exist yet
     }
 
     return ids;
@@ -244,7 +245,8 @@ export class IssuesManager {
     try {
       const content = await this.fs.readTextFile(join(this.projectDir, path));
       return parseIssue(content, path);
-    } catch {
+    } catch (_) {
+      // expected: issue file may not exist
       return null;
     }
   }
@@ -287,7 +289,8 @@ export class IssuesManager {
     try {
       await this.fs.remove(join(this.projectDir, path));
       return true;
-    } catch {
+    } catch (_) {
+      // expected: issue file may not exist
       return false;
     }
   }

package/src/src/mcp/server.ts

@@ -131,8 +131,8 @@ export class MCPServer {
     if (this.integrationLoader && !this.integrationsLoaded) {
       try {
         this.integrationsLoaded = await this.loadIntegrationTools(this.integrationLoader);
-      } catch {
-        // Non-fatal: integration tools won't be available.
+      } catch (_) {
+        // expected: non-fatal integration loading failure; tools won't be available
         // Keep integrationsLoaded=false so a later tools/list can retry.
       }
     }
@@ -328,7 +328,8 @@ export class MCPServer {
       let rpcRequest: JSONRPCRequest;
       try {
         rpcRequest = await request.json();
-      } catch {
+      } catch (_) {
+        // expected: malformed JSON in request body
         return new dntShim.Response(
           JSON.stringify({
             jsonrpc: "2.0",

package/src/src/mcp/types.ts

@@ -6,12 +6,11 @@ import type { Prompt } from "../prompt/index.js";
 /**
  * Generic MCP tool definition
  */
-// deno-lint-ignore no-explicit-any
+// deno-lint-ignore no-explicit-any -- generic erasure: interface must accept any concrete Tool instantiation
 export interface MCPTool<TInput = any, TOutput = any> {
   name: string;
   description: string;
-  // Using ZodType with output type for compatibility with ZodDefault/ZodOptional
-  // deno-lint-ignore no-explicit-any
+  // deno-lint-ignore no-explicit-any -- ZodType Def/Input params require any for ZodDefault/ZodOptional compatibility
   inputSchema: z.ZodType<TInput, any, any>;
   execute: (input: TInput) => Promise<TOutput>;
 }