api-to-cli 0.1.1

package/src/commands/validate.js

@@ -0,0 +1,30 @@
+const path = require('path');
+const { loadConfig } = require('../lib/load-config');
+
+async function validate(flags) {
+  if (!flags.config) {
+    throw new Error('Missing required flag: --config <path>');
+  }
+
+  const configPath = path.resolve(process.cwd(), String(flags.config));
+  const config = loadConfig(configPath);
+
+  console.log(
+    JSON.stringify({
+      ok: true,
+      command: 'validate',
+      configPath,
+      summary: {
+        name: config.name,
+        version: config.version,
+        apiBase: config.apiBase,
+        commandCount: config.commands.length,
+        hasAuth: Boolean(config.auth && config.auth.credentials && config.auth.credentials.length)
+      }
+    })
+  );
+}
+
+module.exports = {
+  validate
+};

package/src/index.js

@@ -0,0 +1,92 @@
+const { generate } = require('./commands/generate');
+const { validate } = require('./commands/validate');
+const { scaffold } = require('./commands/scaffold');
+
+function printUsage() {
+  console.error(
+    [
+      'Usage:',
+      '  api-to-cli generate --config <path> --output <dir>',
+      '  api-to-cli validate --config <path>',
+      '  api-to-cli scaffold --config <path> --output <dir> [--with-skill] [--with-manifest]',
+      '',
+      'Commands:',
+      '  generate   Generate a CLI from config',
+      '  validate   Validate config only',
+      '  scaffold   Generate CLI + optional skill/manifest bundle'
+    ].join('\n')
+  );
+}
+
+function parseFlags(args) {
+  const flags = {};
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (!arg.startsWith('--')) {
+      continue;
+    }
+
+    const key = arg.slice(2);
+    const value = args[i + 1];
+
+    if (!value || value.startsWith('--')) {
+      flags[key] = true;
+      continue;
+    }
+
+    flags[key] = value;
+    i += 1;
+  }
+
+  return flags;
+}
+
+async function run(argv) {
+  const [command, ...rest] = argv;
+
+  if (!command || command === '--help' || command === '-h') {
+    printUsage();
+    process.exit(0);
+  }
+
+  try {
+    const flags = parseFlags(rest);
+
+    if (command === 'generate') {
+      await generate(flags);
+      return;
+    }
+
+    if (command === 'validate') {
+      await validate(flags);
+      return;
+    }
+
+    if (command === 'scaffold') {
+      await scaffold(flags);
+      return;
+    }
+
+    throw new Error(`Unknown command: ${command}`);
+  } catch (error) {
+    console.error(
+      JSON.stringify(
+        {
+          error: true,
+          code: 'GENERATOR_FAILED',
+          message: error.message,
+          details: {}
+        },
+        null,
+        2
+      )
+    );
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  run
+};

package/src/lib/config-utils.js

@@ -0,0 +1,21 @@
+function toKebab(input) {
+  return String(input)
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function getAuthEnvVars(config) {
+  const authVars = (config.auth && Array.isArray(config.auth.credentials))
+    ? config.auth.credentials.map((credential) => credential.envVar)
+    : [];
+
+  return [...new Set(authVars)];
+}
+
+module.exports = {
+  toKebab,
+  getAuthEnvVars
+};

package/src/lib/generate-cli.js

@@ -0,0 +1,295 @@
+const fs = require('fs');
+const path = require('path');
+const { toKebab } = require('./config-utils');
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function commandToMethodName(commandName) {
+  return String(commandName)
+    .split(/[^a-zA-Z0-9]/)
+    .filter(Boolean)
+    .map((part, index) => {
+      const lower = part.toLowerCase();
+      return index === 0 ? lower : lower[0].toUpperCase() + lower.slice(1);
+    })
+    .join('');
+}
+
+function renderPackageJson(config) {
+  const packageJson = {
+    name: `${toKebab(config.name)}-cli`,
+    version: config.version,
+    description: `${config.name} CLI generated by AgentBridge`,
+    license: 'MIT',
+    type: 'commonjs',
+    bin: {
+      [toKebab(config.name)]: `./bin/${toKebab(config.name)}.js`
+    },
+    scripts: {
+      start: `node ./bin/${toKebab(config.name)}.js`
+    },
+    dependencies: {
+      commander: '^12.1.0'
+    }
+  };
+
+  return `${JSON.stringify(packageJson, null, 2)}\n`;
+}
+
+function renderOutputLib() {
+  return `function json(data, pretty) {
+  const text = pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+  process.stdout.write(text + '\\n');
+}
+
+function error(payload, pretty) {
+  const envelope = {
+    error: true,
+    code: payload.code || 'REQUEST_FAILED',
+    message: payload.message || 'Request failed',
+    details: payload.details || {}
+  };
+
+  const text = pretty ? JSON.stringify(envelope, null, 2) : JSON.stringify(envelope);
+  process.stderr.write(text + '\\n');
+}
+
+module.exports = {
+  json,
+  error
+};
+`;
+}
+
+function renderClientLib(config) {
+  const authConfig = JSON.stringify(config.auth || { credentials: [] }, null, 2);
+
+  return `async function request(command, options) {
+  const auth = ${authConfig};
+  const params = new URLSearchParams();
+  const commandParams = command.params || {};
+  let resolvedPath = command.path;
+  const headers = {
+    accept: 'application/json'
+  };
+
+  (auth.credentials || []).forEach((credential) => {
+    const envValue = process.env[credential.envVar];
+
+    if (!envValue) {
+      throw new Error(\`Missing required auth environment variable: \${credential.envVar}\`);
+    }
+
+    const authValue = credential.prefix ? \`\${credential.prefix}\${envValue}\` : envValue;
+
+    if (credential.in === 'header') {
+      headers[credential.name] = authValue;
+      return;
+    }
+
+    params.append(credential.name, authValue);
+  });
+
+  Object.entries(commandParams).forEach(([name, schema]) => {
+    const value = options[name];
+
+    if ((value === undefined || value === null || value === '') && schema.required) {
+      throw new Error(\`Missing required parameter: --\${name}\`);
+    }
+
+    if (value === undefined || value === null || value === '') {
+      return;
+    }
+
+    const token = \`{\${name}}\`;
+
+    if (resolvedPath.includes(token)) {
+      resolvedPath = resolvedPath.replaceAll(token, encodeURIComponent(String(value)));
+      return;
+    }
+
+    params.append(name, String(value));
+  });
+
+  const query = params.toString();
+  const url = '${config.apiBase}' + resolvedPath + (query ? '?' + query : '');
+
+  const response = await fetch(url, {
+    method: command.method,
+    headers
+  });
+
+  const text = await response.text();
+  let body = text;
+
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch (_err) {
+    body = text;
+  }
+
+  if (!response.ok) {
+    const error = new Error(\`HTTP \${response.status}\`);
+    error.statusCode = response.status;
+    error.responseBody = body;
+    throw error;
+  }
+
+  return body;
+}
+
+module.exports = {
+  request
+};
+`;
+}
+
+function renderCommandModule(command) {
+  const functionName = commandToMethodName(command.name);
+  const serializedCommand = JSON.stringify(command, null, 2);
+
+  return `const { request } = require('../lib/client');
+const output = require('../lib/output');
+
+const command = ${serializedCommand};
+
+async function ${functionName}(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: ${functionName},
+  command
+};
+`;
+}
+
+function renderBinFile(config) {
+  const imports = config.commands
+    .map((command, index) => {
+      const varName = `cmd${index}`;
+      return `const ${varName} = require('../commands/${toKebab(command.name)}');`;
+    })
+    .join('\n');
+
+  const registrations = config.commands
+    .map((command, index) => {
+      const varName = `cmd${index}`;
+      const params = command.params || {};
+      const options = Object.entries(params)
+        .map(([paramName, schema]) => {
+          const flagName = `--${toKebab(paramName)} <value>`;
+          const desc = schema.description || `${paramName} parameter`;
+          return `  .option('${flagName}', '${desc}')`;
+        })
+        .join('\n');
+
+      return `program
+  .command('${command.name}')
+  .description('${command.description.replace(/'/g, "\\'")}')
+${options ? `${options}\n` : ''}  .option('--pretty', 'Pretty-print JSON')
+  .action((options) => ${varName}.run(options));`;
+    })
+    .join('\n\n');
+
+  return `#!/usr/bin/env node
+
+const { Command } = require('commander');
+
+${imports}
+
+const program = new Command();
+
+program
+  .name('${toKebab(config.name)}')
+  .description('${config.name} CLI generated by AgentBridge')
+  .version('${config.version}');
+
+${registrations}
+
+program.parse(process.argv);
+`;
+}
+
+function renderReadme(config) {
+  const commandList = config.commands
+    .map((command) => `- \`${toKebab(config.name)} ${command.name}\` - ${command.description}`)
+    .join('\n');
+  const authVars = (config.auth && Array.isArray(config.auth.credentials))
+    ? config.auth.credentials.map((credential) => credential.envVar)
+    : [];
+  const uniqueAuthVars = [...new Set(authVars)];
+  const authSection = uniqueAuthVars.length
+    ? `## Auth\n\nSet required environment variables before running commands:\n\n${uniqueAuthVars.map((envVar) => `- \`${envVar}\``).join('\n')}\n\nDo not pass secrets as command flags.\n\n`
+    : '';
+
+  return `# ${config.name} CLI
+
+Generated by AgentBridge (api-to-cli).
+
+## Install
+
+\`\`\`bash
+npm install
+npm link
+\`\`\`
+
+${authSection}## Commands
+
+${commandList}
+`;
+}
+
+function writeFile(filePath, content, executable = false) {
+  fs.writeFileSync(filePath, content, 'utf8');
+  if (executable) {
+    fs.chmodSync(filePath, 0o755);
+  }
+}
+
+function generateCliProject({ config, outputPath }) {
+  const binName = toKebab(config.name);
+  const binDir = path.join(outputPath, 'bin');
+  const commandsDir = path.join(outputPath, 'commands');
+  const libDir = path.join(outputPath, 'lib');
+
+  ensureDir(outputPath);
+  ensureDir(binDir);
+  ensureDir(commandsDir);
+  ensureDir(libDir);
+
+  writeFile(path.join(outputPath, 'package.json'), renderPackageJson(config));
+  writeFile(path.join(outputPath, 'README.md'), renderReadme(config));
+  writeFile(path.join(libDir, 'output.js'), renderOutputLib());
+  writeFile(path.join(libDir, 'client.js'), renderClientLib(config));
+  writeFile(path.join(binDir, `${binName}.js`), renderBinFile(config), true);
+
+  config.commands.forEach((command) => {
+    writeFile(
+      path.join(commandsDir, `${toKebab(command.name)}.js`),
+      renderCommandModule(command)
+    );
+  });
+}
+
+module.exports = {
+  generateCliProject
+};

package/src/lib/generate-manifest.js

@@ -0,0 +1,51 @@
+const fs = require('fs');
+const path = require('path');
+const { toKebab, getAuthEnvVars } = require('./config-utils');
+
+function buildManifest(config, cliProjectPath, skillPath) {
+  const binName = toKebab(config.name);
+
+  return {
+    schemaVersion: '1.0',
+    generatedBy: 'AgentBridge',
+    generatedAt: new Date().toISOString(),
+    project: {
+      name: config.name,
+      version: config.version
+    },
+    cli: {
+      projectPath: cliProjectPath,
+      packageName: `${binName}-cli`,
+      binary: binName,
+      install: ['npm install', 'npm link']
+    },
+    auth: {
+      envVars: getAuthEnvVars(config)
+    },
+    commands: config.commands.map((command) => ({
+      name: command.name,
+      description: command.description,
+      method: command.method,
+      path: command.path,
+      params: Object.entries(command.params || {}).map(([name, schema]) => ({
+        name,
+        required: Boolean(schema.required),
+        description: schema.description || ''
+      }))
+    })),
+    agent: {
+      skillPath: skillPath || null
+    }
+  };
+}
+
+function writeManifest(outputPath, manifest) {
+  const filePath = path.join(outputPath, 'agentbridge.manifest.json');
+  fs.writeFileSync(filePath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  return filePath;
+}
+
+module.exports = {
+  buildManifest,
+  writeManifest
+};

package/src/lib/generate-skill.js

@@ -0,0 +1,50 @@
+const fs = require('fs');
+const path = require('path');
+const { toKebab, getAuthEnvVars } = require('./config-utils');
+
+function renderSkill(config, cliProjectPath) {
+  const binName = toKebab(config.name);
+  const envVars = getAuthEnvVars(config);
+  const envSection = envVars.length
+    ? envVars.map((envVar) => `- export ${envVar}=\"<value>\"`).join('\n')
+    : '- No auth env vars required';
+
+  const commandDocs = config.commands
+    .map((command) => {
+      const flags = Object.entries(command.params || {})
+        .map(([name, schema]) => {
+          const flag = `--${toKebab(name)} <value>`;
+          const req = schema.required ? 'required' : 'optional';
+          return `  - ${flag} (${req})`;
+        })
+        .join('\n');
+
+      return [
+        `- ${command.name}: ${command.description}`,
+        flags || '  - no params',
+        `  - example: ${binName} ${command.name}${flags ? ` ${Object.keys(command.params || {}).map((p) => `--${toKebab(p)} <value>`).join(' ')}` : ''}`
+      ].join('\n');
+    })
+    .join('\n');
+
+  return `# ${config.name} CLI Skill\n\n## Purpose\nUse the generated ${config.name} CLI from AgentBridge. Always prefer JSON output for machine parsing.\n\n## Location\n- CLI project: ${cliProjectPath}\n- Binary name: ${binName}\n\n## Setup\n1. cd ${cliProjectPath}\n2. npm install\n3. npm link\n\n## Auth\n${envSection}\n\n## Commands\n${commandDocs}\n\n## Rules\n- Do not echo or log auth secrets.\n- Do not pass credentials as command flags.\n- Parse command stdout as JSON.\n- Treat non-zero exits as failure and read stderr JSON envelope.\n`;
+}
+
+function writeSkillPackage(outputPath, config, cliProjectPath) {
+  const skillDir = path.join(outputPath, 'skill');
+  fs.mkdirSync(skillDir, { recursive: true });
+
+  const skillContent = renderSkill(config, cliProjectPath);
+  const skillPath = path.join(skillDir, 'SKILL.md');
+
+  fs.writeFileSync(skillPath, skillContent, 'utf8');
+
+  return {
+    skillDir,
+    skillPath
+  };
+}
+
+module.exports = {
+  writeSkillPackage
+};

package/src/lib/load-config.js

@@ -0,0 +1,120 @@
+const fs = require('fs');
+const path = require('path');
+
+function fail(message) {
+  throw new Error(`Invalid config: ${message}`);
+}
+
+function isObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && Boolean(value.trim());
+}
+
+function validateAuthCredential(credential, index) {
+  if (!isObject(credential)) {
+    fail(`auth.credentials[${index}] must be an object`);
+  }
+
+  if (!isNonEmptyString(credential.envVar)) {
+    fail(`auth.credentials[${index}].envVar must be a non-empty string`);
+  }
+
+  if (credential.in !== 'header' && credential.in !== 'query') {
+    fail(`auth.credentials[${index}].in must be either "header" or "query"`);
+  }
+
+  if (!isNonEmptyString(credential.name)) {
+    fail(`auth.credentials[${index}].name must be a non-empty string`);
+  }
+
+  if (credential.prefix !== undefined && typeof credential.prefix !== 'string') {
+    fail(`auth.credentials[${index}].prefix must be a string when provided`);
+  }
+}
+
+function validateAuth(auth) {
+  if (!isObject(auth)) {
+    fail('auth must be an object when provided');
+  }
+
+  if (!Array.isArray(auth.credentials) || auth.credentials.length === 0) {
+    fail('auth.credentials must be a non-empty array when auth is provided');
+  }
+
+  auth.credentials.forEach(validateAuthCredential);
+}
+
+function validateCommand(command, index) {
+  if (!isObject(command)) {
+    fail(`commands[${index}] must be an object`);
+  }
+
+  if (!isNonEmptyString(command.name)) {
+    fail(`commands[${index}].name must be a non-empty string`);
+  }
+
+  if (!isNonEmptyString(command.description)) {
+    fail(`commands[${index}].description must be a non-empty string`);
+  }
+
+  if (command.method !== 'GET') {
+    fail(`commands[${index}].method must be GET for MVP`);
+  }
+
+  if (typeof command.path !== 'string' || !command.path.startsWith('/')) {
+    fail(`commands[${index}].path must be a string starting with /`);
+  }
+
+  if (command.params !== undefined && !isObject(command.params)) {
+    fail(`commands[${index}].params must be an object when provided`);
+  }
+}
+
+function validateConfig(config) {
+  if (!isObject(config)) {
+    fail('config must export an object');
+  }
+
+  if (!isNonEmptyString(config.name)) {
+    fail('name must be a non-empty string');
+  }
+
+  if (!isNonEmptyString(config.version)) {
+    fail('version must be a non-empty string');
+  }
+
+  if (typeof config.apiBase !== 'string' || !/^https?:\/\//.test(config.apiBase)) {
+    fail('apiBase must be an http(s) URL');
+  }
+
+  if (!Array.isArray(config.commands) || config.commands.length === 0) {
+    fail('commands must be a non-empty array');
+  }
+
+  if (config.auth !== undefined) {
+    validateAuth(config.auth);
+  }
+
+  config.commands.forEach(validateCommand);
+}
+
+function loadConfig(configPath) {
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Config file not found: ${configPath}`);
+  }
+
+  const resolved = path.resolve(configPath);
+  delete require.cache[resolved];
+  const config = require(resolved);
+
+  validateConfig(config);
+
+  return config;
+}
+
+module.exports = {
+  loadConfig
+};