fyflow-plugin-sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# fyflow-plugin-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Types and `definePlugin` for writing **Plugins** for fyflow-app, the visual builder and Host for [fyflow-orchestration](https://www.npmjs.com/package/fyflow-orchestration) flows. A Plugin contributes Node Types (with the Workers that run their Tasks), gate types, Resource Group types and Resource Groups.
+
+```sh
+npm install --save-peer fyflow-plugin-sdk
+npm install --save-dev fyflow-orchestration   # its types, for type checking; the Host brings its own at run time
+```
+
+## The contract
+
+A Plugin is a module whose default export is a plain object. `definePlugin` returns its argument unchanged; it only gives you type checking. Depend on the SDK as a peer and do not bundle it: the Host provides it at run time (see below), and a copy of your own would only report its own `SDK_VERSION`, not the Host's.
+
+```ts
+import { definePlugin } from "fyflow-plugin-sdk";
+
+export default definePlugin({
+  id: "acme.signer", // stable and unique across Plugins
+  version: "1.0.0",
+  base: import.meta.url, // what Worker `url`s resolve against
+  workers: {
+    sign: {
+      url: "./sign.worker.js",
+      configSchema: {
+        type: "object",
+        properties: { key: { type: "string", writeOnly: true } }, // a Profile secret
+      },
+      settingsSchema: { type: "object", properties: { field: { type: "string" } } },
+    },
+  },
+  nodeTypes: {
+    Sign: {
+      worker: "sign",
+      inline: true,
+      groups: ["acme.signing"],
+      icon: "signature", // from the app's icon set, below
+      description: "Signs a field with HMAC.",
+    },
+  },
+  groups: { "acme.signing": { type: "ConcurrentLimitGroup", config: { limit: 2 } } },
+  gateTypes: {
+    threshold: {
+      routes: ["below", "at-or-above"],
+      defaultRoute: "below",
+      fn: ({ key, settings }) => (Number(key) >= Number(settings.at) ? "at-or-above" : "below"),
+    },
+  },
+});
+```
+
+| Field | What it is |
+| --- | --- |
+| `workers` | Worker modules by key. A Worker module's default export is a class: its constructor gets the Profile's config, and `run({ settings, input })` does one Task. Schemas are JSON Schema in fyflow's subset. |
+| `nodeTypes` | Node Types by name, each naming one of this Plugin's `workers`, with fyflow's declaration fields (`inline`, `pool`, `config`, `settings` defaults, `retryPolicy`, `groups`), and, since 0.2.0, how the app shows it: an optional `icon` and a one-line `description`. |
+| `gateTypes` | Gate types by name: their routes, default route, settings schema, and the decision `fn`. |
+| `groupTypes` | Resource Group types by name: a `create(config, key)` factory for the scheduler's limit, and a `configSchema`. |
+| `groups` | Resource Groups by key, of fyflow's built-in types (`ConcurrentLimitGroup`, `RateLimitGroup`, `KeyedRateLimitGroup`) or this Plugin's own. A Node Type may only use its own Plugin's groups. |
+
+Do not name a setting like a member of every JavaScript object (`constructor`, `toString`, `valueOf`, `hasOwnProperty`, `__proto__`). The Host hands Agents a Flow Definition's shape as a JSON Schema that includes your `settingsSchema`, and some JSON Schema validators misread such a property: they refuse, or throw, on a Flow that is valid.
+
+Every name a Plugin contributes (Node Type, gate type, Resource Group type, Resource Group) must be unique across the Plugins a Host loads: the Plugin the Host saw first keeps a name, and a later one that repeats it is skipped with the reason.
+
+## The Plugin directory
+
+A Host loads Plugins from its Plugin directory (`<dataDir>/plugins` unless `pluginDir`, `FYFLOW_PLUGIN_DIR` or `--plugin-dir` says otherwise):
+
+- a **folder** holding `plugin.ts` or `plugin.js`, or a package (`package.json` and its entry), as the Host lays out a Plugin installed from the app;
+- a **package** named `fyflow-plugin-*` or `@scope/fyflow-plugin-*` under the directory's `node_modules`, installed with npm. A package must ship JavaScript: Node does not strip TypeScript under `node_modules`.
+
+A Plugin's own imports resolve from the Plugin directory's `node_modules`, so `npm install` your other dependencies there (or bundle them). The SDK is the Host's to provide: on a server, `npm install fyflow-plugin-sdk` there (npm also installs it as your package's peer); the desktop app puts its own there by itself. Changes take effect when the Host is told to **Reload**.
+
+## Peer range
+
+Declare the SDK versions your Plugin works with as a peer dependency:
+
+```json
+{ "peerDependencies": { "fyflow-plugin-sdk": "^0.2.0" } }
+```
+
+A Host implements its SDK version (`SDK_VERSION`, exported here) and the earlier ones it is compatible with (`SDK_COMPATIBLE`): a 0.2 Host still loads a Plugin declaring `^0.1.0`. It skips, with the reason, a Plugin whose range excludes them all. Declare `^0.2.0` when you use `icon` or `description`.
+
+## Icons
+
+A Node Type's `icon` names one of the app's icons, from [Lucide](https://lucide.dev/icons/): `activity`, `archive`, `bell`, `bot`, `box`, `braces`, `brain`, `calculator`, `calendar`, `camera`, `chart-bar`, `check`, `clock`, `cloud`, `code`, `cpu`, `credit-card`, `database`, `download`, `file`, `file-text`, `filter`, `flag`, `folder`, `git-branch`, `globe`, `hash`, `image`, `key`, `link`, `list`, `lock`, `mail`, `map-pin`, `message-square`, `package`, `pen-tool`, `play`, `plug`, `repeat`, `search`, `send`, `server`, `settings`, `shield`, `shopping-cart`, `signature`, `sparkles`, `table`, `tag`, `terminal`, `timer`, `upload`, `user`, `users`, `wand-sparkles`, `webhook`, `zap`. A name outside the set is not an error: the Node Type shows its Kind's icon, and the Plugins page shows a warning.
+
+## Profiles and secrets
+
+A Node Type's Worker config lives on the Host, not in Flows: a **Profile** is a named configuration of a Node Type, edited in the Host's UI with a form built from the Worker's `configSchema`, and a task Node chooses one. Every Node Type has a default Profile seeded from its declaration's `config`. A Profile's config is merged over the default's, which is merged over yours.
+
+Mark a config property `writeOnly: true` to make it a **secret**: the Host never shows it again, only whether it is set, and redacts its value from errors and logs. Only properties of the config object can be secrets.
+
+## Versioning
+
+This package follows semver. `SDK_VERSION` always equals the package version.

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import type { GateType, GroupInstance, GroupType, NodeTypeDeclaration, WorkerEntry } from "fyflow-orchestration";
+export type { GateContext, GateType, GroupInstance, GroupType, JsonSchema, NodeTypeDeclaration, RetryPolicy, WorkerEntry, } from "fyflow-orchestration";
+/**
+ * The SDK version this package is, and so the one a Host built with it implements. A Plugin whose
+ * `fyflow-plugin-sdk` peer range excludes it, and every one in `SDK_COMPATIBLE`, is not loaded. Kept equal to
+ * package.json's `version` (tested).
+ */
+export declare const SDK_VERSION = "0.2.0";
+/**
+ * The earlier SDK versions this one is a superset of: nothing a Plugin written for them says has changed meaning,
+ * so a Host implements them too (ADR-0021). 0.2.0 only added optional fields.
+ */
+export declare const SDK_COMPATIBLE: readonly string[];
+/** A Node Type as a Plugin declares it: fyflow's declaration, and how the app shows it (since 0.2.0). */
+export interface PluginNodeType extends NodeTypeDeclaration {
+    /** An icon from the app's icon set (Lucide names, listed in the README); an unknown one shows its Kind's icon. */
+    icon?: string;
+    /** One line on what it does, shown in the palette. */
+    description?: string;
+}
+export interface Plugin {
+    /** Stable, unique id, e.g. `acme.images`. */
+    id: string;
+    version: string;
+    /** What worker `url`s resolve against: the plugin module's own `import.meta.url`. */
+    base: string;
+    /**
+     * Worker modules by key; `url` is relative to `base`. A property of a `configSchema` marked `writeOnly: true` is
+     * a Profile secret: a Host never shows it (ADR-0016).
+     */
+    workers?: Readonly<Record<string, WorkerEntry>>;
+    /**
+     * Node Types by name, each naming one of this plugin's `workers`; `groups` names Resource Groups (from this
+     * plugin's `groups`) every Task of the type acquires.
+     */
+    nodeTypes?: Readonly<Record<string, PluginNodeType>>;
+    /** Gate types by name: the routes a gate of the type takes, and its decision. */
+    gateTypes?: Readonly<Record<string, GateType>>;
+    /** Resource Group types by name: a factory for the scheduler's limit, from a Resource Group's `config`. */
+    groupTypes?: Readonly<Record<string, GroupType>>;
+    /** Resource Groups by key: an instance of a group type (fyflow's built-ins or this plugin's), with its config. */
+    groups?: Readonly<Record<string, GroupInstance>>;
+}
+/** Identity at runtime; gives plugin authors type checking and a single import. */
+export declare function definePlugin(plugin: Plugin): Plugin;

package/dist/index.js

@@ -0,0 +1,70 @@
+// The contract between fyflow-app and the code that extends it (ADR-0007, ADR-0015, ADR-0016). Published as
+// `fyflow-plugin-sdk`: everything here is types but `definePlugin`, `SDK_VERSION` and `SDK_COMPATIBLE`.
+             
+           
+                
+            
+                      
+              
+                              
+
+             
+              
+           
+                
+            
+             
+                      
+              
+              
+                              
+
+/**
+ * The SDK version this package is, and so the one a Host built with it implements. A Plugin whose
+ * `fyflow-plugin-sdk` peer range excludes it, and every one in `SDK_COMPATIBLE`, is not loaded. Kept equal to
+ * package.json's `version` (tested).
+ */
+export const SDK_VERSION = "0.2.0";
+
+/**
+ * The earlier SDK versions this one is a superset of: nothing a Plugin written for them says has changed meaning,
+ * so a Host implements them too (ADR-0021). 0.2.0 only added optional fields.
+ */
+export const SDK_COMPATIBLE                    = ["0.1.0"];
+
+/** A Node Type as a Plugin declares it: fyflow's declaration, and how the app shows it (since 0.2.0). */
+                                                             
+                                                                                                                    
+                
+                                                        
+                       
+ 
+
+                         
+                                               
+             
+                  
+                                                                                       
+               
+     
+                                                                                                                   
+                                                        
+     
+                                                  
+     
+                                                                                                              
+                                                        
+     
+                                                       
+                                                                                   
+                                                 
+                                                                                                             
+                                                   
+                                                                                                                    
+                                                   
+ 
+
+/** Identity at runtime; gives plugin authors type checking and a single import. */
+export function definePlugin(plugin        )         {
+  return plugin;
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "fyflow-plugin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Types and definePlugin for fyflow-app Plugins: Node Types, Workers, gate types and Resource Groups",
+  "keywords": [
+    "fyflow",
+    "fyflow-plugin",
+    "plugin",
+    "workflow"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "fyflow-orchestration": "^0.11.0"
+  },
+  "peerDependenciesMeta": {
+    "fyflow-orchestration": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "fyflow-orchestration": "0.11.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }

package/src/index.ts

@@ -0,0 +1,70 @@
+// The contract between fyflow-app and the code that extends it (ADR-0007, ADR-0015, ADR-0016). Published as
+// `fyflow-plugin-sdk`: everything here is types but `definePlugin`, `SDK_VERSION` and `SDK_COMPATIBLE`.
+import type {
+  GateType,
+  GroupInstance,
+  GroupType,
+  NodeTypeDeclaration,
+  WorkerEntry,
+} from "fyflow-orchestration";
+
+export type {
+  GateContext,
+  GateType,
+  GroupInstance,
+  GroupType,
+  JsonSchema,
+  NodeTypeDeclaration,
+  RetryPolicy,
+  WorkerEntry,
+} from "fyflow-orchestration";
+
+/**
+ * The SDK version this package is, and so the one a Host built with it implements. A Plugin whose
+ * `fyflow-plugin-sdk` peer range excludes it, and every one in `SDK_COMPATIBLE`, is not loaded. Kept equal to
+ * package.json's `version` (tested).
+ */
+export const SDK_VERSION = "0.2.0";
+
+/**
+ * The earlier SDK versions this one is a superset of: nothing a Plugin written for them says has changed meaning,
+ * so a Host implements them too (ADR-0021). 0.2.0 only added optional fields.
+ */
+export const SDK_COMPATIBLE: readonly string[] = ["0.1.0"];
+
+/** A Node Type as a Plugin declares it: fyflow's declaration, and how the app shows it (since 0.2.0). */
+export interface PluginNodeType extends NodeTypeDeclaration {
+  /** An icon from the app's icon set (Lucide names, listed in the README); an unknown one shows its Kind's icon. */
+  icon?: string;
+  /** One line on what it does, shown in the palette. */
+  description?: string;
+}
+
+export interface Plugin {
+  /** Stable, unique id, e.g. `acme.images`. */
+  id: string;
+  version: string;
+  /** What worker `url`s resolve against: the plugin module's own `import.meta.url`. */
+  base: string;
+  /**
+   * Worker modules by key; `url` is relative to `base`. A property of a `configSchema` marked `writeOnly: true` is
+   * a Profile secret: a Host never shows it (ADR-0016).
+   */
+  workers?: Readonly<Record<string, WorkerEntry>>;
+  /**
+   * Node Types by name, each naming one of this plugin's `workers`; `groups` names Resource Groups (from this
+   * plugin's `groups`) every Task of the type acquires.
+   */
+  nodeTypes?: Readonly<Record<string, PluginNodeType>>;
+  /** Gate types by name: the routes a gate of the type takes, and its decision. */
+  gateTypes?: Readonly<Record<string, GateType>>;
+  /** Resource Group types by name: a factory for the scheduler's limit, from a Resource Group's `config`. */
+  groupTypes?: Readonly<Record<string, GroupType>>;
+  /** Resource Groups by key: an instance of a group type (fyflow's built-ins or this plugin's), with its config. */
+  groups?: Readonly<Record<string, GroupInstance>>;
+}
+
+/** Identity at runtime; gives plugin authors type checking and a single import. */
+export function definePlugin(plugin: Plugin): Plugin {
+  return plugin;
+}