api-to-cli 0.1.2 → 0.1.3

package/README.md

@@ -12,14 +12,17 @@ This means anyone can create a CLI layer for an API, even if the API owner never
 
 ## Current Scope
 - Generator commands:
+  - `doctor`
+  - `init`
   - `validate`
   - `generate`
   - `scaffold`
 - Generated CLI support:
-  - GET endpoints (MVP)
+  - GET, POST, PUT, PATCH, DELETE
   - JSON output by default
   - JSON error envelope
   - Env-var auth injection (`header` or `query`)
+  - Safe guard for state-changing operations (`--yes` required)
 
 ## Install and Run
 
@@ -41,16 +44,29 @@ api-to-cli --help
 Use either `npx api-to-cli` or `api-to-cli` (if globally installed).
 
 ```bash
-# 1) Validate config only
+# 1) Validate from custom config
 npx api-to-cli validate \
   --config ./examples/trello/api-to-cli.config.js
 
-# 2) Generate only the CLI project
+# 2) Diagnose environment and input before generation
+npx api-to-cli doctor --url https://api.example.com
+
+# 3) Bootstrap a config from an API base URL
+npx api-to-cli init \
+  --url https://api.example.com \
+  --output ./api-to-cli.config.js
+
+# 4) Generate from custom config
 npx api-to-cli generate \
   --config ./examples/trello/api-to-cli.config.js \
   --output ./examples/trello/trelloapi-cli
 
-# 3) Generate a full agent bundle (CLI + skill + manifest)
+# 5) Generate from OpenAPI spec (local file or URL)
+npx api-to-cli generate \
+  --spec ./examples/openapi/sample-openapi.yaml \
+  --output ./examples/openapi/sample-openapi-cli
+
+# 6) Generate a full agent bundle (CLI + skill + manifest)
 npx api-to-cli scaffold \
   --config ./examples/trello/api-to-cli.config.js \
   --output ./examples/trello/trelloapi-agent
@@ -103,6 +119,109 @@ flowchart LR
 2. Agent reads `skill/SKILL.md` for operating rules and command examples.
 3. Agent executes the generated CLI and parses JSON stdout/stderr.
 
+## OpenAPI Notes
+- Supported input: OpenAPI 3.x JSON or YAML (`--spec <path-or-url>`)
+- Command names are derived from `operationId` when available, otherwise method + path
+- Path/query parameters are converted into CLI flags
+- For `POST/PUT/PATCH/DELETE`, generated commands require `--yes`
+- If OpenAPI operation has JSON object requestBody, generated command creates typed body flags like `--body-name`
+- Generated commands also support `--body <json>` and `--body-stdin` as fallback modes
+
+## Init From URL
+- Command: `api-to-cli init --url <api-base-url> --output ./api-to-cli.config.js`
+- Behavior:
+  - Tries to discover OpenAPI automatically from common paths (`/openapi.json`, `/swagger.json`, etc.)
+  - If found: writes a populated config derived from the spec
+  - If not found: writes a starter config template you can edit
+- Optional flags:
+  - `--name <cli-name>`
+  - `--version <semver>`
+
+### URL Init Architecture
+
+```mermaid
+flowchart TD
+  U[--url API base] --> C[Build candidate spec URLs]
+  C --> T[Try candidate endpoints]
+  T -->|Spec found| P[Parse OpenAPI]
+  P --> M[Map to api-to-cli config]
+  M --> W1[Write api-to-cli.config.js]
+  T -->|No spec found| S[Create starter config template]
+  S --> W2[Write api-to-cli.config.js]
+  W1 --> N[Run generate/scaffold]
+  W2 --> N
+```
+
+## Doctor Command
+- Command: `api-to-cli doctor [--config <path>] [--spec <path-or-url>] [--url <api-base-url>]`
+- Checks include:
+  - Node runtime compatibility
+  - fetch availability
+  - working directory writability
+  - config/spec validation (when provided)
+  - OpenAPI discovery hints for URL inputs
+- Output is JSON with pass/fail checks and suggested fixes.
+
+## OpenAPI Quickstart
+
+Run with your own spec file:
+
+```bash
+# 1) Validate an OpenAPI spec
+npx api-to-cli validate --spec ./openapi.yaml
+
+# 2) Generate a CLI project from the spec
+npx api-to-cli generate --spec ./openapi.yaml --output ./myapi-cli
+
+# 3) Generate a full agent bundle (CLI + skill + manifest)
+npx api-to-cli scaffold --spec ./openapi.yaml --output ./myapi-agent
+```
+
+Run the generated CLI:
+
+```bash
+cd ./myapi-cli
+npm install
+node ./bin/<generated-cli-name>.js --help
+```
+
+Mutation command examples (POST/PUT/PATCH/DELETE):
+
+```bash
+# Typed body flags from request schema
+node ./bin/<generated-cli-name>.js create-item --body-name "Alice" --yes --pretty
+
+# Raw JSON body fallback
+node ./bin/<generated-cli-name>.js create-item --body '{"name":"Alice"}' --yes --pretty
+
+# JSON via stdin fallback
+echo '{"name":"Alice"}' | node ./bin/<generated-cli-name>.js create-item --body-stdin --yes --pretty
+```
+
+## OpenAPI Architecture
+
+```mermaid
+flowchart TD
+  SPEC[OpenAPI JSON/YAML] --> PARSE[OpenAPI Parser]
+  PARSE --> MAP[Map operations to command config]
+  MAP --> PARAMS[Path/query params to CLI flags]
+  MAP --> BODY[JSON body schema to body flags]
+  BODY --> FLAGS[--body-field flags]
+  BODY --> FALLBACK[--body / --body-stdin fallback]
+  MAP --> SAFETY[Non-GET safety: --yes required]
+  PARAMS --> GEN[CLI Generator]
+  FLAGS --> GEN
+  FALLBACK --> GEN
+  SAFETY --> GEN
+  GEN --> OUT[Generated CLI + Skill + Manifest]
+```
+
+## Sample OpenAPI Spec
+- Included at `examples/openapi/sample-openapi.yaml`
+- Includes GET and mutation operations with JSON request bodies
+- Generated CLI output: `examples/openapi/sample-openapi-cli`
+- Generated agent bundle output: `examples/openapi/sample-openapi-agent`
+
 ## Suggested Usage Flows
 
 ### Flow A: Local Personal Use (No API Owner Needed)
@@ -145,6 +264,9 @@ This runs:
 - `validate:trello`
 - `generate:trello`
 - `scaffold:trello`
+- `validate:openapi`
+- `generate:openapi`
+- `scaffold:openapi`
 
 ## Notes
 - Generated CLIs depend on `commander`.

package/examples/openapi/sample-openapi-agent/README.md

@@ -0,0 +1,12 @@
+# AgentBridge Scaffold Output
+
+## Contents
+- CLI project: ./cli
+- Input source: spec (./examples/openapi/sample-openapi.yaml)
+- Skill file: ./skill/SKILL.md
+- Manifest: ./agentbridge.manifest.json
+
+## Next Steps
+1. cd ./cli
+2. npm install
+3. npm link

package/examples/openapi/sample-openapi-agent/agentbridge.manifest.json

@@ -0,0 +1,85 @@
+{
+  "schemaVersion": "1.0",
+  "generatedBy": "AgentBridge",
+  "generatedAt": "2026-02-20T01:48:45.765Z",
+  "project": {
+    "name": "sample-crm-api",
+    "version": "1.0.0"
+  },
+  "cli": {
+    "projectPath": "./cli",
+    "packageName": "sample-crm-api-cli",
+    "binary": "sample-crm-api",
+    "install": [
+      "npm install",
+      "npm link"
+    ]
+  },
+  "auth": {
+    "envVars": []
+  },
+  "commands": [
+    {
+      "name": "list-contacts",
+      "description": "List contacts",
+      "method": "GET",
+      "path": "/contacts",
+      "params": [
+        {
+          "name": "limit",
+          "required": false,
+          "description": "Max contacts to return"
+        }
+      ]
+    },
+    {
+      "name": "create-contact",
+      "description": "Create contact",
+      "method": "POST",
+      "path": "/contacts",
+      "params": []
+    },
+    {
+      "name": "get-contacts-by-contactid",
+      "description": "Get contact by ID",
+      "method": "GET",
+      "path": "/contacts/{contactId}",
+      "params": [
+        {
+          "name": "contactId",
+          "required": true,
+          "description": "Contact ID"
+        }
+      ]
+    },
+    {
+      "name": "patch-contacts-by-contactid",
+      "description": "Update contact fields",
+      "method": "PATCH",
+      "path": "/contacts/{contactId}",
+      "params": [
+        {
+          "name": "contactId",
+          "required": true,
+          "description": "Contact ID"
+        }
+      ]
+    },
+    {
+      "name": "delete-contacts-by-contactid",
+      "description": "Delete contact",
+      "method": "DELETE",
+      "path": "/contacts/{contactId}",
+      "params": [
+        {
+          "name": "contactId",
+          "required": true,
+          "description": "Contact ID"
+        }
+      ]
+    }
+  ],
+  "agent": {
+    "skillPath": "./skill/SKILL.md"
+  }
+}

package/examples/openapi/sample-openapi-agent/cli/README.md

@@ -0,0 +1,18 @@
+# sample-crm-api CLI
+
+Generated by AgentBridge (api-to-cli).
+
+## Install
+
+```bash
+npm install
+npm link
+```
+
+## Commands
+
+- `sample-crm-api list-contacts` - List contacts
+- `sample-crm-api create-contact` - Create contact
+- `sample-crm-api get-contacts-by-contactid` - Get contact by ID
+- `sample-crm-api patch-contacts-by-contactid` - Update contact fields
+- `sample-crm-api delete-contacts-by-contactid` - Delete contact

package/examples/openapi/sample-openapi-agent/cli/bin/sample-crm-api.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+
+const cmd0 = require('../commands/list-contacts');
+const cmd1 = require('../commands/create-contact');
+const cmd2 = require('../commands/get-contacts-by-contactid');
+const cmd3 = require('../commands/patch-contacts-by-contactid');
+const cmd4 = require('../commands/delete-contacts-by-contactid');
+
+const program = new Command();
+
+program
+  .name('sample-crm-api')
+  .description('sample-crm-api CLI generated by AgentBridge')
+  .version('1.0.0');
+
+program
+  .command('list-contacts')
+  .description('List contacts')
+  .option('--limit <value>', 'Max contacts to return')
+  .option('--pretty', 'Pretty-print JSON')
+  .action((options) => cmd0.run(options));
+
+program
+  .command('create-contact')
+  .description('Create contact')
+  .option('--yes', 'Confirm non-GET operation')
+  .option('--body <json>', 'Raw JSON request body')
+  .option('--body-stdin', 'Read JSON body from stdin')
+  .option('--body-name <value>', 'Contact full name (required)')
+  .option('--body-email <value>', 'Contact email (optional)')
+  .option('--body-subscribed <value>', 'Newsletter subscription status (optional)')
+  .option('--pretty', 'Pretty-print JSON')
+  .action((options) => cmd1.run(options));
+
+program
+  .command('get-contacts-by-contactid')
+  .description('Get contact by ID')
+  .option('--contact-id <value>', 'Contact ID')
+  .option('--pretty', 'Pretty-print JSON')
+  .action((options) => cmd2.run(options));
+
+program
+  .command('patch-contacts-by-contactid')
+  .description('Update contact fields')
+  .option('--contact-id <value>', 'Contact ID')
+  .option('--yes', 'Confirm non-GET operation')
+  .option('--body <json>', 'Raw JSON request body')
+  .option('--body-stdin', 'Read JSON body from stdin')
+  .option('--body-name <value>', 'Updated full name (optional)')
+  .option('--body-email <value>', 'Updated email (optional)')
+  .option('--pretty', 'Pretty-print JSON')
+  .action((options) => cmd3.run(options));
+
+program
+  .command('delete-contacts-by-contactid')
+  .description('Delete contact')
+  .option('--contact-id <value>', 'Contact ID')
+  .option('--yes', 'Confirm non-GET operation')
+  .option('--pretty', 'Pretty-print JSON')
+  .action((options) => cmd4.run(options));
+
+program.parse(process.argv);

package/examples/openapi/sample-openapi-agent/cli/commands/create-contact.js

@@ -0,0 +1,59 @@
+const { request } = require('../lib/client');
+const output = require('../lib/output');
+
+const command = {
+  "name": "create-contact",
+  "description": "Create contact",
+  "method": "POST",
+  "path": "/contacts",
+  "params": {},
+  "requestBody": {
+    "required": true,
+    "properties": {
+      "name": {
+        "type": "string",
+        "required": true,
+        "description": "Contact full name"
+      },
+      "email": {
+        "type": "string",
+        "required": false,
+        "description": "Contact email"
+      },
+      "subscribed": {
+        "type": "boolean",
+        "required": false,
+        "description": "Newsletter subscription status"
+      }
+    }
+  }
+};
+
+async function createContact(options) {
+  try {
+    if (command.method !== 'GET' && !options.yes) {
+      throw new Error('This operation changes state. Re-run with --yes to confirm.');
+    }
+
+    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: createContact,
+  command
+};

package/examples/openapi/sample-openapi-agent/cli/commands/delete-contacts-by-contactid.js

@@ -0,0 +1,45 @@
+const { request } = require('../lib/client');
+const output = require('../lib/output');
+
+const command = {
+  "name": "delete-contacts-by-contactid",
+  "description": "Delete contact",
+  "method": "DELETE",
+  "path": "/contacts/{contactId}",
+  "params": {
+    "contactId": {
+      "type": "string",
+      "required": true,
+      "description": "Contact ID"
+    }
+  }
+};
+
+async function deleteContactsByContactid(options) {
+  try {
+    if (command.method !== 'GET' && !options.yes) {
+      throw new Error('This operation changes state. Re-run with --yes to confirm.');
+    }
+
+    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: deleteContactsByContactid,
+  command
+};

package/examples/openapi/sample-openapi-agent/cli/commands/get-contacts-by-contactid.js

@@ -0,0 +1,45 @@
+const { request } = require('../lib/client');
+const output = require('../lib/output');
+
+const command = {
+  "name": "get-contacts-by-contactid",
+  "description": "Get contact by ID",
+  "method": "GET",
+  "path": "/contacts/{contactId}",
+  "params": {
+    "contactId": {
+      "type": "string",
+      "required": true,
+      "description": "Contact ID"
+    }
+  }
+};
+
+async function getContactsByContactid(options) {
+  try {
+    if (command.method !== 'GET' && !options.yes) {
+      throw new Error('This operation changes state. Re-run with --yes to confirm.');
+    }
+
+    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: getContactsByContactid,
+  command
+};

package/examples/openapi/sample-openapi-agent/cli/commands/list-contacts.js

@@ -0,0 +1,45 @@
+const { request } = require('../lib/client');
+const output = require('../lib/output');
+
+const command = {
+  "name": "list-contacts",
+  "description": "List contacts",
+  "method": "GET",
+  "path": "/contacts",
+  "params": {
+    "limit": {
+      "type": "number",
+      "required": false,
+      "description": "Max contacts to return"
+    }
+  }
+};
+
+async function listContacts(options) {
+  try {
+    if (command.method !== 'GET' && !options.yes) {
+      throw new Error('This operation changes state. Re-run with --yes to confirm.');
+    }
+
+    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: listContacts,
+  command
+};

package/examples/openapi/sample-openapi-agent/cli/commands/patch-contacts-by-contactid.js

@@ -0,0 +1,60 @@
+const { request } = require('../lib/client');
+const output = require('../lib/output');
+
+const command = {
+  "name": "patch-contacts-by-contactid",
+  "description": "Update contact fields",
+  "method": "PATCH",
+  "path": "/contacts/{contactId}",
+  "params": {
+    "contactId": {
+      "type": "string",
+      "required": true,
+      "description": "Contact ID"
+    }
+  },
+  "requestBody": {
+    "required": true,
+    "properties": {
+      "name": {
+        "type": "string",
+        "required": false,
+        "description": "Updated full name"
+      },
+      "email": {
+        "type": "string",
+        "required": false,
+        "description": "Updated email"
+      }
+    }
+  }
+};
+
+async function patchContactsByContactid(options) {
+  try {
+    if (command.method !== 'GET' && !options.yes) {
+      throw new Error('This operation changes state. Re-run with --yes to confirm.');
+    }
+
+    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: patchContactsByContactid,
+  command
+};