apiskill 0.1.0

package/scripts/apiskill-cli.mjs

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import {
+  createBlankDocument,
+  endpointToManualConfig,
+  findEndpoint,
+  formatManualCli,
+  listCachedVersions,
+  listEndpoints,
+  parseManualCliText,
+  readCachedDocument,
+  saveImportedDocument,
+  saveManualOperation,
+  deleteManualOperation,
+} from './lib/openapi-store.mjs';
+import { crawlOpenApi, importFromCurl, importFromLocalFile, importFromUrl } from './lib/openapi-importer.mjs';
+import { checkCache, formatCheckText, queryEndpoints } from './lib/apiskill-core.mjs';
+import { startMockServer } from './lib/mock-server.mjs';
+
+const program = new Command();
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+program
+  .name('apiskill')
+  .description('API Skill CLI: import OpenAPI docs and create/query/edit/delete local API configs.')
+  .version('0.1.0', '-V, --cli-version', 'Print CLI version')
+  .showHelpAfterError()
+  .addHelpText(
+    'after',
+    `
+
+Examples:
+  apiskill import https://example.com/openapi.yaml
+  apiskill crawl https://example.com/swagger
+  apiskill import-file ./openapi.json
+  apiskill import-curl --file ./request.curl
+  apiskill run web
+  apiskill mock
+  apiskill document create --title "My API" --doc-version 1.0.0
+  apiskill check
+  apiskill versions
+  apiskill query /admin/api/v1/activity/activity/statistics/date/list
+  apiskill query /admin/api/v1/activity --method GET
+  apiskill api list --query user --method post
+  apiskill api query GET /api/v1/user --format cli
+  apiskill api create --file ./api-config.yaml
+  apiskill api edit GET /api/v1/user --file ./api-config.json --version 20260429T000000Z-manual-user
+  apiskill api delete GET /api/v1/user --version 20260429T000000Z-manual-user
+
+CLI config format:
+  {"api":{"method":"post","path":"/api/v1/example","summary":"创建示例","responses":[{"status":"200"}]}}
+  YAML is also accepted with root key api:, config:, or operation:.
+`,
+  );
+
+const run = program.command('run').description('Run API Skill local services.');
+
+run
+  .command('web')
+  .description('Start the API Skill web console from the CLI.')
+  .option('-p, --port <number>', 'Web server port', '8888')
+  .option('--host <host>', 'Host to bind', '127.0.0.1')
+  .option('--strict-port', 'Fail if the requested port is already in use')
+  .option('--cwd <dir>', 'Project directory used for the default cache location')
+  .option('--cache-dir <dir>', 'Cache directory. Defaults to <cwd>/cache')
+  .action(async (options) => {
+    await runWeb(options);
+  });
+
+registerMockCommand(run.command('mock').description('Start a local mock API server from the cached OpenAPI document.'));
+
+registerMockCommand(program.command('mock').description('Start a local mock API server from the cached OpenAPI document.'));
+
+program
+  .command('check')
+  .description('Check whether a usable cached OpenAPI document is configured. Prints import examples when no cache is available.')
+  .option('-j, --json', 'Print JSON')
+  .action(async (options) => {
+    const result = await checkCache();
+    print(options.json ? result : formatCheckText(result));
+  });
+
+program
+  .command('query')
+  .description('Query API operations by path or keyword. A single exact match prints API CLI config; multiple matches print a list.')
+  .argument('<pathOrKeyword>', 'Exact API path or search keyword')
+  .option('-m, --method <method>', 'Optional HTTP method filter: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD')
+  .option('-v, --version <versionId>', 'Version id. Defaults to latest.')
+  .option('-l, --limit <number>', 'Maximum list rows when multiple endpoints match', '20')
+  .option('-j, --json', 'Print JSON')
+  .addHelpText(
+    'after',
+    `
+
+Examples:
+  apiskill query /admin/api/v1/activity/activity/statistics/date/list
+  apiskill query /admin/api/v1/activity/activity/statistics/date/list --method GET
+  apiskill query activity --method POST --limit 10
+
+Behavior:
+  - If one endpoint matches exactly, prints API CLI JSON for that endpoint.
+  - If multiple endpoints match, prints a concise candidate list.
+  - Use --method GET/POST/DELETE/etc. to narrow results.
+`,
+  )
+  .action(async (pathOrKeyword, options) => {
+    const { document } = await readCachedDocument(options.version);
+    const result = queryEndpoints(document, pathOrKeyword, options);
+    if (result.kind === 'single') {
+      print(options.json ? result.endpoint : formatManualCli(endpointToManualConfig(result.endpoint, document)));
+      return;
+    }
+    print(options.json ? result.endpoints : result.endpoints.map((endpoint) => `${endpoint.method.toUpperCase()}\t${endpoint.path}\t${endpoint.summary}`).join('\n'));
+  });
+
+program
+  .command('versions')
+  .description('List cached OpenAPI document versions.')
+  .option('-j, --json', 'Print JSON')
+  .action(async (options) => {
+    const versions = await listCachedVersions();
+    print(options.json ? versions : versions.map((item) => `${item.versionId}\t${item.mode || ''}\t${item.paths ?? 0} paths\t${item.title || item.inputUrl || ''}`).join('\n'));
+  });
+
+program
+  .command('import')
+  .description('Import a direct OpenAPI/Swagger JSON or YAML URL.')
+  .argument('<url>', 'OpenAPI JSON/YAML URL')
+  .option('--auth <username:password>', 'Basic auth credentials')
+  .option('-j, --json', 'Print JSON')
+  .action(async (url, options) => {
+    const result = await importFromUrl(url, { basicAuth: options.auth });
+    const saved = await saveImportedDocument({ document: result.document, mode: 'file', inputUrl: url, resolvedUrl: result.resolvedUrl });
+    printResult(saved, options.json);
+  });
+
+program
+  .command('crawl')
+  .description('Crawl Swagger UI / Knife4j / Redoc page and import discovered OpenAPI document.')
+  .argument('<url>', 'Online API document page URL')
+  .option('--auth <username:password>', 'Basic auth credentials')
+  .option('-j, --json', 'Print JSON')
+  .action(async (url, options) => {
+    const result = await crawlOpenApi(url, { basicAuth: options.auth });
+    const saved = await saveImportedDocument({ document: result.document, mode: 'crawl', inputUrl: url, resolvedUrl: result.resolvedUrl });
+    printResult(saved, options.json);
+  });
+
+program
+  .command('import-file')
+  .description('Import a local OpenAPI/Swagger JSON or YAML file.')
+  .argument('<file>', 'Local JSON/YAML file path')
+  .option('-j, --json', 'Print JSON')
+  .action(async (file, options) => {
+    const result = await importFromLocalFile(file);
+    const saved = await saveImportedDocument({ document: result.document, mode: 'upload', inputUrl: file, resolvedUrl: result.resolvedUrl });
+    printResult(saved, options.json);
+  });
+
+program
+  .command('import-curl')
+  .description('Execute a curl command and import JSON/YAML OpenAPI response.')
+  .option('-c, --command <curl>', 'Curl command text')
+  .option('-f, --file <file>', 'Read curl command from file')
+  .option('-j, --json', 'Print JSON')
+  .action(async (options) => {
+    const curlText = options.file ? await readFile(options.file, 'utf8') : options.command;
+    if (!curlText) throw new Error('请通过 --command 或 --file 提供 curl 命令');
+    const result = await importFromCurl(curlText);
+    const saved = await saveImportedDocument({ document: result.document, mode: 'curl', inputUrl: curlText, resolvedUrl: result.resolvedUrl });
+    printResult(saved, options.json);
+  });
+
+const document = program.command('document').alias('doc').description('Create and maintain local OpenAPI documents.');
+
+document
+  .command('create')
+  .description('Create a blank local OpenAPI document version for AI/CLI/MCP-driven API authoring.')
+  .option('-t, --title <title>', 'Document title', 'API Skill Document')
+  .option('--doc-version <version>', 'OpenAPI info.version value', '1.0.0')
+  .option('-d, --description <description>', 'Document description', 'Created from API Skill blank document.')
+  .option('--environment-name <name>', 'Optional environment name metadata')
+  .option('--environment-base-url <url>', 'Optional environment base URL metadata')
+  .option('-j, --json', 'Print JSON')
+  .action(async (options) => {
+    const saved = await createBlankDocument({
+      title: options.title,
+      version: options.docVersion,
+      description: options.description,
+      environmentName: options.environmentName,
+      environmentBaseUrl: options.environmentBaseUrl,
+    });
+    printResult(saved, options.json);
+  });
+
+const api = program.command('api').description('Create, query, edit, and delete API operations in local versions.');
+
+api
+  .command('list')
+  .description('List/search API operations from a cached version.')
+  .option('-v, --version <versionId>', 'Version id. Defaults to latest.')
+  .option('-q, --query <keyword>', 'Search keyword')
+  .option('-m, --method <method>', 'HTTP method filter')
+  .option('-l, --limit <number>', 'Maximum rows', '50')
+  .option('-j, --json', 'Print JSON')
+  .action(async (options) => {
+    const { document } = await readCachedDocument(options.version);
+    const query = String(options.query || '').toLowerCase();
+    const method = String(options.method || '').toLowerCase();
+    const limit = Number(options.limit) || 50;
+    const endpoints = listEndpoints(document)
+      .filter((endpoint) => !query || endpoint.searchable.includes(query))
+      .filter((endpoint) => !method || endpoint.method === method)
+      .slice(0, limit);
+    print(options.json ? endpoints : endpoints.map((endpoint) => `${endpoint.method.toUpperCase()}\t${endpoint.path}\t${endpoint.summary}`).join('\n'));
+  });
+
+api
+  .command('query')
+  .description('Get one API operation.')
+  .argument('<method>', 'HTTP method')
+  .argument('<path>', 'OpenAPI path')
+  .option('-v, --version <versionId>', 'Version id. Defaults to latest.')
+  .option('-f, --format <json|cli|raw>', 'Output format', 'json')
+  .action(async (method, path, options) => {
+    const { document } = await readCachedDocument(options.version);
+    const endpoint = findEndpoint(document, method, path);
+    if (!endpoint) throw new Error(`接口不存在: ${method.toUpperCase()} ${path}`);
+    if (options.format === 'cli') print(formatManualCli(endpointToManualConfig(endpoint, document)));
+    else if (options.format === 'raw') print(endpoint.operation);
+    else print(endpoint);
+  });
+
+api
+  .command('create')
+  .description('Create an API operation. If --version is omitted, a new manual version is created.')
+  .option('-v, --version <versionId>', 'Version id to append to')
+  .option('-f, --file <file>', 'JSON/YAML/CLI config file')
+  .option('-c, --config <text>', 'Inline JSON/YAML/CLI config')
+  .option('-j, --json', 'Print JSON')
+  .action(async (options) => {
+    const config = await readConfig(options);
+    const saved = await saveManualOperation({ versionId: options.version, config });
+    printResult(saved, options.json);
+  });
+
+api
+  .command('edit')
+  .description('Edit/replace one API operation.')
+  .argument('<method>', 'Original HTTP method')
+  .argument('<path>', 'Original OpenAPI path')
+  .option('-f, --file <file>', 'JSON/YAML/CLI config file')
+  .option('-c, --config <text>', 'Inline JSON/YAML/CLI config')
+  .option('-v, --version <versionId>', 'Version id. Defaults to latest.')
+  .option('-j, --json', 'Print JSON')
+  .action(async (method, path, options) => {
+    const versionId = options.version || (await readCachedDocument()).meta?.versionId;
+    const config = await readConfig(options);
+    const saved = await saveManualOperation({ versionId, config, replaceTarget: { method, path } });
+    printResult(saved, options.json);
+  });
+
+api
+  .command('delete')
+  .description('Delete one API operation from a cached version.')
+  .argument('<method>', 'HTTP method')
+  .argument('<path>', 'OpenAPI path')
+  .option('-v, --version <versionId>', 'Version id. Defaults to latest.')
+  .option('-j, --json', 'Print JSON')
+  .action(async (method, path, options) => {
+    const versionId = options.version || (await readCachedDocument()).meta?.versionId;
+    const saved = await deleteManualOperation({ versionId, method, path });
+    printResult(saved, options.json);
+  });
+
+program.parseAsync().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});
+
+function registerMockCommand(command) {
+  command
+    .option('-p, --port <number>', 'Mock server port', '4010')
+    .option('--host <host>', 'Host to bind', '127.0.0.1')
+    .option('-v, --version <versionId>', 'Version id. Defaults to latest.')
+    .option('-j, --json', 'Print startup info as JSON')
+    .action(async (options) => {
+      await runMock(options);
+    });
+}
+
+async function runWeb(options) {
+  const projectRoot = resolve(options.cwd || process.cwd());
+  const cacheDir = options.cacheDir ? resolve(projectRoot, options.cacheDir) : process.env.APISKILL_CACHE_DIR || resolve(projectRoot, 'cache');
+  const port = Number(options.port) || 8888;
+  const host = options.host || '127.0.0.1';
+
+  process.env.APISKILL_ROOT = projectRoot;
+  process.env.APISKILL_CACHE_DIR = cacheDir;
+
+  const { createServer } = await import('vite');
+  const server = await createServer({
+    root: packageRoot,
+    configFile: resolve(packageRoot, 'vite.config.ts'),
+    clearScreen: false,
+    server: {
+      host,
+      port,
+      strictPort: Boolean(options.strictPort),
+    },
+  });
+
+  await server.listen();
+  console.log(`API Skill web is using cache: ${cacheDir}`);
+  server.printUrls();
+
+  const close = async () => {
+    await server.close();
+    process.exit(0);
+  };
+  process.once('SIGINT', close);
+  process.once('SIGTERM', close);
+}
+
+async function runMock(options) {
+  let cached;
+  try {
+    cached = await readCachedDocument(options.version);
+  } catch {
+    throw new Error('当前没有可用的 API 文档数据，请先导入、爬取或新建文档后再启动 MOCK 服务');
+  }
+  const { document, meta } = cached;
+  const mock = await startMockServer({
+    document,
+    meta,
+    host: options.host || '127.0.0.1',
+    port: Number(options.port) || 4010,
+  });
+
+  const info = {
+    url: mock.url,
+    versionId: mock.versionId,
+    title: mock.title,
+    routes: mock.routesCount,
+  };
+  print(options.json ? info : `API Skill MOCK 服务已启动: ${mock.url}\n版本: ${mock.versionId || 'latest'}\n接口: ${mock.routesCount}\n按 Ctrl+C 停止服务`);
+
+  const close = async () => {
+    await new Promise((resolve) => mock.server.close(resolve));
+    process.exit(0);
+  };
+  process.once('SIGINT', close);
+  process.once('SIGTERM', close);
+}
+
+async function readConfig(options) {
+  const text = options.file ? await readFile(options.file, 'utf8') : options.config;
+  if (!text) throw new Error('请通过 --file 或 --config 提供 API CLI 配置');
+  return parseManualCliText(text);
+}
+
+function printResult(saved, json) {
+  print(json ? saved : `saved ${saved.meta.versionId}\npaths ${saved.meta.paths}\nschemas ${saved.meta.schemas}\nfile ${saved.meta.savedPath}`);
+}
+
+function print(value) {
+  if (typeof value === 'string') console.log(value);
+  else console.log(JSON.stringify(value, null, 2));
+}