@pikku/addon-graph 0.0.2 → 0.12.0

package/.pikku/addon/pikku-addon-types.gen.ts

@@ -1,11 +1,11 @@
 /**
- * This file was generated by @pikku/cli@0.12.2
+ * This file was generated by @pikku/cli@0.12.19
  */
 /**
  * Addon package types for pikkuAddonConfig and pikkuAddonServices
  */
 
-import type { CreateConfig } from '@pikku/core'
+import type { CreateConfig, PikkuWire } from '@pikku/core'
 import type { SingletonServices } from '../../types/application-types.d.js'
 import type { Config } from '../../types/application-types.d.js'
 import type { RequiredSingletonServices } from '../pikku-services.gen.js'
@@ -15,6 +15,7 @@ import { TypedVariablesService } from '../variables/pikku-variables.gen.js'
 
 
 
+
 /**
  * Base services provided to addon package service factories.
  * These are always available from the parent application.
@@ -63,16 +64,42 @@ export const pikkuAddonServices = <T extends Record<string, any>, ExistingServic
   func: (config: Config, services: ExistingServices) => Promise<T>
 ) => {
   return async (config: Config, existingServices?: Partial<SingletonServices>): Promise<RequiredSingletonServices> => {
-    const { logger, variables, secrets } = (existingServices ?? {}) as unknown as SingletonServices
+    const { logger, variables, secrets, schema } = (existingServices ?? {}) as unknown as SingletonServices
     const typedVariables = new TypedVariablesService(variables)
     const typedSecrets = new TypedSecretService(secrets)
     const result = await func(config, { ...existingServices, logger, variables: typedVariables, secrets: typedSecrets } as ExistingServices)
     return {
       config,
       logger,
+      schema,
       variables: typedVariables,
       secrets: typedSecrets,
       ...result,
     } as unknown as RequiredSingletonServices
   }
 }
+
+/**
+ * Creates a Pikku wire services factory for addon packages.
+ * Wire services are created per-request and have access to the HTTP request context.
+ *
+ * @param func - Wire services factory function that receives singleton services and the wire context
+ * @returns The wire services factory function
+ *
+ * @example
+ * ```typescript
+ * export const createWireServices = pikkuAddonWireServices(async (services, wire) => {
+ *   const authHeader = wire.http?.request?.header('authorization')
+ *   return { myService: new MyService(authHeader) }
+ * })
+ * ```
+ */
+export const pikkuAddonWireServices = <ExistingServices extends Omit<Partial<SingletonServices>, 'variables' | 'secrets'> & AddonBaseServices>(
+  func: (services: ExistingServices, wire: PikkuWire) => Promise<Record<string, any>>
+) => {
+  return ((services: any, wire: PikkuWire) => {
+    const typedVariables = new TypedVariablesService(services.variables)
+    const typedSecrets = new TypedSecretService(services.secrets)
+    return func({ ...services, variables: typedVariables, secrets: typedSecrets } as ExistingServices, wire)
+  }) as any
+}

package/.pikku/addon/pikku-package.gen.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.2
+ * This file was generated by @pikku/cli@0.12.19
  */
 import { pikkuState } from '@pikku/core/internal'
 import { createSingletonServices as createSingletonServices } from '../../src/services.js'
@@ -7,3 +7,5 @@ import { createSingletonServices as createSingletonServices } from '../../src/se
 pikkuState('@pikku/addon-graph', 'package', 'factories', {
   createSingletonServices,
 })
+
+pikkuState('@pikku/addon-graph', 'package', 'requiredParentServices', ["jwt"])

package/.pikku/agent/pikku-agent-map.gen.d.ts

@@ -1,16 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.2
+ * This file was generated by @pikku/cli@0.12.19
  */
-/**
- * Agent type map with output types for each agent
- */
-
-
-
-
-interface AgentHandler<O> {
-    output: O;
-}
-
-export type AgentMap = {
-};
+export type AgentMap = {}

package/.pikku/agent/pikku-agent-types.gen.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.2
+ * This file was generated by @pikku/cli@0.12.19
  */
 import {
   CoreAIAgent,
@@ -16,16 +16,22 @@ import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { AIAgentMemoryConfig, AIAgentInput } from '@pikku/core/ai-agent'
 import type { AgentMap } from './pikku-agent-map.gen.d.js'
 
-type AIAgentConfig = Omit<CoreAIAgent<PikkuPermission, PikkuMiddleware>, 'tools' | 'agents' | 'memory'> & {
-  input?: StandardSchemaV1
-  output?: StandardSchemaV1
+type AIAgentConfig<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = Omit<CoreAIAgent<PikkuPermission, PikkuMiddleware>, 'tools' | 'agents' | 'memory' | 'input' | 'output'> & {
+  input?: InputSchema
+  output?: OutputSchema
   memory?: Omit<AIAgentMemoryConfig, 'workingMemory'> & { workingMemory?: StandardSchemaV1 }
   tools?: object[]
-  agents?: AIAgentConfig[]
+  agents?: AIAgentConfig<StandardSchemaV1 | undefined, StandardSchemaV1 | undefined>[]
 }
 
-export const pikkuAIAgent = (
-  agent: AIAgentConfig
+export const pikkuAIAgent = <
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  agent: AIAgentConfig<InputSchema, OutputSchema>
 ) => {
   return agent
 }

package/.pikku/channel/pikku-channel-types.gen.ts

@@ -0,0 +1,177 @@
+/**
+ * This file was generated by @pikku/cli@0.12.19
+ */
+/**
+ * Channel-specific type definitions for tree-shaking optimization
+ */
+
+import { CoreChannel, CorePikkuChannelMiddleware, CorePikkuChannelMiddlewareFactory, wireChannel as wireChannelCore, defineChannelRoutes as defineChannelRoutesCore, addChannelMiddleware as addChannelMiddlewareCore } from '@pikku/core/channel'
+import { AssertHTTPWiringParams } from '@pikku/core/http'
+import type { PikkuFunctionConfig, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware, Services } from '../function/pikku-function-types.gen.js'
+import type { CorePermissionGroup } from '@pikku/core'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
+/**
+ * Helper type to infer the output type from a Standard Schema
+ */
+type InferSchemaOutput<T> = T extends StandardSchemaV1<any, infer Output> ? Output : never
+
+/**
+ * Type definition for WebSocket channels with typed data exchange.
+ * Supports connection, disconnection, and message handling.
+ * Accepts both session-based (PikkuFunction) and sessionless (PikkuFunctionSessionless) functions.
+ *
+ * @template ChannelData - Type of data exchanged through the channel
+ * @template Channel - String literal type for the channel name
+ */
+type ChannelWiring<ChannelData, Channel extends string> = CoreChannel<
+  ChannelData,
+  Channel,
+  PikkuFunctionConfig<void, any, 'channel' | 'session' | 'rpc'>,
+  PikkuFunctionConfig<void, void, 'channel' | 'session' | 'rpc'>,
+  PikkuFunctionConfig<any, any, 'channel' | 'session' | 'rpc'>,
+  PikkuPermission,
+  PikkuMiddleware
+>
+
+/**
+ * Creates a function that handles WebSocket channel connections.
+ * Called when a client connects to a channel.
+ *
+ * @template Out - Output type for connection response
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ */
+export const pikkuChannelConnectionFunc = <Out = unknown>(
+  func:
+    | PikkuFunctionSessionless<void, Out, 'channel' | 'session' | 'rpc'>
+    | PikkuFunctionConfig<void, Out, 'channel' | 'session' | 'rpc'>
+) => {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * Creates a function that handles WebSocket channel disconnections.
+ * Called when a client disconnects from a channel.
+ *
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ */
+export const pikkuChannelDisconnectionFunc = (
+  func:
+    | PikkuFunctionSessionless<void, void, 'channel'>
+    | PikkuFunctionConfig<void, void, 'channel' | 'session' | 'rpc'>
+) => {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * Configuration object for channel functions with Zod schema validation.
+ */
+type PikkuChannelFuncConfigWithSchema<
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = {
+  name?: string
+  tags?: string[]
+  expose?: boolean
+  remote?: boolean
+  func: PikkuFunctionSessionless<
+    InferSchemaOutput<InputSchema>,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'channel' | 'session' | 'rpc'
+  >
+  auth?: boolean
+  permissions?: CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>>
+  middleware?: PikkuMiddleware[]
+  input: InputSchema
+  output?: OutputSchema
+}
+
+/**
+ * Creates a function that handles WebSocket channel messages.
+ * Called when a message is received on a channel.
+ *
+ * Supports two patterns:
+ * 1. Generic types: `pikkuChannelFunc<Input, Output>({ func: ... })`
+ * 2. Zod schemas: `pikkuChannelFunc({ input: z.object(...), func: ... })`
+ *
+ * @template In - Input type for channel messages (inferred from schema if provided)
+ * @template Out - Output type for channel responses (inferred from schema if provided)
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ *
+ * @example
+ * ```typescript
+ * // Pattern 1: Using generic types
+ * const handleMessage = pikkuChannelFunc<{text: string}, {received: boolean}>({
+ *   func: async (_services, { text }) => ({ received: true })
+ * })
+ *
+ * // Pattern 2: Using Zod schemas
+ * const messageInput = z.object({ text: z.string() })
+ * const messageOutput = z.object({ received: z.boolean() })
+ *
+ * const handleMessage = pikkuChannelFunc({
+ *   input: messageInput,
+ *   output: messageOutput,
+ *   func: async (_services, { text }) => ({ received: true })
+ * })
+ * ```
+ */
+export function pikkuChannelFunc<
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuChannelFuncConfigWithSchema<InputSchema, OutputSchema>
+): PikkuFunctionConfig<InferSchemaOutput<InputSchema>, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'channel' | 'session' | 'rpc'>
+export function pikkuChannelFunc<In, Out = unknown>(
+  func:
+    | PikkuFunctionSessionless<In, Out, 'channel' | 'session' | 'rpc'>
+    | PikkuFunctionConfig<In, Out, 'channel' | 'session' | 'rpc'>
+): PikkuFunctionConfig<In, Out, 'channel' | 'session' | 'rpc'>
+export function pikkuChannelFunc(func: any) {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * Registers a WebSocket channel with the Pikku framework.
+ *
+ * @template ChannelData - Type of data associated with the channel
+ * @template Channel - String literal type for the channel name
+ * @param channel - Channel definition with connection, disconnection, and message handlers
+ */
+export const wireChannel = <ChannelData, Channel extends string>(
+  channel: ChannelWiring<ChannelData, Channel> & AssertHTTPWiringParams<ChannelData, Channel>
+) => {
+  wireChannelCore(channel as any)
+}
+
+/**
+ * Type-safe helper for defining channel message routes that can be composed.
+ * Returns the routes record as-is for use with wireChannel's onMessageWiring.
+ *
+ * @template T - Record of channel route handlers
+ * @param routes - The channel routes record
+ * @returns The same routes record (identity function for type safety)
+ */
+export function defineChannelRoutes<T extends Record<string, any>>(routes: T): T {
+  return defineChannelRoutesCore(routes)
+}
+
+export type PikkuChannelMiddleware<RequiredServices extends Services = Services, Event = unknown> = CorePikkuChannelMiddleware<RequiredServices, Event>
+
+export const pikkuChannelMiddleware = <RequiredServices extends Services = Services, Event = unknown>(
+  middleware: PikkuChannelMiddleware<RequiredServices, Event>
+): PikkuChannelMiddleware<RequiredServices, Event> => {
+  return middleware
+}
+
+export const pikkuChannelMiddlewareFactory = <In = any>(
+  factory: CorePikkuChannelMiddlewareFactory<In>
+): CorePikkuChannelMiddlewareFactory<In> => {
+  return factory
+}
+
+export const addChannelMiddleware = (tag: string, middleware: PikkuChannelMiddleware[]) =>
+  addChannelMiddlewareCore(tag, middleware, '@pikku/addon-graph')

package/.pikku/cli/pikku-cli-types.gen.ts

@@ -0,0 +1,105 @@
+/**
+ * This file was generated by @pikku/cli@0.12.19
+ */
+/**
+
+ * CLI-specific type definitions for tree-shaking optimization
+ */
+
+import { CoreCLI, wireCLI as wireCLICore, CorePikkuCLIRender, CoreCLICommandConfig, defineCLICommands as defineCLICommandsCore } from '@pikku/core/cli'
+import type { PikkuFunctionConfig, PikkuMiddleware } from '../function/pikku-function-types.gen.js'
+import type { UserSession } from '../../types/application-types.d.js'
+import type { SingletonServices } from '../../types/application-types.d.js'
+
+
+type Session = UserSession
+
+/**
+ * Type-safe CLI renderer definition that can access your application's services.
+ * Use this to define custom renderers for CLI command output.
+ *
+ * @template Data - The output data type from the CLI command
+ * @template RequiredServices - The services required for this renderer
+ */
+type PikkuCLIRender<Data, RequiredServices extends SingletonServices = SingletonServices> = CorePikkuCLIRender<Data, RequiredServices, Session>
+
+/**
+ * Creates a type-safe CLI renderer with access to your application's singleton services.
+ * The renderer receives the full singleton services and output data to format and display results.
+ *
+ * @template Data - The output data type from the CLI command
+ * @template RequiredServices - The minimum services required for type checking (defaults to SingletonServices)
+ * @param render - Function that receives singleton services and data to render output
+ * @returns A CLI renderer configuration
+ *
+ * @example
+ * ```typescript
+ * const myRenderer = pikkuCLIRender<MyData>(({ logger }, data) => {
+ *   logger.info(data.message)
+ * })
+ * ```
+ */
+export const pikkuCLIRender = <Data, RequiredServices extends SingletonServices = SingletonServices>(
+  render: (services: SingletonServices, data: Data) => void | Promise<void>
+): PikkuCLIRender<Data, RequiredServices> => {
+  return render as any
+}
+
+/**
+ * CLI command configuration with project-specific types.
+ * Uses CoreCLICommandConfig from @pikku/core with local middleware and render types.
+ */
+type CLICommandConfig<Func extends PikkuFunctionConfig<In, Out, 'cli' | 'rpc' | 'session'>, In = any, Out = any, Params extends string = string> = CoreCLICommandConfig<Func, PikkuMiddleware, PikkuCLIRender<any>, Params>
+
+/**
+ * Type definition for CLI applications with commands and global options.
+ *
+ * @template Commands - Type describing the command structure
+ * @template GlobalOptions - Type for global CLI options
+ */
+type CLIWiring<Commands extends Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender<any>, any>>, GlobalOptions> = CoreCLI<Commands, GlobalOptions, PikkuMiddleware, PikkuCLIRender<any>>
+
+/**
+ * Registers a CLI application with the Pikku framework.
+ * Creates command-line interfaces with type-safe commands and options.
+ *
+ * @template Commands - Type describing the command structure
+ * @template GlobalOptions - Type for global CLI options
+ * @param cli - CLI definition with program name, commands, and global options
+ */
+export const wireCLI = <Commands extends Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender<any>, any>>, GlobalOptions>(
+  cli: CLIWiring<Commands, GlobalOptions>
+) => {
+  wireCLICore(cli as any)
+}
+
+/**
+ * Creates a CLI command definition with automatic option inference from the function's input type.
+ * This allows TypeScript to automatically derive CLI options from the function signature.
+ *
+ * @template FuncConfig - The Pikku function config type
+ * @template Params - The parameters string literal type
+ * @param config - CLI command configuration
+ * @returns CLI command configuration with inferred types
+ */
+export const pikkuCLICommand = <
+  FuncConfig extends PikkuFunctionConfig<any, any, 'cli' | 'rpc' | 'session'>,
+  Params extends string
+>(
+  config: CLICommandConfig<FuncConfig, any, any, Params>
+): CoreCLICommandConfig<FuncConfig, PikkuMiddleware, PikkuCLIRender<any>, string> => {
+  return config as any
+}
+
+/**
+ * Type-safe helper for defining CLI commands that can be composed and spread into wireCLI.
+ *
+ * @template T - Record of CLI command configurations
+ * @param commands - The CLI commands record
+ * @returns The same commands record (identity function for type safety)
+ */
+export const defineCLICommands = <T extends Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender<any>, any>>>(
+  commands: T
+): T => {
+  return defineCLICommandsCore(commands as any) as T
+}