api-to-cli 0.1.2 → 0.1.3

package/src/commands/doctor.js

@@ -0,0 +1,234 @@
+const fs = require('fs');
+const path = require('path');
+const { loadConfig } = require('../lib/load-config');
+const { loadConfigFromOpenApi } = require('../lib/openapi-to-config');
+
+const COMMON_SPEC_PATHS = [
+  '/openapi.json',
+  '/openapi.yaml',
+  '/openapi.yml',
+  '/swagger.json',
+  '/v1/openapi.json',
+  '/v1/swagger.json',
+  '/.well-known/openapi.json'
+];
+
+function compareVersions(a, b) {
+  const pa = a.split('.').map((n) => Number(n));
+  const pb = b.split('.').map((n) => Number(n));
+  const len = Math.max(pa.length, pb.length);
+
+  for (let i = 0; i < len; i += 1) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da > db) {
+      return 1;
+    }
+    if (da < db) {
+      return -1;
+    }
+  }
+
+  return 0;
+}
+
+function makeCheck(name, ok, details, fix) {
+  return {
+    name,
+    ok,
+    details,
+    fix: fix || null
+  };
+}
+
+function isHttpUrl(value) {
+  return /^https?:\/\//i.test(String(value));
+}
+
+function normalizeBaseUrl(url) {
+  return String(url).replace(/\/+$/, '');
+}
+
+function buildSpecCandidates(baseUrl) {
+  const normalized = normalizeBaseUrl(baseUrl);
+  const directLooksLikeSpec = /(openapi|swagger)\.(json|ya?ml)$/i.test(normalized);
+
+  const candidates = [normalized];
+  if (!directLooksLikeSpec) {
+    COMMON_SPEC_PATHS.forEach((specPath) => {
+      candidates.push(`${normalized}${specPath}`);
+    });
+  }
+
+  return [...new Set(candidates)];
+}
+
+async function fetchWithTimeout(url, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    return response;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function doctor(flags) {
+  const checks = [];
+
+  const nodeVersion = process.versions.node;
+  const nodeOk = compareVersions(nodeVersion, '18.0.0') >= 0;
+  checks.push(
+    makeCheck(
+      'node-version',
+      nodeOk,
+      `Detected Node.js ${nodeVersion}`,
+      nodeOk ? null : 'Upgrade Node.js to v18 or newer.'
+    )
+  );
+
+  const fetchOk = typeof fetch === 'function';
+  checks.push(
+    makeCheck(
+      'fetch-availability',
+      fetchOk,
+      fetchOk ? 'Global fetch is available.' : 'Global fetch is not available.',
+      fetchOk ? null : 'Use Node.js v18+ where fetch is built in.'
+    )
+  );
+
+  const cwd = process.cwd();
+  const cwdWritable = (() => {
+    try {
+      fs.accessSync(cwd, fs.constants.W_OK);
+      return true;
+    } catch (_error) {
+      return false;
+    }
+  })();
+  checks.push(
+    makeCheck(
+      'cwd-writable',
+      cwdWritable,
+      `Working directory: ${cwd}`,
+      cwdWritable ? null : 'Use a directory where you have write permissions.'
+    )
+  );
+
+  if (flags.config) {
+    const configPath = path.resolve(process.cwd(), String(flags.config));
+    try {
+      const config = loadConfig(configPath);
+      checks.push(
+        makeCheck(
+          'config-validation',
+          true,
+          `Config valid: ${configPath} (${config.commands.length} commands)`,
+          null
+        )
+      );
+    } catch (error) {
+      checks.push(
+        makeCheck(
+          'config-validation',
+          false,
+          `Config invalid: ${configPath} (${error.message})`,
+          'Fix the config schema and re-run doctor.'
+        )
+      );
+    }
+  }
+
+  if (flags.spec) {
+    const specInput = String(flags.spec);
+    try {
+      const config = await loadConfigFromOpenApi({
+        specInput,
+        name: flags.name ? String(flags.name) : undefined,
+        version: flags.version ? String(flags.version) : undefined
+      });
+      checks.push(
+        makeCheck(
+          'spec-parse',
+          true,
+          `Spec parsed: ${specInput} (${config.commands.length} commands)`
+        )
+      );
+    } catch (error) {
+      checks.push(
+        makeCheck(
+          'spec-parse',
+          false,
+          `Spec parse failed: ${specInput} (${error.message})`,
+          'Ensure spec is valid OpenAPI 3.x JSON/YAML and accessible.'
+        )
+      );
+    }
+  }
+
+  if (flags.url) {
+    const baseUrl = String(flags.url);
+    const isUrl = isHttpUrl(baseUrl);
+
+    if (!isUrl) {
+      checks.push(
+        makeCheck(
+          'url-format',
+          false,
+          `URL is not HTTP(S): ${baseUrl}`,
+          'Pass a full base URL like https://api.example.com'
+        )
+      );
+    } else {
+      checks.push(makeCheck('url-format', true, `Valid HTTP(S) URL: ${baseUrl}`));
+      const candidates = buildSpecCandidates(baseUrl);
+      let discovered = null;
+
+      for (const candidate of candidates) {
+        try {
+          const response = await fetchWithTimeout(candidate, 4000);
+          if (!response.ok) {
+            continue;
+          }
+
+          const text = await response.text();
+          if (/("openapi"\s*:|^openapi\s*:)/m.test(text)) {
+            discovered = candidate;
+            break;
+          }
+        } catch (_error) {
+          // continue checking candidates
+        }
+      }
+
+      checks.push(
+        makeCheck(
+          'openapi-discovery',
+          Boolean(discovered),
+          discovered
+            ? `Discovered OpenAPI candidate: ${discovered}`
+            : `No OpenAPI discovered from ${baseUrl}`,
+          discovered ? null : 'Run init anyway to generate starter config, then edit endpoints manually.'
+        )
+      );
+    }
+  }
+
+  const ok = checks.every((check) => check.ok);
+
+  console.log(
+    JSON.stringify({
+      ok,
+      command: 'doctor',
+      checks,
+      next: ok
+        ? 'Environment looks good. Run generate or scaffold.'
+        : 'Address failed checks and rerun doctor.'
+    })
+  );
+}
+
+module.exports = {
+  doctor
+};

package/src/commands/generate.js

@@ -1,20 +1,14 @@
 const path = require('path');
-const { loadConfig } = require('../lib/load-config');
 const { generateCliProject } = require('../lib/generate-cli');
+const { resolveConfigInput } = require('../lib/resolve-config-input');
 
 async function generate(flags) {
-  if (!flags.config) {
-    throw new Error('Missing required flag: --config <path>');
-  }
-
   if (!flags.output) {
     throw new Error('Missing required flag: --output <dir>');
   }
 
-  const configPath = path.resolve(process.cwd(), String(flags.config));
   const outputPath = path.resolve(process.cwd(), String(flags.output));
-
-  const config = loadConfig(configPath);
+  const { config, source } = await resolveConfigInput(flags);
 
   generateCliProject({
     config,
@@ -26,6 +20,8 @@ async function generate(flags) {
       ok: true,
       command: 'generate',
       outputPath,
+      inputType: source.type,
+      input: source.value,
       generatedCommands: config.commands.map((command) => command.name)
     })
   );

package/src/commands/init.js

@@ -0,0 +1,154 @@
+const fs = require('fs');
+const path = require('path');
+const { loadConfigFromOpenApi } = require('../lib/openapi-to-config');
+
+const COMMON_SPEC_PATHS = [
+  '/openapi.json',
+  '/openapi.yaml',
+  '/openapi.yml',
+  '/swagger.json',
+  '/v1/openapi.json',
+  '/v1/swagger.json',
+  '/.well-known/openapi.json'
+];
+
+function normalizeBaseUrl(url) {
+  return String(url).replace(/\/+$/, '');
+}
+
+function inferNameFromUrl(urlValue) {
+  try {
+    const host = new URL(urlValue).hostname;
+    const label = host.split('.').filter(Boolean)[0] || 'myapi';
+    return label.replace(/[^a-zA-Z0-9]+/g, '-').toLowerCase();
+  } catch (_error) {
+    return 'myapi';
+  }
+}
+
+function buildSpecCandidates(baseUrl) {
+  const normalized = normalizeBaseUrl(baseUrl);
+  const directLooksLikeSpec = /(openapi|swagger)\.(json|ya?ml)$/i.test(normalized);
+
+  const candidates = [normalized];
+  if (!directLooksLikeSpec) {
+    COMMON_SPEC_PATHS.forEach((specPath) => {
+      candidates.push(`${normalized}${specPath}`);
+    });
+  }
+
+  return [...new Set(candidates)];
+}
+
+function renderConfig(config) {
+  return `module.exports = ${JSON.stringify(config, null, 2)};\n`;
+}
+
+function renderStarterConfig({ name, version, apiBase }) {
+  const starter = {
+    name,
+    version,
+    apiBase,
+    auth: {
+      credentials: [
+        {
+          envVar: `${name.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_API_KEY`,
+          in: 'header',
+          name: 'Authorization',
+          prefix: 'Bearer '
+        }
+      ]
+    },
+    commands: [
+      {
+        name: 'health',
+        description: 'Health check endpoint (edit path/method as needed)',
+        method: 'GET',
+        path: '/health',
+        params: {}
+      }
+    ]
+  };
+
+  return renderConfig(starter);
+}
+
+async function tryOpenApiCandidates({ candidates, name, version }) {
+  const failures = [];
+
+  for (const candidate of candidates) {
+    try {
+      const config = await loadConfigFromOpenApi({
+        specInput: candidate,
+        name,
+        version
+      });
+
+      return {
+        config,
+        discoveredSpec: candidate,
+        failures
+      };
+    } catch (error) {
+      failures.push({
+        candidate,
+        message: error.message
+      });
+    }
+  }
+
+  return {
+    config: null,
+    discoveredSpec: null,
+    failures
+  };
+}
+
+async function init(flags) {
+  if (!flags.url) {
+    throw new Error('Missing required flag: --url <api-base-url>');
+  }
+
+  const baseUrl = String(flags.url);
+  const outputPath = path.resolve(process.cwd(), String(flags.output || './api-to-cli.config.js'));
+  const name = String(flags.name || inferNameFromUrl(baseUrl));
+  const version = String(flags.version || '1.0.0');
+
+  const candidates = buildSpecCandidates(baseUrl);
+  const result = await tryOpenApiCandidates({ candidates, name, version });
+
+  let mode = 'starter';
+  let discoveredSpec = null;
+  let fileText = renderStarterConfig({
+    name,
+    version,
+    apiBase: normalizeBaseUrl(baseUrl)
+  });
+
+  if (result.config) {
+    mode = 'openapi';
+    discoveredSpec = result.discoveredSpec;
+    fileText = renderConfig(result.config);
+  }
+
+  fs.writeFileSync(outputPath, fileText, 'utf8');
+
+  console.log(
+    JSON.stringify({
+      ok: true,
+      command: 'init',
+      mode,
+      baseUrl: normalizeBaseUrl(baseUrl),
+      outputPath,
+      discoveredSpec,
+      attemptedSpecCandidates: candidates,
+      hint: mode === 'openapi'
+        ? 'OpenAPI discovered. You can run: api-to-cli generate --config <outputPath> --output <dir>'
+        : 'No OpenAPI discovered. Edit the generated config and then run generate.'
+    })
+  );
+}
+
+module.exports = {
+  init
+};

package/src/commands/scaffold.js

@@ -1,9 +1,9 @@
 const fs = require('fs');
 const path = require('path');
-const { loadConfig } = require('../lib/load-config');
 const { generateCliProject } = require('../lib/generate-cli');
 const { writeSkillPackage } = require('../lib/generate-skill');
 const { buildManifest, writeManifest } = require('../lib/generate-manifest');
+const { resolveConfigInput } = require('../lib/resolve-config-input');
 
 function hasOwn(obj, key) {
   return Object.prototype.hasOwnProperty.call(obj, key);
@@ -31,7 +31,8 @@ function writeScaffoldReadme(outputPath, data) {
     '# AgentBridge Scaffold Output',
     '',
     '## Contents',
-    `- CLI project: ${data.cliProjectPath}`
+    `- CLI project: ${data.cliProjectPath}`,
+    `- Input source: ${data.inputType} (${data.inputValue})`
   ];
 
   if (data.skillPath) {
@@ -48,10 +49,6 @@ function writeScaffoldReadme(outputPath, data) {
 }
 
 async function scaffold(flags) {
-  if (!flags.config) {
-    throw new Error('Missing required flag: --config <path>');
-  }
-
   if (!flags.output) {
     throw new Error('Missing required flag: --output <dir>');
   }
@@ -61,11 +58,10 @@ async function scaffold(flags) {
   const skillRelativePath = './skill/SKILL.md';
   const manifestRelativePath = './agentbridge.manifest.json';
 
-  const configPath = path.resolve(process.cwd(), String(flags.config));
   const outputPath = path.resolve(process.cwd(), String(flags.output));
   const cliProjectPath = path.join(outputPath, 'cli');
+  const { config, source } = await resolveConfigInput(flags);
 
-  const config = loadConfig(configPath);
   fs.mkdirSync(outputPath, { recursive: true });
 
   generateCliProject({
@@ -89,7 +85,9 @@ async function scaffold(flags) {
   writeScaffoldReadme(outputPath, {
     cliProjectPath: cliRelativePath,
     skillPath,
-    manifestPath
+    manifestPath,
+    inputType: source.type,
+    inputValue: source.value
   });
 
   console.log(
@@ -97,6 +95,8 @@ async function scaffold(flags) {
       ok: true,
       command: 'scaffold',
       outputPath,
+      inputType: source.type,
+      input: source.value,
       cliProjectPath: cliRelativePath,
       skillPath,
       manifestPath,

package/src/commands/validate.js

@@ -1,25 +1,21 @@
-const path = require('path');
-const { loadConfig } = require('../lib/load-config');
+const { resolveConfigInput } = require('../lib/resolve-config-input');
 
 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);
+  const { config, source } = await resolveConfigInput(flags);
 
   console.log(
     JSON.stringify({
       ok: true,
       command: 'validate',
-      configPath,
+      inputType: source.type,
+      input: source.value,
       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)
+        hasAuth: Boolean(config.auth && config.auth.credentials && config.auth.credentials.length),
+        methods: [...new Set(config.commands.map((command) => command.method))]
       }
     })
   );

package/src/index.js

@@ -1,4 +1,6 @@
+const { doctor } = require('./commands/doctor');
 const { generate } = require('./commands/generate');
+const { init } = require('./commands/init');
 const { validate } = require('./commands/validate');
 const { scaffold } = require('./commands/scaffold');
 
@@ -6,13 +8,17 @@ 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]',
+      '  api-to-cli doctor [--config <path>] [--spec <path-or-url>] [--url <api-base-url>]',
+      '  api-to-cli init --url <api-base-url> [--output <path>] [--name <cli-name>] [--version <semver>]',
+      '  api-to-cli generate (--config <path> | --spec <path-or-url>) --output <dir> [--name <cli-name>]',
+      '  api-to-cli validate (--config <path> | --spec <path-or-url>) [--name <cli-name>]',
+      '  api-to-cli scaffold (--config <path> | --spec <path-or-url>) --output <dir> [--name <cli-name>] [--with-skill] [--with-manifest]',
       '',
       'Commands:',
-      '  generate   Generate a CLI from config',
-      '  validate   Validate config only',
+      '  doctor     Run environment and input diagnostics',
+      '  init       Discover OpenAPI and generate starter config',
+      '  generate   Generate a CLI from config/spec',
+      '  validate   Validate config/spec only',
       '  scaffold   Generate CLI + optional skill/manifest bundle'
     ].join('\n')
   );
@@ -54,6 +60,16 @@ async function run(argv) {
   try {
     const flags = parseFlags(rest);
 
+    if (command === 'doctor') {
+      await doctor(flags);
+      return;
+    }
+
+    if (command === 'init') {
+      await init(flags);
+      return;
+    }
+
     if (command === 'generate') {
       await generate(flags);
       return;