@genfeedai/workflows 0.2.0 → 0.3.0

package/README.md

@@ -94,3 +94,19 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on submitting new workfl
 ## License
 
 AGPL-3.0
+
+
+## Extension & Engine Contracts
+
+Use shared contracts for workflow engines and cloud extension packs:
+
+```typescript
+import type {
+  ExecutableWorkflow,
+  NodeDefinition,
+  ExtensionPack,
+  NodeRegistry,
+} from '@genfeedai/workflows/contracts';
+```
+
+These contracts are designed so private/cloud node packs can extend public core workflows without forking type definitions.

package/dist/chunk-CTZNKWZB.mjs

@@ -0,0 +1,39 @@
+// src/contracts/execution.ts
+var DEFAULT_RETRY_CONFIG = {
+  backoffMultiplier: 2,
+  baseDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  maxRetries: 3
+};
+
+// src/extensions/registry.ts
+var InMemoryNodeRegistry = class {
+  nodes = /* @__PURE__ */ new Map();
+  register(node) {
+    this.nodes.set(this.key(node.type, node.version), node);
+  }
+  registerMany(nodes) {
+    for (const node of nodes) this.register(node);
+  }
+  registerPack(pack) {
+    this.registerMany(pack.nodes);
+  }
+  get(type, version) {
+    if (version !== void 0) {
+      return this.nodes.get(this.key(type, version));
+    }
+    const candidates = [...this.nodes.values()].filter((node) => node.type === type).sort((a, b) => b.version - a.version);
+    return candidates[0];
+  }
+  list() {
+    return [...this.nodes.values()];
+  }
+  key(type, version) {
+    return `${type}@${version}`;
+  }
+};
+
+export {
+  DEFAULT_RETRY_CONFIG,
+  InMemoryNodeRegistry
+};

package/dist/contracts/index.d.mts

@@ -0,0 +1,127 @@
+type ExecutionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+type NodeExecutionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+type WorkflowLifecycle = 'draft' | 'published' | 'archived';
+interface ExecutionProgressEvent {
+    runId: string;
+    workflowId: string;
+    progress: number;
+    currentNodeId?: string;
+    currentNodeLabel?: string;
+    completedNodes: string[];
+    failedNodes: string[];
+    timestamp: Date;
+}
+interface NodeStatusChangeEvent {
+    runId: string;
+    workflowId: string;
+    nodeId: string;
+    previousStatus: NodeExecutionStatus;
+    newStatus: NodeExecutionStatus;
+    error?: string;
+    output?: unknown;
+    timestamp: Date;
+}
+interface ExecutionOptions {
+    nodeIds?: string[];
+    resumeFromNodeId?: string;
+    respectLocks?: boolean;
+    maxRetries?: number;
+    onProgress?: (event: ExecutionProgressEvent) => void;
+    onNodeStatusChange?: (event: NodeStatusChangeEvent) => void;
+    availableCredits?: number;
+    dryRun?: boolean;
+}
+interface ExecutableNode {
+    id: string;
+    type: string;
+    label: string;
+    config: Record<string, unknown>;
+    inputs: string[];
+    isLocked?: boolean;
+    cachedOutput?: unknown;
+}
+interface ExecutableEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+}
+interface ExecutableWorkflow {
+    id: string;
+    organizationId: string;
+    userId: string;
+    nodes: ExecutableNode[];
+    edges: ExecutableEdge[];
+    lockedNodeIds: string[];
+}
+interface ValidationResult {
+    isValid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+interface ValidationError {
+    code: string;
+    message: string;
+    nodeId?: string;
+    field?: string;
+}
+interface ValidationWarning {
+    code: string;
+    message: string;
+    nodeId?: string;
+}
+interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    backoffMultiplier: number;
+}
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+
+/**
+ * Stable extension contracts for workflow engines.
+ * Cloud/private packages should implement these interfaces without forking them.
+ */
+type NodeSchema = Record<string, unknown>;
+interface NodeDefinition {
+    type: string;
+    version: number;
+    label: string;
+    description?: string;
+    inputs: NodeSchema;
+    outputs: NodeSchema;
+    configSchema?: NodeSchema;
+}
+interface NodeExecutionContext {
+    environment?: 'local' | 'cloud';
+    metadata?: Record<string, unknown>;
+}
+interface ExtensionPack {
+    id: string;
+    version: string;
+    nodes: NodeDefinition[];
+    capabilities?: string[];
+}
+
+/**
+ * Minimal registry interface for composing core and private workflow node packs.
+ */
+interface NodeRegistry {
+    register(node: NodeDefinition): void;
+    registerMany(nodes: NodeDefinition[]): void;
+    registerPack(pack: ExtensionPack): void;
+    get(type: string, version?: number): NodeDefinition | undefined;
+    list(): NodeDefinition[];
+}
+declare class InMemoryNodeRegistry implements NodeRegistry {
+    private readonly nodes;
+    register(node: NodeDefinition): void;
+    registerMany(nodes: NodeDefinition[]): void;
+    registerPack(pack: ExtensionPack): void;
+    get(type: string, version?: number): NodeDefinition | undefined;
+    list(): NodeDefinition[];
+    private key;
+}
+
+export { DEFAULT_RETRY_CONFIG, type ExecutableEdge, type ExecutableNode, type ExecutableWorkflow, type ExecutionOptions, type ExecutionProgressEvent, type ExecutionStatus, type ExtensionPack, InMemoryNodeRegistry, type NodeDefinition, type NodeExecutionContext, type NodeExecutionStatus, type NodeRegistry, type NodeSchema, type NodeStatusChangeEvent, type RetryConfig, type ValidationError, type ValidationResult, type ValidationWarning, type WorkflowLifecycle };

package/dist/contracts/index.d.ts

@@ -0,0 +1,127 @@
+type ExecutionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+type NodeExecutionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+type WorkflowLifecycle = 'draft' | 'published' | 'archived';
+interface ExecutionProgressEvent {
+    runId: string;
+    workflowId: string;
+    progress: number;
+    currentNodeId?: string;
+    currentNodeLabel?: string;
+    completedNodes: string[];
+    failedNodes: string[];
+    timestamp: Date;
+}
+interface NodeStatusChangeEvent {
+    runId: string;
+    workflowId: string;
+    nodeId: string;
+    previousStatus: NodeExecutionStatus;
+    newStatus: NodeExecutionStatus;
+    error?: string;
+    output?: unknown;
+    timestamp: Date;
+}
+interface ExecutionOptions {
+    nodeIds?: string[];
+    resumeFromNodeId?: string;
+    respectLocks?: boolean;
+    maxRetries?: number;
+    onProgress?: (event: ExecutionProgressEvent) => void;
+    onNodeStatusChange?: (event: NodeStatusChangeEvent) => void;
+    availableCredits?: number;
+    dryRun?: boolean;
+}
+interface ExecutableNode {
+    id: string;
+    type: string;
+    label: string;
+    config: Record<string, unknown>;
+    inputs: string[];
+    isLocked?: boolean;
+    cachedOutput?: unknown;
+}
+interface ExecutableEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+}
+interface ExecutableWorkflow {
+    id: string;
+    organizationId: string;
+    userId: string;
+    nodes: ExecutableNode[];
+    edges: ExecutableEdge[];
+    lockedNodeIds: string[];
+}
+interface ValidationResult {
+    isValid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+interface ValidationError {
+    code: string;
+    message: string;
+    nodeId?: string;
+    field?: string;
+}
+interface ValidationWarning {
+    code: string;
+    message: string;
+    nodeId?: string;
+}
+interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    backoffMultiplier: number;
+}
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+
+/**
+ * Stable extension contracts for workflow engines.
+ * Cloud/private packages should implement these interfaces without forking them.
+ */
+type NodeSchema = Record<string, unknown>;
+interface NodeDefinition {
+    type: string;
+    version: number;
+    label: string;
+    description?: string;
+    inputs: NodeSchema;
+    outputs: NodeSchema;
+    configSchema?: NodeSchema;
+}
+interface NodeExecutionContext {
+    environment?: 'local' | 'cloud';
+    metadata?: Record<string, unknown>;
+}
+interface ExtensionPack {
+    id: string;
+    version: string;
+    nodes: NodeDefinition[];
+    capabilities?: string[];
+}
+
+/**
+ * Minimal registry interface for composing core and private workflow node packs.
+ */
+interface NodeRegistry {
+    register(node: NodeDefinition): void;
+    registerMany(nodes: NodeDefinition[]): void;
+    registerPack(pack: ExtensionPack): void;
+    get(type: string, version?: number): NodeDefinition | undefined;
+    list(): NodeDefinition[];
+}
+declare class InMemoryNodeRegistry implements NodeRegistry {
+    private readonly nodes;
+    register(node: NodeDefinition): void;
+    registerMany(nodes: NodeDefinition[]): void;
+    registerPack(pack: ExtensionPack): void;
+    get(type: string, version?: number): NodeDefinition | undefined;
+    list(): NodeDefinition[];
+    private key;
+}
+
+export { DEFAULT_RETRY_CONFIG, type ExecutableEdge, type ExecutableNode, type ExecutableWorkflow, type ExecutionOptions, type ExecutionProgressEvent, type ExecutionStatus, type ExtensionPack, InMemoryNodeRegistry, type NodeDefinition, type NodeExecutionContext, type NodeExecutionStatus, type NodeRegistry, type NodeSchema, type NodeStatusChangeEvent, type RetryConfig, type ValidationError, type ValidationResult, type ValidationWarning, type WorkflowLifecycle };

package/dist/contracts/index.js

@@ -0,0 +1,66 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/contracts/index.ts
+var contracts_exports = {};
+__export(contracts_exports, {
+  DEFAULT_RETRY_CONFIG: () => DEFAULT_RETRY_CONFIG,
+  InMemoryNodeRegistry: () => InMemoryNodeRegistry
+});
+module.exports = __toCommonJS(contracts_exports);
+
+// src/contracts/execution.ts
+var DEFAULT_RETRY_CONFIG = {
+  backoffMultiplier: 2,
+  baseDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  maxRetries: 3
+};
+
+// src/extensions/registry.ts
+var InMemoryNodeRegistry = class {
+  nodes = /* @__PURE__ */ new Map();
+  register(node) {
+    this.nodes.set(this.key(node.type, node.version), node);
+  }
+  registerMany(nodes) {
+    for (const node of nodes) this.register(node);
+  }
+  registerPack(pack) {
+    this.registerMany(pack.nodes);
+  }
+  get(type, version) {
+    if (version !== void 0) {
+      return this.nodes.get(this.key(type, version));
+    }
+    const candidates = [...this.nodes.values()].filter((node) => node.type === type).sort((a, b) => b.version - a.version);
+    return candidates[0];
+  }
+  list() {
+    return [...this.nodes.values()];
+  }
+  key(type, version) {
+    return `${type}@${version}`;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_RETRY_CONFIG,
+  InMemoryNodeRegistry
+});

package/dist/contracts/index.mjs

@@ -0,0 +1,8 @@
+import {
+  DEFAULT_RETRY_CONFIG,
+  InMemoryNodeRegistry
+} from "../chunk-CTZNKWZB.mjs";
+export {
+  DEFAULT_RETRY_CONFIG,
+  InMemoryNodeRegistry
+};

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+export { DEFAULT_RETRY_CONFIG, ExecutableEdge, ExecutableNode, ExecutableWorkflow, ExecutionOptions, ExecutionProgressEvent, ExecutionStatus, ExtensionPack, InMemoryNodeRegistry, NodeDefinition, NodeExecutionContext, NodeExecutionStatus, NodeRegistry, NodeSchema, NodeStatusChangeEvent, RetryConfig, ValidationError, ValidationResult, ValidationWarning, WorkflowLifecycle } from './contracts/index.mjs';
 import { ComfyUIPrompt, ComfyUIQueuePromptResponse, ComfyUIHistoryEntry, ComfyUIWorkflowTemplate, WorkflowNode, WorkflowEdge } from '@genfeedai/types';
 
 interface ComfyUIClientOptions {
@@ -132,13 +133,6 @@ interface ZImageTurboLoraParams extends ZImageTurboParams {
 }
 declare function buildZImageTurboLoraPrompt(params: ZImageTurboLoraParams): ComfyUIPrompt;
 
-/**
- * Workflow Registry for @genfeedai/workflows
- *
- * This registry contains metadata for all official workflow templates.
- * The actual workflow JSON files are stored in the `workflows/` directory.
- */
-
 interface WorkflowJson {
     version: number;
     name: string;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { DEFAULT_RETRY_CONFIG, ExecutableEdge, ExecutableNode, ExecutableWorkflow, ExecutionOptions, ExecutionProgressEvent, ExecutionStatus, ExtensionPack, InMemoryNodeRegistry, NodeDefinition, NodeExecutionContext, NodeExecutionStatus, NodeRegistry, NodeSchema, NodeStatusChangeEvent, RetryConfig, ValidationError, ValidationResult, ValidationWarning, WorkflowLifecycle } from './contracts/index.js';
 import { ComfyUIPrompt, ComfyUIQueuePromptResponse, ComfyUIHistoryEntry, ComfyUIWorkflowTemplate, WorkflowNode, WorkflowEdge } from '@genfeedai/types';
 
 interface ComfyUIClientOptions {
@@ -132,13 +133,6 @@ interface ZImageTurboLoraParams extends ZImageTurboParams {
 }
 declare function buildZImageTurboLoraPrompt(params: ZImageTurboLoraParams): ComfyUIPrompt;
 
-/**
- * Workflow Registry for @genfeedai/workflows
- *
- * This registry contains metadata for all official workflow templates.
- * The actual workflow JSON files are stored in the `workflows/` directory.
- */
-
 interface WorkflowJson {
     version: number;
     name: string;

package/dist/index.js

@@ -32,6 +32,8 @@ var index_exports = {};
 __export(index_exports, {
   ComfyUIClient: () => ComfyUIClient,
   ComfyUITemplateRunner: () => ComfyUITemplateRunner,
+  DEFAULT_RETRY_CONFIG: () => DEFAULT_RETRY_CONFIG,
+  InMemoryNodeRegistry: () => InMemoryNodeRegistry,
   WORKFLOW_REGISTRY: () => WORKFLOW_REGISTRY,
   buildFlux2DevPrompt: () => buildFlux2DevPrompt,
   buildFlux2DevPulidLoraPrompt: () => buildFlux2DevPulidLoraPrompt,
@@ -52,6 +54,41 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/contracts/execution.ts
+var DEFAULT_RETRY_CONFIG = {
+  backoffMultiplier: 2,
+  baseDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  maxRetries: 3
+};
+
+// src/extensions/registry.ts
+var InMemoryNodeRegistry = class {
+  nodes = /* @__PURE__ */ new Map();
+  register(node) {
+    this.nodes.set(this.key(node.type, node.version), node);
+  }
+  registerMany(nodes) {
+    for (const node of nodes) this.register(node);
+  }
+  registerPack(pack) {
+    this.registerMany(pack.nodes);
+  }
+  get(type, version) {
+    if (version !== void 0) {
+      return this.nodes.get(this.key(type, version));
+    }
+    const candidates = [...this.nodes.values()].filter((node) => node.type === type).sort((a, b) => b.version - a.version);
+    return candidates[0];
+  }
+  list() {
+    return [...this.nodes.values()];
+  }
+  key(type, version) {
+    return `${type}@${version}`;
+  }
+};
+
 // src/comfyui/client.ts
 var DEFAULT_POLL_MS = 2e3;
 var DEFAULT_TIMEOUT_MS = 3e5;
@@ -1241,6 +1278,8 @@ function searchWorkflowsByTag(tag) {
 0 && (module.exports = {
   ComfyUIClient,
   ComfyUITemplateRunner,
+  DEFAULT_RETRY_CONFIG,
+  InMemoryNodeRegistry,
   WORKFLOW_REGISTRY,
   buildFlux2DevPrompt,
   buildFlux2DevPulidLoraPrompt,

package/dist/index.mjs

@@ -1,3 +1,8 @@
+import {
+  DEFAULT_RETRY_CONFIG,
+  InMemoryNodeRegistry
+} from "./chunk-CTZNKWZB.mjs";
+
 // src/comfyui/client.ts
 var DEFAULT_POLL_MS = 2e3;
 var DEFAULT_TIMEOUT_MS = 3e5;
@@ -1186,6 +1191,8 @@ function searchWorkflowsByTag(tag) {
 export {
   ComfyUIClient,
   ComfyUITemplateRunner,
+  DEFAULT_RETRY_CONFIG,
+  InMemoryNodeRegistry,
   WORKFLOW_REGISTRY,
   buildFlux2DevPrompt,
   buildFlux2DevPulidLoraPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genfeedai/workflows",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "sideEffects": false,
   "license": "AGPL-3.0",
   "repository": {
@@ -25,7 +25,12 @@
       "import": "./dist/comfyui/index.mjs",
       "require": "./dist/comfyui/index.js"
     },
-    "./workflows/*": "./workflows/*"
+    "./workflows/*": "./workflows/*",
+    "./contracts": {
+      "types": "./dist/contracts/index.d.ts",
+      "import": "./dist/contracts/index.mjs",
+      "require": "./dist/contracts/index.js"
+    }
   },
   "files": [
     "dist",
@@ -33,8 +38,8 @@
     "metadata"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "build": "tsup src/index.ts src/contracts/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts src/contracts/index.ts --format esm,cjs --dts --watch",
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {