@pikku/core 0.11.0 → 0.11.2

package/src/wirings/forge-node/forge-node.types.ts

@@ -0,0 +1,135 @@
+/**
+ * Forge node types for workflow builder visualization.
+ * wireForgeNode is metadata-only - no runtime behavior.
+ * The CLI extracts this via AST and generates JSON metadata.
+ */
+
+/**
+ * The type of forge node.
+ * - trigger: Starts workflows (webhooks, schedules, events)
+ * - action: Operations that do something (API calls, send email, database ops)
+ * - end: Terminal nodes with no outputs (logging, notifications)
+ */
+export type ForgeNodeType = 'trigger' | 'action' | 'end'
+
+/**
+ * Configuration for wireForgeNode.
+ * This is the input type that developers use when defining nodes.
+ */
+export type CoreForgeNode = {
+  /** Unique identifier for this node */
+  name: string
+  /** Human-readable name for UI display */
+  displayName: string
+  /** Grouping category (validated against forge.node.categories in config) */
+  category: string
+  /** Node type determining behavior and outputs */
+  type: ForgeNodeType
+  /** RPC name to call when node executes (local name, Forge handles package aliasing) */
+  rpc: string
+  /** Optional description for UI */
+  description?: string
+  /** Whether to add an error output port alongside the default output */
+  errorOutput?: boolean
+  /** Optional tags for filtering/categorization */
+  tags?: string[]
+}
+
+/**
+ * Metadata generated for each forge node.
+ * This is the output type that the CLI generates.
+ */
+export type ForgeNodeMeta = {
+  name: string
+  displayName: string
+  category: string
+  type: ForgeNodeType
+  /** RPC name (local, remapped by Forge for external packages) */
+  rpc: string
+  description?: string
+  /** Whether node has error output port */
+  errorOutput: boolean
+  /** Input schema name extracted from RPC */
+  inputSchemaName: string | null
+  /** Output schema name extracted from RPC */
+  outputSchemaName: string | null
+  tags?: string[]
+}
+
+/**
+ * Record of all forge node metadata, keyed by node name.
+ */
+export type ForgeNodesMeta = Record<string, ForgeNodeMeta>
+
+/**
+ * No-op function for wireForgeNode.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing.
+ */
+export const wireForgeNode = (_config: CoreForgeNode): void => {
+  // No-op - metadata only, extracted by CLI via AST
+}
+
+/**
+ * Configuration for wireForgeCredential.
+ * Declares credentials/secrets required by a Forge package.
+ * Uses Zod for schema definition - converted to JSON Schema at build time.
+ */
+export type CoreForgeCredential<T = unknown> = {
+  /** Unique identifier for this credential */
+  name: string
+  /** Human-readable name for UI display */
+  displayName: string
+  /** Optional description for UI */
+  description?: string
+  /** Key used with SecretService.getSecret() to retrieve the credential */
+  secretId: string
+  /** Zod schema defining the structure of the credential */
+  schema: T
+}
+
+/**
+ * Metadata generated for each forge credential.
+ * Schema is converted from Zod to JSON Schema at build time.
+ */
+export type ForgeCredentialMeta = {
+  name: string
+  displayName: string
+  description?: string
+  secretId: string
+  /** JSON Schema (converted from Zod at build time) or zodLookup reference name */
+  schema: Record<string, unknown> | string
+}
+
+/**
+ * Record of all forge credential metadata, keyed by credential name.
+ */
+export type ForgeCredentialsMeta = Record<string, ForgeCredentialMeta>
+
+/**
+ * No-op function for wireForgeCredential.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod'
+ *
+ * const slackCredentials = z.object({
+ *   botToken: z.string().describe('Bot OAuth token'),
+ *   signingSecret: z.string().describe('Request signing secret')
+ * })
+ *
+ * wireForgeCredential({
+ *   name: 'slack',
+ *   displayName: 'Slack Credentials',
+ *   secretId: 'SLACK_CREDENTIALS',
+ *   schema: slackCredentials
+ * })
+ * ```
+ */
+export const wireForgeCredential = <T>(
+  _config: CoreForgeCredential<T>
+): void => {
+  // No-op - metadata only, extracted by CLI via AST
+}

package/src/wirings/forge-node/index.ts

@@ -0,0 +1 @@
+export * from './forge-node.types.js'

package/src/wirings/http/http-runner.test.ts

@@ -11,19 +11,19 @@ import {
 import { addFunction } from '../../function/function-runner.js'
 import { httpRouter } from './routers/http-router.js'
 
-const sessionMiddleware: CorePikkuMiddleware = async (services, _, next) => {
-  services.userSession.set({ userId: 'test' } as any)
+const sessionMiddleware: CorePikkuMiddleware = async (services, wire, next) => {
+  wire.session?.set({ userId: 'test' } as any)
   await next()
 }
 
 const setHTTPFunctionMap = (func: any) => {
-  pikkuState('function', 'meta', {
+  pikkuState(null, 'function', 'meta', {
     pikku_func_name: {
       pikkuFuncName: 'pikku_func_name',
       services: ['userSession'],
     },
   } as any)
-  pikkuState('http', 'meta', {
+  pikkuState(null, 'http', 'meta', {
     get: {
       test: {
         pikkuFuncName: 'pikku_func_name',
@@ -43,7 +43,7 @@ const setHTTPFunctionMap = (func: any) => {
 
 describe('fetch', () => {
   let singletonServices: any
-  let createSessionServices: any
+  let createWireServices: any
   let request: any
   let response: any
 
@@ -59,7 +59,7 @@ describe('fetch', () => {
       },
     }
 
-    createSessionServices = async () => ({})
+    createWireServices = async () => ({})
     request = new PikkuMockRequest('/test', 'get')
     response = new PikkuMockResponse()
 
@@ -77,7 +77,7 @@ describe('fetch', () => {
       async () =>
         fetch(request, {
           singletonServices,
-          createSessionServices,
+          createWireServices,
           bubbleErrors: true,
         }),
       NotFoundError
@@ -99,7 +99,7 @@ describe('fetch', () => {
 
     const result = await fetch(request, {
       singletonServices,
-      createSessionServices,
+      createWireServices,
     })
 
     assert.deepStrictEqual(await result.json(), { success: true })
@@ -122,7 +122,7 @@ describe('fetch', () => {
 
     await fetch(request, {
       singletonServices,
-      createSessionServices,
+      createWireServices,
     })
 
     assert.strictEqual(await permissions.test(), true)
@@ -143,7 +143,7 @@ describe('fetch', () => {
       async () =>
         fetch(request, {
           singletonServices,
-          createSessionServices,
+          createWireServices,
           bubbleErrors: true,
         }),
       error

package/src/wirings/http/http-runner.ts

@@ -18,25 +18,25 @@ import {
   CoreUserSession,
   CorePikkuMiddleware,
   CorePikkuMiddlewareGroup,
-  SessionServices,
+  WireServices,
+  PikkuWire,
   PikkuWiringTypes,
-  PikkuInteraction,
 } from '../../types/core.types.js'
 import { NotFoundError } from '../../errors/errors.js'
 import {
-  closeSessionServices,
+  closeWireServices,
   createWeakUID,
   isSerializable,
 } from '../../utils.js'
-import { PikkuUserSessionService } from '../../services/user-session-service.js'
+import { PikkuSessionService } from '../../services/user-session-service.js'
 import { handleHTTPError } from '../../handle-error.js'
 import { pikkuState } from '../../pikku-state.js'
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
 import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
 import { PikkuChannel } from '../channel/channel.types.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { rpcService } from '../rpc/rpc-runner.js'
 import { httpRouter } from './routers/http-router.js'
+import { startWorkflowByHttpWire } from '../workflow/workflow-utils.js'
 
 /**
  * Registers HTTP middleware for a specific route pattern.
@@ -69,9 +69,10 @@ import { httpRouter } from './routers/http-router.js'
  */
 export const addHTTPMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
   pattern: string,
-  middleware: CorePikkuMiddlewareGroup
+  middleware: CorePikkuMiddlewareGroup,
+  packageName: string | null = null
 ): CorePikkuMiddlewareGroup => {
-  const httpGroups = pikkuState('middleware', 'httpGroup')
+  const httpGroups = pikkuState(packageName, 'middleware', 'httpGroup')
   httpGroups[pattern] = middleware
   return middleware
 }
@@ -107,9 +108,10 @@ export const addHTTPMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
  */
 export const addHTTPPermission = <PikkuPermission extends CorePikkuPermission>(
   pattern: string,
-  permissions: CorePermissionGroup | CorePikkuPermission[]
+  permissions: CorePermissionGroup | CorePikkuPermission[],
+  packageName: string | null = null
 ): CorePermissionGroup | CorePikkuPermission[] => {
-  const httpGroups = pikkuState('permissions', 'httpGroup')
+  const httpGroups = pikkuState(packageName, 'permissions', 'httpGroup')
   httpGroups[pattern] = permissions
   return permissions
 }
@@ -152,17 +154,19 @@ export const wireHTTP = <
     PikkuMiddleware
   >
 ) => {
-  const httpMeta = pikkuState('http', 'meta')
+  const httpMeta = pikkuState(null, 'http', 'meta')
   const routeMeta = httpMeta[httpWiring.method][httpWiring.route]
   if (!routeMeta) {
     throw new Error('Route metadata not found')
   }
-  addFunction(routeMeta.pikkuFuncName, httpWiring.func)
-  const routes = pikkuState('http', 'routes')
+  if (httpWiring.func) {
+    addFunction(routeMeta.pikkuFuncName, httpWiring.func)
+  }
+  const routes = pikkuState(null, 'http', 'routes')
   if (!routes.has(httpWiring.method)) {
     routes.set(httpWiring.method, new Map())
   }
-  pikkuState('http', 'routes')
+  pikkuState(null, 'http', 'routes')
     .get(httpWiring.method)
     ?.set(httpWiring.route, httpWiring as any)
 }
@@ -185,10 +189,10 @@ const getMatchingRoute = (requestType: string, requestPath: string) => {
   )
 
   if (matchedPath) {
-    const route = pikkuState('http', 'routes')
+    const route = pikkuState(null, 'http', 'routes')
       .get(requestType.toLowerCase() as HTTPMethod)!
       .get(matchedPath.route)!
-    const meta = pikkuState('http', 'meta')[
+    const meta = pikkuState(null, 'http', 'meta')[
       requestType.toLowerCase() as PikkuWiringTypes
     ][route.route]
 
@@ -203,16 +207,16 @@ const getMatchingRoute = (requestType: string, requestPath: string) => {
 }
 
 /**
- * Combines the request and response objects into a single HTTP interaction object.
+ * Combines the request and response objects into a single HTTP wire object.
  *
  * This utility function creates an object that holds both the HTTP request and response,
  * which simplifies passing these around through middleware and route execution.
  *
  * @param {PikkuHTTPRequest | undefined} request - The HTTP request object.
  * @param {PikkuHTTPResponse | undefined} response - The HTTP response object.
- * @returns {PikkuHTTP | undefined} The combined HTTP interaction object or undefined if none provided.
+ * @returns {PikkuHTTP | undefined} The combined HTTP wire object or undefined if none provided.
  */
-export const createHTTPInteraction = (
+export const createHTTPWire = (
   request: PikkuHTTPRequest | undefined,
   response: PikkuHTTPResponse | undefined
 ): PikkuHTTP | undefined => {
@@ -246,15 +250,15 @@ export const createHTTPInteraction = (
  *
  * @param {Object} services - A collection of shared services and utilities.
  * @param {Object} matchedRoute - Contains route details, URL parameters, and optional schema.
- * @param {PikkuHTTP | undefined} http - The HTTP interaction object.
+ * @param {PikkuHTTP | undefined} http - The HTTP wire object.
  * @param {Object} options - Options for route execution (e.g., whether to coerce query strings to arrays).
- * @returns {Promise<any>} An object containing the route handler result and session services (if any).
+ * @returns {Promise<any>} An object containing the route handler result and wire services (if any).
  * @throws Throws errors like MissingSessionError or ForbiddenError on validation failures.
  */
 const executeRoute = async (
   services: {
     singletonServices: any
-    createSessionServices: Function
+    createWireServices?: any
     skipUserSession: boolean
     requestId: string
   },
@@ -269,22 +273,18 @@ const executeRoute = async (
     coerceDataFromSchema: boolean
   }
 ) => {
-  const userSession = new PikkuUserSessionService<CoreUserSession>()
+  const userSession = new PikkuSessionService<CoreUserSession>()
   const { params, route, meta } = matchedRoute
-  const {
-    singletonServices,
-    createSessionServices,
-    skipUserSession,
-    requestId,
-  } = services
-
-  const requiresSession = route.auth !== false
-  let sessionServices: any
-  let result: any
+  const { singletonServices, createWireServices, skipUserSession, requestId } =
+    services
 
   // Attach URL parameters to the request object
   http?.request?.setParams(params)
 
+  const requiresSession = route.auth !== false
+  let wireServices: any
+  let result: any
+
   singletonServices.logger.info(
     `Matched route: ${route.route} | method: ${route.method.toUpperCase()} | auth: ${requiresSession.toString()}`
   )
@@ -324,38 +324,28 @@ const executeRoute = async (
     }
   }
 
-  const interaction: PikkuInteraction = { http, channel }
-
-  const getAllServices = async (session?: CoreUserSession) => {
-    // Create session-specific services for handling the request
-    sessionServices = await createSessionServices(
-      { ...singletonServices, userSession, channel },
-      { http },
-      session
-    )
+  const wire: PikkuWire = { http, channel, session: userSession }
 
-    return rpcService.injectRPCService(
-      {
-        ...singletonServices,
-        ...sessionServices,
-        http,
-        userSession,
-        channel,
-      },
-      interaction,
-      route.auth
+  if (matchedRoute.meta.workflow === true) {
+    await startWorkflowByHttpWire(
+      singletonServices,
+      createWireServices,
+      matchedRoute,
+      wire
     )
+    return wireServices
+      ? { wireServices, result: http.response }
+      : { result: http.response }
   }
 
   result = await runPikkuFunc(
-    PikkuWiringTypes.http,
+    'http',
     `${meta.method}:${meta.route}`,
     meta.pikkuFuncName,
     {
       singletonServices,
-      getAllServices,
+      createWireServices,
       auth: route.auth !== false,
-      userSession,
       data,
       inheritedMiddleware: meta.middleware,
       wireMiddleware: route.middleware,
@@ -363,7 +353,7 @@ const executeRoute = async (
       wirePermissions: route.permissions,
       coerceDataFromSchema: options.coerceDataFromSchema,
       tags: route.tags,
-      interaction,
+      wire,
     }
   )
 
@@ -378,7 +368,7 @@ const executeRoute = async (
   // TODO: Evaluate if the response stream should be explicitly ended.
   // http?.response?.end()
 
-  return sessionServices ? { result, sessionServices } : { result }
+  return wireServices ? { result, wireServices } : { result }
 }
 
 /**
@@ -431,11 +421,11 @@ export const pikkuFetch = async <In, Out>(
  * middleware execution, error handling, and session service cleanup.
  *
  * This function does the following:
- *  - Wraps the incoming request and response into an HTTP interaction object.
+ *  - Wraps the incoming request and response into an HTTP wire object.
  *  - Determines the correct route based on HTTP method and path.
  *  - Executes middleware and the route handler.
  *  - Catches and handles errors, optionally bubbling them if configured.
- *  - Cleans up any session services created during processing.
+ *  - Cleans up any wire services created during processing.
  *
  * @template In Expected input data type.
  * @template Out Expected output data type.
@@ -449,7 +439,7 @@ export const fetchData = async <In, Out>(
   response: PikkuHTTPResponse,
   {
     singletonServices,
-    createSessionServices,
+    createWireServices,
     skipUserSession = false,
     respondWith404 = true,
     logWarningsForStatusCodes = [],
@@ -462,11 +452,11 @@ export const fetchData = async <In, Out>(
     (request as any).getHeader?.('x-request-id') ||
     generateRequestId?.() ||
     createWeakUID()
-  let sessionServices: SessionServices<typeof singletonServices> | undefined
+  let wireServices: WireServices<typeof singletonServices> | undefined
   let result: Out
 
-  // Combine the request and response into one interaction object
-  const http = createHTTPInteraction(
+  // Combine the request and response into one wire object
+  const http = createHTTPWire(
     request instanceof Request ? new PikkuFetchHTTPRequest(request) : request,
     response
   )
@@ -487,10 +477,10 @@ export const fetchData = async <In, Out>(
     }
 
     // Execute the matched route along with its middleware and session management
-    ;({ result, sessionServices } = await executeRoute(
+    ;({ result, wireServices } = await executeRoute(
       {
         singletonServices,
-        createSessionServices,
+        createWireServices,
         skipUserSession,
         requestId,
       },
@@ -513,8 +503,8 @@ export const fetchData = async <In, Out>(
     )
   } finally {
     // Clean up any session-specific services created during processing
-    if (sessionServices) {
-      await closeSessionServices(singletonServices.logger, sessionServices)
+    if (wireServices) {
+      await closeWireServices(singletonServices.logger, wireServices)
     }
   }
 }

package/src/wirings/http/http.types.ts

@@ -1,14 +1,12 @@
 import type { SerializeOptions } from 'cookie'
 import type { PikkuError } from '../../errors/error-handler.js'
 import type {
-  PikkuDocs,
   CoreServices,
   CoreSingletonServices,
   CoreUserSession,
-  CreateSessionServices,
+  CreateWireServices,
   CorePikkuMiddleware,
-  MiddlewareMetadata,
-  PermissionMetadata,
+  CommonWireMeta,
 } from '../../types/core.types.js'
 import type {
   CorePikkuFunction,
@@ -46,7 +44,7 @@ export type RunHTTPWiringOptions = Partial<{
 
 export type RunHTTPWiringParams = {
   singletonServices: CoreSingletonServices
-  createSessionServices: CreateSessionServices<
+  createWireServices: CreateWireServices<
     CoreSingletonServices,
     CoreServices<CoreSingletonServices>,
     CoreUserSession
@@ -83,7 +81,7 @@ export type CoreHTTPFunction = {
   }>
 }
 /**
- * Represents a http interaction within Pikku, including a request and response.
+ * Represents a http wire within Pikku, including a request and response.
  */
 export interface PikkuHTTP<In = unknown> {
   request?: PikkuHTTPRequest<In>
@@ -123,14 +121,12 @@ export type CoreHTTPFunctionWiring<
     In,
     Out,
     any,
-    any,
     any
   > = CorePikkuFunction<In, Out>,
   PikkuFunctionSessionless extends CorePikkuFunctionSessionless<
     In,
     Out,
     any,
-    any,
     any
   > = CorePikkuFunctionSessionless<In, Out>,
   PikkuPermission extends CorePikkuPermission<
@@ -229,6 +225,19 @@ export type CoreHTTPFunctionWiring<
       middleware?: PikkuMiddleware[]
       sse?: undefined
     })
+  | {
+      /** Route triggers a workflow matched by route/method from workflow wires.http */
+      route: R
+      method: HTTPMethod
+      workflow: true
+      func?: undefined
+      permissions?: undefined
+      auth?: undefined
+      tags?: undefined
+      middleware?: undefined
+      returnsJSON?: undefined
+      sse?: boolean
+    }
 
 /**
  * Represents the input types for HTTP wiring metadata, including parameters, query, and body types.
@@ -242,18 +251,14 @@ export type HTTPFunctionMetaInputTypes = {
 /**
  * Represents metadata for a set of HTTP wirings, including HTTP wiring details, methods, input/output types, and documentation.
  */
-export type HTTPWiringMeta = {
-  pikkuFuncName: string
+export type HTTPWiringMeta = CommonWireMeta & {
   route: string
   method: HTTPMethod
   params?: string[]
   query?: string[]
   inputTypes?: HTTPFunctionMetaInputTypes
-  docs?: PikkuDocs
-  tags?: string[]
   sse?: true
-  middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (global + route + tag + explicit)
-  permissions?: PermissionMetadata[] // Pre-resolved permission chain (global + route + tag + explicit)
+  workflow?: true
 }
 export type HTTPWiringsMeta = Record<HTTPMethod, Record<string, HTTPWiringMeta>>
 

package/src/wirings/http/log-http-routes.ts

@@ -6,7 +6,7 @@ import { Logger } from '../../services/index.js'
  * @param logger - A logger for logging information.
  */
 export const logRoutes = (logger: Logger) => {
-  const routesByType = pikkuState('http', 'routes')
+  const routesByType = pikkuState(null, 'http', 'routes')
   if (routesByType.size === 0) {
     logger.info('No routes added')
     return