wormajs 0.4.0 → 1.0.0-beta.1

package/dist/helper/config/GeneratorHelper.js

@@ -10,9 +10,11 @@ const constant_1 = require("../../constant");
 const parser_1 = require("../../core/parser");
 const helper_1 = require("../../core/parser/openApiParser/helper");
 const getAutoTemplateType_1 = __importDefault(require("../../functions/getAutoTemplateType"));
+const sourceSnapshot_1 = require("../../functions/sourceSnapshot");
 const wormaJson_1 = require("../../functions/wormaJson");
 const helper_2 = require("../../helper");
 const progress_1 = require("../../helper/progress");
+const format_1 = require("../../utils/format");
 const zType_1 = require("./zType");
 class GeneratorHelper {
     static instance;
@@ -29,6 +31,15 @@ class GeneratorHelper {
         bodyMediaType: 'application/json',
         type: constant_1.ConfigTypeEnum.AUTO,
         defaultRequire: false,
+        /**
+         * `transformConcurrency` is intentionally omitted: leaving it unset means
+         * "auto" (`min(64, max(8, cpus*4))`), which the parser resolves at runtime.
+         */
+        performance: {
+            workerPool: 'auto',
+            writeConcurrency: 32,
+            deterministicSort: true,
+        },
     });
     static getInstance() {
         if (!GeneratorHelper.instance) {
@@ -52,8 +63,13 @@ class GeneratorHelper {
      * @returns GeneratorHelper instance
      */
     async load(config) {
-        // Merge with default config
-        const mergedConfig = { ...this.defaultConfig, ...config };
+        // Merge with default config. `performance` is an object, so a plain spread
+        // would drop the per-field defaults as soon as the user sets only part of it.
+        const mergedConfig = {
+            ...this.defaultConfig,
+            ...config,
+            performance: { ...this.defaultConfig.performance, ...config.performance },
+        };
         // Validate configuration
         const validatedConfig = await GeneratorHelper.validateConfig(mergedConfig);
         // Update config
@@ -137,7 +153,7 @@ class GeneratorHelper {
             beforeSpecParse: opts?.beforeSpecParse,
         });
     }
-    static async generate(config, { projectPath, force, tracker }) {
+    static async generate(config, { projectPath, tracker }) {
         const reporter = (plugin) => tracker?.reporterFor(plugin.name ?? 'plugin') ?? progress_1.noopReportProgress;
         const pluginDriver = new helper_2.PluginDriver(config.plugins, { reporter });
         const reportCore = (progress, message) => {
@@ -147,7 +163,6 @@ class GeneratorHelper {
         const pluginNames = (config.plugins || []).map(p => p.name).filter(Boolean);
         helper_2.logger.debug('Starting generation process', {
             projectPath,
-            force,
             input: config.input,
             output: config.output,
             plugins: pluginCount,
@@ -173,6 +188,11 @@ class GeneratorHelper {
             reportCore(100, 'skipped: no openapi document');
             return { success: false, resolvedInput };
         }
+        // Requirement: the change baseline is the **source** document — the one
+        // parsed from the `beforeSpecParse` output, taken before the `specParsed`
+        // hooks run. `document` is the very object those hooks receive and they may
+        // mutate it in place, so the snapshot has to be taken right here.
+        const sourceDocumentText = (0, wormaJson_1.stableStringify)(document);
         helper_2.logger.debug('OpenAPI document parsed successfully', {
             resolvedUrl: resolvedInput,
             version: document?.info?.version,
@@ -247,22 +267,21 @@ class GeneratorHelper {
         // P2: Pass tagedApis to avoid re-grouping; apiHashCache avoids re-hashing same Api objects
         const newApis = templateData.allApis || [];
         const newHashInfo = (0, wormaJson_1.computePerTagHashes)(newApis, templateData.tagedApis);
+        // `generate()` is "call means generate": there is deliberately NO whole-run
+        // skip here any more. Change detection is `checkUpdates()`'s job; rendering
+        // stays incremental (only changed tags are re-rendered) as a pure
+        // optimization that does not alter the output.
+        const oldEntry = await (0, wormaJson_1.getCacheEntry)(projectPath, config.output);
         let changedTags;
-        if (!force) {
-            const oldEntry = await (0, wormaJson_1.getCacheEntry)(projectPath, config.output);
-            if (oldEntry) {
-                if (oldEntry.hash === newHashInfo.hash) {
-                    helper_2.logger.debug('Template data unchanged (hash match), skipping generation');
-                    reportCore(100, 'skipped: template data unchanged');
-                    return { success: false, resolvedInput };
-                }
-                // Compute which tags changed for incremental rendering
-                changedTags = (0, wormaJson_1.diffChangedTags)(oldEntry.tags, newHashInfo.tags);
-                helper_2.logger.debug('Incremental update detected', {
-                    totalTags: Object.keys(newHashInfo.tags).length,
-                    changedTags: changedTags.size,
-                });
-            }
+        if ((0, wormaJson_1.hasGenerationBaseline)(oldEntry)) {
+            changedTags = (0, wormaJson_1.diffChangedTags)(oldEntry.tags, newHashInfo.tags);
+            helper_2.logger.debug('Incremental update detected', {
+                totalTags: Object.keys(newHashInfo.tags).length,
+                changedTags: changedTags.size,
+            });
+        }
+        else {
+            helper_2.logger.debug('No render baseline — rendering every tag');
         }
         reportCore(70, 'beforeCodeGenerate');
         helper_2.logger.debug('Running beforeCodeGenerate hook');
@@ -288,7 +307,7 @@ class GeneratorHelper {
             // 9.2.1: Unified streaming pipeline — render + beforeFileWrite hooks + write
             const perf = config.performance;
             const writeConcurrency = perf?.writeConcurrency ?? 32;
-            const formatFile = perf?.formatFile ?? true;
+            const formatFile = (0, format_1.isFormatEnabled)();
             helper_2.logger.debug('Starting template generation', {
                 writeConcurrency,
                 formatFile,
@@ -340,7 +359,41 @@ class GeneratorHelper {
             reportCore(100, `failed: ${codeGenError.message}`);
             throw codeGenError;
         }
-        return { success: true, resolvedInput };
+        // Requirement A: refresh the source-level baseline with the very same raw
+        // text that was just parsed — zero extra requests. Only the `source`
+        // sub-field is touched, so the render baseline (`hash` / `tags`) is kept.
+        if (openApiResult.rawText) {
+            await (0, wormaJson_1.updateSourceBaseline)(projectPath, config.output, {
+                resolvedInput,
+                rawHash: (0, wormaJson_1.computeSpecHash)(openApiResult.rawText),
+                updatedAt: Date.now(),
+            }, config.serverName ?? '');
+        }
+        // Requirement B: the source-document diff runs only **after** a successful
+        // generation, so a failed run never pays for the comparison nor advances the
+        // baseline the next run diffs against.
+        let change;
+        try {
+            const sourceChanges = await (0, sourceSnapshot_1.collectSourceChanges)({
+                projectRoot: projectPath,
+                outputPath: config.output,
+                documentText: sourceDocumentText,
+                resolvedInput,
+            });
+            if (sourceChanges) {
+                change = {
+                    output: config.output,
+                    serverName: config.serverName || templateData.title || '',
+                    resolvedInput,
+                    changes: sourceChanges,
+                };
+            }
+        }
+        catch (error) {
+            // Recording change history must never fail the generation itself.
+            helper_2.logger.debug('Failed to detect source changes', { error: error?.message });
+        }
+        return { success: true, resolvedInput, change };
     }
 }
 exports.GeneratorHelper = GeneratorHelper;

package/dist/helper/config/zType.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.zConfig = exports.zGeneratorConfig = exports._zGeneratorConfig = exports.zApiPlugin = exports.zFetchOptions = exports.zHandleApi = exports.zApiDescriptor = exports.zTemplateResult = exports.zTemplateType = exports.zConfigType = void 0;
+exports.zConfig = exports.zGeneratorConfig = exports._zGeneratorConfig = exports.zPerformanceConfig = exports.zApiPlugin = exports.zFetchOptions = exports.zHandleApi = exports.zApiDescriptor = exports.zTemplateResult = exports.zTemplateType = exports.zConfigType = void 0;
 const node_path_1 = __importDefault(require("node:path"));
 const v3_1 = require("zod/v3"); // v4 is unstable, temporarily using v3
 /**
@@ -34,6 +34,20 @@ exports.zApiPlugin = v3_1.z.object({
     getTemplate: v3_1.z.function().optional(),
     onHandlebarsCreated: v3_1.z.function().optional(),
 });
+/**
+ * Performance tuning options. Declared explicitly so zod's default strip
+ * behavior does not drop `generator[].performance` during validation.
+ */
+exports.zPerformanceConfig = v3_1.z.object({
+    /** `'auto'` adapts the pool size to the API count, a number pins it, `false` disables workers */
+    workerPool: v3_1.z.union([v3_1.z.literal('auto'), v3_1.z.number(), v3_1.z.literal(false)]).optional(),
+    /** Max concurrency for the transform phase; defaults to `min(64, max(8, cpus*4))` */
+    transformConcurrency: v3_1.z.number().optional(),
+    /** Max parallelism for file writes; default 32 */
+    writeConcurrency: v3_1.z.number().optional(),
+    /** Sort components alphabetically for deterministic output; default true */
+    deterministicSort: v3_1.z.boolean().optional(),
+});
 exports._zGeneratorConfig = v3_1.z.object({
     /**
      * Openapi file path, it supports json and yaml file, and network url.
@@ -109,6 +123,10 @@ exports._zGeneratorConfig = v3_1.z.object({
      * plugin will be executed before `handleApi`
      */
     plugins: v3_1.z.array(exports.zApiPlugin).optional(),
+    /**
+     * Performance tuning options for code generation.
+     */
+    performance: exports.zPerformanceConfig.optional(),
     /**
      * Filter or convert the generated api function and return a new `apiDescriptor` to generate the api.
      * When this function is not specified, `apiDescriptor` object is not converted.
@@ -143,6 +161,11 @@ exports._zGeneratorConfig = v3_1.z.object({
 });
 exports.zGeneratorConfig = exports._zGeneratorConfig;
 exports.zConfig = v3_1.z.object({
+    /**
+     * 产物格式化配置（oxfmt）。不做结构校验：字段原样透传给 oxfmt，由 oxfmt 自行校验并报错。
+     * 声明在 schema 中仅为避免 zod 的默认 strip 行为把该字段丢弃。
+     */
+    format: v3_1.z.any().optional(),
     /**
      * API generation settings are arrays. Each item represents an automatically generated rule, including the generated input and output directories, specification file addresses, etc.
      * Currently, only OpenAPI specifications are supported, including OpenAPI 2.0 and 3.0 specifications.

package/dist/helper/template/index.js

@@ -61,6 +61,28 @@ function joinPath(...parts) {
     const p = node_path_1.default.join(...parts);
     return p ? normalizeSlashes(p) : p;
 }
+/**
+ * Recursively delete a directory, ignoring anything that is not there.
+ * Implemented with readdir/unlink/rmdir instead of `fs.rm` so it also works on
+ * virtual filesystems that do not implement `rm`.
+ */
+async function removeDirRecursive(dir) {
+    let entries = [];
+    try {
+        entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = node_path_1.default.join(dir, entry.name);
+        if (entry.isDirectory())
+            await removeDirRecursive(full);
+        else
+            await promises_1.default.unlink(full).catch(() => { });
+    }
+    await promises_1.default.rmdir(dir).catch(() => { });
+}
 class TemplateHelper {
     static instance;
     /** Runtime cache of parsed template data, keyed by `${projectPath}::${output}`. Flushed to disk via flushAllData. */
@@ -286,7 +308,7 @@ class TemplateHelper {
     }
     /**
      * 9.2.3: Private file writing — now internal to the streaming pipeline.
-     * Prettier formatting applied at file level (9.5.2).
+     * oxfmt formatting applied at file level (9.5.2).
      */
     async outputFiles(files, output, writeConcurrency = 32, formatFile = true) {
         const entries = Object.entries(files);
@@ -308,14 +330,14 @@ class TemplateHelper {
             const batch = entries.slice(i, i + concurrency);
             await Promise.all(batch.map(async ([rp, content]) => {
                 const op = node_path_1.default.isAbsolute(rp) ? rp : node_path_1.default.join(output, rp);
-                // 9.5.2: Apply prettier at file level for .ts/.js files
+                // 9.5.2: Apply oxfmt at file level for .ts/.js files
                 let finalContent = content;
                 if (formatFile && /\.(?:ts|js|mjs|cjs|tsx|jsx)$/.test(rp)) {
                     try {
-                        finalContent = await (0, utils_1.format)(content);
+                        finalContent = await (0, utils_1.format)(rp, content);
                     }
                     catch {
-                        // Prettier format failed, use original content
+                        // oxfmt format failed, use original content
                     }
                 }
                 return promises_1.default.writeFile(op, finalContent);
@@ -365,7 +387,20 @@ class TemplateHelper {
         // --- Phase 1: Per-tag streaming (render → collect → batch write) ---
         const nonDirTagTpls = tpls.filter(f => !f.insideTagDir && f.templateType === 'tag');
         const dirTpls = tpls.filter(f => f.insideTagDir);
-        const effectiveTags = changedTags ? tags.filter(t => changedTags.has(t)) : tags;
+        // Incremental rendering normally skips a tag whose hash is unchanged, which
+        // assumes its previously generated files are still on disk. If those files
+        // were deleted manually while the cache survived, the unchanged tag would
+        // never be emitted again. So an unchanged tag is also re-rendered whenever
+        // any of its expected artifacts is missing from the output directory.
+        let effectiveTags;
+        if (changedTags) {
+            const unchangedTags = tags.filter(t => !changedTags.has(t));
+            const missingTags = await this.collectTagsWithMissingArtifacts(unchangedTags, nonDirTagTpls, dirTpls, tagApisMap, outputDir);
+            effectiveTags = tags.filter(t => changedTags.has(t) || missingTags.has(t));
+        }
+        else {
+            effectiveTags = tags;
+        }
         let tagFilesWritten = 0;
         logger_1.logger.debug('Phase 1: Per-tag streaming', {
             totalTags: tags.length,
@@ -431,10 +466,83 @@ class TemplateHelper {
             }
         }
         await this.applyHooksAndWrite(globalFiles, outputDir, beforeFileWrite, undefined, undefined, undefined, writeConcurrency, formatFile, allFilePaths);
+        // --- Phase 3: drop orphaned tag artifacts ---
+        // Tags that existed before but are gone from the spec must not leave stale
+        // files/directories behind in the output directory.
+        await this.removeOrphanTagArtifacts(changedTags, tags, tpls, outputDir);
         logger_1.logger.debug('Phase 2 complete', { globalFilesWritten: Object.keys(globalFiles).length });
         logger_1.logger.debug('Generation summary', { totalOutputFiles: allFilePaths.length });
         return { filePaths: allFilePaths };
     }
+    /**
+     * Detect tags whose previously generated artifacts are missing from disk.
+     *
+     * Mirrors the path derivation used by `renderOne` / `expandByApi` to compute
+     * the expected output path of every per-tag file without rendering anything,
+     * then returns the tags that must be re-rendered because at least one of
+     * their files is gone.
+     */
+    async collectTagsWithMissingArtifacts(candidateTags, nonDirTagTpls, dirTpls, tagApisMap, outputDir) {
+        const missingTags = new Set();
+        for (const tag of candidateTags) {
+            const tagApis = tagApisMap.get(tag);
+            const expectedPaths = [];
+            // Flat `[tag]`-named templates, e.g. `services/[tag].ts.handlebars`
+            for (const tf of nonDirTagTpls) {
+                expectedPaths.push(stripExt(normalizeSlashes(tf.relativePath.replace(constant_1.TemplatePlaceholder.TAG, tag))));
+            }
+            // Tag-dir templates, e.g. `[tag]/index.ts` and `[tag]/[api].ts`
+            for (const tf of dirTpls) {
+                if (tf.templateType === 'api') {
+                    for (const api of tagApis?.apis || []) {
+                        expectedPaths.push(stripExt(normalizeSlashes(tf.relativePath
+                            .replace(constant_1.TemplatePlaceholder.TAG, tag)
+                            .replace(constant_1.TemplatePlaceholder.API, api.name))));
+                    }
+                }
+                else {
+                    expectedPaths.push(stripExt(normalizeSlashes(tf.relativePath.replace(constant_1.TemplatePlaceholder.TAG, tag))));
+                }
+            }
+            for (const relPath of expectedPaths) {
+                if (!(await (0, utils_1.existsPromise)(node_path_1.default.join(outputDir, relPath)))) {
+                    missingTags.add(tag);
+                    break;
+                }
+            }
+        }
+        return missingTags;
+    }
+    /**
+     * Remove generated artifacts of tags that no longer exist in the spec.
+     *
+     * `changedTags` contains both changed and removed tags; the ones missing from
+     * `tags` (the current tag list) are the removed ones. For those we delete:
+     * - the `[tag]` directory produced by tag-dir templates
+     * - the files produced by `[tag]`-named templates
+     */
+    async removeOrphanTagArtifacts(changedTags, tags, tpls, outputDir) {
+        if (!changedTags || changedTags.size === 0)
+            return;
+        const removedTags = [...changedTags].filter(tag => !tags.includes(tag));
+        if (removedTags.length === 0)
+            return;
+        const tagDirTpls = tpls.filter(f => f.insideTagDir);
+        const tagTpls = tpls.filter(f => !f.insideTagDir && f.templateType === 'tag');
+        for (const tag of removedTags) {
+            // Tag-dir templates: delete the whole `[tag]` directory (may be nested)
+            const dirs = new Set(tagDirTpls.map(tf => node_path_1.default.dirname(tf.relativePath.replace(constant_1.TemplatePlaceholder.TAG, tag))));
+            for (const dir of dirs) {
+                await removeDirRecursive(node_path_1.default.join(outputDir, dir));
+            }
+            // Flat `[tag]`-named templates: delete the resolved file
+            for (const tf of tagTpls) {
+                const relPath = stripExt(normalizeSlashes(tf.relativePath.replace(constant_1.TemplatePlaceholder.TAG, tag)));
+                await promises_1.default.unlink(node_path_1.default.join(outputDir, relPath)).catch(() => { });
+            }
+        }
+        logger_1.logger.debug('Removed orphaned tag artifacts', { tags: removedTags });
+    }
     async applyHooksAndWrite(files, outputDir, beforeFileWrite, templateType, tag, api, writeConcurrency, formatFile, allFilePaths) {
         if (beforeFileWrite) {
             // Apply beforeFileWrite to each file sequentially for determinism

package/dist/index.js

@@ -17,13 +17,30 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveWorkspaces = exports.logger = exports.generate = exports.defineConfig = exports.createConfig = exports.setGlobalConfig = void 0;
+exports.resolveWorkspaces = exports.logger = exports.generate = exports.writeSourceSnapshot = exports.sourceDocumentHash = exports.readSourceSnapshot = exports.diffSourceDocument = exports.diffApis = exports.apiDiffKey = exports.removeChange = exports.listChanges = exports.LATEST_CHANGE_ID = exports.getChange = exports.countChanges = exports.defineConfig = exports.createConfig = exports.setGlobalConfig = exports.checkUpdates = void 0;
+var checkUpdates_1 = require("./checkUpdates");
+Object.defineProperty(exports, "checkUpdates", { enumerable: true, get: function () { return checkUpdates_1.checkUpdates; } });
 var config_1 = require("./config");
 Object.defineProperty(exports, "setGlobalConfig", { enumerable: true, get: function () { return config_1.setGlobalConfig; } });
 var createConfig_1 = require("./createConfig");
 Object.defineProperty(exports, "createConfig", { enumerable: true, get: function () { return __importDefault(createConfig_1).default; } });
 var defineConfig_1 = require("./defineConfig");
 Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return defineConfig_1.defineConfig; } });
+var changeReport_1 = require("./functions/changeReport");
+Object.defineProperty(exports, "countChanges", { enumerable: true, get: function () { return changeReport_1.countChanges; } });
+Object.defineProperty(exports, "getChange", { enumerable: true, get: function () { return changeReport_1.getChange; } });
+Object.defineProperty(exports, "LATEST_CHANGE_ID", { enumerable: true, get: function () { return changeReport_1.LATEST_CHANGE_ID; } });
+Object.defineProperty(exports, "listChanges", { enumerable: true, get: function () { return changeReport_1.listChanges; } });
+Object.defineProperty(exports, "removeChange", { enumerable: true, get: function () { return changeReport_1.removeChange; } });
+var diffApis_1 = require("./functions/diffApis");
+Object.defineProperty(exports, "apiDiffKey", { enumerable: true, get: function () { return diffApis_1.apiDiffKey; } });
+Object.defineProperty(exports, "diffApis", { enumerable: true, get: function () { return diffApis_1.diffApis; } });
+var diffDocument_1 = require("./functions/diffDocument");
+Object.defineProperty(exports, "diffSourceDocument", { enumerable: true, get: function () { return diffDocument_1.diffSourceDocument; } });
+var sourceSnapshot_1 = require("./functions/sourceSnapshot");
+Object.defineProperty(exports, "readSourceSnapshot", { enumerable: true, get: function () { return sourceSnapshot_1.readSourceSnapshot; } });
+Object.defineProperty(exports, "sourceDocumentHash", { enumerable: true, get: function () { return sourceSnapshot_1.sourceDocumentHash; } });
+Object.defineProperty(exports, "writeSourceSnapshot", { enumerable: true, get: function () { return sourceSnapshot_1.writeSourceSnapshot; } });
 var generate_1 = require("./generate");
 Object.defineProperty(exports, "generate", { enumerable: true, get: function () { return __importDefault(generate_1).default; } });
 var helper_1 = require("./helper");

package/dist/plugins/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ky = exports.config = exports.axios = exports.alovaGlobals = exports.alova = exports.yapi = exports.swagger = exports.knife4j = exports.fastapi = void 0;
+exports.ky = exports.config = exports.axios = exports.alovaGlobals = exports.alova = exports.yapi = exports.swagger = exports.knife4j = void 0;
 __exportStar(require("./createPlugin"), exports);
 __exportStar(require("./presets/aiDoc"), exports);
 __exportStar(require("./presets/apifox"), exports);
@@ -22,10 +22,10 @@ __exportStar(require("./presets/filterApi"), exports);
 __exportStar(require("./presets/importType"), exports);
 __exportStar(require("./presets/payloadModifier"), exports);
 var platform_1 = require("./presets/platform");
-Object.defineProperty(exports, "fastapi", { enumerable: true, get: function () { return platform_1.fastapi; } });
 Object.defineProperty(exports, "knife4j", { enumerable: true, get: function () { return platform_1.knife4j; } });
 Object.defineProperty(exports, "swagger", { enumerable: true, get: function () { return platform_1.swagger; } });
 Object.defineProperty(exports, "yapi", { enumerable: true, get: function () { return platform_1.yapi; } });
+__exportStar(require("./presets/postman"), exports);
 __exportStar(require("./presets/rename"), exports);
 __exportStar(require("./presets/tagModifier"), exports);
 // Template preset plugins

package/dist/plugins/presets/aiDoc.js

@@ -73,8 +73,15 @@ function aiDoc(config) {
             });
             if (agentValue) {
                 const agentsToInstall = resolveInstallAgents(agentValue);
-                for (const agent of agentsToInstall) {
-                    installSkill(aidocsDir, agent, projectPath);
+                if (agentsToInstall.length) {
+                    for (const agent of agentsToInstall) {
+                        installSkill(aidocsDir, agent, projectPath);
+                    }
+                    // The skill now lives in each agent's own skills directory. Keeping the
+                    // generated copy under the output directory would store the same files
+                    // twice, so it is dropped — but only after *every* install succeeded:
+                    // a failing install throws above and leaves the source in place.
+                    removeSkillSourceDir(aidocsDir);
                 }
             }
         },
@@ -147,6 +154,24 @@ function installSkill(skillPath, agent, projectPath) {
         throw logger_1.logger.throwError(error);
     }
 }
+/**
+ * Delete the generated skill directory once it has been installed.
+ *
+ * `skills add` copies the whole directory into the agent's own skills folder,
+ * so the copy under the generator output is pure duplication.
+ *
+ * A removal failure is reported but never thrown: the install already
+ * succeeded, and failing the whole generation over a leftover directory would
+ * be worse than keeping it.
+ */
+function removeSkillSourceDir(skillPath) {
+    try {
+        node_fs_1.default.rmSync(skillPath, { recursive: true, force: true });
+    }
+    catch (error) {
+        console.error(`${prefix}Failed to remove the generated skill directory "${skillPath}".`, error?.stack ?? error);
+    }
+}
 /**
  * Parse a `key=value` configuration file (same format as an environment file).
  *

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

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TYPE_FAMILY_KEYS = void 0;
+exports.isSchemaPrimitive = isSchemaPrimitive;
+exports.clearTypeFamily = clearTypeFamily;
+exports.stripRef = stripRef;
+exports.dslToSchemaObject = dslToSchemaObject;
+exports.inferEnumType = inferEnumType;
+const VALID_PRIMITIVES = new Set([
+    'number',
+    'string',
+    'boolean',
+    'undefined',
+    'null',
+    'unknown',
+    'any',
+    'never',
+]);
+/**
+ * Keys describing the type shape. They are dropped when a type is replaced so that no
+ * leftover of the previous type survives (e.g. a stale `format: 'int64'`).
+ * Everything else — documentation keys above all — is kept.
+ */
+exports.TYPE_FAMILY_KEYS = [
+    'type',
+    'properties',
+    'items',
+    'enum',
+    'oneOf',
+    'anyOf',
+    'allOf',
+    'format',
+    'required',
+];
+function isSchemaPrimitive(value) {
+    return typeof value === 'string' && VALID_PRIMITIVES.has(value);
+}
+/** Rejects anything that is not a known type expression. */
+function assertPrimitive(value) {
+    if (!VALID_PRIMITIVES.has(value)) {
+        throw new Error(`[payloadModifier] Invalid schema type "${value}". Must be one of: ${[...VALID_PRIMITIVES].join(', ')}`);
+    }
+    return value;
+}
+/** Copies a schema keeping every documentation key and dropping every type-family key. */
+function clearTypeFamily(schema) {
+    const rest = { ...schema };
+    for (const key of exports.TYPE_FAMILY_KEYS) {
+        delete rest[key];
+    }
+    return rest;
+}
+/**
+ * Drops the internal `_$ref` marker stamped by the dereference step. Without this, a
+ * replaced node would still look like a reference to the original component and the
+ * downstream merge step would restore the component instead of keeping the change.
+ */
+function stripRef(schema) {
+    if (!schema || typeof schema !== 'object') {
+        return schema;
+    }
+    const rest = { ...schema };
+    delete rest._$ref;
+    return rest;
+}
+/**
+ * Converts a spec DSL expression into a raw OpenAPI schema object.
+ * This is the only conversion direction the plugin has: nothing ever converts a schema
+ * back into the DSL, so no documentation can be lost along the way.
+ */
+function dslToSchemaObject(dsl) {
+    if (typeof dsl === 'string') {
+        return { type: assertPrimitive(dsl) };
+    }
+    if (Array.isArray(dsl)) {
+        return { type: 'array', items: dslToItems(dsl) };
+    }
+    const spec = dsl;
+    if (Array.isArray(spec.oneOf)) {
+        return { oneOf: toSchemaList(spec.oneOf) };
+    }
+    if (Array.isArray(spec.anyOf)) {
+        return { anyOf: toSchemaList(spec.anyOf) };
+    }
+    if (Array.isArray(spec.allOf)) {
+        return { allOf: toSchemaList(spec.allOf) };
+    }
+    if (Array.isArray(spec.enum)) {
+        return enumToSchemaObject(spec.enum, spec.type);
+    }
+    // object shorthand
+    const properties = {};
+    for (const key of Object.keys(spec)) {
+        properties[key] = dslToSchemaObject(spec[key]);
+    }
+    return { type: 'object', properties, required: Object.keys(spec) };
+}
+function toSchemaList(list) {
+    return list.map(item => dslToSchemaObject(item));
+}
+/** A single element becomes `items`, multiple elements become a tuple (array) `items`. */
+function dslToItems(list) {
+    const items = toSchemaList(list);
+    return items.length === 1 ? items[0] : items;
+}
+function enumToSchemaObject(values, declared) {
+    const result = { enum: values };
+    const type = declared !== undefined
+        ? enumTypeToSchemaType(assertPrimitive(declared), values)
+        : inferEnumType(values);
+    if (type) {
+        result.type = type;
+    }
+    return result;
+}
+/**
+ * Maps a declared DSL type onto the OpenAPI type of an enum: `number` becomes `integer`
+ * when every value is an integer, otherwise it stays `number`. TS-only types such as
+ * `any` or `never` are written through as-is.
+ */
+function enumTypeToSchemaType(declared, values) {
+    if (declared === 'number') {
+        return values.every(value => typeof value === 'number' && Number.isInteger(value))
+            ? 'integer'
+            : 'number';
+    }
+    return declared;
+}
+/**
+ * Infers the OpenAPI type of an enum from its values. Returns `undefined` for mixed or
+ * empty values so no (possibly wrong) type is written.
+ */
+function inferEnumType(values) {
+    if (!values.length) {
+        return undefined;
+    }
+    if (values.every(value => typeof value === 'string')) {
+        return 'string';
+    }
+    if (values.every(value => typeof value === 'boolean')) {
+        return 'boolean';
+    }
+    if (values.every(value => typeof value === 'number')) {
+        return values.every(value => Number.isInteger(value)) ? 'integer' : 'number';
+    }
+    return undefined;
+}