api-to-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RandyVentures
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROJECT_BRIEF.md

@@ -0,0 +1,65 @@
+# API-to-CLI Project Brief
+
+## Working Name
+- Recommended: `AgentBridge`
+- NPM package (generator): `api-to-cli`
+- Why this split: product name can be brandable, while npm name stays literal and searchable.
+
+Other viable names:
+- `APIBridge`
+- `CLIForge`
+- `Toolwire`
+
+## Problem
+Most APIs are not directly usable by AI agents. We want a generator that turns a REST API definition into:
+1. an AI-agent-friendly CLI (JSON-first output), and
+2. an MCP server exposing equivalent tools.
+
+## What We Are Building (MVP)
+- Input:
+  - `api-to-cli.config.js` custom config (first)
+  - OpenAPI support later
+- Output:
+  - Installable Node CLI
+  - MCP server
+- Core behavior:
+  - JSON output by default
+  - Consistent JSON error envelope
+  - Shared auth handling (API key + bearer first)
+  - Safe-by-default confirmations for destructive methods
+
+## Explicit Non-Goals (MVP)
+- Full OAuth/device flow in v1
+- Every OpenAPI edge case in v1
+- Multi-language generators in v1
+
+## Demo API Choice (Free + Popular, No First-Party CLI)
+Recommended demo target: **Trello REST API**
+- Popular real product used by millions
+- Free plan available
+- Official REST API docs and auth flow
+- No first-party Trello CLI from Atlassian (there are community CLIs, which is fine and reinforces the need)
+
+Key references:
+- API reference landing: https://developer.atlassian.com/cloud/trello/rest/
+- API introduction (first calls, key + token): https://developer.atlassian.com/cloud/trello/guides/rest-api/api-introduction/
+- Authorization details: https://developer.atlassian.com/cloud/trello/guides/rest-api/authorization/
+- Pricing (Free plan): https://trello.com/pricing
+
+## MVP Command Set for Trello Demo
+- `trelloapi me`
+- `trelloapi list-boards`
+- `trelloapi list-cards --board-id <id>`
+- `trelloapi create-card --list-id <id> --name <title> --yes`
+
+## Build Sequence
+1. Generator from custom config -> CLI output (GET-only)
+2. Add POST/PUT/PATCH/DELETE with `--yes` guard
+3. Generate MCP server from same config
+4. Add OpenAPI parsing layer
+
+## Immediate Next Step (Before Coding)
+Finalize:
+1. Product name (`AgentBridge` vs alternatives)
+2. Package names (`api-to-cli`, `@randyventures/api-to-cli`, or other)
+3. Trello as first official example API

package/README.md

@@ -0,0 +1,130 @@
+# AgentBridge (`api-to-cli`)
+
+Generate AI-agent-friendly CLIs from API configs.
+
+## What It Does
+AgentBridge takes an API config and generates artifacts that an AI agent can use immediately:
+- A JSON-first CLI project
+- A `SKILL.md` file with usage instructions
+- A machine-readable `agentbridge.manifest.json`
+
+This means anyone can create a CLI layer for an API, even if the API owner never ships one.
+
+## Current Scope
+- Generator commands:
+  - `validate`
+  - `generate`
+  - `scaffold`
+- Generated CLI support:
+  - GET endpoints (MVP)
+  - JSON output by default
+  - JSON error envelope
+  - Env-var auth injection (`header` or `query`)
+
+## Project Setup
+Clone this repository to any local folder and run commands from the repo root.
+
+## Core Commands
+
+```bash
+# 1) Validate config only
+node ./bin/api-to-cli.js validate \
+  --config ./examples/trello/api-to-cli.config.js
+
+# 2) Generate only the CLI project
+node ./bin/api-to-cli.js generate \
+  --config ./examples/trello/api-to-cli.config.js \
+  --output ./examples/trello/trelloapi-cli
+
+# 3) Generate a full agent bundle (CLI + skill + manifest)
+node ./bin/api-to-cli.js scaffold \
+  --config ./examples/trello/api-to-cli.config.js \
+  --output ./examples/trello/trelloapi-agent
+```
+
+## Scaffold Output Layout
+
+```text
+<output>/
+  README.md
+  agentbridge.manifest.json
+  cli/
+    package.json
+    bin/<name>.js
+    commands/*.js
+    lib/client.js
+    lib/output.js
+    README.md
+  skill/
+    SKILL.md
+```
+
+## Architecture
+
+```mermaid
+flowchart LR
+  C[api-to-cli.config.js] --> V[validate]
+  C --> G[generate]
+  C --> S[scaffold]
+  G --> CLI[Generated CLI Project]
+  S --> CLI2[cli/]
+  S --> SK[skill/SKILL.md]
+  S --> MF[agentbridge.manifest.json]
+  MF --> AG[AI Agent]
+  SK --> AG
+  AG --> RUN[Run generated CLI commands]
+  RUN --> API[Target REST API]
+```
+
+## How AI Agents Use This
+1. Agent reads `agentbridge.manifest.json` to discover commands, params, auth env vars, and install steps.
+2. Agent reads `skill/SKILL.md` for operating rules and command examples.
+3. Agent executes the generated CLI and parses JSON stdout/stderr.
+
+## Suggested Usage Flows
+
+### Flow A: Local Personal Use (No API Owner Needed)
+1. Write `api-to-cli.config.js` for the target API.
+2. Run `scaffold`.
+3. Set required auth env vars.
+4. Let your agent use the generated CLI locally.
+
+### Flow B: Team/Internal Use
+1. Run `scaffold`.
+2. Commit generated output to an internal repo.
+3. Publish generated CLI to private npm registry (optional).
+4. Point team agents to the shared skill + manifest.
+
+### Flow C: Public Distribution
+1. Generate CLI from API config.
+2. Validate behavior, docs, and API ToS compliance.
+3. Publish generated CLI package publicly.
+4. Publish skill + manifest so agents can onboard automatically.
+
+## Security Model
+- Credentials are read from environment variables only.
+- Generated CLIs do not persist credentials.
+- Generated errors do not include auth headers or full URLs.
+- Do not pass API keys/tokens as CLI flags.
+
+## Example Config (Trello)
+See `examples/trello/api-to-cli.config.js` for:
+- query-based auth (`TRELLO_KEY`, `TRELLO_TOKEN`)
+- path parameter endpoints
+- generated command mapping
+
+## Smoke Test
+
+```bash
+npm run test:smoke
+```
+
+This runs:
+- `validate:trello`
+- `generate:trello`
+- `scaffold:trello`
+
+## Notes
+- Generated CLIs depend on `commander`.
+- The generator currently targets CommonJS + Node runtime with `fetch` support.
+- Planned next phases include MCP generation and OpenAPI input support.

package/SPEC.md

@@ -0,0 +1,99 @@
+# AgentBridge MVP Spec
+
+## Location
+- Project folder: repository root (where this project is cloned)
+- This project is standalone and not nested inside another repo
+
+## Product Identity
+- Product name: `AgentBridge`
+- Generator package name: `api-to-cli`
+
+## Goal
+Given a config file describing API endpoints, generate:
+1. a JSON-first CLI, and
+2. an MCP server exposing matching tools.
+
+## Demo API (First Example)
+- Trello REST API
+- Why: popular, free tier, official docs, no first-party Trello CLI from Atlassian
+
+## MVP Scope (Current)
+- Input:
+  - `api-to-cli.config.js`
+- Generator commands:
+  - `validate`
+  - `generate`
+- Output:
+  - generated CLI project
+- Endpoint support:
+  - GET only
+- Auth support:
+  - env-var credentials injected into header or query
+
+## CLI Behavior Requirements
+- Every command prints valid JSON to stdout on success.
+- Every failure prints JSON in this shape:
+```json
+{
+  "error": true,
+  "code": "REQUEST_FAILED",
+  "message": "...",
+  "details": {}
+}
+```
+- Exit code:
+  - `0` on success
+  - non-zero on error
+
+## Security Requirements
+- Credentials must come from environment variables only.
+- Generated code must not write credentials to files.
+- Error output must not include auth headers, tokens, or full request URLs.
+
+## Generated Project Structure (MVP)
+```text
+<name>-cli/
+  package.json
+  bin/<name>
+  commands/*.js
+  lib/client.js
+  lib/output.js
+```
+
+## Config Shape (MVP)
+```js
+module.exports = {
+  name: "trelloapi",
+  version: "1.0.0",
+  apiBase: "https://api.trello.com/1",
+  auth: {
+    credentials: [
+      { envVar: "TRELLO_KEY", in: "query", name: "key" },
+      { envVar: "TRELLO_TOKEN", in: "query", name: "token" }
+    ]
+  },
+  commands: [
+    {
+      name: "get-board",
+      description: "Get a board by ID",
+      method: "GET",
+      path: "/boards/{boardId}",
+      params: {
+        boardId: { type: "string", required: true }
+      }
+    }
+  ]
+};
+```
+
+## Out of Scope for MVP
+- OpenAPI parsing
+- MCP generation
+- POST/PUT/PATCH/DELETE
+- confirmation prompts (`--yes`)
+- OAuth flow
+
+## Success Criteria
+- `api-to-cli validate --config <file>` validates and returns summary JSON.
+- `api-to-cli generate --config <file> --output <dir>` creates runnable CLI.
+- Generated CLI executes GET commands and emits valid JSON success/error output.

package/bin/api-to-cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { run } = require('../src/index');
+
+run(process.argv.slice(2));

package/examples/trello/api-to-cli.config.js

@@ -0,0 +1,60 @@
+module.exports = {
+  name: 'trelloapi',
+  version: '1.0.0',
+  apiBase: 'https://api.trello.com/1',
+  auth: {
+    credentials: [
+      {
+        envVar: 'TRELLO_KEY',
+        in: 'query',
+        name: 'key'
+      },
+      {
+        envVar: 'TRELLO_TOKEN',
+        in: 'query',
+        name: 'token'
+      }
+    ]
+  },
+  commands: [
+    {
+      name: 'get-board',
+      description: 'Get a board by ID',
+      method: 'GET',
+      path: '/boards/{boardId}',
+      params: {
+        boardId: {
+          type: 'string',
+          required: true,
+          description: 'Trello board ID'
+        }
+      }
+    },
+    {
+      name: 'list-board-lists',
+      description: 'List lists on a board',
+      method: 'GET',
+      path: '/boards/{boardId}/lists',
+      params: {
+        boardId: {
+          type: 'string',
+          required: true,
+          description: 'Trello board ID'
+        }
+      }
+    },
+    {
+      name: 'list-list-cards',
+      description: 'List cards in a list',
+      method: 'GET',
+      path: '/lists/{listId}/cards',
+      params: {
+        listId: {
+          type: 'string',
+          required: true,
+          description: 'Trello list ID'
+        }
+      }
+    }
+  ]
+};

package/examples/trello/trelloapi-agent/README.md

@@ -0,0 +1,11 @@
+# AgentBridge Scaffold Output
+
+## Contents
+- CLI project: ./cli
+- Skill file: ./skill/SKILL.md
+- Manifest: ./agentbridge.manifest.json
+
+## Next Steps
+1. cd ./cli
+2. npm install
+3. npm link

package/examples/trello/trelloapi-agent/agentbridge.manifest.json

@@ -0,0 +1,68 @@
+{
+  "schemaVersion": "1.0",
+  "generatedBy": "AgentBridge",
+  "generatedAt": "2026-02-20T00:42:33.467Z",
+  "project": {
+    "name": "trelloapi",
+    "version": "1.0.0"
+  },
+  "cli": {
+    "projectPath": "./cli",
+    "packageName": "trelloapi-cli",
+    "binary": "trelloapi",
+    "install": [
+      "npm install",
+      "npm link"
+    ]
+  },
+  "auth": {
+    "envVars": [
+      "TRELLO_KEY",
+      "TRELLO_TOKEN"
+    ]
+  },
+  "commands": [
+    {
+      "name": "get-board",
+      "description": "Get a board by ID",
+      "method": "GET",
+      "path": "/boards/{boardId}",
+      "params": [
+        {
+          "name": "boardId",
+          "required": true,
+          "description": "Trello board ID"
+        }
+      ]
+    },
+    {
+      "name": "list-board-lists",
+      "description": "List lists on a board",
+      "method": "GET",
+      "path": "/boards/{boardId}/lists",
+      "params": [
+        {
+          "name": "boardId",
+          "required": true,
+          "description": "Trello board ID"
+        }
+      ]
+    },
+    {
+      "name": "list-list-cards",
+      "description": "List cards in a list",
+      "method": "GET",
+      "path": "/lists/{listId}/cards",
+      "params": [
+        {
+          "name": "listId",
+          "required": true,
+          "description": "Trello list ID"
+        }
+      ]
+    }
+  ],
+  "agent": {
+    "skillPath": "./skill/SKILL.md"
+  }
+}

package/examples/trello/trelloapi-agent/cli/README.md

@@ -0,0 +1,25 @@
+# trelloapi CLI
+
+Generated by AgentBridge (api-to-cli).
+
+## Install
+
+```bash
+npm install
+npm link
+```
+
+## Auth
+
+Set required environment variables before running commands:
+
+- `TRELLO_KEY`
+- `TRELLO_TOKEN`
+
+Do not pass secrets as command flags.
+
+## Commands
+
+- `trelloapi get-board` - Get a board by ID
+- `trelloapi list-board-lists` - List lists on a board
+- `trelloapi list-list-cards` - List cards in a list

package/examples/trello/trelloapi-agent/cli/bin/trelloapi.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+
+const cmd0 = require('../commands/get-board');
+const cmd1 = require('../commands/list-board-lists');
+const cmd2 = require('../commands/list-list-cards');
+
+const program = new Command();
+
+program
+  .name('trelloapi')
+  .description('trelloapi CLI generated by AgentBridge')
+  .version('1.0.0');
+
+program
+  .command('get-board')
+  .description('Get a board by ID')
+  .option('--board-id <value>', 'Trello board ID')
+  .option('--pretty', 'Pretty-print JSON')
+  .action((options) => cmd0.run(options));
+
+program
+  .command('list-board-lists')
+  .description('List lists on a board')
+  .option('--board-id <value>', 'Trello board ID')
+  .option('--pretty', 'Pretty-print JSON')
+  .action((options) => cmd1.run(options));
+
+program
+  .command('list-list-cards')
+  .description('List cards in a list')
+  .option('--list-id <value>', 'Trello list ID')
+  .option('--pretty', 'Pretty-print JSON')
+  .action((options) => cmd2.run(options));
+
+program.parse(process.argv);

package/examples/trello/trelloapi-agent/cli/commands/get-board.js

@@ -0,0 +1,41 @@
+const { request } = require('../lib/client');
+const output = require('../lib/output');
+
+const command = {
+  "name": "get-board",
+  "description": "Get a board by ID",
+  "method": "GET",
+  "path": "/boards/{boardId}",
+  "params": {
+    "boardId": {
+      "type": "string",
+      "required": true,
+      "description": "Trello board ID"
+    }
+  }
+};
+
+async function getBoard(options) {
+  try {
+    const data = await request(command, options);
+    output.json(data, Boolean(options.pretty));
+  } catch (error) {
+    output.error(
+      {
+        code: error.statusCode ? 'HTTP_ERROR' : 'REQUEST_FAILED',
+        message: error.message,
+        details: {
+          statusCode: error.statusCode || null,
+          command: command.name
+        }
+      },
+      Boolean(options.pretty)
+    );
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  run: getBoard,
+  command
+};

package/examples/trello/trelloapi-agent/cli/commands/list-board-lists.js

@@ -0,0 +1,41 @@
+const { request } = require('../lib/client');
+const output = require('../lib/output');
+
+const command = {
+  "name": "list-board-lists",
+  "description": "List lists on a board",
+  "method": "GET",
+  "path": "/boards/{boardId}/lists",
+  "params": {
+    "boardId": {
+      "type": "string",
+      "required": true,
+      "description": "Trello board ID"
+    }
+  }
+};
+
+async function listBoardLists(options) {
+  try {
+    const data = await request(command, options);
+    output.json(data, Boolean(options.pretty));
+  } catch (error) {
+    output.error(
+      {
+        code: error.statusCode ? 'HTTP_ERROR' : 'REQUEST_FAILED',
+        message: error.message,
+        details: {
+          statusCode: error.statusCode || null,
+          command: command.name
+        }
+      },
+      Boolean(options.pretty)
+    );
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  run: listBoardLists,
+  command
+};

package/examples/trello/trelloapi-agent/cli/commands/list-list-cards.js

@@ -0,0 +1,41 @@
+const { request } = require('../lib/client');
+const output = require('../lib/output');
+
+const command = {
+  "name": "list-list-cards",
+  "description": "List cards in a list",
+  "method": "GET",
+  "path": "/lists/{listId}/cards",
+  "params": {
+    "listId": {
+      "type": "string",
+      "required": true,
+      "description": "Trello list ID"
+    }
+  }
+};
+
+async function listListCards(options) {
+  try {
+    const data = await request(command, options);
+    output.json(data, Boolean(options.pretty));
+  } catch (error) {
+    output.error(
+      {
+        code: error.statusCode ? 'HTTP_ERROR' : 'REQUEST_FAILED',
+        message: error.message,
+        details: {
+          statusCode: error.statusCode || null,
+          command: command.name
+        }
+      },
+      Boolean(options.pretty)
+    );
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  run: listListCards,
+  command
+};