@pikku/core 0.11.2 → 0.12.0

package/dist/wirings/trigger/trigger-runner.js

@@ -1,47 +1,75 @@
 import { pikkuState } from '../../pikku-state.js';
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
+import { PikkuMissingMetaError } from '../../errors/errors.js';
 /**
  * Registers a trigger with the Pikku framework.
- * The trigger will be available for setup via setupTrigger.
+ * Declares a trigger name and its target pikku function.
+ * Runs everywhere. Inspector extracts at build time.
  */
 export const wireTrigger = (trigger) => {
     const meta = pikkuState(null, 'trigger', 'meta');
     const triggerMeta = meta[trigger.name];
     if (!triggerMeta) {
-        throw new Error(`Trigger metadata not found: ${trigger.name}`);
+        throw new PikkuMissingMetaError(`Missing generated metadata for trigger '${trigger.name}'`);
     }
+    addFunction(triggerMeta.pikkuFuncId, trigger.func);
     const triggers = pikkuState(null, 'trigger', 'triggers');
-    if (triggers.has(trigger.name)) {
-        throw new Error(`Trigger already exists: ${trigger.name}`);
-    }
     triggers.set(trigger.name, trigger);
 };
+/**
+ * Registers a trigger source with the Pikku framework.
+ * Provides the actual subscription function and input data.
+ * Only imported in the trigger worker process.
+ */
+export const wireTriggerSource = (source) => {
+    const sourceMeta = pikkuState(null, 'trigger', 'sourceMeta');
+    const triggerSourceMeta = sourceMeta[source.name];
+    if (!triggerSourceMeta) {
+        throw new PikkuMissingMetaError(`Missing generated metadata for trigger source '${source.name}'`);
+    }
+    const triggerSources = pikkuState(null, 'trigger', 'triggerSources');
+    if (triggerSources.has(source.name)) {
+        throw new Error(`Trigger source already exists: ${source.name}`);
+    }
+    triggerSources.set(source.name, source);
+    addFunction(triggerSourceMeta.pikkuFuncId, source.func, triggerSourceMeta.packageName);
+};
 /**
  * Sets up a registered trigger and starts listening for events.
  * Returns a TriggerInstance with a teardown function.
+ *
+ * @param name - The trigger name (must be registered via wireTrigger)
+ * @param singletonServices - The singleton services
+ * @param input - The input to pass to the trigger function
+ * @param onTrigger - Callback invoked when the trigger fires
  */
-export async function setupTrigger({ name, singletonServices, onTrigger, }) {
-    const trigger = pikkuState(null, 'trigger', 'triggers').get(name);
-    const meta = pikkuState(null, 'trigger', 'meta')[name];
-    if (!trigger) {
-        throw new Error(`Trigger not found: ${name}`);
+export async function setupTrigger({ name, singletonServices, createWireServices, input, onTrigger, }) {
+    const source = pikkuState(null, 'trigger', 'triggerSources').get(name);
+    const sourceMeta = pikkuState(null, 'trigger', 'sourceMeta')[name];
+    if (!source) {
+        throw new Error(`Trigger source not found: ${name}`);
     }
-    if (!meta) {
-        throw new Error(`Trigger metadata not found: ${name}`);
+    if (!sourceMeta) {
+        throw new PikkuMissingMetaError(`Missing generated metadata for trigger source '${name}'`);
     }
     const wire = {
         trigger: {
-            trigger: (data) => {
+            invoke: (data) => {
                 singletonServices.logger.info(`Trigger fired: ${name}`);
                 onTrigger(data);
             },
         },
     };
     singletonServices.logger.info(`Setting up trigger: ${name}`);
-    const teardown = await trigger.func.func(singletonServices, trigger.config, wire);
-    return {
-        name,
-        teardown,
-    };
+    const teardown = await runPikkuFunc('trigger', name, sourceMeta.pikkuFuncId, {
+        singletonServices,
+        createWireServices,
+        auth: false,
+        data: () => input,
+        wire,
+        packageName: sourceMeta.packageName || null,
+    });
+    return { name, teardown };
 }
 /**
  * Gets all registered triggers

package/dist/wirings/trigger/trigger.types.d.ts

@@ -1,37 +1,108 @@
-import type { CorePikkuTriggerFunctionConfig } from '../../function/functions.types.js';
+import type { CommonWireMeta, CoreSingletonServices } from '../../types/core.types.js';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { CoreNodeConfig } from '../node/node.types.js';
 /**
  * The trigger interaction object passed to trigger functions via the wire.
  * Call trigger() to fire the trigger and start a new workflow/execution.
  */
 export interface PikkuTrigger<TOutput = unknown> {
-    trigger: (data: TOutput) => void;
+    invoke: (data: TOutput) => void;
 }
 /**
  * Metadata for registered triggers stored in state.
  */
-export type TriggerMeta = Record<string, {
-    pikkuFuncName: string;
+export type TriggerMeta = Record<string, CommonWireMeta & {
     name: string;
+}>;
+export type TriggerSourceMeta = Record<string, {
+    name: string;
+    pikkuFuncId: string;
+    packageName?: string;
+}>;
+/**
+ * A trigger function that sets up a subscription and returns a teardown function.
+ * The trigger is fired via wire.trigger.invoke(data).
+ *
+ * @template TInput - Input type (configuration passed when wired)
+ * @template TOutput - Output type produced when trigger fires
+ * @template Services - Services available to the trigger
+ */
+export type CorePikkuTriggerFunction<TInput = unknown, TOutput = unknown, Services extends CoreSingletonServices = CoreSingletonServices> = (services: Services, input: TInput, wire: {
+    trigger: {
+        invoke: (data: TOutput) => void;
+    };
+}) => Promise<() => void | Promise<void>>;
+/**
+ * Configuration object for creating a trigger function with metadata
+ */
+export type CorePikkuTriggerFunctionConfig<TInput = unknown, TOutput = unknown, Services extends CoreSingletonServices = CoreSingletonServices, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = {
+    /** Optional human-readable title for the trigger */
+    title?: string;
+    /** Optional description of what the trigger does */
     description?: string;
+    /** Optional tags for categorization */
     tags?: string[];
-}>;
+    /** The trigger function */
+    func: CorePikkuTriggerFunction<TInput, TOutput, Services>;
+    /** Optional Zod schema for input validation */
+    input?: InputSchema;
+    /** Optional Zod schema for output validation */
+    output?: OutputSchema;
+    /** Optional node configuration */
+    node?: CoreNodeConfig;
+};
+/**
+ * Factory function for creating trigger functions
+ * Supports both direct function and configuration object syntax
+ *
+ * @example
+ * ```typescript
+ * // Direct function syntax
+ * export const redisSubscribeTrigger = pikkuTriggerFunc<
+ *   { channel: string },
+ *   { message: string }
+ * >(async ({ redis }, { channel }, { trigger }) => {
+ *   const subscriber = redis.duplicate()
+ *   await subscriber.subscribe(channel, (msg) => {
+ *     trigger.invoke({ message: msg })
+ *   })
+ *   return () => subscriber.unsubscribe()
+ * })
+ *
+ * // Configuration object syntax with metadata
+ * export const redisSubscribeTrigger = pikkuTriggerFunc({
+ *   title: 'Redis Subscribe Trigger',
+ *   description: 'Listens to Redis pub/sub channel',
+ *   input: z.object({ channel: z.string() }),
+ *   output: z.object({ message: z.string() }),
+ *   func: async ({ redis }, { channel }, { trigger }) => {
+ *     const subscriber = redis.duplicate()
+ *     await subscriber.subscribe(channel, (msg) => {
+ *       trigger.invoke({ message: msg })
+ *     })
+ *     return () => subscriber.unsubscribe()
+ *   }
+ * })
+ * ```
+ */
+export declare const pikkuTriggerFunc: <TInput = unknown, TOutput = unknown, Services extends CoreSingletonServices = CoreSingletonServices, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(triggerOrConfig: CorePikkuTriggerFunction<TInput, TOutput, Services> | CorePikkuTriggerFunctionConfig<TInput, TOutput, Services, InputSchema, OutputSchema>) => CorePikkuTriggerFunctionConfig<TInput, TOutput, Services, InputSchema, OutputSchema>;
 /**
  * Core trigger definition for registration.
  *
- * @template TConfig - Configuration type
+ * @template TInput - Input type (configuration passed when wired)
  * @template TOutput - Output type
  */
-export interface CoreTrigger<TConfig = unknown, TOutput = unknown, TriggerFunctionConfig extends CorePikkuTriggerFunctionConfig<TConfig, TOutput> = CorePikkuTriggerFunctionConfig<TConfig, TOutput>> {
+export interface CoreTrigger<PikkuFunctionConfig = any> {
     /** Unique name for this trigger */
     name: string;
-    /** The trigger function configuration */
-    func: TriggerFunctionConfig;
-    /** Configuration to pass to the trigger function */
-    config: TConfig;
+    /** The target RPC function to invoke when the trigger fires */
+    func: PikkuFunctionConfig;
     /** Optional description */
     description?: string;
     /** Optional tags for categorization */
     tags?: string[];
+    /** Whether this trigger is used by a graph workflow */
+    graph?: true;
 }
 /**
  * Represents a trigger instance with teardown capability
@@ -40,3 +111,20 @@ export interface TriggerInstance {
     name: string;
     teardown: () => void | Promise<void>;
 }
+/**
+ * A trigger source that provides the subscription function.
+ * Only imported in the trigger worker process.
+ *
+ * @template TInput - Input type passed to the trigger function
+ * @template TOutput - Output type produced when trigger fires
+ */
+export type CoreTriggerSource<TInput = unknown, TOutput = unknown> = {
+    /** Must match a wireTrigger name */
+    name: string;
+    /** The trigger function config that sets up the subscription */
+    func: CorePikkuTriggerFunctionConfig<TInput, TOutput, CoreSingletonServices, StandardSchemaV1 | undefined, StandardSchemaV1 | undefined>;
+} & (unknown extends TInput ? {
+    input?: TInput;
+} : {
+    input: TInput;
+});

package/dist/wirings/trigger/trigger.types.js

@@ -1 +1,40 @@
-export {};
+/**
+ * Factory function for creating trigger functions
+ * Supports both direct function and configuration object syntax
+ *
+ * @example
+ * ```typescript
+ * // Direct function syntax
+ * export const redisSubscribeTrigger = pikkuTriggerFunc<
+ *   { channel: string },
+ *   { message: string }
+ * >(async ({ redis }, { channel }, { trigger }) => {
+ *   const subscriber = redis.duplicate()
+ *   await subscriber.subscribe(channel, (msg) => {
+ *     trigger.invoke({ message: msg })
+ *   })
+ *   return () => subscriber.unsubscribe()
+ * })
+ *
+ * // Configuration object syntax with metadata
+ * export const redisSubscribeTrigger = pikkuTriggerFunc({
+ *   title: 'Redis Subscribe Trigger',
+ *   description: 'Listens to Redis pub/sub channel',
+ *   input: z.object({ channel: z.string() }),
+ *   output: z.object({ message: z.string() }),
+ *   func: async ({ redis }, { channel }, { trigger }) => {
+ *     const subscriber = redis.duplicate()
+ *     await subscriber.subscribe(channel, (msg) => {
+ *       trigger.invoke({ message: msg })
+ *     })
+ *     return () => subscriber.unsubscribe()
+ *   }
+ * })
+ * ```
+ */
+export const pikkuTriggerFunc = (triggerOrConfig) => {
+    if (typeof triggerOrConfig === 'function') {
+        return { func: triggerOrConfig };
+    }
+    return triggerOrConfig;
+};

package/dist/wirings/variable/index.d.ts

@@ -0,0 +1,3 @@
+export { wireVariable } from './variable.types.js';
+export type { CoreVariable, VariableDefinitionMeta, VariableDefinitionsMeta, VariableDefinitions, } from './variable.types.js';
+export { validateAndBuildVariableDefinitionsMeta } from './validate-variable-definitions.js';

package/dist/wirings/variable/index.js

@@ -0,0 +1,2 @@
+export { wireVariable } from './variable.types.js';
+export { validateAndBuildVariableDefinitionsMeta } from './validate-variable-definitions.js';

package/dist/wirings/variable/validate-variable-definitions.d.ts

@@ -0,0 +1,6 @@
+import type { VariableDefinitions, VariableDefinitionsMeta } from './variable.types.js';
+export interface SchemaRefLike {
+    variableName: string;
+    sourceFile: string;
+}
+export declare function validateAndBuildVariableDefinitionsMeta(definitions: VariableDefinitions, schemaLookup: Map<string, SchemaRefLike>): VariableDefinitionsMeta;

package/dist/wirings/variable/validate-variable-definitions.js

@@ -0,0 +1,45 @@
+export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLookup) {
+    const meta = {};
+    const variableIdToDefinition = new Map();
+    for (const def of definitions) {
+        const existingDef = variableIdToDefinition.get(def.variableId);
+        if (existingDef) {
+            if (def.schema && existingDef.schema) {
+                const defSchemaRef = schemaLookup.get(def.schema);
+                const existingSchemaRef = schemaLookup.get(existingDef.schema);
+                if (defSchemaRef && existingSchemaRef) {
+                    if (defSchemaRef.variableName !== existingSchemaRef.variableName ||
+                        defSchemaRef.sourceFile !== existingSchemaRef.sourceFile) {
+                        throw new Error(`Variable '${def.variableId}' is defined with different schemas.\n` +
+                            `  First definition: ${existingDef.sourceFile} (schema: ${existingSchemaRef.variableName})\n` +
+                            `  Second definition: ${def.sourceFile} (schema: ${defSchemaRef.variableName})\n` +
+                            `Variables sharing a variableId must use the same schema.`);
+                    }
+                }
+            }
+            if (!meta[def.name]) {
+                meta[def.name] = {
+                    name: def.name,
+                    displayName: def.displayName,
+                    description: def.description,
+                    variableId: def.variableId,
+                    schema: def.schema,
+                    sourceFile: def.sourceFile,
+                };
+            }
+            continue;
+        }
+        variableIdToDefinition.set(def.variableId, def);
+        if (!meta[def.name]) {
+            meta[def.name] = {
+                name: def.name,
+                displayName: def.displayName,
+                description: def.description,
+                variableId: def.variableId,
+                schema: def.schema,
+                sourceFile: def.sourceFile,
+            };
+        }
+    }
+    return meta;
+}

package/dist/wirings/variable/variable.types.d.ts

@@ -0,0 +1,18 @@
+export type CoreVariable<T = unknown> = {
+    name: string;
+    displayName: string;
+    description?: string;
+    variableId: string;
+    schema: T;
+};
+export type VariableDefinitionMeta = {
+    name: string;
+    displayName: string;
+    description?: string;
+    variableId: string;
+    schema?: Record<string, unknown> | string;
+    sourceFile?: string;
+};
+export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>;
+export type VariableDefinitions = VariableDefinitionMeta[];
+export declare const wireVariable: <T>(_config: CoreVariable<T>) => void;

package/dist/wirings/variable/variable.types.js

@@ -0,0 +1 @@
+export const wireVariable = (_config) => { };

package/dist/wirings/workflow/dsl/index.d.ts

@@ -2,4 +2,4 @@
  * DSL (Domain Specific Language) workflow exports
  */
 export { addWorkflow } from './workflow-runner.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow-dsl.types.js';

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -26,6 +26,10 @@ export type WorkflowWireDoInline = <T>(stepName: string, fn: () => Promise<T> |
  * Type signature for workflow.sleep() - used by inspector
  */
 export type WorkflowWireSleep = (stepName: string, duration: string) => Promise<void>;
+/**
+ * Type signature for workflow.suspend() - used by inspector
+ */
+export type WorkflowWireSuspend = (reason: string) => Promise<void>;
 /**
  * Input source for step arguments in DSL workflows
  */
@@ -274,7 +278,7 @@ export interface WorkflowStepWire {
  */
 export interface PikkuWorkflowWire {
     /** The workflow name */
-    workflowName: string;
+    name: string;
     /** The current run ID */
     runId: string;
     /** Get the current workflow run */
@@ -283,4 +287,6 @@ export interface PikkuWorkflowWire {
     do: WorkflowWireDoRPC & WorkflowWireDoInline;
     /** Sleep for a duration */
     sleep: WorkflowWireSleep;
+    /** Suspend workflow until explicitly resumed */
+    suspend: WorkflowWireSuspend;
 }

package/dist/wirings/workflow/dsl/workflow-runner.js

@@ -1,5 +1,6 @@
 import { pikkuState } from '../../../pikku-state.js';
 import { addFunction } from '../../../function/function-runner.js';
+import { PikkuMissingMetaError } from '../../../errors/errors.js';
 /**
  * Add a workflow to the system
  * This is called by the generated workflow wirings
@@ -9,7 +10,7 @@ export const addWorkflow = (workflowName, workflowFunc) => {
     const meta = pikkuState(null, 'workflows', 'meta');
     const workflowMeta = meta[workflowName];
     if (!workflowMeta) {
-        throw new Error(`Workflow metadata not found for '${workflowName}'. Make sure to run the CLI to generate metadata.`);
+        throw new PikkuMissingMetaError(`Missing generated metadata for workflow '${workflowName}'`);
     }
     // Store workflow definition in state
     const registrations = pikkuState(null, 'workflows', 'registrations');
@@ -18,5 +19,5 @@ export const addWorkflow = (workflowName, workflowFunc) => {
         func: workflowFunc,
     });
     // Register the function with pikku
-    addFunction(workflowMeta.pikkuFuncName, workflowFunc);
+    addFunction(workflowMeta.pikkuFuncId, workflowFunc);
 };

package/dist/wirings/workflow/graph/graph-node.d.ts

@@ -34,7 +34,7 @@ export interface GraphNodeDef<RPCMap extends Record<string, RPCHandler>, NodeIds
  * @example
  * ```typescript
  * // Import the typed graph from generated types
- * import { pikkuWorkflowGraph, wireWorkflow } from './.pikku/workflow/pikku-workflow-types.gen.js'
+ * import { pikkuWorkflowGraph } from './.pikku/workflow/pikku-workflow-types.gen.js'
  *
  * export const myGraph = pikkuWorkflowGraph({
  *   name: 'myWorkflow',
@@ -51,11 +51,6 @@ export interface GraphNodeDef<RPCMap extends Record<string, RPCHandler>, NodeIds
  *     },
  *   },
  * })
- *
- * wireWorkflow({
- *   wires: { http: { route: '/start', method: 'post' } },
- *   graph: myGraph,
- * })
  * ```
  */
 /**

package/dist/wirings/workflow/graph/graph-runner.d.ts

@@ -1,35 +1,9 @@
 import type { PikkuWorkflowService } from '../pikku-workflow-service.js';
-import type { GraphNodeConfig, WorkflowGraphDefinition } from './workflow-graph.types.js';
-/**
- * Add a workflow graph to the system
- * This is called by the generated workflow wirings
- */
-export declare const addWorkflowGraph: (workflowName: string, graphResult: {
-    graph: Record<string, GraphNodeConfig<string>>;
-    wires?: any;
-}) => void;
-/**
- * Get a registered workflow graph by name
- */
-export declare function getWorkflowGraph(name: string): WorkflowGraphDefinition<any> | undefined;
-/**
- * Continue graph execution
- * Non-blocking - finds pending nodes, resolves inputs, queues them for execution
- */
-export declare function continueGraph(workflowService: PikkuWorkflowService, runId: string, graphName: string): Promise<void>;
-/**
- * Execute a graph step with wire context.
- * Called by the step worker when executing graph nodes.
- */
-export declare function executeGraphStep(workflowService: PikkuWorkflowService, rpcService: any, runId: string, stepId: string, stepName: string, rpcName: string, data: any, graphName: string): Promise<any>;
-/**
- * Handle node completion - re-triggers graph continuation
- */
+import type { WorkflowRuntimeMeta, WorkflowRunWire } from '../workflow.types.js';
+export declare function continueGraph(workflowService: PikkuWorkflowService, runId: string, graphName: string, overrideMeta?: WorkflowRuntimeMeta): Promise<void>;
+export declare function executeGraphStep(workflowService: PikkuWorkflowService, rpcService: any, runId: string, stepId: string, nodeId: string, rpcName: string, data: any, graphName: string): Promise<any>;
 export declare function onGraphNodeComplete(workflowService: PikkuWorkflowService, runId: string, graphName: string): Promise<void>;
-/**
- * Start a workflow graph execution
- * @param startNode - Optional starting node ID (from wire config). If not provided, uses wires.api from graph definition.
- */
-export declare function runWorkflowGraph(workflowService: PikkuWorkflowService, graphName: string, triggerInput: any, rpcService?: any, inline?: boolean, startNode?: string): Promise<{
+export declare function runFromMeta(workflowService: PikkuWorkflowService, runId: string, meta: WorkflowRuntimeMeta, _rpcService: any): Promise<void>;
+export declare function runWorkflowGraph(workflowService: PikkuWorkflowService, graphName: string, triggerInput: any, rpcService?: any, inline?: boolean, startNode?: string, wire?: WorkflowRunWire): Promise<{
     runId: string;
 }>;