wormajs 0.2.7 → 0.3.0

package/dist/functions/readWormaRc.js

@@ -15,10 +15,14 @@ const template_1 = require("../template");
  * Parse a single line from .wormarc file
  *
  * Supported formats:
- * - `https://xxxx.com/openapi.json` -> generates in src/api, default alova template
- * - `https://yyyy.com/openapi.json, axios` -> generates in src/api2, axios template
- * - `myApi=https://zzzz.com/openapi.json` -> generates in src/myApi, default alova template
- * - `myApi=https://zzzz.com/openapi.json, fetch` -> generates in src/myApi, fetch template
+ * - `https://xxxx.com/openapi.json` -> generates in src/api, default alova template, no aiDoc plugin
+ * - `https://yyyy.com/openapi.json, axios` -> generates in src/api2, axios template, no aiDoc plugin
+ * - `myApi=https://zzzz.com/openapi.json, fetch` -> generates in src/myApi, fetch template, no aiDoc plugin
+ * - `https://xxxx.com/openapi.json, alova, cursor` -> alova template, aiDoc installed to `cursor`
+ * - `myApi=https://zzzz.com/openapi.json, fetch, cursor, claude-code` -> fetch template, aiDoc installed to both agents
+ *
+ * The optional third comma-separated segment is the `agent` list for the `aiDoc`
+ * plugin. When it is absent, the `aiDoc` plugin is skipped entirely for that line.
  */
 function parseLine(line) {
     line = line.trim();
@@ -38,23 +42,17 @@ function parseLine(line) {
         return null;
     }
     let outputKey;
-    let url;
-    let template;
     // Check for key=value format
     const equalIndex = line.indexOf('=');
     if (equalIndex !== -1) {
         outputKey = line.substring(0, equalIndex).trim();
         line = line.substring(equalIndex + 1).trim();
     }
-    // Split by comma to get URL and template
-    const commaIndex = line.indexOf(',');
-    if (commaIndex !== -1) {
-        url = line.substring(0, commaIndex).trim();
-        template = line.substring(commaIndex + 1).trim() || undefined;
-    }
-    else {
-        url = line.trim();
-    }
+    // Split by comma into at most three segments: url[, template][, agent]
+    const segments = line.split(',').map(s => s.trim()).filter(s => s !== '');
+    const url = segments[0] ?? '';
+    const template = segments[1];
+    const agent = segments[2];
     if (!url) {
         return null;
     }
@@ -62,6 +60,7 @@ function parseLine(line) {
         outputKey,
         url,
         template: template,
+        agent,
     };
 }
 /**
@@ -100,7 +99,7 @@ async function readWormaRc(projectPath) {
             if (!parsed) {
                 continue;
             }
-            const { outputKey, url, template = constant_1.PresetTemplateName.ALOVA } = parsed;
+            const { outputKey, url, template = constant_1.PresetTemplateName.ALOVA, agent } = parsed;
             // Determine output folder
             let output;
             if (outputKey) {
@@ -116,11 +115,18 @@ async function readWormaRc(projectPath) {
             if (!template || !PRESET_TEMPLATES[template]) {
                 throw logger_1.logger.throwError(`Invalid template: ${template}. Available templates: ${Object.keys(PRESET_TEMPLATES).join(', ')}`);
             }
+            // Build plugin list. The aiDoc plugin is only added when an agent is
+            // explicitly specified on the line; otherwise no AI skill doc is generated
+            // or installed for this entry.
+            const plugins = [PRESET_TEMPLATES[template]()];
+            if (agent) {
+                plugins.push((0, plugins_1.aiDoc)({ agent }));
+            }
             // Build generator config
             const generatorConfig = {
                 input: url,
                 output,
-                plugins: [PRESET_TEMPLATES[template](), (0, plugins_1.aiDoc)({ installSkill: true })],
+                plugins,
             };
             generators.push(generatorConfig);
         }

package/dist/plugins/presets/aiDoc.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.aiDoc = aiDoc;
 exports.parseAgentList = parseAgentList;
+exports.parseAgentFile = parseAgentFile;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_module_1 = require("node:module");
@@ -13,12 +14,11 @@ const constant_1 = require("../../constant");
 const logger_1 = require("../../helper/logger");
 const template_1 = require("../../template");
 const nodeRequire = (0, node_module_1.createRequire)(__filename);
-const SKILLS_SUPPORTED_AGENTS_URL = 'https://www.npmjs.com/package/skills#supported-agents';
 const prefix = '[plugin: aiDoc]';
 function aiDoc(config) {
     const outputDirName = config?.outputDir ?? 'aidocs';
     const customTemplatePath = config?.template;
-    const installSkillEnabled = config?.installSkill ?? false;
+    const agentValue = config?.agent;
     let capturedOutput = '';
     let capturedServerName = '';
     return {
@@ -67,9 +67,9 @@ function aiDoc(config) {
                     serverName,
                 },
             });
-            if (installSkillEnabled) {
-                const { agents } = resolveAgents(projectPath);
-                for (const agent of agents) {
+            if (agentValue) {
+                const agentsToInstall = resolveInstallAgents(agentValue);
+                for (const agent of agentsToInstall) {
                     installSkill(aidocsDir, agent, projectPath);
                 }
             }
@@ -77,32 +77,20 @@ function aiDoc(config) {
     };
 }
 /**
- * Resolve the target coding agents from `.env.local` in the project root.
+ * Resolve the list of coding agents to install the generated skill into.
  *
- * Multiple agents can be configured as a comma-separated list, e.g.
- * `agent=cursor, claude-code, windsurf`. Both commas and surrounding
- * whitespace are tolerated.
+ * @param agent the raw `agent` config value
+ *  - `SkillAgent` / `SkillAgent[]`: used directly as the target agent(s).
+ *  - `string`: parsed as a comma (English or Chinese) separated agent list,
+ *    e.g. `"cursor"` or `"cursor, claude-code"`.
  *
- * If the file does not exist, it will be created and `.gitignore` will be
- * updated to ignore `*.local` files. An error is then thrown asking the user
- * to set `agent=<coding-agent>` (optionally multiple, comma-separated).
- *
- * If `agent` is missing or empty, an error is thrown with guidance.
+ * The agent list is no longer read from `node_modules/.worma/skills.local`.
+ * Instead, callers pass the agent(s) explicitly via the `agent`
+ * option (optionally sourced from their own config file via `parseAgentFile`).
  */
-function resolveAgents(projectPath) {
-    const envFilePath = node_path_1.default.join(projectPath, '.env.local');
-    if (!node_fs_1.default.existsSync(envFilePath)) {
-        createEnvLocalFile(envFilePath);
-        ensureGitIgnoreLocal(projectPath);
-        throw logger_1.logger.throwError(`${prefix}Created .env.local at project root. Please set the coding agent you are using, e.g. agent=cursor or multiple agents comma-separated: agent=cursor,claude-code. Supported agents list: ${SKILLS_SUPPORTED_AGENTS_URL}`);
-    }
-    const content = node_fs_1.default.readFileSync(envFilePath, 'utf-8');
-    const raw = parseEnvValue(content, 'agent') ?? '';
-    const agents = parseAgentList(raw);
-    if (agents.length === 0) {
-        throw logger_1.logger.throwError(`${prefix}Missing "agent" in .env.local at project root. Please set the coding agent you are using, e.g. agent=cursor or multiple agents comma-separated: agent=cursor,claude-code. Supported agents list: ${SKILLS_SUPPORTED_AGENTS_URL}`);
-    }
-    return { agents };
+function resolveInstallAgents(agent) {
+    const raw = Array.isArray(agent) ? agent.join(',') : agent;
+    return parseAgentList(raw);
 }
 /**
  * Parse an agent string into a deduplicated list of trimmed agent names.
@@ -155,47 +143,45 @@ function installSkill(skillPath, agent, projectPath) {
         throw logger_1.logger.throwError(error);
     }
 }
-function createEnvLocalFile(envFilePath) {
-    const content = `# Worma aiDoc skill installer configuration
-# Please set the coding agent(s) you are using (e.g. cursor, claude-code, windsurf).
-# You can configure multiple agents comma-separated, e.g. agent=cursor,claude-code.
-# Supported agents list: ${SKILLS_SUPPORTED_AGENTS_URL}
-agent=
-`;
-    node_fs_1.default.writeFileSync(envFilePath, content, 'utf-8');
-}
-function ensureGitIgnoreLocal(projectPath) {
-    const gitignorePath = node_path_1.default.join(projectPath, '.gitignore');
-    const pattern = '*.local';
-    let content = '';
-    if (node_fs_1.default.existsSync(gitignorePath)) {
-        content = node_fs_1.default.readFileSync(gitignorePath, 'utf-8');
-        const lines = content.split(/\r?\n/);
-        if (lines.some(line => line.trim() === pattern || line.trim() === '*.local/')) {
-            return;
-        }
-    }
-    const prefix = content === '' || content.endsWith('\n') ? '' : '\n';
-    node_fs_1.default.writeFileSync(gitignorePath, `${content}${prefix}${pattern}\n`, 'utf-8');
-}
-function parseEnvValue(content, key) {
-    const lines = content.split(/\r?\n/);
-    for (const line of lines) {
+/**
+ * Parse a `key=value` configuration file (same format as an environment file).
+ *
+ * Lines starting with `#` are treated as comments and ignored; blank lines and
+ * lines without `=` are skipped. Surrounding single/double quotes around values
+ * are stripped. Returns a map of keys to their (string) values.
+ *
+ * When `filePath` is omitted, the file is read from `.wormaagent.local` in the
+ * current working directory (project root).
+ *
+ * This makes it easy to keep the target coding agent(s) in a config file and
+ * feed them into the `agent` option:
+ *
+ * @example
+ * ```ts
+ * // .wormaagent.local  ->  agent=cursor, claude-code
+ * const cfg = parseAgentFile() // reads ./.wormaagent.local by default
+ * aiDoc({ agent: cfg.agent })
+ * ```
+ */
+function parseAgentFile(filePath) {
+    const target = filePath ?? node_path_1.default.resolve(process.cwd(), '.wormaagent.local');
+    const content = node_fs_1.default.readFileSync(target, 'utf-8');
+    const result = {};
+    for (const line of content.split(/\r?\n/)) {
         const trimmed = line.trim();
-        if (trimmed.startsWith('#') || !trimmed.includes('=')) {
+        if (trimmed === '' || trimmed.startsWith('#') || !trimmed.includes('=')) {
             continue;
         }
         const eqIndex = trimmed.indexOf('=');
-        const k = trimmed.slice(0, eqIndex).trim();
-        let v = trimmed.slice(eqIndex + 1).trim();
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
         // Remove surrounding quotes if present
-        if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith('\'') && v.endsWith('\''))) {
-            v = v.slice(1, -1);
-        }
-        if (k === key) {
-            return v;
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith('\'') && value.endsWith('\''))) {
+            value = value.slice(1, -1);
         }
+        if (key)
+            result[key] = value;
     }
-    return undefined;
+    return result;
 }
 exports.default = aiDoc;

package/dist/template/presets/config/partials/generator-content.handlebars

@@ -18,7 +18,7 @@ generator: [
       * swagger platform plugin: auto-resolves OpenAPI file URLs from the base URL.
       * The base URL is passed as the plugin argument (not config.input).
       */
-    plugins: [swagger('http://localhost:3000'), aiDoc({ installSkill: true }), {{{templateCall}}}],
+    plugins: [swagger('http://localhost:3000'), aiDoc({ agent: 'codex' }), {{{templateCall}}}],
 
     /**
       * the mediaType of the generated response data. default is `application/json`

package/package.json

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

package/typings/plugins.d.ts

@@ -424,10 +424,30 @@ export interface TemplateData {
  * });
  */
 export declare function createPlugin<T extends any[]>(plugin: (...args: T) => ApiPlugin): (...args: T) => ApiPlugin;
+/**
+ * Coding agents that the generated skill can be installed into.
+ *
+ * The `skills` package (`https://www.npmjs.com/package/skills`) is CLI-only and
+ * ships no TypeScript types, so this union mirrors the agent names it supports
+ * (its documented "supported agents" list). The transitive `@vercel/detect-agent`
+ * package does export a `KnownAgentNames` type, but it only covers a small subset
+ * of agents (e.g. it is missing `claude-code` and `windsurf`), so it cannot be
+ * reused directly here.
+ */
+export type SkillAgent = "aider-desk" | "amp" | "antigravity" | "antigravity-cli" | "astrbot" | "augment" | "autohand-code" | "bob" | "claude-code" | "cline" | "codearts-agent" | "codebuddy" | "codemaker" | "codestudio" | "codex" | "command-code" | "continue" | "cortex" | "crush" | "cursor" | "deepagents" | "devin" | "dexto" | "droid" | "eve" | "firebender" | "forgecode" | "gemini-cli" | "github-copilot" | "goose" | "hermes-agent" | "iflow-cli" | "inference-sh" | "jazz" | "junie" | "kilo" | "kiro-cli" | "kimi-code-cli" | "kode" | "lingma" | "loaf" | "mcpjam" | "mistral-vibe" | "moxby" | "mux" | "ona" | "opencode" | "openhands" | "openclaw" | "pi" | "pochi" | "promptscript" | "qoder" | "qoder-cn" | "qwen-code" | "reasonix" | "replit" | "rovodev" | "roo" | "tabnine-cli" | "terramind" | "tinycloud" | "trae" | "trae-cn" | "universal" | "warp" | "windsurf" | "zed" | "zencoder" | "zenflow" | "neovate" | "adal";
 export interface AiDocConfig {
 	template?: string;
 	outputDir?: string;
-	installSkill?: boolean;
+	/**
+	 * Which coding agent(s) to install the generated skill into.
+	 * - omitted: do NOT install the skill.
+	 * - `SkillAgent` / `SkillAgent[]`: install to the given agent(s) directly.
+	 * - `string`: comma (English or Chinese) separated agent names, used directly
+	 *   as the target agent(s), e.g. `"cursor"` or `"cursor, claude-code"`.
+	 *   This is handy when the agent list comes from a config file parsed via
+	 *   `parseAgentFile`, e.g. `aiDoc({ agent: parseAgentFile('.myrc').agent })`.
+	 */
+	agent?: SkillAgent | (SkillAgent | (string & {}))[] | (string & {});
 }
 export declare function aiDoc(config?: AiDocConfig): ApiPlugin;
 /**
@@ -438,6 +458,27 @@ export declare function aiDoc(config?: AiDocConfig): ApiPlugin;
  * either side. Empty entries are ignored.
  */
 export declare function parseAgentList(raw: string): string[];
+/**
+ * Parse a `key=value` configuration file (same format as an environment file).
+ *
+ * Lines starting with `#` are treated as comments and ignored; blank lines and
+ * lines without `=` are skipped. Surrounding single/double quotes around values
+ * are stripped. Returns a map of keys to their (string) values.
+ *
+ * When `filePath` is omitted, the file is read from `.wormaagent.local` in the
+ * current working directory (project root).
+ *
+ * This makes it easy to keep the target coding agent(s) in a config file and
+ * feed them into the `agent` option:
+ *
+ * @example
+ * ```ts
+ * // .wormaagent.local  ->  agent=cursor, claude-code
+ * const cfg = parseAgentFile() // reads ./.wormaagent.local by default
+ * aiDoc({ agent: cfg.agent })
+ * ```
+ */
+export declare function parseAgentFile(filePath?: string): Record<string, string>;
 export type ScopeType = "ALL" | "SELECTED_ENDPOINTS" | "SELECTED_TAGS" | "SELECTED_FOLDERS";
 export interface APIFoxBody {
 	scope?: {