@synergenius/flow-weaver 0.20.1 → 0.20.3

package/dist/cli/index.js

@@ -39,6 +39,7 @@ import { docsListCommand, docsReadCommand, docsSearchCommand } from './commands/
 import { contextCommand } from './commands/context.js';
 import { statusCommand } from './commands/status.js';
 import { implementCommand } from './commands/implement.js';
+import { modifyAddNodeCommand, modifyRemoveNodeCommand, modifyAddConnectionCommand, modifyRemoveConnectionCommand, modifyRenameNodeCommand, modifySetPositionCommand, modifySetLabelCommand, } from './commands/modify.js';
 import { marketInitCommand, marketPackCommand, marketPublishCommand, marketInstallCommand, marketSearchCommand, marketListCommand, } from './commands/market.js';
 import { mcpSetupCommand } from './commands/mcp-setup.js';
 import { logger } from './utils/logger.js';
@@ -352,6 +353,71 @@ createCmd
     .action(wrapAction(async (name, file, options) => {
     await createNodeCommand(name, file, options);
 }));
+// Modify command (with subcommands)
+const modifyCmd = program.command('modify').description('Modify workflow structure');
+modifyCmd
+    .command('addNode')
+    .description('Add a node instance to a workflow')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--nodeId <id>', 'Node instance ID')
+    .requiredOption('--nodeType <type>', 'Node type name')
+    .action(wrapAction(async (options) => {
+    await modifyAddNodeCommand(options.file, options);
+}));
+modifyCmd
+    .command('removeNode')
+    .description('Remove a node instance from a workflow')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--nodeId <id>', 'Node instance ID')
+    .action(wrapAction(async (options) => {
+    await modifyRemoveNodeCommand(options.file, options);
+}));
+modifyCmd
+    .command('addConnection')
+    .description('Add a connection between nodes')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--from <node.port>', 'Source (e.g. nodeA.output)')
+    .requiredOption('--to <node.port>', 'Target (e.g. nodeB.input)')
+    .action(wrapAction(async (options) => {
+    await modifyAddConnectionCommand(options.file, options);
+}));
+modifyCmd
+    .command('removeConnection')
+    .description('Remove a connection between nodes')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--from <node.port>', 'Source (e.g. nodeA.output)')
+    .requiredOption('--to <node.port>', 'Target (e.g. nodeB.input)')
+    .action(wrapAction(async (options) => {
+    await modifyRemoveConnectionCommand(options.file, options);
+}));
+modifyCmd
+    .command('renameNode')
+    .description('Rename a node instance (updates all connections)')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--oldId <id>', 'Current node ID')
+    .requiredOption('--newId <id>', 'New node ID')
+    .action(wrapAction(async (options) => {
+    await modifyRenameNodeCommand(options.file, options);
+}));
+modifyCmd
+    .command('setPosition')
+    .description('Set position of a node instance')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--nodeId <id>', 'Node instance ID')
+    .requiredOption('--x <number>', 'X coordinate')
+    .requiredOption('--y <number>', 'Y coordinate')
+    .action(wrapAction(async (options) => {
+    await modifySetPositionCommand(options.file, options);
+}));
+modifyCmd
+    .command('setLabel')
+    .description('Set display label for a node instance')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--nodeId <id>', 'Node instance ID')
+    .requiredOption('--label <text>', 'Display label')
+    .action(wrapAction(async (options) => {
+    await modifySetLabelCommand(options.file, options);
+}));
 // Templates command
 program
     .command('templates')
@@ -503,14 +569,19 @@ program
 }));
 // Implement command
 program
-    .command('implement <input> <node>')
+    .command('implement <input> [node]')
     .description('Replace a stub node with a real function skeleton')
     .option('-w, --workflow <name>', 'Specific workflow name')
+    .option('--nodeId <id>', 'Node to implement (alternative to positional arg)')
     .option('-p, --preview', 'Preview the generated code without writing', false)
     .action(wrapAction(async (input, node, options) => {
+    const nodeName = node ?? options.nodeId;
+    if (!nodeName) {
+        throw new Error('Node name is required (as positional arg or --nodeId flag)');
+    }
     if (options.workflow)
         options.workflowName = options.workflow;
-    await implementCommand(input, node, options);
+    await implementCommand(input, nodeName, options);
 }));
 // Changelog command
 program

package/dist/cli/templates/workflows/aggregator.js

@@ -68,9 +68,9 @@ function combineData(dataA: any, dataB: any): { aggregated: any } {
 
 /**
  * @flowWeaver workflow
- * @node sourceA fetchSourceA [position: -180 -90]
- * @node sourceB fetchSourceB [position: -180 90]
- * @node combiner combineData [position: 90 0]
+ * @node sourceA fetchSourceA [position: -180 -90] [color: "blue"] [icon: "download"]
+ * @node sourceB fetchSourceB [position: -180 90] [color: "blue"] [icon: "download"]
+ * @node combiner combineData [position: 90 0] [color: "purple"] [icon: "callMerge"]
  * @position Start -450 0
  * @position Exit 360 0
  * @connect Start.execute -> sourceA.execute

package/dist/cli/templates/workflows/ai-agent.js

@@ -283,9 +283,9 @@ async function executeTools(
  * AI Agent that uses tools to accomplish tasks
  *
  * @flowWeaver workflow
- * @node loop agentLoop [size: 450 350] [position: -180 0]
- * @node llm callLLM loop.iteration [position: -40 100]
- * @node tools executeTools loop.iteration [position: 120 200]
+ * @node loop agentLoop [position: -180 0] [color: "purple"] [icon: "smartToy"]
+ * @node llm callLLM loop.iteration [color: "blue"] [icon: "psychology"]
+ * @node tools executeTools loop.iteration [color: "orange"] [icon: "build"] [suppress: "AGENT_UNGUARDED_TOOL_EXECUTOR"]
  * @position Start -450 0
  * @position Exit 360 0
  * @connect Start.execute -> loop.execute

package/dist/cli/templates/workflows/ai-chat.js

@@ -39,7 +39,7 @@ Be concise but friendly. Remember context from earlier in the conversation.\`;
  * @flowWeaver nodeType
  * @label Memory
  * @input conversationId [order:1] - Conversation identifier
- * @input newMessage [order:2] - Message to add
+ * @input [newMessage] [order:2] - Message to add
  * @input [maxHistory=50] [order:3] - Max messages to retain
  * @input execute [order:0] - Execute
  * @output history [order:2] - Conversation history
@@ -127,9 +127,9 @@ async function chat(
  * Stateful chat with conversation memory
  *
  * @flowWeaver workflow
- * @node mem memory [position: -150 0]
- * @node respond chat [position: 50 0]
- * @node saveMem memory [position: 250 0]
+ * @node mem memory [position: -150 0] [color: "teal"] [icon: "database"]
+ * @node respond chat [position: 50 0] [color: "purple"] [icon: "campaign"] [suppress: "AGENT_LLM_NO_FALLBACK"]
+ * @node saveMem memory [position: 250 0] [color: "teal"] [icon: "database"] [suppress: "UNUSED_OUTPUT_PORT"]
  * @position Start -350 0
  * @position Exit 450 0
  * @connect Start.execute -> mem.execute
@@ -140,6 +140,7 @@ async function chat(
  * @connect Start.conversationId -> saveMem.conversationId
  * @connect respond.responseMessage -> saveMem.newMessage
  * @connect respond.onSuccess -> saveMem.execute
+ * @connect respond.onFailure -> Exit.onFailure
  * @connect respond.response -> Exit.response
  * @connect saveMem.onSuccess -> Exit.onSuccess
  * @param execute [order:0] - Execute

package/dist/cli/templates/workflows/ai-rag.js

@@ -46,7 +46,7 @@ const documentStore: Document[] = [
  * @flowWeaver nodeType
  * @label Retrieve
  * @input query [order:1] - Search query
- * @input topK [order:2] - Number of results (default 3)
+ * @input [topK] [order:2] - Number of results (default 3)
  * @input execute [order:0] - Execute
  * @output documents [order:2] - Retrieved documents
  * @output context [order:3] - Combined document text
@@ -145,8 +145,8 @@ Answer:\`;
  * RAG Pipeline for knowledge-based Q&A
  *
  * @flowWeaver workflow
- * @node retriever retrieve [position: -50 0]
- * @node generator generate [position: 200 0]
+ * @node retriever retrieve [position: -50 0] [color: "teal"] [icon: "search"] [suppress: "UNUSED_OUTPUT_PORT"]
+ * @node generator generate [position: 200 0] [color: "purple"] [icon: "autoAwesome"]
  * @position Start -300 0
  * @position Exit 400 0
  * @connect Start.execute -> retriever.execute

package/dist/cli/templates/workflows/ai-react.js

@@ -247,25 +247,25 @@ async function act(
  * ReAct Agent — iterative Thought→Action→Observation loop
  *
  * @flowWeaver workflow
- * @node loop reactLoop [size: 450 250] [position: -150 0]
- * @node thinking think loop.step [position: -80 30]
- * @node acting act loop.step [position: 130 30]
+ * @node loop reactLoop [position: -150 0] [color: "purple"] [icon: "psychology"]
+ * @node thinking think loop.step [color: "blue"] [icon: "autoAwesome"]
+ * @node acting act loop.step [color: "orange"] [icon: "bolt"]
  * @position Start -400 0
  * @position Exit 350 0
  * @connect Start.execute -> loop.execute
  * @connect Start.task -> loop.task
- * @connect loop.start -> thinking.execute
- * @connect loop.messages -> thinking.messages
+ * @connect loop.start:step -> thinking.execute
+ * @connect loop.messages:step -> thinking.messages
  * @connect thinking.onSuccess -> acting.execute
  * @connect thinking.action -> acting.action
  * @connect thinking.actionInput -> acting.actionInput
- * @connect thinking.thought -> loop.thought
- * @connect thinking.action -> loop.action
- * @connect thinking.actionInput -> loop.actionInput
- * @connect thinking.onFailure -> loop.failure
- * @connect acting.observation -> loop.observation
- * @connect acting.onSuccess -> loop.success
- * @connect acting.onFailure -> loop.failure
+ * @connect thinking.thought -> loop.thought:step
+ * @connect thinking.action -> loop.action:step
+ * @connect thinking.actionInput -> loop.actionInput:step
+ * @connect thinking.onFailure -> loop.failure:step
+ * @connect acting.observation -> loop.observation:step
+ * @connect acting.onSuccess -> loop.success:step
+ * @connect acting.onFailure -> loop.failure:step
  * @connect loop.onSuccess -> Exit.onSuccess
  * @connect loop.onFailure -> Exit.onFailure
  * @connect loop.answer -> Exit.answer

package/dist/cli/templates/workflows/conditional.js

@@ -105,9 +105,9 @@ function handleFailure(
 
 /**
  * @flowWeaver workflow
- * @node router evaluateCondition [position: -180 0]
- * @node successHandler handleSuccess [position: 90 -90]
- * @node failureHandler handleFailure [position: 90 90]
+ * @node router evaluateCondition [position: -180 0] [color: "orange"] [icon: "altRoute"] [suppress: "UNUSED_OUTPUT_PORT"]
+ * @node successHandler handleSuccess [position: 90 -90] [color: "green"] [icon: "checkCircle"]
+ * @node failureHandler handleFailure [position: 90 90] [color: "red"] [icon: "error"]
  * @position Start -450 0
  * @position Exit 360 0
  * @connect Start.execute -> router.execute

package/dist/cli/templates/workflows/error-handler.js

@@ -105,8 +105,8 @@ function tryOperation(
 
 /**
  * @flowWeaver workflow
- * @node loop retryLoop [size: 300 200] [position: -90 0]
- * @node tryOp tryOperation loop.attempt [position: 90 0]
+ * @node loop retryLoop [position: -90 0] [color: "orange"] [icon: "refresh"]
+ * @node tryOp tryOperation loop.attempt [color: "blue"] [icon: "playArrow"]
  * @position Start -450 0
  * @position Exit 360 0
  * @connect Start.execute -> loop.execute

package/dist/cli/templates/workflows/foreach.js

@@ -101,9 +101,9 @@ function aggregateResults(
 
 /**
  * @flowWeaver workflow
- * @node iterator forEachItem [size: 300 200] [position: -90 0]
- * @node processor processItem iterator.processItem [position: 90 0]
- * @node aggregator aggregateResults [position: 270 0]
+ * @node iterator forEachItem [position: -90 0] [color: "purple"] [icon: "repeat"]
+ * @node processor processItem iterator.processItem [color: "blue"] [icon: "settings"]
+ * @node aggregator aggregateResults [position: 270 0] [color: "teal"] [icon: "inventory"]
  * @position Start -450 0
  * @position Exit 450 0
  * @connect Start.execute -> iterator.execute

package/dist/cli/templates/workflows/sequential.js

@@ -87,12 +87,13 @@ function outputResult(data: any): { result: any } {
 
 /**
  * @flowWeaver workflow
- * @node validator validateData [position: -300 0]
- * @node transformer transformData [position: 0 0]
- * @node outputter outputResult [position: 300 0]
+ * @node validator validateData [position: -300 0] [color: "green"] [icon: "verified"] [suppress: "UNUSED_OUTPUT_PORT"]
+ * @node transformer transformData [position: 0 0] [color: "blue"] [icon: "sync"]
+ * @node outputter outputResult [position: 300 0] [color: "cyan"] [icon: "inventory"]
  * @position Start -600 0
  * @position Exit 600 0
  * @path Start -> validator -> transformer -> outputter -> Exit
+ * @connect outputter.result -> Exit.result
  * @connect validator.onFailure -> Exit.onFailure
  * @connect validator.error -> Exit.error
  * @param execute [order:0] - Execute
@@ -134,9 +135,11 @@ function ${name}(${inputPortName}: any): { ${outputPortName}: any } {
     // Generate workflow annotations
     const spacing = 300;
     const startX = -(nodeNames.length * (spacing / 2) + spacing / 2);
+    const stepColors = ['green', 'blue', 'cyan', 'orange', 'purple', 'teal', 'pink', 'yellow'];
     const nodeAnnotations = nodeNames.map((name, i) => {
         const x = startX + (i + 1) * spacing;
-        return ` * @node step${i} ${name} [position: ${x} 0]`;
+        const color = stepColors[i % stepColors.length];
+        return ` * @node step${i} ${name} [position: ${x} 0] [color: "${color}"] [icon: "settings"]`;
     }).join('\n');
     const positionAnnotations = [
         ` * @position Start ${startX} 0`,

package/dist/cli/templates/workflows/webhook.js

@@ -120,9 +120,9 @@ function formatResponse(
 
 /**
  * @flowWeaver workflow
- * @node validator validateRequest [position: -180 0]
- * @node processor processPayload [position: 90 -60]
- * @node responder formatResponse [position: 270 0]
+ * @node validator validateRequest [position: -180 0] [color: "green"] [icon: "verified"]
+ * @node processor processPayload [position: 90 -60] [color: "blue"] [icon: "settings"]
+ * @node responder formatResponse [position: 270 0] [color: "cyan"] [icon: "send"]
  * @position Start -450 0
  * @position Exit 450 0
  * @connect Start.execute -> validator.execute

package/dist/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.20.1";
+export declare const VERSION = "0.20.3";
 //# sourceMappingURL=generated-version.d.ts.map

package/dist/generated-version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.ts — do not edit manually
-export const VERSION = '0.20.1';
+export const VERSION = '0.20.3';
 //# sourceMappingURL=generated-version.js.map

package/dist/jsdoc-parser.d.ts

@@ -88,6 +88,7 @@ export interface JSDocWorkflowConfig {
         job?: string;
         /** CI/CD deployment environment */
         environment?: string;
+        suppressWarnings?: string[];
     }>;
     connections?: Array<{
         from: {

package/dist/jsdoc-parser.js

@@ -740,7 +740,7 @@ export class JSDocParser {
         else if (func) {
             const returnType = func.getReturnType();
             const returnTypeText = returnType.getText();
-            const fieldMatch = returnTypeText.match(new RegExp(`${name}\\s*:\\s*([^;},]+)`));
+            const fieldMatch = returnTypeText.match(new RegExp(`${name}\\??\\s*:\\s*([^;},]+)`));
             if (fieldMatch) {
                 type = inferDataTypeFromTS(fieldMatch[1].trim());
             }
@@ -795,7 +795,7 @@ export class JSDocParser {
                     paramTypeText === '{}' ||
                     /^\{\s*\[[\w]+:\s*string\]:\s*(never|any|unknown);\s*\}$/.test(paramTypeText));
                 if (!isCatchAllRecord) {
-                    const fieldMatch = paramTypeText.match(new RegExp(`${name}\\s*:\\s*([^;},]+)`));
+                    const fieldMatch = paramTypeText.match(new RegExp(`${name}\\??\\s*:\\s*([^;},]+)`));
                     if (fieldMatch) {
                         type = inferDataTypeFromTS(fieldMatch[1].trim());
                     }
@@ -850,7 +850,7 @@ export class JSDocParser {
         if (!result) {
             return;
         }
-        const { instanceId, nodeType, parentScope, label, expressions, portOrder, portLabel, minimized, pullExecution, size, position, color, icon, tags, job, environment, } = result;
+        const { instanceId, nodeType, parentScope, label, expressions, portOrder, portLabel, minimized, pullExecution, size, position, color, icon, tags, job, environment, suppress, } = result;
         // Capture source location from tag
         const line = tag.getStartLineNumber();
         // Build portConfigs from portOrder, portLabel, and expressions
@@ -900,6 +900,7 @@ export class JSDocParser {
             ...(position && { x: position.x, y: position.y }),
             ...(job && { job }),
             ...(environment && { environment }),
+            ...(suppress && suppress.length > 0 && { suppressWarnings: suppress }),
             sourceLocation: { line, column: 0 },
         });
     }

package/dist/mcp/tools-pattern.js

@@ -7,191 +7,12 @@ import { listPatterns, applyPattern, findWorkflows, extractPattern } from '../ap
 import { generateInPlace } from '../api/generate-in-place.js';
 import { applyMigrations, getRegisteredMigrations } from '../migration/registry.js';
 import { describeWorkflow, formatDescribeOutput } from '../cli/commands/describe.js';
+import { applyModifyOperation, validateModifyParams } from '../api/modify-operation.js';
 import { addNode as manipAddNode, removeNode as manipRemoveNode, renameNode as manipRenameNode, addConnection as manipAddConnection, removeConnection as manipRemoveConnection, setNodePosition as manipSetNodePosition, setNodeLabel as manipSetNodeLabel, } from '../api/manipulation/index.js';
 import { findIsolatedNodes } from '../api/query.js';
 import { AnnotationParser } from '../parser.js';
 import { makeToolResult, makeErrorResult, addHintsToItems } from './response-utils.js';
 import { getFriendlyError } from '../friendly-errors.js';
-// Runtime validation schemas for fw_modify operations
-const modifyParamsSchemas = {
-    addNode: z.object({
-        nodeId: z.string({ required_error: 'nodeId is required' }),
-        nodeType: z.string({ required_error: 'nodeType is required' }),
-        x: z.number().optional(),
-        y: z.number().optional(),
-    }),
-    removeNode: z.object({
-        nodeId: z.string({ required_error: 'nodeId is required' }),
-    }),
-    renameNode: z.object({
-        oldId: z.string({ required_error: 'oldId is required' }),
-        newId: z.string({ required_error: 'newId is required' }),
-    }),
-    addConnection: z.object({
-        from: z.string({ required_error: 'from is required (format: "node.port")' }),
-        to: z.string({ required_error: 'to is required (format: "node.port")' }),
-    }),
-    removeConnection: z.object({
-        from: z.string({ required_error: 'from is required (format: "node.port")' }),
-        to: z.string({ required_error: 'to is required (format: "node.port")' }),
-    }),
-    setNodePosition: z.object({
-        nodeId: z.string({ required_error: 'nodeId is required' }),
-        x: z.number({ required_error: 'x is required', invalid_type_error: 'x must be a number' }),
-        y: z.number({ required_error: 'y is required', invalid_type_error: 'y must be a number' }),
-    }),
-    setNodeLabel: z.object({
-        nodeId: z.string({ required_error: 'nodeId is required' }),
-        label: z.string({ required_error: 'label is required' }),
-    }),
-};
-function validateModifyParams(operation, params) {
-    const schema = modifyParamsSchemas[operation];
-    if (!schema) {
-        return { success: false, error: `Unknown operation: ${operation}` };
-    }
-    const result = schema.safeParse(params);
-    if (!result.success) {
-        const messages = result.error.issues.map((i) => i.message).join('; ');
-        return { success: false, error: `${operation} params invalid: ${messages}` };
-    }
-    return { success: true };
-}
-/**
- * Apply a single modify operation to an AST.
- * Shared by fw_modify and fw_modify_batch.
- */
-function applyModifyOperation(ast, operation, params) {
-    const p = params;
-    const warnings = [];
-    const extraData = {};
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- AST manipulation functions use loose typing
-    let modifiedAST = ast;
-    switch (operation) {
-        case 'addNode': {
-            const nodeId = p.nodeId;
-            const nodeType = p.nodeType;
-            const nodeTypeExists = modifiedAST.nodeTypes.some((nt) => nt.name === nodeType || nt.functionName === nodeType);
-            if (!nodeTypeExists) {
-                warnings.push(`Node type "${nodeType}" is not defined in the file. ` +
-                    `The node will be added but may not render until the type is defined.`);
-            }
-            let autoX = typeof p.x === 'number' ? p.x : undefined;
-            let autoY = typeof p.y === 'number' ? p.y : undefined;
-            if (autoX === undefined || autoY === undefined) {
-                const positions = modifiedAST.instances
-                    .map((inst) => inst.config)
-                    .filter((c) => c !== undefined &&
-                    c !== null &&
-                    typeof c.x === 'number' &&
-                    typeof c.y === 'number');
-                if (positions.length > 0) {
-                    const maxX = Math.max(...positions.map((pos) => pos.x));
-                    if (autoX === undefined)
-                        autoX = maxX + 180;
-                    if (autoY === undefined)
-                        autoY = 0;
-                }
-                else {
-                    if (autoX === undefined)
-                        autoX = 0;
-                    if (autoY === undefined)
-                        autoY = 0;
-                }
-            }
-            modifiedAST = manipAddNode(modifiedAST, {
-                type: 'NodeInstance',
-                id: nodeId,
-                nodeType,
-                config: { x: autoX, y: autoY },
-            });
-            break;
-        }
-        case 'removeNode': {
-            const nodeId = p.nodeId;
-            const removedConnections = modifiedAST.connections
-                .filter((c) => c.from.node === nodeId || c.to.node === nodeId)
-                .map((c) => ({
-                from: `${c.from.node}.${c.from.port}`,
-                to: `${c.to.node}.${c.to.port}`,
-            }));
-            modifiedAST = manipRemoveNode(modifiedAST, nodeId);
-            if (removedConnections.length > 0) {
-                extraData.removedConnections = removedConnections;
-            }
-            break;
-        }
-        case 'renameNode': {
-            modifiedAST = manipRenameNode(modifiedAST, p.oldId, p.newId);
-            break;
-        }
-        case 'addConnection': {
-            const from = p.from;
-            const to = p.to;
-            const [fromNode, fromPort] = from.split('.');
-            const [toNode, toPort] = to.split('.');
-            if (!fromPort || !toPort) {
-                throw new Error('Connection format must be "node.port" (e.g., "Start.execute")');
-            }
-            const validNodes = [
-                'Start',
-                'Exit',
-                ...modifiedAST.instances.map((i) => i.id),
-            ];
-            if (!validNodes.includes(fromNode)) {
-                throw new Error(`Source node "${fromNode}" not found. Available: ${validNodes.join(', ')}`);
-            }
-            if (!validNodes.includes(toNode)) {
-                throw new Error(`Target node "${toNode}" not found. Available: ${validNodes.join(', ')}`);
-            }
-            if (fromNode !== 'Start' && fromNode !== 'Exit') {
-                const inst = modifiedAST.instances.find((i) => i.id === fromNode);
-                const nt = modifiedAST.nodeTypes.find((t) => t.name === inst?.nodeType);
-                if (nt && !nt.outputs[fromPort]) {
-                    throw new Error(`Node "${fromNode}" has no output "${fromPort}". Available: ${Object.keys(nt.outputs).join(', ')}`);
-                }
-            }
-            if (toNode !== 'Start' && toNode !== 'Exit') {
-                const inst = modifiedAST.instances.find((i) => i.id === toNode);
-                const nt = modifiedAST.nodeTypes.find((t) => t.name === inst?.nodeType);
-                if (nt && !nt.inputs[toPort]) {
-                    throw new Error(`Node "${toNode}" has no input "${toPort}". Available: ${Object.keys(nt.inputs).join(', ')}`);
-                }
-            }
-            modifiedAST = manipAddConnection(modifiedAST, from, to);
-            // Transition from autoConnect to explicit mode when connections are manually modified
-            if (modifiedAST.options?.autoConnect) {
-                modifiedAST = { ...modifiedAST, options: { ...modifiedAST.options, autoConnect: undefined } };
-                warnings.push('autoConnect was disabled because connections were manually modified');
-            }
-            break;
-        }
-        case 'removeConnection': {
-            modifiedAST = manipRemoveConnection(modifiedAST, p.from, p.to);
-            // Transition from autoConnect to explicit mode when connections are manually modified
-            if (modifiedAST.options?.autoConnect) {
-                modifiedAST = { ...modifiedAST, options: { ...modifiedAST.options, autoConnect: undefined } };
-                warnings.push('autoConnect was disabled because connections were manually modified');
-            }
-            const newlyIsolated = findIsolatedNodes(modifiedAST);
-            if (newlyIsolated.length > 0) {
-                extraData.newlyIsolatedNodes = newlyIsolated;
-            }
-            break;
-        }
-        case 'setNodePosition': {
-            modifiedAST = manipSetNodePosition(modifiedAST, p.nodeId, p.x, p.y);
-            break;
-        }
-        case 'setNodeLabel': {
-            modifiedAST = manipSetNodeLabel(modifiedAST, p.nodeId, p.label);
-            break;
-        }
-        default:
-            throw new Error(`Unknown operation: ${operation}`);
-    }
-    return { ast: modifiedAST, warnings, extraData };
-}
 export function registerPatternTools(mcp) {
     mcp.tool('fw_list_patterns', 'List reusable patterns defined in a file.', {
         filePath: z.string().describe('Path to file containing patterns'),

package/dist/parser.js

@@ -970,6 +970,7 @@ export class AnnotationParser {
                         ...(inst.tags && inst.tags.length > 0 && { tags: inst.tags }),
                         ...(inst.width && { width: inst.width }),
                         ...(inst.height && { height: inst.height }),
+                        ...(inst.suppressWarnings?.length && { suppressWarnings: inst.suppressWarnings }),
                     },
                     ...(inst.sourceLocation && {
                         sourceLocation: { file: filePath, ...inst.sourceLocation },

package/dist/validator.js

@@ -228,6 +228,21 @@ export class WorkflowValidator {
             });
             this.warnings.push(...promoted);
         }
+        // Filter out warnings suppressed by per-instance [suppress: "CODE"] annotations
+        const suppressMap = new Map();
+        for (const inst of workflow.instances) {
+            if (inst.config?.suppressWarnings?.length) {
+                suppressMap.set(inst.id, new Set(inst.config.suppressWarnings));
+            }
+        }
+        if (suppressMap.size > 0) {
+            this.warnings = this.warnings.filter((w) => {
+                if (!w.node)
+                    return true;
+                const codes = suppressMap.get(w.node);
+                return !codes || !codes.has(w.code);
+            });
+        }
         // Attach doc URLs to diagnostics that have mapped error codes
         for (const diag of [...this.errors, ...this.warnings]) {
             if (!diag.docUrl && ERROR_DOC_URLS[diag.code]) {

package/docs/reference/advanced-annotations.md

@@ -423,6 +423,17 @@ Visual tags/badges on the instance. Each tag has a label string and optional too
 @node myNode MyType [tags: "async" "Runs asynchronously", "beta"]
 ```
 
+### Suppress Warnings (`[suppress: ...]`)
+
+Silences specific validator warnings on a per-instance basis. Useful when a warning is intentional, such as output ports that are deliberately left unconnected in CI/CD workflows where data is discarded by design.
+
+```typescript
+@node fetch fetchData [suppress: "UNUSED_OUTPUT_PORT"]
+@node check runCheck [suppress: "UNUSED_OUTPUT_PORT", "UNREACHABLE_EXIT_PORT"]
+```
+
+The suppression is scoped to the annotated instance only. Other instances of the same type still produce warnings normally. The codes correspond to the warning codes listed in the error codes reference.
+
 ### Combining Attributes
 
 Multiple attribute brackets can appear on the same `@node`: