just-bash-executor

@just-bash/executor — agent guide

This file is for an AI agent writing code that uses @just-bash/executor. It maps each input (an OpenAPI spec, a GraphQL endpoint, an MCP server, or your own JS functions) to the exact code to write and the exact surfaces (JS API + bash CLI) the user gets back.

Read top to bottom on the first task; jump by section number on later tasks.

§1. Decide which source kind you have

Have an OpenAPI spec / Swagger doc?     → §3 OpenAPI
Have a GraphQL endpoint or SDL?         → §4 GraphQL
Have an MCP server (URL or stdio)?      → §5 MCP
Defining tools yourself in code?        → §2 Inline
Mixing several of the above?            → call sources.add() once per source
                                          inside the same setup(); paths stay
                                          namespaced by `name`

For all four, the consuming code is identical (§6, §7) — what changes is the createExecutor config.

§2. Inline tools

Use when there's no upstream spec — the user wants to expose specific JS functions to the sandbox.

import { Bash } from "just-bash";
import { createExecutor } from "@just-bash/executor";

const executor = await createExecutor({
  tools: {
    "ns.action": {
      description: "What it does",
      execute: async (args: { /* shape */ }, { abortSignal }) => {
        // Forward abortSignal to cancellable I/O.
        return { /* JSON-serializable */ };
      },
    },
  },
});

const bash = new Bash({
  customCommands: executor.commands,
  javascript: { invokeTool: executor.invokeTool },
});

Conversion (single rule):

key in tools: {…}      JS                          bash
"ns.action"      →     await tools.ns.action(args) ns action key=value
                                                    ns action --key value
                                                    ns action --json '{"key":1}'

The first dot-segment is the namespace command; the rest is the subcommand (kebab-cased, with the original form as an alias when different).

§3. OpenAPI → tools

Ask the user for: spec source, base endpoint, namespace name, and optional auth headers.

The spec field accepts three forms:

spec: "https://petstore3.swagger.io/api/v3/openapi.json"  // URL — fetched at setup
spec: fs.readFileSync("./openapi.yaml", "utf8")          // YAML text
spec: JSON.stringify(specObject)                          // JSON text