@loopstack/sandbox-filesystem 0.2.0

package/src/tools/sandbox-create-directory.tool.ts

@@ -0,0 +1,93 @@
+/*
+Copyright 2025 The Loopstack Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+import { Injectable, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { BlockConfig, Tool, ToolResult, WithArguments } from '@loopstack/common';
+import { ToolBase, WorkflowExecution } from '@loopstack/core';
+import { SandboxCommand } from '@loopstack/sandbox-tool';
+
+const propertiesSchema = z
+  .object({
+    containerId: z.string().describe('The ID of the container to create the directory in'),
+    path: z.string().describe('The path of the directory to create'),
+    recursive: z.boolean().default(true).describe("Whether to create parent directories if they don't exist"),
+  })
+  .strict();
+
+type SandboxCreateDirectoryArgs = z.infer<typeof propertiesSchema>;
+
+interface SandboxCreateDirectoryResult {
+  path: string;
+  created: boolean;
+}
+
+@Injectable()
+@BlockConfig({
+  config: {
+    description: 'Create a directory in a sandbox container',
+  },
+})
+@WithArguments(propertiesSchema)
+export class SandboxCreateDirectory extends ToolBase<SandboxCreateDirectoryArgs> {
+  private readonly logger = new Logger(SandboxCreateDirectory.name);
+
+  @Tool() private sandboxCommand: SandboxCommand;
+
+  async execute(
+    args: SandboxCreateDirectoryArgs,
+    _ctx: WorkflowExecution,
+  ): Promise<ToolResult<SandboxCreateDirectoryResult>> {
+    const { containerId, path: dirPath, recursive } = args;
+
+    this.logger.debug(`Creating directory ${dirPath} in container ${containerId} (recursive: ${recursive})`);
+
+    const mkdirArgs = recursive ? ['-p', dirPath] : [dirPath];
+
+    const result = await this.sandboxCommand.execute({
+      containerId,
+      executable: 'mkdir',
+      args: mkdirArgs,
+      workingDirectory: '/',
+      timeout: 10000,
+    });
+
+    if (!result.data) {
+      this.logger.error(`Failed to create directory ${dirPath}: No result data`);
+      throw new Error(`Failed to create directory ${dirPath}: No result data`);
+    }
+
+    // Exit code 0 means success, exit code 1 with "File exists" is okay if directory already exists
+    const alreadyExists = result.data.exitCode !== 0 && result.data.stderr.includes('File exists');
+
+    if (result.data.exitCode !== 0 && !alreadyExists) {
+      this.logger.error(`Failed to create directory ${dirPath}: ${result.data.stderr || 'Unknown error'}`);
+      throw new Error(`Failed to create directory ${dirPath}: ${result.data.stderr || 'Unknown error'}`);
+    }
+
+    if (alreadyExists) {
+      this.logger.debug(`Directory ${dirPath} already exists`);
+    } else {
+      this.logger.log(`Successfully created directory ${dirPath} in container ${containerId}`);
+    }
+
+    return {
+      data: {
+        path: dirPath,
+        created: result.data.exitCode === 0,
+      },
+    };
+  }
+}

package/src/tools/sandbox-delete.tool.ts

@@ -0,0 +1,87 @@
+/*
+Copyright 2025 The Loopstack Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+import { Injectable, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { BlockConfig, Tool, ToolResult, WithArguments } from '@loopstack/common';
+import { ToolBase, WorkflowExecution } from '@loopstack/core';
+import { SandboxCommand } from '@loopstack/sandbox-tool';
+
+const propertiesSchema = z
+  .object({
+    containerId: z.string().describe('The ID of the container to delete the file/directory from'),
+    path: z.string().describe('The path to the file or directory to delete'),
+    recursive: z.boolean().default(false).describe('Whether to recursively delete directories and their contents'),
+    force: z.boolean().default(false).describe('Whether to force deletion without prompting for confirmation'),
+  })
+  .strict();
+
+type SandboxDeleteArgs = z.infer<typeof propertiesSchema>;
+
+interface SandboxDeleteResult {
+  path: string;
+  deleted: boolean;
+}
+
+@Injectable()
+@BlockConfig({
+  config: {
+    description: 'Delete a file or directory in a sandbox container',
+  },
+})
+@WithArguments(propertiesSchema)
+export class SandboxDelete extends ToolBase<SandboxDeleteArgs> {
+  private readonly logger = new Logger(SandboxDelete.name);
+
+  @Tool() private sandboxCommand: SandboxCommand;
+
+  async execute(args: SandboxDeleteArgs, _ctx: WorkflowExecution): Promise<ToolResult<SandboxDeleteResult>> {
+    const { containerId, path: targetPath, recursive, force } = args;
+
+    this.logger.debug(`Deleting ${targetPath} in container ${containerId} (recursive: ${recursive}, force: ${force})`);
+
+    const rmArgs: string[] = [];
+    if (recursive) rmArgs.push('-r');
+    if (force) rmArgs.push('-f');
+    rmArgs.push(targetPath);
+
+    const result = await this.sandboxCommand.execute({
+      containerId,
+      executable: 'rm',
+      args: rmArgs,
+      workingDirectory: '/',
+      timeout: 30000,
+    });
+
+    if (!result.data) {
+      this.logger.error(`Failed to delete ${targetPath}: No result data`);
+      throw new Error(`Failed to delete ${targetPath}: No result data`);
+    }
+
+    if (result.data.exitCode !== 0) {
+      this.logger.error(`Failed to delete ${targetPath}: ${result.data.stderr || 'Unknown error'}`);
+      throw new Error(`Failed to delete ${targetPath}: ${result.data.stderr || 'Unknown error'}`);
+    }
+
+    this.logger.log(`Successfully deleted ${targetPath} in container ${containerId}`);
+
+    return {
+      data: {
+        path: targetPath,
+        deleted: true,
+      },
+    };
+  }
+}

package/src/tools/sandbox-exists.tool.ts

@@ -0,0 +1,102 @@
+/*
+Copyright 2025 The Loopstack Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+import { Injectable, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { BlockConfig, Tool, ToolResult, WithArguments } from '@loopstack/common';
+import { ToolBase, WorkflowExecution } from '@loopstack/core';
+import { SandboxCommand } from '@loopstack/sandbox-tool';
+
+const propertiesSchema = z
+  .object({
+    containerId: z.string().describe('The ID of the container to check for file existence'),
+    path: z.string().describe('The path to check for existence'),
+  })
+  .strict();
+
+type SandboxExistsArgs = z.infer<typeof propertiesSchema>;
+
+interface SandboxExistsResult {
+  path: string;
+  exists: boolean;
+  type: 'file' | 'directory' | 'symlink' | 'other' | null;
+}
+
+@Injectable()
+@BlockConfig({
+  config: {
+    description: 'Check if a file or directory exists in a sandbox container',
+  },
+})
+@WithArguments(propertiesSchema)
+export class SandboxExists extends ToolBase<SandboxExistsArgs> {
+  private readonly logger = new Logger(SandboxExists.name);
+
+  @Tool() private sandboxCommand: SandboxCommand;
+
+  async execute(args: SandboxExistsArgs, _ctx: WorkflowExecution): Promise<ToolResult<SandboxExistsResult>> {
+    const { containerId, path: targetPath } = args;
+
+    this.logger.debug(`Checking existence of ${targetPath} in container ${containerId}`);
+
+    // Use test command to check existence and stat to get type
+    const result = await this.sandboxCommand.execute({
+      containerId,
+      executable: 'sh',
+      args: [
+        '-c',
+        `if [ -e '${targetPath.replace(/'/g, "'\\''")}' ]; then stat -c '%F' '${targetPath.replace(/'/g, "'\\''")}'; else echo 'NOT_FOUND'; fi`,
+      ],
+      workingDirectory: '/',
+      timeout: 10000,
+    });
+
+    if (!result.data) {
+      this.logger.error(`Failed to check existence of ${targetPath}: No result data`);
+      throw new Error(`Failed to check existence of ${targetPath}: No result data`);
+    }
+
+    if (result.data.exitCode !== 0) {
+      this.logger.error(`Failed to check existence of ${targetPath}: ${result.data.stderr || 'Unknown error'}`);
+      throw new Error(`Failed to check existence of ${targetPath}: ${result.data.stderr || 'Unknown error'}`);
+    }
+
+    const output = result.data.stdout.trim();
+    const exists = output !== 'NOT_FOUND';
+
+    let type: SandboxExistsResult['type'] = null;
+    if (exists) {
+      type = this.parseFileType(output);
+    }
+
+    this.logger.debug(`Path ${targetPath} exists: ${exists}${exists ? `, type: ${type}` : ''}`);
+
+    return {
+      data: {
+        path: targetPath,
+        exists,
+        type,
+      },
+    };
+  }
+
+  private parseFileType(statOutput: string): SandboxExistsResult['type'] {
+    const lower = statOutput.toLowerCase();
+    if (lower.includes('regular')) return 'file';
+    if (lower.includes('directory')) return 'directory';
+    if (lower.includes('symbolic link')) return 'symlink';
+    return 'other';
+  }
+}

package/src/tools/sandbox-file-info.tool.ts

@@ -0,0 +1,119 @@
+/*
+Copyright 2025 The Loopstack Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+import { Injectable, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { BlockConfig, Tool, ToolResult, WithArguments } from '@loopstack/common';
+import { ToolBase, WorkflowExecution } from '@loopstack/core';
+import { SandboxCommand } from '@loopstack/sandbox-tool';
+
+const propertiesSchema = z
+  .object({
+    containerId: z.string().describe('The ID of the container to get file info from'),
+    path: z.string().describe('The path to the file or directory'),
+  })
+  .strict();
+
+type SandboxFileInfoArgs = z.infer<typeof propertiesSchema>;
+
+interface SandboxFileInfoResult {
+  path: string;
+  name: string;
+  type: 'file' | 'directory' | 'symlink' | 'other';
+  size: number;
+  permissions: string;
+  owner: string;
+  group: string;
+  modifiedAt: string;
+  accessedAt: string;
+  createdAt: string;
+}
+
+@Injectable()
+@BlockConfig({
+  config: {
+    description: 'Get detailed information about a file or directory in a sandbox container',
+  },
+})
+@WithArguments(propertiesSchema)
+export class SandboxFileInfo extends ToolBase<SandboxFileInfoArgs> {
+  private readonly logger = new Logger(SandboxFileInfo.name);
+
+  @Tool() private sandboxCommand: SandboxCommand;
+
+  async execute(args: SandboxFileInfoArgs, _ctx: WorkflowExecution): Promise<ToolResult<SandboxFileInfoResult>> {
+    const { containerId, path: targetPath } = args;
+
+    this.logger.debug(`Getting file info for ${targetPath} in container ${containerId}`);
+
+    // Use stat to get detailed file information
+    // Format: type|size|permissions|owner|group|mtime|atime|ctime
+    const result = await this.sandboxCommand.execute({
+      containerId,
+      executable: 'stat',
+      args: ['-c', '%F|%s|%A|%U|%G|%y|%x|%w', targetPath],
+      workingDirectory: '/',
+      timeout: 10000,
+    });
+
+    if (!result.data) {
+      this.logger.error(`Failed to get file info for ${targetPath}: No result data`);
+      throw new Error(`Failed to get file info for ${targetPath}: No result data`);
+    }
+
+    if (result.data.exitCode !== 0) {
+      this.logger.error(`Failed to get file info for ${targetPath}: ${result.data.stderr || 'Unknown error'}`);
+      throw new Error(`Failed to get file info for ${targetPath}: ${result.data.stderr || 'Unknown error'}`);
+    }
+
+    const output = result.data.stdout.trim();
+    const parts = output.split('|');
+
+    if (parts.length < 8) {
+      this.logger.error(`Unexpected stat output format: ${output}`);
+      throw new Error(`Unexpected stat output format: ${output}`);
+    }
+
+    const [typeStr, sizeStr, permissions, owner, group, mtime, atime, ctime] = parts;
+
+    const name = targetPath.split('/').pop() || targetPath;
+    const fileType = this.parseFileType(typeStr);
+
+    this.logger.debug(`Retrieved info for ${targetPath}: type=${fileType}, size=${sizeStr}`);
+
+    return {
+      data: {
+        path: targetPath,
+        name,
+        type: fileType,
+        size: parseInt(sizeStr, 10),
+        permissions,
+        owner,
+        group,
+        modifiedAt: mtime,
+        accessedAt: atime,
+        createdAt: ctime === '-' ? mtime : ctime,
+      },
+    };
+  }
+
+  private parseFileType(typeStr: string): SandboxFileInfoResult['type'] {
+    const lower = typeStr.toLowerCase();
+    if (lower.includes('regular')) return 'file';
+    if (lower.includes('directory')) return 'directory';
+    if (lower.includes('symbolic link')) return 'symlink';
+    return 'other';
+  }
+}

package/src/tools/sandbox-list-directory.tool.ts

@@ -0,0 +1,131 @@
+/*
+Copyright 2025 The Loopstack Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+import { Injectable, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { BlockConfig, Tool, ToolResult, WithArguments } from '@loopstack/common';
+import { ToolBase, WorkflowExecution } from '@loopstack/core';
+import { SandboxCommand } from '@loopstack/sandbox-tool';
+
+const propertiesSchema = z
+  .object({
+    containerId: z.string().describe('The ID of the container to list the directory from'),
+    path: z.string().describe('The path to the directory to list'),
+    recursive: z.boolean().default(false).describe('Whether to list directories recursively'),
+  })
+  .strict();
+
+type SandboxListDirectoryArgs = z.infer<typeof propertiesSchema>;
+
+interface FileEntry {
+  name: string;
+  type: 'file' | 'directory' | 'symlink' | 'other';
+  size: number;
+  path: string;
+}
+
+interface SandboxListDirectoryResult {
+  path: string;
+  entries: FileEntry[];
+}
+
+@Injectable()
+@BlockConfig({
+  config: {
+    description: 'List files and directories in a sandbox container',
+  },
+})
+@WithArguments(propertiesSchema)
+export class SandboxListDirectory extends ToolBase<SandboxListDirectoryArgs> {
+  private readonly logger = new Logger(SandboxListDirectory.name);
+
+  @Tool() private sandboxCommand: SandboxCommand;
+
+  async execute(
+    args: SandboxListDirectoryArgs,
+    _ctx: WorkflowExecution,
+  ): Promise<ToolResult<SandboxListDirectoryResult>> {
+    const { containerId, path: dirPath, recursive } = args;
+
+    this.logger.debug(`Listing directory ${dirPath} in container ${containerId} (recursive: ${recursive})`);
+
+    // Use find for recursive, ls for non-recursive
+    // Output format: type size path
+    const command = recursive
+      ? `find '${dirPath.replace(/'/g, "'\\''")}' -printf '%y %s %p\\n'`
+      : `find '${dirPath.replace(/'/g, "'\\''")}' -maxdepth 1 -printf '%y %s %p\\n'`;
+
+    const result = await this.sandboxCommand.execute({
+      containerId,
+      executable: 'sh',
+      args: ['-c', command],
+      workingDirectory: '/',
+      timeout: 30000,
+    });
+
+    if (!result.data) {
+      this.logger.error(`Failed to list directory ${dirPath}: No result data`);
+      throw new Error(`Failed to list directory ${dirPath}: No result data`);
+    }
+
+    if (result.data.exitCode !== 0) {
+      this.logger.error(`Failed to list directory ${dirPath}: ${result.data.stderr || 'Unknown error'}`);
+      throw new Error(`Failed to list directory ${dirPath}: ${result.data.stderr || 'Unknown error'}`);
+    }
+
+    const entries: FileEntry[] = [];
+    const lines = result.data.stdout.split('\n').filter((line) => line.trim());
+
+    for (const line of lines) {
+      const match = line.match(/^(\S)\s+(\d+)\s+(.+)$/);
+      if (match) {
+        const [, typeChar, sizeStr, fullPath] = match;
+        const name = fullPath.split('/').pop() || fullPath;
+
+        // Skip the directory itself in non-recursive mode
+        if (fullPath === dirPath) continue;
+
+        entries.push({
+          name,
+          type: this.parseFileType(typeChar),
+          size: parseInt(sizeStr, 10),
+          path: fullPath,
+        });
+      }
+    }
+
+    this.logger.debug(`Listed ${entries.length} entries in ${dirPath}`);
+
+    return {
+      data: {
+        path: dirPath,
+        entries,
+      },
+    };
+  }
+
+  private parseFileType(typeChar: string): FileEntry['type'] {
+    switch (typeChar) {
+      case 'f':
+        return 'file';
+      case 'd':
+        return 'directory';
+      case 'l':
+        return 'symlink';
+      default:
+        return 'other';
+    }
+  }
+}

package/src/tools/sandbox-read-file.tool.ts

@@ -0,0 +1,82 @@
+/*
+Copyright 2025 The Loopstack Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+import { Injectable, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { BlockConfig, Tool, ToolResult, WithArguments } from '@loopstack/common';
+import { ToolBase, WorkflowExecution } from '@loopstack/core';
+import { SandboxCommand } from '@loopstack/sandbox-tool';
+
+const propertiesSchema = z
+  .object({
+    containerId: z.string().describe('The ID of the container to read the file from'),
+    path: z.string().describe('The path to the file to read'),
+    encoding: z.enum(['utf8', 'base64']).default('utf8').describe('The encoding to use when reading the file'),
+  })
+  .strict();
+
+type SandboxReadFileArgs = z.infer<typeof propertiesSchema>;
+
+interface SandboxReadFileResult {
+  content: string;
+  encoding: string;
+}
+
+@Injectable()
+@BlockConfig({
+  config: {
+    description: 'Read file contents from a sandbox container',
+  },
+})
+@WithArguments(propertiesSchema)
+export class SandboxReadFile extends ToolBase<SandboxReadFileArgs> {
+  private readonly logger = new Logger(SandboxReadFile.name);
+
+  @Tool() private sandboxCommand: SandboxCommand;
+
+  async execute(args: SandboxReadFileArgs, _ctx: WorkflowExecution): Promise<ToolResult<SandboxReadFileResult>> {
+    const { containerId, path, encoding } = args;
+
+    this.logger.debug(`Reading file ${path} from container ${containerId} (encoding: ${encoding})`);
+
+    const executable = encoding === 'base64' ? 'base64' : 'cat';
+    const result = await this.sandboxCommand.execute({
+      containerId,
+      executable,
+      args: [path],
+      workingDirectory: '/',
+      timeout: 30000,
+    });
+
+    if (!result.data) {
+      this.logger.error(`Failed to read file ${path}: No result data`);
+      throw new Error(`Failed to read file ${path}: No result data`);
+    }
+
+    if (result.data.exitCode !== 0) {
+      this.logger.error(`Failed to read file ${path}: ${result.data.stderr || 'Unknown error'}`);
+      throw new Error(`Failed to read file ${path}: ${result.data.stderr || 'Unknown error'}`);
+    }
+
+    this.logger.debug(`Successfully read file ${path} (${result.data.stdout.length} characters)`);
+
+    return {
+      data: {
+        content: result.data.stdout,
+        encoding,
+      },
+    };
+  }
+}