@chat-js/cli 0.1.3 → 0.2.0

package/templates/chat-app/.cursor/skills/ultracite/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: ultracite
+description: 'Skill: ultracite'
+---
+
+# Ultracite Code Standards
+
+This project uses **Ultracite**, a zero-config Biome preset that enforces strict code quality standards through automated formatting and linting.
+
+## Quick Reference
+
+- **Format code**: `npx ultracite@6.3.3 fix`
+- **Check for issues**: `npx ultracite@6.3.3 check`
+- **Diagnose setup**: `npx ultracite@6.3.3 doctor`
+
+Biome (the underlying engine) provides extremely fast Rust-based linting and formatting. Most issues are automatically fixable.
+
+---
+
+## Core Principles
+
+Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity.
+
+### Type Safety & Explicitness
+
+- Use explicit types for function parameters and return values when they enhance clarity
+- Prefer `unknown` over `any` when the type is genuinely unknown
+- Use const assertions (`as const`) for immutable values and literal types
+- Leverage TypeScript's type narrowing instead of type assertions
+- Use meaningful variable names instead of magic numbers - extract constants with descriptive names
+
+### Modern JavaScript/TypeScript
+
+- Use arrow functions for callbacks and short functions
+- Prefer `for...of` loops over `.forEach()` and indexed `for` loops
+- Use optional chaining (`?.`) and nullish coalescing (`??`) for safer property access
+- Prefer template literals over string concatenation
+- Use destructuring for object and array assignments
+- Use `const` by default, `let` only when reassignment is needed, never `var`
+
+### Async & Promises
+
+- Always `await` promises in async functions - don't forget to use the return value
+- Use `async/await` syntax instead of promise chains for better readability
+- Handle errors appropriately in async code with try-catch blocks
+- Don't use async functions as Promise executors
+
+### React & JSX
+
+- Use function components over class components
+- Call hooks at the top level only, never conditionally
+- Specify all dependencies in hook dependency arrays correctly
+- Use the `key` prop for elements in iterables (prefer unique IDs over array indices)
+- Nest children between opening and closing tags instead of passing as props
+- Don't define components inside other components
+- Use semantic HTML and ARIA attributes for accessibility:
+  - Provide meaningful alt text for images
+  - Use proper heading hierarchy
+  - Add labels for form inputs
+  - Include keyboard event handlers alongside mouse events
+  - Use semantic elements (`<button>`, `<nav>`, etc.) instead of divs with roles
+
+### Error Handling & Debugging
+
+- Remove `console.log`, `debugger`, and `alert` statements from production code
+- Throw `Error` objects with descriptive messages, not strings or other values
+- Use `try-catch` blocks meaningfully - don't catch errors just to rethrow them
+- Prefer early returns over nested conditionals for error cases
+
+### Code Organization
+
+- Keep functions focused and under reasonable cognitive complexity limits
+- Extract complex conditions into well-named boolean variables
+- Use early returns to reduce nesting
+- Prefer simple conditionals over nested ternary operators
+- Group related code together and separate concerns
+
+### Security
+
+- Add `rel="noopener"` when using `target="_blank"` on links
+- Avoid `dangerouslySetInnerHTML` unless absolutely necessary
+- Don't use `eval()` or assign directly to `document.cookie`
+- Validate and sanitize user input
+
+### Performance
+
+- Avoid spread syntax in accumulators within loops
+- Use top-level regex literals instead of creating them in loops
+- Prefer specific imports over namespace imports
+- Avoid barrel files (index files that re-export everything)
+- Use proper image components (e.g., Next.js `<Image>`) over `<img>` tags
+
+### Framework-Specific Guidance
+
+**Next.js:**
+- Use Next.js `<Image>` component for images
+- Use `next/head` or App Router metadata API for head elements
+- Use Server Components for async data fetching instead of async Client Components
+
+**React 19+:**
+- Use ref as a prop instead of `React.forwardRef`
+
+**Solid/Svelte/Vue/Qwik:**
+- Use `class` and `for` attributes (not `className` or `htmlFor`)
+
+---
+
+## Testing
+
+- Write assertions inside `it()` or `test()` blocks
+- Avoid done callbacks in async tests - use async/await instead
+- Don't use `.only` or `.skip` in committed code
+- Keep test suites reasonably flat - avoid excessive `describe` nesting
+
+## When Biome Can't Help
+
+Biome's linter will catch most issues automatically. Focus your attention on:
+
+1. **Business logic correctness** - Biome can't validate your algorithms
+2. **Meaningful naming** - Use descriptive names for functions, variables, and types
+3. **Architecture decisions** - Component structure, data flow, and API design
+4. **Edge cases** - Handle boundary conditions and error states
+5. **User experience** - Accessibility, performance, and usability considerations
+6. **Documentation** - Add comments for complex logic, but prefer self-documenting code
+
+---
+
+Most formatting and common issues are automatically fixed by Biome. Run `npx ultracite@6.3.3 fix` before committing to ensure compliance.

package/templates/chat-app/app/(chat)/actions.ts

@@ -11,7 +11,7 @@ export async function generateTitleFromUserMessage({
   message: ChatMessage;
 }) {
   const { text: title } = await generateText({
-    model: await getLanguageModel(config.models.defaults.title),
+    model: await getLanguageModel(config.ai.workflows.title),
     system: `\n
     - you will generate a short title based on the first message a user begins a conversation with
     - ensure it is not more than 40 characters long

package/templates/chat-app/app/(chat)/api/chat/[id]/stream/route.ts

@@ -43,17 +43,18 @@ export async function GET(
     return new ChatSDKError("bad_request:api").toResponse();
   }
 
-  // Get message and validate it exists with an active stream
-  const messageWithParts = await getChatMessageWithPartsById({ id: messageId });
+  const [messageWithParts, session, chat] = await Promise.all([
+    getChatMessageWithPartsById({ id: messageId }),
+    auth.api.getSession({ headers: await headers() }),
+    getChatById({ id: chatId }),
+  ]);
+
   if (!messageWithParts || messageWithParts.chatId !== chatId) {
     return new ChatSDKError("not_found:stream").toResponse();
   }
 
-  // Validate chat ownership
-  const session = await auth.api.getSession({ headers: await headers() });
   const userId = session?.user?.id || null;
 
-  const chat = await getChatById({ id: chatId });
   if (!chat) {
     return new ChatSDKError("not_found:chat").toResponse();
   }

package/templates/chat-app/app/(chat)/api/chat/route.ts

@@ -415,7 +415,7 @@ async function createChatStream({
       const responseMessages = response.messages;
 
       // Generate and stream follow-up suggestions
-      if (config.features.followupSuggestions) {
+      if (config.ai.tools.followupSuggestions.enabled) {
         const followupSuggestionsResult = generateFollowupSuggestions([
           ...contextForLLM,
           ...responseMessages,
@@ -826,14 +826,19 @@ export async function POST(request: NextRequest) {
     const explicitlyRequestedTools =
       determineExplicitlyRequestedTools(selectedTool);
 
-    const contextResult = await prepareRequestContext({
-      userMessage,
-      chatId,
-      isAnonymous,
-      anonymousPreviousMessages,
-      modelDefinition,
-      explicitlyRequestedTools,
-    });
+    const [contextResult, mcpConnectors] = await Promise.all([
+      prepareRequestContext({
+        userMessage,
+        chatId,
+        isAnonymous,
+        anonymousPreviousMessages,
+        modelDefinition,
+        explicitlyRequestedTools,
+      }),
+      config.ai.tools.mcp.enabled && userId && !isAnonymous
+        ? getMcpConnectorsByUserId({ userId })
+        : Promise.resolve([]),
+    ]);
 
     if (contextResult.error) {
       return contextResult.error;
@@ -841,12 +846,6 @@ export async function POST(request: NextRequest) {
 
     const { previousMessages, allowedTools } = contextResult;
 
-    // Fetch MCP connectors for authenticated users (only if MCP integration enabled)
-    const mcpConnectors: McpConnector[] =
-      config.features.mcp && userId && !isAnonymous
-        ? await getMcpConnectorsByUserId({ userId })
-        : [];
-
     // Create AbortController with timeout
     const abortController = new AbortController();
     const timeoutId = setTimeout(() => {

package/templates/chat-app/app/(chat)/chat-providers.tsx

@@ -3,9 +3,9 @@
 import { AnonymousSessionInit } from "@/components/anonymous-session-init";
 import { ChatIdProvider } from "@/providers/chat-id-provider";
 
-type ChatProvidersProps = {
+interface ChatProvidersProps {
   children: React.ReactNode;
-};
+}
 
 export function ChatProviders({ children }: ChatProvidersProps) {
   return (

package/templates/chat-app/app/(chat)/layout.tsx

@@ -19,17 +19,18 @@ export default async function ChatLayout({
 }: {
   children: React.ReactNode;
 }) {
-  const cookieStore = await cookies();
-  const session = await auth.api.getSession({ headers: await headers() });
+  const [cookieStore, headersRes, chatModels] = await Promise.all([
+    cookies(),
+    headers(),
+    getChatModels(),
+  ]);
+  const session = await auth.api.getSession({ headers: headersRes });
   const isCollapsed = cookieStore.get("sidebar:state")?.value !== "true";
 
   const cookieModel = cookieStore.get("chat-model")?.value;
   const isAnonymous = !session?.user;
 
-  // Always fetch chat models - needed for ChatModelsProvider and cookie validation
-  const chatModels = await getChatModels();
-
-  const default_chat_model = config.models.defaults.chat;
+  const default_chat_model = config.ai.workflows.chat;
   // Check if the model from cookie exists in available models
   let defaultModel: AppModelId =
     (cookieModel as AppModelId) ?? default_chat_model;

package/templates/chat-app/app/api/cron/cleanup/route.ts

@@ -37,9 +37,10 @@ export async function GET(request: NextRequest) {
 }
 
 async function cleanupOrphanedAttachments() {
-  // Skip cleanup if neither imageGeneration nor attachments is enabled
-  const { imageGeneration, attachments } = config.features;
-  if (!(imageGeneration || attachments)) {
+  // Skip cleanup if neither image tool nor attachments is enabled
+  const imageGenerationEnabled = config.ai.tools.image.enabled;
+  const attachmentsEnabled = config.features.attachments;
+  if (!(imageGenerationEnabled || attachmentsEnabled)) {
     return { deletedCount: 0, deletedUrls: [], skipped: true };
   }
 

package/templates/chat-app/app/globals.css

@@ -425,19 +425,19 @@
 
 .lexical-content-editable {
   position: relative;
-  outline: none;
-  user-select: text;
-  white-space: pre-wrap;
-  word-break: break-word;
+  overflow-y: auto;
   font-family: inherit;
   font-size: inherit;
   line-height: 1.5;
   color: inherit;
-  background: transparent;
-  border: none;
+  word-break: break-word;
+  white-space: pre-wrap;
   resize: none;
-  overflow-y: auto;
+  user-select: text;
+  outline: none;
   scrollbar-width: thin;
+  background: transparent;
+  border: none;
 }
 
 .lexical-content-editable::-webkit-scrollbar {
@@ -458,15 +458,15 @@
 }
 
 .lexical-placeholder {
-  color: var(--muted-foreground);
-  pointer-events: none;
-  user-select: none;
   position: absolute;
   top: 0;
-  left: 0;
   right: 0;
   bottom: 0;
+  left: 0;
   z-index: 1;
+  color: var(--muted-foreground);
+  pointer-events: none;
+  user-select: none;
 }
 
 .lexical-root {
@@ -474,8 +474,8 @@
 }
 
 .lexical-root p {
-  margin: 0;
   padding: 0;
+  margin: 0;
 }
 
 .lexical-root p:first-child {
@@ -505,25 +505,25 @@
 }
 
 .editor-container {
-  background: #fff;
-  margin: 20px auto 20px auto;
-  border-radius: 2px;
-  max-width: 600px;
-  color: #000;
   position: relative;
-  line-height: 20px;
+  max-width: 600px;
+  margin: 20px auto 20px auto;
   font-weight: 400;
+  line-height: 20px;
+  color: #000;
   text-align: left;
+  background: #fff;
+  border-radius: 2px;
 }
 
 .editor-input {
-  resize: none;
-  font-size: 15px;
   position: relative;
-  tab-size: 1;
-  outline: 0;
   padding: 10px 10px 5px;
+  font-size: 15px;
+  tab-size: 1;
   caret-color: currentColor;
+  resize: none;
+  outline: 0;
 }
 
 /*

package/templates/chat-app/app/layout.tsx

@@ -88,7 +88,7 @@ export default async function RootLayout({
       <body className="antialiased">
         <Script
           src="https://cdn.jsdelivr.net/pyodide/v0.23.4/full/pyodide.js"
-          strategy="beforeInteractive"
+          strategy="afterInteractive"
         />
         <NuqsAdapter>
           <ThemeProvider

package/templates/chat-app/biome.jsonc

@@ -2,11 +2,11 @@
   "extends": ["ultracite/core", "ultracite/react", "ultracite/next"],
   "files": {
     "includes": [
-      "**/*",
       "!.next",
-      "!.next",
-      "!.devtools",
       "!.devtools",
+      "!node_modules",
+      "!playwright-report",
+      "!test-results",
       "!components/ui",
       "!components/ai-elements",
       "!components/streamdown",

package/templates/chat-app/chat.config.ts

@@ -45,14 +45,7 @@ const config = {
     paymentProcessors: [],
   },
   features: {
-    sandbox: true, // Vercel-native, no key needed
-    webSearch: true, // Requires TAVILY_API_KEY or FIRECRAWL_API_KEY
-    urlRetrieval: true, // Requires FIRECRAWL_API_KEY
-    deepResearch: true, // Requires webSearch
-    mcp: true, // Requires MCP_ENCRYPTION_KEY
-    imageGeneration: true, // Requires BLOB_READ_WRITE_TOKEN
     attachments: true, // Requires BLOB_READ_WRITE_TOKEN
-    followupSuggestions: true,
   },
   legal: {
     minimumAge: 13,
@@ -74,7 +67,7 @@ const config = {
     github: true, // Requires AUTH_GITHUB_ID + AUTH_GITHUB_SECRET
     vercel: true, // Requires VERCEL_APP_CLIENT_ID + VERCEL_APP_CLIENT_SECRET
   },
-  models: {
+  ai: {
     gateway: "vercel",
     providerOrder: ["openai", "google", "anthropic", "xai"],
     disabledModels: ["morph/morph-v3-large", "morph/morph-v3-fast"],
@@ -100,22 +93,56 @@ const config = {
       "openai/gpt-5-nano",
       "anthropic/claude-haiku-4.5",
     ],
-    defaults: {
+    workflows: {
       chat: "openai/gpt-5-mini",
       title: "openai/gpt-5-nano",
       pdf: "openai/gpt-5-mini",
-      artifact: "openai/gpt-5-nano",
-      artifactSuggestion: "openai/gpt-5-mini",
-      followupSuggestions: "openai/gpt-5-nano",
-      suggestions: "openai/gpt-5-mini",
-      polishText: "openai/gpt-5-mini",
-      formatSheet: "openai/gpt-5-mini",
-      analyzeSheet: "openai/gpt-5-mini",
-      codeEdits: "openai/gpt-5-mini",
       chatImageCompatible: "openai/gpt-4o-mini",
-      image: "google/gemini-3-pro-image",
-      deepResearch: "google/gemini-2.5-flash-lite",
-      deepResearchFinalReport: "google/gemini-3-flash",
+    },
+    tools: {
+      webSearch: {
+        enabled: true, // Requires TAVILY_API_KEY or FIRECRAWL_API_KEY
+      },
+      urlRetrieval: {
+        enabled: true, // Requires FIRECRAWL_API_KEY
+      },
+      codeExecution: {
+        enabled: true, // Vercel-native, no key needed
+      },
+      mcp: {
+        enabled: true, // Requires MCP_ENCRYPTION_KEY
+      },
+      followupSuggestions: {
+        enabled: true,
+        default: "openai/gpt-5-nano",
+      },
+      text: {
+        polish: "openai/gpt-5-mini",
+      },
+      sheet: {
+        format: "openai/gpt-5-mini",
+        analyze: "openai/gpt-5-mini",
+      },
+      code: {
+        edits: "openai/gpt-5-mini",
+      },
+      image: {
+        enabled: true, // Requires BLOB_READ_WRITE_TOKEN
+        default: "google/gemini-3-pro-image",
+      },
+      video: {
+        enabled: true, // Requires BLOB_READ_WRITE_TOKEN
+        default: "xai/grok-imagine-video",
+      },
+      deepResearch: {
+        enabled: true, // Requires webSearch
+        defaultModel: "google/gemini-2.5-flash-lite",
+        finalReportModel: "google/gemini-3-flash",
+        allowClarification: true,
+        maxResearcherIterations: 1,
+        maxConcurrentResearchUnits: 2,
+        maxSearchQueries: 2,
+      },
     },
   },
   anonymous: {

package/templates/chat-app/components/anonymous-session-init.tsx

@@ -29,7 +29,6 @@ export function AnonymousSessionInit() {
   const trpc = useTRPC();
 
   useEffect(() => {
-    // Only initialize for non-authenticated users after session is loaded
     if (isPending) {
       return;
     }
@@ -37,34 +36,27 @@ export function AnonymousSessionInit() {
       return;
     }
 
-    // Get raw session data and validate/migrate
     const existingSession = getAnonymousSession();
 
     if (existingSession) {
-      // Validate the existing session schema
       if (!isValidAnonymousSession(existingSession)) {
         console.warn(
           "Invalid session schema detected during init, clearing and creating new session"
         );
         clearAnonymousSession();
-        const newSession = createAnonymousSession();
-        setAnonymousSession(newSession);
-        // Ensure UI refetches credits after creating a valid anonymous session
+        setAnonymousSession(createAnonymousSession());
         queryClient.invalidateQueries({
           queryKey: trpc.credits.getAvailableCredits.queryKey(),
         });
         return;
       }
     } else {
-      // Create new session if none exists
-      const newSession = createAnonymousSession();
-      setAnonymousSession(newSession);
-      // Ensure UI refetches credits after first-time session creation
+      setAnonymousSession(createAnonymousSession());
       queryClient.invalidateQueries({
         queryKey: trpc.credits.getAvailableCredits.queryKey(),
       });
     }
-  }, [session, isPending, queryClient, trpc.credits.getAvailableCredits]);
+  }, [isPending, queryClient, trpc, session?.user]);
 
-  return null; // This component doesn't render anything
+  return null;
 }

package/templates/chat-app/components/artifact-actions.tsx

@@ -7,16 +7,16 @@ import { Button } from "./ui/button";
 import { Toggle } from "./ui/toggle";
 import { Tooltip, TooltipContent, TooltipTrigger } from "./ui/tooltip";
 
-type ArtifactActionsProps = {
+interface ArtifactActionsProps {
   artifact: UIArtifact;
-  handleVersionChange: (type: "next" | "prev" | "toggle" | "latest") => void;
   currentVersionIndex: number;
+  handleVersionChange: (type: "next" | "prev" | "toggle" | "latest") => void;
   isCurrentVersion: boolean;
-  mode: "edit" | "diff";
+  isReadonly: boolean;
   metadata: any;
+  mode: "edit" | "diff";
   setMetadata: Dispatch<SetStateAction<any>>;
-  isReadonly: boolean;
-};
+}
 
 function PureArtifactActions({
   artifact,

package/templates/chat-app/components/artifact-panel.tsx

@@ -34,16 +34,16 @@ import { VersionFooter } from "./version-footer";
 
 export const artifactDefinitions = [textArtifact, codeArtifact, sheetArtifact];
 
-export type UIArtifact = {
-  title: string;
+export interface UIArtifact {
+  content: string;
+  date?: string;
   documentId: string;
+  isVisible: boolean;
   kind: ArtifactKind;
-  content: string;
   messageId: string;
-  isVisible: boolean;
   status: "streaming" | "idle";
-  date?: string;
-};
+  title: string;
+}
 
 function PureArtifactPanel({
   isReadonly,

package/templates/chat-app/components/assistant-message.tsx

@@ -48,7 +48,7 @@ const PureAssistantMessage = ({
           key={`action-${messageId}`}
           messageId={messageId}
         />
-        {isReadonly || !config.features.followupSuggestions ? null : (
+        {isReadonly || !config.ai.tools.followupSuggestions.enabled ? null : (
           <FollowUpSuggestionsParts messageId={messageId} />
         )}
       </MessageContent>

package/templates/chat-app/components/chat/chat-layout.tsx

@@ -10,9 +10,9 @@ import {
 import { useSidebar } from "@/components/ui/sidebar";
 import { cn } from "@/lib/utils";
 
-type ChatLayoutContextValue = {
+interface ChatLayoutContextValue {
   isSecondaryPanelVisible: boolean;
-};
+}
 
 const ChatLayoutContext = createContext<ChatLayoutContextValue | null>(null);
 

package/templates/chat-app/components/chat/chat-welcome.tsx

@@ -43,6 +43,7 @@ function PureChatWelcome({
           <WelcomeMessage />
         </div>
         <MultimodalInput
+          autoFocus
           chatId={chatId}
           parentMessageId={parentMessageId}
           status={status}

package/templates/chat-app/components/chat-features-definitions.ts

@@ -4,15 +4,16 @@ import {
   Images,
   type LucideIcon,
   Telescope,
+  Video,
 } from "lucide-react";
 import type { UiToolName } from "@/lib/ai/types";
 import { config } from "@/lib/config";
 
-type ToolDefinition = {
-  name: string;
+interface ToolDefinition {
   icon: LucideIcon;
+  name: string;
   shortName: string;
-};
+}
 
 export const toolDefinitions: Record<UiToolName, ToolDefinition> = {
   webSearch: { name: "Web Search", icon: GlobeIcon, shortName: "Search" },
@@ -22,6 +23,7 @@ export const toolDefinitions: Record<UiToolName, ToolDefinition> = {
     shortName: "Research",
   },
   generateImage: { name: "Create an image", icon: Images, shortName: "Image" },
+  generateVideo: { name: "Create a video", icon: Video, shortName: "Video" },
   createTextDocument: { name: "Canvas", icon: Edit3, shortName: "Canvas" },
   createCodeDocument: { name: "Canvas", icon: Edit3, shortName: "Canvas" },
   createSheetDocument: { name: "Canvas", icon: Edit3, shortName: "Canvas" },
@@ -37,10 +39,11 @@ export const toolDefinitions: Record<UiToolName, ToolDefinition> = {
 export const enabledTools: UiToolName[] = [
   // Canvas tools are always available
   "createTextDocument",
-  // Web search tools require webSearch integration
-  ...(config.features.webSearch
-    ? (["webSearch", "deepResearch"] as const)
-    : []),
+  // Web search tool
+  ...(config.ai.tools.webSearch.enabled ? (["webSearch"] as const) : []),
+  // Deep research tool
+  ...(config.ai.tools.deepResearch.enabled ? (["deepResearch"] as const) : []),
   // Image generation requires imageGeneration integration
-  ...(config.features.imageGeneration ? (["generateImage"] as const) : []),
+  ...(config.ai.tools.image.enabled ? (["generateImage"] as const) : []),
+  ...(config.ai.tools.video.enabled ? (["generateVideo"] as const) : []),
 ];

package/templates/chat-app/components/chat-menu-items.tsx

@@ -4,14 +4,14 @@ import { Pencil, PinIcon, Trash2 } from "lucide-react";
 import { DropdownMenuItem } from "@/components/ui/dropdown-menu";
 import { ShareMenuItem } from "@/components/upgrade-cta/share-menu-item";
 
-type ChatMenuItemsProps = {
+interface ChatMenuItemsProps {
   isPinned: boolean;
-  onRename: () => void;
-  onTogglePin: () => void;
   onDelete: () => void;
+  onRename: () => void;
   onShare?: () => void;
+  onTogglePin: () => void;
   showShare?: boolean;
-};
+}
 
 export function ChatMenuItems({
   isPinned,