wormajs 0.3.1 → 0.4.0

package/dist/plugins/presets/aiDoc.js

@@ -39,6 +39,9 @@ function aiDoc(config) {
                 ? (node_path_1.default.isAbsolute(customTemplatePath) ? customTemplatePath : node_path_1.default.resolve(projectPath, customTemplatePath))
                 : (0, template_1.getPresetTemplatePath)(constant_1.PresetTemplateName.AI_DOC);
             const serverName = capturedServerName || templateData.title || 'API';
+            // Skill name written into SKILL.md frontmatter. Defaults to `apis-<title>`
+            // which is the historical name the generated skill used before this option existed.
+            const skillName = config?.skillName ?? `apis-${templateData.title ?? ''}`;
             // Compute file location for each API (relative path from project root to generated file)
             // Skip fileLocation for alova-globals since APIs are called globally, not from a specific file
             const isGlobals = templateData.config?.templateName === 'alova-globals';
@@ -65,6 +68,7 @@ function aiDoc(config) {
                 data: {
                     ...enrichedData,
                     serverName,
+                    skillName,
                 },
             });
             if (agentValue) {

package/dist/plugins/presets/payloadModifier/hepler.js

@@ -55,7 +55,6 @@ const VALID_PRIMITIVES = new Set([
     'unknown',
     'any',
     'never',
-    'integer',
 ]);
 function validatePrimitive(val) {
     if (!VALID_PRIMITIVES.has(val)) {
@@ -86,13 +85,20 @@ function toSchemaObject(base, s) {
         const arr = s;
         cleanType(result);
         result.type = 'array';
-        const items = arr.map(item => toSchemaObject({}, item));
+        // Pass the original `items` down as the base of each element so documentation
+        // fields (e.g. `description`) survive the round-trip.
+        const baseItems = base.items;
+        const baseItemsList = Array.isArray(baseItems) ? baseItems : (baseItems ? [baseItems] : []);
+        const items = arr.map((item, idx) => toSchemaObject((baseItemsList[idx] || {}), item));
         result.items = (items.length === 1 ? items[0] : items);
         return result;
     }
     // Primitive types — validate against SchemaPrimitive set during conversion
     if (typeof s === 'string') {
         validatePrimitive(s);
+        // Drop the structural fields inherited from the base so they don't leak into the
+        // new type; documentation fields such as `description` are kept.
+        cleanType(result);
         result.type = s;
         return result;
     }
@@ -118,15 +124,28 @@ function toSchemaObject(base, s) {
         result.allOf = spec.allOf.map((item, idx) => toSchemaObject(baseAllOf[idx] || {}, item));
         return result;
     }
-    // Enum: set enum and optional type
+    // Enum: write the enum values back, converting the TS primitive type from the
+    // handler into its OpenAPI counterpart (`number` -> `integer`/`number`, `string`, ...).
     if (s.enum) {
         const spec = s;
+        // Drop the structural fields inherited from the base; documentation fields are kept.
+        cleanType(result);
         result.enum = spec.enum;
         if (spec.type) {
             if (typeof spec.type === 'string') {
                 validatePrimitive(spec.type);
             }
-            result.type = spec.type;
+            // `number` only becomes `integer` when every enum value is an integer.
+            result.type = enumTypeToSchemaType(spec.type, spec.enum);
+        }
+        else {
+            // No type from the handler: keep an OpenAPI 3.1 type array (e.g. `['string', 'null']`)
+            // as-is, otherwise infer the type from the enum values.
+            const fallback = Array.isArray(base.type) ? base.type : inferEnumType(spec.enum);
+            if (fallback) {
+                result.type = fallback;
+            }
+            // otherwise the enum stays untyped (mixed or empty values)
         }
         return result;
     }
@@ -135,9 +154,14 @@ function toSchemaObject(base, s) {
     // scalar fields like description from base)
     const ref = s;
     if (ref && typeof ref === 'object') {
+        // Drop the structural fields inherited from the base; documentation fields are kept.
+        cleanType(result);
         result.type = 'object';
         const properties = {};
         const requiredSet = new Set();
+        // The base of each property is taken from the ORIGINAL `base.properties` (not from the
+        // object being built) so documentation fields like `description` survive the round-trip.
+        const baseProperties = (base.properties || {});
         for (const key in ref) {
             const val = ref[key];
             if (!val) {
@@ -157,7 +181,7 @@ function toSchemaObject(base, s) {
                 isOptional = false;
                 effectiveVal = val;
             }
-            const baseProp = properties[key];
+            const baseProp = baseProperties[key];
             properties[key] = toSchemaObject(baseProp || {}, effectiveVal);
             if (isOptional) {
                 requiredSet.delete(key);
@@ -187,6 +211,37 @@ function schemaTypeToPrimitiveType(t) {
     }
     return t;
 }
+// Convert a SchemaPrimitive (the TS type used by the handler) back into the OpenAPI type
+// of an enum. A numeric enum is written as `integer` (the OpenAPI counterpart of the TS
+// `number`) only when every value is an integer, otherwise it stays `number` so the type
+// matches the values. `string`/`boolean` map 1:1, TS-only types are written through as-is.
+function enumTypeToSchemaType(t, enumValues) {
+    if (t === 'number') {
+        return enumValues.every(v => typeof v === 'number' && Number.isInteger(v))
+            ? 'integer'
+            : 'number';
+    }
+    return t;
+}
+// Infer the OpenAPI type of an enum from its values, used when no type is declared so the
+// enum does not stay untyped. Returns `undefined` for mixed or empty values so that no
+// (possibly wrong) type is written.
+function inferEnumType(enumValues) {
+    if (!enumValues.length) {
+        return undefined;
+    }
+    if (enumValues.every(v => typeof v === 'string')) {
+        return 'string';
+    }
+    if (enumValues.every(v => typeof v === 'boolean')) {
+        return 'boolean';
+    }
+    if (enumValues.every(v => typeof v === 'number')) {
+        return enumValues.every(v => Number.isInteger(v)) ? 'integer' : 'number';
+    }
+    // mixed value types -> leave the enum untyped
+    return undefined;
+}
 // Convert existing OpenAPI SchemaObject -> Schema (best-effort, for handler input)
 function toSchemaSpec(obj) {
     if (!obj || typeof obj !== 'object') {
@@ -205,9 +260,12 @@ function toSchemaSpec(obj) {
         const arr = obj.allOf;
         return { allOf: arr.map(item => toSchemaSpec(item)) };
     }
-    // Enum
+    // Enum: the OpenAPI type is normalized to its TS primitive counterpart
+    // (e.g. `integer` -> `number`), consistent with how plain primitives are converted.
     if (Array.isArray(obj.enum) && obj.enum.length > 0) {
-        const type = typeof obj.type === 'string' ? obj.type : undefined;
+        const type = typeof obj.type === 'string'
+            ? schemaTypeToPrimitiveType(obj.type)
+            : undefined;
         return { enum: obj.enum, type };
     }
     // Array -> native array

package/dist/template/presets/ai-doc/SKILL.md.handlebars

@@ -1,5 +1,5 @@
 ---
-name: apis-{{{title}}}
+name: {{{skillName}}}
 description: >-
   API reference documentation for {{{serverName}}} ({{{title}}} v{{{version}}}).
   Contains specifications for all REST API endpoints, including HTTP request methods,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wormajs",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "A modern OpenAPI code generator - Generate type-safe API clients from OpenAPI specs",
   "author": "worma",
   "license": "MIT",

package/typings/plugins.d.ts

@@ -438,6 +438,12 @@ export type SkillAgent = "aider-desk" | "amp" | "antigravity" | "antigravity-cli
 export interface AiDocConfig {
 	template?: string;
 	outputDir?: string;
+	/**
+	 * Name written into the generated skill's `SKILL.md` frontmatter. This is the
+	 * name the skill is installed/referenced under. When omitted, the skill keeps
+	 * its default name derived from the API title: `apis-<title>`.
+	 */
+	skillName?: string;
 	/**
 	 * Which coding agent(s) to install the generated skill into.
 	 * - omitted: do NOT install the skill.
@@ -575,7 +581,7 @@ export declare function importType(imports: Record<string, string[]>, options?:
 	files?: string[];
 }): ApiPlugin;
 export type ModifierScope = "params" | "pathParams" | "data" | "response";
-export type SchemaPrimitive = "number" | "string" | "boolean" | "undefined" | "null" | "unknown" | "any" | "never" | "integer";
+export type SchemaPrimitive = "number" | "string" | "boolean" | "undefined" | "null" | "unknown" | "any" | "never";
 /**
  * Array type: a native JS array whose elements are Schemas.
  * e.g. ['string'] means string[]; ['string', 'number'] means the tuple [string, number]