@synergenius/flow-weaver 0.33.2 → 0.44.0

package/dist/console/terminals.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What `Start` hands out and what `Exit` takes in, port by port.
+ *
+ * The process model knows which steps `Start` leads to and which arms reach
+ * `Exit`, but not which parameter feeds which input, or which step's output
+ * becomes which return value. That is the part a person clicks `Start` or
+ * `Exit` to learn, and it is in the connections -- `@path` name matching,
+ * `@connect` and `[expr:]` references all end up there.
+ */
+import type { TWorkflowAST } from '../ast/types.js';
+export interface PortEnd {
+    node: string;
+    port: string;
+}
+export interface TerminalWiring {
+    /** For each `Start` port, every input it is wired to, in connection order. */
+    start: Record<string, PortEnd[]>;
+    /** For each `Exit` port, the output that feeds it. A port fed twice keeps the first. */
+    exit: Record<string, PortEnd>;
+}
+export declare function terminalWiring(ast: Pick<TWorkflowAST, 'connections'>): TerminalWiring;
+//# sourceMappingURL=terminals.d.ts.map

package/dist/console/workflow-view.d.ts

@@ -0,0 +1,153 @@
+import type { TWorkflowAST, TNodeTypeAST, TNodeInstanceAST, TPortDefinition, THttpRoute } from '../ast/types.js';
+import type { Json } from './respond.js';
+export declare function nodeTypeOf(ast: TWorkflowAST, inst: TNodeInstanceAST): TNodeTypeAST | undefined;
+export declare function ports(map: Record<string, TPortDefinition> | undefined): {
+    name: string;
+    tsType: string;
+    optional: boolean;
+    description: string;
+}[];
+export declare function parseOne(file: string, name: string): Promise<{
+    ast?: TWorkflowAST;
+    errors: string[];
+}>;
+/**
+ * A workflow as it was at a git ref. The old text is written beside the
+ * file for a moment under a `.fw-diff-` name, so its relative imports still
+ * resolve, parsed, and removed. The scanner and the watcher both skip it.
+ */
+export declare function astAt(file: string, name: string, ref: string): Promise<{
+    ast?: TWorkflowAST;
+    error?: string;
+}>;
+export declare function describeWorkflow(projectDir: string, file: string, name: string): Promise<{
+    file: string;
+    rel: string;
+    name: string;
+    parseErrors: string[];
+    description?: undefined;
+    compiled?: undefined;
+    params?: undefined;
+    paramsSchema?: undefined;
+    returns?: undefined;
+    wiring?: undefined;
+    model?: undefined;
+    nodes?: undefined;
+    issues?: undefined;
+    source?: undefined;
+    sourceLine?: undefined;
+    deploy?: undefined;
+    http?: undefined;
+    reference?: undefined;
+} | {
+    file: string;
+    rel: string;
+    name: string;
+    description: string;
+    compiled: boolean;
+    params: {
+        name: string;
+        tsType: string;
+        optional: boolean;
+        description: string;
+    }[];
+    paramsSchema: Record<string, import("./schema.js").FieldSchema> | null;
+    returns: {
+        name: string;
+        tsType: string;
+        optional: boolean;
+        description: string;
+    }[];
+    wiring: import("./terminals.js").TerminalWiring;
+    model: import("../diagram/process-view.js").ProcessModel;
+    nodes: Record<string, Json>;
+    issues: {
+        severity: "error" | "warning";
+        code: string;
+        message: string;
+        node: string | null;
+        line: number | null;
+        hint: string | null;
+    }[];
+    source: string;
+    sourceLine: number;
+    deploy: Record<string, Record<string, unknown>> | null;
+    http: THttpRoute[];
+    reference: {
+        options: {
+            strictTypes?: boolean;
+            autoConnect?: boolean;
+            trigger?: {
+                event?: string;
+                cron?: string;
+            };
+            http?: THttpRoute[];
+            cancelOn?: {
+                event: string;
+                match?: string;
+                timeout?: string;
+            };
+            retries?: number;
+            timeout?: string;
+            throttle?: {
+                limit: number;
+                period?: string;
+            };
+        };
+        paths: {
+            node: string;
+            route?: "ok" | "fail";
+        }[][];
+        connects: {
+            from: {
+                node: string;
+                port: string;
+            };
+            to: {
+                node: string;
+                port: string;
+            };
+        }[];
+        exprs: {
+            node: string;
+            port: string;
+            expr: string;
+        }[];
+        importsFrom: {
+            type: string;
+            from: string;
+        }[];
+    };
+    parseErrors?: undefined;
+}>;
+/** A route as the client sent it, checked; a string says what is wrong. */
+export declare function routeFrom(raw: unknown): THttpRoute | string;
+/**
+ * Rewrite a workflow's `@http` lines: the existing ones go, the given ones
+ * land after `@flowWeaver workflow`. A textual edit of the JSDoc only, and
+ * the file is parsed again before it stands -- a result that does not parse
+ * is put back.
+ */
+export declare function setHttpRoutes(file: string, name: string, routes: THttpRoute[]): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;
+/**
+ * An absolute path as clickable segments.
+ *
+ * `path.parse().root` is `/` on POSIX and `C:\\` on Windows, and the rest
+ * splits on the platform's own separator, so the dialog works on both
+ * without the client knowing which it is on.
+ */
+export declare function crumbsFor(at: string): Array<{
+    name: string;
+    dir: string;
+}>;
+export declare function errorCodeSection(code: string): {
+    heading: string;
+    content: string;
+    codeBlocks: string[];
+} | null;
+//# sourceMappingURL=workflow-view.d.ts.map

package/dist/constants.d.ts

@@ -48,6 +48,11 @@
  * }
  * ```
  */
+/**
+ * The oldest Node.js major the package supports. Mirrors `engines.node` in
+ * package.json (a test keeps the two equal); `fw doctor` checks against it.
+ */
+export declare const MIN_NODE_MAJOR = 22;
 export declare const RESERVED_NODE_NAMES: {
     readonly START: "Start";
     readonly EXIT: "Exit";
@@ -103,7 +108,6 @@ export declare const VALID_NODE_COLORS: readonly ["blue", "purple", "cyan", "ora
 export type ValidNodeColor = (typeof VALID_NODE_COLORS)[number];
 export declare const KNOWN_NODETYPE_TAGS: Set<string>;
 export declare const KNOWN_WORKFLOW_TAGS: Set<string>;
-export declare const KNOWN_PATTERN_TAGS: Set<string>;
 export declare const STANDARD_JSDOC_TAGS: Set<string>;
 /**
  * Build a dynamic known-workflow-tags set that includes core tags

package/dist/constants.js

@@ -1,168 +1,57 @@
-/**
- * # Flow Weaver Constants
- *
- * This module defines reserved names and constants used throughout the Flow Weaver system.
- *
- * ## Scoped Port Architecture
- *
- * Scoped ports enable iteration patterns (forEach, map) WITHOUT graph cycles.
- * The key insight is that port directions are INVERTED for scoped ports:
- *
- * ```
- * ┌─────────────────────────────────────────────────────────────────────┐
- * │                    SCOPED PORT DIRECTION MAPPING                    │
- * ├─────────────────┬──────────┬────────────────────────────────────────┤
- * │ Scoped OUTPUT   │ Parent→  │ Parameters TO children (start, item)   │
- * │ Scoped INPUT    │ →Parent  │ Returns FROM children (success, result)│
- * └─────────────────┴──────────┴────────────────────────────────────────┘
- * ```
- *
- * **Why this inversion?**
- * - Scoped OUTPUT ports (like `start`, `item`) are data the parent SENDS to nested nodes
- * - Scoped INPUT ports (like `success`, `result`) are data the parent RECEIVES from nested nodes
- * - The loop iteration happens in the parent's imperative code, not as graph cycles
- *
- * ## Mandatory Scoped Ports
- *
- * Every scoped node must have these ports for each scope it declares:
- * - `start` (OUTPUT) - Triggers scope execution, passed as first param
- * - `success` (INPUT) - Signals successful completion from child
- * - `failure` (INPUT) - Signals failure from child
- *
- * ## Example: forEach Node
- *
- * ```typescript
- * @scope processItem
- * @output start scope:processItem    // OUTPUT → function param (triggers iteration)
- * @output item scope:processItem     // OUTPUT → function param (current item)
- * @input success scope:processItem   // INPUT → return value (completion signal)
- * @input processed scope:processItem // INPUT → return value (processed data)
- *
- * function forEach(execute, items, processItem) {
- *   const results = [];
- *   for (const item of items) {
- *     const r = processItem(true, item); // Calls generated closure
- *     if (r.success) results.push(r.processed);
- *   }
- *   return { onSuccess: true, results };
- * }
- * ```
- */
-export const RESERVED_NODE_NAMES = {
-    START: "Start",
-    EXIT: "Exit",
+import {
+  BRANCHING_STRATEGIES,
+  EXECUTION_STRATEGIES,
+  KNOWN_NODETYPE_TAGS,
+  KNOWN_WORKFLOW_TAGS,
+  MIN_NODE_MAJOR,
+  RESERVED_NODE_NAMES,
+  RESERVED_PORT_NAMES,
+  SCOPED_PORT_NAMES,
+  STANDARD_JSDOC_TAGS,
+  VALID_NODE_COLORS,
+  getKnownWorkflowTags,
+  isControlFlowPort,
+  isExecutePort,
+  isExitNode,
+  isFailurePort,
+  isPseudoNode,
+  isReservedNodeName,
+  isReservedPortName,
+  isScopedFailurePort,
+  isScopedMandatoryPort,
+  isScopedPort,
+  isScopedStartPort,
+  isScopedSuccessPort,
+  isSpecialNode,
+  isStartNode,
+  isSuccessPort
+} from "./chunks/chunk-R4QGNK34.js";
+import "./chunks/chunk-SEWDMQ6Q.js";
+export {
+  BRANCHING_STRATEGIES,
+  EXECUTION_STRATEGIES,
+  KNOWN_NODETYPE_TAGS,
+  KNOWN_WORKFLOW_TAGS,
+  MIN_NODE_MAJOR,
+  RESERVED_NODE_NAMES,
+  RESERVED_PORT_NAMES,
+  SCOPED_PORT_NAMES,
+  STANDARD_JSDOC_TAGS,
+  VALID_NODE_COLORS,
+  getKnownWorkflowTags,
+  isControlFlowPort,
+  isExecutePort,
+  isExitNode,
+  isFailurePort,
+  isPseudoNode,
+  isReservedNodeName,
+  isReservedPortName,
+  isScopedFailurePort,
+  isScopedMandatoryPort,
+  isScopedPort,
+  isScopedStartPort,
+  isScopedSuccessPort,
+  isSpecialNode,
+  isStartNode,
+  isSuccessPort
 };
-export const RESERVED_PORT_NAMES = {
-    EXECUTE: "execute",
-    ON_SUCCESS: "onSuccess",
-    ON_FAILURE: "onFailure",
-};
-// Scoped mandatory ports (different from external)
-export const SCOPED_PORT_NAMES = {
-    START: "start", // OUTPUT - starts scope iteration
-    SUCCESS: "success", // INPUT - success signal from scope
-    FAILURE: "failure", // INPUT - failure signal from scope
-};
-export const EXECUTION_STRATEGIES = {
-    CONJUNCTION: "CONJUNCTION",
-    DISJUNCTION: "DISJUNCTION",
-    CUSTOM: "CUSTOM",
-};
-export const BRANCHING_STRATEGIES = {
-    VALUE_BASED: "value-based",
-    EXCEPTION_BASED: "exception-based",
-    NONE: "none",
-};
-export function isReservedNodeName(name) {
-    return Object.values(RESERVED_NODE_NAMES).includes(name);
-}
-export function isReservedPortName(name) {
-    return Object.values(RESERVED_PORT_NAMES).includes(name);
-}
-export function isStartNode(nodeName) {
-    return nodeName === RESERVED_NODE_NAMES.START;
-}
-export function isExitNode(nodeName) {
-    return nodeName === RESERVED_NODE_NAMES.EXIT;
-}
-export function isSpecialNode(nodeName) {
-    return isStartNode(nodeName) || isExitNode(nodeName);
-}
-/** Pseudo-nodes like `secret:NAME` are connection sources that don't correspond to real node instances. */
-export function isPseudoNode(nodeName) {
-    return nodeName.startsWith('secret:');
-}
-export function isExecutePort(portName) {
-    return portName === RESERVED_PORT_NAMES.EXECUTE;
-}
-export function isSuccessPort(portName) {
-    return portName === RESERVED_PORT_NAMES.ON_SUCCESS;
-}
-export function isFailurePort(portName) {
-    return portName === RESERVED_PORT_NAMES.ON_FAILURE;
-}
-// Scoped port checks
-export function isScopedStartPort(portName) {
-    return portName === SCOPED_PORT_NAMES.START;
-}
-export function isScopedSuccessPort(portName) {
-    return portName === SCOPED_PORT_NAMES.SUCCESS;
-}
-export function isScopedFailurePort(portName) {
-    return portName === SCOPED_PORT_NAMES.FAILURE;
-}
-export function isScopedMandatoryPort(portName) {
-    return isScopedStartPort(portName) || isScopedSuccessPort(portName) || isScopedFailurePort(portName);
-}
-export function isControlFlowPort(portName) {
-    return (isExecutePort(portName) ||
-        isSuccessPort(portName) ||
-        isFailurePort(portName));
-}
-/**
- * Check if a port definition represents a scoped port
- * Scoped ports are FUNCTION type with a scope attribute
- */
-export function isScopedPort(portDef) {
-    return portDef.dataType === "FUNCTION" && portDef.scope !== undefined;
-}
-// ── Valid annotation values ───────────────────────────────────────────
-export const VALID_NODE_COLORS = [
-    'blue', 'purple', 'cyan', 'orange', 'pink', 'green', 'red', 'yellow', 'teal',
-];
-// ── Known annotation tags per block type ──────────────────────────────
-export const KNOWN_NODETYPE_TAGS = new Set([
-    'flowWeaver', 'name', 'label', 'description', 'color', 'icon', 'tag',
-    'executeWhen', 'scope', 'expression', 'pullExecution', 'input', 'output', 'step',
-    // Async is auto-detected from the TS signature but accepted as an explicit annotation
-    'async',
-    // Deployment annotations
-    'deploy',
-]);
-export const KNOWN_WORKFLOW_TAGS = new Set([
-    'flowWeaver', 'name', 'fwImport', 'description', 'strictTypes', 'autoConnect',
-    'node', 'position', 'connect', 'scope', 'map', 'path', 'fanOut', 'fanIn',
-    'coerce', 'trigger', 'cancelOn', 'retries', 'timeout', 'throttle', 'param',
-    'return', 'returns',
-    // Async is auto-detected from the TS signature but accepted as an explicit annotation
-    'async',
-    // Deployment annotations
-    'deploy',
-]);
-export const KNOWN_PATTERN_TAGS = new Set([
-    'flowWeaver', 'name', 'description', 'node', 'position', 'connect', 'port',
-]);
-export const STANDARD_JSDOC_TAGS = new Set([
-    'example', 'see', 'deprecated', 'type', 'typedef', 'template',
-    'link', 'since', 'version', 'author',
-]);
-/**
- * Build a dynamic known-workflow-tags set that includes core tags
- * plus any extra tags contributed by pack registries.
- */
-export function getKnownWorkflowTags(extraTags) {
-    if (!extraTags || extraTags.length === 0)
-        return KNOWN_WORKFLOW_TAGS;
-    return new Set([...KNOWN_WORKFLOW_TAGS, ...extraTags]);
-}
-//# sourceMappingURL=constants.js.map

package/dist/context/index.d.ts

@@ -22,6 +22,16 @@ export interface ContextResult {
     lineCount: number;
     topicSlugs: string[];
     profile: ContextProfile;
+    /**
+     * Every topic the bundle did not include, with its compact size, so a
+     * caller can decide what to load next without listing first. Pack topics
+     * are included once loaded.
+     */
+    availableTopics: Array<{
+        slug: string;
+        description: string;
+        compactBytes: number;
+    }>;
 }
 export declare const PRESETS: Record<ContextPreset, string[]>;
 export declare const PRESET_NAMES: ContextPreset[];

package/dist/context/index.js

@@ -1,192 +1,15 @@
-/**
- * LLM context bundle builder.
- *
- * Composes Flow Weaver documentation, annotation grammar, and a profile-specific
- * preamble into a single markdown document suitable for LLM consumption.
- */
-import { readTopic, listTopics, getPackDocTopics } from '../docs/index.js';
-import { getAllGrammars, serializedToEBNF } from '../chevrotain-parser/grammar-diagrams.js';
-// ---------------------------------------------------------------------------
-// Presets
-// ---------------------------------------------------------------------------
-export const PRESETS = {
-    core: ['concepts', 'jsdoc-grammar', 'tutorial'],
-    authoring: [
-        'concepts',
-        'jsdoc-grammar',
-        'advanced-annotations',
-        'built-in-nodes',
-        'scaffold',
-        'node-conversion',
-        'patterns',
-    ],
-    ops: [
-        'cli-reference',
-        'compilation',
-        'deployment',
-        'export-interface',
-        'debugging',
-        'error-codes',
-    ],
-    full: [
-        'concepts',
-        'tutorial',
-        'jsdoc-grammar',
-        'advanced-annotations',
-        'built-in-nodes',
-        'cli-reference',
-        'compilation',
-        'debugging',
-        'deployment',
-        'error-codes',
-        'export-interface',
-        'iterative-development',
-        'marketplace',
-        'node-conversion',
-        'patterns',
-        'scaffold',
-    ],
+import {
+  PRESETS,
+  PRESET_NAMES,
+  buildContext,
+  resolveTopics
+} from "../chunks/chunk-TN4YZ3O7.js";
+import "../chunks/chunk-KMWCCOUJ.js";
+import "../chunks/chunk-QYPORSLO.js";
+import "../chunks/chunk-SEWDMQ6Q.js";
+export {
+  PRESETS,
+  PRESET_NAMES,
+  buildContext,
+  resolveTopics
 };
-export const PRESET_NAMES = Object.keys(PRESETS);
-// ---------------------------------------------------------------------------
-// Preambles
-// ---------------------------------------------------------------------------
-const STANDALONE_PREAMBLE = `# Flow Weaver Reference
-
-Flow Weaver is a TypeScript workflow compiler. You write plain .ts files with
-JSDoc annotations (@flowWeaver nodeType, @flowWeaver workflow, @input, @output,
-@connect, @node, @scope). The compiler parses these annotations, validates the
-graph, and generates executable code inline. The source file is the workflow:
-no JSON configs, no YAML, no separate graph files.
-
-Key concepts: node types define reusable processing steps with typed input/output
-ports. Workflows instantiate nodes and connect their ports. Start and Exit are
-implicit boundary nodes. The compiler handles execution ordering, type checking,
-and code generation.`;
-function buildAssistantPreamble() {
-    const allSlugs = listTopics().map((t) => t.slug);
-    return `# Flow Weaver Context
-
-You have Flow Weaver MCP tools available (fw_ prefix). Use them to create,
-modify, validate, compile, and inspect workflows without manual file editing.
-
-For documentation not included below, call fw_docs(action="read", topic="<slug>").
-Available topic slugs: ${allSlugs.join(', ')}.
-
-Tool quick reference:
-- fw_create_model: Build workflow from structured description (steps + flow path)
-- fw_implement_node: Replace a declare stub with a real function body
-- fw_modify / fw_modify_batch: Add/remove nodes, connections, rename, reposition
-- fw_validate: Check for errors after any change
-- fw_describe: Inspect structure. Use format "text" for readable, "json" for data
-- fw_diagram: Visualize. Prefer format "ascii-compact" in chat contexts
-- fw_compile: Generate executable TypeScript from annotations
-- fw_docs: Look up reference docs by topic slug
-- fw_scaffold: Create from templates (sequential, foreach, ai-agent, cicd-test-deploy, cicd-docker, etc.)
-- fw_export: Deploy to cloud or generate CI/CD pipelines (targets depend on installed packs)
-
-Flow Weaver can also generate CI/CD pipelines. Use @secret, @runner, @trigger,
-@cache, @matrix, and [job: "name"] annotations to define pipeline structure,
-then export to GitHub Actions YAML or GitLab CI YAML with fw_export.
-For details: fw_docs(action="read", topic="cicd")
-
-File conventions: .ts extension, camelCase node names, PascalCase workflow names.`;
-}
-// ---------------------------------------------------------------------------
-// Topic resolution
-// ---------------------------------------------------------------------------
-export function resolveTopics(preset, explicit, add) {
-    const base = explicit ?? PRESETS[preset];
-    // Append pack doc topics that declare this preset
-    const packSlugs = getPackDocTopics()
-        .filter((t) => t.presets?.includes(preset))
-        .map((t) => t.slug);
-    const combined = [...base, ...packSlugs, ...(add ?? [])];
-    // Deduplicate while preserving order
-    return [...new Set(combined)];
-}
-// ---------------------------------------------------------------------------
-// Grammar builder
-// ---------------------------------------------------------------------------
-function buildGrammarSection() {
-    const grammars = getAllGrammars();
-    const allProductions = [
-        ...grammars.port,
-        ...grammars.node,
-        ...grammars.connect,
-        ...grammars.position,
-        ...grammars.scope,
-    ];
-    const ebnf = serializedToEBNF(allProductions);
-    return `## JSDoc Annotation Grammar (EBNF)\n\n\`\`\`ebnf\n${ebnf}\n\`\`\``;
-}
-// ---------------------------------------------------------------------------
-// Main builder
-// ---------------------------------------------------------------------------
-export function buildContext(options = {}) {
-    const profile = options.profile ?? 'standalone';
-    const preset = options.preset ?? 'core';
-    const includeGrammar = options.includeGrammar ?? true;
-    const topicSlugs = resolveTopics(preset, options.topics, options.addTopics);
-    const sections = [];
-    // Preamble
-    if (profile === 'standalone') {
-        sections.push(STANDALONE_PREAMBLE);
-    }
-    else {
-        sections.push(buildAssistantPreamble());
-    }
-    // Grammar
-    if (includeGrammar) {
-        sections.push(buildGrammarSection());
-    }
-    // Topics
-    let topicCount = 0;
-    const includedSlugs = [];
-    for (const slug of topicSlugs) {
-        const doc = readTopic(slug, true);
-        if (!doc)
-            continue;
-        // Compact mode prepends "# Name\ndescription\n" which duplicates our heading.
-        // Strip the leading heading block so we can use our own consistent ## heading.
-        // Then bump all remaining headings down one level so they nest under our ##.
-        let body = doc.content;
-        if (body.startsWith('# ')) {
-            const lines = body.split('\n');
-            // Skip the "# Name" line and the description line that follows it
-            let startLine = 1;
-            if (lines.length > 1 && lines[1].trim() && !lines[1].startsWith('#')) {
-                startLine = 2;
-            }
-            body = lines.slice(startLine).join('\n').replace(/^\n+/, '');
-        }
-        // Bump all headings down one level (# -> ##, ## -> ###, etc.)
-        // so they nest under our ## topic heading. Only transform outside code blocks.
-        const bodyLines = body.split('\n');
-        let inCode = false;
-        for (let i = 0; i < bodyLines.length; i++) {
-            if (bodyLines[i].trimStart().startsWith('```')) {
-                inCode = !inCode;
-                continue;
-            }
-            if (!inCode && bodyLines[i].match(/^#{1,5}\s/)) {
-                bodyLines[i] = '##' + bodyLines[i];
-            }
-        }
-        body = bodyLines.join('\n');
-        const heading = doc.name || slug;
-        sections.push(`## ${heading}\n\n${body}`);
-        topicCount++;
-        includedSlugs.push(slug);
-    }
-    const content = sections.join('\n\n---\n\n');
-    const lineCount = content.split('\n').length;
-    return {
-        content,
-        topicCount,
-        lineCount,
-        topicSlugs: includedSlugs,
-        profile,
-    };
-}
-//# sourceMappingURL=index.js.map