@llmist/cli 9.1.2 → 9.3.0

package/README.md

@@ -0,0 +1,107 @@
+# @llmist/cli
+
+<p align="center">
+  <a href="https://github.com/zbigniewsobiecki/llmist/actions/workflows/ci.yml"><img src="https://github.com/zbigniewsobiecki/llmist/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@llmist/cli"><img src="https://img.shields.io/npm/v/@llmist/cli.svg" alt="npm version"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
+</p>
+
+**Command-line interface for llmist - run LLM agents from the terminal.**
+
+## Installation
+
+```bash
+npm install -g @llmist/cli
+# or
+bunx @llmist/cli
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+export OPENAI_API_KEY="sk-..."
+
+# Quick completion
+llmist complete "Explain TypeScript generics in one paragraph"
+
+# Run an agent with gadgets
+llmist agent "Search for files" --gadgets ./my-gadgets/
+
+# Interactive chat
+llmist chat
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `complete <prompt>` | One-shot LLM completion |
+| `agent <prompt>` | Run agent with gadgets |
+| `chat` | Interactive chat session |
+| `tui` | Launch terminal UI |
+
+## Using Gadgets
+
+Load gadgets from various sources:
+
+```bash
+# Local directory
+llmist agent "Do something" --gadgets ./gadgets/
+
+# npm package
+llmist agent "Search the web" --gadgets dhalsim/BrowseWeb
+
+# Git URL
+llmist agent "Process files" --gadgets github:user/repo
+```
+
+## Configuration
+
+Create a `llmist.toml` file for reusable configurations:
+
+```toml
+[agent]
+model = "sonnet"
+system = "You are a helpful assistant"
+
+[gadgets]
+paths = ["./gadgets"]
+external = ["dhalsim/BrowseWeb"]
+
+[display]
+markdown = true
+colors = true
+```
+
+Use with:
+
+```bash
+llmist agent "Do something" --config ./llmist.toml
+```
+
+## Terminal UI
+
+The TUI provides an interactive interface to browse execution history, inspect raw payloads, and debug agent runs:
+
+```bash
+llmist tui
+```
+
+## Documentation
+
+Full documentation at [llmist.dev/cli](https://llmist.dev/cli/getting-started/introduction/)
+
+- [Configuration Reference](https://llmist.dev/cli/configuration/toml-reference/)
+- [Writing Gadgets](https://llmist.dev/cli/gadgets/local-gadgets/)
+- [External Gadgets](https://llmist.dev/cli/gadgets/external-gadgets/)
+- [TUI Guide](https://llmist.dev/cli/tui/overview/)
+
+## Related Packages
+
+- [`llmist`](https://www.npmjs.com/package/llmist) - Core library
+- [`@llmist/testing`](https://www.npmjs.com/package/@llmist/testing) - Testing utilities
+
+## License
+
+MIT

package/dist/cli.js

@@ -79,7 +79,7 @@ import { Command, InvalidArgumentError as InvalidArgumentError2 } from "commande
 // package.json
 var package_default = {
   name: "@llmist/cli",
-  version: "9.1.2",
+  version: "9.3.0",
   description: "CLI for llmist - run LLM agents from the command line",
   type: "module",
   main: "dist/cli.js",
@@ -94,6 +94,7 @@ var package_default = {
     clean: "rimraf dist",
     postinstall: "node scripts/postinstall.js"
   },
+  homepage: "https://llmist.dev",
   repository: {
     type: "git",
     url: "https://github.com/zbigniewsobiecki/llmist.git",
@@ -360,6 +361,84 @@ import { AbstractGadget } from "llmist";
 import { z as z2 } from "zod";
 import { createGadget as createGadget2 } 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((resolve2, reject) => {
+    proc.on("exit", (code) => {
+      resolve2(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";
@@ -449,11 +528,16 @@ q`
     const validatedPath = validatePathIsWithinCwd(filePath);
     const safeCommands = filterDangerousCommands(commands);
     try {
-      const proc = Bun.spawn(["ed", validatedPath], {
+      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();
@@ -773,7 +857,7 @@ var runCommand = createGadget6({
     }
     let timeoutId;
     try {
-      const proc = Bun.spawn(argv, {
+      const proc = spawn(argv, {
         cwd: workingDir,
         stdout: "pipe",
         stderr: "pipe"
@@ -848,49 +932,71 @@ function parseGadgetSpecifier(specifier) {
     let baseUrl;
     let ref;
     let preset;
+    let gadgetName;
+    const extractGadgetName = (str) => {
+      const match = str.match(/^(.*)\/([A-Z][a-zA-Z0-9]*)$/);
+      if (match) {
+        return { rest: match[1], gadgetName: match[2] };
+      }
+      return { rest: str };
+    };
     if (url.includes("#")) {
       const hashIndex = url.indexOf("#");
       baseUrl = url.slice(0, hashIndex);
-      const refAndPreset = url.slice(hashIndex + 1);
-      if (refAndPreset.includes(":")) {
-        const colonIndex = refAndPreset.indexOf(":");
-        ref = refAndPreset.slice(0, colonIndex);
-        preset = refAndPreset.slice(colonIndex + 1);
+      let refAndRest = url.slice(hashIndex + 1);
+      const gadgetResult = extractGadgetName(refAndRest);
+      refAndRest = gadgetResult.rest;
+      gadgetName = gadgetResult.gadgetName;
+      if (refAndRest.includes(":")) {
+        const colonIndex = refAndRest.indexOf(":");
+        ref = refAndRest.slice(0, colonIndex);
+        preset = refAndRest.slice(colonIndex + 1);
       } else {
-        ref = refAndPreset;
+        ref = refAndRest;
       }
     } else {
       const gitExtIndex = url.indexOf(".git");
       if (gitExtIndex !== -1) {
-        const afterGit = url.slice(gitExtIndex + 4);
+        let afterGit = url.slice(gitExtIndex + 4);
+        baseUrl = url.slice(0, gitExtIndex + 4);
+        const gadgetResult = extractGadgetName(afterGit);
+        afterGit = gadgetResult.rest;
+        gadgetName = gadgetResult.gadgetName;
         if (afterGit.startsWith(":")) {
-          baseUrl = url.slice(0, gitExtIndex + 4);
           preset = afterGit.slice(1);
-        } else {
-          baseUrl = url;
         }
       } else {
-        baseUrl = url;
+        const gadgetResult = extractGadgetName(url);
+        baseUrl = gadgetResult.rest;
+        gadgetName = gadgetResult.gadgetName;
       }
     }
     return {
       type: "git",
       package: baseUrl,
       version: ref,
-      preset
+      preset,
+      gadgetName
     };
   }
-  const npmMatch = specifier.match(
-    /^(@?[a-z0-9][\w.-]*)(?:@([\w.-]+))?(?::([a-z]+))?(?:\/(\w+))?$/i
+  let npmSpecifier = specifier;
+  let npmGadgetName;
+  const gadgetMatch = specifier.match(/^(.+)\/([A-Z][a-zA-Z0-9]*)$/);
+  if (gadgetMatch) {
+    npmSpecifier = gadgetMatch[1];
+    npmGadgetName = gadgetMatch[2];
+  }
+  const npmMatch = npmSpecifier.match(
+    /^(@[a-z0-9][\w.-]*\/[a-z0-9][\w.-]*|[a-z0-9][\w.-]*)(?:@([\w.-]+))?(?::([a-z]+))?$/i
   );
   if (npmMatch) {
-    const [, pkg, version, preset, gadgetName] = npmMatch;
+    const [, pkg, version, preset] = npmMatch;
     return {
       type: "npm",
       package: pkg,
       version,
       preset,
-      gadgetName
+      gadgetName: npmGadgetName
     };
   }
   return null;
@@ -1144,6 +1250,14 @@ function expandHomePath(input) {
   }
   return path5.join(home, input.slice(1));
 }
+function parseLocalSpecifier(specifier) {
+  const match = specifier.match(/^(.+):([A-Z][a-zA-Z0-9]*)$/);
+  if (match) {
+    const [, basePath, gadgetName] = match;
+    return { path: basePath, gadgetName };
+  }
+  return { path: specifier };
+}
 function isFileLikeSpecifier(specifier) {
   return PATH_PREFIXES.some((prefix) => specifier.startsWith(prefix)) || specifier.includes(path5.sep);
 }
@@ -1227,7 +1341,10 @@ async function loadGadgets(specifiers, cwd, importer = (specifier) => import(spe
         throw new Error(`Failed to load external package '${specifier}': ${message}`);
       }
     }
-    const resolved = resolveGadgetSpecifier(specifier, cwd);
+    const localSpec = isFileLikeSpecifier(specifier) ? parseLocalSpecifier(specifier) : null;
+    const pathToResolve = localSpec?.path ?? specifier;
+    const gadgetNameFilter = localSpec?.gadgetName;
+    const resolved = resolveGadgetSpecifier(pathToResolve, cwd);
     let exports;
     try {
       exports = await importer(resolved);
@@ -1242,6 +1359,17 @@ async function loadGadgets(specifiers, cwd, importer = (specifier) => import(spe
       const message = error instanceof Error ? error.message : String(error);
       throw new Error(`Failed to initialize gadgets from module '${specifier}': ${message}`);
     }
+    if (gadgetNameFilter) {
+      const filtered = extracted.filter(
+        (g) => g.name?.toLowerCase() === gadgetNameFilter.toLowerCase()
+      );
+      if (filtered.length === 0) {
+        throw new Error(
+          `Gadget '${gadgetNameFilter}' not found in module '${pathToResolve}'. Available gadgets: ${extracted.map((g) => g.name).join(", ")}`
+        );
+      }
+      extracted = filtered;
+    }
     if (extracted.length === 0) {
       throw new Error(`Module '${specifier}' does not export any Gadget instances.`);
     }