@pikku/cli 0.10.2 → 0.11.0

package/src/functions/wirings/rpc/serialize-typed-rpc-map.ts

@@ -48,11 +48,18 @@ export type RPCInvoke = <Name extends keyof RPCMap>(
   }
 ) => Promise<RPCMap[Name]['output']>
 
+// Import WorkflowMap for workflow typing
+import type { WorkflowMap } from '../workflow/pikku-workflow-map.gen.js'
+
 export type TypedPikkuRPC = {
   depth: number;
   global: boolean;
   invoke: RPCInvoke;
-  invokeExposed: (name: string, data: any) => Promise<any> 
+  invokeExposed: (name: string, data: any) => Promise<any>;
+  startWorkflow: <Name extends keyof WorkflowMap>(
+    name: Name,
+    input: WorkflowMap[Name]['input']
+  ) => Promise<{ runId: string }>;
 }
   `
 }
@@ -79,8 +86,24 @@ function generateRPCs(
     const output = functionMeta.outputs ? functionMeta.outputs[0] : undefined
 
     // Store the input and output types for RPCHandler
-    const inputType = input ? typesMap.getTypeMeta(input).uniqueName : 'null'
-    const outputType = output ? typesMap.getTypeMeta(output).uniqueName : 'null'
+    // Use 'any' for types not in typesMap (e.g., inline types in generated workflow workers)
+    let inputType = 'null'
+    if (input) {
+      try {
+        inputType = typesMap.getTypeMeta(input).uniqueName
+      } catch {
+        inputType = 'any'
+      }
+    }
+
+    let outputType = 'null'
+    if (output) {
+      try {
+        outputType = typesMap.getTypeMeta(output).uniqueName
+      } catch {
+        outputType = 'any'
+      }
+    }
 
     requiredTypes.add(inputType)
     requiredTypes.add(outputType)

package/src/functions/wirings/workflow/pikku-command-workflow-map.ts

@@ -0,0 +1,24 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { serializeWorkflowMap } from './serialize-workflow-map.js'
+
+export const pikkuWorkflowMap: any = pikkuSessionlessFunc<void, void>({
+  func: async ({ logger, config, getInspectorState }) => {
+    const visitState = await getInspectorState()
+    const { workflowMapDeclarationFile, packageMappings } = config
+    const { workflows, functions: functionState } = visitState
+    const { typesMap } = functionState
+
+    await writeFileInDir(
+      logger,
+      workflowMapDeclarationFile,
+      serializeWorkflowMap(
+        workflowMapDeclarationFile,
+        packageMappings,
+        typesMap,
+        functionState.meta,
+        workflows.meta
+      )
+    )
+  },
+})

package/src/functions/wirings/workflow/pikku-command-workflow-types.ts

@@ -0,0 +1,22 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { serializeWorkflowTypes } from './serialize-workflow-types.js'
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
+
+export const pikkuWorkflowTypes: any = pikkuSessionlessFunc<void, void>({
+  func: async ({ logger, config }) => {
+    const { workflowTypesFile, functionTypesFile, packageMappings } = config
+
+    const functionTypesImportPath = getFileImportRelativePath(
+      workflowTypesFile,
+      functionTypesFile,
+      packageMappings
+    )
+
+    await writeFileInDir(
+      logger,
+      workflowTypesFile,
+      serializeWorkflowTypes(functionTypesImportPath)
+    )
+  },
+})

package/src/functions/wirings/workflow/pikku-command-workflow.ts

@@ -0,0 +1,123 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { ErrorCode } from '@pikku/inspector'
+import { serializeFileImports } from '../../../utils/file-imports-serializer.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
+import { serializeWorkflowMeta } from './serialize-workflow-meta.js'
+import { serializeWorkflowTypes } from './serialize-workflow-types.js'
+import { serializeWorkflowMap } from './serialize-workflow-map.js'
+import { serializeWorkflowWorkers } from './serialize-workflow-workers.js'
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
+import { join } from 'path'
+
+export const pikkuWorkflow: any = pikkuSessionlessFunc<
+  void,
+  boolean | undefined
+>({
+  func: async ({ logger, config, getInspectorState }) => {
+    const visitState = await getInspectorState()
+    const {
+      workflowsWiringFile,
+      workflowsWiringMetaFile,
+      workflowMapDeclarationFile,
+      workflowTypesFile,
+      functionTypesFile,
+      typesDeclarationFile,
+      packageMappings,
+    } = config
+    const { workflows, functions: functionState } = visitState
+    const { typesMap } = functionState
+
+    // Validate that workflowService service is configured if workflows are defined
+    const hasWorkflows = Object.keys(workflows.meta).length > 0
+    if (hasWorkflows) {
+      const hasWorkflowState =
+        visitState.serviceAggregation.allSingletonServices.includes(
+          'workflowService'
+        )
+      if (!hasWorkflowState) {
+        logger.critical(
+          ErrorCode.WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED,
+          'Workflows detected but workflowService service not configured. Please add workflowService to your singleton services'
+        )
+        throw new Error(
+          'WorkflowState service not configured but workflows are defined'
+        )
+      }
+    }
+
+    // Write workflow metadata
+    await writeFileInDir(
+      logger,
+      workflowsWiringMetaFile,
+      serializeWorkflowMeta(workflows.meta)
+    )
+
+    // Write workflow wirings (imports)
+    await writeFileInDir(
+      logger,
+      workflowsWiringFile,
+      serializeFileImports(
+        'wireWorkflow',
+        workflowsWiringFile,
+        workflows.files,
+        packageMappings
+      )
+    )
+
+    // Write workflow types
+    const functionTypesImportPath = getFileImportRelativePath(
+      workflowTypesFile,
+      functionTypesFile,
+      packageMappings
+    )
+    await writeFileInDir(
+      logger,
+      workflowTypesFile,
+      serializeWorkflowTypes(functionTypesImportPath)
+    )
+
+    // Write workflow map (type-safe client API)
+    await writeFileInDir(
+      logger,
+      workflowMapDeclarationFile,
+      serializeWorkflowMap(
+        workflowMapDeclarationFile,
+        packageMappings,
+        typesMap,
+        functionState.meta,
+        workflows.meta
+      )
+    )
+
+    if (config.workflows) {
+      if (config.workflows.singleQueue) {
+        const workflowPath = join(config.rootDir, config.workflows.path)
+        const pathToPikkuTypes = getFileImportRelativePath(
+          workflowPath,
+          typesDeclarationFile,
+          packageMappings
+        )
+        await writeFileInDir(
+          logger,
+          workflowPath,
+          serializeWorkflowWorkers(pathToPikkuTypes)
+        )
+      } else if (workflows.files.size > 0) {
+        logger.critical(
+          ErrorCode.WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED,
+          'Multi-queue workflows are not supported when workflows.singleQueue is false. Please enable singleQueue in your configuration.'
+        )
+        return false
+      }
+    }
+
+    return true
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Finding Workflows',
+      commandEnd: 'Found Workflows',
+    }),
+  ],
+})

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

@@ -0,0 +1,123 @@
+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>()
+  const serializedCustomTypes = generateCustomTypes(typesMap, requiredTypes)
+  const serializedWorkflows = generateWorkflows(
+    workflowsMeta,
+    functionsMeta,
+    typesMap,
+    requiredTypes
+  )
+
+  const serializedImportMap = serializeImportMap(
+    relativeToPath,
+    packageMappings,
+    typesMap,
+    requiredTypes
+  )
+
+  return `/**
+ * This provides the structure needed for TypeScript to be aware of workflows and their input/output types
+ */
+
+${serializedImportMap}
+${serializedCustomTypes}
+
+interface WorkflowHandler<I, O> {
+    input: I;
+    output: O;
+}
+
+${serializedWorkflows}
+
+/**
+ * Type-safe workflow client API
+ */
+export type WorkflowClient<Name extends keyof WorkflowMap> = {
+  /**
+   * Start a new workflow run
+   */
+  start: (input: WorkflowMap[Name]['input']) => Promise<{ runId: string }>;
+
+  /**
+   * Get a workflow run by ID
+   */
+  getRun: <output extends keyof WorkflowMap[Name]>(runId: string) => Promise<WorkflowMap[Name][output]>;
+
+  /**
+   * Cancel a running workflow
+   */
+  cancelRun: (runId: string) => Promise<boolean>;
+}
+
+/**
+ * Map of all registered workflows with type-safe client APIs
+ */
+export type TypedWorkflowClients = {
+  [Name in keyof WorkflowMap]: WorkflowClient<Name>;
+}
+  `
+}
+
+function generateWorkflows(
+  workflowsMeta: WorkflowsMeta,
+  functionsMeta: FunctionsMeta,
+  typesMap: TypesMap,
+  requiredTypes: Set<string>
+) {
+  // Initialize an object to collect workflows
+  const workflowsObj: Record<
+    string,
+    { inputType: string; outputType: string }
+  > = {}
+
+  // Iterate through workflow metadata
+  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
+
+    // Store the input and output types for WorkflowHandler
+    const inputType = input ? typesMap.getTypeMeta(input).uniqueName : 'void'
+    const outputType = output ? typesMap.getTypeMeta(output).uniqueName : 'void'
+
+    requiredTypes.add(inputType)
+    requiredTypes.add(outputType)
+
+    // Add workflow entry
+    workflowsObj[workflowName] = {
+      inputType,
+      outputType,
+    }
+  }
+
+  // Build the Workflows object as a string
+  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

@@ -0,0 +1,16 @@
+import { WorkflowsMeta } from '@pikku/core/workflow'
+
+export const serializeWorkflowMeta = (workflowsMeta: WorkflowsMeta) => {
+  const serializedOutput: string[] = []
+  serializedOutput.push("import { pikkuState } from '@pikku/core'")
+  serializedOutput.push(
+    `pikkuState('workflows', 'meta', ${JSON.stringify(workflowsMeta, null, 2)})`
+  )
+  const workflowsMetaValues = Object.values(workflowsMeta)
+  if (workflowsMetaValues.length > 0) {
+    serializedOutput.push(
+      `export type WorkflowNames = '${workflowsMetaValues.map((w) => w.workflowName).join("' | '")}'`
+    )
+  }
+  return serializedOutput.join('\n')
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Generates type definitions for workflow wirings
+ */
+export const serializeWorkflowTypes = (functionTypesImportPath: string) => {
+  return `/**
+ * Workflow-specific type definitions for tree-shaking optimization
+ */
+
+import { CoreWorkflow, wireWorkflow as wireWorkflowCore, PikkuWorkflowInteraction, WorkflowStepOptions } from '@pikku/core/workflow'
+import { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '@pikku/core'
+import type { PikkuPermission, PikkuMiddleware } from '${functionTypesImportPath}'
+import type { UserSession, SingletonServices } from '../../types/application-types.d.js'
+import type { TypedPikkuRPC, RPCMap } from '../rpc/pikku-rpc-wirings-map.internal.gen.d.js'
+
+/**
+ * Type definition for workflows that orchestrate multi-step processes.
+ * Workflows support both inline and remote execution modes with step caching.
+ */
+type WorkflowWiring = CoreWorkflow<
+  CorePikkuFunctionConfig<PikkuFunctionWorkflow<any, any>, PikkuPermission<any>, PikkuMiddleware>
+>
+
+/**
+ * Typed workflow interaction with RPC awareness
+ * Provides type-safe workflow.do() for RPC steps
+ */
+export interface TypedWorkflow extends PikkuWorkflowInteraction {
+  /**
+   * Execute a workflow step with RPC invocation (typed based on available RPCs)
+   * @template K - RPC name from the RPC map
+   */
+  do<K extends keyof RPCMap>(
+    stepName: string,
+    rpcName: K,
+    data: RPCMap[K]['input'],
+    options?: WorkflowStepOptions
+  ): Promise<RPCMap[K]['output']>
+
+  /**
+   * Execute a workflow step with inline function
+   * @template T - Return type of the inline function
+   */
+  do<T>(
+    stepName: string,
+    fn: () => T | Promise<T>,
+    options?: WorkflowStepOptions
+  ): Promise<T>
+}
+
+/**
+ * Workflow function type with typed workflow service
+ * Includes the workflow interaction object with typed RPC methods
+ */
+export type PikkuFunctionWorkflow<
+  In = unknown,
+  Out = never
+> = CorePikkuFunctionSessionless<
+  In,
+  Out,
+  null,
+  SingletonServices & {
+    rpc: TypedPikkuRPC
+    workflow: TypedWorkflow
+  },
+  UserSession
+>
+
+/**
+ * Creates a workflow function with typed input and output.
+ * Workflow functions have access to the workflow interaction object for step execution.
+ *
+ * @template In - Input type for the workflow
+ * @template Out - Output type for the workflow
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ */
+export const pikkuWorkflowFunc = <In, Out = unknown>(
+  func:
+    | PikkuFunctionWorkflow<In, Out>
+    | CorePikkuFunctionConfig<PikkuFunctionWorkflow<In, Out>, PikkuPermission<In>, PikkuMiddleware>
+) => {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * Registers a workflow with the Pikku framework.
+ * Workflows can run in 'inline' (synchronous) or 'remote' (queue-based) execution modes.
+ *
+ * @param workflow - Workflow definition with name, execution mode, and handler function
+ */
+export const wireWorkflow = (workflow: WorkflowWiring) => {
+  wireWorkflowCore(workflow as any)
+}
+`
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Generate queue workers and RPC functions for workflow steps and orchestrator
+ */
+export const serializeWorkflowWorkers = (pathToPikkuTypes: string) => {
+  return `/**
+ * Auto-generated workflow queue workers and RPC functions
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { pikkuSessionlessFunc, wireQueueWorker } from '${pathToPikkuTypes}'
+
+/**
+ * Worker input types for generated queue workers
+ */
+export type WorkflowStepInput = {
+  runId: string
+  stepName: string
+  rpcName: string
+  data: any
+}
+
+export const pikkuWorkflowWorker = pikkuSessionlessFunc<
+  WorkflowStepInput,
+  void
+>({
+  func: async ({ workflowService, rpc }, { runId, stepName, rpcName, data }) => {
+    await workflowService!.executeWorkflowStep(runId, stepName, rpcName, data, rpc)
+  }
+})
+
+export const pikkuWorkflowOrchestrator = pikkuSessionlessFunc<
+  { runId: string },
+  void
+>({
+  func: async ({ workflowService, rpc }, { runId }) => {
+    await workflowService!.orchestrateWorkflow(runId, rpc)
+  }
+})
+
+export const pikkuWorkflowSleeper = pikkuSessionlessFunc<
+  { runId: string, stepId: string },
+  void
+>({
+  func: async ({ workflowService }, { runId, stepId }) => {
+    await workflowService!.executeWorkflowSleep(runId, stepId)
+  },
+  name: 'pikkuWorkflowStepSleeper',
+  internal: true,
+})
+
+wireQueueWorker({
+  queueName: 'pikku-workflow-step-worker',
+  func: pikkuWorkflowWorker,
+})
+
+wireQueueWorker({
+  queueName: 'pikku-workflow-orchestrator',
+  func: pikkuWorkflowOrchestrator,
+})
+`
+}

package/src/services/cli-logger-forwarder.service.ts

@@ -78,7 +78,7 @@ export class CLILoggerForwarder implements Logger {
   }
 
   critical(code: ErrorCode, message: string) {
-    const url = `https://pikku.dev/docs/cli-errors/${code.toLowerCase()}`
+    const url = `https://pikku.dev/docs/pikku-cli/errors/${code.toLowerCase()}`
     const formattedMessage = `[${code}] ${message}\n  → ${url}`
     this.error(formattedMessage)
   }

package/src/services/cli-logger.service.ts

@@ -11,7 +11,7 @@ const logo = `
 |_|    |_|_| _)_| _)____/
 `
 
-const BASE_ERROR_URL = 'https://pikku.dev/errors'
+const BASE_ERROR_URL = 'https://pikku.dev/docs/pikku-cli/errors'
 
 export class CLILogger implements Logger {
   private silent: boolean

package/src/utils/command-summary.ts

@@ -8,6 +8,7 @@ export interface CommandSummaryStats {
   queueWorkers?: number
   mcpEndpoints?: number
   cliCommands?: number
+  workflows?: number
   [key: string]: number | undefined
 }
 
@@ -66,19 +67,20 @@ export class CommandSummary {
 
     // Stats
     const statLabels: Record<keyof CommandSummaryStats, string> = {
-      httpRoutes: 'HTTP routes',
-      channels: 'WebSocket channels',
-      functions: 'functions',
-      scheduledTasks: 'scheduled tasks',
-      queueWorkers: 'queue workers',
-      mcpEndpoints: 'MCP endpoints',
-      cliCommands: 'CLI commands',
+      httpRoutes: 'HTTP route',
+      channels: 'WebSocket channel',
+      functions: 'Function',
+      scheduledTasks: 'Scheduled task',
+      queueWorkers: 'Queue worker',
+      mcpEndpoints: 'MCP endpoint',
+      cliCommands: 'CLI command',
+      workflows: 'Workflow',
     }
 
     for (const [key, label] of Object.entries(statLabels)) {
       const value = this.stats[key]
       if (value !== undefined && value > 0) {
-        lines.push(chalk.gray(`  • ${value} ${label}`))
+        lines.push(chalk.gray(`  • ${value} ${label}${value > 1 ? 's' : ''}`))
       }
     }
 

package/src/utils/pikku-cli-config.ts

@@ -66,11 +66,9 @@ const _getPikkuCLIConfig = async (
         },
         ignoreFiles: config.ignoreFiles ??
           extendedConfig.ignoreFiles ?? [
-            '**/*.gen.ts',
             '**/*.test.ts',
             '**/*.spec.ts',
             '**/node_modules/**',
-            '**/.pikku/**',
             '**/dist/**',
           ],
         schema: {
@@ -89,11 +87,9 @@ const _getPikkuCLIConfig = async (
           ? resolve(configDir, config.rootDir)
           : configDir,
         ignoreFiles: config.ignoreFiles ?? [
-          '**/*.gen.ts',
           '**/*.test.ts',
           '**/*.spec.ts',
           '**/node_modules/**',
-          '**/.pikku/**',
           '**/dist/**',
         ],
         schema: {
@@ -111,6 +107,7 @@ const _getPikkuCLIConfig = async (
     const rpcDir = join(result.outDir, 'rpc')
     const schedulerDir = join(result.outDir, 'scheduler')
     const queueDir = join(result.outDir, 'queue')
+    const workflowDir = join(result.outDir, 'workflow')
     const mcpDir = join(result.outDir, 'mcp')
     const cliDir = join(result.outDir, 'cli')
     const middlewareDir = join(result.outDir, 'middleware')
@@ -209,6 +206,17 @@ const _getPikkuCLIConfig = async (
       )
     }
 
+    // RPC config defaults
+    if (!result.rpc) {
+      result.rpc = {}
+    }
+    if (!result.rpc.remoteRpcWorkersPath) {
+      result.rpc.remoteRpcWorkersPath = join(
+        rpcDir,
+        'pikku-remote-rpc-workers.gen.ts'
+      )
+    }
+
     // Scheduler
     if (!result.schedulersWiringFile) {
       result.schedulersWiringFile = join(
@@ -252,6 +260,38 @@ const _getPikkuCLIConfig = async (
       result.queueTypesFile = join(queueDir, 'pikku-queue-types.gen.ts')
     }
 
+    // Workflows
+    if (!result.workflowsWiringFile) {
+      result.workflowsWiringFile = join(
+        workflowDir,
+        'pikku-workflow-wirings.gen.ts'
+      )
+    }
+    if (!result.workflowsWiringMetaFile) {
+      result.workflowsWiringMetaFile = join(
+        workflowDir,
+        'pikku-workflow-wirings-meta.gen.ts'
+      )
+    }
+    if (!result.workflowsWorkersFile) {
+      result.workflowsWorkersFile = join(
+        workflowDir,
+        'pikku-workflow-workers.gen.ts'
+      )
+    }
+    if (!result.workflowMapDeclarationFile) {
+      result.workflowMapDeclarationFile = join(
+        workflowDir,
+        'pikku-workflow-map.gen.d.ts'
+      )
+    }
+    if (!result.workflowTypesFile) {
+      result.workflowTypesFile = join(
+        workflowDir,
+        'pikku-workflow-types.gen.ts'
+      )
+    }
+
     // Services
     if (!result.servicesFile) {
       result.servicesFile = join(result.outDir, 'pikku-services.gen.ts')