feat: Add just-bash support for WebContainer editing - #489

packages/webcontainer/src/WebContainerFsAdapter.ts (1)

100-102: Type assertion bypasses compile-time interface verification.

Using as unknown as IFileSystem circumvents TypeScript's structural typing. If IFileSystem adds new required methods in just-bash, this class won't fail to compile even though it's incomplete.

Consider adding implements IFileSystem to the class declaration for compile-time guarantees:

-export class WebContainerFsAdapter {
+export class WebContainerFsAdapter implements IFileSystem {

This would require importing IFileSystem as a type and ensuring all methods match the expected signatures.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webcontainer/src/WebContainerFsAdapter.ts` around lines 100 - 102,
The current asFileSystem() uses a double type assertion that bypasses TypeScript
checks; update the WebContainerFsAdapter class to explicitly implement the
IFileSystem interface (add "implements IFileSystem" to the class declaration and
import IFileSystem as a type), then adjust or remove asFileSystem() to return
this as a properly-typed IFileSystem (or simply return this) and ensure all
methods on WebContainerFsAdapter match the IFileSystem method signatures so the
compiler can verify completeness.

packages/webcontainer/src/shims/node-zlib.ts (1)

7-11: Consider clarifying the error message.

The message "just-bash gzip commands remain unsupported in this environment" could be confusing since it implies just-bash's gzip support is limited, when actually the issue is that Node's synchronous zlib API isn't available in the browser. The actual just-bash gzip commands may work fine through the WebContainer.

💡 Suggested clarification

 function unsupported(methodName: string): never {
   throw new Error(
-    `${methodName} is not available in browser builds. just-bash gzip commands remain unsupported in this environment.`,
+    `${methodName} is not available in browser builds. Use the WebContainer's native filesystem or just-bash commands instead.`,
   );
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webcontainer/src/shims/node-zlib.ts` around lines 7 - 11, The error
thrown by the unsupported function currently implies that "just-bash gzip
commands" are unsupported; update the message in unsupported(methodName: string)
to clearly state that Node's synchronous zlib APIs are not available in browser
builds and that the browser environment (WebContainer) may still support gzip
via other means, while including the methodName and the phrase "not available in
browser builds (synchronous zlib APIs unsupported)". Keep the throw in
unsupported(...) and only change the error text to this clarified wording.

packages/webcontainer/src/createWebContainerBashTool.tsx (2)

162-167: Props types are missing toolCallId expected by ToolRendererProps.

Per the ToolRendererProps interface in packages/ai-core/src/types.ts, tool renderers receive a toolCallId prop. While the current implementation works (unused props are simply ignored), adding it to the type definitions would ensure consistency with the framework's expectations.

♻️ Suggested props type alignment

 type WebContainerBashToolResultProps = {
   input: WebContainerBashToolParameters;
   output: WebContainerBashToolOutput | undefined;
   state: ToolResultState;
+  toolCallId: string;
   errorText?: string;
 };

Similarly for the other result props types.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webcontainer/src/createWebContainerBashTool.tsx` around lines 162 -
167, The WebContainerBashToolResultProps type is missing the toolCallId prop
expected by the ToolRendererProps interface; update the type definition for
WebContainerBashToolResultProps (and any other result props types) to include
toolCallId: string (or the correct id type) so the component signatures match
the framework's expectations, ensuring you add the field alongside input,
output, state, and errorText in the type declaration.

---

43-50: Consider improving type safety for WebContainerToolkitResult.

The any types here lose the benefit of TypeScript's type checking. While the eslint-disable comment indicates this is intentional, using more specific types would improve DX for consumers.

💡 Suggested type improvement

-// eslint-disable-next-line `@typescript-eslint/no-explicit-any`
-export type WebContainerToolkitResult = {
-  bash: any;
-  readFile: any;
-  writeFile: any;
-  tools: Record<string, any>;
-  toolRenderers: Record<string, React.ComponentType<any>>;
-};
+export type WebContainerToolkitResult = {
+  bash: ReturnType<typeof tool<typeof WebContainerBashToolParameters, WebContainerBashToolOutput>>;
+  readFile: ReturnType<typeof tool>;
+  writeFile: ReturnType<typeof tool>;
+  tools: {
+    bash: WebContainerToolkitResult['bash'];
+    readFile: WebContainerToolkitResult['readFile'];
+    writeFile: WebContainerToolkitResult['writeFile'];
+  };
+  toolRenderers: Record<string, React.ComponentType<ToolRendererProps<unknown, unknown>>>;
+};

Alternatively, if complex inference is problematic, at minimum the tools and toolRenderers keys could be typed as string literals:

tools: Record<'bash' | 'readFile' | 'writeFile', Tool>;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webcontainer/src/createWebContainerBashTool.tsx` around lines 43 -
50, The WebContainerToolkitResult type uses broad any types (bash, readFile,
writeFile, tools, toolRenderers) which reduces TypeScript safety; define
explicit interfaces (e.g., a Tool type for tool functions/objects and a
ToolRenderer type for React components) and replace the anys with those
types—assign bash a callable signature (promise-returning), readFile/writeFile
appropriate param/return types, tools as Record<string, Tool> (or a union of
literal keys like 'bash'|'readFile'|'writeFile' -> Tool), and toolRenderers as
Record<string, ToolRenderer>; remove the eslint-disable comment after typing so
WebContainerToolkitResult, bash, readFile, writeFile, tools, and toolRenderers
are strongly typed.

packages/webcontainer/src/WebContainerFsAdapter.ts (1)

174-193: ⚠️ Potential issue | 🟠 Major

Broaden the append rollback to cover parent creation.

The try block only starts after Line 185. If webContainer.fs.mkdir() fails there, the mirror keeps the appended bytes while the WebContainer stays unchanged. The existing resync path should start before ensureParentDirectory() as well.

🛠️ Suggested fix

   async appendFile(
     path: string,
     content: FileContent,
     options?: {encoding?: BufferEncoding} | BufferEncoding,
   ): Promise<void> {
     const resolvedPath = this.resolveWithinRoot('/', path);
     await this.mirror.appendFile(
       resolvedPath,
       content,
       options as BufferEncoding,
     );
-    await this.ensureParentDirectory(resolvedPath);
-    const updatedContents = await this.mirror.readFileBuffer(resolvedPath);
     try {
+      await this.ensureParentDirectory(resolvedPath);
+      const updatedContents = await this.mirror.readFileBuffer(resolvedPath);
       await this.webContainer.fs.writeFile(resolvedPath, updatedContents);
     } catch (error) {
       await this.syncFromWebContainer();
       throw error;
     }
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webcontainer/src/WebContainerFsAdapter.ts` around lines 174 - 193,
In appendFile, broaden the try/catch to start before calling
ensureParentDirectory so any failure during parent-directory creation or the
subsequent write is rolled back; specifically, wrap the mirror.appendFile and
ensureParentDirectory and the webContainer.fs.writeFile calls inside the same
try block (referencing appendFile, mirror.appendFile, ensureParentDirectory,
webContainer.fs.writeFile) and retain the catch behavior to call
this.syncFromWebContainer() and rethrow the error.

packages/webcontainer/src/createWebContainerBashTool.tsx (4)

52-61: Consider extracting Zod schemas for readFile and writeFile parameters for type consistency.

The bash tool has its parameter schema exported (WebContainerBashToolParameters) with an inferred type, but readFile and writeFile use inline object types in WebContainerToolkitResult while the actual tool definitions use inline Zod schemas (lines 116-118, 128-131). Extracting these schemas would provide consistent typing and allow consumers to reuse the parameter types.

♻️ Suggested refactor for consistent schema exports

+export const WebContainerReadFileToolParameters = z.object({
+  path: z.string().describe('The path to the file to read'),
+});
+export type WebContainerReadFileToolParameters = z.infer<
+  typeof WebContainerReadFileToolParameters
+>;
+
+export const WebContainerWriteFileToolParameters = z.object({
+  path: z.string().describe('The path where the file should be written'),
+  content: z.string().describe('The content to write to the file'),
+});
+export type WebContainerWriteFileToolParameters = z.infer<
+  typeof WebContainerWriteFileToolParameters
+>;
+
 export type WebContainerToolkitResult = {
   bash: Tool<WebContainerBashToolParameters, WebContainerBashToolOutput>;
-  readFile: Tool<{path: string}, WebContainerReadFileToolOutput>;
-  writeFile: Tool<
-    {path: string; content: string},
-    WebContainerWriteFileToolOutput
-  >;
+  readFile: Tool<WebContainerReadFileToolParameters, WebContainerReadFileToolOutput>;
+  writeFile: Tool<WebContainerWriteFileToolParameters, WebContainerWriteFileToolOutput>;
   tools: Record<string, Tool>;
   toolRenderers: Record<string, ComponentType<ToolResultRendererProps>>;
 };

Then reference these schemas in the tool definitions at lines 116-118 and 128-131.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webcontainer/src/createWebContainerBashTool.tsx` around lines 52 -
61, Extract and export Zod schemas and inferred TS types for the readFile and
writeFile tool parameters (e.g., create WebContainerReadFileParamsSchema and
WebContainerWriteFileParamsSchema and export types like
WebContainerReadFileParameters and WebContainerWriteFileParameters), replace the
inline object types used in the WebContainerToolkitResult type and the
readFile/writeFile tool definitions with these exported parameter types, and
update any references to use the new schema variables where the tools are
defined (matching how WebContainerBashToolParameters is used) to ensure
consistent typing and reuse.

---

218-226: Unused destructured props may trigger lint warnings.

The output and state props are declared in the type but not used. The readFile renderer doesn't display success/error states unlike the bash renderer (which shows exit code and error text). Consider either:

1. Prefix unused props with underscore to satisfy linting
2. Enhance the renderer to show loading/success/error states for consistency

♻️ Option 1: Prefix unused props

 export function WebContainerReadFileToolResult({
   input,
+  state: _state,
+  output: _output,
 }: WebContainerReadFileToolResultProps) {

♻️ Option 2: Show state feedback

 export function WebContainerReadFileToolResult({
   input,
+  state,
+  output,
 }: WebContainerReadFileToolResultProps) {
+  const isFinished = state === 'output-available' || state === 'output-error';
+  const suffix = isFinished
+    ? output
+      ? ` (${output.content.length} bytes)`
+      : ' (failed)'
+    : '';
+
   return (
     <div className="text-foreground/50 text-xs">
-      Reading file <span className="font-mono">{input.path}</span>
+      Reading file <span className="font-mono">{input.path}</span>{suffix}
     </div>
   );
 }

As per coding guidelines: "Maintain lint baseline with warnings only; zero errors is the expected state."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webcontainer/src/createWebContainerBashTool.tsx` around lines 218 -
226, The component WebContainerReadFileToolResult currently destructures props
declared on WebContainerReadFileToolResultProps but does not use output and
state, causing lint warnings; either (A) rename the unused props to _output and
_state in the WebContainerReadFileToolResult signature to satisfy linting, or
(B) enhance WebContainerReadFileToolResult to render state feedback consistent
with the bash renderer: use state to show loading indicator, display output
(file contents) on success, and render error text/exit code on failure
(reference the output and state properties on
WebContainerReadFileToolResultProps when implementing this).

---

235-242: Same unused props concern applies to WebContainerWriteFileToolResult.

Similar to WebContainerReadFileToolResult, the output and state props are unused and the renderer doesn't show operation status. The same two options (prefix unused or enhance renderer) apply here.

♻️ Suggested enhancement for write file renderer

 export function WebContainerWriteFileToolResult({
   input,
+  state,
 }: WebContainerWriteFileToolResultProps) {
+  const isFinished = state === 'output-available' || state === 'output-error';
+  const suffix = state === 'output-error'
+    ? ' (failed)'
+    : isFinished
+      ? ' (done)'
+      : '';
+
   return (
     <div className="text-foreground/50 text-xs">
-      Writing file <span className="font-mono">{input.path}</span>
+      Writing file <span className="font-mono">{input.path}</span>{suffix}
     </div>
   );
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webcontainer/src/createWebContainerBashTool.tsx` around lines 235 -
242, The WebContainerWriteFileToolResult component declares props (output,
state, input) but only uses input.path; either remove the unused props from
WebContainerWriteFileToolResultProps and the component signature to avoid lint
warnings, or enhance the renderer to display operation status by using the state
and output props (e.g., show "Writing...", "Success" / "Error" and any message
from output) — update the WebContainerWriteFileToolResult function signature and
JSX accordingly to either drop output/state references or render their values
alongside input.path.

---

114-139: Inconsistent error handling between tools—consider returning structured errors instead of throwing.

The bash tool returns errors within a structured response ({success, details, errorMessage?}), but readFile and writeFile throw exceptions. While the Vercel AI SDK does handle thrown errors as 'tool-error' parts in tool execution, the inconsistency makes the API harder to use. Align readFile and writeFile with the bash tool pattern by returning structured error responses instead of throwing, which also better matches SDK best practices of returning meaningful error objects.

♻️ Suggested error handling for file tools

   const readFile = tool({
     description: 'Read the contents of a file from the project',
     inputSchema: z.object({
       path: z.string().describe('The path to the file to read'),
     }),
     execute: async ({path}) => {
+      try {
         const content = await getSandbox().readFile(path);
         return {content} satisfies WebContainerReadFileToolOutput;
+      } catch (error) {
+        throw new Error(
+          `Failed to read file "${path}": ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     },
   });
 
   const writeFile = tool({
     description:
       'Write content to a file in the project. Creates the file if it does not exist.',
     inputSchema: z.object({
       path: z.string().describe('The path where the file should be written'),
       content: z.string().describe('The content to write to the file'),
     }),
     execute: async ({
       path,
       content,
     }): Promise<WebContainerWriteFileToolOutput> => {
+      try {
         await getSandbox().writeFiles([{path, content}]);
         return {success: true};
+      } catch (error) {
+        throw new Error(
+          `Failed to write file "${path}": ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     },
   });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webcontainer/src/createWebContainerBashTool.tsx` around lines 114 -
139, The readFile and writeFile tool execute handlers currently throw on
failure; change them to mirror the bash tool's structured response pattern by
catching errors from getSandbox().readFile and getSandbox().writeFiles and
returning typed objects (e.g., WebContainerReadFileToolOutput and
WebContainerWriteFileToolOutput) with success: false plus errorMessage and
optional details instead of throwing; when successful return success: true and
content (for readFile) or success: true (for writeFile), and preserve the
existing inputSchema and types so callers receive consistent structured error
responses.

packages/webcontainer/src/createWebContainerBashTool.tsx (2)

62-68: Minor: ToolResultState is referenced before its declaration.

The type ToolResultState used on line 66 is defined later at line 204. While TypeScript hoists type declarations so this compiles correctly, consider moving ToolResultState definition earlier (near line 62) for improved readability.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webcontainer/src/createWebContainerBashTool.tsx` around lines 62 -
68, ToolResultRendererProps references the ToolResultState type before its
declaration; move the ToolResultState type definition so it appears above (or
immediately before) the ToolResultRendererProps definition, or alternatively
inline/export it near the top of this file so ToolResultRendererProps references
a previously declared symbol — update the declaration order around
ToolResultState and ToolResultRendererProps to improve readability.

---

115-132: Inconsistent error handling: bash tool lacks try-catch wrapper.

The readFile and writeFile tools wrap their execute handlers in try-catch to return structured error responses. However, bash does not, so if getSandbox().executeCommand(command) throws (e.g., sandbox initialization failure), the exception propagates instead of returning { success: false, errorMessage: ... }.

♻️ Proposed fix for consistent error handling

     execute: async ({command}) => {
+      try {
         const result = await getSandbox().executeCommand(command);
         return {
           success: result.exitCode === 0,
           details: {
             command,
             stdout: result.stdout,
             stderr: result.stderr,
             exitCode: result.exitCode,
           },
           ...(result.exitCode === 0
             ? {}
             : {
                 errorMessage:
                   result.stderr || `Command exited with code ${result.exitCode}.`,
               }),
         } satisfies WebContainerBashToolOutput;
+      } catch (error) {
+        return {
+          success: false,
+          details: {
+            command,
+            stdout: '',
+            stderr: '',
+            exitCode: -1,
+          },
+          errorMessage:
+            error instanceof Error ? error.message : 'Failed to execute command',
+        } satisfies WebContainerBashToolOutput;
+      }
     },

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webcontainer/src/createWebContainerBashTool.tsx` around lines 115 -
132, The bash tool's execute handler (the async execute in
createWebContainerBashTool) doesn't catch exceptions from
getSandbox().executeCommand(command), so thrown errors propagate instead of
returning a structured WebContainerBashToolOutput; wrap the body of that execute
function in a try-catch, call getSandbox().executeCommand(command) inside try,
construct the success/details/errorMessage shape as currently done on nonzero
exitCode, and in catch return { success: false, errorMessage: error.message ||
String(error), details: { command } } to match the other tools' error-response
pattern.