@pikku/core 0.9.11 → 0.10.0

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

@@ -85,16 +85,15 @@ export const runChannelConnect = async ({
 
   const userSession = new PikkuUserSessionService(channelStore, channelId)
 
-  const { channelConfig, openingData, meta, httpMiddleware } =
-    await openChannel({
-      channelId,
-      createSessionServices,
-      request,
-      route,
-      singletonServices,
-      coerceDataFromSchema,
-      userSession,
-    })
+  const { channelConfig, openingData, meta } = await openChannel({
+    channelId,
+    createSessionServices,
+    request,
+    route,
+    singletonServices,
+    coerceDataFromSchema,
+    userSession,
+  })
 
   const main = async () => {
     try {
@@ -148,9 +147,8 @@ export const runChannelConnect = async ({
     },
     { http },
     combineMiddleware(PikkuWiringTypes.channel, channelConfig.name, {
-      wiringMiddleware: channelConfig.middleware,
-      wiringTags: channelConfig.tags,
-      httpMiddleware,
+      wireInheritedMiddleware: meta.middleware,
+      wireMiddleware: channelConfig.middleware,
     }),
     main
   )
@@ -171,7 +169,7 @@ export const runChannelDisconnect = async ({
   if (!sessionServices && params.createSessionServices) {
     sessionServices = await params.createSessionServices(
       singletonServices,
-      {},
+      { channel },
       session
     )
   }
@@ -195,7 +193,8 @@ export const runChannelMessage = async (
   let sessionServices: SessionServices | undefined
   const { openingData, channelName, session } =
     await params.channelStore.getChannelAndSession(params.channelId)
-  const { channelHandler, channelConfig } = getVariablesForChannel({
+
+  const { channel, channelHandler, channelConfig } = getVariablesForChannel({
     ...params,
     openingData,
     channelName,
@@ -203,7 +202,7 @@ export const runChannelMessage = async (
   if (params.createSessionServices) {
     sessionServices = await params.createSessionServices(
       singletonServices,
-      {},
+      { channel },
       session
     )
   }
@@ -211,7 +210,6 @@ export const runChannelMessage = async (
   try {
     const onMessage = processMessageHandlers(
       { ...singletonServices, ...sessionServices },
-      session,
       channelConfig,
       channelHandler
     )

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

@@ -0,0 +1,123 @@
+import { pikkuState } from '../../../pikku-state.js'
+import { CorePikkuCLIRender, CLIMeta } from '../cli.types.js'
+import { generateCommandHelp, parseCLIArguments } from '../command-parser.js'
+
+/**
+ * Default JSON renderer for CLI output
+ */
+const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
+  console.log(JSON.stringify(data, null, 2))
+}
+
+/**
+ * Execute a CLI program via WebSocket channel
+ * This is the main entry point for CLI-over-Channel clients
+ */
+export async function executeCLIViaChannel({
+  programName,
+  pikkuWS,
+  args = process.argv.slice(2),
+  renderers = {},
+  defaultRenderer,
+}: {
+  programName: string
+  pikkuWS: any // CorePikkuWebsocket instance
+  args?: string[]
+  renderers?: Record<string, CorePikkuCLIRender<any>>
+  defaultRenderer?: CorePikkuCLIRender<any>
+}): Promise<void> {
+  // Get CLI metadata from state
+  const allCLIMeta = pikkuState('cli', 'meta') as unknown as CLIMeta | undefined
+  if (!allCLIMeta) {
+    throw new Error(
+      '[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/errors/pku342 for more information.'
+    )
+  }
+  const programMeta = allCLIMeta.programs[programName]
+
+  if (!programMeta) {
+    console.error(`Error: CLI program "${programName}" not found`)
+    process.exit(1)
+  }
+
+  // Parse arguments for this specific program
+  const parsed = parseCLIArguments(args, programName, allCLIMeta)
+
+  // Handle help (check after parsing to support subcommand help)
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    const helpText = generateCommandHelp(
+      programName,
+      allCLIMeta,
+      parsed.commandPath
+    )
+    console.log(helpText)
+    return
+  }
+
+  if (parsed.errors.length > 0) {
+    // Check if any error is about an unknown command
+    const hasUnknownCommand = parsed.errors.some(
+      (error) =>
+        error.startsWith('Unknown command:') ||
+        error.startsWith('Command not found:')
+    )
+
+    if (hasUnknownCommand) {
+      // Show help instead of error for unknown commands
+      const helpText = generateCommandHelp(
+        programName,
+        allCLIMeta,
+        parsed.commandPath
+      )
+      console.log(helpText)
+      process.exit(1)
+    } else {
+      // Show errors for other types of errors
+      console.error('Errors:')
+      parsed.errors.forEach((error) => console.error(`  ${error}`))
+      process.exit(1)
+    }
+  }
+
+  // Merge positionals and options into single data object
+  const data = { ...parsed.positionals, ...parsed.options }
+
+  // Get the renderer for this command
+  const commandId = parsed.commandPath.join('.')
+  const renderer =
+    renderers[commandId] || defaultRenderer || defaultJSONRenderer
+
+  return new Promise((resolve, reject) => {
+    // Subscribe to responses for this command
+    const commandRoute = pikkuWS.getRoute('command')
+
+    const responseHandler = (response: any) => {
+      // Call renderer for any output
+      renderer(null as any, response, undefined)
+    }
+
+    commandRoute.subscribe(commandId, responseHandler)
+
+    // Handle connection close
+    pikkuWS.ws.addEventListener('close', () => {
+      commandRoute.unsubscribe(commandId, responseHandler)
+      resolve(undefined)
+    })
+
+    pikkuWS.ws.addEventListener('error', (error: any) => {
+      commandRoute.unsubscribe(commandId, responseHandler)
+      reject(error)
+    })
+
+    // Send the command once connected
+    if (pikkuWS.ws.readyState === 1) {
+      // Already open
+      commandRoute.send(commandId, data)
+    } else {
+      // Wait for open
+      pikkuWS.ws.addEventListener('open', () => {
+        commandRoute.send(commandId, data)
+      })
+    }
+  })
+}

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

@@ -0,0 +1 @@
+export * from './cli-channel-runner.js'

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

@@ -0,0 +1,403 @@
+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 { wireCLI, runCLICommand, pikkuCLIRender } from './cli-runner.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { addFunction } from '../../function/function-runner.js'
+
+describe('CLI Runner', () => {
+  let singletonServices: any
+  let createSessionServices: any
+
+  beforeEach(() => {
+    resetPikkuState()
+
+    singletonServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+      },
+    }
+
+    createSessionServices = async () => ({})
+  })
+
+  afterEach(() => {
+    resetPikkuState()
+  })
+
+  describe('runCLICommand', () => {
+    test('should throw NotFoundError when program not found', async () => {
+      pikkuState('cli', 'meta', { programs: {}, renderers: {} })
+
+      await assert.rejects(
+        async () =>
+          runCLICommand({
+            program: 'nonexistent',
+            commandPath: ['test'],
+            data: {},
+            singletonServices,
+          }),
+        NotFoundError
+      )
+    })
+
+    test('should throw NotFoundError when command not found', async () => {
+      pikkuState('cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {},
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      pikkuState('cli', 'programs', {
+        'test-cli': {
+          defaultRenderer: undefined,
+          middleware: [],
+          renderers: {},
+        },
+      })
+
+      await assert.rejects(
+        async () =>
+          runCLICommand({
+            program: 'test-cli',
+            commandPath: ['nonexistent'],
+            data: {},
+            singletonServices,
+          }),
+        NotFoundError
+      )
+    })
+
+    test('should execute command function with merged data', async () => {
+      let receivedData: any
+      const testFunc = async (_services: any, data: any) => {
+        receivedData = data
+        return { success: true }
+      }
+
+      // Setup metadata
+      pikkuState('cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              greet: {
+                command: 'greet <name>',
+                pikkuFuncName: 'greetFunc',
+                positionals: [{ name: 'name', required: true }],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      pikkuState('cli', 'programs', {
+        'test-cli': {
+          defaultRenderer: undefined,
+          middleware: [],
+          renderers: {},
+        },
+      })
+
+      pikkuState('function', 'meta', {
+        greetFunc: {
+          pikkuFuncName: 'greetFunc',
+          inputSchemaName: null,
+          outputSchemaName: null,
+        },
+      })
+
+      addFunction('greetFunc', { func: testFunc, auth: false })
+
+      const result = await runCLICommand({
+        program: 'test-cli',
+        commandPath: ['greet'],
+        data: { name: 'Alice', loud: true },
+        singletonServices,
+      })
+
+      assert.strictEqual(result.success, true)
+      assert.deepStrictEqual(receivedData, { name: 'Alice', loud: true })
+    })
+
+    test('should run middleware before function execution', async () => {
+      const executionOrder: string[] = []
+
+      const testMiddleware: CorePikkuMiddleware = async (
+        _services,
+        _interaction,
+        next
+      ) => {
+        executionOrder.push('middleware')
+        await next()
+      }
+
+      const testFunc = async () => {
+        executionOrder.push('function')
+        return { success: true }
+      }
+
+      pikkuState('cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              test: {
+                command: 'test',
+                pikkuFuncName: 'testFunc',
+                positionals: [],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      pikkuState('cli', 'programs', {
+        'test-cli': {
+          defaultRenderer: undefined,
+          middleware: [testMiddleware],
+          renderers: {},
+        },
+      })
+
+      pikkuState('function', 'meta', {
+        testFunc: {
+          pikkuFuncName: 'testFunc',
+          inputSchemaName: null,
+          outputSchemaName: null,
+        },
+      })
+
+      addFunction('testFunc', { func: testFunc, auth: false })
+
+      await runCLICommand({
+        program: 'test-cli',
+        commandPath: ['test'],
+        data: {},
+        singletonServices,
+      })
+
+      assert.deepStrictEqual(executionOrder, ['middleware', 'function'])
+    })
+
+    test.skip('should provide CLI context to middleware', async () => {
+      let cliContext: any = null
+
+      const testMiddleware: CorePikkuMiddleware = async (
+        _services,
+        interaction,
+        next
+      ) => {
+        cliContext = interaction.cli
+        await next()
+      }
+
+      const testFunc = async () => ({ success: true })
+
+      pikkuState('cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              greet: {
+                command: 'greet <name>',
+                pikkuFuncName: 'greetFunc',
+                positionals: [{ name: 'name', required: true }],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      pikkuState('cli', 'programs', {
+        'test-cli': {
+          defaultRenderer: undefined,
+          middleware: [testMiddleware],
+          renderers: {},
+        },
+      })
+
+      pikkuState('function', 'meta', {
+        greetFunc: {
+          pikkuFuncName: 'greetFunc',
+          inputSchemaName: null,
+          outputSchemaName: null,
+        },
+      })
+
+      addFunction('greetFunc', { func: testFunc, auth: false })
+
+      await runCLICommand({
+        program: 'test-cli',
+        commandPath: ['greet'],
+        data: { name: 'Alice' },
+        singletonServices,
+      })
+
+      assert.ok(cliContext, 'CLI context should be set by middleware')
+      assert.strictEqual(cliContext.program, 'test-cli')
+      assert.deepStrictEqual(cliContext.command, ['greet'])
+      assert.deepStrictEqual(cliContext.data, { name: 'Alice' })
+    })
+
+    test('should throw error when auth required but no session', async () => {
+      const testFunc = async () => ({ success: true })
+
+      pikkuState('cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              secure: {
+                command: 'secure',
+                pikkuFuncName: 'secureFunc',
+                positionals: [],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      pikkuState('function', 'meta', {
+        secureFunc: {
+          pikkuFuncName: 'secureFunc',
+          inputSchemaName: null,
+          outputSchemaName: null,
+        },
+      })
+
+      addFunction('secureFunc', { func: testFunc, auth: true })
+
+      await assert.rejects(
+        async () =>
+          runCLICommand({
+            program: 'test-cli',
+            commandPath: ['secure'],
+            data: {},
+            singletonServices,
+            createSessionServices,
+          }),
+        /Authentication required/
+      )
+    })
+  })
+
+  describe('wireCLI', () => {
+    test('should register CLI program and commands', () => {
+      const greetFunc = async () => 'Hello'
+
+      pikkuState('cli', 'meta', {
+        programs: {
+          'my-cli': {
+            program: 'my-cli',
+            commands: {
+              greet: {
+                command: 'greet <name>',
+                pikkuFuncName: 'greetFunc',
+                positionals: [{ name: 'name', required: true }],
+                options: {
+                  loud: {
+                    description: 'Use loud greeting',
+                    short: 'l',
+                    default: false,
+                  },
+                },
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      wireCLI({
+        program: 'my-cli',
+        commands: {
+          greet: greetFunc,
+        },
+      })
+
+      const programs = pikkuState('cli', 'programs')
+      assert.ok(programs['my-cli'])
+      assert.strictEqual(programs['my-cli'].middleware.length, 0)
+    })
+
+    test('should register CLI with global middleware', () => {
+      const middleware: CorePikkuMiddleware = async (_s, _i, next) => {
+        await next()
+      }
+
+      pikkuState('cli', 'meta', {
+        programs: {
+          'my-cli': {
+            program: 'my-cli',
+            commands: {},
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      wireCLI({
+        program: 'my-cli',
+        commands: {},
+        middleware: [middleware],
+      })
+
+      const programs = pikkuState('cli', 'programs')
+      assert.strictEqual(programs['my-cli'].middleware.length, 1)
+      assert.strictEqual(programs['my-cli'].middleware[0], middleware)
+    })
+
+    test('should throw error when CLI metadata not found', () => {
+      pikkuState('cli', 'meta', { programs: {}, renderers: {} })
+
+      assert.throws(() => {
+        wireCLI({
+          program: 'nonexistent',
+          commands: {},
+        })
+      }, /CLI metadata not found for program 'nonexistent'/)
+    })
+  })
+
+  describe('pikkuCLIRender', () => {
+    test('should create CLI renderer function', () => {
+      const renderer = pikkuCLIRender((services, data) => {
+        console.log(data)
+      })
+
+      assert.strictEqual(typeof renderer, 'function')
+    })
+
+    test('should preserve renderer function behavior', async () => {
+      let receivedData: any
+      const renderer = pikkuCLIRender((services, data) => {
+        receivedData = data
+      })
+
+      await renderer({} as any, { test: 'value' })
+      assert.deepStrictEqual(receivedData, { test: 'value' })
+    })
+  })
+})