@synergenius/flow-weaver 0.8.2 → 0.9.0

package/dist/annotation-generator.d.ts

@@ -1,4 +1,4 @@
-import type { TNodeInstanceAST, TPortDefinition, TWorkflowAST } from "./ast/index.js";
+import type { TNodeTypeAST, TNodeInstanceAST, TPortDefinition, TWorkflowAST } from "./ast/index.js";
 export interface GenerateAnnotationsOptions {
     includeComments?: boolean;
     includeMetadata?: boolean;
@@ -41,5 +41,10 @@ export declare function assignPortOrders(ports: [string, TPortDefinition][], _di
  * Exported for reuse in generate-in-place.ts to maintain DRY principle
  */
 export declare function generateNodeInstanceTag(instance: TNodeInstanceAST): string;
+/**
+ * Generate a TypeScript function signature from a node type definition.
+ * Handles three modes: stub (declare function), expression (pure function), normal (execute/onSuccess/onFailure).
+ */
+export declare function generateFunctionSignature(nodeType: TNodeTypeAST): string[];
 export declare const annotationGenerator: AnnotationGenerator;
 //# sourceMappingURL=annotation-generator.d.ts.map

package/dist/annotation-generator.js

@@ -24,6 +24,10 @@ export class AnnotationGenerator {
             if (nodeType.variant === 'COERCION') {
                 return;
             }
+            // Skip inferred stubs — they have no @flowWeaver annotation and were auto-detected
+            if (nodeType.variant === 'STUB' && nodeType.inferred) {
+                return;
+            }
             lines.push(...this.generateNodeTypeAnnotation(nodeType, indent, includeComments, includeMetadata));
             lines.push("");
         });
@@ -47,8 +51,14 @@ export class AnnotationGenerator {
             }
             lines.push(` *`);
         }
-        // @flowWeaver nodeType marker
-        lines.push(" * @flowWeaver nodeType");
+        // @flowWeaver marker: use 'node' shorthand for stubs and expression nodes
+        const isStub = nodeType.variant === 'STUB';
+        if (isStub || nodeType.expression) {
+            lines.push(" * @flowWeaver node");
+        }
+        else {
+            lines.push(" * @flowWeaver nodeType");
+        }
         // Add label if present
         if (includeMetadata && nodeType.label) {
             lines.push(` * @label ${nodeType.label}`);
@@ -117,28 +127,7 @@ export class AnnotationGenerator {
         return `{ ${props.join(", ")} }`;
     }
     generateFunctionSignature(nodeType) {
-        const lines = [];
-        // Build parameters (excluding execute which will be first)
-        const params = ["execute: boolean"];
-        Object.entries(nodeType.inputs).forEach(([name, port]) => {
-            if (isExecutePort(name))
-                return;
-            const optional = port.optional ? "?" : "";
-            const defaultVal = port.default !== undefined ? ` = ${JSON.stringify(port.default)}` : "";
-            params.push(`${name}${optional}: ${this.mapDataTypeToTS(port.dataType)}${defaultVal}`);
-        });
-        // Build return type (including onSuccess/onFailure)
-        const returns = ["onSuccess: boolean", "onFailure: boolean"];
-        Object.entries(nodeType.outputs).forEach(([name, port]) => {
-            if (isSuccessPort(name) || isFailurePort(name))
-                return;
-            returns.push(`${name}: ${this.mapDataTypeToTS(port.dataType)}`);
-        });
-        lines.push(`function ${nodeType.functionName}(${params.join(", ")}) {`);
-        lines.push(`  if (!execute) return { onSuccess: false, onFailure: false };`);
-        lines.push(`  return { onSuccess: true, onFailure: false };`);
-        lines.push(`}`);
-        return lines;
+        return generateFunctionSignature(nodeType);
     }
     generateWorkflowAnnotation(workflow, indent, includeComments, skipParamReturns = false) {
         const lines = [];
@@ -329,6 +318,11 @@ export class AnnotationGenerator {
     }
     generateWorkflowFunctionSignature(workflow) {
         const lines = [];
+        // Stub workflows use const declaration format
+        if (workflow.stub) {
+            lines.push(`export const ${workflow.functionName} = 'flowWeaver:draft';`);
+            return lines;
+        }
         const startPorts = workflow.startPorts || {};
         const exitPorts = workflow.exitPorts || {};
         // Build parameter types (excluding execute)
@@ -614,5 +608,62 @@ export function generateNodeInstanceTag(instance) {
     }
     return ` * @node ${instance.id} ${instance.nodeType}${parent}${labelAttr}${portOrderAttr}${portLabelAttr}${exprAttr}${pullExecutionAttr}${minimizedAttr}${colorAttr}${iconAttr}${tagsAttr}${sizeAttr}${positionAttr}`;
 }
+/**
+ * Generate a TypeScript function signature from a node type definition.
+ * Handles three modes: stub (declare function), expression (pure function), normal (execute/onSuccess/onFailure).
+ */
+export function generateFunctionSignature(nodeType) {
+    const lines = [];
+    const isStub = nodeType.variant === 'STUB';
+    const isExpression = isStub || nodeType.expression;
+    if (isExpression) {
+        const params = [];
+        Object.entries(nodeType.inputs).forEach(([name, port]) => {
+            if (isExecutePort(name))
+                return;
+            const optional = port.optional ? "?" : "";
+            params.push(`${name}${optional}: ${mapToTypeScript(port.dataType)}`);
+        });
+        const returns = [];
+        Object.entries(nodeType.outputs).forEach(([name, port]) => {
+            if (isSuccessPort(name) || isFailurePort(name))
+                return;
+            returns.push(`${name}: ${mapToTypeScript(port.dataType)}`);
+        });
+        const returnType = returns.length === 1
+            ? mapToTypeScript((Object.entries(nodeType.outputs).find(([n]) => !isSuccessPort(n) && !isFailurePort(n))?.[1].dataType || 'ANY'))
+            : `{ ${returns.join("; ")} }`;
+        if (isStub) {
+            lines.push(`declare function ${nodeType.functionName}(${params.join(", ")}): ${returnType};`);
+        }
+        else {
+            lines.push(`function ${nodeType.functionName}(${params.join(", ")}): ${returnType} {`);
+            lines.push(`  // TODO: implement`);
+            lines.push(`  throw new Error('Not implemented');`);
+            lines.push(`}`);
+        }
+    }
+    else {
+        const params = ["execute: boolean"];
+        Object.entries(nodeType.inputs).forEach(([name, port]) => {
+            if (isExecutePort(name))
+                return;
+            const optional = port.optional ? "?" : "";
+            const defaultVal = port.default !== undefined ? ` = ${JSON.stringify(port.default)}` : "";
+            params.push(`${name}${optional}: ${mapToTypeScript(port.dataType)}${defaultVal}`);
+        });
+        const returns = ["onSuccess: boolean", "onFailure: boolean"];
+        Object.entries(nodeType.outputs).forEach(([name, port]) => {
+            if (isSuccessPort(name) || isFailurePort(name))
+                return;
+            returns.push(`${name}: ${mapToTypeScript(port.dataType)}`);
+        });
+        lines.push(`function ${nodeType.functionName}(${params.join(", ")}) {`);
+        lines.push(`  if (!execute) return { onSuccess: false, onFailure: false };`);
+        lines.push(`  return { onSuccess: true, onFailure: false };`);
+        lines.push(`}`);
+    }
+    return lines;
+}
 export const annotationGenerator = new AnnotationGenerator();
 //# sourceMappingURL=annotation-generator.js.map

package/dist/api/generate.d.ts

@@ -37,6 +37,11 @@ export interface GenerateOptions extends Partial<ASTGenerateOptions> {
      * @example { 'add': '../node-types/add.js', 'greet': '../node-types/greet.js' }
      */
     externalNodeTypes?: Record<string, string>;
+    /**
+     * Allow generation even when stub nodes exist. Stub nodes will emit
+     * a throw statement at runtime. Default: false (refuse to generate with stubs).
+     */
+    generateStubs?: boolean;
 }
 /**
  * Generate an import statement in the appropriate module format

package/dist/api/generate.js

@@ -38,7 +38,14 @@ export function generateModuleExports(functionNames) {
     return `module.exports = { ${functionNames.join(', ')} };`;
 }
 export function generateCode(ast, options) {
-    const { production = false, sourceMap = false, allWorkflows = [], moduleFormat = 'esm', externalRuntimePath, constants = [], externalNodeTypes = {}, } = options || {};
+    const { production = false, sourceMap = false, allWorkflows = [], moduleFormat = 'esm', externalRuntimePath, constants = [], externalNodeTypes = {}, generateStubs = false, } = options || {};
+    // Check for stub nodes — refuse to generate unless explicitly allowed
+    const stubNodeTypes = ast.nodeTypes.filter((nt) => nt.variant === 'STUB');
+    if (stubNodeTypes.length > 0 && !generateStubs) {
+        const stubNames = stubNodeTypes.map((nt) => nt.functionName).join(', ');
+        throw new Error(`Cannot generate code: workflow has ${stubNodeTypes.length} stub node(s) without implementation: ${stubNames}. ` +
+            `Implement them or pass { generateStubs: true } to emit placeholder throws.`);
+    }
     // Determine if workflow should be async based on node composition
     const { shouldBeAsync, warning } = validateWorkflowAsync(ast, ast.nodeTypes);
     if (warning && !production) {

package/dist/api/validate.d.ts

@@ -18,8 +18,11 @@ export interface ValidationResult {
  * Agent rules are always applied automatically.
  *
  * @param ast - The workflow AST to validate
- * @param customRules - Optional array of additional custom validation rules
+ * @param options - Validation options: custom rules and/or draft mode
  * @returns ValidationResult with errors and warnings
  */
-export declare function validateWorkflow(ast: TWorkflowAST, customRules?: TValidationRule[]): ValidationResult;
+export declare function validateWorkflow(ast: TWorkflowAST, options?: {
+    customRules?: TValidationRule[];
+    mode?: 'strict' | 'draft';
+}): ValidationResult;
 //# sourceMappingURL=validate.d.ts.map

package/dist/api/validate.js

@@ -13,14 +13,14 @@ import { getAgentValidationRules } from "../validation/agent-rules.js";
  * Agent rules are always applied automatically.
  *
  * @param ast - The workflow AST to validate
- * @param customRules - Optional array of additional custom validation rules
+ * @param options - Validation options: custom rules and/or draft mode
  * @returns ValidationResult with errors and warnings
  */
-export function validateWorkflow(ast, customRules) {
+export function validateWorkflow(ast, options) {
     // Use the consolidated validator
-    const result = validator.validate(ast);
+    const result = validator.validate(ast, { mode: options?.mode });
     // Apply agent-specific rules + any custom rules
-    const allRules = [...getAgentValidationRules(), ...(customRules || [])];
+    const allRules = [...getAgentValidationRules(), ...(options?.customRules || [])];
     for (const rule of allRules) {
         const ruleResults = rule.validate(ast);
         for (const err of ruleResults) {

package/dist/ast/types.d.ts

@@ -104,6 +104,8 @@ export type TWorkflowAST = {
     availableFunctionNames?: string[];
     /** Sugar macros (@map, @filter) that expand to full scope patterns. Stored for round-trip preservation. */
     macros?: TWorkflowMacro[];
+    /** Whether this workflow was defined as a stub (const declaration, no function body). */
+    stub?: boolean;
     /** Reserved for plugin extensibility */
     metadata?: TWorkflowMetadata;
 };
@@ -240,7 +242,7 @@ export type TNodeTypeAST = {
     /** Multiple scopes this node creates */
     scopes?: string[];
     /** Variant identifier (set by app layer) */
-    variant?: 'FUNCTION' | 'WORKFLOW' | 'IMPORTED_WORKFLOW' | 'MAP_ITERATOR' | 'COERCION';
+    variant?: 'FUNCTION' | 'WORKFLOW' | 'IMPORTED_WORKFLOW' | 'MAP_ITERATOR' | 'COERCION' | 'STUB';
     /** File path for external node types */
     path?: string;
     /** Function reference for function-based node types */

package/dist/cli/commands/implement.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Implement command — replaces a stub node with a real function skeleton
+ */
+export interface ImplementOptions {
+    workflowName?: string;
+    preview?: boolean;
+}
+export declare function implementCommand(input: string, nodeName: string, options?: ImplementOptions): Promise<void>;
+//# sourceMappingURL=implement.d.ts.map

package/dist/cli/commands/implement.js

@@ -0,0 +1,96 @@
+/**
+ * Implement command — replaces a stub node with a real function skeleton
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseWorkflow } from '../../api/index.js';
+import { generateFunctionSignature } from '../../annotation-generator.js';
+import { logger } from '../utils/logger.js';
+import { getErrorMessage } from '../../utils/error-utils.js';
+/**
+ * Find a `declare function <name>(...): ...;` declaration in source text,
+ * handling multiline signatures. Returns the full matched text and its
+ * leading indentation, or null if not found.
+ */
+function findDeclareFunction(source, functionName) {
+    const lines = source.split('\n');
+    const escaped = functionName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const startPattern = new RegExp(`^(\\s*)declare\\s+function\\s+${escaped}\\s*\\(`);
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(startPattern);
+        if (!m)
+            continue;
+        const indent = m[1] || '';
+        // Accumulate lines until we find one ending with ;
+        let accumulated = lines[i];
+        let j = i;
+        while (!accumulated.trimEnd().endsWith(';') && j < lines.length - 1) {
+            j++;
+            accumulated += '\n' + lines[j];
+        }
+        return { match: accumulated, indent };
+    }
+    return null;
+}
+export async function implementCommand(input, nodeName, options = {}) {
+    const { workflowName, preview = false } = options;
+    try {
+        const filePath = path.resolve(input);
+        if (!fs.existsSync(filePath)) {
+            logger.error(`File not found: ${input}`);
+            process.exit(1);
+        }
+        const parseResult = await parseWorkflow(filePath, { workflowName });
+        if (parseResult.errors.length > 0) {
+            logger.error('Parse errors:');
+            parseResult.errors.forEach((e) => logger.error(`  ${e}`));
+            process.exit(1);
+        }
+        const ast = parseResult.ast;
+        // Find the stub node type
+        const stubNodeType = ast.nodeTypes.find((nt) => nt.variant === 'STUB' && (nt.functionName === nodeName || nt.name === nodeName));
+        if (!stubNodeType) {
+            const existingNt = ast.nodeTypes.find((nt) => nt.functionName === nodeName || nt.name === nodeName);
+            if (existingNt) {
+                logger.warn(`Node "${nodeName}" is already implemented.`);
+                process.exit(0);
+            }
+            const available = ast.nodeTypes
+                .filter((nt) => nt.variant === 'STUB')
+                .map((nt) => nt.functionName);
+            if (available.length === 0) {
+                logger.error('No stub nodes found in this workflow.');
+            }
+            else {
+                logger.error(`Stub node "${nodeName}" not found. Available stubs: ${available.join(', ')}`);
+            }
+            process.exit(1);
+        }
+        const source = fs.readFileSync(filePath, 'utf8');
+        const found = findDeclareFunction(source, stubNodeType.functionName);
+        if (!found) {
+            logger.error(`Could not find "declare function ${stubNodeType.functionName}" in source file.`);
+            process.exit(1);
+        }
+        // Generate the real function signature
+        const implementedType = { ...stubNodeType, variant: 'FUNCTION' };
+        const signatureLines = generateFunctionSignature(implementedType);
+        const replacement = signatureLines.map((line) => found.indent + line).join('\n');
+        if (preview) {
+            logger.section(`Preview: ${stubNodeType.functionName}`);
+            logger.newline();
+            // eslint-disable-next-line no-console
+            console.log(replacement);
+        }
+        else {
+            const updated = source.replace(found.match, replacement);
+            fs.writeFileSync(filePath, updated, 'utf8');
+            logger.success(`Implemented ${stubNodeType.functionName} in ${path.basename(filePath)}`);
+        }
+    }
+    catch (error) {
+        logger.error(`Implement failed: ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=implement.js.map

package/dist/cli/commands/status.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Status command — reports implementation progress for stub workflows
+ */
+export interface StatusOptions {
+    workflowName?: string;
+    json?: boolean;
+}
+export declare function statusCommand(input: string, options?: StatusOptions): Promise<void>;
+//# sourceMappingURL=status.d.ts.map

package/dist/cli/commands/status.js

@@ -0,0 +1,121 @@
+/**
+ * Status command — reports implementation progress for stub workflows
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseWorkflow } from '../../api/index.js';
+import { validator } from '../../validator.js';
+import { logger } from '../utils/logger.js';
+import { getErrorMessage } from '../../utils/error-utils.js';
+function formatPortList(ports) {
+    return Object.entries(ports)
+        .filter(([name]) => name !== 'execute' && name !== 'onSuccess' && name !== 'onFailure')
+        .map(([name, port]) => `${name}(${port.dataType.toLowerCase()})`);
+}
+export async function statusCommand(input, options = {}) {
+    const { workflowName, json = false } = options;
+    try {
+        const filePath = path.resolve(input);
+        if (!fs.existsSync(filePath)) {
+            if (json) {
+                console.log(JSON.stringify({ error: `File not found: ${input}` }));
+            }
+            else {
+                logger.error(`File not found: ${input}`);
+            }
+            process.exit(1);
+        }
+        const parseResult = await parseWorkflow(filePath, { workflowName });
+        if (parseResult.errors.length > 0) {
+            if (json) {
+                console.log(JSON.stringify({ error: `Parse errors: ${parseResult.errors.join(', ')}` }));
+            }
+            else {
+                logger.error('Parse errors:');
+                parseResult.errors.forEach((e) => logger.error(`  ${e}`));
+            }
+            process.exit(1);
+        }
+        const ast = parseResult.ast;
+        // Collect node statuses
+        const instanceTypeMap = new Map();
+        for (const nt of ast.nodeTypes) {
+            instanceTypeMap.set(nt.name, nt);
+            if (nt.functionName !== nt.name) {
+                instanceTypeMap.set(nt.functionName, nt);
+            }
+        }
+        const nodes = [];
+        const seen = new Set();
+        for (const instance of ast.instances) {
+            const nt = instanceTypeMap.get(instance.nodeType);
+            if (!nt || seen.has(nt.functionName))
+                continue;
+            seen.add(nt.functionName);
+            nodes.push({
+                name: nt.functionName,
+                status: nt.variant === 'STUB' ? 'STUB' : 'OK',
+                inputs: formatPortList(nt.inputs),
+                outputs: formatPortList(nt.outputs),
+            });
+        }
+        const implemented = nodes.filter((n) => n.status === 'OK').length;
+        const total = nodes.length;
+        // Run draft validation for structural checks
+        const validation = validator.validate(ast, { mode: 'draft' });
+        const structuralErrors = validation.errors
+            .filter((e) => e.code !== 'STUB_NODE')
+            .map((e) => e.message);
+        const result = {
+            name: ast.name,
+            implemented,
+            total,
+            nodes,
+            structurallyValid: structuralErrors.length === 0,
+            structuralErrors,
+        };
+        if (json) {
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            logger.section(`${ast.name}: ${implemented}/${total} nodes implemented`);
+            logger.newline();
+            const maxNameLen = Math.max(...nodes.map((n) => n.name.length), 0);
+            for (const node of nodes) {
+                const tag = node.status === 'STUB' ? '[STUB]' : '[OK]  ';
+                const paddedName = node.name.padEnd(maxNameLen);
+                const inputStr = node.inputs.length > 0 ? `inputs: ${node.inputs.join(', ')}` : '';
+                const outputStr = node.outputs.length > 0 ? `outputs: ${node.outputs.join(', ')}` : '';
+                const arrow = inputStr && outputStr ? ' → ' : '';
+                const portsStr = `${inputStr}${arrow}${outputStr}`;
+                if (node.status === 'STUB') {
+                    logger.warn(`  ${paddedName}  ${tag}  ${portsStr}`);
+                }
+                else {
+                    logger.success(`  ${paddedName}  ${tag}  ${portsStr}`);
+                }
+            }
+            if (structuralErrors.length > 0) {
+                logger.newline();
+                logger.error(`Structural errors (${structuralErrors.length}):`);
+                structuralErrors.forEach((e) => logger.error(`  - ${e}`));
+            }
+            else {
+                logger.newline();
+                logger.success('Graph structure is valid.');
+            }
+        }
+    }
+    catch (error) {
+        if (json) {
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify({ error: getErrorMessage(error) }));
+        }
+        else {
+            logger.error(`Status failed: ${getErrorMessage(error)}`);
+        }
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=status.js.map