api-to-cli 0.1.1 → 0.1.3

package/src/lib/openapi-to-config.js

@@ -0,0 +1,314 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { validateConfig } = require('./load-config');
+const { toKebab } = require('./config-utils');
+
+function isUrl(value) {
+  return /^https?:\/\//i.test(String(value));
+}
+
+function readLocalFile(specPath) {
+  const resolved = path.resolve(process.cwd(), specPath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Spec file not found: ${resolved}`);
+  }
+
+  return fs.readFileSync(resolved, 'utf8');
+}
+
+async function readSpecText(specInput) {
+  if (isUrl(specInput)) {
+    const response = await fetch(String(specInput));
+    if (!response.ok) {
+      throw new Error(`Unable to fetch spec: HTTP ${response.status}`);
+    }
+
+    return response.text();
+  }
+
+  return readLocalFile(String(specInput));
+}
+
+function parseSpec(text) {
+  try {
+    return JSON.parse(text);
+  } catch (_error) {
+    return yaml.load(text);
+  }
+}
+
+function resolveParameter(spec, parameter) {
+  if (!parameter || typeof parameter !== 'object') {
+    return null;
+  }
+
+  if (!parameter.$ref) {
+    return parameter;
+  }
+
+  const match = String(parameter.$ref).match(/^#\/components\/parameters\/([^/]+)$/);
+  if (!match) {
+    throw new Error(`Unsupported parameter $ref: ${parameter.$ref}`);
+  }
+
+  const key = match[1];
+  const resolved = spec.components && spec.components.parameters && spec.components.parameters[key];
+
+  if (!resolved) {
+    throw new Error(`Unable to resolve parameter ref: ${parameter.$ref}`);
+  }
+
+  return resolved;
+}
+
+function resolveSchema(spec, schema) {
+  if (!schema || typeof schema !== 'object') {
+    return null;
+  }
+
+  if (!schema.$ref) {
+    return schema;
+  }
+
+  const match = String(schema.$ref).match(/^#\/components\/schemas\/([^/]+)$/);
+  if (!match) {
+    return null;
+  }
+
+  const key = match[1];
+  return spec.components && spec.components.schemas && spec.components.schemas[key];
+}
+
+function resolveRequestBody(spec, requestBody) {
+  if (!requestBody || typeof requestBody !== 'object') {
+    return null;
+  }
+
+  if (!requestBody.$ref) {
+    return requestBody;
+  }
+
+  const match = String(requestBody.$ref).match(/^#\/components\/requestBodies\/([^/]+)$/);
+  if (!match) {
+    throw new Error(`Unsupported requestBody $ref: ${requestBody.$ref}`);
+  }
+
+  const key = match[1];
+  const resolved = spec.components && spec.components.requestBodies && spec.components.requestBodies[key];
+
+  if (!resolved) {
+    throw new Error(`Unable to resolve requestBody ref: ${requestBody.$ref}`);
+  }
+
+  return resolved;
+}
+
+function dedupeParameters(parameters) {
+  const map = new Map();
+
+  parameters.forEach((parameter) => {
+    if (!parameter || !parameter.name) {
+      return;
+    }
+
+    const key = `${parameter.in}:${parameter.name}`;
+    map.set(key, parameter);
+  });
+
+  return [...map.values()];
+}
+
+function inferTypeFromSchema(schema) {
+  const resolved = schema && typeof schema === 'object' ? schema : {};
+  if (resolved.type === 'integer' || resolved.type === 'number') {
+    return 'number';
+  }
+
+  if (resolved.type === 'boolean') {
+    return 'boolean';
+  }
+
+  return 'string';
+}
+
+function inferType(parameter) {
+  return inferTypeFromSchema(parameter.schema || {});
+}
+
+function buildCommandName(method, routePath, operation) {
+  if (operation.operationId && String(operation.operationId).trim()) {
+    return toKebab(String(operation.operationId).trim());
+  }
+
+  const parts = routePath
+    .split('/')
+    .filter(Boolean)
+    .map((part) => {
+      if (part.startsWith('{') && part.endsWith('}')) {
+        return `by-${part.slice(1, -1)}`;
+      }
+
+      return part;
+    });
+
+  return [method.toLowerCase(), ...parts]
+    .join('-')
+    .replace(/[^a-zA-Z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+}
+
+function extractRequestBody(spec, requestBody) {
+  const resolved = resolveRequestBody(spec, requestBody);
+  if (!resolved) {
+    return undefined;
+  }
+
+  const content = resolved.content || {};
+  const jsonContent = content['application/json'];
+  if (!jsonContent || !jsonContent.schema) {
+    return undefined;
+  }
+
+  const schema = resolveSchema(spec, jsonContent.schema) || jsonContent.schema;
+  const request = {
+    required: Boolean(resolved.required)
+  };
+
+  if (schema.type === 'object' && schema.properties && typeof schema.properties === 'object') {
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const properties = {};
+
+    Object.entries(schema.properties).forEach(([name, propSchema]) => {
+      const resolvedProp = resolveSchema(spec, propSchema) || propSchema;
+      properties[name] = {
+        type: inferTypeFromSchema(resolvedProp),
+        required: required.has(name),
+        description: (resolvedProp && resolvedProp.description) || `${name} field`
+      };
+    });
+
+    request.properties = properties;
+  }
+
+  return request;
+}
+
+function operationToCommand(spec, method, routePath, operation) {
+  const combinedParameters = dedupeParameters([
+    ...((operation.__pathParameters || []).map((parameter) => resolveParameter(spec, parameter))),
+    ...((operation.parameters || []).map((parameter) => resolveParameter(spec, parameter)))
+  ]);
+
+  const params = {};
+
+  combinedParameters.forEach((parameter) => {
+    if (!parameter || !parameter.name) {
+      return;
+    }
+
+    if (parameter.in !== 'path' && parameter.in !== 'query') {
+      return;
+    }
+
+    params[parameter.name] = {
+      type: inferType(parameter),
+      required: parameter.in === 'path' ? true : Boolean(parameter.required),
+      description: parameter.description || `${parameter.name} (${parameter.in})`
+    };
+  });
+
+  return {
+    name: buildCommandName(method, routePath, operation),
+    description: operation.summary || operation.description || `${method.toUpperCase()} ${routePath}`,
+    method: method.toUpperCase(),
+    path: routePath,
+    params,
+    requestBody: extractRequestBody(spec, operation.requestBody)
+  };
+}
+
+function normalizeName(rawName) {
+  return String(rawName)
+    .trim()
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+}
+
+function toConfigFromSpec(spec, overrides = {}) {
+  if (!spec || typeof spec !== 'object') {
+    throw new Error('Invalid OpenAPI: spec must be an object');
+  }
+
+  const title = (spec.info && spec.info.title) || overrides.name;
+  const version = overrides.version || (spec.info && spec.info.version) || '1.0.0';
+  const server = (spec.servers && spec.servers[0] && spec.servers[0].url) || '';
+
+  if (!title) {
+    throw new Error('Missing CLI name: provide --name or include info.title in spec');
+  }
+
+  if (!server || !/^https?:\/\//.test(server)) {
+    throw new Error('OpenAPI spec must include servers[0].url with http(s) base URL');
+  }
+
+  const paths = spec.paths && typeof spec.paths === 'object' ? spec.paths : {};
+  const commands = [];
+  const methods = ['get', 'post', 'put', 'patch', 'delete'];
+
+  Object.entries(paths).forEach(([routePath, pathItem]) => {
+    if (!pathItem || typeof pathItem !== 'object') {
+      return;
+    }
+
+    methods.forEach((method) => {
+      if (!pathItem[method] || typeof pathItem[method] !== 'object') {
+        return;
+      }
+
+      const operation = {
+        ...pathItem[method],
+        __pathParameters: Array.isArray(pathItem.parameters) ? pathItem.parameters : []
+      };
+
+      commands.push(operationToCommand(spec, method, routePath, operation));
+    });
+  });
+
+  if (commands.length === 0) {
+    throw new Error('No supported operations found in OpenAPI spec');
+  }
+
+  const config = {
+    name: normalizeName(title),
+    version: String(version),
+    apiBase: String(server).replace(/\/$/, ''),
+    commands
+  };
+
+  validateConfig(config);
+
+  return config;
+}
+
+async function loadConfigFromOpenApi({ specInput, name, version }) {
+  if (!specInput) {
+    throw new Error('Missing required flag: --spec <path-or-url>');
+  }
+
+  const text = await readSpecText(specInput);
+  const spec = parseSpec(text);
+
+  if (!spec || typeof spec !== 'object') {
+    throw new Error('Failed to parse OpenAPI spec');
+  }
+
+  return toConfigFromSpec(spec, { name, version });
+}
+
+module.exports = {
+  loadConfigFromOpenApi
+};

package/src/lib/resolve-config-input.js

@@ -0,0 +1,50 @@
+const path = require('path');
+const { loadConfig } = require('./load-config');
+const { loadConfigFromOpenApi } = require('./openapi-to-config');
+
+function hasFlag(flags, key) {
+  return Object.prototype.hasOwnProperty.call(flags, key);
+}
+
+async function resolveConfigInput(flags) {
+  const hasConfig = hasFlag(flags, 'config');
+  const hasSpec = hasFlag(flags, 'spec');
+
+  if (!hasConfig && !hasSpec) {
+    throw new Error('Provide one input source: --config <path> or --spec <path-or-url>');
+  }
+
+  if (hasConfig && hasSpec) {
+    throw new Error('Use either --config or --spec, not both');
+  }
+
+  if (hasConfig) {
+    const configPath = path.resolve(process.cwd(), String(flags.config));
+    const config = loadConfig(configPath);
+    return {
+      config,
+      source: {
+        type: 'config',
+        value: configPath
+      }
+    };
+  }
+
+  const config = await loadConfigFromOpenApi({
+    specInput: String(flags.spec),
+    name: flags.name ? String(flags.name) : undefined,
+    version: flags.version ? String(flags.version) : undefined
+  });
+
+  return {
+    config,
+    source: {
+      type: 'spec',
+      value: String(flags.spec)
+    }
+  };
+}
+
+module.exports = {
+  resolveConfigInput
+};

package/PROJECT_BRIEF.md

@@ -1,65 +0,0 @@
-# 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/SPEC.md

@@ -1,99 +0,0 @@
-# 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.