@pulse-editor/cli 0.1.4 → 0.1.5

package/dist/lib/server/express.js

@@ -97,8 +97,14 @@ app.all(/^\/server-function\/(.*)/, async (req, res) => {
 });
 if (isPreview) {
     /* Preview mode */
-    app.get("/pulse.config.json", (_req, res) => {
-        res.sendFile(path.resolve("dist/pulse.config.json"));
+    app.get("/pulse.config.json", async (_req, res) => {
+        try {
+            const data = await import("fs/promises").then((fs) => fs.readFile("dist/pulse.config.json", "utf-8"));
+            res.type("json").send(data);
+        }
+        catch {
+            res.status(404).json({ error: "pulse.config.json not found" });
+        }
     });
     app.use(express.static("dist/client"));
     // Expose skill actions as REST API endpoints in dev and preview modes

package/dist/lib/webpack/configs/mf-server.js

@@ -1,11 +1,9 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import mfNode from "@module-federation/node";
 import fs from "fs";
-import { globSync } from "glob";
 import path from "path";
-import { Node, Project, SyntaxKind } from "ts-morph";
 import wp from "webpack";
-import { discoverAppSkillActions, discoverServerFunctions, loadPulseConfig, } from "./utils.js";
+import { compileAppActionSkills, discoverAppSkillActions, discoverServerFunctions, loadPulseConfig, } from "./utils.js";
 const { NodeFederationPlugin } = mfNode;
 const { webpack } = wp;
 class MFServerPlugin {
@@ -48,13 +46,13 @@ class MFServerPlugin {
                         : false;
                     if (isActionChange) {
                         console.log(`[Server] Detected changes in actions. Recompiling...`);
-                        this.compileAppActionSkills();
+                        compileAppActionSkills(this.pulseConfig);
                     }
                 }
                 else {
                     console.log(`[Server] 🔄 Building app...`);
                     await this.compileServerFunctions(compiler);
-                    this.compileAppActionSkills();
+                    compileAppActionSkills(this.pulseConfig);
                     console.log(`[Server] ✅ Successfully built server.`);
                     const funcs = discoverServerFunctions();
                     console.log(`\n🛜 Server functions:
@@ -85,7 +83,7 @@ ${Object.entries(funcs)
                 else {
                     try {
                         await this.compileServerFunctions(compiler);
-                        this.compileAppActionSkills();
+                        compileAppActionSkills(this.pulseConfig);
                     }
                     catch (err) {
                         console.error(`[Server] ❌ Error during compilation:`, err);
@@ -158,252 +156,6 @@ ${Object.entries(funcs)
             },
         }, {});
     }
-    /**
-     * Register default functions defined in src/skill as exposed modules in Module Federation.
-     * This will:
-     * 	1. Search for all .ts files under src/skill
-     *  2. Use ts-morph to get the default function information, including function name, parameters, and JSDoc comments
-     *  3. Organize the functions' information into a list of Action
-     * @param compiler
-     */
-    compileAppActionSkills() {
-        // 1. Get all TypeScript files under src/skill
-        const files = globSync("./src/skill/*/action.ts");
-        const project = new Project({
-            tsConfigFilePath: path.join(process.cwd(), "node_modules/.pulse/tsconfig.server.json"),
-        });
-        const actions = [];
-        files.forEach((file) => {
-            const sourceFile = project.addSourceFileAtPath(file);
-            const defaultExportSymbol = sourceFile.getDefaultExportSymbol();
-            if (!defaultExportSymbol)
-                return;
-            const defaultExportDeclarations = defaultExportSymbol.getDeclarations();
-            defaultExportDeclarations.forEach((declaration) => {
-                if (declaration.getKind() !== SyntaxKind.FunctionDeclaration)
-                    return;
-                const funcDecl = declaration.asKindOrThrow(SyntaxKind.FunctionDeclaration);
-                // Get action name from path `src/skill/{actionName}/action.ts`
-                // Match `*/src/skill/{actionName}/action.ts` and extract {actionName}
-                const pattern = /src\/skill\/([^\/]+)\/action\.ts$/;
-                const match = file.replaceAll("\\", "/").match(pattern);
-                if (!match) {
-                    console.warn(`File path ${file} does not match pattern ${pattern}. Skipping...`);
-                    return;
-                }
-                const actionName = match[1];
-                if (!actionName) {
-                    console.warn(`Could not extract action name from file path ${file}. Skipping...`);
-                    return;
-                }
-                // Throw an error if the funcName is duplicated with an existing action to prevent accidental overwriting
-                if (actions.some((action) => action.name === actionName)) {
-                    throw new Error(`Duplicate action name "${actionName}" detected in file ${file}. Please ensure all actions have unique names to avoid conflicts.`);
-                }
-                const defaultExportJSDocs = funcDecl.getJsDocs();
-                // Validate that the function has a JSDoc description
-                const descriptionText = defaultExportJSDocs
-                    .map((doc) => doc.getDescription().replace(/^\*+/gm, "").trim())
-                    .join("\n")
-                    .trim();
-                if (defaultExportJSDocs.length === 0 || !descriptionText) {
-                    throw new Error(`[Action Validation] Action "${actionName}" in ${file} is missing a JSDoc description. ` +
-                        `Please add a JSDoc comment block with a description above the function.` +
-                        `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
-                }
-                const description = defaultExportJSDocs
-                    .map((doc) => doc.getFullText())
-                    .join("\n");
-                const allJSDocs = sourceFile.getDescendantsOfKind(SyntaxKind.JSDoc);
-                const typeDefs = this.parseTypeDefs(allJSDocs);
-                /* Extract parameter descriptions from JSDoc */
-                const funcParam = funcDecl.getParameters()[0];
-                const params = {};
-                if (funcParam) {
-                    /**
-                     * Extract default values from the destructured parameter
-                     * (ObjectBindingPattern → BindingElement initializer)
-                     */
-                    const defaults = new Map();
-                    const nameNode = funcParam.getNameNode();
-                    if (Node.isObjectBindingPattern(nameNode)) {
-                        nameNode.getElements().forEach((el) => {
-                            if (!Node.isBindingElement(el))
-                                return;
-                            const name = el.getName();
-                            const initializer = el.getInitializer()?.getText();
-                            if (initializer) {
-                                defaults.set(name, initializer);
-                            }
-                        });
-                    }
-                    const paramProperties = funcParam.getType().getProperties();
-                    const inputTypeDef = typeDefs["input"] ?? {};
-                    if (paramProperties.length > 0 && !typeDefs["input"]) {
-                        throw new Error(`[Action Validation] Action "${actionName}" in ${file} has parameters but is missing an ` +
-                            `"@typedef {Object} input" JSDoc block. Please document all parameters with ` +
-                            `@typedef {Object} input and @property tags.` +
-                            `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
-                    }
-                    paramProperties.forEach((prop) => {
-                        const name = prop.getName();
-                        if (!inputTypeDef[name]) {
-                            throw new Error(`[Action Validation] Action "${actionName}" in ${file}: parameter "${name}" is missing ` +
-                                `a @property entry in the "input" JSDoc typedef. Please add ` +
-                                `"@property {type} ${name} - description" to the JSDoc.` +
-                                `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
-                        }
-                        if (!inputTypeDef[name]?.description?.trim()) {
-                            throw new Error(`[Action Validation] Action "${actionName}" in ${file}: parameter "${name}" has an empty ` +
-                                `description in the JSDoc @property. Please provide a meaningful description.` +
-                                `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
-                        }
-                        const variable = {
-                            description: inputTypeDef[name]?.description ?? "",
-                            type: this.getType(inputTypeDef[name]?.type ?? ""),
-                            optional: prop.isOptional() ? true : undefined,
-                            defaultValue: defaults.get(name),
-                        };
-                        params[name] = variable;
-                    });
-                }
-                /* Extract return type from JSDoc */
-                const rawReturnType = funcDecl.getReturnType();
-                const isPromiseLikeReturn = this.isPromiseLikeType(rawReturnType);
-                const returnType = this.unwrapPromiseLikeType(rawReturnType);
-                // Check if the return type is an object
-                if (!returnType.isObject()) {
-                    console.warn(`[Action Registration] Function ${actionName}'s return type should be an object. Skipping...`);
-                    return;
-                }
-                const returns = {};
-                const returnProperties = returnType.getProperties();
-                const outputTypeDef = typeDefs["output"] ?? {};
-                const hasOutputTypeDef = !!typeDefs["output"];
-                if (returnProperties.length > 0 &&
-                    !hasOutputTypeDef &&
-                    !isPromiseLikeReturn) {
-                    throw new Error(`[Action Validation] Action "${actionName}" in ${file} returns properties but is missing an ` +
-                        `"@typedef {Output}" JSDoc block. Please document all return values with ` +
-                        `@typedef {Output} and @property tags.` +
-                        `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
-                }
-                if (returnProperties.length > 0 && !hasOutputTypeDef && isPromiseLikeReturn) {
-                    console.warn(`[Action Validation] Action "${actionName}" in ${file} is missing an "@typedef {Object} output" JSDoc block. ` +
-                        `Falling back to TypeScript-inferred return metadata because the action returns a Promise.`);
-                }
-                returnProperties.forEach((prop) => {
-                    const name = prop.getName();
-                    if (!hasOutputTypeDef) {
-                        const variable = {
-                            description: "",
-                            type: this.getType(prop.getTypeAtLocation(funcDecl).getText()),
-                            optional: prop.isOptional() ? true : undefined,
-                            defaultValue: undefined,
-                        };
-                        returns[name] = variable;
-                        return;
-                    }
-                    if (!outputTypeDef[name]) {
-                        throw new Error(`[Action Validation] Action "${actionName}" in ${file}: return property "${name}" is missing ` +
-                            `a @property entry in the "output" JSDoc typedef. Please add ` +
-                            `"@property {type} ${name} - description" to the JSDoc.` +
-                            `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
-                    }
-                    if (!outputTypeDef[name]?.description?.trim()) {
-                        throw new Error(`[Action Validation] Action "${actionName}" in ${file}: return property "${name}" has an empty ` +
-                            `description in the JSDoc @property. Please provide a meaningful description.` +
-                            `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
-                    }
-                    const variable = {
-                        description: outputTypeDef[name]?.description ?? "",
-                        type: this.getType(outputTypeDef[name]?.type ?? ""),
-                        optional: prop.isOptional() ? true : undefined,
-                        defaultValue: undefined,
-                    };
-                    returns[name] = variable;
-                });
-                actions.push({
-                    name: actionName,
-                    description,
-                    parameters: params,
-                    returns,
-                });
-            });
-        });
-        // You can now register `actions` in Module Federation or expose them as needed
-        // Register actions in pulse config for runtime access
-        this.pulseConfig.actions = actions;
-    }
-    parseTypeDefs(jsDocs) {
-        const typeDefs = {};
-        // Match @typedef {Type} Name
-        const typedefRegex = /@typedef\s+{([^}]+)}\s+([^\s-]+)/g;
-        // Match @property {Type} [name] Description text...
-        const propertyRegex = /@property\s+{([^}]+)}\s+(\[?[^\]\s]+\]?)\s*-?\s*(.*)/g;
-        jsDocs.forEach((doc) => {
-            const text = doc.getFullText();
-            let typedefMatches;
-            while ((typedefMatches = typedefRegex.exec(text)) !== null) {
-                const typeName = typedefMatches[2];
-                if (!typeName)
-                    continue;
-                const properties = {};
-                let propertyMatches;
-                while ((propertyMatches = propertyRegex.exec(text)) !== null) {
-                    const propName = this.normalizeJSDocPropertyName(propertyMatches[2]);
-                    const propType = propertyMatches[1];
-                    const propDescription = propertyMatches[3] || "";
-                    if (propName && propType) {
-                        properties[propName] = {
-                            type: propType,
-                            description: propDescription.trim(),
-                        };
-                    }
-                }
-                typeDefs[typeName.toLowerCase()] = properties;
-            }
-        });
-        return typeDefs;
-    }
-    normalizeJSDocPropertyName(name) {
-        if (!name)
-            return "";
-        return name
-            .trim()
-            .replace(/^\[/, "")
-            .replace(/\]$/, "")
-            .split("=")[0]
-            ?.trim();
-    }
-    isPromiseLikeType(type) {
-        const symbolName = type.getSymbol()?.getName();
-        return symbolName === "Promise" || symbolName === "PromiseLike";
-    }
-    unwrapPromiseLikeType(type) {
-        const symbolName = type.getSymbol()?.getName();
-        if ((symbolName === "Promise" || symbolName === "PromiseLike") &&
-            type.getTypeArguments().length > 0) {
-            return type.getTypeArguments()[0] ?? type;
-        }
-        return type;
-    }
-    getType(text) {
-        if (text === "string")
-            return "string";
-        if (text === "number")
-            return "number";
-        if (text === "boolean")
-            return "boolean";
-        if (text === "any")
-            return "object";
-        if (text.endsWith("[]"))
-            return [this.getType(text.slice(0, -2))];
-        if (text.length === 0)
-            return "undefined";
-        console.warn(`[Type Warning] Unrecognized type "${text}". Consider adding explicit types in your action's JSDoc comments for better type safety and documentation.`);
-        return text;
-    }
     printChanges(compiler) {
         const modified = compiler.modifiedFiles
             ? Array.from(compiler.modifiedFiles)

package/dist/lib/webpack/configs/preview.d.ts

@@ -1,3 +1,4 @@
 import { Configuration as WebpackConfig } from "webpack";
 import { Configuration as DevServerConfig } from "webpack-dev-server";
+export declare function makeMFPreviewConfig(): Promise<WebpackConfig>;
 export declare function makePreviewClientConfig(mode: "development" | "production"): Promise<WebpackConfig & DevServerConfig>;

package/dist/lib/webpack/configs/preview.js

@@ -1,10 +1,133 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import mfNode from "@module-federation/node";
 import CopyWebpackPlugin from "copy-webpack-plugin";
 import fs from "fs";
 import HtmlWebpackPlugin from "html-webpack-plugin";
 import MiniCssExtractPlugin from "mini-css-extract-plugin";
 import path from "path";
-import { getLocalNetworkIP, loadPulseConfig } from "./utils.js";
+import wp from "webpack";
+import { compileAppActionSkills, discoverAppSkillActions, getLocalNetworkIP, loadPulseConfig, } from "./utils.js";
+const { NodeFederationPlugin } = mfNode;
+const { webpack } = wp;
+class MFPreviewPlugin {
+    projectDirName;
+    pulseConfig;
+    constructor(pulseConfig) {
+        this.projectDirName = process.cwd();
+        this.pulseConfig = pulseConfig;
+    }
+    apply(compiler) {
+        let isFirstRun = true;
+        compiler.hooks.environment.tap("WatchSkillPlugin", () => {
+            compiler.hooks.thisCompilation.tap("WatchActions", (compilation) => {
+                compilation.contextDependencies.add(path.resolve(this.projectDirName, "src/skill"));
+            });
+        });
+        compiler.hooks.watchRun.tap("MFPreviewPlugin", async () => {
+            if (!isFirstRun) {
+                const isActionChange = compiler.modifiedFiles
+                    ? Array.from(compiler.modifiedFiles).some((file) => file.includes("src/skill"))
+                    : false;
+                if (isActionChange) {
+                    console.log("[preview-server] Detected changes in actions. Recompiling...");
+                    await this.compileActions(compiler);
+                }
+            }
+            else {
+                console.log("[preview-server] 🔄 Building...");
+                await this.compileActions(compiler);
+                console.log("[preview-server] ✅ Successfully built preview server.");
+            }
+        });
+        compiler.hooks.done.tap("MFPreviewPlugin", () => {
+            if (isFirstRun) {
+                isFirstRun = false;
+            }
+            else {
+                console.log("[preview-server] ✅ Reload finished.");
+            }
+            fs.writeFileSync(path.resolve(this.projectDirName, "dist/pulse.config.json"), JSON.stringify(this.pulseConfig, null, 2));
+        });
+    }
+    makeNodeFederationPlugin() {
+        const actions = discoverAppSkillActions();
+        return new NodeFederationPlugin({
+            name: this.pulseConfig.id + "_server",
+            remoteType: "script",
+            useRuntimePlugin: true,
+            library: { type: "commonjs-module" },
+            filename: "remoteEntry.js",
+            exposes: { ...actions },
+        }, {});
+    }
+    async compileActions(compiler) {
+        compileAppActionSkills(this.pulseConfig);
+        const options = {
+            ...compiler.options,
+            watch: false,
+            plugins: [this.makeNodeFederationPlugin()],
+        };
+        const newCompiler = webpack(options);
+        return new Promise((resolve, reject) => {
+            newCompiler?.run((err, stats) => {
+                if (err) {
+                    console.error("[preview-server] ❌ Error during recompilation:", err);
+                    reject(err);
+                }
+                else if (stats?.hasErrors()) {
+                    console.error("[preview-server] ❌ Compilation errors:", stats.toJson().errors);
+                    reject(new Error("Compilation errors"));
+                }
+                else {
+                    console.log("[preview-server] ✅ Compiled actions successfully.");
+                    resolve();
+                }
+            });
+        });
+    }
+}
+export async function makeMFPreviewConfig() {
+    const projectDirName = process.cwd();
+    const pulseConfig = await loadPulseConfig();
+    return {
+        mode: "development",
+        name: "preview-server",
+        entry: {},
+        target: "async-node",
+        output: {
+            publicPath: "auto",
+            path: path.resolve(projectDirName, "dist/server"),
+        },
+        resolve: {
+            extensions: [".ts", ".js"],
+        },
+        plugins: [new MFPreviewPlugin(pulseConfig)],
+        module: {
+            rules: [
+                {
+                    test: /\.tsx?$/,
+                    use: {
+                        loader: "ts-loader",
+                        options: {
+                            configFile: "node_modules/.pulse/tsconfig.server.json",
+                        },
+                    },
+                    exclude: [/node_modules/, /dist/],
+                },
+            ],
+        },
+        stats: {
+            all: false,
+            errors: true,
+            warnings: true,
+            logging: "warn",
+            colors: true,
+        },
+        infrastructureLogging: {
+            level: "warn",
+        },
+    };
+}
 class PreviewClientPlugin {
     projectDirName;
     pulseConfig;
@@ -50,8 +173,6 @@ class PreviewClientPlugin {
             else {
                 console.log("[client-preview] ✅ Reload finished");
             }
-            // Write pulse config to dist
-            fs.writeFileSync(path.resolve(this.projectDirName, "dist/pulse.config.json"), JSON.stringify(this.pulseConfig, null, 2));
         });
     }
 }

package/dist/lib/webpack/configs/utils.d.ts

@@ -1,3 +1,5 @@
+import type { TypedVariableType } from "@pulse-editor/shared-utils/dist/types/types.js";
+import { JSDoc } from "ts-morph";
 export declare function loadPulseConfig(): Promise<any>;
 export declare function getLocalNetworkIP(): string;
 export declare function readConfigFile(): Promise<any>;
@@ -7,4 +9,13 @@ export declare function discoverServerFunctions(): {
 export declare function discoverAppSkillActions(): {
     [x: string]: string;
 } | null;
+export declare function parseTypeDefs(jsDocs: JSDoc[]): Record<string, Record<string, {
+    type: string;
+    description: string;
+}>>;
+export declare function normalizeJSDocPropertyName(name: string | undefined): string | undefined;
+export declare function isPromiseLikeType(type: import("ts-morph").Type): boolean;
+export declare function unwrapPromiseLikeType(type: import("ts-morph").Type): import("ts-morph").Type<import("ts-morph").ts.Type>;
+export declare function getActionType(text: string): TypedVariableType;
+export declare function compileAppActionSkills(pulseConfig: any): void;
 export declare function generateTempTsConfig(): void;

package/dist/lib/webpack/configs/utils.js

@@ -1,10 +1,9 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import { existsSync, writeFileSync } from "fs";
 import fs from "fs/promises";
 import { globSync } from "glob";
 import { networkInterfaces } from "os";
 import path from "path";
-import { Project, SyntaxKind } from "ts-morph";
+import { Node, Project, SyntaxKind } from "ts-morph";
 import ts from "typescript";
 import { pathToFileURL } from "url";
 export async function loadPulseConfig() {
@@ -143,6 +142,226 @@ export function discoverAppSkillActions() {
     }, {});
     return entryPoints;
 }
+export function parseTypeDefs(jsDocs) {
+    const typeDefs = {};
+    const typedefRegex = /@typedef\s+{([^}]+)}\s+([^\s-]+)/g;
+    const propertyRegex = /@property\s+{([^}]+)}\s+(\[?[^\]\s]+\]?)\s*-?\s*(.*)/g;
+    jsDocs.forEach((doc) => {
+        const text = doc.getFullText();
+        let typedefMatches;
+        while ((typedefMatches = typedefRegex.exec(text)) !== null) {
+            const typeName = typedefMatches[2];
+            if (!typeName)
+                continue;
+            const properties = {};
+            let propertyMatches;
+            while ((propertyMatches = propertyRegex.exec(text)) !== null) {
+                const propName = normalizeJSDocPropertyName(propertyMatches[2]);
+                const propType = propertyMatches[1];
+                const propDescription = propertyMatches[3] || "";
+                if (propName && propType) {
+                    properties[propName] = {
+                        type: propType,
+                        description: propDescription.trim(),
+                    };
+                }
+            }
+            typeDefs[typeName.toLowerCase()] = properties;
+        }
+    });
+    return typeDefs;
+}
+export function normalizeJSDocPropertyName(name) {
+    if (!name)
+        return "";
+    return name
+        .trim()
+        .replace(/^\[/, "")
+        .replace(/\]$/, "")
+        .split("=")[0]
+        ?.trim();
+}
+export function isPromiseLikeType(type) {
+    const symbolName = type.getSymbol()?.getName();
+    return symbolName === "Promise" || symbolName === "PromiseLike";
+}
+export function unwrapPromiseLikeType(type) {
+    const symbolName = type.getSymbol()?.getName();
+    if ((symbolName === "Promise" || symbolName === "PromiseLike") &&
+        type.getTypeArguments().length > 0) {
+        return type.getTypeArguments()[0] ?? type;
+    }
+    return type;
+}
+export function getActionType(text) {
+    if (text === "string")
+        return "string";
+    if (text === "number")
+        return "number";
+    if (text === "boolean")
+        return "boolean";
+    if (text === "any")
+        return "object";
+    if (text.endsWith("[]"))
+        return [getActionType(text.slice(0, -2))];
+    if (text.length === 0)
+        return "undefined";
+    console.warn(`[Type Warning] Unrecognized type "${text}". Consider adding explicit types in your action's JSDoc comments for better type safety and documentation.`);
+    return text;
+}
+export function compileAppActionSkills(pulseConfig) {
+    const files = globSync("./src/skill/*/action.ts");
+    const project = new Project({
+        tsConfigFilePath: path.join(process.cwd(), "node_modules/.pulse/tsconfig.server.json"),
+    });
+    const actions = [];
+    files.forEach((file) => {
+        const sourceFile = project.addSourceFileAtPath(file);
+        const defaultExportSymbol = sourceFile.getDefaultExportSymbol();
+        if (!defaultExportSymbol)
+            return;
+        const defaultExportDeclarations = defaultExportSymbol.getDeclarations();
+        defaultExportDeclarations.forEach((declaration) => {
+            if (declaration.getKind() !== SyntaxKind.FunctionDeclaration)
+                return;
+            const funcDecl = declaration.asKindOrThrow(SyntaxKind.FunctionDeclaration);
+            const pattern = /src\/skill\/([^\/]+)\/action\.ts$/;
+            const match = file.replaceAll("\\", "/").match(pattern);
+            if (!match) {
+                console.warn(`File path ${file} does not match pattern ${pattern}. Skipping...`);
+                return;
+            }
+            const actionName = match[1];
+            if (!actionName) {
+                console.warn(`Could not extract action name from file path ${file}. Skipping...`);
+                return;
+            }
+            if (actions.some((action) => action.name === actionName)) {
+                throw new Error(`Duplicate action name "${actionName}" detected in file ${file}. Please ensure all actions have unique names to avoid conflicts.`);
+            }
+            const defaultExportJSDocs = funcDecl.getJsDocs();
+            const descriptionText = defaultExportJSDocs
+                .map((doc) => doc.getDescription().replace(/^\*+/gm, "").trim())
+                .join("\n")
+                .trim();
+            if (defaultExportJSDocs.length === 0 || !descriptionText) {
+                throw new Error(`[Action Validation] Action "${actionName}" in ${file} is missing a JSDoc description. ` +
+                    `Please add a JSDoc comment block with a description above the function.` +
+                    `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
+            }
+            const description = defaultExportJSDocs
+                .map((doc) => doc.getFullText())
+                .join("\n");
+            const allJSDocs = sourceFile.getDescendantsOfKind(SyntaxKind.JSDoc);
+            const typeDefs = parseTypeDefs(allJSDocs);
+            const funcParam = funcDecl.getParameters()[0];
+            const params = {};
+            if (funcParam) {
+                const defaults = new Map();
+                const nameNode = funcParam.getNameNode();
+                if (Node.isObjectBindingPattern(nameNode)) {
+                    nameNode.getElements().forEach((el) => {
+                        if (!Node.isBindingElement(el))
+                            return;
+                        const name = el.getName();
+                        const initializer = el.getInitializer()?.getText();
+                        if (initializer) {
+                            defaults.set(name, initializer);
+                        }
+                    });
+                }
+                const paramProperties = funcParam.getType().getProperties();
+                const inputTypeDef = typeDefs["input"] ?? {};
+                if (paramProperties.length > 0 && !typeDefs["input"]) {
+                    throw new Error(`[Action Validation] Action "${actionName}" in ${file} has parameters but is missing an ` +
+                        `"@typedef {Object} input" JSDoc block. Please document all parameters with ` +
+                        `@typedef {Object} input and @property tags.` +
+                        `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
+                }
+                paramProperties.forEach((prop) => {
+                    const name = prop.getName();
+                    if (!inputTypeDef[name]) {
+                        throw new Error(`[Action Validation] Action "${actionName}" in ${file}: parameter "${name}" is missing ` +
+                            `a @property entry in the "input" JSDoc typedef. Please add ` +
+                            `"@property {type} ${name} - description" to the JSDoc.` +
+                            `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
+                    }
+                    if (!inputTypeDef[name]?.description?.trim()) {
+                        throw new Error(`[Action Validation] Action "${actionName}" in ${file}: parameter "${name}" has an empty ` +
+                            `description in the JSDoc @property. Please provide a meaningful description.` +
+                            `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
+                    }
+                    const variable = {
+                        description: inputTypeDef[name]?.description ?? "",
+                        type: getActionType(inputTypeDef[name]?.type ?? ""),
+                        optional: prop.isOptional() ? true : undefined,
+                        defaultValue: defaults.get(name),
+                    };
+                    params[name] = variable;
+                });
+            }
+            const rawReturnType = funcDecl.getReturnType();
+            const isPromiseLikeReturn = isPromiseLikeType(rawReturnType);
+            const returnType = unwrapPromiseLikeType(rawReturnType);
+            if (!returnType.isObject()) {
+                console.warn(`[Action Registration] Function ${actionName}'s return type should be an object. Skipping...`);
+                return;
+            }
+            const returns = {};
+            const returnProperties = returnType.getProperties();
+            const outputTypeDef = typeDefs["output"] ?? {};
+            const hasOutputTypeDef = !!typeDefs["output"];
+            if (returnProperties.length > 0 && !hasOutputTypeDef && !isPromiseLikeReturn) {
+                throw new Error(`[Action Validation] Action "${actionName}" in ${file} returns properties but is missing an ` +
+                    `"@typedef {Output}" JSDoc block. Please document all return values with ` +
+                    `@typedef {Output} and @property tags.` +
+                    `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
+            }
+            if (returnProperties.length > 0 && !hasOutputTypeDef && isPromiseLikeReturn) {
+                console.warn(`[Action Validation] Action "${actionName}" in ${file} is missing an "@typedef {Object} output" JSDoc block. ` +
+                    `Falling back to TypeScript-inferred return metadata because the action returns a Promise.`);
+            }
+            returnProperties.forEach((prop) => {
+                const name = prop.getName();
+                if (!hasOutputTypeDef) {
+                    const variable = {
+                        description: "",
+                        type: getActionType(prop.getTypeAtLocation(funcDecl).getText()),
+                        optional: prop.isOptional() ? true : undefined,
+                        defaultValue: undefined,
+                    };
+                    returns[name] = variable;
+                    return;
+                }
+                if (!outputTypeDef[name]) {
+                    throw new Error(`[Action Validation] Action "${actionName}" in ${file}: return property "${name}" is missing ` +
+                        `a @property entry in the "output" JSDoc typedef. Please add ` +
+                        `"@property {type} ${name} - description" to the JSDoc.` +
+                        `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
+                }
+                if (!outputTypeDef[name]?.description?.trim()) {
+                    throw new Error(`[Action Validation] Action "${actionName}" in ${file}: return property "${name}" has an empty ` +
+                        `description in the JSDoc @property. Please provide a meaningful description.` +
+                        `Run \`pulse skill fix ${actionName}\` to automatically add a JSDoc template for this action.`);
+                }
+                const variable = {
+                    description: outputTypeDef[name]?.description ?? "",
+                    type: getActionType(outputTypeDef[name]?.type ?? ""),
+                    optional: prop.isOptional() ? true : undefined,
+                    defaultValue: undefined,
+                };
+                returns[name] = variable;
+            });
+            actions.push({
+                name: actionName,
+                description,
+                parameters: params,
+                returns,
+            });
+        });
+    });
+    pulseConfig.actions = actions;
+}
 // Generate tsconfig for server functions
 export function generateTempTsConfig() {
     const tempTsConfigPath = path.join(process.cwd(), "node_modules/.pulse/tsconfig.server.json");

package/dist/lib/webpack/webpack-config.js

@@ -1,12 +1,12 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { makeMFClientConfig } from "./configs/mf-client.js";
 import { makeMFServerConfig } from "./configs/mf-server.js";
-import { makePreviewClientConfig } from "./configs/preview.js";
+import { makeMFPreviewConfig, makePreviewClientConfig } from "./configs/preview.js";
 export async function createWebpackConfig(isPreview, buildTarget, mode) {
     if (isPreview) {
         const previewClientConfig = await makePreviewClientConfig("development");
-        const mfServerConfig = await makeMFServerConfig("development");
-        return [previewClientConfig, mfServerConfig];
+        const mfPreviewConfig = await makeMFPreviewConfig();
+        return [previewClientConfig, mfPreviewConfig];
     }
     else if (buildTarget === "server") {
         const mfServerConfig = await makeMFServerConfig(mode);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pulse-editor/cli",
-	"version": "0.1.4",
+	"version": "0.1.5",
 	"license": "MIT",
 	"bin": {
 		"pulse": "dist/cli.js"