@skill-tools/gen 0.2.0

package/dist/chunk-EMDMG3H6.js

@@ -0,0 +1,609 @@
+// src/openapi.ts
+import YAML from "yaml";
+function parseOpenApi(content) {
+  const MAX_SPEC_SIZE = 1e7;
+  if (content.length > MAX_SPEC_SIZE) {
+    throw new Error(`OpenAPI spec exceeds maximum size (${MAX_SPEC_SIZE} bytes)`);
+  }
+  const doc = parseDocument(content);
+  const version = doc.openapi;
+  if (!version || !version.startsWith("3.")) {
+    throw new Error(
+      `Unsupported OpenAPI version: ${version ?? "unknown"}. Only OpenAPI 3.x is supported.`
+    );
+  }
+  const title = doc.info?.title ?? "Untitled API";
+  const description = doc.info?.description ?? "";
+  const apiVersion = doc.info?.version ?? "0.0.0";
+  const servers = extractServers(doc);
+  const auth = extractAuthSchemes(doc);
+  const endpoints = extractEndpoints(doc);
+  return {
+    title,
+    description,
+    version: apiVersion,
+    servers,
+    auth,
+    endpoints
+  };
+}
+function parseDocument(content) {
+  const trimmed = content.trim();
+  if (trimmed.startsWith("{")) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+    }
+  }
+  return YAML.parse(content);
+}
+function resolveRef(doc, ref) {
+  if (!ref.startsWith("#/")) {
+    return {};
+  }
+  const path = ref.slice(2).split("/");
+  let current = doc;
+  for (const segment of path) {
+    if (current == null || typeof current !== "object") return {};
+    current = current[segment];
+  }
+  return current ?? {};
+}
+function deref(doc, obj) {
+  if (typeof obj.$ref === "string") {
+    return resolveRef(doc, obj.$ref);
+  }
+  return obj;
+}
+function extractServers(doc) {
+  const servers = doc.servers;
+  if (!Array.isArray(servers)) return [];
+  return servers.map((s) => s.url).filter(Boolean);
+}
+function extractAuthSchemes(doc) {
+  const components = doc.components;
+  const schemes = components?.securitySchemes;
+  if (!schemes) return [];
+  return Object.entries(schemes).map(([name, raw]) => {
+    const scheme = deref(doc, raw);
+    return {
+      type: scheme.type ?? "apiKey",
+      name,
+      description: scheme.description,
+      in: scheme.in,
+      scheme: scheme.scheme
+    };
+  });
+}
+function extractEndpoints(doc) {
+  const paths = doc.paths;
+  if (!paths) return [];
+  const endpoints = [];
+  const httpMethods = ["get", "post", "put", "patch", "delete", "head", "options"];
+  for (const [path, pathItem] of Object.entries(paths)) {
+    const resolved = deref(doc, pathItem);
+    const pathParams = Array.isArray(resolved.parameters) ? resolved.parameters.map((p) => extractParameter(doc, p)) : [];
+    for (const method of httpMethods) {
+      const operation = resolved[method];
+      if (!operation) continue;
+      const opParams = Array.isArray(operation.parameters) ? operation.parameters.map((p) => extractParameter(doc, p)) : [];
+      const paramMap = /* @__PURE__ */ new Map();
+      for (const p of pathParams) paramMap.set(`${p.in}:${p.name}`, p);
+      for (const p of opParams) paramMap.set(`${p.in}:${p.name}`, p);
+      const requestBody = operation.requestBody ? extractRequestBody(doc, deref(doc, operation.requestBody)) : void 0;
+      const responses = extractResponses(
+        doc,
+        operation.responses
+      );
+      endpoints.push({
+        method: method.toUpperCase(),
+        path,
+        operationId: operation.operationId,
+        summary: operation.summary,
+        description: operation.description,
+        tags: Array.isArray(operation.tags) ? operation.tags : [],
+        parameters: Array.from(paramMap.values()),
+        requestBody,
+        responses
+      });
+    }
+  }
+  return endpoints;
+}
+function extractParameter(doc, raw) {
+  const param = deref(doc, raw);
+  const schema = param.schema ? deref(doc, param.schema) : {};
+  return {
+    name: param.name ?? "",
+    in: param.in ?? "query",
+    description: param.description,
+    required: param.required ?? false,
+    type: schema.type,
+    example: param.example
+  };
+}
+function extractRequestBody(doc, body) {
+  const content = body.content;
+  if (!content) return void 0;
+  const contentType = "application/json" in content ? "application/json" : Object.keys(content)[0];
+  if (!contentType) return void 0;
+  const mediaType = content[contentType];
+  if (!mediaType) return void 0;
+  const schema = mediaType.schema ? deref(doc, mediaType.schema) : {};
+  return {
+    description: body.description,
+    contentType,
+    required: body.required ?? false,
+    properties: extractProperties(doc, schema),
+    example: mediaType.example ?? schema.example
+  };
+}
+function extractProperties(doc, schema) {
+  const properties = schema.properties;
+  if (!properties) return [];
+  const requiredFields = new Set(
+    Array.isArray(schema.required) ? schema.required : []
+  );
+  return Object.entries(properties).map(([name, raw]) => {
+    const prop = deref(doc, raw);
+    return {
+      name,
+      type: prop.type ?? "unknown",
+      description: prop.description,
+      required: requiredFields.has(name),
+      example: prop.example
+    };
+  });
+}
+function extractResponses(doc, responses) {
+  if (!responses) return [];
+  return Object.entries(responses).map(([statusCode, raw]) => {
+    const response = deref(doc, raw);
+    const content = response.content;
+    let contentType;
+    let properties = [];
+    if (content) {
+      contentType = "application/json" in content ? "application/json" : Object.keys(content)[0];
+      if (contentType && content[contentType]) {
+        const mediaType = content[contentType];
+        const schema = mediaType.schema ? deref(doc, mediaType.schema) : {};
+        properties = extractProperties(doc, schema);
+      }
+    }
+    return {
+      statusCode,
+      description: response.description,
+      contentType,
+      properties
+    };
+  });
+}
+
+// src/renderer.ts
+function renderSkillMd(spec, options = {}) {
+  const mode = options.mode ?? "unified";
+  const files = /* @__PURE__ */ new Map();
+  if (mode === "unified") {
+    const name = options.name ?? toKebabCase(spec.title);
+    const content = renderUnified(spec, { ...options, name });
+    files.set(`${name}/SKILL.md`, content);
+  } else {
+    for (const endpoint of spec.endpoints) {
+      const epName = endpoint.operationId ? toKebabCase(endpoint.operationId) : toKebabCase(`${endpoint.method}-${endpoint.path}`);
+      const content = renderSingleEndpoint(spec, endpoint, {
+        ...options,
+        name: epName
+      });
+      files.set(`${epName}/SKILL.md`, content);
+    }
+  }
+  return files;
+}
+function renderUnified(spec, options) {
+  const lines = [];
+  lines.push("---");
+  lines.push(`name: ${options.name}`);
+  lines.push(`description: >-`, `  ${options.description ?? buildUnifiedDescription(spec)}`);
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${spec.title}`);
+  lines.push("");
+  if (spec.description) {
+    lines.push(spec.description);
+    lines.push("");
+  }
+  if (spec.servers.length > 0) {
+    lines.push("## Base URL");
+    lines.push("");
+    for (const server of spec.servers) {
+      lines.push(`- \`${server}\``);
+    }
+    lines.push("");
+  }
+  if (spec.auth.length > 0) {
+    lines.push("## Authentication");
+    lines.push("");
+    lines.push(renderAuth(spec.auth));
+    lines.push("");
+  }
+  lines.push("## Endpoints");
+  lines.push("");
+  const grouped = groupByTag(spec.endpoints);
+  for (const [tag, endpoints] of grouped) {
+    if (tag !== "_untagged") {
+      lines.push(`### ${tag}`);
+      lines.push("");
+    }
+    for (const ep of endpoints) {
+      lines.push(renderEndpointSection(ep));
+      lines.push("");
+    }
+  }
+  if (options.includeErrorHandling !== false) {
+    lines.push("## Error Handling");
+    lines.push("");
+    lines.push(renderErrorHandling(spec));
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderSingleEndpoint(spec, endpoint, options) {
+  const lines = [];
+  const summary = endpoint.summary ?? endpoint.description ?? `${endpoint.method} ${endpoint.path}`;
+  lines.push("---");
+  lines.push(`name: ${options.name}`);
+  lines.push(
+    `description: >-`,
+    `  ${options.description ?? `Use when the user wants to ${summary.toLowerCase()}. Calls ${endpoint.method} ${endpoint.path}.`}`
+  );
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${summary}`);
+  lines.push("");
+  if (endpoint.description && endpoint.description !== endpoint.summary) {
+    lines.push(endpoint.description);
+    lines.push("");
+  }
+  if (spec.servers.length > 0) {
+    lines.push(`**Base URL:** \`${spec.servers[0]}\``);
+    lines.push("");
+  }
+  if (spec.auth.length > 0) {
+    lines.push("## Authentication");
+    lines.push("");
+    lines.push(renderAuth(spec.auth));
+    lines.push("");
+  }
+  lines.push(`## ${endpoint.method} \`${endpoint.path}\``);
+  lines.push("");
+  if (endpoint.parameters.length > 0) {
+    lines.push("### Parameters");
+    lines.push("");
+    lines.push(renderParametersTable(endpoint));
+    lines.push("");
+  }
+  if (endpoint.requestBody) {
+    lines.push("### Request Body");
+    lines.push("");
+    lines.push(renderRequestBody(endpoint.requestBody, options));
+    lines.push("");
+  }
+  if (endpoint.responses.length > 0) {
+    lines.push("### Responses");
+    lines.push("");
+    lines.push(renderResponses(endpoint));
+    lines.push("");
+  }
+  if (options.includeExamples !== false) {
+    lines.push("## Example");
+    lines.push("");
+    lines.push(renderExample(spec, endpoint));
+    lines.push("");
+  }
+  if (options.includeErrorHandling !== false) {
+    lines.push("## Error Handling");
+    lines.push("");
+    lines.push(renderEndpointErrorHandling(endpoint));
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function buildUnifiedDescription(spec) {
+  const endpointCount = spec.endpoints.length;
+  const methods = new Set(spec.endpoints.map((e) => e.method));
+  const methodList = Array.from(methods).join(", ");
+  if (spec.description) {
+    return `${spec.description.split(".")[0]}. Use when working with the ${spec.title} (${endpointCount} endpoints, ${methodList}).`;
+  }
+  return `Interact with the ${spec.title}. Use when the user needs to call any of the ${endpointCount} available endpoints (${methodList}).`;
+}
+function renderAuth(auth) {
+  const lines = [];
+  for (const scheme of auth) {
+    switch (scheme.type) {
+      case "http":
+        if (scheme.scheme === "bearer") {
+          lines.push("Use Bearer token authentication:");
+          lines.push("```");
+          lines.push("Authorization: Bearer <token>");
+          lines.push("```");
+        } else if (scheme.scheme === "basic") {
+          lines.push("Use HTTP Basic authentication:");
+          lines.push("```");
+          lines.push("Authorization: Basic <base64(username:password)>");
+          lines.push("```");
+        }
+        break;
+      case "apiKey":
+        lines.push(`Pass the API key via ${scheme.in ?? "header"}:`);
+        lines.push("```");
+        lines.push(`${scheme.name}: <api-key>`);
+        lines.push("```");
+        break;
+      case "oauth2":
+        lines.push("Uses OAuth 2.0 authentication. Obtain an access token first.");
+        break;
+      default:
+        if (scheme.description) {
+          lines.push(scheme.description);
+        }
+    }
+  }
+  return lines.join("\n");
+}
+function groupByTag(endpoints) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const ep of endpoints) {
+    const tag = ep.tags.length > 0 ? ep.tags[0] : "_untagged";
+    const list = grouped.get(tag) ?? [];
+    list.push(ep);
+    grouped.set(tag, list);
+  }
+  return grouped;
+}
+function renderEndpointSection(ep) {
+  const lines = [];
+  const heading = ep.summary ?? `${ep.method} ${ep.path}`;
+  lines.push(`#### ${ep.method} \`${ep.path}\` \u2014 ${heading}`);
+  lines.push("");
+  if (ep.description && ep.description !== ep.summary) {
+    lines.push(ep.description);
+    lines.push("");
+  }
+  if (ep.parameters.length > 0) {
+    lines.push(renderParametersTable(ep));
+    lines.push("");
+  }
+  if (ep.requestBody) {
+    lines.push(`**Request body** (\`${ep.requestBody.contentType}\`):`);
+    lines.push("");
+    lines.push(renderPropertiesTable(ep.requestBody.properties));
+    lines.push("");
+  }
+  const successResponse = ep.responses.find((r) => r.statusCode.startsWith("2"));
+  if (successResponse) {
+    lines.push(
+      `**Response:** ${successResponse.statusCode} \u2014 ${successResponse.description ?? "Success"}`
+    );
+  }
+  return lines.join("\n");
+}
+function renderParametersTable(ep) {
+  const lines = [];
+  lines.push("| Parameter | In | Type | Required | Description |");
+  lines.push("|-----------|-----|------|----------|-------------|");
+  for (const param of ep.parameters) {
+    const req = param.required ? "Yes" : "No";
+    const desc = param.description ?? "";
+    lines.push(`| \`${param.name}\` | ${param.in} | ${param.type ?? "-"} | ${req} | ${desc} |`);
+  }
+  return lines.join("\n");
+}
+function renderPropertiesTable(properties) {
+  if (properties.length === 0) return "";
+  const lines = [];
+  lines.push("| Property | Type | Required | Description |");
+  lines.push("|----------|------|----------|-------------|");
+  for (const prop of properties) {
+    const req = prop.required ? "Yes" : "No";
+    const desc = prop.description ?? "";
+    lines.push(`| \`${prop.name}\` | ${prop.type} | ${req} | ${desc} |`);
+  }
+  return lines.join("\n");
+}
+function renderRequestBody(body, options) {
+  const lines = [];
+  if (body.description) {
+    lines.push(body.description);
+    lines.push("");
+  }
+  lines.push(`Content-Type: \`${body.contentType}\``);
+  lines.push("");
+  if (body.properties.length > 0) {
+    lines.push(renderPropertiesTable(body.properties));
+  }
+  if (options.includeExamples !== false && body.example) {
+    lines.push("");
+    lines.push("**Example:**");
+    lines.push("```json");
+    lines.push(JSON.stringify(body.example, null, 2));
+    lines.push("```");
+  }
+  return lines.join("\n");
+}
+function renderResponses(ep) {
+  const lines = [];
+  for (const resp of ep.responses) {
+    lines.push(`**${resp.statusCode}** \u2014 ${resp.description ?? ""}`);
+    if (resp.properties.length > 0) {
+      lines.push("");
+      lines.push(renderPropertiesTable(resp.properties));
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderExample(spec, ep) {
+  const baseUrl = spec.servers[0] ?? "https://api.example.com";
+  const lines = [];
+  lines.push("```bash");
+  lines.push(`curl -X ${ep.method} "${baseUrl}${ep.path}" \\`);
+  if (spec.auth.length > 0) {
+    const authScheme = spec.auth[0];
+    if (authScheme.type === "http" && authScheme.scheme === "bearer") {
+      lines.push('  -H "Authorization: Bearer $TOKEN" \\');
+    } else if (authScheme.type === "apiKey") {
+      lines.push(`  -H "${authScheme.name}: $API_KEY" \\`);
+    }
+  }
+  lines.push('  -H "Content-Type: application/json"');
+  if (ep.requestBody?.example) {
+    lines.push(`  -d '${JSON.stringify(ep.requestBody.example)}'`);
+  }
+  lines.push("```");
+  return lines.join("\n");
+}
+function renderErrorHandling(spec) {
+  const errorCodes = /* @__PURE__ */ new Set();
+  for (const ep of spec.endpoints) {
+    for (const resp of ep.responses) {
+      if (resp.statusCode.startsWith("4") || resp.statusCode.startsWith("5")) {
+        errorCodes.add(resp.statusCode);
+      }
+    }
+  }
+  const lines = [];
+  lines.push("Common error responses:");
+  lines.push("");
+  if (errorCodes.size === 0) {
+    lines.push("- **4xx**: Client error \u2014 check request parameters and authentication");
+    lines.push("- **5xx**: Server error \u2014 retry with exponential backoff");
+  } else {
+    for (const code of Array.from(errorCodes).sort()) {
+      lines.push(`- **${code}**: ${httpStatusDescription(code)}`);
+    }
+  }
+  lines.push("");
+  lines.push("When an error occurs:");
+  lines.push("1. Check the response body for a detailed error message");
+  lines.push("2. Verify authentication credentials are valid");
+  lines.push("3. For 429 (rate limit), wait and retry with exponential backoff");
+  lines.push("4. For 5xx errors, retry up to 3 times with backoff");
+  return lines.join("\n");
+}
+function renderEndpointErrorHandling(ep) {
+  const errorResponses = ep.responses.filter(
+    (r) => r.statusCode.startsWith("4") || r.statusCode.startsWith("5")
+  );
+  const lines = [];
+  if (errorResponses.length > 0) {
+    lines.push("Possible errors:");
+    lines.push("");
+    for (const resp of errorResponses) {
+      lines.push(
+        `- **${resp.statusCode}**: ${resp.description ?? httpStatusDescription(resp.statusCode)}`
+      );
+    }
+  } else {
+    lines.push("- Check authentication credentials if you receive a 401/403");
+    lines.push("- Validate request parameters for 400 errors");
+    lines.push("- Retry on 5xx with exponential backoff");
+  }
+  return lines.join("\n");
+}
+function httpStatusDescription(code) {
+  const descriptions = {
+    "400": "Bad Request \u2014 check request parameters",
+    "401": "Unauthorized \u2014 check authentication",
+    "403": "Forbidden \u2014 insufficient permissions",
+    "404": "Not Found \u2014 resource does not exist",
+    "405": "Method Not Allowed",
+    "409": "Conflict \u2014 resource state conflict",
+    "422": "Unprocessable Entity \u2014 validation error",
+    "429": "Too Many Requests \u2014 rate limited, retry after backoff",
+    "500": "Internal Server Error \u2014 retry with backoff",
+    "502": "Bad Gateway \u2014 upstream service error",
+    "503": "Service Unavailable \u2014 retry later"
+  };
+  return descriptions[code] ?? `HTTP ${code} error`;
+}
+function toKebabCase(input) {
+  return input.replace(/[^a-zA-Z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/([a-z])([A-Z])/g, "$1-$2").replace(/-+/g, "-").toLowerCase().replace(/^-|-$/g, "").slice(0, 64);
+}
+
+// src/generator.ts
+import { readFile } from "fs/promises";
+import { countTokens } from "@skill-tools/core";
+async function generateFromOpenApi(specPath, options = {}) {
+  try {
+    const content = await readFile(specPath, "utf-8");
+    const spec = parseOpenApi(content);
+    return generateFromSpec(spec, options);
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function generateFromSpec(spec, options = {}) {
+  try {
+    const files = renderSkillMd(spec, options);
+    let totalTokens = 0;
+    for (const content of files.values()) {
+      totalTokens += countTokens(content);
+    }
+    const maxTokens = options.maxTokens ?? 4e3;
+    if (options.mode !== "per-endpoint" && totalTokens > maxTokens) {
+    }
+    return {
+      ok: true,
+      files,
+      endpointCount: spec.endpoints.length,
+      tokenCount: totalTokens
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function generateFromText(name, description, instructions = "") {
+  const kebabName = name.replace(/[^a-zA-Z0-9\s-]/g, "").replace(/\s+/g, "-").toLowerCase().slice(0, 64);
+  const lines = [];
+  lines.push("---");
+  lines.push(`name: ${kebabName}`);
+  lines.push(`description: >-`);
+  lines.push(`  ${description}`);
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${name}`);
+  lines.push("");
+  lines.push(description);
+  lines.push("");
+  if (instructions) {
+    lines.push("## Instructions");
+    lines.push("");
+    lines.push(instructions);
+    lines.push("");
+  }
+  const content = lines.join("\n");
+  const files = /* @__PURE__ */ new Map();
+  files.set(`${kebabName}/SKILL.md`, content);
+  return {
+    ok: true,
+    files,
+    endpointCount: 0,
+    tokenCount: countTokens(content)
+  };
+}
+
+export {
+  parseOpenApi,
+  renderSkillMd,
+  generateFromOpenApi,
+  generateFromSpec,
+  generateFromText
+};
+//# sourceMappingURL=chunk-EMDMG3H6.js.map