@pikku/core 0.11.1 → 0.11.2

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

@@ -57,7 +57,7 @@ export const wireCLI = <
   cli: CoreCLI<Commands, GlobalOptions, PikkuMiddleware, GlobalOutput>
 ) => {
   // Get the existing metadata that was generated during inspection
-  const cliMeta = pikkuState('cli', 'meta') || {}
+  const cliMeta = pikkuState(null, 'cli', 'meta') || {}
 
   if (!cliMeta.programs?.[cli.program]) {
     throw new Error(
@@ -67,7 +67,7 @@ export const wireCLI = <
 
   // Get existing programs state and add this program
   const programs: Record<string, CLIProgramState> =
-    pikkuState('cli', 'programs') || {}
+    pikkuState(null, 'cli', 'programs') || {}
   programs[cli.program] = {
     defaultRenderer: (cli.render ||
       defaultJSONRenderer) as CorePikkuCLIRender<any>,
@@ -75,7 +75,7 @@ export const wireCLI = <
     renderers: {},
     tags: cli.tags,
   }
-  pikkuState('cli', 'programs', programs)
+  pikkuState(null, 'cli', 'programs', programs)
 
   // Register all command functions recursively
   registerCLICommands(
@@ -130,7 +130,7 @@ function registerCLICommands(
   program: string
 ) {
   // Get the CLI metadata to find actual function names
-  const cliMeta = pikkuState('cli', 'meta').programs[program]
+  const cliMeta = pikkuState(null, 'cli', 'meta').programs[program]
 
   for (const [name, command] of Object.entries(commands)) {
     const fullPath = [...path, name]
@@ -166,6 +166,7 @@ function registerCLICommands(
 
     // Store the options and middleware in program state for use during execution
     const programs: Record<string, CLIProgramState> = pikkuState(
+      null,
       'cli',
       'programs'
     )
@@ -208,10 +209,10 @@ function pluckCLIData(
   funcName: string,
   availableOptions: Record<string, CLIOption>
 ): Record<string, any> {
-  const funcMeta = pikkuState('function', 'meta')[funcName]
+  const funcMeta = pikkuState(null, 'function', 'meta')[funcName]
   const schemaName = funcMeta?.inputSchemaName
   const schema = schemaName
-    ? pikkuState('misc', 'schemas').get(schemaName)
+    ? pikkuState(null, 'misc', 'schemas').get(schemaName)
     : null
 
   if (schema && schema.properties) {
@@ -249,7 +250,7 @@ export async function runCLICommand({
   createWireServices?: CreateWireServices
 }): Promise<any> {
   // Get the command metadata to find the function name
-  const cliMeta = pikkuState('cli', 'meta')
+  const cliMeta = pikkuState(null, 'cli', 'meta')
   const programMeta = cliMeta.programs?.[program]
   if (!programMeta) {
     throw new NotFoundError(`Program not found: ${program}`)
@@ -275,7 +276,7 @@ export async function runCLICommand({
 
   // Get program-specific data
   const programs: Record<string, CLIProgramState> =
-    pikkuState('cli', 'programs') || {}
+    pikkuState(null, 'cli', 'programs') || {}
   const programData = programs[program]
 
   // Combine program middleware + command middleware from the hierarchy
@@ -406,7 +407,7 @@ export async function executeCLI({
 
   try {
     // Get CLI metadata from state
-    const allCLIMeta = pikkuState('cli', 'meta') as unknown as
+    const allCLIMeta = pikkuState(null, 'cli', 'meta') as unknown as
       | CLIMeta
       | undefined
     if (!allCLIMeta) {

package/src/wirings/cli/cli.types.ts

@@ -222,6 +222,7 @@ export type CoreCLICommandConfig<
 > = {
   parameters?: ValidateParameters<Params, ExtractFunctionInput<FuncConfig>>
   func?: FuncConfig
+  title?: string
   description?: string
   render?: PikkuCLIRender
   options?: {

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

@@ -17,13 +17,13 @@ const sessionMiddleware: CorePikkuMiddleware = async (services, wire, 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',

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

@@ -36,6 +36,7 @@ import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
 import { PikkuChannel } from '../channel/channel.types.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { httpRouter } from './routers/http-router.js'
+import { startWorkflowByHttpWire } from '../workflow/workflow-utils.js'
 
 /**
  * Registers HTTP middleware for a specific route pattern.
@@ -68,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
 }
@@ -106,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
 }
@@ -151,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)
 }
@@ -184,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]
 
@@ -273,13 +278,13 @@ const executeRoute = async (
   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
 
-  // Attach URL parameters to the request object
-  http?.request?.setParams(params)
-
   singletonServices.logger.info(
     `Matched route: ${route.route} | method: ${route.method.toUpperCase()} | auth: ${requiresSession.toString()}`
   )
@@ -321,6 +326,18 @@ const executeRoute = async (
 
   const wire: PikkuWire = { http, channel, session: userSession }
 
+  if (matchedRoute.meta.workflow === true) {
+    await startWorkflowByHttpWire(
+      singletonServices,
+      createWireServices,
+      matchedRoute,
+      wire
+    )
+    return wireServices
+      ? { wireServices, result: http.response }
+      : { result: http.response }
+  }
+
   result = await runPikkuFunc(
     'http',
     `${meta.method}:${meta.route}`,

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

@@ -225,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.
@@ -245,6 +258,7 @@ export type HTTPWiringMeta = CommonWireMeta & {
   query?: string[]
   inputTypes?: HTTPFunctionMetaInputTypes
   sse?: true
+  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

package/src/wirings/http/routers/path-to-regex.test.ts

@@ -23,6 +23,7 @@ describe('PathToRegexRouter', () => {
     test('should correctly identify static routes', () => {
       // Setup test routes
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([
@@ -36,8 +37,8 @@ describe('PathToRegexRouter', () => {
           ],
         ])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -56,6 +57,7 @@ describe('PathToRegexRouter', () => {
     test('should handle dynamic routes with parameters', () => {
       // Setup test routes with parameters
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([
@@ -71,8 +73,8 @@ describe('PathToRegexRouter', () => {
           ],
         ])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -98,6 +100,7 @@ describe('PathToRegexRouter', () => {
     test('should handle multi-parameter routes', () => {
       // Setup routes with multiple parameters
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([
@@ -116,8 +119,8 @@ describe('PathToRegexRouter', () => {
           ],
         ])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -139,6 +142,7 @@ describe('PathToRegexRouter', () => {
     test('should prioritize static routes over dynamic routes for performance', () => {
       // Setup mixed routes where static could conflict with dynamic
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([
@@ -151,8 +155,8 @@ describe('PathToRegexRouter', () => {
           ],
         ])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -167,6 +171,7 @@ describe('PathToRegexRouter', () => {
   describe('Path Normalization', () => {
     test('should normalize paths without leading slash', () => {
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([
@@ -179,8 +184,8 @@ describe('PathToRegexRouter', () => {
           ],
         ])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -201,9 +206,10 @@ describe('PathToRegexRouter', () => {
 
   describe('Channel Routes Integration', () => {
     test('should handle channel routes as GET routes', () => {
-      pikkuState('http', 'routes', new Map())
-      pikkuState('http', 'middleware', new Map())
+      pikkuState(null, 'http', 'routes', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
       pikkuState(
+        null,
         'channel',
         'channels',
         new Map([
@@ -233,11 +239,13 @@ describe('PathToRegexRouter', () => {
       const routeMiddleware = [async () => {}]
 
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([['get', new Map([['/api/test', mockRoute('/api/test')]])]])
       )
       pikkuState(
+        null,
         'http',
         'middleware',
         new Map([
@@ -245,7 +253,7 @@ describe('PathToRegexRouter', () => {
           ['/api/test', routeMiddleware],
         ])
       )
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -260,12 +268,13 @@ describe('PathToRegexRouter', () => {
   describe('No Match Scenarios', () => {
     test('should return null for non-existent routes', () => {
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([['get', new Map([['/existing', mockRoute('/existing')]])]])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -275,12 +284,13 @@ describe('PathToRegexRouter', () => {
 
     test('should return null for unsupported HTTP methods', () => {
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([['get', new Map([['/test', mockRoute('/test')]])]])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       router.initialize()
 
@@ -292,12 +302,13 @@ describe('PathToRegexRouter', () => {
   describe('Lazy Initialization', () => {
     test('should initialize automatically on first match call', () => {
       pikkuState(
+        null,
         'http',
         'routes',
         new Map([['get', new Map([['/test', mockRoute('/test')]])]])
       )
-      pikkuState('http', 'middleware', new Map())
-      pikkuState('channel', 'channels', new Map())
+      pikkuState(null, 'http', 'middleware', new Map())
+      pikkuState(null, 'channel', 'channels', new Map())
 
       // Don't call initialize manually
       const result = router.match('get', '/test')

package/src/wirings/http/routers/path-to-regex.ts

@@ -25,8 +25,8 @@ export class PathToRegexRouter implements Router {
   }
 
   public initialize() {
-    const routes = pikkuState('http', 'routes')
-    const channelRoutes = pikkuState('channel', 'channels')
+    const routes = pikkuState(null, 'http', 'routes')
+    const channelRoutes = pikkuState(null, 'channel', 'channels')
 
     // Helper function to compile routes for a given method
     const compileRoutesForMethod = (