@402md/skillmd 0.1.0

package/dist/index.js

@@ -0,0 +1,723 @@
+// src/parse.ts
+import YAML from "yaml";
+
+// src/constants.ts
+var SKILL_TYPES = [
+  "API",
+  "SAAS",
+  "PRODUCT",
+  "SERVICE",
+  "SUBSCRIPTION",
+  "CONTENT"
+];
+var HTTP_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH"
+];
+var PAYMENT_NETWORKS = [
+  "stellar",
+  "base",
+  "base-sepolia",
+  "stellar-testnet"
+];
+var SKILL_TYPES_SET = new Set(SKILL_TYPES);
+var HTTP_METHODS_SET = new Set(HTTP_METHODS);
+var PAYMENT_NETWORKS_SET = new Set(PAYMENT_NETWORKS);
+var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+// src/parse.ts
+function parseSkillMd(content) {
+  const { data, body } = extractFrontmatter(content);
+  return buildManifest(data, body);
+}
+function parseFrontmatter(md) {
+  const match = md.match(FRONTMATTER_RE);
+  if (!match) {
+    return { data: { name: "unknown" }, body: md };
+  }
+  const data = YAML.parse(match[1]);
+  return { data, body: match[2] };
+}
+function extractFrontmatter(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) {
+    throw new Error("Invalid SKILL.md: missing frontmatter delimiters (---)");
+  }
+  const data = YAML.parse(match[1]);
+  return { data, body: match[2].trim() };
+}
+function buildManifest(data, body) {
+  const name = requireString(data, "name");
+  const description = requireString(data, "description");
+  const base_url = requireString(data, "base_url");
+  const rawType = getString(data, "type") ?? "API";
+  const type = SKILL_TYPES_SET.has(rawType) ? rawType : "API";
+  const payment = parsePayment(data);
+  const endpoints = parseEndpoints(data);
+  return {
+    name,
+    displayName: getString(data, "displayName"),
+    description,
+    version: getString(data, "version"),
+    author: getString(data, "author"),
+    base_url,
+    type,
+    payment,
+    endpoints,
+    tags: getStringArray(data, "tags"),
+    category: getString(data, "category"),
+    sla: getString(data, "sla"),
+    rateLimit: getString(data, "rateLimit"),
+    sandbox: getString(data, "sandbox"),
+    body
+  };
+}
+function parsePayment(data) {
+  const raw = data.payment;
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const payment = raw;
+    const networks = parseNetworks(payment.networks);
+    return {
+      networks,
+      asset: getString(payment, "asset") ?? "USDC",
+      payTo: requireString(payment, "payTo"),
+      payToEvm: getString(payment, "payToEvm"),
+      facilitator: getString(payment, "facilitator")
+    };
+  }
+  return {
+    networks: ["base"],
+    asset: "USDC",
+    payTo: ""
+  };
+}
+function parseNetworks(raw) {
+  if (!Array.isArray(raw)) return ["base"];
+  return raw.filter((n) => typeof n === "string" && PAYMENT_NETWORKS_SET.has(n)).map((n) => n);
+}
+function parseEndpoints(data) {
+  const raw = data.endpoints;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((e) => e && typeof e === "object").map((e) => {
+    const ep = e;
+    const method = (getString(ep, "method") ?? "POST").toUpperCase();
+    return {
+      path: getString(ep, "path") ?? "/",
+      method: HTTP_METHODS_SET.has(method) ? method : "POST",
+      description: getString(ep, "description") ?? "",
+      priceUsdc: getString(ep, "priceUsdc") ?? getString(ep, "price") ?? "0",
+      inputSchema: getObject(ep, "inputSchema"),
+      outputSchema: getObject(ep, "outputSchema")
+    };
+  });
+}
+function requireString(obj, key) {
+  const val = obj[key];
+  if (typeof val === "string") return val;
+  if (typeof val === "number" || typeof val === "boolean") return String(val);
+  throw new Error(`Missing required field: ${key}`);
+}
+function getString(obj, key) {
+  const val = obj[key];
+  if (typeof val === "string") return val;
+  if (typeof val === "number" || typeof val === "boolean") return String(val);
+  return void 0;
+}
+function getStringArray(obj, key) {
+  const val = obj[key];
+  if (!Array.isArray(val)) return void 0;
+  return val.filter((v) => typeof v === "string");
+}
+function getObject(obj, key) {
+  const val = obj[key];
+  if (val && typeof val === "object" && !Array.isArray(val)) {
+    return val;
+  }
+  return void 0;
+}
+
+// src/validate.ts
+var NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
+var SEMVER_RE = /^\d+\.\d+\.\d+/;
+var PRICE_RE = /^\d+(\.\d+)?$/;
+var EVM_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
+var STELLAR_ADDRESS_RE = /^G[A-Z2-7]{55}$/;
+function validateSkill(manifest) {
+  const errors = [];
+  const warnings = [];
+  validateName(manifest.name, errors);
+  validateDescription(manifest.description, errors);
+  validateBaseUrl(manifest.base_url, errors);
+  validateType(manifest.type, errors);
+  validatePayment(manifest.payment, errors, warnings);
+  validateEndpoints(manifest.endpoints, errors, warnings);
+  validateVersion(manifest.version, warnings);
+  validateTags(manifest.tags, warnings);
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateSkillMd(content) {
+  try {
+    const manifest = parseSkillMd(content);
+    return validateSkill(manifest);
+  } catch (err) {
+    return {
+      valid: false,
+      errors: [
+        {
+          field: "frontmatter",
+          message: err instanceof Error ? err.message : "Failed to parse SKILL.md",
+          code: "PARSE_ERROR"
+        }
+      ],
+      warnings: []
+    };
+  }
+}
+function validateName(name, errors) {
+  if (!name) {
+    errors.push({
+      field: "name",
+      message: "Name is required",
+      code: "REQUIRED"
+    });
+    return;
+  }
+  if (!NAME_RE.test(name)) {
+    errors.push({
+      field: "name",
+      message: "Name must be kebab-case (lowercase letters, numbers, hyphens, underscores)",
+      code: "INVALID_FORMAT"
+    });
+  }
+  if (name.length > 100) {
+    errors.push({
+      field: "name",
+      message: "Name must be 100 characters or fewer",
+      code: "TOO_LONG"
+    });
+  }
+}
+function validateDescription(description, errors) {
+  if (!description) {
+    errors.push({
+      field: "description",
+      message: "Description is required",
+      code: "REQUIRED"
+    });
+  }
+  if (description && description.length > 2e3) {
+    errors.push({
+      field: "description",
+      message: "Description must be 2000 characters or fewer",
+      code: "TOO_LONG"
+    });
+  }
+}
+function validateBaseUrl(base_url, errors) {
+  if (!base_url) {
+    errors.push({
+      field: "base_url",
+      message: "base_url is required",
+      code: "REQUIRED"
+    });
+    return;
+  }
+  try {
+    new URL(base_url);
+  } catch {
+    errors.push({
+      field: "base_url",
+      message: "base_url must be a valid URL",
+      code: "INVALID_URL"
+    });
+  }
+}
+function validateType(type, errors) {
+  if (!SKILL_TYPES_SET.has(type)) {
+    errors.push({
+      field: "type",
+      message: `Invalid type "${type}". Must be one of: ${[...SKILL_TYPES_SET].join(", ")}`,
+      code: "INVALID_ENUM"
+    });
+  }
+}
+function validatePayment(payment, errors, warnings) {
+  if (!payment.networks || payment.networks.length === 0) {
+    errors.push({
+      field: "payment.networks",
+      message: "At least one payment network is required",
+      code: "REQUIRED"
+    });
+  } else {
+    for (const network of payment.networks) {
+      if (!PAYMENT_NETWORKS_SET.has(network)) {
+        errors.push({
+          field: "payment.networks",
+          message: `Invalid network "${network}". Must be one of: ${[...PAYMENT_NETWORKS_SET].join(", ")}`,
+          code: "INVALID_ENUM"
+        });
+      }
+    }
+  }
+  if (!payment.payTo) {
+    errors.push({
+      field: "payment.payTo",
+      message: "payTo address is required",
+      code: "REQUIRED"
+    });
+  } else {
+    const isEvm = EVM_ADDRESS_RE.test(payment.payTo);
+    const isStellar = STELLAR_ADDRESS_RE.test(payment.payTo);
+    if (!isEvm && !isStellar) {
+      warnings.push({
+        field: "payment.payTo",
+        message: "payTo does not look like a valid Stellar or EVM address",
+        code: "SUSPICIOUS_ADDRESS"
+      });
+    }
+  }
+  if (payment.payToEvm && !EVM_ADDRESS_RE.test(payment.payToEvm)) {
+    errors.push({
+      field: "payment.payToEvm",
+      message: "payToEvm must be a valid EVM address (0x...)",
+      code: "INVALID_FORMAT"
+    });
+  }
+  if (payment.facilitator) {
+    try {
+      new URL(payment.facilitator);
+    } catch {
+      errors.push({
+        field: "payment.facilitator",
+        message: "facilitator must be a valid URL",
+        code: "INVALID_URL"
+      });
+    }
+  }
+  if (!payment.asset) {
+    warnings.push({
+      field: "payment.asset",
+      message: "No asset specified, defaulting to USDC",
+      code: "MISSING_OPTIONAL"
+    });
+  }
+}
+function validateEndpoints(endpoints, errors, warnings) {
+  if (!endpoints || endpoints.length === 0) {
+    errors.push({
+      field: "endpoints",
+      message: "At least one endpoint is required",
+      code: "REQUIRED"
+    });
+    return;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (let i = 0; i < endpoints.length; i++) {
+    const ep = endpoints[i];
+    const prefix = `endpoints[${i}]`;
+    if (!ep.path || !ep.path.startsWith("/")) {
+      errors.push({
+        field: `${prefix}.path`,
+        message: "Endpoint path must start with /",
+        code: "INVALID_FORMAT"
+      });
+    }
+    if (!HTTP_METHODS_SET.has(ep.method)) {
+      errors.push({
+        field: `${prefix}.method`,
+        message: `Invalid method "${ep.method}"`,
+        code: "INVALID_ENUM"
+      });
+    }
+    if (!ep.description) {
+      warnings.push({
+        field: `${prefix}.description`,
+        message: "Endpoint is missing a description",
+        code: "MISSING_OPTIONAL"
+      });
+    }
+    if (!PRICE_RE.test(ep.priceUsdc)) {
+      errors.push({
+        field: `${prefix}.priceUsdc`,
+        message: `Invalid price "${ep.priceUsdc}". Must be a decimal string (e.g. "0.001")`,
+        code: "INVALID_FORMAT"
+      });
+    }
+    const key = `${ep.method} ${ep.path}`;
+    if (seen.has(key)) {
+      errors.push({
+        field: `${prefix}`,
+        message: `Duplicate endpoint: ${key}`,
+        code: "DUPLICATE"
+      });
+    }
+    seen.add(key);
+  }
+}
+function validateVersion(version, warnings) {
+  if (!version) {
+    warnings.push({
+      field: "version",
+      message: "No version specified",
+      code: "MISSING_OPTIONAL"
+    });
+    return;
+  }
+  if (!SEMVER_RE.test(version)) {
+    warnings.push({
+      field: "version",
+      message: 'Version should follow semver (e.g. "1.0.0")',
+      code: "INVALID_FORMAT"
+    });
+  }
+}
+function validateTags(tags, warnings) {
+  if (tags && tags.length > 20) {
+    warnings.push({
+      field: "tags",
+      message: "Too many tags (max 20)",
+      code: "TOO_MANY"
+    });
+  }
+}
+
+// src/generate.ts
+import YAML2 from "yaml";
+function generateSkillMd(config) {
+  const frontmatter = buildFrontmatter(config);
+  const yaml = YAML2.stringify(frontmatter, {
+    lineWidth: 0,
+    defaultStringType: "PLAIN",
+    defaultKeyType: "PLAIN"
+  }).trimEnd();
+  const body = config.body ?? generateDefaultBody(config.displayName ?? config.name, config.description);
+  return `---
+${yaml}
+---
+
+${body}
+`;
+}
+function generateFromOpenAPI(spec, payment, options) {
+  const baseUrl = options?.baseUrlOverride ?? spec.servers?.[0]?.url ?? "https://api.example.com";
+  const defaultPrice = options?.defaultPrice ?? "0.001";
+  const pricing = options?.pricing;
+  const endpoints = [];
+  for (const [path, methods] of Object.entries(spec.paths)) {
+    const methodEntries = [
+      ["GET", methods.get],
+      ["POST", methods.post],
+      ["PUT", methods.put],
+      ["DELETE", methods.delete],
+      ["PATCH", methods.patch]
+    ];
+    for (const [method, operation] of methodEntries) {
+      if (!operation) continue;
+      const inputSchema = extractInputSchema(operation);
+      const outputSchema = extractOutputSchema(operation);
+      endpoints.push({
+        path,
+        method,
+        description: operation.summary ?? operation.description ?? `${method} ${path}`,
+        priceUsdc: resolvePrice(method, path, pricing, defaultPrice),
+        ...inputSchema && { inputSchema },
+        ...outputSchema && { outputSchema }
+      });
+    }
+  }
+  return {
+    name: slugify(spec.info.title),
+    displayName: spec.info.title,
+    description: spec.info.description ?? spec.info.title,
+    version: spec.info.version,
+    base_url: baseUrl,
+    type: "API",
+    payment,
+    endpoints,
+    body: ""
+  };
+}
+function toOpenAPI(manifest) {
+  const paths = {};
+  for (const ep of manifest.endpoints) {
+    const method = ep.method.toLowerCase();
+    if (!paths[ep.path]) paths[ep.path] = {};
+    const operation = {
+      summary: ep.description,
+      operationId: `${manifest.name}_${method}_${ep.path.replace(/\//g, "_").replace(/^_/, "")}`
+    };
+    if (ep.inputSchema && ["post", "put", "patch"].includes(method)) {
+      operation.requestBody = {
+        content: {
+          "application/json": { schema: ep.inputSchema }
+        }
+      };
+    }
+    operation.responses = {
+      "200": {
+        description: "Successful response",
+        ...ep.outputSchema && {
+          content: {
+            "application/json": { schema: ep.outputSchema }
+          }
+        }
+      },
+      "402": {
+        description: `Payment Required \u2014 ${ep.priceUsdc} USDC`
+      }
+    };
+    paths[ep.path][method] = operation;
+  }
+  return {
+    openapi: "3.0.3",
+    info: {
+      title: manifest.displayName ?? manifest.name,
+      description: manifest.description,
+      version: manifest.version ?? "1.0.0"
+    },
+    servers: [{ url: manifest.base_url }],
+    paths
+  };
+}
+function buildFrontmatter(config) {
+  const fm = {
+    name: config.name
+  };
+  if (config.displayName) fm.displayName = config.displayName;
+  fm.description = config.description;
+  if (config.version) fm.version = config.version;
+  if (config.author) fm.author = config.author;
+  fm.base_url = config.base_url;
+  fm.type = config.type ?? "API";
+  fm.payment = {
+    networks: config.payment.networks,
+    asset: config.payment.asset || "USDC",
+    payTo: config.payment.payTo,
+    ...config.payment.payToEvm && {
+      payToEvm: config.payment.payToEvm
+    },
+    ...config.payment.facilitator && {
+      facilitator: config.payment.facilitator
+    }
+  };
+  fm.endpoints = config.endpoints.map((ep) => {
+    const entry = {
+      path: ep.path,
+      method: ep.method,
+      description: ep.description,
+      priceUsdc: ep.priceUsdc
+    };
+    if (ep.inputSchema) entry.inputSchema = ep.inputSchema;
+    if (ep.outputSchema) entry.outputSchema = ep.outputSchema;
+    return entry;
+  });
+  if (config.tags?.length) fm.tags = config.tags;
+  if (config.category) fm.category = config.category;
+  if (config.sla) fm.sla = config.sla;
+  if (config.rateLimit) fm.rateLimit = config.rateLimit;
+  if (config.sandbox) fm.sandbox = config.sandbox;
+  return fm;
+}
+function generateDefaultBody(name, description) {
+  return `# ${name}
+
+${description}`;
+}
+function extractInputSchema(op) {
+  const content = op.requestBody?.content;
+  if (!content) return void 0;
+  const json = content["application/json"] ?? Object.values(content)[0];
+  return json?.schema;
+}
+function extractOutputSchema(op) {
+  if (!op.responses) return void 0;
+  const successResponse = op.responses["200"] ?? op.responses["201"] ?? op.responses["2xx"];
+  if (!successResponse?.content) return void 0;
+  const json = successResponse.content["application/json"] ?? Object.values(successResponse.content)[0];
+  return json?.schema;
+}
+function resolvePrice(method, path, pricing, defaultPrice) {
+  if (!pricing) return defaultPrice;
+  return pricing[`${method} ${path}`] ?? pricing["*"] ?? defaultPrice;
+}
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+// src/mcp.ts
+function toMcpToolDefinitions(manifest) {
+  return manifest.endpoints.map((ep) => {
+    const slug = ep.path.replace(/^\//, "").replace(/\//g, "_").replace(/[^a-zA-Z0-9_-]/g, "");
+    const network = manifest.payment.networks[0] ?? "unknown";
+    return {
+      name: `${manifest.name}_${slug}`,
+      description: `${ep.description} (${ep.priceUsdc} USDC via ${network})`,
+      inputSchema: ep.inputSchema ?? { type: "object", properties: {} }
+    };
+  });
+}
+
+// src/schema.ts
+var SKILLMD_JSON_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  title: "SKILL.md Frontmatter",
+  description: "Schema for the YAML frontmatter in a SKILL.md file",
+  type: "object",
+  required: ["name", "description", "base_url", "payment", "endpoints"],
+  properties: {
+    name: {
+      type: "string",
+      pattern: "^[a-z0-9][a-z0-9_-]*$",
+      minLength: 1,
+      maxLength: 100,
+      description: "Unique skill identifier (kebab-case)"
+    },
+    displayName: {
+      type: "string",
+      maxLength: 200,
+      description: "Human-readable name"
+    },
+    description: {
+      type: "string",
+      minLength: 1,
+      maxLength: 2e3,
+      description: "What this skill does"
+    },
+    version: {
+      type: "string",
+      pattern: "^\\d+\\.\\d+\\.\\d+",
+      description: "Semantic version"
+    },
+    author: {
+      type: "string",
+      maxLength: 100
+    },
+    base_url: {
+      type: "string",
+      format: "uri",
+      description: "Base URL of the API"
+    },
+    type: {
+      type: "string",
+      enum: [...SKILL_TYPES],
+      default: "API"
+    },
+    payment: {
+      type: "object",
+      required: ["networks", "payTo"],
+      properties: {
+        networks: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: [...PAYMENT_NETWORKS]
+          },
+          minItems: 1,
+          description: "Supported payment networks"
+        },
+        asset: {
+          type: "string",
+          default: "USDC",
+          description: "Payment asset"
+        },
+        payTo: {
+          type: "string",
+          minLength: 1,
+          description: "Recipient address (Stellar or EVM)"
+        },
+        payToEvm: {
+          type: "string",
+          pattern: "^0x[a-fA-F0-9]{40}$",
+          description: "EVM address (fallback)"
+        },
+        facilitator: {
+          type: "string",
+          format: "uri",
+          description: "Facilitator URL"
+        }
+      },
+      additionalProperties: false
+    },
+    endpoints: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["path", "method", "description", "priceUsdc"],
+        properties: {
+          path: {
+            type: "string",
+            pattern: "^/",
+            description: "Endpoint path (must start with /)"
+          },
+          method: {
+            type: "string",
+            enum: [...HTTP_METHODS]
+          },
+          description: {
+            type: "string",
+            minLength: 1
+          },
+          priceUsdc: {
+            type: "string",
+            pattern: "^\\d+(\\.\\d+)?$",
+            description: 'Price in USDC (e.g. "0.001")'
+          },
+          inputSchema: {
+            type: "object",
+            description: "JSON Schema for request body"
+          },
+          outputSchema: {
+            type: "object",
+            description: "JSON Schema for response body"
+          }
+        },
+        additionalProperties: false
+      },
+      minItems: 1
+    },
+    tags: {
+      type: "array",
+      items: { type: "string" },
+      maxItems: 20
+    },
+    category: {
+      type: "string"
+    },
+    sla: {
+      type: "string",
+      description: 'Uptime guarantee (e.g. "99.9%")'
+    },
+    rateLimit: {
+      type: "string",
+      description: 'Rate limit (e.g. "1000/hour")'
+    },
+    sandbox: {
+      type: "string",
+      format: "uri",
+      description: "Free test endpoint URL"
+    }
+  },
+  additionalProperties: true
+};
+export {
+  HTTP_METHODS,
+  PAYMENT_NETWORKS,
+  SKILLMD_JSON_SCHEMA,
+  SKILL_TYPES,
+  generateFromOpenAPI,
+  generateSkillMd,
+  parseFrontmatter,
+  parseSkillMd,
+  toMcpToolDefinitions,
+  toOpenAPI,
+  validateSkill,
+  validateSkillMd
+};
+//# sourceMappingURL=index.js.map