@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/mcp/auto-registration.js

@@ -1,62 +0,0 @@
-import { execSync } from 'child_process';
-import * as readline from 'readline';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
-function defaultRegistrationDeps() {
-    return {
-        execCommand: async (cmd) => {
-            try {
-                const stdout = execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
-                return { stdout: stdout.trim(), exitCode: 0 };
-            }
-            catch {
-                return { stdout: '', exitCode: 1 };
-            }
-        },
-        prompt: (question) => new Promise((resolve) => {
-            const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
-            rl.question(question, (answer) => {
-                rl.close();
-                resolve(answer.trim().toLowerCase());
-            });
-        }),
-        log: (msg) => process.stderr.write(msg + '\n'),
-        resolveCliPath: () => {
-            // import.meta.url works in ESM (tsx), __dirname works in CJS (built bundle)
-            try {
-                return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-            }
-            catch {
-                return path.resolve(__dirname, '..');
-            }
-        },
-    };
-}
-export async function offerClaudeRegistration(options, deps) {
-    const d = deps ?? defaultRegistrationDeps();
-    // 1. Detect Claude Code
-    const whichCmd = process.platform === 'win32' ? 'where claude' : 'which claude';
-    const whichResult = await d.execCommand(whichCmd);
-    if (whichResult.exitCode !== 0) {
-        d.log('Claude Code not found in PATH. Skipping auto-registration.');
-        return;
-    }
-    // 2. Check if already registered
-    const listResult = await d.execCommand('claude mcp list');
-    if (listResult.stdout.includes('flow-weaver')) {
-        d.log('Flow Weaver MCP server already registered in Claude Code.');
-        return;
-    }
-    // 3. Prompt user
-    const answer = await d.prompt('Claude Code detected. Register Flow Weaver MCP server? (y/N) ');
-    if (answer !== 'y' && answer !== 'yes') {
-        d.log('Skipped MCP server registration.');
-        return;
-    }
-    // 4. Register
-    const cliPath = d.resolveCliPath();
-    const cmd = `claude mcp add --scope project flow-weaver -- npx tsx ${cliPath}/index.ts mcp-server --stdio`;
-    await d.execCommand(cmd);
-    d.log('Registered Flow Weaver MCP server. Restart Claude Code to activate.');
-}
-//# sourceMappingURL=auto-registration.js.map

package/dist/mcp/debug-session.js

@@ -1,25 +0,0 @@
-/**
- * In-memory registry for active debug sessions.
- * Mirrors the pattern of run-registry.ts but tracks DebugController state
- * instead of AgentChannel state.
- */
-const debugSessions = new Map();
-export function storeDebugSession(session) {
-    debugSessions.set(session.debugId, session);
-}
-export function getDebugSession(debugId) {
-    return debugSessions.get(debugId);
-}
-export function removeDebugSession(debugId) {
-    debugSessions.delete(debugId);
-}
-export function listDebugSessions() {
-    return Array.from(debugSessions.values()).map((session) => ({
-        debugId: session.debugId,
-        filePath: session.filePath,
-        workflowName: session.workflowName,
-        createdAt: session.createdAt,
-        lastPauseState: session.lastPauseState,
-    }));
-}
-//# sourceMappingURL=debug-session.js.map

package/dist/mcp/index.d.ts

@@ -1,11 +0,0 @@
-export type { McpServerOptions, RegistrationDeps, } from './types.js';
-export { offerClaudeRegistration } from './auto-registration.js';
-export { makeToolResult, makeErrorResult } from './response-utils.js';
-export { registerQueryTools } from './tools-query.js';
-export { registerTemplateTools } from './tools-template.js';
-export { registerPatternTools } from './tools-pattern.js';
-export { registerDebugTools } from './tools-debug.js';
-export { registerResourceTools } from './tools-resources.js';
-export { registerPrompts } from './prompts.js';
-export { startMcpServer, mcpServerCommand } from './server.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.js

@@ -1,10 +0,0 @@
-export { offerClaudeRegistration } from './auto-registration.js';
-export { makeToolResult, makeErrorResult } from './response-utils.js';
-export { registerQueryTools } from './tools-query.js';
-export { registerTemplateTools } from './tools-template.js';
-export { registerPatternTools } from './tools-pattern.js';
-export { registerDebugTools } from './tools-debug.js';
-export { registerResourceTools } from './tools-resources.js';
-export { registerPrompts } from './prompts.js';
-export { startMcpServer, mcpServerCommand } from './server.js';
-//# sourceMappingURL=index.js.map

package/dist/mcp/pack-tools.js

@@ -1,59 +0,0 @@
-/**
- * Registers MCP tools contributed by installed marketplace packs.
- *
- * Scans for packs with mcpEntrypoint in their manifest. For each,
- * imports the entrypoint and calls its registerMcpTools(mcp) function.
- */
-import * as path from 'path';
-import { listInstalledPackages } from '../marketplace/registry.js';
-import { VERSION } from '../generated-version.js';
-function compareVersions(a, b) {
-    const pa = a.split('.').map(Number);
-    const pb = b.split('.').map(Number);
-    for (let i = 0; i < 3; i++) {
-        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
-        if (diff !== 0)
-            return diff;
-    }
-    return 0;
-}
-function checkPackEngineVersion(pkg) {
-    const required = pkg.manifest.engineVersion;
-    if (!required)
-        return;
-    const minVersion = required.replace(/^>=?\s*/, '');
-    const current = VERSION;
-    if (compareVersions(current, minVersion) < 0) {
-        process.stderr.write(`\x1b[33mWarning: ${pkg.name} requires flow-weaver >=${minVersion} but ${current} is installed.\x1b[0m\n`);
-        process.stderr.write(`\x1b[33mRun: npm install @synergenius/flow-weaver@latest\x1b[0m\n`);
-    }
-}
-export async function registerPackMcpTools(mcp) {
-    const projectDir = process.cwd();
-    let packages;
-    try {
-        packages = await listInstalledPackages(projectDir);
-    }
-    catch {
-        return;
-    }
-    for (const pkg of packages) {
-        const manifest = pkg.manifest;
-        if (!manifest.mcpEntrypoint || !manifest.mcpTools?.length)
-            continue;
-        checkPackEngineVersion(pkg);
-        const entrypointPath = path.join(pkg.path, manifest.mcpEntrypoint);
-        try {
-            const mod = await import(entrypointPath);
-            if (typeof mod.registerMcpTools === 'function') {
-                await mod.registerMcpTools(mcp);
-            }
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            // Log to stderr so it doesn't interfere with MCP JSON-RPC on stdout
-            process.stderr.write(`[mcp] Failed to load pack tools from ${pkg.name}: ${msg}\n`);
-        }
-    }
-}
-//# sourceMappingURL=pack-tools.js.map

package/dist/mcp/prompts.js

@@ -1,68 +0,0 @@
-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/response-utils.js

@@ -1,97 +0,0 @@
-/**
- * Wraps a data payload into a successful MCP tool result with JSON text content.
- * @param data - The result data to include in the response.
- * @returns An MCP tool result object with `success: true` and the serialized data.
- */
-export function makeToolResult(data) {
-    return {
-        content: [{ type: 'text', text: JSON.stringify({ success: true, data }, null, 2) }],
-    };
-}
-/**
- * Wraps an error code and message into a failed MCP tool result.
- * @param code - A machine-readable error code (e.g. "UNKNOWN_NODE_TYPE").
- * @param message - A human-readable error description.
- * @returns An MCP tool result object with `success: false`, `isError: true`, and the serialized error.
- */
-export function makeErrorResult(code, message) {
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify({ success: false, error: { code, message } }, null, 2),
-            },
-        ],
-        isError: true,
-    };
-}
-/**
- * Maps validation error codes to suggested next MCP tool actions.
- * Used to guide LLM agents toward resolving workflow issues.
- */
-export const ERROR_HINTS = {
-    UNKNOWN_NODE_TYPE: 'Run fw_query(query="node-types") to see available types',
-    UNKNOWN_SOURCE_NODE: 'Run fw_query(query="nodes") to see all node instances',
-    UNKNOWN_TARGET_NODE: 'Run fw_query(query="nodes") to see all node instances',
-    UNKNOWN_SOURCE_PORT: 'Run fw_describe(node="<nodeId>") to see available ports. Use fw_modify(operation="addConnection") to safely wire ports.',
-    UNKNOWN_TARGET_PORT: 'Run fw_describe(node="<nodeId>") to see available ports. Use fw_modify(operation="addConnection") to safely wire ports.',
-    MISSING_REQUIRED_INPUT: 'Add a @connect to this port, or make it optional with @input portName [optional]',
-    CYCLE_DETECTED: 'Use a scoped forEach node instead of graph loops. See flow-weaver:flow-weaver-export-interface',
-    STEP_PORT_TYPE_MISMATCH: 'STEP ports (execute, onSuccess, onFailure) can only connect to other STEP ports',
-    MULTIPLE_CONNECTIONS_TO_INPUT: 'Data inputs accept only one connection. Use a merge node or separate ports',
-    UNUSED_NODE: 'Connect this node or remove it with fw_modify(operation="removeNode")',
-    NO_START_CONNECTIONS: 'Add @connect Start.portName -> node.port, or use fw_modify(operation="addConnection") to wire it.',
-    NO_EXIT_CONNECTIONS: 'Add @connect node.port -> Exit.portName, or use fw_modify(operation="addConnection") to wire it.',
-    UNREACHABLE_EXIT_PORT: 'Use fw_modify(operation="addConnection") to connect a node output to this Exit port.',
-    RESERVED_NODE_NAME: 'Rename the node type — "Start" and "Exit" are reserved',
-    RESERVED_INSTANCE_ID: 'Rename the instance — "Start" and "Exit" are reserved IDs',
-    MULTIPLE_WORKFLOWS_FOUND: 'Specify workflowName parameter to select which workflow to use',
-    DUPLICATE_NODE_NAME: 'Rename one of the duplicate node type functions to be unique',
-    UNDEFINED_NODE: 'Add a @node annotation for the referenced instance, or fix the connection',
-    INVALID_EXIT_PORT_TYPE: 'Ensure Exit onSuccess/onFailure ports are STEP type (auto-generated)',
-    // Agent-specific rules
-    AGENT_LLM_MISSING_ERROR_HANDLER: 'Use fw_modify(operation="addConnection", params={from:"<nodeId>.onFailure", to:"Exit.onFailure"}) or add a retry/fallback node',
-    AGENT_UNGUARDED_TOOL_EXECUTOR: 'Add a human-approval node before the tool executor. Use fw_scaffold(template="human-approval") to create one',
-    AGENT_MISSING_MEMORY_IN_LOOP: 'Add a conversation-memory node inside the loop scope. Use fw_scaffold(template="conversation-memory") to create one',
-    AGENT_LLM_NO_FALLBACK: 'Add a retry or fallback node between the LLM onFailure and Exit. Consider a second LLM provider as fallback',
-    AGENT_TOOL_NO_OUTPUT_HANDLING: 'Use fw_modify(operation="addConnection") to wire tool output ports to downstream nodes',
-    // Design quality rules
-    DESIGN_ASYNC_NO_ERROR_PATH: 'Use fw_modify(operation="addConnection", params={from:"<nodeId>.onFailure", to:"Exit.onFailure"}) or add a retry/error handler',
-    DESIGN_SCOPE_NO_FAILURE_EXIT: 'Use fw_modify(operation="addConnection", params={from:"<nodeId>.onFailure", to:"Exit.onFailure"}) to surface scope failures',
-    DESIGN_UNBOUNDED_RETRY: 'Add a maxAttempts or retries input port to the retry node type to bound the loop',
-    DESIGN_FANOUT_NO_FANIN: 'Add a merge node downstream where parallel branches converge before Exit',
-    DESIGN_EXIT_DATA_UNREACHABLE: 'Use fw_modify(operation="addConnection") to connect a node output to this Exit port, or add a pull-execution node',
-    DESIGN_PULL_CANDIDATE: 'Add [pullExecution: execute] to the @node annotation so the node runs on demand',
-    DESIGN_PULL_UNUSED: 'Connect a data output from this node to a downstream consumer, or remove pullExecution',
-};
-/**
- * Enriches validation items with actionable hints from {@link ERROR_HINTS} and optional
- * friendly error explanations. Replaces `<nodeId>` placeholders in hints with actual node IDs.
- * @param items - Array of validation errors/warnings, each with a message, severity, and optional code.
- * @param friendlyErrorFn - Optional function that produces user-friendly error explanations.
- * @returns A new array with `hint` and `friendly` fields added where applicable.
- */
-export function addHintsToItems(items, friendlyErrorFn) {
-    return items.map((item) => {
-        if (!item.code)
-            return item;
-        const result = { ...item };
-        // Add MCP tool hint
-        let hint = ERROR_HINTS[item.code];
-        if (hint) {
-            if (item.nodeId && hint.includes('<nodeId>')) {
-                hint = hint.replace(/<nodeId>/g, item.nodeId);
-            }
-            result.hint = hint;
-        }
-        // Add friendly error explanation
-        if (friendlyErrorFn) {
-            const friendly = friendlyErrorFn({ code: item.code, message: item.message, node: item.nodeId });
-            if (friendly) {
-                result.friendly = { title: friendly.title, explanation: friendly.explanation, fix: friendly.fix };
-            }
-        }
-        return result;
-    });
-}
-//# sourceMappingURL=response-utils.js.map

package/dist/mcp/run-registry.d.ts

@@ -1,29 +0,0 @@
-/**
- * In-memory registry for pending workflow runs that are waiting for agent input.
- * Used by fw_execute_workflow (to store paused runs) and fw_resume_workflow (to resume them).
- */
-import type { AgentChannel } from './agent-channel.js';
-export interface PendingRun {
-    runId: string;
-    filePath: string;
-    workflowName?: string;
-    /** The still-pending execution promise. Resolves when workflow completes. */
-    executionPromise: Promise<unknown>;
-    agentChannel: AgentChannel;
-    /** The agent request data that triggered the pause. */
-    request?: object;
-    createdAt: number;
-    /** Temp files to clean up when the run completes or is cancelled. */
-    tmpFiles: string[];
-}
-export declare function storePendingRun(run: PendingRun): void;
-export declare function getPendingRun(runId: string): PendingRun | undefined;
-export declare function removePendingRun(runId: string): void;
-export declare function listPendingRuns(): Array<{
-    runId: string;
-    filePath: string;
-    workflowName?: string;
-    request?: object;
-    createdAt: number;
-}>;
-//# sourceMappingURL=run-registry.d.ts.map

package/dist/mcp/run-registry.js

@@ -1,24 +0,0 @@
-/**
- * In-memory registry for pending workflow runs that are waiting for agent input.
- * Used by fw_execute_workflow (to store paused runs) and fw_resume_workflow (to resume them).
- */
-const pendingRuns = new Map();
-export function storePendingRun(run) {
-    pendingRuns.set(run.runId, run);
-}
-export function getPendingRun(runId) {
-    return pendingRuns.get(runId);
-}
-export function removePendingRun(runId) {
-    pendingRuns.delete(runId);
-}
-export function listPendingRuns() {
-    return Array.from(pendingRuns.values()).map((run) => ({
-        runId: run.runId,
-        filePath: run.filePath,
-        workflowName: run.workflowName,
-        request: run.request,
-        createdAt: run.createdAt,
-    }));
-}
-//# sourceMappingURL=run-registry.js.map

package/dist/mcp/server.js

@@ -1,63 +0,0 @@
-// Load built-in extensions (CI/CD, etc.) before tool registration
-import '../extensions/index.js';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { registerQueryTools } from './tools-query.js';
-import { registerTemplateTools } from './tools-template.js';
-import { registerPatternTools } from './tools-pattern.js';
-import { registerExportTools } from './tools-export.js';
-import { registerMarketplaceTools } from './tools-marketplace.js';
-import { registerDiagramTools } from './tools-diagram.js';
-import { registerDocsTools } from './tools-docs.js';
-import { registerModelTools } from './tools-model.js';
-import { registerDebugTools } from './tools-debug.js';
-import { registerWorkflowRunTools } from './tools-workflow-run.js';
-import { registerContextTools } from './tools-context.js';
-import { registerResourceTools } from './tools-resources.js';
-import { registerPrompts } from './prompts.js';
-import { registerPackMcpTools } from './pack-tools.js';
-export async function startMcpServer(options) {
-    // Create MCP server
-    const mcp = new McpServer({
-        name: 'flow-weaver',
-        version: '1.0.0',
-    });
-    // Register all tools
-    registerQueryTools(mcp);
-    registerTemplateTools(mcp);
-    registerPatternTools(mcp);
-    registerExportTools(mcp);
-    registerMarketplaceTools(mcp);
-    registerDiagramTools(mcp);
-    registerDocsTools(mcp);
-    registerModelTools(mcp);
-    registerDebugTools(mcp);
-    registerWorkflowRunTools(mcp);
-    registerContextTools(mcp);
-    registerResourceTools(mcp);
-    registerPrompts(mcp);
-    await registerPackMcpTools(mcp);
-    // Connect transport (only in stdio MCP mode)
-    if (options.stdio) {
-        const transport = new StdioServerTransport();
-        await mcp.connect(transport);
-    }
-}
-export async function mcpServerCommand(options) {
-    // In stdio mode, stdout is reserved for JSON-RPC — log to stderr.
-    // In interactive mode, log to stdout (write + flush to survive SIGTERM).
-    const log = options.stdio
-        ? (msg) => process.stderr.write(msg + '\n')
-        : (msg) => process.stdout.write(msg + '\n');
-    if (!options.stdio) {
-        log('Tip: run "fw mcp-setup" to register with your AI tools.');
-        log('Starting MCP server...');
-    }
-    await startMcpServer(options);
-    if (!options.stdio) {
-        log('MCP server running. Waiting for connections...');
-    }
-    // Keep alive
-    await new Promise(() => { });
-}
-//# sourceMappingURL=server.js.map

package/dist/mcp/tools-context.js

@@ -1,51 +0,0 @@
-import { z } from 'zod';
-import { buildContext } from '../context/index.js';
-import { makeToolResult, makeErrorResult } from './response-utils.js';
-export function registerContextTools(mcp) {
-    mcp.tool('fw_context', 'Generate a self-contained LLM context bundle with Flow Weaver documentation, grammar, and conventions. Use preset="core" for basics, "authoring" for writing workflows, "full" for everything, "ops" for CLI/deployment reference.', {
-        preset: z
-            .enum(['core', 'authoring', 'full', 'ops'])
-            .optional()
-            .default('core')
-            .describe('Topic preset'),
-        profile: z
-            .enum(['standalone', 'assistant'])
-            .optional()
-            .default('assistant')
-            .describe('standalone = full self-contained dump, assistant = assumes MCP tools available'),
-        topics: z
-            .string()
-            .optional()
-            .describe('Comma-separated topic slugs (overrides preset)'),
-        addTopics: z
-            .string()
-            .optional()
-            .describe('Comma-separated slugs to add to preset'),
-        includeGrammar: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe('Include EBNF annotation grammar section'),
-    }, async (args) => {
-        try {
-            const result = buildContext({
-                preset: args.preset,
-                profile: args.profile,
-                topics: args.topics ? args.topics.split(',').map((s) => s.trim()) : undefined,
-                addTopics: args.addTopics ? args.addTopics.split(',').map((s) => s.trim()) : undefined,
-                includeGrammar: args.includeGrammar,
-            });
-            return makeToolResult({
-                profile: result.profile,
-                topicCount: result.topicCount,
-                lineCount: result.lineCount,
-                topicSlugs: result.topicSlugs,
-                content: result.content,
-            });
-        }
-        catch (err) {
-            return makeErrorResult('CONTEXT_ERROR', `fw_context failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    });
-}
-//# sourceMappingURL=tools-context.js.map