@llmist/cli 10.1.1 → 10.3.1

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import * as llmist from 'llmist';
+
+declare const editFile: llmist.AbstractGadget;
+
+/**
+ * ListDirectory gadget - Lists files and directories with full metadata.
+ * All directory paths are validated to be within the current working directory.
+ */
+declare const listDirectory: llmist.AbstractGadget;
+
+/**
+ * ReadFile gadget - Reads the entire content of a file and returns it as text.
+ * All file paths are validated to be within the current working directory.
+ */
+declare const readFile: llmist.AbstractGadget;
+
+/**
+ * WriteFile gadget - Writes content to a file.
+ * Creates parent directories if needed. Overwrites existing files.
+ * All file paths are validated to be within the current working directory.
+ */
+declare const writeFile: llmist.AbstractGadget;
+
+/**
+ * RunCommand gadget - Executes a command with arguments and returns its output.
+ *
+ * Uses argv array to bypass shell interpretation entirely - arguments are
+ * passed directly to the process without any escaping or shell expansion.
+ * This allows special characters (quotes, backticks, newlines) to work correctly.
+ *
+ * Safety should be added externally via the hook system (see example 10).
+ *
+ * Output format follows the established pattern: `status=N\n\n<output>`
+ */
+declare const runCommand: llmist.AbstractGadget;
+
+/**
+ * Exception thrown when a path validation fails due to sandbox constraints.
+ * This ensures all file operations are restricted to the current working directory.
+ */
+declare class PathSandboxException extends Error {
+    constructor(inputPath: string, reason: string);
+}
+/**
+ * Validates that a given path is within the current working directory.
+ * This prevents directory traversal attacks and ensures all file operations
+ * are sandboxed to the CWD and its subdirectories.
+ *
+ * @param inputPath - Path to validate (can be relative or absolute)
+ * @returns The validated absolute path
+ * @throws PathSandboxException if the path is outside the CWD
+ * @throws Error for other file system errors
+ */
+declare function validatePathIsWithinCwd(inputPath: string): string;
+
+export { editFile as EditFile, listDirectory as ListDirectory, PathSandboxException, readFile as ReadFile, runCommand as RunCommand, writeFile as WriteFile, editFile, listDirectory, readFile, runCommand, validatePathIsWithinCwd, writeFile };

package/dist/index.js

@@ -0,0 +1,552 @@
+// src/builtins/filesystem/edit-file.ts
+import { z } from "zod";
+import { createGadget } from "llmist";
+
+// src/spawn.ts
+import { spawn as nodeSpawn } from "child_process";
+var isBun = typeof Bun !== "undefined";
+function adaptBunProcess(proc) {
+  return {
+    exited: proc.exited,
+    stdout: proc.stdout ?? null,
+    stderr: proc.stderr ?? null,
+    stdin: proc.stdin ? {
+      write(data) {
+        proc.stdin?.write(data);
+      },
+      end() {
+        proc.stdin?.end();
+      }
+    } : null,
+    kill: () => proc.kill()
+  };
+}
+function nodeStreamToReadableStream(nodeStream) {
+  if (!nodeStream) return null;
+  return new ReadableStream({
+    start(controller) {
+      nodeStream.on("data", (chunk) => {
+        controller.enqueue(new Uint8Array(chunk));
+      });
+      nodeStream.on("end", () => {
+        controller.close();
+      });
+      nodeStream.on("error", (err) => {
+        controller.error(err);
+      });
+    },
+    cancel() {
+      nodeStream.destroy();
+    }
+  });
+}
+function spawn(argv, options = {}) {
+  if (isBun) {
+    return adaptBunProcess(Bun.spawn(argv, options));
+  }
+  const [command, ...args] = argv;
+  const proc = nodeSpawn(command, args, {
+    cwd: options.cwd,
+    stdio: [
+      options.stdin === "pipe" ? "pipe" : options.stdin ?? "ignore",
+      options.stdout === "pipe" ? "pipe" : options.stdout ?? "ignore",
+      options.stderr === "pipe" ? "pipe" : options.stderr ?? "ignore"
+    ]
+  });
+  const exited = new Promise((resolve, reject) => {
+    proc.on("exit", (code) => {
+      resolve(code ?? 1);
+    });
+    proc.on("error", (err) => {
+      reject(err);
+    });
+  });
+  const stdin = proc.stdin ? {
+    write(data) {
+      proc.stdin?.write(data);
+    },
+    end() {
+      proc.stdin?.end();
+    }
+  } : null;
+  return {
+    exited,
+    stdout: nodeStreamToReadableStream(proc.stdout),
+    stderr: nodeStreamToReadableStream(proc.stderr),
+    stdin,
+    kill() {
+      proc.kill();
+    }
+  };
+}
+
+// src/builtins/filesystem/utils.ts
+import fs from "fs";
+import path from "path";
+var PathSandboxException = class extends Error {
+  constructor(inputPath, reason) {
+    super(`Path access denied: ${inputPath}. ${reason}`);
+    this.name = "PathSandboxException";
+  }
+};
+function validatePathIsWithinCwd(inputPath) {
+  const cwd = process.cwd();
+  const resolvedPath = path.resolve(cwd, inputPath);
+  let finalPath;
+  try {
+    finalPath = fs.realpathSync(resolvedPath);
+  } catch (error) {
+    const nodeError = error;
+    if (nodeError.code === "ENOENT") {
+      finalPath = resolvedPath;
+    } else {
+      throw error;
+    }
+  }
+  const cwdWithSep = cwd + path.sep;
+  if (!finalPath.startsWith(cwdWithSep) && finalPath !== cwd) {
+    throw new PathSandboxException(inputPath, "Path is outside the current working directory");
+  }
+  return finalPath;
+}
+
+// src/builtins/filesystem/edit-file.ts
+function filterDangerousCommands(commands) {
+  return commands.split("\n").filter((line) => !line.trimStart().startsWith("!")).join("\n");
+}
+var editFile = createGadget({
+  name: "EditFile",
+  description: "Edit a file using ed commands. Ed is a line-oriented text editor - pipe commands to it for precise file modifications. Commands are executed in sequence. Remember to end with 'w' (write) and 'q' (quit). Shell escape commands (!) are filtered for security.",
+  schema: z.object({
+    filePath: z.string().describe("Path to the file to edit (relative or absolute)"),
+    commands: z.string().describe("Ed commands to execute, one per line")
+  }),
+  examples: [
+    {
+      params: {
+        filePath: "config.txt",
+        commands: `1,$p
+q`
+      },
+      output: "path=config.txt\n\n32\nkey=value\noption=true",
+      comment: "Print entire file contents (ed shows byte count, then content)"
+    },
+    {
+      params: {
+        filePath: "data.txt",
+        commands: `1,$s/foo/bar/g
+w
+q`
+      },
+      output: "path=data.txt\n\n42\n42",
+      comment: "Replace all 'foo' with 'bar' (ed shows bytes read, then bytes written)"
+    },
+    {
+      params: {
+        filePath: "list.txt",
+        commands: `3d
+w
+q`
+      },
+      output: "path=list.txt\n\n45\n28",
+      comment: "Delete line 3, save and quit"
+    },
+    {
+      params: {
+        filePath: "readme.txt",
+        commands: `$a
+New last line
+.
+w
+q`
+      },
+      output: "path=readme.txt\n\n40\n56",
+      comment: "Append text after last line ($ = last line, . = end input mode)"
+    }
+  ],
+  timeoutMs: 3e4,
+  execute: async ({ filePath, commands }) => {
+    const validatedPath = validatePathIsWithinCwd(filePath);
+    const safeCommands = filterDangerousCommands(commands);
+    try {
+      const proc = spawn(["ed", validatedPath], {
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe"
+      });
+      if (!proc.stdin) {
+        return `path=${filePath}
+
+error: Failed to open stdin for ed process`;
+      }
+      proc.stdin.write(`${safeCommands}
+`);
+      proc.stdin.end();
+      let timeoutId;
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+          proc.kill();
+          reject(new Error("ed command timed out after 30000ms"));
+        }, 3e4);
+      });
+      const [exitCode, stdout, stderr] = await Promise.race([
+        Promise.all([
+          proc.exited,
+          new Response(proc.stdout).text(),
+          new Response(proc.stderr).text()
+        ]),
+        timeoutPromise
+      ]);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      const output = [stdout, stderr].filter(Boolean).join("\n").trim();
+      if (exitCode !== 0) {
+        return `path=${filePath}
+
+${output || "ed exited with non-zero status"}`;
+      }
+      return `path=${filePath}
+
+${output || "(no output)"}`;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return `path=${filePath}
+
+error: ${message}`;
+    }
+  }
+});
+
+// src/builtins/filesystem/list-directory.ts
+import fs2 from "fs";
+import path2 from "path";
+import { z as z2 } from "zod";
+import { createGadget as createGadget2 } from "llmist";
+function listFiles(dirPath, basePath = dirPath, maxDepth = 1, currentDepth = 1) {
+  const entries = [];
+  try {
+    const items = fs2.readdirSync(dirPath);
+    for (const item of items) {
+      const fullPath = path2.join(dirPath, item);
+      const relativePath = path2.relative(basePath, fullPath);
+      try {
+        const stats = fs2.lstatSync(fullPath);
+        let type;
+        let size;
+        if (stats.isSymbolicLink()) {
+          type = "symlink";
+          size = 0;
+        } else if (stats.isDirectory()) {
+          type = "directory";
+          size = 0;
+        } else {
+          type = "file";
+          size = stats.size;
+        }
+        entries.push({
+          name: item,
+          relativePath,
+          type,
+          size,
+          modified: Math.floor(stats.mtime.getTime() / 1e3)
+        });
+        if (type === "directory" && currentDepth < maxDepth) {
+          try {
+            validatePathIsWithinCwd(fullPath);
+            const subEntries = listFiles(fullPath, basePath, maxDepth, currentDepth + 1);
+            entries.push(...subEntries);
+          } catch {
+          }
+        }
+      } catch {
+      }
+    }
+  } catch {
+    return [];
+  }
+  return entries;
+}
+function formatAge(epochSeconds) {
+  const now = Math.floor(Date.now() / 1e3);
+  const seconds = now - epochSeconds;
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d`;
+  const weeks = Math.floor(days / 7);
+  if (weeks < 4) return `${weeks}w`;
+  const months = Math.floor(days / 30);
+  if (months < 12) return `${months}mo`;
+  const years = Math.floor(days / 365);
+  return `${years}y`;
+}
+function formatEntriesAsString(entries) {
+  if (entries.length === 0) {
+    return "#empty";
+  }
+  const sortedEntries = [...entries].sort((a, b) => {
+    const typeOrder = { directory: 0, file: 1, symlink: 2 };
+    const typeCompare = typeOrder[a.type] - typeOrder[b.type];
+    if (typeCompare !== 0) return typeCompare;
+    return a.relativePath.localeCompare(b.relativePath);
+  });
+  const typeCode = {
+    directory: "D",
+    file: "F",
+    symlink: "L"
+  };
+  const encodeName = (name) => name.replace(/\|/g, "%7C").replace(/\n/g, "%0A");
+  const header = "#T|N|S|A";
+  const rows = sortedEntries.map(
+    (e) => `${typeCode[e.type]}|${encodeName(e.relativePath)}|${e.size}|${formatAge(e.modified)}`
+  );
+  return [header, ...rows].join("\n");
+}
+var listDirectory = createGadget2({
+  name: "ListDirectory",
+  description: "List files and directories in a directory with full details (names, types, sizes, modification dates). Use maxDepth to explore subdirectories recursively. The directory path must be within the current working directory or its subdirectories.",
+  schema: z2.object({
+    directoryPath: z2.string().default(".").describe("Path to the directory to list"),
+    maxDepth: z2.number().int().min(1).max(10).default(1).describe(
+      "Maximum depth to recurse (1 = immediate children only, 2 = include grandchildren, etc.)"
+    )
+  }),
+  examples: [
+    {
+      params: { directoryPath: ".", maxDepth: 1 },
+      output: "path=. maxDepth=1\n\n#T|N|S|A\nD|src|0|2h\nD|tests|0|1d\nF|package.json|2841|3h",
+      comment: "List current directory"
+    },
+    {
+      params: { directoryPath: "src", maxDepth: 2 },
+      output: "path=src maxDepth=2\n\n#T|N|S|A\nD|components|0|1d\nD|utils|0|2d\nF|index.ts|512|1h\nF|components/Button.tsx|1024|3h",
+      comment: "List src directory recursively"
+    }
+  ],
+  execute: ({ directoryPath, maxDepth }) => {
+    const validatedPath = validatePathIsWithinCwd(directoryPath);
+    const stats = fs2.statSync(validatedPath);
+    if (!stats.isDirectory()) {
+      throw new Error(`Path is not a directory: ${directoryPath}`);
+    }
+    const entries = listFiles(validatedPath, validatedPath, maxDepth);
+    const formattedList = formatEntriesAsString(entries);
+    return `path=${directoryPath} maxDepth=${maxDepth}
+
+${formattedList}`;
+  }
+});
+
+// src/builtins/filesystem/read-file.ts
+import fs3 from "fs";
+import { z as z3 } from "zod";
+import { createGadget as createGadget3 } from "llmist";
+var readFile = createGadget3({
+  name: "ReadFile",
+  description: "Read the entire content of a file and return it as text. The file path must be within the current working directory or its subdirectories.",
+  schema: z3.object({
+    filePath: z3.string().describe("Path to the file to read (relative or absolute)")
+  }),
+  examples: [
+    {
+      params: { filePath: "package.json" },
+      output: 'path=package.json\n\n{\n  "name": "my-project",\n  "version": "1.0.0"\n  ...\n}',
+      comment: "Read a JSON config file"
+    },
+    {
+      params: { filePath: "src/index.ts" },
+      output: "path=src/index.ts\n\nexport function main() { ... }",
+      comment: "Read a source file"
+    }
+  ],
+  execute: ({ filePath }) => {
+    const validatedPath = validatePathIsWithinCwd(filePath);
+    const content = fs3.readFileSync(validatedPath, "utf-8");
+    return `path=${filePath}
+
+${content}`;
+  }
+});
+
+// src/builtins/filesystem/write-file.ts
+import fs4 from "fs";
+import path3 from "path";
+import { z as z4 } from "zod";
+import { createGadget as createGadget4 } from "llmist";
+var writeFile = createGadget4({
+  name: "WriteFile",
+  description: "Write content to a file. Creates parent directories if needed. Overwrites existing files. The file path must be within the current working directory or its subdirectories.",
+  schema: z4.object({
+    filePath: z4.string().describe("Path to the file to write (relative or absolute)"),
+    content: z4.string().describe("Content to write to the file")
+  }),
+  examples: [
+    {
+      params: { filePath: "output.txt", content: "Hello, World!" },
+      output: "path=output.txt\n\nWrote 13 bytes",
+      comment: "Write a simple text file"
+    },
+    {
+      params: {
+        filePath: "src/server.ts",
+        content: `import { serve } from "bun";
+
+const port = 3000;
+
+serve({
+  port,
+  fetch: (req) => new Response(\`Hello from \${req.url}\`),
+});
+
+console.log(\`Server running on http://localhost:\${port}\`);`
+      },
+      output: "path=src/server.ts\n\nWrote 198 bytes (created directory: src)",
+      comment: "Write code with template literals - NO escaping needed inside heredoc (use <<<EOF...EOF)"
+    }
+  ],
+  execute: ({ filePath, content }) => {
+    const validatedPath = validatePathIsWithinCwd(filePath);
+    const parentDir = path3.dirname(validatedPath);
+    let createdDir = false;
+    if (!fs4.existsSync(parentDir)) {
+      validatePathIsWithinCwd(parentDir);
+      fs4.mkdirSync(parentDir, { recursive: true });
+      createdDir = true;
+    }
+    fs4.writeFileSync(validatedPath, content, "utf-8");
+    const bytesWritten = Buffer.byteLength(content, "utf-8");
+    const dirNote = createdDir ? ` (created directory: ${path3.dirname(filePath)})` : "";
+    return `path=${filePath}
+
+Wrote ${bytesWritten} bytes${dirNote}`;
+  }
+});
+
+// src/builtins/run-command.ts
+import { z as z5 } from "zod";
+import { createGadget as createGadget5 } from "llmist";
+var runCommand = createGadget5({
+  name: "RunCommand",
+  description: "Execute a command with arguments and return its output. Uses argv array to bypass shell - arguments are passed directly without interpretation. Returns stdout/stderr combined with exit status.",
+  schema: z5.object({
+    argv: z5.array(z5.string()).describe("Command and arguments as array (e.g., ['git', 'commit', '-m', 'message'])"),
+    cwd: z5.string().optional().describe("Working directory for the command (default: current directory)"),
+    timeout: z5.number().default(3e4).describe("Timeout in milliseconds (default: 30000)")
+  }),
+  examples: [
+    {
+      params: { argv: ["ls", "-la"], timeout: 3e4 },
+      output: "status=0\n\ntotal 24\ndrwxr-xr-x  5 user  staff   160 Nov 27 10:00 .\ndrwxr-xr-x  3 user  staff    96 Nov 27 09:00 ..\n-rw-r--r--  1 user  staff  1024 Nov 27 10:00 package.json",
+      comment: "List directory contents with details"
+    },
+    {
+      params: { argv: ["echo", "Hello World"], timeout: 3e4 },
+      output: "status=0\n\nHello World",
+      comment: "Echo without shell - argument passed directly"
+    },
+    {
+      params: { argv: ["cat", "nonexistent.txt"], timeout: 3e4 },
+      output: "status=1\n\ncat: nonexistent.txt: No such file or directory",
+      comment: "Command that fails returns non-zero status"
+    },
+    {
+      params: { argv: ["pwd"], cwd: "/tmp", timeout: 3e4 },
+      output: "status=0\n\n/tmp",
+      comment: "Execute command in a specific directory"
+    },
+    {
+      params: {
+        argv: [
+          "gh",
+          "pr",
+          "review",
+          "123",
+          "--comment",
+          "--body",
+          "Review with `backticks` and 'quotes'"
+        ],
+        timeout: 3e4
+      },
+      output: "status=0\n\n(no output)",
+      comment: "Complex arguments with special characters - no escaping needed"
+    },
+    {
+      params: {
+        argv: [
+          "gh",
+          "pr",
+          "review",
+          "123",
+          "--approve",
+          "--body",
+          "## Review Summary\n\n**Looks good!**\n\n- Clean code\n- Tests pass"
+        ],
+        timeout: 3e4
+      },
+      output: "status=0\n\nApproving pull request #123",
+      comment: "Multiline body: --body flag and content must be SEPARATE array elements"
+    }
+  ],
+  execute: async ({ argv, cwd, timeout }) => {
+    const workingDir = cwd ?? process.cwd();
+    if (argv.length === 0) {
+      return "status=1\n\nerror: argv array cannot be empty";
+    }
+    let timeoutId;
+    try {
+      const proc = spawn(argv, {
+        cwd: workingDir,
+        stdout: "pipe",
+        stderr: "pipe"
+      });
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+          proc.kill();
+          reject(new Error(`Command timed out after ${timeout}ms`));
+        }, timeout);
+      });
+      const [exitCode, stdout, stderr] = await Promise.race([
+        Promise.all([
+          proc.exited,
+          new Response(proc.stdout).text(),
+          new Response(proc.stderr).text()
+        ]),
+        timeoutPromise
+      ]);
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      const output = [stdout, stderr].filter(Boolean).join("\n").trim();
+      return `status=${exitCode}
+
+${output || "(no output)"}`;
+    } catch (error) {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      return `status=1
+
+error: ${message}`;
+    }
+  }
+});
+export {
+  editFile as EditFile,
+  listDirectory as ListDirectory,
+  PathSandboxException,
+  readFile as ReadFile,
+  runCommand as RunCommand,
+  writeFile as WriteFile,
+  editFile,
+  listDirectory,
+  readFile,
+  runCommand,
+  validatePathIsWithinCwd,
+  writeFile
+};
+//# sourceMappingURL=index.js.map