feat: add Executor SDK plugin for cli-to-js

[aidenybai]

Summary

Adds a new package @cli-to-js/plugin-executor that integrates cli-to-js with the Executor SDK (@executor-js/sdk). This lets any CLI tool wrapped by cli-to-js be exposed as invocable tools inside an Executor, alongside MCP, OpenAPI, GraphQL, and other plugin-based tool sources.

Usage

import { createExecutor } from "@executor-js/sdk";
import { cliPlugin } from "@cli-to-js/plugin-executor";

const executor = await createExecutor({
  scope: { name: "my-app" },
  plugins: [cliPlugin()] as const,
});

// Auto-discover a CLI tool by running its --help
await executor.cli.addBinary({ binary: "git", options: { subcommands: true } });

// Or register from pre-parsed help text
await executor.cli.addHelpText({
  binary: "curl",
  helpText: "Usage: curl [options] <url> ...",
  namespace: "curl",
});

// All CLI tools are now in the unified tool catalog
const tools = await executor.tools.list();

// Invoke any CLI subcommand as a tool
const result = await executor.tools.invoke(
  "git.status",
  { short: true },
  { onElicitation: "accept-all" },
);

// Clean up
await executor.close();

What the plugin does

• Registers as an Executor plugin under the "cli" key
• addBinary(config) — runs a binary's --help, parses the output via cli-to-js, and registers every flag/subcommand as an executor tool with JSON Schema inputSchema
• addHelpText(config) — same as above but from a string (no subprocess needed)
• removeBinary(namespace) — unregisters all tools for a namespace
• list() — returns all registered namespace keys
• Tool invocation routes through cli-to-js's CliApi proxy, returning { stdout, stderr, exitCode }
• Cleanup on executor.close() unregisters all tools via Promise.all

Package structure

packages/plugin-cli-to-js/
├── src/
│   ├── index.ts                      # Public re-exports
│   ├── plugin.ts                     # Core plugin (definePlugin + invoker)
│   ├── constants.ts                  # PLUGIN_KEY, SOURCE_PREFIX, ROOT_TOOL_SUFFIX
│   └── utils/
│       └── build-input-schema.ts     # Flags/positionals → JSON Schema
├── tests/
│   ├── build-input-schema.test.ts    # 11 unit tests
│   └── plugin.test.ts               # 12 integration tests via createExecutor
├── package.json
├── tsconfig.json
└── vite.config.ts

Tests

23 tests across 2 test files, all passing:

Test file	Tests	Coverage
build-input-schema.test.ts	11	Schema generation from flags + positionals (including kebab→camel conversion, flag types, descriptions, defaults, positional signatures, required markers)
plugin.test.ts	12	Full integration via createExecutor — plugin registration, addHelpText, addBinary, tool listing, schema inspection, tool invocation with real binaries, ToolNotFoundError, removeBinary, multi-binary isolation