@particle-academy/fancy-flow 0.33.3 → 0.35.0

package/dist/{types-Bj_ZHwqG.d.ts → types-D8Dezh9v.d.cts}

@@ -1,6 +1,6 @@
 import { ReactNode, ComponentType } from 'react';
 import { NodeProps } from '@xyflow/react';
-import { P as PortDescriptor, N as NodeExecutor, a as FlowNode } from './types-CMSrWVYM.js';
+import { P as PortDescriptor, N as NodeExecutor, b as FlowNode } from './types-sOmpCitB.cjs';
 
 /**
  * The human-pause contract.
@@ -97,6 +97,237 @@ declare function pauseForHuman(ctx: {
     abort: (reason?: string) => never;
 }, awaiting: PauseAwaiting, detail?: unknown): never;
 
+/**
+ * The node package manifest — what a marketplace node declares about itself.
+ *
+ * A node is not one artifact. It is a kind definition (palette entry, config
+ * schema, ports, renderer) plus an executor for EACH runtime the consumer runs.
+ * A package shipping only a TS executor is unusable to anyone executing on PHP,
+ * and without a manifest that is invisible until a run fails. Requested by the
+ * MOIC Suite consumer (fancy-flow#2 §2), who runs the editor in TS and executes
+ * in PHP and hit exactly this.
+ *
+ * The manifest is data, not code: the registry, the CLI, and the MCP all read
+ * it without executing anything a package author wrote.
+ *
+ * ## Why the engine range lives per runtime
+ *
+ * The first cut of this manifest carried ONE `fancyFlow` range, and it was
+ * wrong: the two engines version independently, so a single range cannot say
+ * "needs npm >=0.11 AND php >=0.5". A package supporting both runtimes would
+ * install cleanly against a host whose OTHER runtime was too old — the 0.9.0
+ * failure shape wearing a manifest. The range belongs inside each runtime.
+ */
+
+/** The current manifest schema version. Bump only on a breaking shape change. */
+declare const NODE_MANIFEST_SCHEMA_VERSION = 1;
+/**
+ * A runtime a node can implement.
+ *
+ * Open rather than a closed union — the PHP and Node twins are what exist
+ * today, but the point of a manifest is that a runtime we haven't written can
+ * declare itself without a release here.
+ */
+type NodeRuntimeId = "ts" | "php" | (string & {});
+/**
+ * How one runtime provides this node, and which engine version it needs.
+ *
+ * `files` are source directories, not a dependency: a node is **vendored**, so
+ * `fancy-cli add node` copies them into the project the way it copies a
+ * component's source. One node, one source, readable and editable in the app
+ * rather than hidden in `node_modules` or `vendor`.
+ *
+ * This spec covers a runtime's BACKEND only. The surface lives in the
+ * manifest's `ui`, because the editor is React on every host — a Laravel
+ * project needs the React kind and does not need the TypeScript executor.
+ */
+type NodeRuntimeSpec = {
+    /** This backend's source directories, relative to the node. */
+    files: string[];
+    /** Semver range of THIS runtime's engine. Required — see the module note. */
+    engine: string;
+};
+/**
+ * Whether a capability must be wired for the node to work at all.
+ *
+ * `required` is checked at AUTHOR time, not run time. The failure that hurts is
+ * a node that installs fine, authors fine, and silently no-ops during a run —
+ * the same silence as a routing bug. An editor can grey the node and say which
+ * capability the host never registered.
+ */
+type CapabilityRequirement = "required" | "optional";
+/**
+ * Whether a node is safe to run again.
+ *
+ * Durable runs RETRY. A node that writes needs to say so, or a host has to pick
+ * one retry policy for every node and get it wrong somewhere.
+ */
+type SideEffects = "none" | "idempotent" | "unsafe-to-replay";
+/**
+ * A Fancy suite package this node's source imports.
+ *
+ * Separate from a plain npm dependency because the suite is polyglot and
+ * vendorable: the same capability ships as an npm package, a Composer package,
+ * or source you copy in, and which of those a consumer wants depends on the
+ * host — so the node names the *package*, and the CLI offers the routes that
+ * exist. A bare `dependencies: ["@particle-academy/fancy-screens"]` can only
+ * ever offer `npm install`, which is the wrong answer in a Laravel app whose
+ * editor is vendored.
+ *
+ * ## No versions, deliberately
+ *
+ * Nothing here carries a range, and the validator rejects one. A pinned
+ * marketplace node freezes a consumer on an old surface: the suite ships
+ * additively and often, and a node that pinned `^0.4` at authoring time would
+ * be holding a project back a year later for a constraint nobody revisits.
+ * Compatibility is expressed where it can actually be checked — `runtimes[].engine`
+ * against the *engine*, which is the contract a node really depends on.
+ */
+type FancyDependency = {
+    /** Suite slug — what `/packages/<slug>` documents. */
+    package: string;
+    /** npm name, when the suite ships one. */
+    npm?: string;
+    /** Composer name, when the suite ships one. */
+    composer?: string;
+    /**
+     * Why the node needs it, in a few words.
+     *
+     * Printed at install. Without it the CLI can only present a bare name and a
+     * command, which reads as an unexplained demand for a second package.
+     */
+    reason?: string;
+    /** Whether the node fails without it, or merely does less. Defaults to required. */
+    requirement?: CapabilityRequirement;
+};
+type NodePackageManifest = {
+    /** Must equal `NODE_MANIFEST_SCHEMA_VERSION`. */
+    schemaVersion: number;
+    /** Package name, as installed (`@acme/fancy-flow-salesforce`). */
+    name: string;
+    /**
+     * The canonical kind id this package provides — namespaced, and the string
+     * that gets persisted into every document using it.
+     */
+    kind: string;
+    /**
+     * Previous ids this kind still answers to.
+     *
+     * Core renamed `llm_branch` to `llm_router` and kept every old id working.
+     * Third-party packages will rename too, and their documents break the same
+     * way core's would have — so packages get the same escape hatch, otherwise
+     * only first-party nodes can rename safely.
+     */
+    aliases?: string[];
+    /**
+     * Version of this node's CONFIG shape, independent of the document schema.
+     *
+     * A node's config evolves on its own clock. Without a declared version, every
+     * executor accretes hand-written read-fallbacks forever (MOIC carries one for
+     * `routes[].key` → `routes[].port`), because nothing canonicalises old config
+     * the way import canonicalises kind ids.
+     */
+    configVersion?: number;
+    /**
+     * The node's SURFACE — its React kind — as source directories.
+     *
+     * Copied whichever backend the consumer picks, because the editor is React on
+     * every host. Kept out of `runtimes` deliberately: fold the two together and
+     * a PHP project either loses its palette entry or gains a TypeScript executor
+     * it will never run.
+     */
+    ui?: string[];
+    /** Per-runtime backend source and engine ranges. */
+    runtimes: Partial<Record<NodeRuntimeId, NodeRuntimeSpec>>;
+    /**
+     * Host capabilities this node needs, and whether each is mandatory.
+     *
+     * Declared so the CLI and the editor can say what to wire BEFORE a run,
+     * rather than the node silently no-opping or crashing mid-run.
+     */
+    capabilities?: Record<string, CapabilityRequirement>;
+    /** Fancy suite packages this node's source imports. See {@link FancyDependency}. */
+    fancyDependencies?: FancyDependency[];
+    /**
+     * Path to this node's golden fixtures, relative to the package root.
+     *
+     * REQUIRED. Every runtime the package claims runs these same cases, which is
+     * what makes "behaves identically on both runtimes" verified rather than
+     * asserted. See `./fixtures`.
+     */
+    fixtures: string;
+    /**
+     * Declares the node halts for a person. Mirrors `NodeKindDefinition`.
+     *
+     * A host-planning fact, not a node internal: a parent that embeds workflows
+     * needs to reject a child that can pause, because a paused child wedges the
+     * parent — and discovering that at run time means watching a run park.
+     */
+    pausesForHuman?: PauseAwaiting;
+    /** Whether this node is safe to replay. See `SideEffects`. */
+    sideEffects?: SideEffects;
+    /** One-line summary — what `search_nodes` matches against. */
+    description?: string;
+    /**
+     * Assigned by the registry, never by the author. Present in a manifest being
+     * submitted for publication, it is a claim to a trust signal the author does
+     * not get to make.
+     */
+    verified?: boolean;
+};
+type ManifestProblem = {
+    level: "error" | "warning";
+    field: string;
+    message: string;
+};
+type ManifestValidation = {
+    /** True when there are no `error`-level problems. Warnings do not block. */
+    ok: boolean;
+    manifest?: NodePackageManifest;
+    problems: ManifestProblem[];
+};
+/**
+ * Validate a manifest read from disk or a registry.
+ *
+ * Returns every problem rather than throwing on the first, because an author
+ * fixing a package wants the whole list — a validator that reveals one error
+ * per run turns a five-minute fix into five round trips.
+ */
+declare function validateNodeManifest(input: unknown): ManifestValidation;
+/**
+ * Check a node against the runtimes a host executes on, and their versions.
+ *
+ * Two failures live here, and both are errors because the node genuinely
+ * cannot run: a runtime the package does not implement at all, and a runtime
+ * it implements against an engine newer than the host's.
+ *
+ * `engineVersions` is optional — pass what the host knows. An unchecked range
+ * is reported as a warning rather than passed over silently, because "we did
+ * not check" and "it is fine" must not look the same.
+ */
+declare function checkRuntimeSupport(manifest: Pick<NodePackageManifest, "kind" | "runtimes">, hostRuntimes: readonly string[], engineVersions?: Readonly<Record<string, string>>): ManifestProblem[];
+/**
+ * Minimal semver range check — `^x.y.z`, `~x.y.z`, `>=x.y.z`, `x.y.z`, `*`.
+ *
+ * Deliberately small: this runs in the CLI and in CI, and pulling a semver
+ * library into the engine for one comparison is not worth the dependency. It
+ * covers the forms a manifest actually uses; anything it cannot parse is
+ * treated as unsatisfied rather than silently passed, so an unparseable range
+ * fails loudly instead of waving a node through.
+ */
+declare function satisfiesRange(version: string, range: string): boolean;
+/**
+ * Check that every capability a node needs is wired.
+ *
+ * A `required` capability that is missing is an ERROR — that is the whole point
+ * of the requirement level. It is meant to be surfaced at author time, so an
+ * editor can grey the node and name what the host never registered, rather than
+ * the node installing cleanly and silently no-opping during a run.
+ *
+ * An `optional` one is a warning: the node still works, with less.
+ */
+declare function checkCapabilities(manifest: Pick<NodePackageManifest, "kind" | "capabilities">, available: Readonly<Record<string, boolean>>): ManifestProblem[];
+
 /** Categories used by the palette for grouping. */
 type NodeCategory = "trigger" | "logic" | "data" | "ai" | "io" | "human" | "output" | "layout" | "annotation" | "custom";
 /**
@@ -336,6 +567,24 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
      * refuse to list a pausing node whose package never says so.
      */
     pausesForHuman?: PauseAwaiting;
+    /**
+     * Whether a node of this kind is safe to run twice.
+     *
+     * The same three values a marketplace manifest declares (see `SideEffects`),
+     * lifted onto the KIND so it is readable at run time. A manifest is install-
+     * time data; a durable runner needs this while deciding whether to retry, and
+     * cannot go and read a manifest to find out.
+     *
+     * `fancy-flow-php`'s per-node queue driver keys its retry policy on exactly
+     * this: an `unsafe-to-replay` node gets one attempt whatever `tries` says,
+     * because a retried `git_pr_open` opens a second pull request. This field is
+     * the TypeScript half of that contract — the twins declare the same kind
+     * metadata or they are not twins.
+     *
+     * Declaration only. Nothing here enforces it; a host's runner decides what to
+     * do with it, and the TS in-process runner currently does not retry at all.
+     */
+    sideEffects?: SideEffects;
     /**
      * Make nodes of this kind resizable via drag handles (xyflow NodeResizer).
      * `true` enables it with defaults; pass options to bound it. The resulting
@@ -374,4 +623,4 @@ type NodeKindDefinition<TConfig = Record<string, unknown>, TIn = any, TOut = any
     reactive?: boolean;
 };
 
-export { type ConfigField as C, type DocumentConfigField as D, type ExpressionConfigField as E, type JsonConfigField as J, type KeyValueConfigField as K, LEGACY_PAUSE_PREFIXES as L, type NodeKindDefinition as N, type PauseAwaiting as P, type RenderBodyContext as R, type SelectConfigField as S, type TextConfigField as T, type NodeCategory as a, PAUSE_PREFIX as b, type PauseSignal as c, type PortSpec as d, decodePause as e, encodePause as f, type CredentialConfigField as g, type NumberConfigField as h, isPause as i, type RepeaterConfigField as j, type RepeaterRowField as k, type SwitchConfigField as l, type TextareaConfigField as m, pauseForHuman as p };
+export { type CapabilityRequirement as C, type DocumentConfigField as D, type ExpressionConfigField as E, type JsonConfigField as J, type KeyValueConfigField as K, LEGACY_PAUSE_PREFIXES as L, type ManifestProblem as M, NODE_MANIFEST_SCHEMA_VERSION as N, type PauseAwaiting as P, type RenderBodyContext as R, type SideEffects as S, type TextConfigField as T, type ConfigField as a, type ManifestValidation as b, type NodeCategory as c, type NodeKindDefinition as d, type NodePackageManifest as e, type NodeRuntimeId as f, type NodeRuntimeSpec as g, PAUSE_PREFIX as h, type PauseSignal as i, type PortSpec as j, checkCapabilities as k, checkRuntimeSupport as l, decodePause as m, encodePause as n, isPause as o, pauseForHuman as p, type CredentialConfigField as q, type NumberConfigField as r, satisfiesRange as s, type RepeaterConfigField as t, type RepeaterRowField as u, validateNodeManifest as v, type SelectConfigField as w, type SwitchConfigField as x, type TextareaConfigField as y };

package/dist/{types-CMSrWVYM.d.cts → types-sOmpCitB.d.cts}

@@ -106,4 +106,4 @@ type RunEvent = {
     error: string;
 };
 
-export type { ActionNodeData as A, BaseNodeData as B, DecisionNodeData as D, ExecutorRegistry as E, FlowGraph as F, NodeExecutor as N, OutputNodeData as O, PortDescriptor as P, RunEvent as R, SubgraphNodeData as S, TriggerNodeData as T, FlowNode as a, FlowEdge as b, FlowNodeData as c, FlowNodeKind as d, NodeRunStatus as e, NoteNodeData as f };
+export type { ActionNodeData as A, BaseNodeData as B, DecisionNodeData as D, ExecutorRegistry as E, FlowGraph as F, NodeExecutor as N, OutputNodeData as O, PortDescriptor as P, RunEvent as R, SubgraphNodeData as S, TriggerNodeData as T, FlowEdge as a, FlowNode as b, FlowNodeData as c, FlowNodeKind as d, NodeRunStatus as e, NoteNodeData as f };

package/dist/{types-CMSrWVYM.d.ts → types-sOmpCitB.d.ts}

@@ -106,4 +106,4 @@ type RunEvent = {
     error: string;
 };
 
-export type { ActionNodeData as A, BaseNodeData as B, DecisionNodeData as D, ExecutorRegistry as E, FlowGraph as F, NodeExecutor as N, OutputNodeData as O, PortDescriptor as P, RunEvent as R, SubgraphNodeData as S, TriggerNodeData as T, FlowNode as a, FlowEdge as b, FlowNodeData as c, FlowNodeKind as d, NodeRunStatus as e, NoteNodeData as f };
+export type { ActionNodeData as A, BaseNodeData as B, DecisionNodeData as D, ExecutorRegistry as E, FlowGraph as F, NodeExecutor as N, OutputNodeData as O, PortDescriptor as P, RunEvent as R, SubgraphNodeData as S, TriggerNodeData as T, FlowEdge as a, FlowNode as b, FlowNodeData as c, FlowNodeKind as d, NodeRunStatus as e, NoteNodeData as f };

package/dist/ux.d.cts

@@ -1,7 +1,7 @@
 import { EffectRegistry, DispatchActor } from '@particle-academy/fancy-auto-common';
 export { AutoActivityEvent } from '@particle-academy/fancy-auto-common';
-import { a as NodeCategory, C as ConfigField } from './types-DEmDSByY.cjs';
-import { E as ExecutorRegistry } from './types-CMSrWVYM.cjs';
+import { c as NodeCategory, a as ConfigField } from './types-D8Dezh9v.cjs';
+import { E as ExecutorRegistry } from './types-sOmpCitB.cjs';
 import 'react';
 import '@xyflow/react';
 

package/dist/ux.d.ts

@@ -1,7 +1,7 @@
 import { EffectRegistry, DispatchActor } from '@particle-academy/fancy-auto-common';
 export { AutoActivityEvent } from '@particle-academy/fancy-auto-common';
-import { a as NodeCategory, C as ConfigField } from './types-Bj_ZHwqG.js';
-import { E as ExecutorRegistry } from './types-CMSrWVYM.js';
+import { c as NodeCategory, a as ConfigField } from './types-D6lsIGoe.js';
+import { E as ExecutorRegistry } from './types-sOmpCitB.js';
 import 'react';
 import '@xyflow/react';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-flow",
-  "version": "0.33.3",
+  "version": "0.35.0",
   "description": "Workflow editor + runner. Six built-in node kits (trigger / action / decision / output / note / subgraph), tokenized theme, topological execution with per-node status. React-flow bundled; consumers npm install fancy-flow and get nothing extra.",
   "repository": {
     "type": "git",
@@ -123,7 +123,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "lint": "tsc --noEmit",
+    "lint": "tsc --noEmit && eslint .",
     "test": "vitest run",
     "clean": "rm -rf dist",
     "prepublishOnly": "tsup"
@@ -144,7 +144,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@particle-academy/fancy-auto-common": "^0.1.0"
+    "@particle-academy/fancy-auto-common": ">=0.1 <2.0"
   },
   "devDependencies": {
     "@dagrejs/dagre": "^3.0.0",
@@ -157,11 +157,14 @@
     "@xyflow/react": "^12.4.0",
     "ai": "^7.0.31",
     "clsx": "^2.1.0",
+    "eslint": "^10.8.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
     "jsdom": "^29.1.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",
+    "typescript-eslint": "^8.65.0",
     "vitest": "^3.2.6",
     "zod": "^4.4.3"
   },