@pikku/core 0.11.1 → 0.12.0

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

@@ -1,4 +1,4 @@
-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'
@@ -20,7 +20,10 @@ import type {
   CreateSingletonServices,
 } from '../../types/core.types.js'
 import { PikkuChannel } from '../channel/channel.types.js'
-import { PikkuSessionService } from '../../services/user-session-service.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../services/user-session-service.js'
 import { LocalVariablesService } from '../../services/local-variables.js'
 import { generateCommandHelp, parseCLIArguments } from './command-parser.js'
 
@@ -57,17 +60,17 @@ 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(
-      `CLI metadata not found for program '${cli.program}'. Did you run 'pikku all'?`
+    throw new PikkuMissingMetaError(
+      `CLI metadata not found for program '${cli.program}'`
     )
   }
 
   // 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 +78,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 +133,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]
@@ -141,7 +144,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) {
@@ -166,6 +169,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 +212,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 +253,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}`)
@@ -271,11 +275,11 @@ 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> =
-    pikkuState('cli', 'programs') || {}
+    pikkuState(null, 'cli', 'programs') || {}
   const programData = programs[program]
 
   // Combine program middleware + command middleware from the hierarchy
@@ -331,7 +335,7 @@ export async function runCLICommand({
       data: pluckedData,
       channel,
     },
-    session: userSession,
+    ...createMiddlewareSessionWireProps(userSession),
   }
 
   try {
@@ -346,10 +350,12 @@ 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())
       )
@@ -394,7 +400,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> {
@@ -406,7 +412,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) {
@@ -469,7 +475,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

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

@@ -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/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'

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

@@ -0,0 +1,322 @@
+import { test, describe, beforeEach, afterEach } from 'node:test'
+import * as assert from 'assert'
+import { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { addFunction } from '../../function/function-runner.js'
+import { httpRouter } from './routers/http-router.js'
+import { CorePikkuMiddleware } from '../../types/core.types.js'
+
+// Mock function for testing
+const mockFunc = async () => ({ success: true })
+
+// Mock middleware
+const mockMiddleware: CorePikkuMiddleware = async (_services, _wire, next) => {
+  await next()
+}
+
+// Helper to set up function metadata for routes
+const setupFunctionMeta = (
+  routes: Array<{ method: string; route: string }>
+) => {
+  const meta: Record<string, Record<string, any>> = {
+    get: {},
+    post: {},
+    delete: {},
+    patch: {},
+    head: {},
+    put: {},
+    options: {},
+  }
+
+  for (const { method, route } of routes) {
+    meta[method][route] = {
+      pikkuFuncId: `func_${route.replace(/[^a-z0-9]/gi, '_')}`,
+      route,
+      method,
+    }
+  }
+
+  pikkuState(null, 'http', 'meta', meta)
+
+  for (const { method, route } of routes) {
+    const funcName = `func_${route.replace(/[^a-z0-9]/gi, '_')}`
+    pikkuState(null, 'function', 'meta', {
+      [funcName]: {
+        pikkuFuncId: funcName,
+        services: [],
+      },
+    } as any)
+    addFunction(funcName, { func: mockFunc })
+  }
+}
+
+describe('defineHTTPRoutes', () => {
+  test('should accept routes directly', () => {
+    const routes = defineHTTPRoutes({
+      list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      get: { method: 'get', route: '/todos/:id', func: { func: mockFunc } },
+    })
+
+    assert.ok(routes.routes.list)
+    assert.ok(routes.routes.get)
+    assert.strictEqual(routes.routes.list.method, 'get')
+    assert.strictEqual(routes.routes.list.route, '/todos')
+  })
+
+  test('should accept config with routes', () => {
+    const routes = defineHTTPRoutes({
+      auth: true,
+      tags: ['todos'],
+      routes: {
+        list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      },
+    })
+
+    assert.strictEqual(routes.auth, true)
+    assert.deepStrictEqual(routes.tags, ['todos'])
+    assert.ok(routes.routes.list)
+  })
+
+  test('should handle basePath in config', () => {
+    const routes = defineHTTPRoutes({
+      basePath: '/api',
+      routes: {
+        list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      },
+    })
+
+    assert.strictEqual(routes.basePath, '/api')
+  })
+})
+
+describe('wireHTTPRoutes', () => {
+  beforeEach(() => {
+    resetPikkuState()
+    httpRouter.reset()
+  })
+
+  afterEach(() => {
+    resetPikkuState()
+    httpRouter.reset()
+  })
+
+  test('should wire flat array of routes', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'post', route: '/todos' },
+    ])
+
+    wireHTTPRoutes({
+      routes: [
+        { method: 'get', route: '/todos', func: { func: mockFunc } },
+        { method: 'post', route: '/todos', func: { func: mockFunc } },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/todos'))
+    assert.ok(routes.get('post')?.has('/todos'))
+  })
+
+  test('should wire nested object routes', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'get', route: '/todos/:id' },
+      { method: 'post', route: '/auth/login' },
+    ])
+
+    wireHTTPRoutes({
+      routes: {
+        todos: {
+          list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+          get: {
+            method: 'get',
+            route: '/todos/:id',
+            func: { func: mockFunc },
+          },
+        },
+        auth: {
+          login: {
+            method: 'post',
+            route: '/auth/login',
+            func: { func: mockFunc },
+          },
+        },
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/todos'))
+    assert.ok(routes.get('get')?.has('/todos/:id'))
+    assert.ok(routes.get('post')?.has('/auth/login'))
+  })
+
+  test('should apply basePath to all routes', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/api/v1/todos' },
+      { method: 'post', route: '/api/v1/todos' },
+    ])
+
+    wireHTTPRoutes({
+      basePath: '/api/v1',
+      routes: [
+        { method: 'get', route: '/todos', func: { func: mockFunc } },
+        { method: 'post', route: '/todos', func: { func: mockFunc } },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/api/v1/todos'))
+    assert.ok(routes.get('post')?.has('/api/v1/todos'))
+  })
+
+  test('should merge tags from group config and route config', () => {
+    setupFunctionMeta([{ method: 'get', route: '/todos' }])
+
+    wireHTTPRoutes({
+      tags: ['api'],
+      routes: [
+        {
+          method: 'get',
+          route: '/todos',
+          func: { func: mockFunc },
+          tags: ['todos'],
+        },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const route = routes.get('get')?.get('/todos')
+    assert.deepStrictEqual(route?.tags, ['api', 'todos'])
+  })
+
+  test('should merge middleware from group config and route config', () => {
+    setupFunctionMeta([{ method: 'get', route: '/todos' }])
+
+    const groupMiddleware: CorePikkuMiddleware = async (_s, _w, next) => {
+      await next()
+    }
+    const routeMiddleware: CorePikkuMiddleware = async (_s, _w, next) => {
+      await next()
+    }
+
+    wireHTTPRoutes({
+      middleware: [groupMiddleware],
+      routes: [
+        {
+          method: 'get',
+          route: '/todos',
+          func: { func: mockFunc },
+          middleware: [routeMiddleware],
+        },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const route = routes.get('get')?.get('/todos')
+    assert.strictEqual(route?.middleware?.length, 2)
+  })
+
+  test('should allow route auth to override group auth', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'post', route: '/auth/login' },
+    ])
+
+    wireHTTPRoutes({
+      auth: true,
+      routes: [
+        { method: 'get', route: '/todos', func: { func: mockFunc } },
+        {
+          method: 'post',
+          route: '/auth/login',
+          func: { func: mockFunc },
+          auth: false,
+        },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const todosRoute = routes.get('get')?.get('/todos')
+    const loginRoute = routes.get('post')?.get('/auth/login')
+
+    assert.strictEqual(todosRoute?.auth, true)
+    assert.strictEqual(loginRoute?.auth, false)
+  })
+
+  test('should wire routes from defineHTTPRoutes contracts', () => {
+    const todosRoutes = defineHTTPRoutes({
+      tags: ['todos'],
+      routes: {
+        list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      },
+    })
+
+    setupFunctionMeta([{ method: 'get', route: '/api/todos' }])
+
+    wireHTTPRoutes({
+      basePath: '/api',
+      tags: ['api'],
+      routes: {
+        todos: todosRoutes,
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const route = routes.get('get')?.get('/api/todos')
+    assert.ok(route)
+    assert.deepStrictEqual(route?.tags, ['api', 'todos'])
+  })
+
+  test('should cascade basePath from multiple levels', () => {
+    const todosRoutes = defineHTTPRoutes({
+      basePath: '/todos',
+      routes: {
+        list: { method: 'get', route: '', func: { func: mockFunc } },
+        get: { method: 'get', route: '/:id', func: { func: mockFunc } },
+      },
+    })
+
+    setupFunctionMeta([
+      { method: 'get', route: '/api/v1/todos' },
+      { method: 'get', route: '/api/v1/todos/:id' },
+    ])
+
+    wireHTTPRoutes({
+      basePath: '/api/v1',
+      routes: {
+        todos: todosRoutes,
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/api/v1/todos'))
+    assert.ok(routes.get('get')?.has('/api/v1/todos/:id'))
+  })
+
+  test('should handle deeply nested route maps', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'get', route: '/todos/:id' },
+    ])
+
+    wireHTTPRoutes({
+      routes: {
+        level1: {
+          level2: {
+            list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+            get: {
+              method: 'get',
+              route: '/todos/:id',
+              func: { func: mockFunc },
+            },
+          },
+        },
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/todos'))
+    assert.ok(routes.get('get')?.has('/todos/:id'))
+  })
+})