@pikku/cli 0.11.3 → 0.12.0

package/src/functions/wirings/workflow/serialize-workflow-map.ts

@@ -1,121 +0,0 @@
-/**
- * Generate workflow map type definitions for type-safe client API
- */
-import type { WorkflowsMeta } from '@pikku/core/workflow'
-import { serializeImportMap } from '../../../utils/serialize-import-map.js'
-import { TypesMap } from '@pikku/inspector'
-import { FunctionsMeta } from '@pikku/core'
-import { generateCustomTypes } from '../../../utils/custom-types-generator.js'
-
-export const serializeWorkflowMap = (
-  relativeToPath: string,
-  packageMappings: Record<string, string>,
-  typesMap: TypesMap,
-  functionsMeta: FunctionsMeta,
-  workflowsMeta: WorkflowsMeta
-) => {
-  const requiredTypes = new Set<string>()
-
-  // First generate workflows to collect required types
-  const serializedWorkflows = generateWorkflows(
-    workflowsMeta,
-    functionsMeta,
-    typesMap,
-    requiredTypes
-  )
-
-  // Only generate custom types if we have workflows with types
-  const hasWorkflows = Object.keys(workflowsMeta).length > 0
-  const serializedCustomTypes = hasWorkflows
-    ? generateCustomTypes(typesMap, requiredTypes)
-    : ''
-
-  const serializedImportMap = hasWorkflows
-    ? serializeImportMap(
-        relativeToPath,
-        packageMappings,
-        typesMap,
-        requiredTypes
-      )
-    : ''
-
-  return `/**
- * Workflow type map with input/output types for each workflow
- */
-
-${serializedImportMap}
-${serializedCustomTypes}
-
-interface WorkflowHandler<I, O> {
-    input: I;
-    output: O;
-}
-
-${serializedWorkflows}
-
-export type WorkflowClient<Name extends keyof WorkflowMap> = {
-  start: (input: WorkflowMap[Name]['input']) => Promise<{ runId: string }>;
-  getRun: <output extends keyof WorkflowMap[Name]>(runId: string) => Promise<WorkflowMap[Name][output]>;
-  cancelRun: (runId: string) => Promise<boolean>;
-}
-
-export type TypedWorkflowClients = {
-  [Name in keyof WorkflowMap]: WorkflowClient<Name>;
-}
-`
-}
-
-function generateWorkflows(
-  workflowsMeta: WorkflowsMeta,
-  functionsMeta: FunctionsMeta,
-  typesMap: TypesMap,
-  requiredTypes: Set<string>
-) {
-  const workflowsObj: Record<
-    string,
-    { inputType: string; outputType: string }
-  > = {}
-
-  for (const [workflowName, { pikkuFuncName }] of Object.entries(
-    workflowsMeta
-  )) {
-    const functionMeta = functionsMeta[pikkuFuncName]
-    if (!functionMeta) {
-      throw new Error(
-        `Function ${workflowName} not found in functionsMeta. Please check your configuration.`
-      )
-    }
-
-    const input = functionMeta.inputs ? functionMeta.inputs[0] : undefined
-    const output = functionMeta.outputs ? functionMeta.outputs[0] : undefined
-
-    let inputType = 'void'
-    if (input) {
-      try {
-        inputType = typesMap.getTypeMeta(input).uniqueName
-      } catch {
-        inputType = input
-      }
-    }
-    let outputType = 'void'
-    if (output) {
-      try {
-        outputType = typesMap.getTypeMeta(output).uniqueName
-      } catch {
-        outputType = output
-      }
-    }
-
-    requiredTypes.add(inputType)
-    requiredTypes.add(outputType)
-    workflowsObj[workflowName] = { inputType, outputType }
-  }
-
-  let workflowsStr = 'export type WorkflowMap = {\n'
-  for (const [workflowName, handler] of Object.entries(workflowsObj)) {
-    workflowsStr += `  readonly '${workflowName}': WorkflowHandler<${handler.inputType}, ${handler.outputType}>,\n`
-  }
-  workflowsStr += '};\n'
-
-  return workflowsStr
-}

package/src/functions/wirings/workflow/serialize-workflow-meta.ts

@@ -1,73 +0,0 @@
-/**
- * Generate workflow meta aggregation file that imports individual workflow JSON files
- * and registers them with pikkuState
- */
-import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
-
-export const serializeWorkflowMeta = (
-  outputPath: string,
-  metaDir: string,
-  workflowNames: string[],
-  packageMappings: Record<string, string>,
-  supportsImportAttributes: boolean,
-  packageName?: string
-) => {
-  const lines: string[] = []
-
-  if (workflowNames.length === 0) {
-    // Empty meta file - still need to register empty meta
-    lines.push("import { pikkuState } from '@pikku/core'")
-    lines.push(
-      "import type { SerializedWorkflowGraphs } from '@pikku/inspector/workflow-graph'"
-    )
-    lines.push('')
-    lines.push('const workflowsMeta: SerializedWorkflowGraphs = {}')
-    lines.push('')
-    const packageNameValue = packageName ? `'${packageName}'` : 'null'
-    lines.push(
-      `pikkuState(${packageNameValue}, 'workflows', 'meta', workflowsMeta)`
-    )
-    return lines.join('\n')
-  }
-
-  // Imports
-  lines.push("import { pikkuState } from '@pikku/core'")
-  lines.push(
-    "import type { SerializedWorkflowGraphs } from '@pikku/inspector/workflow-graph'"
-  )
-  lines.push('')
-
-  // Import each workflow meta JSON
-  const sortedNames = [...workflowNames].sort()
-  for (const name of sortedNames) {
-    const jsonPath = `${metaDir}/${name}.gen.json`
-    const importPath = getFileImportRelativePath(
-      outputPath,
-      jsonPath,
-      packageMappings
-    )
-    const importStatement = supportsImportAttributes
-      ? `import ${name}Meta from '${importPath}' with { type: 'json' }`
-      : `import ${name}Meta from '${importPath}'`
-    lines.push(importStatement)
-  }
-
-  lines.push('')
-
-  // Create aggregated meta object (cast JSON imports to proper types)
-  lines.push('const workflowsMeta = {')
-  for (const name of sortedNames) {
-    lines.push(`  '${name}': ${name}Meta,`)
-  }
-  lines.push('} as SerializedWorkflowGraphs')
-
-  lines.push('')
-
-  // Register meta with pikkuState
-  const packageNameValue = packageName ? `'${packageName}'` : 'null'
-  lines.push(
-    `pikkuState(${packageNameValue}, 'workflows', 'meta', workflowsMeta)`
-  )
-
-  return lines.join('\n')
-}

package/src/functions/wirings/workflow/serialize-workflow-registration.ts

@@ -1,83 +0,0 @@
-/**
- * Generate workflow runtime registration
- * Imports meta (which registers with pikkuState) and registers DSL workflows (addWorkflow) and graph workflows (addWorkflowGraph)
- */
-import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
-
-export const serializeWorkflowRegistration = (
-  outputPath: string,
-  metaImportPath: string,
-  workflowNames: string[],
-  workflowFiles: Map<string, { path: string; exportedName: string }>,
-  graphFiles: Map<string, { path: string; exportedName: string }>,
-  packageMappings: Record<string, string>,
-  _packageName?: string
-) => {
-  const lines: string[] = []
-  const hasWorkflows = workflowNames.length > 0
-  const hasDslWorkflows = workflowFiles.size > 0
-  const hasGraphWorkflows = graphFiles.size > 0
-
-  // Imports
-  const imports: string[] = []
-  if (hasDslWorkflows) {
-    imports.push('addWorkflow')
-  }
-  if (hasGraphWorkflows) {
-    imports.push('addWorkflowGraph')
-  }
-  if (imports.length > 0) {
-    lines.push(`import { ${imports.join(', ')} } from '@pikku/core/workflow'`)
-  }
-
-  // Import meta file (which registers meta with pikkuState)
-  if (hasWorkflows) {
-    lines.push(`import '${metaImportPath}'`)
-  }
-
-  // Import DSL workflow functions
-  const sortedWorkflows = Array.from(workflowFiles.entries()).sort((a, b) =>
-    a[0].localeCompare(b[0])
-  )
-  for (const [, { path, exportedName }] of sortedWorkflows) {
-    const importPath = getFileImportRelativePath(
-      outputPath,
-      path,
-      packageMappings
-    )
-    lines.push(`import { ${exportedName} } from '${importPath}'`)
-  }
-
-  // Import graph workflow definitions
-  const sortedGraphWorkflows = Array.from(graphFiles.entries()).sort((a, b) =>
-    a[0].localeCompare(b[0])
-  )
-  for (const [, { path, exportedName }] of sortedGraphWorkflows) {
-    const importPath = getFileImportRelativePath(
-      outputPath,
-      path,
-      packageMappings
-    )
-    lines.push(`import { ${exportedName} } from '${importPath}'`)
-  }
-
-  lines.push('')
-
-  // Register DSL workflows
-  for (const [pikkuFuncName, { exportedName }] of sortedWorkflows) {
-    lines.push(`addWorkflow('${pikkuFuncName}', ${exportedName})`)
-  }
-
-  // Register graph workflows
-  for (const [workflowName, { exportedName }] of sortedGraphWorkflows) {
-    lines.push(`addWorkflowGraph('${workflowName}', ${exportedName})`)
-  }
-
-  // Export workflow names type
-  if (hasWorkflows) {
-    lines.push('')
-    lines.push(`export type WorkflowNames = '${workflowNames.join("' | '")}'`)
-  }
-
-  return lines.join('\n')
-}

package/src/functions/wirings/workflow/serialize-workflow-types.ts

@@ -1,357 +0,0 @@
-/**
- * Generate all workflow type helpers for authoring workflows
- * Combines DSL helpers (pikkuWorkflowFunc, pikkuWorkflowComplexFunc) and
- * graph helpers (pikkuWorkflowGraph) with unified wireWorkflow
- */
-export const serializeWorkflowTypes = (
-  functionTypesImportPath: string,
-  rpcMapImportPath: string
-) => {
-  return `/**
- * Workflow type definitions and helpers
- * Used for authoring both DSL and graph-based workflows
- */
-
-import { PikkuWorkflowWire, WorkflowStepOptions, WorkflowCancelledException } from '@pikku/core/workflow'
-
-// Re-export WorkflowCancelledException for use in workflow functions
-export { WorkflowCancelledException }
-import type { PikkuFunctionSessionless, PikkuFunctionConfig } from '${functionTypesImportPath}'
-import type { RPCMap, FlattenedRPCMap } from '${rpcMapImportPath}'
-import type { GraphNodeConfig, HTTPMethod } from '@pikku/core'
-import { createGraph, wireWorkflow as coreWireWorkflow } from '@pikku/core'
-
-// ============================================================================
-// DSL Workflow Types (pikkuWorkflowFunc, pikkuWorkflowComplexFunc)
-// ============================================================================
-
-/**
- * Typed workflow wire with RPC awareness
- * Provides type-safe workflow.do() for RPC steps
- */
-export interface TypedWorkflow extends PikkuWorkflowWire {
-  do<K extends keyof RPCMap>(
-    stepName: string,
-    rpcName: K,
-    data: RPCMap[K]['input'],
-    options?: WorkflowStepOptions
-  ): Promise<RPCMap[K]['output']>
-
-  do<T>(
-    stepName: string,
-    fn: () => T | Promise<T>,
-    options?: WorkflowStepOptions
-  ): Promise<T>
-}
-
-/**
- * Workflow function type with typed workflow service
- */
-export type PikkuFunctionWorkflow<
-  In = unknown,
-  Out = never
-> = PikkuFunctionSessionless<In, Out, 'workflow'>
-
-/**
- * Creates a DSL-compatible workflow function (serializable, shows in Forge UI)
- */
-export const pikkuWorkflowFunc = <In, Out = unknown>(
-  func:
-    | PikkuFunctionWorkflow<In, Out>
-    | PikkuFunctionConfig<In, Out, 'workflow', PikkuFunctionWorkflow<In, Out>>
-) => {
-  return typeof func === 'function' ? { func } : func
-}
-
-/**
- * Creates a complex workflow function (arbitrary code, hidden from Forge UI)
- */
-export const pikkuWorkflowComplexFunc = <In, Out = unknown>(
-  func:
-    | PikkuFunctionWorkflow<In, Out>
-    | PikkuFunctionConfig<In, Out, 'workflow', PikkuFunctionWorkflow<In, Out>>
-) => {
-  return typeof func === 'function' ? { func } : func
-}
-
-// ============================================================================
-// Graph Workflow Types (pikkuWorkflowGraph)
-// ============================================================================
-
-/**
- * Type-safe graph builder with full RPC autocomplete
- */
-const graphBuilder = createGraph<FlattenedRPCMap>()
-
-/** HTTP wire configuration for graph workflows */
-interface GraphHttpWire<NodeIds extends string> {
-  route: string
-  method: HTTPMethod
-  startNode: NodeIds
-}
-
-/** Channel wire configuration for graph workflows */
-interface GraphChannelWire<NodeIds extends string> {
-  name: string
-  onConnect?: NodeIds
-  onDisconnect?: NodeIds
-  onMessage?: NodeIds
-}
-
-/** Queue wire configuration for graph workflows */
-interface GraphQueueWire<NodeIds extends string> {
-  name: string
-  startNode: NodeIds
-}
-
-/** CLI wire configuration for graph workflows */
-interface GraphCliWire<NodeIds extends string> {
-  command: string
-  startNode: NodeIds
-}
-
-/** MCP wire configurations for graph workflows */
-interface GraphMcpWires<NodeIds extends string> {
-  tool?: Array<{ name: string; startNode: NodeIds }>
-  prompt?: Array<{ name: string; startNode: NodeIds }>
-  resource?: Array<{ uri: string; startNode: NodeIds }>
-}
-
-/** Schedule wire configuration for graph workflows */
-interface GraphScheduleWire<NodeIds extends string> {
-  cron?: string
-  interval?: string
-  startNode: NodeIds
-}
-
-/** Trigger wire configuration for graph workflows */
-interface GraphTriggerWire<NodeIds extends string> {
-  name: string  // RPC name of the trigger function
-  startNode: NodeIds
-}
-
-/** All wire configurations for graph workflows */
-interface GraphWiresConfig<NodeIds extends string> {
-  http?: Array<GraphHttpWire<NodeIds>>
-  channel?: Array<GraphChannelWire<NodeIds>>
-  queue?: Array<GraphQueueWire<NodeIds>>
-  cli?: Array<GraphCliWire<NodeIds>>
-  mcp?: GraphMcpWires<NodeIds>
-  schedule?: Array<GraphScheduleWire<NodeIds>>
-  trigger?: Array<GraphTriggerWire<NodeIds>>
-}
-
-/** Configuration for graph-based workflow */
-export interface PikkuWorkflowGraphConfig<
-  FuncMap extends Record<string, keyof FlattenedRPCMap & string>,
-  T
-> {
-  /** Workflow name (optional - defaults to exported variable name) */
-  name?: string
-  /** Optional description */
-  description?: string
-  /** Optional tags for organization */
-  tags?: string[]
-  /** Node to RPC function mapping */
-  nodes: FuncMap
-  /** Wire configurations - how this workflow can be triggered */
-  wires?: GraphWiresConfig<Extract<keyof FuncMap, string>>
-  /** Node configurations (next, input, onError) */
-  config?: T
-}
-
-/** Result of pikkuWorkflowGraph - includes metadata for wiring */
-export interface PikkuWorkflowGraphResult<T, NodeIds extends string = string> {
-  __type: 'pikkuWorkflowGraph'
-  name?: string
-  description?: string
-  tags?: string[]
-  wires?: GraphWiresConfig<NodeIds>
-  graph: T
-}
-
-/**
- * Creates a graph-based workflow definition with metadata
- * Name defaults to the exported variable name if not provided.
- *
- * @example
- * // Name inferred from exported variable name
- * export const myWorkflow = pikkuWorkflowGraph({
- *   description: 'Handles user onboarding',
- *   tags: ['onboarding'],
- *   nodes: {
- *     entry: 'createUser',
- *     sendEmail: 'sendWelcomeEmail',
- *   },
- *   config: {
- *     entry: { next: 'sendEmail' },
- *     sendEmail: { input: (ref) => ({ to: ref('entry', 'email') }) },
- *   },
- * })
- */
-export function pikkuWorkflowGraph<
-  const FuncMap extends Record<string, keyof FlattenedRPCMap & string>
->(
-  config: PikkuWorkflowGraphConfig<FuncMap, GraphNodeConfigMap<FuncMap>>
-): PikkuWorkflowGraphResult<Record<Extract<keyof FuncMap, string>, GraphNodeConfig<Extract<keyof FuncMap, string>>>, Extract<keyof FuncMap, string>> {
-  return {
-    __type: 'pikkuWorkflowGraph',
-    name: config.name,
-    description: config.description,
-    tags: config.tags,
-    wires: config.wires,
-    graph: graphBuilder(config.nodes, config.config as any),
-  }
-}
-
-/** Typed ref value */
-type TypedRef<T> = { $ref: string; path?: string } & { __phantomType?: T }
-
-/** Template string type - assignable to string fields */
-type TemplateString = {
-  $template: {
-    parts: string[]
-    expressions: Array<{ $ref: string; path?: string }>
-  }
-} & { __brand: 'TemplateString' }
-
-/**
- * Creates a template string with variable interpolation
- * Uses indexed placeholders $0, $1, etc. with refs array
- *
- * @example
- * template('Hello $0, your order $1 is ready', [ref('trigger', 'name'), ref('step_0', 'orderId')])
- */
-export function template(templateStr: string, refs: TypedRef<unknown>[]): TemplateString {
-  const parts: string[] = []
-  const expressions: Array<{ $ref: string; path?: string }> = []
-
-  // Parse template string: "Hello $0" -> parts: ["Hello ", ""], use refs[0] for expression
-  const regex = /\$(\d+)/g
-  let lastIndex = 0
-  let match
-
-  while ((match = regex.exec(templateStr)) !== null) {
-    // Add the part before this match
-    parts.push(templateStr.slice(lastIndex, match.index))
-
-    // Get the ref by index
-    const refIndex = parseInt(match[1]!, 10)
-    const refValue = refs[refIndex]
-    if (refValue) {
-      const expr: { $ref: string; path?: string } = { $ref: refValue.$ref }
-      if (refValue.path) {
-        expr.path = refValue.path
-      }
-      expressions.push(expr)
-    } else {
-      expressions.push({ $ref: 'unknown' })
-    }
-
-    lastIndex = regex.lastIndex
-  }
-
-  // Add the remaining part
-  parts.push(templateStr.slice(lastIndex))
-
-  return {
-    $template: { parts, expressions }
-  } as TemplateString
-}
-
-/** Map input type fields to allow TypedRef or TemplateString for any field */
-type InputWithRefs<T> = {
-  [K in keyof T]?: T[K] | TypedRef<T[K]> | TypedRef<unknown> | TemplateString
-}
-
-/** Get the input type for a node based on its RPC mapping */
-type NodeInputType<FuncMap extends Record<string, string>, K extends keyof FuncMap> =
-  FuncMap[K] extends keyof FlattenedRPCMap
-    ? InputWithRefs<FlattenedRPCMap[FuncMap[K]]['input']>
-    : Record<string, unknown>
-
-/** Get the output type keys for a node based on its RPC mapping */
-type NodeOutputKeys<FuncMap extends Record<string, string>, N extends string> =
-  N extends keyof FuncMap
-    ? FuncMap[N] extends keyof FlattenedRPCMap
-      ? keyof FlattenedRPCMap[FuncMap[N]]['output'] & string
-      : string
-    : string
-
-/** Ref function type with path validation */
-type RefFunction<FuncMap extends Record<string, string>> = {
-  <N extends Extract<keyof FuncMap, string>>(
-    nodeId: N,
-    path: NodeOutputKeys<FuncMap, N>
-  ): TypedRef<unknown>
-  (nodeId: 'trigger' | '$item', path?: string): TypedRef<unknown>
-}
-
-/** Template function type */
-type TemplateFunction = (templateStr: string, refs: TypedRef<unknown>[]) => TemplateString
-
-/** Type helper for node configuration */
-type GraphNodeConfigMap<FuncMap extends Record<string, string>> = {
-  [K in Extract<keyof FuncMap, string>]?: {
-    next?: NextConfig<Extract<keyof FuncMap, string>>
-    input?:
-      | NodeInputType<FuncMap, K>
-      | (() => NodeInputType<FuncMap, K>)
-      | ((ref: RefFunction<FuncMap>, template: TemplateFunction) => NodeInputType<FuncMap, K>)
-    onError?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[]
-  }
-}
-
-type NextConfig<NodeIds extends string> = NodeIds | NodeIds[] | { if: string; then: NodeIds; else?: NodeIds }
-
-// ============================================================================
-// Unified wireWorkflow
-// ============================================================================
-
-/** Workflow definition with DSL function */
-interface WorkflowDefinitionFunc {
-  /** Whether this workflow wiring is enabled (default: true) */
-  enabled?: boolean
-  /** Wire configurations for the workflow */
-  wires: {
-    http?: { route: string; method: HTTPMethod }
-    channel?: string
-    queue?: string
-  }
-  /** DSL workflow function */
-  func: PikkuFunctionConfig<any, any, 'workflow', PikkuFunctionWorkflow<any, any>>
-}
-
-/** Workflow definition with graph */
-interface WorkflowDefinitionGraph<T, NodeIds extends string = string> {
-  /** Whether this workflow wiring is enabled (default: true) */
-  enabled?: boolean
-  /** Graph workflow definition - wires are defined in the graph itself */
-  graph: PikkuWorkflowGraphResult<T, NodeIds>
-}
-
-/**
- * Wire a workflow with wires
- * Accepts either a DSL function (func) or a graph definition (graph)
- *
- * @example
- * // DSL workflow
- * wireWorkflow({
- *   wires: { http: { route: '/start', method: 'post' } },
- *   func: myWorkflowFunc,
- * })
- *
- * @example
- * // Graph workflow - wires are defined in the graph itself
- * wireWorkflow({
- *   enabled: true,  // default: true
- *   graph: myGraphWorkflow,
- * })
- */
-export function wireWorkflow<T extends Record<string, GraphNodeConfig<Extract<keyof T, string>>>, NodeIds extends string = string>(
-  definition: WorkflowDefinitionFunc | WorkflowDefinitionGraph<T, NodeIds>
-): void {
-  coreWireWorkflow(definition as any)
-}
-`
-}

package/src/functions/wirings/workflow/serialize-workflow-workers.ts

@@ -1,47 +0,0 @@
-/**
- * Generate queue workers for workflow orchestration
- */
-export const serializeWorkflowWorkers = (pathToPikkuTypes: string) => {
-  return `/**
- * Workflow queue workers for orchestration
- */
-import { pikkuSessionlessFunc, wireQueueWorker } from '${pathToPikkuTypes}'
-
-export type WorkflowStepInput = {
-  runId: string
-  stepName: string
-  rpcName: string
-  data: any
-}
-
-export const pikkuWorkflowWorker = pikkuSessionlessFunc<WorkflowStepInput, void>({
-  func: async ({ workflowService }, { runId, stepName, rpcName, data }, { rpc }) => {
-    await workflowService!.executeWorkflowStep(runId, stepName, rpcName, data, rpc)
-  }
-})
-
-export const pikkuWorkflowOrchestrator = pikkuSessionlessFunc<{ runId: string }, void>({
-  func: async ({ workflowService }, { runId }, { rpc }) => {
-    await workflowService!.orchestrateWorkflow(runId, rpc)
-  }
-})
-
-export const pikkuWorkflowSleeper = pikkuSessionlessFunc<{ runId: string, stepId: string }, void>({
-  func: async ({ workflowService }, { runId, stepId }) => {
-    await workflowService!.executeWorkflowSleepCompleted(runId, stepId)
-  },
-  internal: true,
-})
-
-export const pikkuRemoteInternalRPC = pikkuSessionlessFunc<{ rpcName: string, data?: any }, any>({
-  func: async (_services, { rpcName, data }, { rpc }) => {
-    return await (rpc.invoke as any)(rpcName, data)
-  },
-  internal: true,
-})
-
-wireQueueWorker({ queueName: 'pikku-workflow-step-worker', func: pikkuWorkflowWorker })
-wireQueueWorker({ queueName: 'pikku-workflow-orchestrator', func: pikkuWorkflowOrchestrator })
-wireQueueWorker({ queueName: 'pikku-remote-internal-rpc', func: pikkuRemoteInternalRPC })
-`
-}