@codemation/node-example 0.0.1

package/README.md

@@ -0,0 +1,23 @@
+# `@codemation/node-example`
+
+A **minimal example node package**: shows how to ship a custom node (config + implementation) that depends only on `@codemation/core`. The monorepo uses it in tests and as a template for **community or private node packages**.
+
+## Install
+
+```bash
+pnpm add @codemation/node-example@^0.0.0
+# or
+npm install @codemation/node-example@^0.0.0
+```
+
+## When to use
+
+Reference or copy this package when you author a new **`node-*`** package. Adding a real node package should not require changes inside `@codemation/core`.
+
+## Usage
+
+```ts
+import { ExampleUppercase, ExampleUppercaseNode } from "@codemation/node-example";
+```
+
+Inspect `src/` for the uppercase sample node pattern, then replace it with your own `NodeConfigBase` and `Node` classes and export them from your package’s public entry.

package/dist/chunk-fLflgnQm.js

@@ -0,0 +1,25 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+//#endregion
+export {  };

package/dist/index.cjs

@@ -0,0 +1,79 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let __codemation_core = require("@codemation/core");
+__codemation_core = __toESM(__codemation_core);
+
+//#region \0@oxc-project+runtime@0.95.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+//#endregion
+//#region src/ExampleUppercaseNode.ts
+let ExampleUppercaseNode = class ExampleUppercaseNode$1 {
+	kind = "node";
+	outputPorts = ["main"];
+	async execute(items, ctx) {
+		const out = [];
+		for (let i = 0; i < items.length; i++) {
+			const item = items[i];
+			const json = typeof item.json === "object" && item.json !== null ? item.json : {};
+			const value = String(json[ctx.config.cfg.field] ?? "");
+			out.push({
+				...item,
+				json: {
+					...json,
+					[ctx.config.cfg.field]: value.toUpperCase()
+				}
+			});
+		}
+		return { main: out };
+	}
+};
+ExampleUppercaseNode = __decorate([(0, __codemation_core.node)({ packageName: "@codemation/node-example" })], ExampleUppercaseNode);
+
+//#endregion
+//#region src/uppercase.ts
+var ExampleUppercase = class {
+	kind = "node";
+	type = ExampleUppercaseNode;
+	constructor(name, cfg, id) {
+		this.name = name;
+		this.cfg = cfg;
+		this.id = id;
+	}
+};
+
+//#endregion
+exports.ExampleUppercase = ExampleUppercase;
+Object.defineProperty(exports, 'ExampleUppercaseNode', {
+  enumerable: true,
+  get: function () {
+    return ExampleUppercaseNode;
+  }
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["ExampleUppercaseNode","out: Item[]","name: string","cfg: { field: TField }","id?: string"],"sources":["../src/ExampleUppercaseNode.ts","../src/uppercase.ts"],"sourcesContent":["import type { Item, Items, Node, NodeExecutionContext, NodeOutputs } from \"@codemation/core\";\n\nimport { node } from \"@codemation/core\";\n\nimport { ExampleUppercase } from \"./uppercase\";\n\n@node({ packageName: \"@codemation/node-example\" })\nexport class ExampleUppercaseNode implements Node<ExampleUppercase<Record<string, unknown>, string>> {\n  kind = \"node\" as const;\n  outputPorts = [\"main\"] as const;\n\n  async execute(\n    items: Items,\n    ctx: NodeExecutionContext<ExampleUppercase<Record<string, unknown>, string>>,\n  ): Promise<NodeOutputs> {\n    const out: Item[] = [];\n    for (let i = 0; i < items.length; i++) {\n      const item = items[i]!;\n      const json = typeof item.json === \"object\" && item.json !== null ? (item.json as Record<string, unknown>) : {};\n      const value = String(json[ctx.config.cfg.field] ?? \"\");\n      out.push({ ...item, json: { ...json, [ctx.config.cfg.field]: value.toUpperCase() } });\n    }\n    return { main: out };\n  }\n}\n","import type { RunnableNodeConfig, TypeToken } from \"@codemation/core\";\n\nimport { ExampleUppercaseNode } from \"./ExampleUppercaseNode\";\n\nexport class ExampleUppercase<\n  TInputJson extends Record<string, unknown> = Record<string, unknown>,\n  TField extends keyof TInputJson & string = keyof TInputJson & string,\n> implements RunnableNodeConfig<TInputJson, TInputJson> {\n  readonly kind = \"node\" as const;\n  readonly type: TypeToken<unknown> = ExampleUppercaseNode;\n  constructor(\n    public readonly name: string,\n    public readonly cfg: { field: TField },\n    public readonly id?: string,\n  ) {}\n}\n\nexport { ExampleUppercaseNode } from \"./ExampleUppercaseNode\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOO,iCAAMA,uBAAwF;CACnG,OAAO;CACP,cAAc,CAAC,OAAO;CAEtB,MAAM,QACJ,OACA,KACsB;EACtB,MAAMC,MAAc,EAAE;AACtB,OAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;GACrC,MAAM,OAAO,MAAM;GACnB,MAAM,OAAO,OAAO,KAAK,SAAS,YAAY,KAAK,SAAS,OAAQ,KAAK,OAAmC,EAAE;GAC9G,MAAM,QAAQ,OAAO,KAAK,IAAI,OAAO,IAAI,UAAU,GAAG;AACtD,OAAI,KAAK;IAAE,GAAG;IAAM,MAAM;KAAE,GAAG;MAAO,IAAI,OAAO,IAAI,QAAQ,MAAM,aAAa;KAAE;IAAE,CAAC;;AAEvF,SAAO,EAAE,MAAM,KAAK;;;+DAhBlB,EAAE,aAAa,4BAA4B,CAAC;;;;ACFlD,IAAa,mBAAb,MAGwD;CACtD,AAAS,OAAO;CAChB,AAAS,OAA2B;CACpC,YACE,AAAgBC,MAChB,AAAgBC,KAChB,AAAgBC,IAChB;EAHgB;EACA;EACA"}

package/dist/index.d.cts

@@ -0,0 +1,270 @@
+import { ReadableStream } from "node:stream/web";
+import { InjectionToken as TypeToken } from "tsyringe";
+
+//#region ../core/src/contracts/retryPolicySpec.types.d.ts
+
+/**
+ * In-process retry policy for runnable nodes. Serialized configs use the same
+ * `kind` discriminator (`JSON.stringify` / persisted workflows).
+ *
+ * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
+ */
+type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
+interface NoneRetryPolicySpec {
+  readonly kind: "none";
+}
+interface FixedRetryPolicySpec {
+  readonly kind: "fixed";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly delayMs: number;
+}
+interface ExponentialRetryPolicySpec {
+  readonly kind: "exponential";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly initialDelayMs: number;
+  readonly multiplier: number;
+  readonly maxDelayMs?: number;
+  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
+  readonly jitter?: boolean;
+}
+//#endregion
+//#region ../core/src/contracts/runTypes.d.ts
+
+type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+interface NodeExecutionError {
+  message: string;
+  name?: string;
+  stack?: string;
+}
+/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
+type ConnectionInvocationId = string;
+/** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
+type ConnectionInvocationAppendArgs = Readonly<{
+  invocationId: ConnectionInvocationId;
+  connectionNodeId: NodeId;
+  parentAgentNodeId: NodeId;
+  parentAgentActivationId: NodeActivationId;
+  status: NodeExecutionStatus;
+  managedInput?: JsonValue;
+  managedOutput?: JsonValue;
+  error?: NodeExecutionError;
+  queuedAt?: string;
+  startedAt?: string;
+  finishedAt?: string;
+}>;
+//#endregion
+//#region ../core/src/contracts/runtimeTypes.d.ts
+interface NodeExecutionStatePublisher {
+  markQueued(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void>;
+  markRunning(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void>;
+  markCompleted(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    outputs?: NodeOutputs;
+  }): Promise<void>;
+  markFailed(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    error: Error;
+  }): Promise<void>;
+  appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void>;
+}
+type BinaryBody = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | Uint8Array | ArrayBuffer;
+interface BinaryStorageReadResult {
+  body: ReadableStream<Uint8Array>;
+  size?: number;
+}
+interface BinaryAttachmentCreateRequest {
+  name: string;
+  body: BinaryBody;
+  mimeType: string;
+  filename?: string;
+  previewKind?: BinaryAttachment["previewKind"];
+}
+interface NodeBinaryAttachmentService extends ExecutionBinaryService {
+  attach(args: BinaryAttachmentCreateRequest): Promise<BinaryAttachment>;
+  withAttachment<TJson>(item: Item<TJson>, name: string, attachment: BinaryAttachment): Item<TJson>;
+}
+interface ExecutionBinaryService {
+  forNode(args: {
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }): NodeBinaryAttachmentService;
+  openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
+}
+interface ExecutionContext {
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  /** This run's subworkflow depth (0 = root). */
+  subworkflowDepth: number;
+  /** Effective activation budget cap for this run (after policy merge). */
+  engineMaxNodeActivations: number;
+  /** Effective subworkflow nesting cap for this run (after policy merge). */
+  engineMaxSubworkflowDepth: number;
+  now: () => Date;
+  data: RunDataSnapshot;
+  nodeState?: NodeExecutionStatePublisher;
+  binary: ExecutionBinaryService;
+  getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+}
+interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  config: TConfig;
+  binary: NodeBinaryAttachmentService;
+}
+interface Node<TConfig extends NodeConfigBase = NodeConfigBase> {
+  kind: "node";
+  outputPorts: ReadonlyArray<OutputPortKey>;
+  execute(items: Items, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
+}
+//#endregion
+//#region ../core/src/contracts/workflowTypes.d.ts
+type WorkflowId = string;
+type NodeId = string;
+type OutputPortKey = string;
+type InputPortKey = string;
+type NodeKind = "trigger" | "node";
+type JsonPrimitive = string | number | boolean | null;
+interface JsonObject {
+  readonly [key: string]: JsonValue;
+}
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+type JsonArray = ReadonlyArray<JsonValue>;
+interface NodeConfigBase {
+  readonly kind: NodeKind;
+  readonly type: TypeToken<unknown>;
+  readonly name?: string;
+  readonly id?: NodeId;
+  readonly icon?: string;
+  readonly execution?: Readonly<{
+    hint?: "local" | "worker";
+    queue?: string;
+  }>;
+  /** In-process execute retries (runnable nodes). Triggers typically omit this. */
+  readonly retryPolicy?: RetryPolicySpec;
+  /** Recover from execute failures; return outputs to continue, or rethrow to fail the node. */
+  readonly nodeErrorHandler?: NodeErrorHandlerSpec;
+  /**
+   * When true, edges carrying zero items on an output port still schedule single-input downstream nodes.
+   * Decided from the **source** node that produced the (empty) output. Default (false/undefined): empty
+   * main batches skip downstream execution and propagate the empty path.
+   */
+  readonly continueWhenEmptyOutput?: boolean;
+  getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+}
+declare const runnableNodeInputType: unique symbol;
+declare const runnableNodeOutputType: unique symbol;
+interface RunnableNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> extends NodeConfigBase {
+  readonly kind: "node";
+  readonly [runnableNodeInputType]?: TInputJson$1;
+  readonly [runnableNodeOutputType]?: TOutputJson$1;
+}
+type PairedItemRef = Readonly<{
+  nodeId: NodeId;
+  output: OutputPortKey;
+  itemIndex: number;
+}>;
+type BinaryPreviewKind = "image" | "audio" | "video" | "download";
+type BinaryAttachment = Readonly<{
+  id: string;
+  storageKey: string;
+  mimeType: string;
+  size: number;
+  storageDriver: string;
+  previewKind: BinaryPreviewKind;
+  createdAt: string;
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  filename?: string;
+  sha256?: string;
+}>;
+type ItemBinary = Readonly<Record<string, BinaryAttachment>>;
+type Item<TJson = unknown> = Readonly<{
+  json: TJson;
+  binary?: ItemBinary;
+  meta?: Readonly<Record<string, unknown>>;
+  paired?: ReadonlyArray<PairedItemRef>;
+}>;
+type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
+type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
+type RunId = string;
+type NodeActivationId = string;
+interface ParentExecutionRef {
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  /** Subworkflow depth of the **spawning** run (0 = root). Passed when starting a child run. */
+  subworkflowDepth?: number;
+  /** Effective max node activations from the parent run (propagated to child policy merge). */
+  engineMaxNodeActivations?: number;
+  /** Effective max subworkflow depth from the parent run (propagated to child policy merge). */
+  engineMaxSubworkflowDepth?: number;
+}
+interface RunDataSnapshot {
+  getOutputs(nodeId: NodeId): NodeOutputs | undefined;
+  getOutputItems(nodeId: NodeId, output?: OutputPortKey): Items;
+  getOutputItem(nodeId: NodeId, itemIndex: number, output?: OutputPortKey): Item | undefined;
+}
+interface NodeErrorHandlerArgs<TConfig extends NodeConfigBase = NodeConfigBase> {
+  readonly kind: "single" | "multi";
+  readonly items: Items;
+  readonly inputsByPort: Readonly<Record<InputPortKey, Items>> | undefined;
+  readonly ctx: NodeExecutionContext<TConfig>;
+  readonly error: Error;
+}
+interface NodeErrorHandler {
+  handle<TConfig extends NodeConfigBase>(args: NodeErrorHandlerArgs<TConfig>): Promise<NodeOutputs>;
+}
+type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
+//#endregion
+//#region ../core/src/contracts/credentialTypes.d.ts
+type CredentialTypeId = string;
+type CredentialRequirement = Readonly<{
+  slotKey: string;
+  label: string;
+  acceptedTypes: ReadonlyArray<CredentialTypeId>;
+  optional?: true;
+  helpText?: string;
+  helpUrl?: string;
+}>;
+//#endregion
+//#region src/ExampleUppercaseNode.d.ts
+declare class ExampleUppercaseNode implements Node<ExampleUppercase<Record<string, unknown>, string>> {
+  kind: "node";
+  outputPorts: readonly ["main"];
+  execute(items: Items, ctx: NodeExecutionContext<ExampleUppercase<Record<string, unknown>, string>>): Promise<NodeOutputs>;
+}
+//#endregion
+//#region src/uppercase.d.ts
+declare class ExampleUppercase<TInputJson$1 extends Record<string, unknown> = Record<string, unknown>, TField extends keyof TInputJson$1 & string = keyof TInputJson$1 & string> implements RunnableNodeConfig<TInputJson$1, TInputJson$1> {
+  readonly name: string;
+  readonly cfg: {
+    field: TField;
+  };
+  readonly id?: string | undefined;
+  readonly kind: "node";
+  readonly type: TypeToken<unknown>;
+  constructor(name: string, cfg: {
+    field: TField;
+  }, id?: string | undefined);
+}
+//#endregion
+export { ExampleUppercase, ExampleUppercaseNode };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+import { ReadableStream } from "node:stream/web";
+import { InjectionToken as TypeToken } from "tsyringe";
+
+//#region ../core/src/contracts/retryPolicySpec.types.d.ts
+
+/**
+ * In-process retry policy for runnable nodes. Serialized configs use the same
+ * `kind` discriminator (`JSON.stringify` / persisted workflows).
+ *
+ * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
+ */
+type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
+interface NoneRetryPolicySpec {
+  readonly kind: "none";
+}
+interface FixedRetryPolicySpec {
+  readonly kind: "fixed";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly delayMs: number;
+}
+interface ExponentialRetryPolicySpec {
+  readonly kind: "exponential";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly initialDelayMs: number;
+  readonly multiplier: number;
+  readonly maxDelayMs?: number;
+  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
+  readonly jitter?: boolean;
+}
+//#endregion
+//#region ../core/src/contracts/runTypes.d.ts
+
+type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+interface NodeExecutionError {
+  message: string;
+  name?: string;
+  stack?: string;
+}
+/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
+type ConnectionInvocationId = string;
+/** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
+type ConnectionInvocationAppendArgs = Readonly<{
+  invocationId: ConnectionInvocationId;
+  connectionNodeId: NodeId;
+  parentAgentNodeId: NodeId;
+  parentAgentActivationId: NodeActivationId;
+  status: NodeExecutionStatus;
+  managedInput?: JsonValue;
+  managedOutput?: JsonValue;
+  error?: NodeExecutionError;
+  queuedAt?: string;
+  startedAt?: string;
+  finishedAt?: string;
+}>;
+//#endregion
+//#region ../core/src/contracts/runtimeTypes.d.ts
+interface NodeExecutionStatePublisher {
+  markQueued(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void>;
+  markRunning(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void>;
+  markCompleted(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    outputs?: NodeOutputs;
+  }): Promise<void>;
+  markFailed(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    error: Error;
+  }): Promise<void>;
+  appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void>;
+}
+type BinaryBody = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | Uint8Array | ArrayBuffer;
+interface BinaryStorageReadResult {
+  body: ReadableStream<Uint8Array>;
+  size?: number;
+}
+interface BinaryAttachmentCreateRequest {
+  name: string;
+  body: BinaryBody;
+  mimeType: string;
+  filename?: string;
+  previewKind?: BinaryAttachment["previewKind"];
+}
+interface NodeBinaryAttachmentService extends ExecutionBinaryService {
+  attach(args: BinaryAttachmentCreateRequest): Promise<BinaryAttachment>;
+  withAttachment<TJson>(item: Item<TJson>, name: string, attachment: BinaryAttachment): Item<TJson>;
+}
+interface ExecutionBinaryService {
+  forNode(args: {
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }): NodeBinaryAttachmentService;
+  openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
+}
+interface ExecutionContext {
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  /** This run's subworkflow depth (0 = root). */
+  subworkflowDepth: number;
+  /** Effective activation budget cap for this run (after policy merge). */
+  engineMaxNodeActivations: number;
+  /** Effective subworkflow nesting cap for this run (after policy merge). */
+  engineMaxSubworkflowDepth: number;
+  now: () => Date;
+  data: RunDataSnapshot;
+  nodeState?: NodeExecutionStatePublisher;
+  binary: ExecutionBinaryService;
+  getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+}
+interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  config: TConfig;
+  binary: NodeBinaryAttachmentService;
+}
+interface Node<TConfig extends NodeConfigBase = NodeConfigBase> {
+  kind: "node";
+  outputPorts: ReadonlyArray<OutputPortKey>;
+  execute(items: Items, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
+}
+//#endregion
+//#region ../core/src/contracts/workflowTypes.d.ts
+type WorkflowId = string;
+type NodeId = string;
+type OutputPortKey = string;
+type InputPortKey = string;
+type NodeKind = "trigger" | "node";
+type JsonPrimitive = string | number | boolean | null;
+interface JsonObject {
+  readonly [key: string]: JsonValue;
+}
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+type JsonArray = ReadonlyArray<JsonValue>;
+interface NodeConfigBase {
+  readonly kind: NodeKind;
+  readonly type: TypeToken<unknown>;
+  readonly name?: string;
+  readonly id?: NodeId;
+  readonly icon?: string;
+  readonly execution?: Readonly<{
+    hint?: "local" | "worker";
+    queue?: string;
+  }>;
+  /** In-process execute retries (runnable nodes). Triggers typically omit this. */
+  readonly retryPolicy?: RetryPolicySpec;
+  /** Recover from execute failures; return outputs to continue, or rethrow to fail the node. */
+  readonly nodeErrorHandler?: NodeErrorHandlerSpec;
+  /**
+   * When true, edges carrying zero items on an output port still schedule single-input downstream nodes.
+   * Decided from the **source** node that produced the (empty) output. Default (false/undefined): empty
+   * main batches skip downstream execution and propagate the empty path.
+   */
+  readonly continueWhenEmptyOutput?: boolean;
+  getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+}
+declare const runnableNodeInputType: unique symbol;
+declare const runnableNodeOutputType: unique symbol;
+interface RunnableNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> extends NodeConfigBase {
+  readonly kind: "node";
+  readonly [runnableNodeInputType]?: TInputJson$1;
+  readonly [runnableNodeOutputType]?: TOutputJson$1;
+}
+type PairedItemRef = Readonly<{
+  nodeId: NodeId;
+  output: OutputPortKey;
+  itemIndex: number;
+}>;
+type BinaryPreviewKind = "image" | "audio" | "video" | "download";
+type BinaryAttachment = Readonly<{
+  id: string;
+  storageKey: string;
+  mimeType: string;
+  size: number;
+  storageDriver: string;
+  previewKind: BinaryPreviewKind;
+  createdAt: string;
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  filename?: string;
+  sha256?: string;
+}>;
+type ItemBinary = Readonly<Record<string, BinaryAttachment>>;
+type Item<TJson = unknown> = Readonly<{
+  json: TJson;
+  binary?: ItemBinary;
+  meta?: Readonly<Record<string, unknown>>;
+  paired?: ReadonlyArray<PairedItemRef>;
+}>;
+type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
+type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
+type RunId = string;
+type NodeActivationId = string;
+interface ParentExecutionRef {
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  /** Subworkflow depth of the **spawning** run (0 = root). Passed when starting a child run. */
+  subworkflowDepth?: number;
+  /** Effective max node activations from the parent run (propagated to child policy merge). */
+  engineMaxNodeActivations?: number;
+  /** Effective max subworkflow depth from the parent run (propagated to child policy merge). */
+  engineMaxSubworkflowDepth?: number;
+}
+interface RunDataSnapshot {
+  getOutputs(nodeId: NodeId): NodeOutputs | undefined;
+  getOutputItems(nodeId: NodeId, output?: OutputPortKey): Items;
+  getOutputItem(nodeId: NodeId, itemIndex: number, output?: OutputPortKey): Item | undefined;
+}
+interface NodeErrorHandlerArgs<TConfig extends NodeConfigBase = NodeConfigBase> {
+  readonly kind: "single" | "multi";
+  readonly items: Items;
+  readonly inputsByPort: Readonly<Record<InputPortKey, Items>> | undefined;
+  readonly ctx: NodeExecutionContext<TConfig>;
+  readonly error: Error;
+}
+interface NodeErrorHandler {
+  handle<TConfig extends NodeConfigBase>(args: NodeErrorHandlerArgs<TConfig>): Promise<NodeOutputs>;
+}
+type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
+//#endregion
+//#region ../core/src/contracts/credentialTypes.d.ts
+type CredentialTypeId = string;
+type CredentialRequirement = Readonly<{
+  slotKey: string;
+  label: string;
+  acceptedTypes: ReadonlyArray<CredentialTypeId>;
+  optional?: true;
+  helpText?: string;
+  helpUrl?: string;
+}>;
+//#endregion
+//#region src/ExampleUppercaseNode.d.ts
+declare class ExampleUppercaseNode implements Node<ExampleUppercase<Record<string, unknown>, string>> {
+  kind: "node";
+  outputPorts: readonly ["main"];
+  execute(items: Items, ctx: NodeExecutionContext<ExampleUppercase<Record<string, unknown>, string>>): Promise<NodeOutputs>;
+}
+//#endregion
+//#region src/uppercase.d.ts
+declare class ExampleUppercase<TInputJson$1 extends Record<string, unknown> = Record<string, unknown>, TField extends keyof TInputJson$1 & string = keyof TInputJson$1 & string> implements RunnableNodeConfig<TInputJson$1, TInputJson$1> {
+  readonly name: string;
+  readonly cfg: {
+    field: TField;
+  };
+  readonly id?: string | undefined;
+  readonly kind: "node";
+  readonly type: TypeToken<unknown>;
+  constructor(name: string, cfg: {
+    field: TField;
+  }, id?: string | undefined);
+}
+//#endregion
+export { ExampleUppercase, ExampleUppercaseNode };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,49 @@
+import { node } from "@codemation/core";
+
+//#region \0@oxc-project+runtime@0.95.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+//#endregion
+//#region src/ExampleUppercaseNode.ts
+let ExampleUppercaseNode = class ExampleUppercaseNode$1 {
+	kind = "node";
+	outputPorts = ["main"];
+	async execute(items, ctx) {
+		const out = [];
+		for (let i = 0; i < items.length; i++) {
+			const item = items[i];
+			const json = typeof item.json === "object" && item.json !== null ? item.json : {};
+			const value = String(json[ctx.config.cfg.field] ?? "");
+			out.push({
+				...item,
+				json: {
+					...json,
+					[ctx.config.cfg.field]: value.toUpperCase()
+				}
+			});
+		}
+		return { main: out };
+	}
+};
+ExampleUppercaseNode = __decorate([node({ packageName: "@codemation/node-example" })], ExampleUppercaseNode);
+
+//#endregion
+//#region src/uppercase.ts
+var ExampleUppercase = class {
+	kind = "node";
+	type = ExampleUppercaseNode;
+	constructor(name, cfg, id) {
+		this.name = name;
+		this.cfg = cfg;
+		this.id = id;
+	}
+};
+
+//#endregion
+export { ExampleUppercase, ExampleUppercaseNode };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["ExampleUppercaseNode","out: Item[]","name: string","cfg: { field: TField }","id?: string"],"sources":["../src/ExampleUppercaseNode.ts","../src/uppercase.ts"],"sourcesContent":["import type { Item, Items, Node, NodeExecutionContext, NodeOutputs } from \"@codemation/core\";\n\nimport { node } from \"@codemation/core\";\n\nimport { ExampleUppercase } from \"./uppercase\";\n\n@node({ packageName: \"@codemation/node-example\" })\nexport class ExampleUppercaseNode implements Node<ExampleUppercase<Record<string, unknown>, string>> {\n  kind = \"node\" as const;\n  outputPorts = [\"main\"] as const;\n\n  async execute(\n    items: Items,\n    ctx: NodeExecutionContext<ExampleUppercase<Record<string, unknown>, string>>,\n  ): Promise<NodeOutputs> {\n    const out: Item[] = [];\n    for (let i = 0; i < items.length; i++) {\n      const item = items[i]!;\n      const json = typeof item.json === \"object\" && item.json !== null ? (item.json as Record<string, unknown>) : {};\n      const value = String(json[ctx.config.cfg.field] ?? \"\");\n      out.push({ ...item, json: { ...json, [ctx.config.cfg.field]: value.toUpperCase() } });\n    }\n    return { main: out };\n  }\n}\n","import type { RunnableNodeConfig, TypeToken } from \"@codemation/core\";\n\nimport { ExampleUppercaseNode } from \"./ExampleUppercaseNode\";\n\nexport class ExampleUppercase<\n  TInputJson extends Record<string, unknown> = Record<string, unknown>,\n  TField extends keyof TInputJson & string = keyof TInputJson & string,\n> implements RunnableNodeConfig<TInputJson, TInputJson> {\n  readonly kind = \"node\" as const;\n  readonly type: TypeToken<unknown> = ExampleUppercaseNode;\n  constructor(\n    public readonly name: string,\n    public readonly cfg: { field: TField },\n    public readonly id?: string,\n  ) {}\n}\n\nexport { ExampleUppercaseNode } from \"./ExampleUppercaseNode\";\n"],"mappings":";;;;;;;;;;;;AAOO,iCAAMA,uBAAwF;CACnG,OAAO;CACP,cAAc,CAAC,OAAO;CAEtB,MAAM,QACJ,OACA,KACsB;EACtB,MAAMC,MAAc,EAAE;AACtB,OAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;GACrC,MAAM,OAAO,MAAM;GACnB,MAAM,OAAO,OAAO,KAAK,SAAS,YAAY,KAAK,SAAS,OAAQ,KAAK,OAAmC,EAAE;GAC9G,MAAM,QAAQ,OAAO,KAAK,IAAI,OAAO,IAAI,UAAU,GAAG;AACtD,OAAI,KAAK;IAAE,GAAG;IAAM,MAAM;KAAE,GAAG;MAAO,IAAI,OAAO,IAAI,QAAQ,MAAM,aAAa;KAAE;IAAE,CAAC;;AAEvF,SAAO,EAAE,MAAM,KAAK;;;mCAhBvB,KAAK,EAAE,aAAa,4BAA4B,CAAC;;;;ACFlD,IAAa,mBAAb,MAGwD;CACtD,AAAS,OAAO;CAChB,AAAS,OAA2B;CACpC,YACE,AAAgBC,MAChB,AAAgBC,KAChB,AAAgBC,IAChB;EAHgB;EACA;EACA"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@codemation/node-example",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Made Relevant B.V.",
+  "homepage": "https://www.maderelevant.com",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": {
+        "import": "./src/index.ts",
+        "require": "./dist/index.cjs"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "@codemation/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "eslint": "^10.0.3",
+    "tsdown": "^0.15.5",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "echo \"(test placeholder)\""
+  }
+}

package/src/ExampleUppercaseNode.ts

@@ -0,0 +1,25 @@
+import type { Item, Items, Node, NodeExecutionContext, NodeOutputs } from "@codemation/core";
+
+import { node } from "@codemation/core";
+
+import { ExampleUppercase } from "./uppercase";
+
+@node({ packageName: "@codemation/node-example" })
+export class ExampleUppercaseNode implements Node<ExampleUppercase<Record<string, unknown>, string>> {
+  kind = "node" as const;
+  outputPorts = ["main"] as const;
+
+  async execute(
+    items: Items,
+    ctx: NodeExecutionContext<ExampleUppercase<Record<string, unknown>, string>>,
+  ): Promise<NodeOutputs> {
+    const out: Item[] = [];
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i]!;
+      const json = typeof item.json === "object" && item.json !== null ? (item.json as Record<string, unknown>) : {};
+      const value = String(json[ctx.config.cfg.field] ?? "");
+      out.push({ ...item, json: { ...json, [ctx.config.cfg.field]: value.toUpperCase() } });
+    }
+    return { main: out };
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./uppercase";

package/src/uppercase.ts

@@ -0,0 +1,18 @@
+import type { RunnableNodeConfig, TypeToken } from "@codemation/core";
+
+import { ExampleUppercaseNode } from "./ExampleUppercaseNode";
+
+export class ExampleUppercase<
+  TInputJson extends Record<string, unknown> = Record<string, unknown>,
+  TField extends keyof TInputJson & string = keyof TInputJson & string,
+> implements RunnableNodeConfig<TInputJson, TInputJson> {
+  readonly kind = "node" as const;
+  readonly type: TypeToken<unknown> = ExampleUppercaseNode;
+  constructor(
+    public readonly name: string,
+    public readonly cfg: { field: TField },
+    public readonly id?: string,
+  ) {}
+}
+
+export { ExampleUppercaseNode } from "./ExampleUppercaseNode";

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/tsdown.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: "src/index.ts",
+  outDir: "dist",
+  clean: false,
+  dts: true,
+  format: ["esm", "cjs"],
+  sourcemap: true,
+});