@pikku/core 0.11.2 → 0.12.1

package/src/wirings/channel/serverless/serverless-channel-runner.ts

@@ -1,4 +1,4 @@
-import { PikkuWire, WireServices } from '../../../types/core.types.js'
+import type { PikkuWire, WireServices } from '../../../types/core.types.js'
 import { closeWireServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
 import { openChannel } from '../channel-runner.js'
@@ -9,12 +9,19 @@ import type {
   PikkuChannelHandlerFactory,
 } from '../channel.types.js'
 import { createHTTPWire } from '../../http/http-runner.js'
-import { ChannelStore } from '../channel-store.js'
+import type { ChannelStore } from '../channel-store.js'
 import { handleHTTPError } from '../../../handle-error.js'
-import { PikkuSessionService } from '../../../services/user-session-service.js'
-import { pikkuState } from '../../../pikku-state.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../../services/user-session-service.js'
+import {
+  getSingletonServices,
+  getCreateWireServices,
+  pikkuState,
+} from '../../../pikku-state.js'
 import { PikkuFetchHTTPRequest } from '../../http/pikku-fetch-http-request.js'
-import { PikkuHTTP } from '../../http/http.types.js'
+import type { PikkuHTTP } from '../../http/http.types.js'
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js'
 
 export interface RunServerlessChannelParams<ChannelData>
@@ -59,13 +66,11 @@ const getVariablesForChannel = ({
 }
 
 export const runChannelConnect = async ({
-  singletonServices,
   channelId,
   channelObject,
   request,
   response,
   route,
-  createWireServices,
   channelStore,
   channelHandlerFactory,
   coerceDataFromSchema = true,
@@ -75,6 +80,8 @@ export const runChannelConnect = async ({
 }: Pick<CoreChannel<unknown, any>, 'route'> &
   RunChannelOptions &
   RunServerlessChannelParams<unknown>) => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   let wireServices: WireServices | undefined
 
   let http: PikkuHTTP | undefined
@@ -86,10 +93,8 @@ export const runChannelConnect = async ({
 
   const { channelConfig, openingData, meta } = await openChannel({
     channelId,
-    createWireServices,
     request,
     route,
-    singletonServices,
     coerceDataFromSchema,
     userSession,
   })
@@ -107,7 +112,10 @@ export const runChannelConnect = async ({
       channelName: channelConfig.name,
     })
 
-    const wire: PikkuWire = { channel, session: userSession }
+    const wire: PikkuWire = {
+      channel,
+      ...createMiddlewareSessionWireProps(userSession),
+    }
 
     if (createWireServices) {
       wireServices = await createWireServices(singletonServices, wire)
@@ -127,6 +135,7 @@ export const runChannelConnect = async ({
         services,
         channel,
         data: openingData,
+        channelMiddlewareMeta: meta.channelMiddleware,
       })
     }
     http?.response?.status(101)
@@ -148,9 +157,12 @@ export const runChannelConnect = async ({
 }
 
 export const runChannelDisconnect = async ({
-  singletonServices,
-  ...params
+  channelId,
+  channelStore,
+  channelHandlerFactory,
 }: RunServerlessChannelParams<unknown>): Promise<void> => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   let wireServices: WireServices | undefined
 
   // Try to get channel from store. In serverless environments (especially with
@@ -159,31 +171,31 @@ export const runChannelDisconnect = async ({
   // there's nothing to disconnect, so we can return early.
   let channelData
   try {
-    channelData = await params.channelStore.getChannelAndSession(
-      params.channelId
-    )
-  } catch (error) {
+    channelData = await channelStore.getChannelAndSession(channelId)
+  } catch {
     singletonServices.logger.info(
-      `Channel ${params.channelId} not found during disconnect - already cleaned up`
+      `Channel ${channelId} not found during disconnect - already cleaned up`
     )
     return
   }
 
   const { openingData, channelName, session } = channelData
   const { channel, channelConfig, meta } = getVariablesForChannel({
-    ...params,
+    channelId,
+    channelHandlerFactory,
     openingData,
     channelName,
   })
-  const userSession = new PikkuSessionService(
-    params.channelStore,
-    params.channelId
-  )
+
+  const userSession = new PikkuSessionService(channelStore, channelId)
   userSession.setInitial(session)
-  const wire: PikkuWire = { channel, session: userSession }
+  const wire: PikkuWire = {
+    channel,
+    ...createMiddlewareSessionWireProps(userSession),
+  }
 
-  if (!wireServices && params.createWireServices) {
-    wireServices = await params.createWireServices(singletonServices, wire)
+  if (createWireServices) {
+    wireServices = await createWireServices(singletonServices, wire)
   }
 
   const services = {
@@ -200,6 +212,7 @@ export const runChannelDisconnect = async ({
         lifecycleType: 'disconnect',
         services,
         channel,
+        channelMiddlewareMeta: meta.channelMiddleware,
       })
     } catch (e: any) {
       singletonServices.logger.error(
@@ -207,34 +220,42 @@ export const runChannelDisconnect = async ({
       )
     }
   }
-  await params.channelStore.removeChannels([channel.channelId])
+  await channelStore.removeChannels([channel.channelId])
   if (wireServices) {
     await closeWireServices(singletonServices.logger, wireServices)
   }
 }
 
 export const runChannelMessage = async (
-  { singletonServices, ...params }: RunServerlessChannelParams<unknown>,
+  {
+    channelId,
+    channelStore,
+    channelHandlerFactory,
+  }: RunServerlessChannelParams<unknown>,
   data: unknown
 ): Promise<unknown> => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   let wireServices: WireServices | undefined
   const { openingData, channelName, session } =
-    await params.channelStore.getChannelAndSession(params.channelId)
+    await channelStore.getChannelAndSession(channelId)
 
   const { channel, channelHandler, channelConfig } = getVariablesForChannel({
-    ...params,
+    channelId,
+    channelHandlerFactory,
     openingData,
     channelName,
   })
-  const userSession = new PikkuSessionService(
-    params.channelStore,
-    params.channelId
-  )
+
+  const userSession = new PikkuSessionService(channelStore, channelId)
   userSession.setInitial(session)
-  const wire: PikkuWire = { channel, session: userSession }
+  const wire: PikkuWire = {
+    channel,
+    ...createMiddlewareSessionWireProps(userSession),
+  }
 
-  if (params.createWireServices) {
-    wireServices = await params.createWireServices(singletonServices, wire)
+  if (createWireServices) {
+    wireServices = await createWireServices(singletonServices, wire)
   }
 
   const services = {

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

@@ -1,5 +1,5 @@
 import { pikkuState } from '../../../pikku-state.js'
-import { CorePikkuCLIRender, type CLIMeta } from '../cli.types.js'
+import type { CorePikkuCLIRender, CLIMeta } from '../cli.types.js'
 import { generateCommandHelp, parseCLIArguments } from '../command-parser.js'
 
 /**

package/src/wirings/cli/channel/index.ts

@@ -1 +1 @@
-export * from './cli-channel-runner.js'
+export { executeCLIViaChannel } from './cli-channel-runner.js'

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

@@ -1,7 +1,7 @@
 import { test, describe, beforeEach, afterEach } from 'node:test'
 import * as assert from 'assert'
 import { NotFoundError } from '../../errors/errors.js'
-import { CorePikkuMiddleware } from '../../types/core.types.js'
+import type { CorePikkuMiddleware } from '../../types/core.types.js'
 import { wireCLI, runCLICommand, pikkuCLIRender } from './cli-runner.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import { addFunction } from '../../function/function-runner.js'
@@ -91,7 +91,7 @@ describe('CLI Runner', () => {
             commands: {
               greet: {
                 command: 'greet <name>',
-                pikkuFuncName: 'greetFunc',
+                pikkuFuncId: 'greetFunc',
                 positionals: [{ name: 'name', required: true }],
                 options: {},
               },
@@ -112,7 +112,7 @@ describe('CLI Runner', () => {
 
       pikkuState(null, 'function', 'meta', {
         greetFunc: {
-          pikkuFuncName: 'greetFunc',
+          pikkuFuncId: 'greetFunc',
           inputSchemaName: null,
           outputSchemaName: null,
         },
@@ -155,7 +155,7 @@ describe('CLI Runner', () => {
             commands: {
               test: {
                 command: 'test',
-                pikkuFuncName: 'testFunc',
+                pikkuFuncId: 'testFunc',
                 positionals: [],
                 options: {},
               },
@@ -176,7 +176,7 @@ describe('CLI Runner', () => {
 
       pikkuState(null, 'function', 'meta', {
         testFunc: {
-          pikkuFuncName: 'testFunc',
+          pikkuFuncId: 'testFunc',
           inputSchemaName: null,
           outputSchemaName: null,
         },
@@ -215,7 +215,7 @@ describe('CLI Runner', () => {
             commands: {
               greet: {
                 command: 'greet <name>',
-                pikkuFuncName: 'greetFunc',
+                pikkuFuncId: 'greetFunc',
                 positionals: [{ name: 'name', required: true }],
                 options: {},
               },
@@ -236,7 +236,7 @@ describe('CLI Runner', () => {
 
       pikkuState(null, 'function', 'meta', {
         greetFunc: {
-          pikkuFuncName: 'greetFunc',
+          pikkuFuncId: 'greetFunc',
           inputSchemaName: null,
           outputSchemaName: null,
         },
@@ -267,7 +267,7 @@ describe('CLI Runner', () => {
             commands: {
               secure: {
                 command: 'secure',
-                pikkuFuncName: 'secureFunc',
+                pikkuFuncId: 'secureFunc',
                 positionals: [],
                 options: {},
               },
@@ -280,7 +280,7 @@ describe('CLI Runner', () => {
 
       pikkuState(null, 'function', 'meta', {
         secureFunc: {
-          pikkuFuncName: 'secureFunc',
+          pikkuFuncId: 'secureFunc',
           inputSchemaName: null,
           outputSchemaName: null,
         },
@@ -313,7 +313,7 @@ describe('CLI Runner', () => {
             commands: {
               greet: {
                 command: 'greet <name>',
-                pikkuFuncName: 'greetFunc',
+                pikkuFuncId: 'greetFunc',
                 positionals: [{ name: 'name', required: true }],
                 options: {
                   loud: {

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

@@ -1,8 +1,11 @@
-import { NotFoundError } from '../../errors/errors.js'
+import { NotFoundError, PikkuMissingMetaError } from '../../errors/errors.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { pikkuState } from '../../pikku-state.js'
-import { CorePikkuMiddleware, CoreUserSession } from '../../types/core.types.js'
-import {
+import type {
+  CorePikkuMiddleware,
+  CoreUserSession,
+} from '../../types/core.types.js'
+import type {
   CoreCLI,
   CLICommandMeta,
   CLIOption,
@@ -19,8 +22,11 @@ import type {
   CreateConfig,
   CreateSingletonServices,
 } from '../../types/core.types.js'
-import { PikkuChannel } from '../channel/channel.types.js'
-import { PikkuSessionService } from '../../services/user-session-service.js'
+import type { PikkuChannel } from '../channel/channel.types.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../services/user-session-service.js'
 import { LocalVariablesService } from '../../services/local-variables.js'
 import { generateCommandHelp, parseCLIArguments } from './command-parser.js'
 
@@ -60,8 +66,8 @@ export const wireCLI = <
   const cliMeta = pikkuState(null, 'cli', 'meta') || {}
 
   if (!cliMeta.programs?.[cli.program]) {
-    throw new Error(
-      `CLI metadata not found for program '${cli.program}'. Did you run 'pikku all'?`
+    throw new PikkuMissingMetaError(
+      `CLI metadata not found for program '${cli.program}'`
     )
   }
 
@@ -141,7 +147,7 @@ function registerCLICommands(
     for (let i = 1; i < fullPath.length; i++) {
       currentMeta = currentMeta?.subcommands?.[fullPath[i]]
     }
-    const funcName = currentMeta?.pikkuFuncName
+    const funcName = currentMeta?.pikkuFuncId
 
     // Skip if no function name (could be a command group)
     if (!funcName) {
@@ -272,7 +278,7 @@ export async function runCLICommand({
     currentCommand = currentCommand.subcommands[commandPath[i]]
   }
 
-  const funcName = currentCommand.pikkuFuncName
+  const funcName = currentCommand.pikkuFuncId
 
   // Get program-specific data
   const programs: Record<string, CLIProgramState> =
@@ -332,7 +338,7 @@ export async function runCLICommand({
       data: pluckedData,
       channel,
     },
-    session: userSession,
+    ...createMiddlewareSessionWireProps(userSession),
   }
 
   try {
@@ -347,12 +353,18 @@ export async function runCLICommand({
       wirePermissions: undefined,
       tags: programData?.tags,
       wire,
+      sessionService: userSession,
     })
 
     // Apply renderer one final time with the final output (if renderer exists)
-    if (renderer) {
+    // Skip if result is undefined (void functions handle their own output)
+    if (renderer && result !== undefined) {
       await Promise.resolve(
-        renderer(singletonServices, result, userSession.get())
+        renderer(
+          singletonServices,
+          result,
+          userSession.get() as CoreUserSession | undefined
+        )
       )
     }
 
@@ -395,7 +407,7 @@ export async function executeCLI({
 }: {
   programName: string
   args?: string[]
-  createConfig: CreateConfig<any, any>
+  createConfig?: CreateConfig<any, any>
   createSingletonServices: CreateSingletonServices<any, any>
   createWireServices?: CreateWireServices<any, any, any>
 }): Promise<void> {
@@ -470,7 +482,9 @@ export async function executeCLI({
     const data = { ...parsed.positionals, ...parsed.options }
 
     // Create config (pass data in case it needs to use any parsed options)
-    const config = await createConfig(new LocalVariablesService(), data)
+    const config = createConfig
+      ? await createConfig(new LocalVariablesService(), data)
+      : ({} as any)
 
     // Create services with config
     const singletonServices = await createSingletonServices(config)

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

@@ -1,4 +1,4 @@
-import {
+import type {
   CorePikkuMiddleware,
   CoreSingletonServices,
   CoreUserSession,
@@ -6,13 +6,13 @@ import {
   MiddlewareMetadata,
   PermissionMetadata,
 } from '../../types/core.types.js'
-import {
+import type {
   CorePikkuFunctionConfig,
   CorePikkuPermission,
   CorePikkuFunction,
   CorePikkuFunctionSessionless,
 } from '../../function/functions.types.js'
-import { PikkuChannel } from '../channel/channel.types.js'
+import type { PikkuChannel } from '../channel/channel.types.js'
 
 /**
  * CLI option definition
@@ -69,7 +69,7 @@ export interface CLIProgramState {
  */
 export interface CLICommandMeta {
   parameters?: string
-  pikkuFuncName: string
+  pikkuFuncId: string
   positionals: CLIPositional[]
   options: Record<string, CLIOption>
   renderName?: string
@@ -131,8 +131,8 @@ export type CorePikkuCLIRender<
 export type ExtractFunctionInput<Func> =
   Func extends CorePikkuFunctionConfig<infer FuncType, any, any>
     ? FuncType extends
-        | CorePikkuFunction<infer Input, any, any, any>
-        | CorePikkuFunctionSessionless<infer Input, any, any, any>
+        | CorePikkuFunction<infer Input, any, any, any, any>
+        | CorePikkuFunctionSessionless<infer Input, any, any, any, any>
       ? Input
       : never
     : never
@@ -198,8 +198,8 @@ export type ValidateParameters<Params extends string, Input> =
 export type ExtractFunctionOutput<Func> =
   Func extends CorePikkuFunctionConfig<infer FuncType, any, any>
     ? FuncType extends
-        | CorePikkuFunction<any, infer Output, any, any>
-        | CorePikkuFunctionSessionless<any, infer Output, any, any>
+        | CorePikkuFunction<any, infer Output, any, any, any>
+        | CorePikkuFunctionSessionless<any, infer Output, any, any, any>
       ? Output
       : never
     : never
@@ -249,8 +249,8 @@ export interface CoreCLICommand<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any>
+    | CorePikkuFunction<In, Out, any, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any, any>
   >,
   PikkuPermission extends CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware,
@@ -282,8 +282,8 @@ export type CLICommandShorthand<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any>
+    | CorePikkuFunction<In, Out, any, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any, any>
   >,
 > = PikkuFunctionConfig
 
@@ -294,8 +294,8 @@ export type CLICommandDefinition<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any>
+    | CorePikkuFunction<In, Out, any, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any, any>
   >,
   PikkuPermission extends CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware,

package/src/wirings/cli/command-parser.test.ts

@@ -1,7 +1,7 @@
 import { test, describe } from 'node:test'
 import * as assert from 'assert'
 import { parseCLIArguments, generateCommandHelp } from './command-parser.js'
-import { CLIMeta } from './cli.types.js'
+import type { CLIMeta } from './cli.types.js'
 
 const testMeta: CLIMeta = {
   programs: {
@@ -17,7 +17,7 @@ const testMeta: CLIMeta = {
       commands: {
         greet: {
           parameters: '<name>',
-          pikkuFuncName: 'greetFunc',
+          pikkuFuncId: 'greetFunc',
           positionals: [{ name: 'name', required: true }],
           options: {
             loud: {
@@ -28,13 +28,13 @@ const testMeta: CLIMeta = {
           },
         },
         user: {
-          pikkuFuncName: '',
+          pikkuFuncId: '',
           positionals: [],
           options: {},
           subcommands: {
             create: {
               parameters: '<name> <email>',
-              pikkuFuncName: 'createUserFunc',
+              pikkuFuncId: 'createUserFunc',
               positionals: [
                 { name: 'name', required: true },
                 { name: 'email', required: true },
@@ -50,7 +50,7 @@ const testMeta: CLIMeta = {
             },
             delete: {
               parameters: '<id>',
-              pikkuFuncName: 'deleteUserFunc',
+              pikkuFuncId: 'deleteUserFunc',
               positionals: [{ name: 'id', required: true }],
               options: {
                 force: {
@@ -64,13 +64,13 @@ const testMeta: CLIMeta = {
         },
         files: {
           parameters: '<paths...>',
-          pikkuFuncName: 'filesFunc',
+          pikkuFuncId: 'filesFunc',
           positionals: [{ name: 'paths', required: true, variadic: true }],
           options: {},
         },
         optional: {
           parameters: '[name]',
-          pikkuFuncName: 'optionalFunc',
+          pikkuFuncId: 'optionalFunc',
           positionals: [{ name: 'name', required: false }],
           options: {},
         },
@@ -299,7 +299,7 @@ describe('Command Parser', () => {
             options: {},
             commands: {
               test: {
-                pikkuFuncName: 'testFunc',
+                pikkuFuncId: 'testFunc',
                 positionals: [],
                 options: {
                   port: {
@@ -380,7 +380,7 @@ describe('Command Parser', () => {
             commands: {
               greet: {
                 parameters: '<name>',
-                pikkuFuncName: 'greetFunc',
+                pikkuFuncId: 'greetFunc',
                 description: 'Greet a user',
                 positionals: [{ name: 'name', required: true }],
                 options: {},

package/src/wirings/cli/command-parser.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   CLIMeta,
   CLIProgramMeta,
   CLICommandMeta,

package/src/wirings/cli/define-cli-commands.ts

@@ -0,0 +1,24 @@
+import type { CoreCLICommandConfig } from './cli.types.js'
+
+/**
+ * Type-safe helper for defining CLI commands that can be composed.
+ * Returns the commands record as-is (identity function) for use with `wireCLI`.
+ *
+ * @example
+ * ```typescript
+ * export const chatCommands = defineCLICommands({
+ *   chat: pikkuCLICommand({ func: chatFunc }),
+ *   'chat:history': pikkuCLICommand({ func: historyFunc }),
+ * })
+ *
+ * wireCLI({
+ *   program: 'my-app',
+ *   commands: { ...chatCommands, other: pikkuCLICommand({ func: otherFunc }) }
+ * })
+ * ```
+ */
+export function defineCLICommands<
+  T extends Record<string, CoreCLICommandConfig<any, any, any, any>>,
+>(commands: T): T {
+  return commands
+}

package/src/wirings/cli/index.ts

@@ -1,7 +1,3 @@
-export * from './cli.types.js'
-export * from './cli-runner.js'
-export * from './command-parser.js'
-
 export {
   wireCLI,
   runCLICommand,
@@ -11,3 +7,13 @@ export {
 } from './cli-runner.js'
 
 export { parseCLIArguments, generateCommandHelp } from './command-parser.js'
+
+export { defineCLICommands } from './define-cli-commands.js'
+export type {
+  CLIMeta,
+  CLICommandMeta,
+  CLIProgramMeta,
+  CoreCLI,
+  CoreCLICommandConfig,
+  CorePikkuCLIRender,
+} from './cli.types.js'