@synergenius/flow-weaver 0.10.7 → 0.10.9

package/dist/mcp/prompts.js

@@ -0,0 +1,68 @@
+const NOCODE_SYSTEM_PROMPT = `You are a workflow developer powered by Flow Weaver. You write real, production-quality TypeScript behind the scenes, but you present everything to the user as plain-language step descriptions, connections, and diagrams. The user never needs to see code unless they ask for it.
+
+## How you work
+
+When the user describes a workflow:
+
+1. Break their description into discrete steps (nodes), each with typed inputs and outputs.
+2. Call fw_create_model to generate the workflow skeleton with declare stubs.
+3. Call fw_implement_node for each step, writing real TypeScript function bodies that do what the user described. Write actual working code, not placeholder comments.
+4. Call fw_validate to check the result. If there are errors you can fix (missing connections, type mismatches), fix them silently with fw_modify. Only tell the user about problems you genuinely cannot resolve.
+5. Show the result as:
+   - A numbered list of steps with one-sentence descriptions
+   - An ASCII diagram (call fw_diagram with format "ascii-compact")
+   Never show TypeScript code in this summary.
+
+When the user asks to modify an existing workflow:
+- Use fw_modify or fw_modify_batch for structural changes (add/remove nodes, connections).
+- Use fw_implement_node to update a step's logic.
+- Re-validate after every change.
+
+## When to show code
+
+Only reveal TypeScript when the user explicitly asks: "show me the code", "let me see the implementation", "what does step X look like", etc. When showing code, use fw_describe with format "text" or read the file directly.
+
+## Tool usage patterns
+
+- fw_create_model: Create new workflows from a structured description (steps, inputs/outputs, flow path).
+- fw_implement_node: Replace a declare stub with a real function body.
+- fw_modify / fw_modify_batch: Add/remove nodes and connections, rename nodes, reposition.
+- fw_validate: Always run after changes. Fix what you can, report what you cannot.
+- fw_describe: Inspect workflow structure. Use format "text" for human-readable, "json" for programmatic.
+- fw_diagram: Generate visual representation. Prefer format "ascii-compact" for chat.
+- fw_workflow_status: Check which steps are implemented vs still stubs.
+- fw_scaffold / fw_list_templates: Bootstrap from templates when the user's request matches a known pattern.
+- fw_docs: Look up Flow Weaver features (scoped ports, branching, iteration, agents) when you need specifics.
+- fw_find_workflows: Locate existing workflow files in a directory.
+- fw_compile: Generate executable JavaScript from the workflow source.
+
+## Interaction style
+
+- Ask 1-2 clarifying questions when the request is vague, not a long interrogation list.
+- Default to sensible choices for things the user did not specify (file names, port types, node names).
+- After creating or modifying a workflow, always show the step summary and ASCII diagram.
+- Use fw_docs to look up advanced features before guessing at syntax.
+
+## File conventions
+
+- Workflow files use .ts extension.
+- Default location is the current working directory.
+- Node names use camelCase (e.g., validateEmail, sendNotification).
+- Workflow names use PascalCase (e.g., EmailValidation, OrderProcessing).`;
+export function registerPrompts(mcp) {
+    mcp.registerPrompt('flow-weaver-nocode', {
+        title: 'Flow Weaver No-Code Mode',
+        description: 'Describe workflows in plain language. The agent writes real TypeScript behind the scenes and presents results as step summaries and diagrams. Code is available on request.',
+    }, () => ({
+        messages: [
+            {
+                role: 'assistant',
+                content: {
+                    type: 'text',
+                    text: NOCODE_SYSTEM_PROMPT,
+                },
+            },
+        ],
+    }));
+}
+//# sourceMappingURL=prompts.js.map

package/dist/mcp/server.js

@@ -14,6 +14,7 @@ import { registerDiagramTools } from './tools-diagram.js';
 import { registerDocsTools } from './tools-docs.js';
 import { registerModelTools } from './tools-model.js';
 import { registerResources } from './resources.js';
+import { registerPrompts } from './prompts.js';
 function parseEventFilterFromEnv() {
     const filter = {};
     const include = process.env.FW_EVENT_INCLUDE;
@@ -75,6 +76,7 @@ export async function startMcpServer(options) {
     registerDocsTools(mcp);
     registerModelTools(mcp);
     registerResources(mcp, connection, buffer);
+    registerPrompts(mcp);
     // Connect transport (only in stdio MCP mode)
     if (!options._testDeps && options.stdio) {
         const transport = new StdioServerTransport();

package/dist/mcp/tools-diagram.d.ts

@@ -1,7 +1,8 @@
 /**
  * MCP Diagram Tool - fw_diagram
  *
- * Generates SVG or interactive HTML diagrams from workflow files.
+ * Generates diagrams from workflow files or inline source code.
+ * Supports SVG, interactive HTML, and ASCII text formats.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerDiagramTools(mcp: McpServer): void;

package/dist/mcp/tools-diagram.js

@@ -1,20 +1,30 @@
 /**
  * MCP Diagram Tool - fw_diagram
  *
- * Generates SVG or interactive HTML diagrams from workflow files.
+ * Generates diagrams from workflow files or inline source code.
+ * Supports SVG, interactive HTML, and ASCII text formats.
  */
 import { z } from 'zod';
 import * as fs from 'fs';
 import * as path from 'path';
-import { fileToSVG, fileToHTML } from '../diagram/index.js';
+import { fileToSVG, fileToHTML, fileToASCII, sourceToSVG, sourceToHTML, sourceToASCII } from '../diagram/index.js';
 import { makeToolResult, makeErrorResult } from './response-utils.js';
+const ASCII_FORMATS = new Set(['ascii', 'ascii-compact', 'text']);
 export function registerDiagramTools(mcp) {
-    mcp.tool('fw_diagram', 'Generate an SVG diagram of a workflow. Returns SVG string or writes to a file.', {
-        filePath: z.string().describe('Path to the workflow .ts file'),
+    mcp.tool('fw_diagram', 'Generate a diagram of a workflow. Formats: svg/html produce visual markup, ascii/ascii-compact/text produce plain text readable in terminal. ' +
+        'Provide either filePath (workflow .ts file) or source (inline code).', {
+        filePath: z
+            .string()
+            .optional()
+            .describe('Path to the workflow .ts file (required if source is not provided)'),
+        source: z
+            .string()
+            .optional()
+            .describe('Inline workflow source code (required if filePath is not provided)'),
         outputPath: z
             .string()
             .optional()
-            .describe('Output file path for the SVG. If omitted, returns SVG as text.'),
+            .describe('Output file path. If omitted, returns content as text.'),
         workflowName: z
             .string()
             .optional()
@@ -28,24 +38,50 @@ export function registerDiagramTools(mcp) {
             .optional()
             .describe('Show port labels on diagram (default: true)'),
         format: z
-            .enum(['svg', 'html'])
+            .enum(['svg', 'html', 'ascii', 'ascii-compact', 'text'])
             .optional()
-            .describe('Output format: svg (default) or html (interactive viewer)'),
+            .describe('Output format: svg (default), html (interactive viewer), ascii (port-level detail), ascii-compact (compact boxes), text (structured list)'),
     }, async (args) => {
         try {
-            const resolvedPath = path.resolve(args.filePath);
-            if (!fs.existsSync(resolvedPath)) {
-                return makeErrorResult('FILE_NOT_FOUND', `File not found: ${resolvedPath}`);
+            if (!args.filePath && !args.source) {
+                return makeErrorResult('MISSING_PARAM', 'Provide either filePath or source parameter');
             }
+            const format = args.format ?? 'svg';
             const diagramOptions = {
                 workflowName: args.workflowName,
                 theme: args.theme,
                 showPortLabels: args.showPortLabels,
+                format,
             };
-            const isHtml = args.format === 'html';
-            const result = isHtml
-                ? fileToHTML(resolvedPath, diagramOptions)
-                : fileToSVG(resolvedPath, diagramOptions);
+            let result;
+            if (args.source) {
+                // Inline source code
+                if (ASCII_FORMATS.has(format)) {
+                    result = sourceToASCII(args.source, diagramOptions);
+                }
+                else if (format === 'html') {
+                    result = sourceToHTML(args.source, diagramOptions);
+                }
+                else {
+                    result = sourceToSVG(args.source, diagramOptions);
+                }
+            }
+            else {
+                // File path
+                const resolvedPath = path.resolve(args.filePath);
+                if (!fs.existsSync(resolvedPath)) {
+                    return makeErrorResult('FILE_NOT_FOUND', `File not found: ${resolvedPath}`);
+                }
+                if (ASCII_FORMATS.has(format)) {
+                    result = fileToASCII(resolvedPath, diagramOptions);
+                }
+                else if (format === 'html') {
+                    result = fileToHTML(resolvedPath, diagramOptions);
+                }
+                else {
+                    result = fileToSVG(resolvedPath, diagramOptions);
+                }
+            }
             if (args.outputPath) {
                 const outputResolved = path.resolve(args.outputPath);
                 fs.writeFileSync(outputResolved, result, 'utf-8');

package/dist/mcp/tools-query.js

@@ -21,9 +21,9 @@ export function registerQueryTools(mcp) {
     mcp.tool('fw_describe', 'Describe a workflow in LLM-friendly format (nodes, connections, graph, validation).', {
         filePath: z.string().describe('Path to the workflow .ts file'),
         format: z
-            .enum(['json', 'text', 'mermaid', 'paths'])
+            .enum(['json', 'text', 'mermaid', 'paths', 'ascii', 'ascii-compact'])
             .optional()
-            .describe('Output format (default: json)'),
+            .describe('Output format (default: json). ascii/ascii-compact produce terminal-readable diagrams.'),
         node: z.string().optional().describe('Focus on a specific node ID'),
         workflowName: z.string().optional().describe('Specific workflow if file has multiple'),
     }, async (args) => {

package/dist/parser.d.ts

@@ -166,6 +166,12 @@ export declare class AnnotationParser {
      * Returns a map of property names to their TypeScript type strings.
      */
     private extractTypeSchema;
+    /**
+     * Check if a type should be expanded into individual ports via getProperties().
+     * Returns true for object literals and interfaces, false for primitives, arrays,
+     * and built-in types whose properties are prototype methods (string, number, etc.).
+     */
+    private isExpandableObjectType;
     private inferPortType;
     /**
      * Check if a function has a valid @flowWeaver annotation (nodeType, workflow, or pattern).

package/dist/parser.js

@@ -1799,32 +1799,52 @@ export class AnnotationParser {
             else {
                 ports.execute = { dataType: 'STEP', tsType: 'boolean', label: 'Execute' };
             }
-            // Extract data ports from second parameter if it exists
+            // Extract data ports from parameters beyond execute
             if (params.length > 1) {
-                const dataParam = params[1];
-                const dataParamType = dataParam.getType();
-                const properties = dataParamType.getProperties();
-                properties.forEach((prop) => {
-                    const propName = prop.getName();
-                    const propType = prop.getTypeAtLocation(dataParam);
-                    const portType = this.inferPortType(propType);
-                    const propTypeText = propType.getText();
-                    // Extract schema for complex types (interfaces/objects)
-                    const tsSchema = portType === 'OBJECT' ? this.extractTypeSchema(propType) : undefined;
-                    // Check if JSDoc has explicit metadata override for this start port (from @param annotation)
-                    // Always prefer ts-morph inferred type over JSDoc regex-based inference
-                    // (JSDoc @param type inference uses regex which can fail for complex types)
-                    const startPortConfig = config?.startPorts?.[propName];
-                    ports[propName] = {
-                        dataType: portType,
-                        label: startPortConfig?.label || this.capitalize(propName),
-                        ...(startPortConfig?.metadata && { metadata: startPortConfig.metadata }),
-                        // Include original TS type for rich type display
-                        ...(propTypeText && { tsType: propTypeText }),
-                        // Include schema breakdown for complex types
-                        ...(tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }),
-                    };
-                });
+                // Filter out __abortSignal__ which is injected by generateInPlace and
+                // is not a user-visible port.
+                const dataParams = params.slice(1).filter(p => p.getName() !== '__abortSignal__');
+                // Multiple separate params: each becomes its own port
+                // Single param with object type: expand its properties into ports
+                const shouldExpandProperties = dataParams.length === 1 && this.isExpandableObjectType(dataParams[0].getType());
+                if (shouldExpandProperties) {
+                    const dataParam = dataParams[0];
+                    const dataParamType = dataParam.getType();
+                    const properties = dataParamType.getProperties();
+                    properties.forEach((prop) => {
+                        const propName = prop.getName();
+                        const propType = prop.getTypeAtLocation(dataParam);
+                        const portType = this.inferPortType(propType);
+                        const propTypeText = propType.getText();
+                        const tsSchema = portType === 'OBJECT' ? this.extractTypeSchema(propType) : undefined;
+                        const startPortConfig = config?.startPorts?.[propName];
+                        ports[propName] = {
+                            dataType: portType,
+                            label: startPortConfig?.label || this.capitalize(propName),
+                            ...(startPortConfig?.metadata && { metadata: startPortConfig.metadata }),
+                            ...(propTypeText && { tsType: propTypeText }),
+                            ...(tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }),
+                        };
+                    });
+                }
+                else {
+                    // Each parameter becomes its own port
+                    for (const param of dataParams) {
+                        const paramName = param.getName();
+                        const paramType = param.getType();
+                        const portType = this.inferPortType(paramType);
+                        const paramTypeText = paramType.getText(param);
+                        const tsSchema = portType === 'OBJECT' ? this.extractTypeSchema(paramType) : undefined;
+                        const startPortConfig = config?.startPorts?.[paramName];
+                        ports[paramName] = {
+                            dataType: portType,
+                            label: startPortConfig?.label || this.capitalize(paramName),
+                            ...(startPortConfig?.metadata && { metadata: startPortConfig.metadata }),
+                            ...(paramTypeText && { tsType: paramTypeText }),
+                            ...(tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }),
+                        };
+                    }
+                }
             }
         }
         else {
@@ -1923,6 +1943,20 @@ export class AnnotationParser {
         }
         return Object.keys(schema).length > 0 ? schema : undefined;
     }
+    /**
+     * Check if a type should be expanded into individual ports via getProperties().
+     * Returns true for object literals and interfaces, false for primitives, arrays,
+     * and built-in types whose properties are prototype methods (string, number, etc.).
+     */
+    isExpandableObjectType(tsType) {
+        const typeText = tsType.getText();
+        const primitiveTypes = new Set(['string', 'number', 'boolean', 'any', 'unknown', 'never', 'object', 'Object']);
+        if (primitiveTypes.has(typeText))
+            return false;
+        if (typeText.endsWith('[]') || typeText.startsWith('Array<'))
+            return false;
+        return tsType.isObject() && tsType.getProperties().length > 0;
+    }
     inferPortType(tsType) {
         const typeText = tsType.getText();
         // Delegate to inferDataTypeFromTS for consistent type mapping

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.10.7",
+  "version": "0.10.9",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",