@flowdrop/flowdrop 1.0.0

package/dist/registry/plugin.js

@@ -0,0 +1,249 @@
+/**
+ * FlowDrop Plugin System
+ * Provides APIs for external libraries to register custom node components.
+ *
+ * This enables a plugin ecosystem where:
+ * - Third-party libraries can provide custom node types
+ * - Custom nodes are namespaced to avoid conflicts
+ * - Registration is simplified with a clean API
+ */
+import { nodeComponentRegistry, createNamespacedType } from './nodeComponentRegistry.js';
+/**
+ * Register a FlowDrop plugin with custom node components.
+ * All node types are automatically namespaced with the plugin namespace.
+ *
+ * @param config - Plugin configuration with namespace and node definitions
+ * @returns Result object with registered types and any errors
+ *
+ * @example
+ * ```typescript
+ * import { registerFlowDropPlugin } from "@flowdrop/lib";
+ * import FancyNode from "./FancyNode.svelte";
+ * import GlowNode from "./GlowNode.svelte";
+ *
+ * const result = registerFlowDropPlugin({
+ *     namespace: "awesome",
+ *     name: "Awesome Nodes",
+ *     version: "1.0.0",
+ *     nodes: [
+ *         {
+ *             type: "fancy",
+ *             displayName: "Fancy Node",
+ *             component: FancyNode,
+ *             icon: "mdi:sparkles"
+ *         },
+ *         {
+ *             type: "glow",
+ *             displayName: "Glowing Node",
+ *             component: GlowNode,
+ *             icon: "mdi:lightbulb"
+ *         }
+ *     ]
+ * });
+ *
+ * // Result:
+ * // {
+ * //     success: true,
+ * //     namespace: "awesome",
+ * //     registeredTypes: ["awesome:fancy", "awesome:glow"],
+ * //     errors: []
+ * // }
+ * ```
+ */
+export function registerFlowDropPlugin(config) {
+    const result = {
+        success: true,
+        namespace: config.namespace,
+        registeredTypes: [],
+        errors: []
+    };
+    // Validate namespace
+    if (!isValidNamespace(config.namespace)) {
+        result.success = false;
+        result.errors.push(`Invalid namespace "${config.namespace}". ` +
+            `Namespace must be lowercase alphanumeric with optional hyphens.`);
+        return result;
+    }
+    // Register each node
+    for (const nodeDef of config.nodes) {
+        try {
+            const namespacedType = createNamespacedType(config.namespace, nodeDef.type);
+            const registration = {
+                type: namespacedType,
+                displayName: nodeDef.displayName,
+                description: nodeDef.description,
+                component: nodeDef.component,
+                icon: nodeDef.icon,
+                category: nodeDef.category ?? 'custom',
+                source: config.namespace,
+                statusPosition: nodeDef.statusPosition,
+                statusSize: nodeDef.statusSize
+            };
+            nodeComponentRegistry.register(registration);
+            result.registeredTypes.push(namespacedType);
+        }
+        catch (error) {
+            result.success = false;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            result.errors.push(`Failed to register ${config.namespace}:${nodeDef.type}: ${errorMessage}`);
+        }
+    }
+    return result;
+}
+/**
+ * Unregister all nodes from a plugin by namespace.
+ *
+ * @param namespace - The plugin namespace to unregister
+ * @returns Array of unregistered type identifiers
+ *
+ * @example
+ * ```typescript
+ * const removed = unregisterFlowDropPlugin("awesome");
+ * // Returns ["awesome:fancy", "awesome:glow"]
+ * ```
+ */
+export function unregisterFlowDropPlugin(namespace) {
+    const unregistered = [];
+    const types = nodeComponentRegistry.getTypes();
+    for (const type of types) {
+        if (type.startsWith(`${namespace}:`)) {
+            if (nodeComponentRegistry.unregister(type)) {
+                unregistered.push(type);
+            }
+        }
+    }
+    return unregistered;
+}
+/**
+ * Check if a namespace is valid.
+ * Must be lowercase alphanumeric with optional hyphens.
+ *
+ * @param namespace - The namespace to validate
+ * @returns true if valid
+ */
+export function isValidNamespace(namespace) {
+    return /^[a-z][a-z0-9-]*$/.test(namespace);
+}
+/**
+ * Get all registered plugins (unique namespaces).
+ *
+ * @returns Array of namespace strings
+ */
+export function getRegisteredPlugins() {
+    const sources = new Set();
+    const registrations = nodeComponentRegistry.getAll();
+    for (const reg of registrations) {
+        if (reg.source && reg.source !== 'flowdrop') {
+            sources.add(reg.source);
+        }
+    }
+    return Array.from(sources);
+}
+/**
+ * Get the count of nodes registered by a plugin.
+ *
+ * @param namespace - The plugin namespace
+ * @returns Number of nodes registered by this plugin
+ */
+export function getPluginNodeCount(namespace) {
+    return nodeComponentRegistry.getBySource(namespace).length;
+}
+/**
+ * Register a single custom node without a full plugin.
+ * Useful for project-specific custom nodes.
+ *
+ * @param type - Type identifier (can be namespaced or plain)
+ * @param displayName - Display name for UI
+ * @param component - Svelte component
+ * @param options - Additional options
+ *
+ * @example
+ * ```typescript
+ * import { registerCustomNode } from "@flowdrop/lib";
+ * import MyNode from "./MyNode.svelte";
+ *
+ * registerCustomNode("myproject:special", "Special Node", MyNode, {
+ *     icon: "mdi:star",
+ *     description: "A special node for my project"
+ * });
+ * ```
+ */
+export function registerCustomNode(type, displayName, component, options = {}) {
+    nodeComponentRegistry.register({
+        type,
+        displayName,
+        component,
+        description: options.description,
+        icon: options.icon,
+        category: options.category ?? 'custom',
+        source: options.source ?? 'custom',
+        statusPosition: options.statusPosition,
+        statusSize: options.statusSize
+    });
+}
+/**
+ * Create a plugin builder for a fluent API experience.
+ *
+ * @param namespace - Plugin namespace
+ * @param name - Plugin name
+ * @returns Plugin builder with chainable methods
+ *
+ * @example
+ * ```typescript
+ * import { createPlugin } from "@flowdrop/lib";
+ *
+ * createPlugin("awesome", "Awesome Nodes")
+ *     .version("1.0.0")
+ *     .node("fancy", "Fancy Node", FancyNode)
+ *     .node("glow", "Glowing Node", GlowNode, { icon: "mdi:lightbulb" })
+ *     .register();
+ * ```
+ */
+export function createPlugin(namespace, name) {
+    const config = {
+        namespace,
+        name,
+        nodes: []
+    };
+    const builder = {
+        /**
+         * Set plugin version
+         */
+        version(v) {
+            config.version = v;
+            return builder;
+        },
+        /**
+         * Set plugin description
+         */
+        description(desc) {
+            config.description = desc;
+            return builder;
+        },
+        /**
+         * Add a node to the plugin
+         */
+        node(type, displayName, component, options = {}) {
+            config.nodes.push({
+                type,
+                displayName,
+                component,
+                ...options
+            });
+            return builder;
+        },
+        /**
+         * Register the plugin
+         */
+        register() {
+            return registerFlowDropPlugin(config);
+        },
+        /**
+         * Get the config without registering (for testing/inspection)
+         */
+        getConfig() {
+            return { ...config };
+        }
+    };
+    return builder;
+}

package/dist/registry/workflowFormatRegistry.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Workflow Format Registry
+ *
+ * Central registry for workflow format adapters that allows built-in and
+ * third-party formats to be registered and resolved at runtime.
+ *
+ * This enables:
+ * - Custom workflow formats (e.g., n8n, LangGraph) to be registered by users
+ * - Format adapters to bundle their own node types
+ * - Bidirectional conversion between FlowDrop's StandardWorkflow and external formats
+ *
+ * Extends BaseRegistry for shared mechanics (subscribe, onClear, etc.).
+ */
+import type { StandardWorkflow } from '../adapters/WorkflowAdapter.js';
+import type { NodeMetadata, WorkflowFormat } from '../types/index.js';
+import { BaseRegistry } from './BaseRegistry.js';
+/**
+ * Validation result returned by format adapters.
+ */
+export interface FormatValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Interface that all workflow format adapters must implement.
+ * Adapters handle bidirectional conversion between FlowDrop's StandardWorkflow
+ * and an external workflow format.
+ *
+ * @example
+ * ```typescript
+ * const myAdapter: WorkflowFormatAdapter = {
+ *   id: 'n8n',
+ *   name: 'n8n Workflow',
+ *   export: (workflow) => JSON.stringify(convertToN8n(workflow)),
+ *   import: (data) => convertFromN8n(JSON.parse(data)),
+ * };
+ * ```
+ */
+export interface WorkflowFormatAdapter {
+    /** Unique format identifier (e.g., 'agentspec', 'n8n') */
+    id: WorkflowFormat;
+    /** Display name for UI (e.g., 'Agent Spec (Oracle)') */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Version */
+    version?: string;
+    /**
+     * Optional node types specific to this format.
+     * When provided, these nodes are merged into the sidebar
+     * and automatically tagged with this format.
+     */
+    nodes?: NodeMetadata[];
+    /** Convert a StandardWorkflow to this format's JSON string */
+    export(workflow: StandardWorkflow): string;
+    /** Parse this format's input and convert to StandardWorkflow */
+    import(data: string): StandardWorkflow;
+    /** Validate whether a workflow can be exported to this format */
+    validate?(workflow: StandardWorkflow): FormatValidationResult;
+}
+/**
+ * Central registry for workflow format adapters.
+ * Singleton — extends BaseRegistry for shared mechanics.
+ *
+ * @example
+ * ```typescript
+ * // Register a custom format
+ * workflowFormatRegistry.register({
+ *   id: 'n8n',
+ *   name: 'n8n Workflow',
+ *   export: (workflow) => JSON.stringify(convertToN8n(workflow)),
+ *   import: (data) => convertFromN8n(JSON.parse(data)),
+ * });
+ *
+ * // Get an adapter
+ * const adapter = workflowFormatRegistry.get('n8n');
+ * ```
+ */
+declare class WorkflowFormatRegistry extends BaseRegistry<string, WorkflowFormatAdapter> {
+    /**
+     * Register a workflow format adapter.
+     *
+     * @param adapter - The format adapter to register
+     * @param overwrite - If true, allows overwriting existing registrations
+     * @throws Error if format already registered and overwrite is false
+     */
+    register(adapter: WorkflowFormatAdapter, overwrite?: boolean): void;
+    /**
+     * Get all registered format identifiers.
+     *
+     * @returns Array of format id strings
+     */
+    getIds(): string[];
+    /**
+     * Get all node types provided by registered format adapters.
+     * Collects `adapter.nodes` from all adapters that provide them.
+     *
+     * @returns Array of NodeMetadata from all format adapters
+     */
+    getAllFormatNodes(): NodeMetadata[];
+    /**
+     * Get node types for a specific format.
+     *
+     * @param formatId - The format identifier
+     * @returns Array of NodeMetadata for the format, or empty array
+     */
+    getFormatNodes(formatId: WorkflowFormat): NodeMetadata[];
+    /**
+     * Get oneOf options for config forms.
+     * Returns array suitable for JSON Schema oneOf with const/title.
+     *
+     * @returns Array of oneOf items
+     */
+    getOneOfOptions(): Array<{
+        const: string;
+        title: string;
+    }>;
+}
+/** Singleton instance of the workflow format registry */
+export declare const workflowFormatRegistry: WorkflowFormatRegistry;
+export {};

package/dist/registry/workflowFormatRegistry.js

@@ -0,0 +1,96 @@
+/**
+ * Workflow Format Registry
+ *
+ * Central registry for workflow format adapters that allows built-in and
+ * third-party formats to be registered and resolved at runtime.
+ *
+ * This enables:
+ * - Custom workflow formats (e.g., n8n, LangGraph) to be registered by users
+ * - Format adapters to bundle their own node types
+ * - Bidirectional conversion between FlowDrop's StandardWorkflow and external formats
+ *
+ * Extends BaseRegistry for shared mechanics (subscribe, onClear, etc.).
+ */
+import { BaseRegistry } from './BaseRegistry.js';
+/**
+ * Central registry for workflow format adapters.
+ * Singleton — extends BaseRegistry for shared mechanics.
+ *
+ * @example
+ * ```typescript
+ * // Register a custom format
+ * workflowFormatRegistry.register({
+ *   id: 'n8n',
+ *   name: 'n8n Workflow',
+ *   export: (workflow) => JSON.stringify(convertToN8n(workflow)),
+ *   import: (data) => convertFromN8n(JSON.parse(data)),
+ * });
+ *
+ * // Get an adapter
+ * const adapter = workflowFormatRegistry.get('n8n');
+ * ```
+ */
+class WorkflowFormatRegistry extends BaseRegistry {
+    /**
+     * Register a workflow format adapter.
+     *
+     * @param adapter - The format adapter to register
+     * @param overwrite - If true, allows overwriting existing registrations
+     * @throws Error if format already registered and overwrite is false
+     */
+    register(adapter, overwrite = false) {
+        if (this.items.has(adapter.id) && !overwrite) {
+            throw new Error(`Workflow format "${adapter.id}" is already registered. ` +
+                `Use overwrite: true to replace it.`);
+        }
+        this.items.set(adapter.id, adapter);
+        this.notifyListeners();
+    }
+    /**
+     * Get all registered format identifiers.
+     *
+     * @returns Array of format id strings
+     */
+    getIds() {
+        return this.getKeys();
+    }
+    /**
+     * Get all node types provided by registered format adapters.
+     * Collects `adapter.nodes` from all adapters that provide them.
+     *
+     * @returns Array of NodeMetadata from all format adapters
+     */
+    getAllFormatNodes() {
+        const allNodes = [];
+        for (const adapter of this.items.values()) {
+            if (adapter.nodes && adapter.nodes.length > 0) {
+                allNodes.push(...adapter.nodes);
+            }
+        }
+        return allNodes;
+    }
+    /**
+     * Get node types for a specific format.
+     *
+     * @param formatId - The format identifier
+     * @returns Array of NodeMetadata for the format, or empty array
+     */
+    getFormatNodes(formatId) {
+        const adapter = this.items.get(formatId);
+        return adapter?.nodes ?? [];
+    }
+    /**
+     * Get oneOf options for config forms.
+     * Returns array suitable for JSON Schema oneOf with const/title.
+     *
+     * @returns Array of oneOf items
+     */
+    getOneOfOptions() {
+        return this.getAll().map((adapter) => ({
+            const: adapter.id,
+            title: adapter.name
+        }));
+    }
+}
+/** Singleton instance of the workflow format registry */
+export const workflowFormatRegistry = new WorkflowFormatRegistry();

package/dist/schema/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * FlowDrop Workflow JSON Schema
+ *
+ * Provides the versioned JSON Schema for the FlowDrop workflow document format.
+ * The schema is generated from the OpenAPI YAML definitions in `api/v1/components/schemas/`.
+ *
+ * @example
+ * ```typescript
+ * import { workflowSchema, WORKFLOW_SCHEMA_VERSION } from '@flowdrop/flowdrop/core';
+ *
+ * // Use with any JSON Schema validator (e.g., Ajv)
+ * import Ajv from 'ajv/dist/2020';
+ * const ajv = new Ajv();
+ * const validate = ajv.compile(workflowSchema);
+ * const valid = validate(myWorkflow);
+ * ```
+ *
+ * @module schema
+ */
+import workflowSchema from '../schemas/v1/workflow.schema.json';
+/** Current workflow schema format version */
+export declare const WORKFLOW_SCHEMA_VERSION = "1.0.0";
+export { workflowSchema };

package/dist/schema/index.js

@@ -0,0 +1,23 @@
+/**
+ * FlowDrop Workflow JSON Schema
+ *
+ * Provides the versioned JSON Schema for the FlowDrop workflow document format.
+ * The schema is generated from the OpenAPI YAML definitions in `api/v1/components/schemas/`.
+ *
+ * @example
+ * ```typescript
+ * import { workflowSchema, WORKFLOW_SCHEMA_VERSION } from '@flowdrop/flowdrop/core';
+ *
+ * // Use with any JSON Schema validator (e.g., Ajv)
+ * import Ajv from 'ajv/dist/2020';
+ * const ajv = new Ajv();
+ * const validate = ajv.compile(workflowSchema);
+ * const valid = validate(myWorkflow);
+ * ```
+ *
+ * @module schema
+ */
+import workflowSchema from '../schemas/v1/workflow.schema.json';
+/** Current workflow schema format version */
+export const WORKFLOW_SCHEMA_VERSION = '1.0.0';
+export { workflowSchema };