@pikku/cli 0.11.3 → 0.12.0

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

@@ -1,101 +0,0 @@
-/**
- * Generates type definitions for CLI wirings
- */
-export const serializeCLITypes = (
-  functionTypesImportPath: string,
-  userSessionTypeImport: string,
-  userSessionTypeName: string,
-  singletonServicesTypeImport: string,
-  singletonServicesTypeName: string
-) => {
-  return `/**
-
- * CLI-specific type definitions for tree-shaking optimization
- */
-
-import { CoreCLI, wireCLI as wireCLICore, CorePikkuCLIRender, CoreCLICommandConfig } from '@pikku/core/cli'
-import type { PikkuFunctionConfig, PikkuMiddleware } from '${functionTypesImportPath}'
-${userSessionTypeImport}
-${singletonServicesTypeImport}
-
-${singletonServicesTypeName !== 'SingletonServices' ? `type SingletonServices = ${singletonServicesTypeName}` : ''}
-${userSessionTypeName !== 'Session' ? `type Session = ${userSessionTypeName}` : ''}
-
-/**
- * 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
-}
-`
-}

package/src/functions/wirings/cli/serialize-local-cli-bootstrap.ts

@@ -1,80 +0,0 @@
-import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
-import { Config } from '../../../../types/application-types.js'
-
-/**
- * Serializes the local (in-program) CLI bootstrap code
- */
-export function serializeLocalCLIBootstrap(
-  programName: string,
-  _programMeta: any,
-  bootstrapFile: string,
-  config: Config,
-  pikkuConfigFactory: { file: string; variable: string },
-  singletonServicesFactory: { file: string; variable: string },
-  wireServicesFactory: { file: string; variable: string }
-): string {
-  const capitalizedName =
-    programName.charAt(0).toUpperCase() + programName.slice(1).replace(/-/g, '')
-
-  // Get relative import paths
-  const pikkuConfigPath = getFileImportRelativePath(
-    bootstrapFile,
-    pikkuConfigFactory.file,
-    config.packageMappings
-  )
-  const singletonServicesPath = getFileImportRelativePath(
-    bootstrapFile,
-    singletonServicesFactory.file,
-    config.packageMappings
-  )
-  const wireServicesPath = getFileImportRelativePath(
-    bootstrapFile,
-    wireServicesFactory.file,
-    config.packageMappings
-  )
-  const cliBootstrapPath = getFileImportRelativePath(
-    bootstrapFile,
-    config.bootstrapFile,
-    config.packageMappings
-  )
-
-  return `
-import { executeCLI, CLIError } from '@pikku/core/cli'
-import { ${pikkuConfigFactory.variable} as createConfig } from '${pikkuConfigPath}'
-import { ${singletonServicesFactory.variable} as createSingletonServices } from '${singletonServicesPath}'
-import { ${wireServicesFactory.variable} as createWireServices } from '${wireServicesPath}'
-import '${cliBootstrapPath}'
-
-/**
- * ${capitalizedName} CLI function
- * Handles command line arguments and executes the appropriate function
- */
-export async function ${capitalizedName}CLI(args: string[]): Promise<void> {
-  try {
-    await executeCLI({
-      programName: '${programName}',
-      args: args || process.argv.slice(2),
-      createConfig,
-      createSingletonServices,
-      createWireServices,
-    })
-  } catch (error) {
-    if (error instanceof CLIError) {
-      process.exit(error.exitCode)
-    }
-    throw error
-  }
-}
-
-// Export as default for easy importing
-export default ${capitalizedName}CLI
-
-// For direct execution (if this file is run directly)
-if (import.meta.url === \`file://\${process.argv[1]}\`) {
-  ${capitalizedName}CLI(process.argv.slice(2)).catch(error => {
-    console.error('Fatal error:', error.message)
-    process.exit(1)
-  })
-}
-`
-}

package/src/functions/wirings/fetch/index.ts

@@ -1,36 +0,0 @@
-import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
-import { serializeFetchWrapper } from '../http/serialize-fetch-wrapper.js'
-import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
-import { writeFileInDir } from '../../../utils/file-writer.js'
-import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
-
-export const pikkuFetch: any = pikkuSessionlessFunc<void, void>({
-  func: async ({ logger, config }) => {
-    const { fetchFile, httpMapDeclarationFile, packageMappings } = config
-
-    // If fetchFile is not set, clean up any existing file and return
-    if (!fetchFile) {
-      logger.info({
-        message:
-          "Skipping generating fetch wrapper since fetchFile isn't set in the pikku config.",
-        type: 'skip',
-      })
-      return
-    }
-
-    const routesMapDeclarationPath = getFileImportRelativePath(
-      fetchFile,
-      httpMapDeclarationFile,
-      packageMappings
-    )
-
-    const content = [serializeFetchWrapper(routesMapDeclarationPath)]
-    await writeFileInDir(logger, fetchFile, content.join('\n'))
-  },
-  middleware: [
-    logCommandInfoAndTime({
-      commandStart: 'Generating fetch wrapper',
-      commandEnd: 'Generated fetch wrapper',
-    }),
-  ],
-})

package/src/functions/wirings/forge/pikku-command-forge-nodes.ts

@@ -1,135 +0,0 @@
-import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
-import { ErrorCode } from '@pikku/inspector'
-import { writeFileInDir } from '../../../utils/file-writer.js'
-import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
-import { readFile } from 'fs/promises'
-import { join, isAbsolute } from 'path'
-import {
-  stripVerboseFields,
-  hasVerboseFields,
-} from '../../../utils/strip-verbose-meta.js'
-
-/**
- * Load and sanitize an SVG icon file.
- * Returns the SVG content as a string, or undefined if not found.
- */
-const loadIcon = async (
-  iconPath: string | undefined,
-  rootDir: string,
-  logger: any
-): Promise<string | undefined> => {
-  if (!iconPath) return undefined
-
-  // Resolve the full path to the icon
-  const fullPath = isAbsolute(iconPath) ? iconPath : join(rootDir, iconPath)
-
-  try {
-    const content = await readFile(fullPath, 'utf-8')
-
-    // Basic SVG validation - must start with <svg
-    const trimmed = content.trim()
-    if (!trimmed.startsWith('<svg') && !trimmed.startsWith('<?xml')) {
-      logger.warn(`Icon file is not a valid SVG: ${fullPath}`)
-      return undefined
-    }
-
-    // Return the sanitized SVG (remove XML declaration if present)
-    return trimmed.replace(/<\?xml[^?]*\?>\s*/g, '').trim()
-  } catch (e) {
-    logger.warn(`Could not load icon: ${fullPath}`)
-    return undefined
-  }
-}
-
-export const pikkuForgeNodes: any = pikkuSessionlessFunc<
-  void,
-  boolean | undefined
->({
-  func: async ({ logger, config, getInspectorState }) => {
-    const { forgeNodes, forgeCredentials } = await getInspectorState()
-    const { forgeNodesMetaJsonFile, forge, rootDir } = config
-
-    const hasNodes = Object.keys(forgeNodes.meta).length > 0
-    const hasCredentials = Object.keys(forgeCredentials.meta).length > 0
-
-    // Only generate if there are forge nodes or credentials
-    if (!hasNodes && !hasCredentials) {
-      return undefined
-    }
-
-    // Validate categories if configured
-    const allowedCategories = forge?.node?.categories
-    if (allowedCategories && allowedCategories.length > 0) {
-      for (const [name, meta] of Object.entries(forgeNodes.meta) as [
-        string,
-        any,
-      ][]) {
-        if (!allowedCategories.includes(meta.category)) {
-          logger.critical(
-            ErrorCode.INVALID_VALUE,
-            `Forge node '${name}' has invalid category '${meta.category}'. ` +
-              `Allowed categories: ${allowedCategories.join(', ')}`
-          )
-        }
-      }
-    }
-
-    // Build the output metadata - remove per-node icon field
-    const outputMeta: Record<string, any> = {}
-    for (const [name, meta] of Object.entries(forgeNodes.meta) as [
-      string,
-      any,
-    ][]) {
-      // Remove icon from node meta - only package-level icon is used
-      const { icon: _icon, ...nodeMetaWithoutIcon } = meta
-      outputMeta[name] = nodeMetaWithoutIcon
-    }
-
-    // Load package-level icon
-    const packageIcon = await loadIcon(forge?.node?.icon, rootDir, logger)
-
-    const metaData = {
-      nodes: outputMeta,
-      credentials: forgeCredentials.meta,
-      package: {
-        displayName: forge?.node?.displayName,
-        description: forge?.node?.description,
-        icon: packageIcon,
-        categories: forge?.node?.categories,
-      },
-    }
-
-    if (forgeNodesMetaJsonFile) {
-      // Write minimal JSON (runtime-only fields)
-      const minimalMeta = stripVerboseFields(metaData)
-      await writeFileInDir(
-        logger,
-        forgeNodesMetaJsonFile,
-        JSON.stringify(minimalMeta, null, 2),
-        { ignoreModifyComment: true }
-      )
-
-      // Write verbose JSON only if it has additional fields
-      if (hasVerboseFields(metaData)) {
-        const verbosePath = forgeNodesMetaJsonFile.replace(
-          /\.gen\.json$/,
-          '-verbose.gen.json'
-        )
-        await writeFileInDir(
-          logger,
-          verbosePath,
-          JSON.stringify(metaData, null, 2),
-          { ignoreModifyComment: true }
-        )
-      }
-    }
-
-    return true
-  },
-  middleware: [
-    logCommandInfoAndTime({
-      commandStart: 'Generating Forge nodes metadata',
-      commandEnd: 'Generated Forge nodes metadata',
-    }),
-  ],
-})

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

@@ -1,38 +0,0 @@
-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 { serializeForgeTypes } from './serialize-forge-types.js'
-
-export const pikkuForgeTypes: any = pikkuSessionlessFunc<void, void>({
-  func: async ({ logger, config }) => {
-    const {
-      forgeTypesFile,
-      rpcInternalMapDeclarationFile,
-      packageMappings,
-      forge,
-    } = config
-
-    // Get the import path for the RPC map declaration file
-    // The declaration file ends in .d.ts, but we need to import from .js
-    // getFileImportRelativePath converts .ts -> .js, so .d.ts -> .d.js
-    // We need to remove the extra .d extension
-    let rpcMapImportPath = getFileImportRelativePath(
-      forgeTypesFile,
-      rpcInternalMapDeclarationFile,
-      packageMappings
-    )
-    // Fix: .d.ts files should be imported as .js (TypeScript resolves types from .d.ts)
-    rpcMapImportPath = rpcMapImportPath.replace('.d.js', '.js')
-
-    const categories = forge?.node?.categories
-    const content = serializeForgeTypes(rpcMapImportPath, categories)
-    await writeFileInDir(logger, forgeTypesFile, content)
-  },
-  middleware: [
-    logCommandInfoAndTime({
-      commandStart: 'Creating Forge types',
-      commandEnd: 'Created Forge types',
-    }),
-  ],
-})

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

@@ -1,94 +0,0 @@
-/**
- * Generates type definitions for Forge wirings with typed category and RPC validation
- */
-export const serializeForgeTypes = (
-  rpcMapImportPath: string,
-  categories: string[] | undefined
-) => {
-  // Generate category union type - 'never' if no categories configured
-  const categoryType = categories?.length
-    ? categories.map((c) => `'${c}'`).join(' | ')
-    : 'never'
-
-  return `/**
- * Forge-specific type definitions for typed wireForgeNode and wireForgeCredential
- */
-
-import { wireForgeNode as wireForgeNodeCore, wireForgeCredential as wireForgeCredentialCore } from '@pikku/core/forge-node'
-import type { CoreForgeNode, CoreForgeCredential } from '@pikku/core/forge-node'
-import type { FlattenedRPCMap } from '${rpcMapImportPath}'
-
-/**
- * Valid category values for forge nodes.
- * ${categories?.length ? `Configured categories: ${categories.join(', ')}` : 'No categories configured - wireForgeNode cannot be used until forge.node.categories is defined in pikku.config.json.'}
- */
-export type ForgeCategory = ${categoryType}
-
-/**
- * Valid RPC names that can be used with forge nodes.
- * These are derived from the FlattenedRPCMap which includes both local and external package RPCs.
- */
-export type ForgeRPCName = keyof FlattenedRPCMap
-
-/**
- * Typed forge node configuration.
- * Validates that category and rpc are valid values.
- */
-export type TypedForgeNode = Omit<CoreForgeNode, 'category' | 'rpc'> & {
-  /** Grouping category (validated against forge.node.categories in config) */
-  category: ForgeCategory
-  /** RPC name to call when node executes (must be a valid RPC name) */
-  rpc: ForgeRPCName
-}
-
-/**
- * Registers a Forge node with validated category and RPC.
- *
- * @param config - Forge node configuration with typed category and rpc
- *
- * @example
- * \`\`\`typescript
- * wireForgeNode({
- *   name: 'send-email',
- *   displayName: 'Send Email',
- *   category: 'Communication', // Must be in forge.node.categories
- *   type: 'action',
- *   rpc: 'sendEmail', // Must be a valid RPC name
- *   description: 'Sends an email to a recipient'
- * })
- * \`\`\`
- */
-export const wireForgeNode = (config: TypedForgeNode): void => {
-  wireForgeNodeCore(config as CoreForgeNode)
-}
-
-/**
- * Registers a Forge credential definition.
- * Credentials define secrets/API keys required by the package.
- *
- * @template T - Zod schema type for the credential structure
- * @param config - Forge credential configuration
- *
- * @example
- * \`\`\`typescript
- * import { z } from 'zod'
- *
- * const apiCredentials = z.object({
- *   apiKey: z.string().describe('API key for authentication'),
- *   apiSecret: z.string().describe('API secret')
- * })
- *
- * wireForgeCredential({
- *   name: 'example-api',
- *   displayName: 'Example API Credentials',
- *   description: 'Credentials for the example external API',
- *   secretId: 'EXAMPLE_API_CREDENTIALS',
- *   schema: apiCredentials
- * })
- * \`\`\`
- */
-export const wireForgeCredential = <T>(config: CoreForgeCredential<T>): void => {
-  wireForgeCredentialCore(config)
-}
-`
-}

package/src/functions/wirings/functions/pikku-command-function-types-split.ts

@@ -1,61 +0,0 @@
-import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
-import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
-import { checkRequiredTypes } from '../../../utils/check-required-types.js'
-import { writeFileInDir } from '../../../utils/file-writer.js'
-import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
-import { serializeFunctionTypes } from './serialize-function-types.js'
-
-export const pikkuFunctionTypesSplit: any = pikkuSessionlessFunc<void, void>({
-  func: async ({ logger, config, getInspectorState }) => {
-    const visitState = await getInspectorState()
-    const {
-      functionTypesFile,
-      packageMappings,
-      rpcInternalMapDeclarationFile,
-      servicesFile,
-    } = config
-
-    // Check for required types
-    checkRequiredTypes(visitState.filesAndMethodsErrors, {
-      userSessionType: true,
-      wireServiceType: true,
-      singletonServicesType: true,
-    })
-
-    const {
-      userSessionType,
-      wireServicesType,
-      singletonServicesType,
-      pikkuConfigType,
-    } = visitState.filesAndMethods
-
-    if (!userSessionType || !wireServicesType || !singletonServicesType) {
-      throw new Error('Required types not found')
-    }
-
-    const configTypeImport = pikkuConfigType
-      ? `import type { ${pikkuConfigType.type} } from '${getFileImportRelativePath(functionTypesFile, pikkuConfigType.typePath, packageMappings)}'`
-      : '// Config type not found, will use fallback'
-
-    const content = serializeFunctionTypes(
-      `import type { ${userSessionType.type} } from '${getFileImportRelativePath(functionTypesFile, userSessionType.typePath, packageMappings)}'`,
-      userSessionType.type,
-      `import type { ${singletonServicesType.type} } from '${getFileImportRelativePath(functionTypesFile, singletonServicesType.typePath, packageMappings)}'`,
-      singletonServicesType.type,
-      `import type { ${wireServicesType.type} } from '${getFileImportRelativePath(functionTypesFile, wireServicesType.typePath, packageMappings)}'`,
-      wireServicesType.type,
-      `import type { TypedPikkuRPC, FlattenedRPCMap } from '${getFileImportRelativePath(functionTypesFile, rpcInternalMapDeclarationFile, packageMappings)}'`,
-      `import type { RequiredSingletonServices, RequiredWireServices } from '${getFileImportRelativePath(functionTypesFile, servicesFile, packageMappings)}'`,
-      configTypeImport,
-      config.externalPackageName
-    )
-
-    await writeFileInDir(logger, functionTypesFile, content)
-  },
-  middleware: [
-    logCommandInfoAndTime({
-      commandStart: 'Creating function types',
-      commandEnd: 'Created function types',
-    }),
-  ],
-})

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

@@ -1,50 +0,0 @@
-import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
-import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
-import { writeFileInDir } from '../../../utils/file-writer.js'
-import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
-import { serializePikkuTypesHub } from './serialize-pikku-types-hub.js'
-
-export const pikkuFunctionTypes: any = pikkuSessionlessFunc<void, void>({
-  func: async ({ logger, config }) => {
-    const {
-      typesDeclarationFile: typesFile,
-      packageMappings,
-      functionTypesFile,
-      httpTypesFile,
-      channelsTypesFile,
-      schedulersTypesFile,
-      queueTypesFile,
-      mcpTypesFile,
-      cliTypesFile,
-      forgeTypesFile,
-    } = config
-
-    const getImportPath = (file: string) =>
-      config.externalPackage
-        ? null
-        : getFileImportRelativePath(typesFile, file, packageMappings)
-
-    // Forge types are included for external packages (they need wireForgeNode/wireForgeCredential)
-    const getForgeImportPath = (file: string) =>
-      getFileImportRelativePath(typesFile, file, packageMappings)
-
-    const content = serializePikkuTypesHub(
-      getFileImportRelativePath(typesFile, functionTypesFile, packageMappings),
-      getImportPath(httpTypesFile),
-      getImportPath(channelsTypesFile),
-      getImportPath(schedulersTypesFile),
-      getImportPath(queueTypesFile),
-      getImportPath(mcpTypesFile),
-      getImportPath(cliTypesFile),
-      getForgeImportPath(forgeTypesFile)
-    )
-
-    await writeFileInDir(logger, typesFile, content)
-  },
-  middleware: [
-    logCommandInfoAndTime({
-      commandStart: 'Creating api types hub',
-      commandEnd: 'Created api types hub',
-    }),
-  ],
-})