@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/api/manipulation/nodes.d.ts

@@ -1,8 +1,8 @@
 /**
  * Node instance operations for workflow manipulation
  */
-import type { TWorkflowAST, TNodeInstanceAST, TNodeInstanceConfig } from "../../ast/types.js";
-import { type RemoveOptions } from "../helpers.js";
+import type { TWorkflowAST, TNodeInstanceAST, TNodeInstanceConfig } from "../../ast/types";
+import { type RemoveOptions } from "../helpers";
 /**
  * Add a node instance to the workflow
  *
@@ -70,7 +70,7 @@ export declare function renameNode(ast: TWorkflowAST, oldId: string, newId: stri
  * @example
  * ```typescript
  * const ast = updateNode(workflow, 'processor1', {
- *   config: { x: 100, y: 200, label: 'Main Processor' }
+ *   config: { label: 'Main Processor' }
  * });
  * ```
  */
@@ -103,16 +103,6 @@ export declare function removeNodes(ast: TWorkflowAST, nodeIds: string[]): TWork
  * @returns Modified workflow
  */
 export declare function setNodeConfig(ast: TWorkflowAST, nodeId: string, config: TNodeInstanceConfig): TWorkflowAST;
-/**
- * Set node position (UI coordinates)
- *
- * @param ast - Workflow to modify
- * @param nodeId - ID of node to position (including virtual nodes "Start" and "Exit")
- * @param x - X coordinate
- * @param y - Y coordinate
- * @returns Modified workflow
- */
-export declare function setNodePosition(ast: TWorkflowAST, nodeId: string, x: number, y: number): TWorkflowAST;
 /**
  * Set node minimized state (UI state)
  *

package/dist/api/manipulation/ports.d.ts

@@ -1,7 +1,7 @@
 /**
  * Port operations for workflow manipulation
  */
-import type { TWorkflowAST } from "../../ast/types.js";
+import type { TWorkflowAST } from "../../ast/types";
 /**
  * Swap the order of two ports on a node type (Start/Exit only)
  * For regular instances, use swapNodeInstancePortOrder()

package/dist/api/manipulation/scopes.d.ts

@@ -1,7 +1,7 @@
 /**
  * Scope operations for workflow manipulation
  */
-import type { TWorkflowAST } from "../../ast/types.js";
+import type { TWorkflowAST } from "../../ast/types";
 /**
  * Create a new scope
  *

package/dist/api/manipulation/workflow.d.ts

@@ -1,7 +1,7 @@
 /**
  * Workflow-level operations for manipulation
  */
-import type { TWorkflowAST, TWorkflowMetadata, TNodeTypePort } from "../../ast/types.js";
+import type { TWorkflowAST, TWorkflowMetadata, TNodeTypePort } from "../../ast/types";
 /**
  * Clone a workflow (creates deep copy via Immer)
  *

package/dist/api/modify-operation.d.ts

@@ -1,6 +1,4 @@
-import { z } from 'zod';
 import type { TWorkflowAST } from '../ast/types.js';
-export declare const modifyParamsSchemas: Record<string, z.ZodType>;
 export declare function validateModifyParams(operation: string, params: Record<string, unknown>): {
     success: true;
 } | {

package/dist/api/parse.d.ts

@@ -1,4 +1,9 @@
-import type { TParseOptions as ASTParseOptions, TWorkflowAST } from '../ast/types.js';
+import type { TParseOptions as ASTParseOptions, TWorkflowAST } from '../ast/types';
+import { type SourceImportResolver, type SourceOverrideLoader, type TExternalNodeType } from '../parser/annotation-parser';
+/** Prefix of the parse error raised when a file declares several workflows and none was named. */
+export declare const MULTIPLE_WORKFLOWS_MARKER = "[MULTIPLE_WORKFLOWS_FOUND]";
+/** The parse failed only because the file declares several workflows and none was picked. */
+export declare function isMultipleWorkflows(errors: readonly unknown[]): boolean;
 export interface ParseOptions extends Partial<ASTParseOptions> {
     /**
      * Name of the workflow to parse from the file.
@@ -15,6 +20,20 @@ export interface ParseOptions extends Partial<ASTParseOptions> {
      * marketplace packs are discovered and registered before parsing.
      */
     projectDir?: string;
+    /**
+     * Definitions of foreign nodeTypes the workflow references by name
+     * (an `@node <id> <foreignType>` from another pack). Forwarded to the
+     * underlying `parser.parse(filePath, externalNodeTypes)` so the
+     * reference resolves without the foreign pack's source on the parse
+     * path. Callers that resolve these from a wire manifest (rather than
+     * from `node_modules`) pass them here. Omit when the file declares
+     * every nodeType it uses.
+     */
+    externalNodeTypes?: TExternalNodeType[];
+    /** @internal Resolver for a virtual pre-bundle TypeScript module graph. */
+    sourceImportResolver?: SourceImportResolver;
+    /** @internal Source overlays for a virtual pre-bundle TypeScript graph. */
+    sourceOverrideLoader?: SourceOverrideLoader;
 }
 export interface ParseResult {
     ast: TWorkflowAST;
@@ -50,4 +69,6 @@ export interface ParseResult {
  * ```
  */
 export declare function parseWorkflow(filePath: string, options?: ParseOptions): Promise<ParseResult>;
+/** @internal Parse a source override without erasing its real import base. */
+export declare function parseWorkflowSourceAtPath(filePath: string, source: string, options?: ParseOptions): Promise<ParseResult>;
 //# sourceMappingURL=parse.d.ts.map

package/dist/api/port-references.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Port reference helpers.
+ *
+ * Pure functions over TPortReference with no dependency on validation, so the
+ * query layer can compare references without importing the manipulation
+ * helpers (which validate, and validation reads the query layer).
+ */
+import type { TPortReference } from "../ast/types";
+/**
+ * Validates and normalizes port reference format
+ * Accepts either string format ("nodeId.portName") or object format ({ node, port })
+ *
+ * @param ref - Port reference to validate
+ * @returns Validated TPortReference object
+ * @throws {Error} If format is invalid
+ *
+ * @example
+ * ```typescript
+ * // String format
+ * const ref1 = validatePortReference("processor1.input");
+ * // Returns: { node: "processor1", port: "input" }
+ *
+ * // Object format
+ * const ref2 = validatePortReference({ node: "processor1", port: "input" });
+ * // Returns: { node: "processor1", port: "input" }
+ *
+ * // Invalid format throws error
+ * validatePortReference("invalid"); // Throws: Invalid port reference format
+ * ```
+ */
+export declare function validatePortReference(ref: string | TPortReference): TPortReference;
+/**
+ * Checks if two port references point to the same port
+ * Compares both node ID and port name for equality
+ *
+ * @param a - First port reference
+ * @param b - Second port reference
+ * @returns True if both references point to the same port
+ *
+ * @example
+ * ```typescript
+ * const ref1 = { node: "processor1", port: "input" };
+ * const ref2 = { node: "processor1", port: "input" };
+ * const ref3 = { node: "processor1", port: "output" };
+ *
+ * portReferencesEqual(ref1, ref2); // true
+ * portReferencesEqual(ref1, ref3); // false
+ * ```
+ */
+export declare function portReferencesEqual(a: TPortReference, b: TPortReference): boolean;
+/**
+ * Formats a port reference object as a string
+ * Converts { node, port } to "node.port" format
+ *
+ * @param ref - Port reference to format
+ * @returns String representation in "node.port" format
+ *
+ * @example
+ * ```typescript
+ * const ref = { node: "processor1", port: "input" };
+ * const str = formatPortReference(ref);
+ * // Returns: "processor1.input"
+ * ```
+ */
+export declare function formatPortReference(ref: TPortReference): string;
+//# sourceMappingURL=port-references.d.ts.map

package/dist/api/query.d.ts

@@ -2,8 +2,8 @@
  * Query API for read-only workflow inspection
  * All functions are pure and do not modify the workflow
  */
-import type { TWorkflowAST, TNodeInstanceAST, TConnectionAST, TPortReference } from '../ast/types.js';
-import type { NodeFilter } from './helpers.js';
+import type { TWorkflowAST, TNodeInstanceAST, TConnectionAST, TPortReference } from '../ast/types';
+import type { NodeFilter } from './helpers';
 /**
  * Get a single node instance by ID
  *
@@ -428,4 +428,20 @@ export declare function findDisconnectedOutputPorts(ast: TWorkflowAST): Array<{
     nodeId: string;
     ports: string[];
 }>;
+/** A file that contains one or more workflows, with a summary of each. */
+export interface WorkflowFileInfo {
+    filePath: string;
+    workflows: Array<{
+        name: string;
+        functionName: string;
+        nodeCount: number;
+        connectionCount: number;
+    }>;
+}
+/**
+ * Find workflow files under a directory (optionally filtered by a glob),
+ * returning a summary of the workflows each one declares. Files that fail to
+ * parse are skipped. Read-only: nothing is written.
+ */
+export declare function findWorkflows(directory: string, pattern?: string): Promise<WorkflowFileInfo[]>;
 //# sourceMappingURL=query.d.ts.map

package/dist/api/templates.d.ts

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import { type WorkflowTemplate, type NodeTemplate, type WorkflowTemplateOptions } from "../cli/templates/index.js";
+import { type WorkflowTemplate, type NodeTemplate, type WorkflowTemplateOptions } from "../cli/templates";
 export type { WorkflowTemplate, NodeTemplate, WorkflowTemplateOptions };
 /**
  * List all available workflow templates

package/dist/api/transform.d.ts

@@ -1,4 +1,4 @@
-import type { TASTTransformer, TWorkflowAST } from "../ast/types.js";
+import type { TASTTransformer, TWorkflowAST } from "../ast/types";
 /**
  * Applies a single transformer to a workflow AST.
  * The AST is deep-cloned before transformation to avoid mutating the original.

package/dist/api/validate.d.ts

@@ -5,7 +5,7 @@
  * the consolidated WorkflowValidator internally.
  */
 import type { TValidationRule, TWorkflowAST } from "../ast/index.js";
-import { type TValidationError } from "../validator.js";
+import { type TValidationError } from "../validation/validator";
 export interface ValidationResult {
     valid: boolean;
     errors: TValidationError[];

package/dist/api/validation-registry.d.ts

@@ -1,10 +1,10 @@
 /**
  * Singleton validation rule registry for the public API.
  *
- * Core rule sets (agent, CI/CD) are registered statically.
+ * Core rule sets (e.g. agent rules) are registered statically.
  * Pack-contributed rule sets are registered via marketplace discovery.
  */
-import { ValidationRuleRegistry } from '../validation/rule-registry.js';
+import { ValidationRuleRegistry } from '../validation/rule-registry';
 /** Global validation rule registry. Packs register rule sets here at startup. */
 export declare const validationRuleRegistry: ValidationRuleRegistry;
 //# sourceMappingURL=validation-registry.d.ts.map

package/dist/artifacts/brief.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A workflow as a document for people who will not open the code.
+ *
+ * The picture comes first: the spine the console draws, large, with every
+ * step there to be clicked. A product manager reads what goes in, what
+ * comes out and where a person is needed. An architect reads the same and
+ * follows the arms. One self-contained file, nothing fetched.
+ *
+ * Two renderings of the same content:
+ * - `interactive` (the default): the page. Click a step and a panel beside
+ *   the graph says what it does, what it reads, what it hands on and where
+ *   its failure goes, and the edges that touch it light up. Light and dark, a
+ *   print button.
+ * - `print`: the same content for paper, no script. The first page is the
+ *   overview -- the graph at the size the console draws it, beside what goes
+ *   in, what comes out, who is waited for and what happens on failure. The
+ *   pages after it are every step in detail. This is what the PDF is made
+ *   from. The interactive page prints its own, simpler, version.
+ */
+import type { TWorkflowAST } from '../ast/types.js';
+export interface BriefOptions {
+    theme?: 'light' | 'dark';
+    /** Shown under the title, the project's name, say. */
+    subtitle?: string;
+    /** The page (default), or the same content laid out for paper. */
+    mode?: 'interactive' | 'print';
+}
+/** The brief as HTML. */
+export declare function renderBrief(ast: TWorkflowAST, options?: BriefOptions): string;
+/**
+ * Where the graph goes and how large. It is drawn at its natural size when
+ * that fits beside the overview on the first page, scaled down when it is
+ * somewhat too tall, and given a page of its own when scaling it to fit
+ * would make it unreadable. Pure, so it is tested with numbers.
+ */
+export declare function fitGraph(w: number, h: number, headerPx: number, page?: {
+    w: number;
+    h: number;
+}): {
+    scale: number;
+    ownPage: boolean;
+};
+//# sourceMappingURL=brief.d.ts.map

package/dist/artifacts/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Artifacts: a workflow as something to hand to a person.
+ *
+ * - the brief, as a page (interactive) or laid out for paper (print)
+ * - the brief as a PDF, printed by the browser on the machine
+ * - the spine as an SVG (from the diagram module)
+ *
+ * `fw artifact`, the console's Share menu and the MCP tools all come here.
+ */
+import type { TWorkflowAST } from '../ast/types.js';
+import { type BriefOptions } from './brief.js';
+import { type PdfOptions } from './pdf.js';
+export type { BriefOptions } from './brief.js';
+export type { PdfOptions } from './pdf.js';
+export type ArtifactKind = 'brief' | 'pdf' | 'svg';
+export declare const ARTIFACT_KINDS: readonly ArtifactKind[];
+export interface ArtifactOptions extends BriefOptions {
+    pdf?: PdfOptions;
+}
+export interface Artifact {
+    kind: ArtifactKind;
+    /** The bytes, or a string for text formats. */
+    body: string | Buffer;
+    /** MIME type for a download. */
+    type: string;
+    /** File extension including the dot, e.g. `.brief.html`. */
+    extension: string;
+}
+/** Produce one artifact from a parsed workflow. */
+export declare function renderArtifact(ast: TWorkflowAST, kind: ArtifactKind, options?: ArtifactOptions): Promise<Artifact>;
+//# sourceMappingURL=index.d.ts.map

package/dist/artifacts/pdf.d.ts

@@ -0,0 +1,19 @@
+export declare class BrowserNotFoundError extends Error {
+    readonly name = "BrowserNotFoundError";
+    constructor();
+}
+/**
+ * The browser to print with: `FW_BROWSER` (or `CHROME_PATH`,
+ * `PUPPETEER_EXECUTABLE_PATH`) when set, else the first one found where the
+ * platform installs them. `undefined` when there is none.
+ */
+export declare function findBrowser(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | undefined;
+export interface PdfOptions {
+    /** The browser binary; found on the machine when omitted. */
+    browser?: string;
+    /** How long to give the browser, in milliseconds. Default 60 s. */
+    timeoutMs?: number;
+}
+/** Print an HTML document to PDF. Resolves to the PDF's bytes. */
+export declare function htmlToPdf(html: string, options?: PdfOptions): Promise<Buffer>;
+//# sourceMappingURL=pdf.d.ts.map

package/dist/ast/builder.d.ts

@@ -1,4 +1,4 @@
-import type { TBranchingStrategy, TConnectionAST, TDataType, TExecuteWhen, TImportDeclaration, TImportSpecifier, TNodeTypeAST, TNodeInstanceAST, TPortDefinition, TPortReference, TSerializableValue, TWorkflowAST } from "./types.js";
+import type { TBranchingStrategy, TConnectionAST, TDataType, TExecuteWhen, TImportDeclaration, TImportSpecifier, TNodeTypeAST, TNodeInstanceAST, TPortDefinition, TPortReference, TSerializableValue, TWorkflowAST } from "./types";
 /**
  * Fluent builder for constructing TWorkflowAST programmatically
  *
@@ -65,7 +65,7 @@ export declare class NodeTypeBuilder {
     failurePort(enabled?: boolean): this;
     executeWhen(when: TExecuteWhen): this;
     branchingStrategy(strategy: TBranchingStrategy, field?: string): this;
-    defaultConfig(config: import("./types.js").TNodeTypeDefaultConfig): this;
+    defaultConfig(config: import("./types").TNodeTypeDefaultConfig): this;
     metadata(key: string, value: unknown): this;
     /** Build and return the final TNodeTypeAST */
     build(): TNodeTypeAST;
@@ -90,7 +90,7 @@ export declare class NodeInstanceBuilder {
      * @param nodeType - Name of the NodeType this instance references
      */
     constructor(id: string, nodeType: string);
-    config(configData: import("./types.js").TNodeInstanceConfig): this;
+    config(configData: import("./types").TNodeInstanceConfig): this;
     parentScope(scope: string): this;
     metadata(key: string, value: unknown): this;
     /** Build and return the final TNodeInstanceAST */

package/dist/ast/index.d.ts

@@ -1,5 +1,5 @@
-export * from "./builder.js";
-export * from "./types.js";
-export * from "./workflow-utils.js";
-export * from "./serialization.js";
+export * from "./builder";
+export * from "./types";
+export * from "./workflow-utils";
+export * from "./serialization";
 //# sourceMappingURL=index.d.ts.map

package/dist/ast/index.js

@@ -1,5 +1,60 @@
-export * from "./builder.js";
-export * from "./types.js";
-export * from "./workflow-utils.js";
-export * from "./serialization.js";
-//# sourceMappingURL=index.js.map
+import {
+  astToString,
+  deserializeAST,
+  serializeAST,
+  validateASTStructure
+} from "../chunks/chunk-VWA7MCV2.js";
+import {
+  ConnectionBuilder,
+  NodeInstanceBuilder,
+  NodeTypeBuilder,
+  WorkflowBuilder,
+  connect,
+  connection,
+  defaultImport,
+  importDecl,
+  namedImport,
+  namespaceImport,
+  nodeInstance,
+  nodeType,
+  port,
+  portRef,
+  workflow
+} from "../chunks/chunk-CY3RNVML.js";
+import {
+  extractExitPorts,
+  extractStartPorts,
+  getConnectionsFrom,
+  getConnectionsTo,
+  getNodeType,
+  hasBranching
+} from "../chunks/chunk-CZBCCK4Y.js";
+import "../chunks/chunk-R4QGNK34.js";
+import "../chunks/chunk-SEWDMQ6Q.js";
+export {
+  ConnectionBuilder,
+  NodeInstanceBuilder,
+  NodeTypeBuilder,
+  WorkflowBuilder,
+  astToString,
+  connect,
+  connection,
+  defaultImport,
+  deserializeAST,
+  extractExitPorts,
+  extractStartPorts,
+  getConnectionsFrom,
+  getConnectionsTo,
+  getNodeType,
+  hasBranching,
+  importDecl,
+  namedImport,
+  namespaceImport,
+  nodeInstance,
+  nodeType,
+  port,
+  portRef,
+  serializeAST,
+  validateASTStructure,
+  workflow
+};

package/dist/ast/serialization-node.d.ts

@@ -1,4 +1,4 @@
-import type { TWorkflowAST } from "./types.js";
+import type { TWorkflowAST } from "./types";
 export declare function saveAST(ast: TWorkflowAST, filePath: string): Promise<void>;
 export declare function loadAST(filePath: string): Promise<TWorkflowAST>;
 export declare function saveASTAlongside(ast: TWorkflowAST): Promise<string>;

package/dist/ast/serialization.d.ts

@@ -1,4 +1,4 @@
-import type { TWorkflowAST } from "./types.js";
+import type { TWorkflowAST } from "./types";
 /**
  * Serializes a workflow AST to a JSON string.
  *