apiskill 0.1.0

package/scripts/lib/openapi-store.mjs

@@ -0,0 +1,542 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+export const METHODS = ['get', 'post', 'put', 'delete', 'patch', 'options', 'head'];
+
+const rootDir = process.env.APISKILL_ROOT || resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const cacheDir = process.env.APISKILL_CACHE_DIR || resolve(rootDir, 'cache');
+const versionsDir = resolve(cacheDir, 'versions');
+const latestMetaPath = resolve(cacheDir, 'latest-import.json');
+const legacyCachePath = resolve(cacheDir, 'openapi-cache.json');
+const legacyCacheMetaPath = resolve(cacheDir, 'import-meta.json');
+
+export function parseOpenApiText(text) {
+  const cleaned = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+  try {
+    return JSON.parse(cleaned);
+  } catch {
+    return parseYaml(cleaned);
+  }
+}
+
+export function isOpenApiDocument(value) {
+  return Boolean(value && typeof value === 'object' && (value.openapi || value.swagger) && value.paths && typeof value.paths === 'object');
+}
+
+export async function readCachedDocument(versionId) {
+  if (versionId) {
+    assertSafeVersionId(versionId);
+    const metaPath = resolve(versionsDir, `${versionId}.meta.json`);
+    const documentPath = resolve(versionsDir, `${versionId}.json`);
+    if (!existsSync(metaPath) && !existsSync(documentPath)) throw new Error(`缓存版本不存在: ${versionId}`);
+    const meta = existsSync(metaPath) ? JSON.parse(await readFile(metaPath, 'utf8')) : { versionId, savedPath: documentPath };
+    const savedPath = typeof meta.savedPath === 'string' ? meta.savedPath : documentPath;
+    return { document: JSON.parse(await readFile(savedPath, 'utf8')), meta: { ...meta, savedPath } };
+  }
+
+  if (!existsSync(latestMetaPath) && !existsSync(legacyCachePath)) throw new Error('没有本地缓存文档');
+  const meta = existsSync(latestMetaPath)
+    ? JSON.parse(await readFile(latestMetaPath, 'utf8'))
+    : existsSync(legacyCacheMetaPath)
+      ? JSON.parse(await readFile(legacyCacheMetaPath, 'utf8'))
+      : {};
+  const documentPath = typeof meta.savedPath === 'string' ? meta.savedPath : legacyCachePath;
+  return { document: JSON.parse(await readFile(documentPath, 'utf8')), meta };
+}
+
+export async function listCachedVersions() {
+  const latestMeta = existsSync(latestMetaPath) ? JSON.parse(await readFile(latestMetaPath, 'utf8')) : undefined;
+  if (!existsSync(versionsDir)) {
+    if (!existsSync(legacyCachePath)) return [];
+    const fileStat = await stat(legacyCachePath);
+    return [
+      {
+        versionId: 'legacy-openapi-cache',
+        mode: 'legacy',
+        savedAt: fileStat.mtime.toISOString(),
+        savedPath: legacyCachePath,
+        latest: true,
+      },
+    ];
+  }
+  const files = await readdir(versionsDir);
+  const versionIds = new Set(files.filter((file) => file.endsWith('.json') && !file.endsWith('.meta.json')).map((file) => file.replace(/\.json$/, '')));
+  files.filter((file) => file.endsWith('.meta.json')).forEach((file) => versionIds.add(file.replace(/\.meta\.json$/, '')));
+  const metas = await Promise.all(
+    [...versionIds].map(async (versionId) => {
+      const documentPath = resolve(versionsDir, `${versionId}.json`);
+      const metaPath = resolve(versionsDir, `${versionId}.meta.json`);
+      try {
+        const fileStat = existsSync(documentPath) ? await stat(documentPath) : undefined;
+        const meta = existsSync(metaPath) ? JSON.parse(await readFile(metaPath, 'utf8')) : {};
+        return {
+          versionId,
+          mode: meta.mode || '',
+          inputUrl: meta.inputUrl || '',
+          resolvedUrl: meta.resolvedUrl || '',
+          title: meta.title || '',
+          version: meta.version || '',
+          savedAt: meta.savedAt || fileStat?.mtime.toISOString() || '',
+          paths: meta.paths,
+          schemas: meta.schemas,
+          savedFile: meta.savedFile || `${versionId}.json`,
+          savedPath: meta.savedPath || documentPath,
+          latest: latestMeta?.versionId === versionId,
+        };
+      } catch {
+        return undefined;
+      }
+    }),
+  );
+  return metas.filter(Boolean).sort((a, b) => String(b.savedAt || '').localeCompare(String(a.savedAt || '')));
+}
+
+export async function saveImportedDocument({ document, mode, inputUrl, resolvedUrl, versionId }) {
+  if (!isOpenApiDocument(document)) throw new Error('不是有效的 OpenAPI/Swagger 文档');
+  const existing = versionId ? await readCachedDocument(versionId) : undefined;
+  const savedAt = new Date();
+  const nextVersionId = existing?.meta?.versionId || `${formatVersionDate(savedAt)}-${mode}-${slugify(sourceName(resolvedUrl || inputUrl))}`;
+  return writeVersion(document, {
+    ...(existing?.meta ?? {}),
+    savedPath: existing?.meta?.savedPath,
+    versionId: nextVersionId,
+    mode,
+    inputUrl,
+    resolvedUrl: resolvedUrl || inputUrl,
+    title: document.info?.title || '',
+    version: document.info?.version || '',
+    savedAt: savedAt.toISOString(),
+  });
+}
+
+export async function createBlankDocument({
+  title = 'API Skill Document',
+  version = '1.0.0',
+  description = 'Created from API Skill blank document.',
+  environmentName = '',
+  environmentBaseUrl = '',
+} = {}) {
+  const document = createManualDocument(text(title) || 'API Skill Document', text(version) || '1.0.0', text(description));
+  const savedAt = new Date();
+  const versionId = `${formatVersionDate(savedAt)}-document-${slugify(document.info?.title || 'api-skill-document')}`;
+  return writeVersion(document, {
+    versionId,
+    mode: 'document',
+    inputUrl: 'manual-document',
+    resolvedUrl: 'manual-document',
+    title: document.info?.title || '',
+    version: document.info?.version || '',
+    environmentName: text(environmentName).slice(0, 80),
+    environmentBaseUrl: text(environmentBaseUrl),
+    savedAt: savedAt.toISOString(),
+  });
+}
+
+export async function saveManualOperation({ versionId, config, replaceTarget }) {
+  const normalized = normalizeManualConfig(config);
+  const existing = versionId ? await readCachedDocument(versionId) : undefined;
+  let document = existing?.document ?? createManualDocument();
+  if (replaceTarget?.method && replaceTarget?.path) {
+    document = deleteOperation(document, replaceTarget.method, replaceTarget.path);
+  }
+  document = applyOperation(document, normalized);
+  const savedAt = new Date();
+  const nextVersionId = existing?.meta?.versionId || `${formatVersionDate(savedAt)}-manual-${slugify(normalized.operationId || normalized.summary || normalized.path)}`;
+  return writeVersion(document, {
+    ...(existing?.meta ?? {}),
+    versionId: nextVersionId,
+    mode: existing?.meta?.mode || 'manual',
+    inputUrl: existing?.meta?.inputUrl || 'manual-api-config',
+    resolvedUrl: existing?.meta?.resolvedUrl || 'manual-api-config',
+    title: document.info?.title || 'Manual API Config',
+    version: document.info?.version || 'manual',
+    savedAt: savedAt.toISOString(),
+  });
+}
+
+export async function deleteManualOperation({ versionId, method, path }) {
+  const existing = await readCachedDocument(required(versionId, '必须指定 --version'));
+  const document = deleteOperation(existing.document, method, path);
+  return writeVersion(document, {
+    ...existing.meta,
+    savedAt: new Date().toISOString(),
+  });
+}
+
+export function parseManualCliText(text) {
+  const cleaned = stripFence(required(text, 'API 配置不能为空'));
+  let parsed;
+  try {
+    parsed = JSON.parse(cleaned);
+  } catch {
+    parsed = parseYaml(cleaned);
+  }
+  const record = parsed && typeof parsed === 'object' ? parsed : {};
+  return normalizeManualConfig(record.api ?? record.config ?? record.operation ?? parsed);
+}
+
+export function formatManualCli(config) {
+  return JSON.stringify({ api: normalizeManualConfig(config) });
+}
+
+export function listEndpoints(document) {
+  return Object.entries(document.paths ?? {})
+    .flatMap(([path, item]) =>
+      METHODS.flatMap((method) => {
+        const operation = item?.[method];
+        if (!operation) return [];
+        const tags = operation.tags?.length ? operation.tags : ['未分组'];
+        const summary = operation.summary || operation.description || '未命名接口';
+        const params = operation.parameters ?? [];
+        const searchable = [
+          method,
+          path,
+          summary,
+          operation.description,
+          operation.operationId,
+          tags.join(' '),
+          params.map((parameter) => `${parameter.name} ${parameter.description ?? ''} ${parameter.schema?.description ?? ''}`).join(' '),
+        ]
+          .filter(Boolean)
+          .join(' ')
+          .toLowerCase();
+        return [{ method, path, operation, tags, summary, searchable, hasBody: Boolean(operation.requestBody) }];
+      }),
+    )
+    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+}
+
+export function findEndpoint(document, method, path) {
+  return listEndpoints(document).find((endpoint) => endpoint.method === String(method).toLowerCase() && endpoint.path === path);
+}
+
+export function endpointToManualConfig(endpoint, document = {}) {
+  const operation = endpoint.operation;
+  return normalizeManualConfig({
+    method: endpoint.method,
+    path: endpoint.path,
+    summary: endpoint.summary,
+    description: operation.description || '',
+    operationId: operation.operationId || '',
+    tags: operation.tags || [],
+    parameters: (operation.parameters ?? [])
+      .filter((parameter) => parameter.in !== 'body' && parameter.in !== 'formData')
+        .map((parameter) => ({
+        name: parameter.name,
+        location: parameter.in,
+        required: Boolean(parameter.required),
+        type: schemaType(parameter.schema ?? parameter),
+        format: schemaFormat(parameter.schema ?? parameter),
+        description: parameter.description || parameter.schema?.description || '',
+        enumValue: parameter.enum?.join(',') || parameter.schema?.enum?.join(',') || '',
+      }))
+      .sort(compareFields),
+    requestBody: requestBodyConfig(operation, document),
+    responses: Object.entries(operation.responses ?? {}).map(([status, response]) => responseConfig(status, response, document)),
+  });
+}
+
+function requestBodyConfig(operation, document) {
+  const entry = Object.entries(operation.requestBody?.content ?? {})[0];
+  const bodyParameter = operation.parameters?.find((parameter) => parameter.in === 'body');
+  if (entry) {
+    return {
+      required: Boolean(operation.requestBody?.required),
+      contentType: entry[0],
+      fields: schemaToFields(entry[1].schema, document),
+    };
+  }
+  if (bodyParameter?.schema) {
+    return { required: Boolean(bodyParameter.required), contentType: operation.consumes?.[0] || 'application/json', fields: schemaToFields(bodyParameter.schema, document) };
+  }
+  return { required: false, contentType: 'application/json', fields: [] };
+}
+
+function responseConfig(status, response, document) {
+  const entry = Object.entries(response.content ?? {})[0];
+  const schema = entry?.[1]?.schema ?? response.schema ?? response.responseSchema;
+  return {
+    status,
+    description: response.description || '',
+    contentType: entry?.[0] || 'application/json',
+    fields: schemaToFields(schema, document),
+  };
+}
+
+function schemaToFields(schema, document = {}, prefix = '', seen = new Set()) {
+  if (!schema) return [];
+  const resolved = resolveSchema(document, schema, seen) ?? schema;
+  if (resolved.type === 'array') return schemaToFields(resolved.items, document, prefix, seen);
+  const properties = resolved.properties ?? {};
+  return Object.entries(properties)
+    .sort(([left], [right]) => left.localeCompare(right, undefined, { sensitivity: 'base' }))
+    .map(([name, property]) => ({
+      name: prefix ? `${prefix}.${name}` : name,
+      location: 'body',
+      required: resolved.required?.includes(name) ?? false,
+      type: schemaType(resolveSchema(document, property) ?? property),
+      format: schemaFormat(resolveSchema(document, property) ?? property),
+      description: property.description || (resolveSchema(document, property) ?? property).description || '',
+      defaultValue: formatValue((resolveSchema(document, property) ?? property).default),
+      enumValue: ((resolveSchema(document, property) ?? property).enum ?? property.enum)?.join(',') || '',
+      children: hasChildren(document, property) ? schemaToFields(childSchema(document, property), document, '', new Set(seen)).sort(compareFields) : [],
+    }))
+    .sort(compareFields);
+}
+
+function schemaType(schema = {}) {
+  if (schema.$ref) return 'object';
+  if (schema.type) return schema.type;
+  if (schema.properties) return 'object';
+  return 'string';
+}
+
+function schemaFormat(schema = {}) {
+  if (schema.type === 'array' && schema.items?.$ref) return `[]*${schema.items.$ref.split('/').pop()}`;
+  return schema.format || '';
+}
+
+function hasChildren(document, schema) {
+  const resolved = resolveSchema(document, schema) ?? schema;
+  if (resolved.type === 'array') return Boolean(resolveSchema(document, resolved.items)?.properties || resolved.items?.properties);
+  return Boolean(resolved.properties);
+}
+
+function childSchema(document, schema) {
+  const resolved = resolveSchema(document, schema) ?? schema;
+  if (resolved.type === 'array') return resolved.items;
+  return resolved;
+}
+
+function resolveSchema(document, schema, seen = new Set()) {
+  if (!schema || typeof schema !== 'object') return undefined;
+  if (schema.$ref) {
+    if (seen.has(schema.$ref)) return schema;
+    seen.add(schema.$ref);
+    const resolved = schema.$ref
+      .slice(2)
+      .split('/')
+      .reduce((current, key) => (current && typeof current === 'object' ? current[decodeURIComponent(key)] : undefined), document);
+    const next = resolveSchema(document, resolved, seen) ?? resolved;
+    return { ...next, description: schema.description || next?.description };
+  }
+  if (Array.isArray(schema.allOf)) {
+    return schema.allOf.reduce(
+      (merged, item) => {
+        const next = resolveSchema(document, item, seen) ?? item;
+        return {
+          ...merged,
+          ...next,
+          required: [...new Set([...(merged.required ?? []), ...(next.required ?? [])])],
+          properties: { ...(merged.properties ?? {}), ...(next.properties ?? {}) },
+          description: [merged.description, next.description].filter(Boolean).join('；') || undefined,
+        };
+      },
+      { ...schema, allOf: undefined },
+    );
+  }
+  return schema;
+}
+
+function normalizeManualConfig(input) {
+  if (!input || typeof input !== 'object') throw new Error('接口配置不能为空');
+  const method = String(input.method || '').toLowerCase();
+  if (!METHODS.includes(method)) throw new Error('method 必须是有效 HTTP 方法');
+  const path = normalizePath(required(input.path, 'path 不能为空'));
+  const summary = required(input.summary, 'summary 不能为空');
+  const requestBody = input.requestBody && typeof input.requestBody === 'object' ? input.requestBody : {};
+  const responses = Array.isArray(input.responses) ? input.responses.map(normalizeResponse).filter((item) => item.status) : [];
+  return {
+    method,
+    path,
+    summary,
+    description: text(input.description),
+    operationId: text(input.operationId),
+    tags: Array.isArray(input.tags) ? input.tags.map(text).filter(Boolean) : text(input.tags).split(',').map((item) => item.trim()).filter(Boolean),
+    parameters: Array.isArray(input.parameters) ? input.parameters.map(normalizeField).filter((item) => item.name) : [],
+    requestBody: {
+      required: Boolean(requestBody.required),
+      contentType: text(requestBody.contentType) || 'application/json',
+      fields: Array.isArray(requestBody.fields) ? requestBody.fields.map(normalizeField).filter((item) => item.name).sort(compareFields) : [],
+    },
+    responses: (responses.length ? responses : [{ status: '200', description: 'Success', contentType: 'application/json', fields: [] }]).map((response) => ({
+      ...response,
+      fields: [...(response.fields ?? [])].sort(compareFields),
+    })),
+  };
+}
+
+function applyOperation(document, config) {
+  const next = clone(document);
+  next.paths ??= {};
+  next.paths[config.path] ??= {};
+  next.paths[config.path][config.method] = {
+    tags: config.tags?.length ? config.tags : ['手动配置'],
+    summary: config.summary,
+    description: config.description || undefined,
+    operationId: config.operationId || undefined,
+    parameters: (config.parameters ?? []).map(fieldToParameter),
+    responses: Object.fromEntries((config.responses ?? []).map((response) => [response.status, responseToOpenApi(response)])),
+  };
+  if (config.requestBody?.fields?.length) {
+    next.paths[config.path][config.method].requestBody = {
+      required: Boolean(config.requestBody.required),
+      content: {
+        [config.requestBody.contentType || 'application/json']: { schema: fieldsToSchema(config.requestBody.fields) },
+      },
+    };
+  }
+  return next;
+}
+
+function deleteOperation(document, method, path) {
+  const next = clone(document);
+  const normalizedPath = normalizePath(path);
+  const normalizedMethod = String(method || '').toLowerCase();
+  delete next.paths?.[normalizedPath]?.[normalizedMethod];
+  if (next.paths?.[normalizedPath] && !Object.keys(next.paths[normalizedPath]).length) delete next.paths[normalizedPath];
+  return next;
+}
+
+function createManualDocument(title = 'Manual API Config', version = 'manual', description = '') {
+  return {
+    openapi: '3.0.3',
+    info: {
+      title,
+      version,
+      ...(description ? { description } : {}),
+    },
+    paths: {},
+    components: { schemas: {} },
+  };
+}
+
+function fieldToParameter(field) {
+  return { name: field.name, in: field.location || 'query', required: Boolean(field.required), description: field.description || undefined, schema: fieldToSchema(field) };
+}
+
+function responseToOpenApi(response) {
+  const value = { description: response.description || 'Success' };
+  if (response.fields?.length) value.content = { [response.contentType || 'application/json']: { schema: fieldsToSchema(response.fields) } };
+  return value;
+}
+
+function fieldsToSchema(fields) {
+  const schema = { type: 'object', properties: {}, required: [] };
+  for (const field of fields ?? []) {
+    setSchemaProperty(schema, field.name, fieldToSchema(field), Boolean(field.required));
+  }
+  if (!schema.required.length) delete schema.required;
+  return schema;
+}
+
+function setSchemaProperty(root, path, schema, required) {
+  const parts = String(path || '').split('.').map((part) => part.trim()).filter(Boolean);
+  if (!parts.length) return;
+  let current = root;
+  parts.forEach((part, index) => {
+    current.properties ??= {};
+    if (index === parts.length - 1) {
+      current.properties[part] = schema;
+      if (required) current.required = [...new Set([...(current.required ?? []), part])];
+      return;
+    }
+    current.properties[part] ??= { type: 'object', properties: {}, required: [] };
+    current = current.properties[part];
+  });
+}
+
+function fieldToSchema(field) {
+  const schema = { type: field.type || 'string', format: field.format || undefined, description: field.description || undefined };
+  if (field.enumValue) schema.enum = field.enumValue.split(',').map((item) => item.trim()).filter(Boolean);
+  if (field.type === 'object') {
+    const child = fieldsToSchema(field.children ?? []);
+    schema.properties = child.properties;
+    schema.required = child.required;
+  }
+  if (field.type === 'array') schema.items = field.children?.length ? fieldsToSchema(field.children) : { type: 'string' };
+  return schema;
+}
+
+function normalizeResponse(input) {
+  return { status: text(input.status) || '200', description: text(input.description), contentType: text(input.contentType) || 'application/json', fields: Array.isArray(input.fields) ? input.fields.map(normalizeField).filter((item) => item.name) : [] };
+}
+
+function normalizeField(input) {
+  const location = text(input.location);
+  return {
+    name: text(input.name),
+    location: ['query', 'path', 'header', 'cookie', 'body'].includes(location) ? location : 'query',
+    required: Boolean(input.required),
+    type: text(input.type) || 'string',
+    format: text(input.format),
+    description: text(input.description),
+    defaultValue: text(input.defaultValue),
+    enumValue: text(input.enumValue),
+    children: Array.isArray(input.children) ? input.children.map(normalizeField).filter((item) => item.name).sort(compareFields) : [],
+  };
+}
+
+function compareFields(left, right) {
+  return String(left.name || '').localeCompare(String(right.name || ''), undefined, { sensitivity: 'base' });
+}
+
+async function writeVersion(document, metaInput) {
+  const stats = { paths: Object.keys(document.paths ?? {}).length, schemas: Object.keys(document.components?.schemas ?? document.definitions ?? {}).length };
+  const versionPath = metaInput.savedPath || resolve(versionsDir, `${metaInput.versionId}.json`);
+  const meta = { ...metaInput, ...stats, savedFile: basename(versionPath), savedPath: versionPath };
+  await mkdir(dirname(versionPath), { recursive: true });
+  await writeFile(versionPath, JSON.stringify(document, null, 2));
+  await writeFile(resolve(versionsDir, `${meta.versionId}.meta.json`), JSON.stringify(meta, null, 2));
+  await writeFile(latestMetaPath, JSON.stringify(meta, null, 2));
+  return { document, meta };
+}
+
+function assertSafeVersionId(versionId) {
+  if (!/^[a-zA-Z0-9_.-]+$/.test(versionId)) throw new Error('versionId 不合法');
+}
+
+function formatVersionDate(value) {
+  return value.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
+function sourceName(value) {
+  try {
+    return new URL(value).hostname || value;
+  } catch {
+    return value;
+  }
+}
+
+function slugify(value) {
+  return String(value || 'openapi').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'openapi';
+}
+
+function normalizePath(value) {
+  return value.startsWith('/') ? value : `/${value}`;
+}
+
+function required(value, message) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(message);
+  return value.trim();
+}
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function formatValue(value) {
+  if (value === undefined || value === null) return '';
+  return typeof value === 'string' ? value : JSON.stringify(value);
+}
+
+function stripFence(value) {
+  return value.trim().replace(/^```(?:json|ya?ml|yaml)?\s*/i, '').replace(/```$/i, '').trim();
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value || createManualDocument()));
+}