@chat-js/cli 0.6.1 → 0.6.3

package/templates/chat-app/scripts/check-env.ts

@@ -5,6 +5,11 @@
  * Run via `bun run check-env` or automatically in prebuild.
  */
 import "dotenv/config";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// biome-ignore lint/performance/noNamespaceImport: TypeScript API requires namespace import due to extensive usage
+import * as ts from "typescript";
 import type { GatewayType } from "../lib/ai/gateways/registry";
 import { generatedForGateway } from "../lib/ai/models.generated";
 import { config } from "../lib/config";
@@ -23,6 +28,180 @@ interface ValidationError {
   missing: string[];
 }
 
+type StaticToolEnvVar = {
+  description?: string;
+  options: string[][];
+};
+
+type StaticToolEnvVars = StaticToolEnvVar[];
+
+type StaticToolMetadata = {
+  toolEnvVars: StaticToolEnvVars;
+};
+
+const projectRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+
+function unwrapExpression(node: ts.Expression): ts.Expression {
+  if (ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) {
+    return unwrapExpression(node.expression);
+  }
+  return node;
+}
+
+function readString(node: ts.Expression): string | null {
+  const expr = unwrapExpression(node);
+  if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) {
+    return expr.text;
+  }
+  return null;
+}
+
+function readStringArray(node: ts.Expression): string[] | null {
+  const expr = unwrapExpression(node);
+  if (!ts.isArrayLiteralExpression(expr)) {
+    return null;
+  }
+
+  const values: string[] = [];
+  for (const element of expr.elements) {
+    if (!ts.isExpression(element)) {
+      return null;
+    }
+    const value = readString(element);
+    if (value === null) {
+      return null;
+    }
+    values.push(value);
+  }
+
+  return values;
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: AST traversal logic is inherently complex
+function readToolEnvVar(node: ts.Expression): StaticToolEnvVar | null {
+  const expr = unwrapExpression(node);
+  if (!ts.isObjectLiteralExpression(expr)) {
+    return null;
+  }
+
+  let description: string | null = null;
+  let options: string[][] | null = null;
+
+  for (const property of expr.properties) {
+    if (!ts.isPropertyAssignment(property)) {
+      return null;
+    }
+
+    const nameNode = property.name;
+    const name =
+      ts.isIdentifier(nameNode) || ts.isStringLiteral(nameNode)
+        ? nameNode.text
+        : null;
+
+    if (name === "description") {
+      description = readString(property.initializer);
+    } else if (name === "options") {
+      const outer = unwrapExpression(property.initializer);
+      if (!ts.isArrayLiteralExpression(outer)) {
+        return null;
+      }
+
+      const groups: string[][] = [];
+      for (const element of outer.elements) {
+        if (!ts.isExpression(element)) {
+          return null;
+        }
+        const group = readStringArray(element);
+        if (group === null) {
+          return null;
+        }
+        groups.push(group);
+      }
+      options = groups;
+    }
+  }
+
+  return options ? { ...(description ? { description } : {}), options } : null;
+}
+
+function readToolEnvVars(node: ts.Expression): StaticToolEnvVars {
+  const expr = unwrapExpression(node);
+  if (!ts.isArrayLiteralExpression(expr)) {
+    return [];
+  }
+
+  const toolEnvVars: StaticToolEnvVars = [];
+  for (const element of expr.elements) {
+    if (!ts.isExpression(element)) {
+      return [];
+    }
+    const toolEnvVar = readToolEnvVar(element);
+    if (!toolEnvVar) {
+      return [];
+    }
+    toolEnvVars.push(toolEnvVar);
+  }
+
+  return toolEnvVars;
+}
+
+function readStaticToolMetadata(sourceText: string): StaticToolMetadata {
+  const sourceFile = ts.createSourceFile(
+    "tool.ts",
+    sourceText,
+    ts.ScriptTarget.ESNext,
+    true,
+    ts.ScriptKind.TS
+  );
+  const toolEnvVars: StaticToolEnvVars = [];
+
+  function visit(node: ts.Node): void {
+    if (
+      ts.isVariableStatement(node) &&
+      node.modifiers?.some(
+        (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword
+      )
+    ) {
+      for (const declaration of node.declarationList.declarations) {
+        if (declaration.name.getText() !== "toolEnvVars") {
+          continue;
+        }
+        const initializer = declaration.initializer;
+        if (initializer && ts.isExpression(initializer)) {
+          toolEnvVars.push(...readToolEnvVars(initializer));
+        }
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+
+  return {
+    toolEnvVars,
+  };
+}
+
+function resolveToolsDir(toolsPath: string): string {
+  if (toolsPath.startsWith("@/")) {
+    return path.resolve(projectRoot, toolsPath.slice(2));
+  }
+
+  if (toolsPath.startsWith("./") || toolsPath.startsWith("../")) {
+    return path.resolve(projectRoot, toolsPath);
+  }
+
+  if (path.isAbsolute(toolsPath)) {
+    return toolsPath;
+  }
+
+  return path.resolve(projectRoot, toolsPath);
+}
+
 function validateGatewayKey(env: NodeJS.ProcessEnv): ValidationError | null {
   // Prevent TS from narrowing to the current literal config value.
   const gateway = (() => config.ai.gateway as GatewayType)();
@@ -131,6 +310,52 @@ function validateAuthentication(env: NodeJS.ProcessEnv): ValidationError[] {
   return errors;
 }
 
+async function validateInstalledTools(
+  env: NodeJS.ProcessEnv
+): Promise<ValidationError[]> {
+  const toolsDir = resolveToolsDir(config.paths.tools);
+  const entries = await fs
+    .readdir(toolsDir, { withFileTypes: true })
+    .catch((error: NodeJS.ErrnoException) => {
+      if (error.code === "ENOENT") {
+        return [];
+      }
+      throw error;
+    });
+  const errors: ValidationError[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith("_")) {
+      continue;
+    }
+
+    const toolPath = path.join(toolsDir, entry.name, "tool.ts");
+    const exists = await fs
+      .access(toolPath)
+      .then(() => true)
+      .catch(() => false);
+
+    if (!exists) {
+      continue;
+    }
+
+    const toolSource = await fs.readFile(toolPath, "utf8");
+    const mod = readStaticToolMetadata(toolSource);
+
+    for (const toolEnvVar of mod.toolEnvVars) {
+      const missing = getMissingRequirement(toolEnvVar, env);
+      if (missing) {
+        errors.push({
+          feature: `tools.${entry.name}`,
+          missing: [missing],
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
 function validateBaseUrl(env: NodeJS.ProcessEnv): ValidationError | null {
   const isProduction = env.NODE_ENV === "production" || env.VERCEL === "1";
   if (!isProduction) {
@@ -157,7 +382,7 @@ function checkGatewaySnapshot(): string | null {
   return `models.generated.ts was built for "${generatedForGateway}" but config uses "${config.ai.gateway}". Run \`bun fetch:models\` to update the fallback snapshot.`;
 }
 
-function checkEnv(): void {
+async function checkEnv(): Promise<void> {
   const env = process.env;
   if (isPlaywrightTestEnvironment(env)) {
     console.log(
@@ -169,11 +394,13 @@ function checkEnv(): void {
   }
 
   const baseUrlError = validateBaseUrl(env);
+  const installedToolErrors = await validateInstalledTools(env);
   const errors = [
     ...(baseUrlError ? [baseUrlError] : []),
     ...validateFeatures(env),
     ...validateAiTools(env),
     ...validateAuthentication(env),
+    ...installedToolErrors,
   ];
 
   if (errors.length > 0) {
@@ -195,4 +422,4 @@ function checkEnv(): void {
   console.log("✅ Environment validation passed");
 }
 
-checkEnv();
+await checkEnv();

package/templates/chat-app/tools/chatjs/_shared/lib/tool-part.ts

@@ -0,0 +1,5 @@
+import type { Tool, UIToolInvocation } from "ai";
+
+export type ToolPartFromTool<T extends Tool> = UIToolInvocation<T>;
+
+export type TypelessToolPartFromTool<T extends Tool> = ToolPartFromTool<T>;

package/templates/chat-app/{components/part/weather.tsx → tools/chatjs/get-weather/renderer.tsx}

@@ -2,9 +2,11 @@
 
 import { format, isWithinInterval } from "date-fns";
 import { useIsMobile } from "@/hooks/use-mobile";
-import type { WeatherAtLocation } from "@/lib/ai/tools/get-weather";
-import type { ChatMessage } from "@/lib/ai/types";
 import { cn } from "@/lib/utils";
+import type { TypelessToolPartFromTool } from "@/tools/chatjs/_shared/lib/tool-part";
+import type { getWeather, WeatherAtLocation } from "./tool";
+
+type GetWeatherRendererTool = TypelessToolPartFromTool<typeof getWeather>;
 
 const SAMPLE = {
   latitude: 37.763_283,
@@ -165,11 +167,6 @@ function n(num: number): number {
   return Math.ceil(num);
 }
 
-export type WeatherTool = Extract<
-  ChatMessage["parts"][number],
-  { type: "tool-getWeather" }
->;
-
 function WeatherCard({
   weatherAtLocation,
 }: {
@@ -188,15 +185,10 @@ function WeatherCard({
   });
 
   const isMobile = useIsMobile();
-
   const hoursToShow = isMobile ? 5 : 6;
-
-  // Find the index of the current time or the next closest time
   const currentTimeIndex = weatherAtLocation.hourly.time.findIndex(
     (time) => new Date(time) >= new Date(weatherAtLocation.current.time)
   );
-
-  // Slice the arrays to get the desired number of items
   const displayTimes = weatherAtLocation.hourly.time.slice(
     currentTimeIndex,
     currentTimeIndex + hoursToShow
@@ -210,12 +202,8 @@ function WeatherCard({
     <div
       className={cn(
         "skeleton-bg flex max-w-[500px] flex-col gap-4 rounded-2xl p-4",
-        {
-          "bg-blue-400": isDay,
-        },
-        {
-          "bg-indigo-900": !isDay,
-        }
+        { "bg-blue-400": isDay },
+        { "bg-indigo-900": !isDay }
       )}
     >
       <div className="flex flex-row items-center justify-between">
@@ -223,12 +211,8 @@ function WeatherCard({
           <div
             className={cn(
               "skeleton-div size-10 rounded-full",
-              {
-                "bg-yellow-300": isDay,
-              },
-              {
-                "bg-indigo-100": !isDay,
-              }
+              { "bg-yellow-300": isDay },
+              { "bg-indigo-100": !isDay }
             )}
           />
           <div className="font-medium text-4xl text-blue-50">
@@ -249,12 +233,8 @@ function WeatherCard({
             <div
               className={cn(
                 "skeleton-div size-6 rounded-full",
-                {
-                  "bg-yellow-300": isDay,
-                },
-                {
-                  "bg-indigo-200": !isDay,
-                }
+                { "bg-yellow-300": isDay },
+                { "bg-indigo-200": !isDay }
               )}
             />
             <div className="text-blue-50 text-sm">
@@ -268,18 +248,24 @@ function WeatherCard({
   );
 }
 
-export function Weather({ tool }: { tool: WeatherTool }) {
-  const isLoading = tool.state === "input-available";
-  const weatherAtLocation: WeatherAtLocation =
-    tool.state === "output-available" ? tool.output : SAMPLE;
-
-  if (isLoading) {
+export function GetWeatherRenderer({
+  tool,
+}: {
+  tool: GetWeatherRendererTool;
+  messageId: string;
+  isReadonly: boolean;
+}) {
+  if (tool.state !== "output-available") {
     return (
       <div className="skeleton" key={tool.toolCallId}>
-        <WeatherCard weatherAtLocation={weatherAtLocation} />
+        <WeatherCard weatherAtLocation={SAMPLE} />
       </div>
     );
   }
 
-  return <WeatherCard weatherAtLocation={weatherAtLocation} />;
+  if (!tool.output) {
+    return <WeatherCard weatherAtLocation={SAMPLE} />;
+  }
+
+  return <WeatherCard weatherAtLocation={tool.output} />;
 }

package/templates/chat-app/{components/part/retrieve-url.tsx → tools/chatjs/retrieve-url/renderer.tsx}

@@ -1,14 +1,11 @@
 "use client";
 
 import { ChevronDown, ExternalLink, Globe, TextIcon } from "lucide-react";
-import Image from "next/image";
 import ReactMarkdown from "react-markdown";
-import type { ChatMessage } from "@/lib/ai/types";
+import type { TypelessToolPartFromTool } from "@/tools/chatjs/_shared/lib/tool-part";
+import type { retrieveUrl } from "./tool";
 
-export type RetrieveUrlTool = Extract<
-  ChatMessage["parts"][number],
-  { type: "tool-retrieveUrl" }
->;
+type RetrieveUrlRendererTool = TypelessToolPartFromTool<typeof retrieveUrl>;
 
 function LoadingState() {
   return (
@@ -77,13 +74,7 @@ function RetrievedContentHeader({ firstItem }: { firstItem: unknown }) {
       <div className="flex items-start gap-4">
         <div className="relative h-10 w-10 shrink-0">
           <div className="absolute inset-0 rounded-lg bg-linear-to-br from-primary/10 to-transparent" />
-          <Image
-            alt=""
-            className="absolute inset-0 m-auto"
-            height={20}
-            src={`https://www.google.com/s2/favicons?sz=64&domain_url=${encodeURIComponent(url)}`}
-            width={20}
-          />
+          <Globe className="absolute inset-0 m-auto h-5 w-5 text-primary/70" />
         </div>
         <div className="min-w-0 flex-1 space-y-2">
           <h2 className="truncate font-semibold text-foreground text-lg tracking-tight">
@@ -159,11 +150,25 @@ function getErrorMessage(result: unknown, firstItem: unknown): string | null {
   return topLevelError ?? firstItemError ?? null;
 }
 
-export function RetrieveUrl({ tool }: { tool: RetrieveUrlTool }) {
-  if (tool.state === "input-available") {
+export function RetrieveUrlRenderer({
+  tool,
+}: {
+  tool: RetrieveUrlRendererTool;
+  messageId: string;
+  isReadonly: boolean;
+}) {
+  if (tool.state === "input-available" || tool.state === "input-streaming") {
     return <LoadingState />;
   }
 
+  if (tool.state !== "output-available") {
+    return null;
+  }
+
+  if (!tool.output) {
+    return null;
+  }
+
   const { output: result } = tool;
   const firstItem = getFirstItem(result);
   const errorMessage = getErrorMessage(result, firstItem);

package/templates/chat-app/{lib/ai/tools/retrieve-url.ts → tools/chatjs/retrieve-url/tool.ts}

@@ -2,7 +2,19 @@ import FirecrawlApp from "@mendable/firecrawl-js";
 import { tool } from "ai";
 import { z } from "zod";
 import { env } from "@/lib/env";
-import { createModuleLogger } from "../../logger";
+import { createModuleLogger } from "@/lib/logger";
+
+type ToolEnvVars = {
+  description?: string;
+  options: string[][];
+}[];
+
+export const toolEnvVars: ToolEnvVars = [
+  {
+    description: "FIRECRAWL_API_KEY",
+    options: [["FIRECRAWL_API_KEY"]],
+  },
+];
 
 const log = createModuleLogger("tools/retrieve-url");
 
@@ -10,6 +22,22 @@ const app = env.FIRECRAWL_API_KEY
   ? new FirecrawlApp({ apiKey: env.FIRECRAWL_API_KEY })
   : null;
 
+function parseUrl(url: string): URL | null {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function redactUrl(url: URL): string {
+  return `${url.origin}${url.pathname}`;
+}
+
 export const retrieveUrl = tool({
   description: `Fetch structured information from a single URL via Firecrawl.
 
@@ -29,7 +57,16 @@ Avoid:
             "Firecrawl is not configured. Set FIRECRAWL_API_KEY to enable retrieval.",
         };
       }
-      const content = await app.scrapeUrl(url);
+      const parsedUrl = parseUrl(url);
+      if (!parsedUrl) {
+        return {
+          error: "Please provide a valid http:// or https:// URL.",
+        };
+      }
+
+      const redactedUrl = redactUrl(parsedUrl);
+      const normalizedUrl = parsedUrl.toString();
+      const content = await app.scrapeUrl(normalizedUrl);
       if (!(content.success && content.metadata)) {
         return {
           results: [
@@ -40,7 +77,6 @@ Avoid:
         };
       }
 
-      // Define schema for extracting missing content
       const schema = z.object({
         title: z.string(),
         content: z.string(),
@@ -51,9 +87,8 @@ Avoid:
       let description = content.metadata.description;
       let extractedContent = content.markdown;
 
-      // If any content is missing, use extract to get it
       if (!(title && description && extractedContent)) {
-        const extractResult = await app.extract([url], {
+        const extractResult = await app.extract([normalizedUrl], {
           prompt:
             "Extract the page title, main content, and a brief description.",
           schema,
@@ -71,14 +106,18 @@ Avoid:
           {
             title: title || "Untitled",
             content: extractedContent || "",
-            url: content.metadata.sourceURL,
+            url: redactedUrl,
             description: description || "",
             language: content.metadata.language,
           },
         ],
       };
     } catch (error) {
-      log.error({ err: error, url }, "Firecrawl API error in retrieveUrl tool");
+      const parsedUrl = parseUrl(url);
+      log.error(
+        { err: error, url: parsedUrl ? redactUrl(parsedUrl) : "<invalid-url>" },
+        "Firecrawl API error in retrieveUrl tool"
+      );
       return { error: "Failed to retrieve content" };
     }
   },

package/templates/chat-app/tools/chatjs/tools.ts

@@ -0,0 +1,16 @@
+// Server-side tools installed via `chatjs add`.
+// This file is fully managed by the CLI — do not edit manually.
+
+// [chatjs-registry:tool-imports]
+import { getWeather } from "@/tools/chatjs/get-weather/tool";
+import { retrieveUrl } from "@/tools/chatjs/retrieve-url/tool";
+import { wordCount } from "@/tools/chatjs/word-count/tool";
+// [/chatjs-registry:tool-imports]
+
+export const tools = {
+  // [chatjs-registry:tools]
+  getWeather,
+  retrieveUrl,
+  wordCount,
+  // [/chatjs-registry:tools]
+} as const;

package/templates/chat-app/tools/chatjs/ui.ts

@@ -0,0 +1,17 @@
+// Client-side tool renderers installed via `chatjs add`.
+// This file is fully managed by the CLI — do not edit manually.
+import type { ToolRendererRegistry } from "@/lib/ai/tool-renderer-registry";
+
+// [chatjs-registry:ui-imports]
+import { GetWeatherRenderer } from "@/tools/chatjs/get-weather/renderer";
+import { RetrieveUrlRenderer } from "@/tools/chatjs/retrieve-url/renderer";
+import { WordCountRenderer } from "@/tools/chatjs/word-count/renderer";
+// [/chatjs-registry:ui-imports]
+
+export const ui = {
+  // [chatjs-registry:ui]
+  "tool-getWeather": GetWeatherRenderer,
+  "tool-retrieveUrl": RetrieveUrlRenderer,
+  "tool-wordCount": WordCountRenderer,
+  // [/chatjs-registry:ui]
+} satisfies ToolRendererRegistry;

package/templates/chat-app/tools/chatjs/word-count/renderer.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import type { TypelessToolPartFromTool } from "@/tools/chatjs/_shared/lib/tool-part";
+import type { wordCount } from "./tool";
+
+type WordCountRendererTool = TypelessToolPartFromTool<typeof wordCount>;
+
+export function WordCountRenderer({
+  tool,
+}: {
+  tool: WordCountRendererTool;
+  messageId: string;
+  isReadonly: boolean;
+}) {
+  if (tool.state === "input-available") {
+    return (
+      <div className="rounded-lg border p-3 text-muted-foreground text-sm">
+        Counting words...
+      </div>
+    );
+  }
+
+  if (tool.state !== "output-available") {
+    return null;
+  }
+
+  if (!tool.output) {
+    return null;
+  }
+
+  const { words, characters, charactersNoSpaces, sentences } = tool.output;
+
+  return (
+    <div className="grid grid-cols-2 gap-2 rounded-lg border p-3 text-sm sm:grid-cols-4">
+      <Stat label="Words" value={words} />
+      <Stat label="Characters" value={characters} />
+      <Stat label="No spaces" value={charactersNoSpaces} />
+      <Stat label="Sentences" value={sentences} />
+    </div>
+  );
+}
+
+function Stat({ label, value }: { label: string; value: number }) {
+  return (
+    <div className="flex flex-col items-center gap-1">
+      <span className="font-semibold text-lg">{value}</span>
+      <span className="text-muted-foreground text-xs">{label}</span>
+    </div>
+  );
+}

package/templates/chat-app/tools/chatjs/word-count/tool.ts

@@ -0,0 +1,30 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+const WORD_SPLIT_REGEX = /\s+/;
+const SENTENCE_SPLIT_REGEX = /[.!?]+/;
+
+export const wordCount = tool({
+  description: "Count the words, characters, and sentences in a given text",
+  inputSchema: z.object({
+    text: z.string().describe("The text to analyze"),
+  }),
+  execute: ({ text }: { text: string }) => {
+    const words =
+      text.trim() === "" ? 0 : text.trim().split(WORD_SPLIT_REGEX).length;
+    const characters = text.length;
+    const charactersNoSpaces = text.replace(/\s/g, "").length;
+    const sentences = text
+      .split(SENTENCE_SPLIT_REGEX)
+      .filter((s) => s.trim().length > 0).length;
+
+    return { words, characters, charactersNoSpaces, sentences };
+  },
+});
+
+export type WordCountOutput = {
+  words: number;
+  characters: number;
+  charactersNoSpaces: number;
+  sentences: number;
+};

package/templates/chat-app/{lib/ai/tools → tools/platform}/code-execution.ts

@@ -15,7 +15,8 @@ import {
   type SupportedExecutionLanguage,
   supportedExecutionLanguages,
 } from "./code-execution.types";
-import { toolsDefinitions } from "./tools-definitions";
+
+const COST_CENTS = 5; // Vercel Sandbox execution
 
 const languageSchema = z.enum(supportedExecutionLanguages);
 
@@ -115,10 +116,7 @@ Output rules:
                 requestId,
               });
 
-        costAccumulator?.addAPICost(
-          "codeExecution",
-          toolsDefinitions.codeExecution.cost
-        );
+        costAccumulator?.addAPICost("codeExecution", COST_CENTS);
 
         return result;
       } catch (err) {