@pikku/cli 0.9.15 → 0.10.0

package/src/functions/wirings/rpc/pikku-command-rpc-map.ts

@@ -0,0 +1,48 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
+import { serializeTypedRPCMap } from './serialize-typed-rpc-map.js'
+
+export const pikkuRPCInternalMap: any = pikkuSessionlessFunc<void, void>({
+  func: async ({ logger, config, getInspectorState }) => {
+    const { functions, rpc } = await getInspectorState()
+    const { rpcInternalMapDeclarationFile, packageMappings } = config
+
+    const content = serializeTypedRPCMap(
+      rpcInternalMapDeclarationFile,
+      packageMappings,
+      functions.typesMap,
+      functions.meta,
+      rpc.internalMeta
+    )
+    await writeFileInDir(logger, rpcInternalMapDeclarationFile, content)
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Creating RPC internal map',
+      commandEnd: 'Created RPC internal map',
+    }),
+  ],
+})
+
+export const pikkuRPCExposedMap: any = pikkuSessionlessFunc<void, void>({
+  func: async ({ logger, config, getInspectorState }) => {
+    const { functions, rpc } = await getInspectorState()
+    const { rpcMapDeclarationFile, packageMappings } = config
+
+    const content = serializeTypedRPCMap(
+      rpcMapDeclarationFile,
+      packageMappings,
+      functions.typesMap,
+      functions.meta,
+      rpc.exposedMeta
+    )
+    await writeFileInDir(logger, rpcMapDeclarationFile, content)
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Creating RPC external map',
+      commandEnd: 'Created RPC external map',
+    }),
+  ],
+})

package/src/functions/wirings/rpc/pikku-command-rpc.ts

@@ -0,0 +1,26 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
+
+export const pikkuRPC: any = pikkuSessionlessFunc<void, boolean>({
+  func: async ({ logger, config, getInspectorState }) => {
+    const { rpc } = await getInspectorState()
+    const { rpcInternalWiringMetaFile } = config
+
+    if (rpc.internalFiles.size > 0) {
+      await writeFileInDir(
+        logger,
+        rpcInternalWiringMetaFile,
+        `import { pikkuState } from '@pikku/core'\npikkuState('rpc', 'meta', ${JSON.stringify(rpc.internalMeta, null, 2)})`
+      )
+      return true
+    }
+    return false
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Finding RPCs tasks',
+      commandEnd: 'Found RPCs',
+    }),
+  ],
+})

package/src/{wirings → functions/wirings}/rpc/serialize-typed-rpc-map.ts

@@ -1,7 +1,7 @@
-import { serializeImportMap } from '../../serialize-import-map.js'
+import { serializeImportMap } from '../../../utils/serialize-import-map.js'
 import { TypesMap } from '@pikku/inspector'
 import { FunctionsMeta } from '@pikku/core'
-import { generateCustomTypes } from '../../utils.js'
+import { generateCustomTypes } from '../../../utils/custom-types-generator.js'
 
 export const serializeTypedRPCMap = (
   relativeToPath: string,

package/src/functions/wirings/scheduler/pikku-command-scheduler-types.ts

@@ -0,0 +1,25 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
+import { serializeSchedulerTypes } from './serialize-scheduler-types.js'
+
+export const pikkuSchedulerTypes: any = pikkuSessionlessFunc<void, void>({
+  func: async ({ logger, config }) => {
+    const { schedulersTypesFile, functionTypesFile, packageMappings } = config
+
+    const functionTypesImportPath = getFileImportRelativePath(
+      schedulersTypesFile,
+      functionTypesFile,
+      packageMappings
+    )
+    const content = serializeSchedulerTypes(functionTypesImportPath)
+    await writeFileInDir(logger, schedulersTypesFile, content)
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Creating cheduler types',
+      commandEnd: 'Created scheduler types',
+    }),
+  ],
+})

package/src/functions/wirings/scheduler/pikku-command-scheduler.ts

@@ -0,0 +1,41 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { serializeFileImports } from '../../../utils/file-imports-serializer.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
+import { serializeSchedulerMeta } from './serialize-scheduler-meta.js'
+
+export const pikkuScheduler: any = pikkuSessionlessFunc<
+  void,
+  boolean | undefined
+>({
+  func: async ({ logger, config, getInspectorState }) => {
+    const visitState = await getInspectorState()
+    const { schedulersWiringFile, schedulersWiringMetaFile, packageMappings } =
+      config
+    const { scheduledTasks } = visitState
+
+    await writeFileInDir(
+      logger,
+      schedulersWiringMetaFile,
+      serializeSchedulerMeta(scheduledTasks.meta)
+    )
+    await writeFileInDir(
+      logger,
+      schedulersWiringFile,
+      serializeFileImports(
+        'addScheduledTasks',
+        schedulersWiringFile,
+        scheduledTasks.files,
+        packageMappings
+      )
+    )
+
+    return true
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Finding Scheduled tasks',
+      commandEnd: 'Found Scheduled tasks',
+    }),
+  ],
+})

package/src/functions/wirings/scheduler/serialize-scheduler-types.ts

@@ -0,0 +1,28 @@
+/**
+ * Generates type definitions for scheduler wirings
+ */
+export const serializeSchedulerTypes = (functionTypesImportPath: string) => {
+  return `/**
+ * Scheduler-specific type definitions for tree-shaking optimization
+ */
+
+import { CoreScheduledTask, wireScheduler as wireSchedulerCore } from '@pikku/core/scheduler'
+import type { PikkuFunctionConfig, PikkuMiddleware } from '${functionTypesImportPath}'
+
+/**
+ * Type definition for scheduled tasks that run at specified intervals.
+ * These are sessionless functions that execute based on cron expressions.
+ */
+type SchedulerWiring = CoreScheduledTask<PikkuFunctionConfig<void, void>, PikkuMiddleware>
+
+/**
+ * Registers a scheduled task with the Pikku framework.
+ * Tasks run based on cron expressions and are sessionless.
+ *
+ * @param task - Scheduled task definition with cron expression and handler
+ */
+export const wireScheduler = (task: SchedulerWiring) => {
+  wireSchedulerCore(task as any) // TODO
+}
+`
+}

package/src/middleware/log-command-info-and-time.ts

@@ -0,0 +1,35 @@
+import type { Services } from '../../types/application-types.js'
+import type { PikkuInteraction } from '@pikku/core'
+
+// Middleware type for CLI
+type PikkuMiddleware = (
+  services: Services,
+  interaction: PikkuInteraction,
+  next: () => Promise<void>
+) => Promise<void>
+
+export interface LogCommandInfoOptions {
+  commandStart: string
+  commandEnd: string
+}
+
+/**
+ * Middleware to log command execution timing and status
+ * Replaces the logCommandInfoAndTime wrapper function
+ */
+export const logCommandInfoAndTime = ({
+  commandStart,
+  commandEnd,
+}: LogCommandInfoOptions): PikkuMiddleware => {
+  return async ({ logger }, _interaction, next) => {
+    // Log start
+    const start = Date.now()
+    logger.info(`• ${commandStart}...`)
+
+    // Execute the function
+    await next()
+
+    // Log completion
+    logger.info(`✓ ${commandEnd} in ${Date.now() - start}ms.`)
+  }
+}

package/src/services/cli-logger-forwarder.service.ts

@@ -0,0 +1,90 @@
+import { Logger, LogLevel } from '@pikku/core'
+import { PikkuChannel } from '@pikku/core/channel'
+import { ErrorCode } from '@pikku/inspector'
+
+/**
+ * Log message structure sent through the channel
+ */
+export interface ForwardedLogMessage {
+  message: string
+  level: 'trace' | 'debug' | 'info' | 'warn' | 'error'
+  type?: string
+}
+
+/**
+ * A logger implementation that forwards log messages to a CLI channel
+ * instead of logging to console directly.
+ */
+export class CLILoggerForwarder implements Logger {
+  private level: LogLevel = LogLevel.info
+
+  constructor(
+    private logger: Logger,
+    private channel: PikkuChannel<unknown, any>
+  ) {}
+
+  setLevel(level: LogLevel): void {
+    this.level = level
+  }
+
+  private log(
+    level: ForwardedLogMessage['level'],
+    logLevel: LogLevel,
+    messageOrObj: string | Record<string, any> | Error,
+    type?: string
+  ) {
+    if (this.level > logLevel) return
+
+    let message: string
+
+    if (messageOrObj instanceof Error) {
+      this.logger.error(messageOrObj)
+      message = messageOrObj.message
+    } else if (typeof messageOrObj === 'object') {
+      if (
+        'message' in messageOrObj &&
+        typeof messageOrObj.message === 'string'
+      ) {
+        message = messageOrObj.message
+        type = type || (messageOrObj.type as string)
+      } else {
+        message = JSON.stringify(messageOrObj)
+      }
+    } else {
+      message = messageOrObj
+    }
+
+    this.channel.send({ message, level, type })
+  }
+
+  info(messageOrObj: string | Record<string, any>, ..._meta: any[]) {
+    this.log('info', LogLevel.info, messageOrObj)
+  }
+
+  error(messageOrObj: string | Record<string, any> | Error, ..._meta: any[]) {
+    this.log('error', LogLevel.error, messageOrObj)
+  }
+
+  warn(messageOrObj: string | Record<string, any>, ..._meta: any[]) {
+    this.log('warn', LogLevel.warn, messageOrObj)
+  }
+
+  debug(message: string, ..._meta: any[]) {
+    this.log('debug', LogLevel.debug, message)
+  }
+
+  trace(message: string, ..._meta: any[]) {
+    this.log('trace', LogLevel.trace, message)
+  }
+
+  critical(code: ErrorCode, message: string) {
+    const url = `https://pikku.dev/docs/cli-errors/${code.toLowerCase()}`
+    const formattedMessage = `[${code}] ${message}\n  → ${url}`
+    this.error(formattedMessage)
+  }
+
+  hasCriticalErrors(): boolean {
+    // The underlying logger (CLILogger) tracks critical errors
+    return (this.logger as any).hasCriticalErrors?.() ?? false
+  }
+}

package/src/services/cli-logger.service.ts

@@ -0,0 +1,93 @@
+import chalk from 'chalk'
+import { Logger, LogLevel } from '@pikku/core'
+import { ErrorCode } from '@pikku/inspector'
+
+const logo = `
+ ______ _ _     _
+(_____ (_) |   | |
+ _____) )| |  _| |  _ _   _
+|  ____/ | |_/ ) |_/ ) | | |
+| |    | |  _ (|  _ (|  _ (| |_| |
+|_|    |_|_| _)_| _)____/
+`
+
+const BASE_ERROR_URL = 'https://pikku.dev/errors'
+
+export class CLILogger implements Logger {
+  private silent: boolean
+  private level: LogLevel = LogLevel.info
+  private criticalErrors: string[] = []
+
+  constructor({
+    logLogo,
+    silent = false,
+  }: {
+    logLogo: boolean
+    silent?: boolean
+  }) {
+    this.silent = silent
+    if (logLogo && !silent) {
+      this.logPikkuLogo()
+    }
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level
+  }
+
+  info(message: string | { message: string; type?: string }) {
+    if (this.level > LogLevel.info || this.silent) return
+
+    let c = chalk.blue
+    if (typeof message === 'object') {
+      if (message.type === 'success') {
+        c = chalk.green
+      } else if (message.type === 'timing') {
+        c = chalk.gray
+      }
+    }
+    console.log(c(typeof message === 'string' ? message : message.message))
+  }
+
+  error(message: string) {
+    if (this.level > LogLevel.error) return
+    console.error(chalk.red(message))
+  }
+
+  warn(message: string) {
+    if (this.level > LogLevel.warn) return
+    console.error(chalk.yellow(message))
+  }
+
+  debug(message: string) {
+    if (this.level > LogLevel.debug || this.silent) return
+    console.log(chalk.gray(message))
+  }
+
+  critical(code: ErrorCode, message: string) {
+    const url = `${BASE_ERROR_URL}/${code.toLowerCase()}`
+    const formattedMessage = `[${code}] ${message}\n  → ${url}`
+    this.criticalErrors.push(formattedMessage)
+    console.error(chalk.red.bold(formattedMessage))
+  }
+
+  hasCriticalErrors(): boolean {
+    return this.criticalErrors.length > 0
+  }
+
+  private logPikkuLogo() {
+    this.primary(logo)
+    // // When running from dist/, __filename is dist/src/services/cli-logger.service.js
+    // // So we need to go up 3 levels: dist/src/services -> dist/src -> dist -> package.json
+    // const packageJson = JSON.parse(
+    //   readFileSync(`${dirname(__filename)}/../../../package.json`, 'utf-8')
+    // )
+    // this.primary(`⚙️  Welcome to the Pikku CLI (v${packageJson.version})\n`)
+  }
+
+  private primary(message: string) {
+    if (!this.silent) {
+      console.log(chalk.green(message))
+    }
+  }
+}

package/src/services.ts

@@ -0,0 +1,240 @@
+import type {
+  Config,
+  Services,
+  SingletonServices,
+  UserSession,
+} from '../types/application-types.js'
+import {
+  CreateConfig,
+  CreateSessionServices,
+  CreateSingletonServices,
+} from '@pikku/core'
+import { pikkuCLIRender } from '@pikku/core/cli'
+import { LocalVariablesService } from '@pikku/core/services'
+import { CLILogger } from './services/cli-logger.service.js'
+import { getPikkuCLIConfig } from './utils/pikku-cli-config.js'
+import {
+  inspect,
+  InspectorState,
+  InspectorFilters,
+  serializeInspectorState,
+  deserializeInspectorState,
+  filterInspectorState,
+} from '@pikku/inspector'
+import { glob } from 'tinyglobby'
+import path from 'path'
+import { PikkuCLIConfig } from '../types/config.js'
+import {
+  CLILoggerForwarder,
+  ForwardedLogMessage,
+} from './services/cli-logger-forwarder.service.js'
+import { readFile, writeFile } from 'fs/promises'
+
+const logger = new CLILogger({ logLogo: true, silent: false })
+
+/**
+ * Parse a comma-separated string or array into an array of trimmed, non-empty strings
+ * Returns undefined if the input is empty/undefined or results in an empty array
+ */
+function parseCommaSeparated(
+  value: string | string[] | undefined
+): string[] | undefined {
+  if (!value) return undefined
+
+  // If already an array, flatten and split any comma-separated values
+  if (Array.isArray(value)) {
+    const flattened = value
+      .flatMap((item) => item.split(','))
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0)
+    return flattened.length > 0 ? flattened : undefined
+  }
+
+  // If string, split by comma
+  const parsed = value
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0)
+
+  return parsed.length > 0 ? parsed : undefined
+}
+
+/**
+ * Parse CLI filter arguments into InspectorFilters format
+ */
+function parseCLIFilters(data: any): InspectorFilters {
+  const filters: InspectorFilters = {}
+
+  if (data.filters) {
+    return JSON.parse(data.filters)
+  }
+
+  // Parse each filter type from CLI arguments
+  const names = parseCommaSeparated(data.names)
+  const tags = parseCommaSeparated(data.tags)
+  const types = parseCommaSeparated(data.types)
+  const directories = parseCommaSeparated(data.directories)
+  const httpRoutes = parseCommaSeparated(data.httpRoutes)
+  const httpMethods = parseCommaSeparated(data.httpMethods)
+
+  // Only include non-undefined values in the result
+  if (names) filters.names = names
+  if (tags) filters.tags = tags
+  if (types) filters.types = types
+  if (directories) filters.directories = directories
+  if (httpRoutes) filters.httpRoutes = httpRoutes
+  if (httpMethods) filters.httpMethods = httpMethods
+
+  return filters
+}
+
+/**
+ * Default CLI renderer that logs output using the logger
+ */
+export const defaultCLIRenderer = pikkuCLIRender<
+  ForwardedLogMessage,
+  SingletonServices
+>((_services, data) => {
+  if (data) {
+    logger[data.level]({ message: data.message, type: data.type })
+  }
+})
+
+/**
+ * Client-safe CLI renderer that outputs to console (no service dependencies)
+ * This renderer can be used in CLI-over-channel clients
+ */
+export const clientCLIRenderer = pikkuCLIRender<ForwardedLogMessage>(
+  (_services, data) => {
+    if (data) {
+      // Simple console output without service dependencies
+      const prefix = data.type ? `[${data.type}] ` : ''
+      console.log(`${prefix}${data.message}`)
+    }
+  }
+)
+
+export const createConfig: CreateConfig<Config, [PikkuCLIConfig]> = async (
+  _variablesService,
+  data
+) => {
+  const cliConfig = await getPikkuCLIConfig(logger, data.configFile, [], true)
+
+  // Load inspector state from file if stateInput is provided
+  let preloadedInspectorState: Omit<InspectorState, 'typesLookup'> | undefined =
+    undefined
+
+  if (data.stateInput) {
+    try {
+      logger.info(`Loading inspector state from ${data.stateInput}`)
+      const stateJson = await readFile(data.stateInput, 'utf-8')
+      const serializedState = JSON.parse(stateJson)
+      preloadedInspectorState = deserializeInspectorState(serializedState)
+      logger.info(`Inspector state loaded successfully`)
+    } catch (error: any) {
+      logger.error(
+        `Failed to load inspector state from ${data.stateInput}: ${error.message}`
+      )
+      throw error
+    }
+  }
+
+  return {
+    ...cliConfig,
+    ...data,
+    filters: parseCLIFilters(data),
+    preloadedInspectorState,
+  }
+}
+
+/**
+ * Singleton services factory for the Pikku CLI
+ * This function creates the singleton services used by the CLI and is created once on start.
+ */
+export const createSingletonServices: CreateSingletonServices<
+  Config,
+  SingletonServices
+> = async (config) => {
+  const {
+    rootDir,
+    srcDirectories,
+    filters,
+    preloadedInspectorState,
+    stateOutput,
+  } = config
+  const variables = new LocalVariablesService()
+
+  // Store unfiltered state
+  let unfilteredState:
+    | InspectorState
+    | Omit<InspectorState, 'typesLookup'>
+    | undefined = preloadedInspectorState
+
+  const getInspectorState = async (refresh: boolean = false) => {
+    // Get or refresh the unfiltered state
+    if (!unfilteredState || refresh) {
+      // Run inspector WITHOUT filters to get full state
+      const wiringFiles = (
+        await Promise.all(
+          srcDirectories.map((dir) =>
+            glob(`${path.join(rootDir, dir)}/**/*.ts`)
+          )
+        )
+      ).flat()
+      unfilteredState = await inspect(logger, wiringFiles, {
+        // NO filters here - inspector returns full unfiltered state
+        types: {
+          configFileType: config.configFile,
+          userSessionType: config.userSessionType,
+          singletonServicesFactoryType: config.singletonServicesFactoryType,
+          sessionServicesFactoryType: config.sessionServicesFactoryType,
+        },
+      })
+
+      // Save unfiltered inspector state to file if stateOutput is provided
+      if (stateOutput && 'typesLookup' in unfilteredState) {
+        try {
+          logger.info(`Saving inspector state to ${stateOutput}`)
+          const serialized = serializeInspectorState(unfilteredState)
+          await writeFile(
+            stateOutput,
+            JSON.stringify(serialized, null, 2),
+            'utf-8'
+          )
+          logger.info(`Inspector state saved successfully`)
+        } catch (error: any) {
+          logger.error(
+            `Failed to save inspector state to ${stateOutput}: ${error.message}`
+          )
+          // Don't throw - state saving is optional/nice-to-have
+        }
+      }
+    }
+
+    // Apply filters as a post-processing step
+    const filteredState = filterInspectorState(unfilteredState, filters, logger)
+
+    return filteredState as InspectorState
+  }
+
+  return {
+    config,
+    logger,
+    variables,
+    getInspectorState,
+  }
+}
+
+export const createSessionServices: CreateSessionServices<
+  SingletonServices,
+  Services,
+  UserSession
+> = async ({ logger }, { cli, channel }) => {
+  const vChannel = cli ? cli.channel : channel
+  if (!vChannel) {
+    throw new Error('No channel provided for CLI services')
+  }
+  return {
+    logger: new CLILoggerForwarder(logger, vChannel),
+  }
+}

package/src/utils/check-required-types.ts

@@ -0,0 +1,53 @@
+import { FilesAndMethodsErrors } from '@pikku/inspector'
+
+export type RequiredTypes = Partial<{
+  config: boolean
+  sessionServiceType: boolean
+  singletonServicesType: boolean
+  userSessionType: boolean
+  singletonServicesFactory: boolean
+  sessionServicesFactory: boolean
+}>
+
+export const checkRequiredTypes = (
+  errors: FilesAndMethodsErrors,
+  requires: RequiredTypes = {}
+): void => {
+  // Only throw if there are errors AND we require those types
+  const hasRequiredErrors = Array.from(errors.keys()).some((message) => {
+    if (requires.config && message.includes('CoreConfig')) return true
+    if (requires.sessionServiceType && message.includes('CoreServices'))
+      return true
+    if (
+      requires.singletonServicesType &&
+      message.includes('CoreSingletonServices')
+    )
+      return true
+    if (requires.userSessionType && message.includes('CoreUserSession'))
+      return true
+    if (
+      requires.singletonServicesFactory &&
+      message.includes('CreateSingletonServices')
+    )
+      return true
+    if (
+      requires.sessionServicesFactory &&
+      message.includes('CreateSessionServices')
+    )
+      return true
+    return false
+  })
+
+  if (hasRequiredErrors) {
+    const result: string[] = ['Found errors:']
+    errors.forEach((filesAndMethods, message) => {
+      result.push(`- ${message}`)
+      filesAndMethods.forEach((methods, file) => {
+        result.push(
+          `\t* methods: ${methods.map(({ variable, type }) => `${variable}: ${type}`).join(', ')}`
+        )
+      })
+    })
+    throw new Error(result.join('\n'))
+  }
+}