@pikku/cli 0.9.16-next.0 → 0.10.1

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

@@ -1,4 +1,6 @@
-import { Logger, LogLevel, PikkuChannel } from '@pikku/core'
+import { Logger, LogLevel } from '@pikku/core'
+import { PikkuChannel } from '@pikku/core/channel'
+import { ErrorCode } from '@pikku/inspector'
 
 /**
  * Log message structure sent through the channel
@@ -18,7 +20,7 @@ export class CLILoggerForwarder implements Logger {
 
   constructor(
     private logger: Logger,
-    private channel: PikkuChannel<unknown, ForwardedLogMessage>
+    private channel: PikkuChannel<unknown, any>
   ) {}
 
   setLevel(level: LogLevel): void {
@@ -74,4 +76,15 @@ export class CLILoggerForwarder implements Logger {
   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

@@ -1,5 +1,6 @@
 import chalk from 'chalk'
 import { Logger, LogLevel } from '@pikku/core'
+import { ErrorCode } from '@pikku/inspector'
 
 const logo = `
  ______ _ _     _
@@ -10,9 +11,12 @@ 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,
@@ -60,6 +64,17 @@ export class CLILogger implements Logger {
     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

package/src/services.ts

@@ -8,12 +8,19 @@ import {
   CreateConfig,
   CreateSessionServices,
   CreateSingletonServices,
-  pikkuCLIRender,
 } 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 } from '@pikku/inspector'
+import {
+  inspect,
+  InspectorState,
+  InspectorFilters,
+  serializeInspectorState,
+  deserializeInspectorState,
+  filterInspectorState,
+} from '@pikku/inspector'
 import { glob } from 'tinyglobby'
 import path from 'path'
 import { PikkuCLIConfig } from '../types/config.js'
@@ -21,9 +28,66 @@ 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
  */
@@ -36,20 +100,50 @@ export const defaultCLIRenderer = pikkuCLIRender<
   }
 })
 
+/**
+ * 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,
-    [],
-    data,
-    true
-  )
+  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,
   }
 }
 
@@ -61,12 +155,25 @@ export const createSingletonServices: CreateSingletonServices<
   Config,
   SingletonServices
 > = async (config) => {
-  const { rootDir, srcDirectories, filters } = config
+  const {
+    rootDir,
+    srcDirectories,
+    filters,
+    preloadedInspectorState,
+    stateOutput,
+  } = config
   const variables = new LocalVariablesService()
 
-  let inspectorState: InspectorState | undefined = undefined
+  // Store unfiltered state
+  let unfilteredState:
+    | InspectorState
+    | Omit<InspectorState, 'typesLookup'>
+    | undefined = preloadedInspectorState
+
   const getInspectorState = async (refresh: boolean = false) => {
-    if (refresh || !inspectorState) {
+    // 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) =>
@@ -74,18 +181,40 @@ export const createSingletonServices: CreateSingletonServices<
           )
         )
       ).flat()
-      inspectorState = await inspect(logger, wiringFiles, {
-        filters,
+      unfilteredState = await inspect(logger, wiringFiles, {
+        // NO filters here - inspector returns full unfiltered state
         types: {
           configFileType: config.configFile,
-          userSessionType: config.tags?.[0], // TODO: Properly handle type selection
-          singletonServicesFactoryType: undefined,
-          sessionServicesFactoryType: undefined,
+          userSessionType: config.userSessionType,
+          singletonServicesFactoryType: config.singletonServicesFactoryType,
+          sessionServicesFactoryType: config.sessionServicesFactoryType,
         },
       })
-      return inspectorState
+
+      // 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
+        }
+      }
     }
-    return inspectorState!
+
+    // Apply filters as a post-processing step
+    const filteredState = filterInspectorState(unfilteredState, filters, logger)
+
+    return filteredState as InspectorState
   }
 
   return {

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

@@ -13,8 +13,23 @@ export const checkRequiredTypes = (
   errors: FilesAndMethodsErrors,
   requires: RequiredTypes = {}
 ): void => {
+  // Filter out errors that are about missing Types when we have the corresponding Factory
+  // e.g., if we have a CreateConfig factory, we don't need a CoreConfig type
+  const errorMessages = Array.from(errors.keys())
+  const hasCreateConfigFactory = errorMessages.every(
+    (msg) => !msg.includes('No CreateConfig found')
+  )
+
   // Only throw if there are errors AND we require those types
-  const hasRequiredErrors = Array.from(errors.keys()).some((message) => {
+  const hasRequiredErrors = errorMessages.some((message) => {
+    // Skip CoreConfig type errors if we have a CreateConfig factory
+    if (
+      requires.config &&
+      message.includes('No CoreConfig found') &&
+      hasCreateConfigFactory
+    ) {
+      return false
+    }
     if (requires.config && message.includes('CoreConfig')) return true
     if (requires.sessionServiceType && message.includes('CoreServices'))
       return true

package/src/utils/custom-types-generator.ts

@@ -9,8 +9,14 @@ export function generateCustomTypes(
 // or are broken into simpler types
 ${Array.from(typesMap.customTypes.entries())
   .map(([name, { type, references }]) => {
-    references.forEach((name) => {
-      requiredTypes.add(name)
+    references.forEach((refName) => {
+      // Skip __object types (including those with suffixes like __object_abc123)
+      // These are placeholder types created by the inspector for invalid/broken functions
+      // (e.g., functions with type errors or missing return statements). Attempting to
+      // import these would fail since the source files don't actually export __object.
+      if (refName !== '__object' && !refName.startsWith('__object_')) {
+        requiredTypes.add(refName)
+      }
     })
 
     // Extract type names from the type string that might not be in references

package/src/utils/file-writer.ts

@@ -1,10 +1,11 @@
 import { dirname } from 'path'
-import { mkdir, readFile, writeFile } from 'fs/promises'
+import { mkdir, readFile, writeFile, rm } from 'fs/promises'
+import { existsSync } from 'fs'
 import { CLILogger } from '../services/cli-logger.service.js'
+import { getCLIVersion } from './get-cli-version.js'
 
-// TODO: add version back in once the ESM dust settles
 export const DO_NOT_MODIFY_COMMENT = `/**
- * This file was generated by the @pikku/cli
+ * This file was generated by @pikku/cli@${getCLIVersion()}
  */
 `
 
@@ -54,3 +55,18 @@ export const writeFileInDir = async (
     }
   }
 }
+
+export const removeFileInDir = async (
+  logger: CLILogger,
+  path: string,
+  { logRemove = true }: { logRemove?: boolean } = {}
+) => {
+  // Check if file exists before attempting removal
+  if (existsSync(path)) {
+    await rm(path, { force: true })
+
+    if (logRemove) {
+      logger.info({ message: `✓ File removed at ${path}`, type: 'success' })
+    }
+  }
+}

package/src/utils/get-cli-version.ts

@@ -0,0 +1,28 @@
+import { dirname, join } from 'path'
+import { readFile } from 'fs/promises'
+import { fileURLToPath } from 'url'
+
+// Get package version for generated file comments
+const __dirname = dirname(fileURLToPath(import.meta.url))
+let version = 'unknown'
+
+try {
+  // Try from src/ first (development), then from dist/src/ (built)
+  const pkgPath = join(__dirname, '..', '..', 'package.json')
+  const pkgJson = JSON.parse(await readFile(pkgPath, 'utf-8'))
+  version = pkgJson.version
+} catch {
+  try {
+    const pkgPath = join(__dirname, '..', '..', '..', 'package.json')
+    const pkgJson = JSON.parse(await readFile(pkgPath, 'utf-8'))
+    version = pkgJson.version
+  } catch {
+    // Fallback to unknown if package.json can't be found
+  }
+}
+
+/**
+ * Returns the CLI version string
+ * Works from both src/ and dist/src/ locations
+ */
+export const getCLIVersion = () => version

package/src/utils/pikku-cli-config.ts

@@ -1,8 +1,6 @@
 import { join, dirname, resolve, isAbsolute } from 'path'
 import { readdir, readFile } from 'fs/promises'
 import { PikkuCLIConfig } from '../../types/config.js'
-import { InspectorFilters } from '@pikku/inspector'
-import { PikkuWiringTypes } from '@pikku/core'
 import { CLILogger } from '../services/cli-logger.service.js'
 
 const CONFIG_DIR_FILES = [
@@ -19,14 +17,12 @@ export const getPikkuCLIConfig = async (
   logger: CLILogger,
   configFile: string | undefined = undefined,
   requiredFields: Array<keyof PikkuCLIConfig>,
-  filters: InspectorFilters = {},
   exitProcess: boolean = false
 ): Promise<PikkuCLIConfig> => {
   const config = await _getPikkuCLIConfig(
     logger,
     configFile,
     requiredFields,
-    filters,
     exitProcess
   )
   return config
@@ -36,7 +32,6 @@ const _getPikkuCLIConfig = async (
   logger: CLILogger,
   configFile: string | undefined = undefined,
   requiredFields: Array<keyof PikkuCLIConfig>,
-  filters: InspectorFilters = {},
   exitProcess: boolean = false
 ): Promise<PikkuCLIConfig> => {
   if (!configFile) {
@@ -59,7 +54,6 @@ const _getPikkuCLIConfig = async (
         logger,
         resolve(configDir, config.extends),
         [],
-        filters,
         exitProcess
       )
       result = {
@@ -246,6 +240,12 @@ const _getPikkuCLIConfig = async (
       )
     }
 
+    // Permissions
+    const permissionsDir = join(result.outDir, 'permissions')
+    if (!result.permissionsFile) {
+      result.permissionsFile = join(permissionsDir, 'pikku-permissions.gen.ts')
+    }
+
     // Bootstrap files
     if (!result.bootstrapFile) {
       result.bootstrapFile = join(result.outDir, 'pikku-bootstrap.gen.ts')
@@ -279,15 +279,6 @@ const _getPikkuCLIConfig = async (
       result.cliTypesFile = join(cliDir, 'pikku-cli-types.gen.ts')
     }
 
-    result.bootstrapFiles = result.bootstrapFiles || {}
-    for (const key of Object.keys(PikkuWiringTypes)) {
-      const eventDir = join(result.outDir, key.toLowerCase())
-      result.bootstrapFiles[key] = join(
-        eventDir,
-        `pikku-bootstrap-${key}.gen.ts`
-      )
-    }
-
     if (requiredFields.length > 0) {
       validateCLIConfig(result, requiredFields)
     }
@@ -306,26 +297,6 @@ const _getPikkuCLIConfig = async (
       }
     }
 
-    // Separately normalize bootstrapFiles (Record<string, string>)
-    if (result.bootstrapFiles && typeof result.bootstrapFiles === 'object') {
-      for (const [key, value] of Object.entries(result.bootstrapFiles)) {
-        if (typeof value === 'string' && !isAbsolute(value)) {
-          result.bootstrapFiles[key] = join(result.rootDir, value)
-        }
-      }
-    }
-
-    result.filters = result.filters || {}
-    if (filters.tags && filters.tags.length > 0) {
-      result.filters.tags = filters.tags
-    }
-    if (filters.types && filters.types.length > 0) {
-      result.filters.types = filters.types
-    }
-    if (filters.directories && filters.directories.length > 0) {
-      result.filters.directories = filters.directories
-    }
-
     if (!isAbsolute(result.tsconfig)) {
       result.tsconfig = join(result.rootDir, result.tsconfig)
     }

package/src/utils/schema-generator.ts

@@ -3,7 +3,7 @@ import { writeFileInDir } from './file-writer.js'
 import { mkdir, writeFile } from 'fs/promises'
 import { FunctionsMeta, JSONValue } from '@pikku/core'
 import { HTTPWiringsMeta } from '@pikku/core/http'
-import { TypesMap } from '@pikku/inspector'
+import { TypesMap, ErrorCode } from '@pikku/inspector'
 import { CLILogger } from '../services/cli-logger.service.js'
 
 export async function generateSchemas(
@@ -66,10 +66,14 @@ export async function generateSchemas(
     } catch (e) {
       // Ignore rootless errors
       if (e instanceof RootlessError) {
-        logger.error(`Error generating schema since it has no root: ${schema}`)
+        logger.error(
+          `[${ErrorCode.SCHEMA_NO_ROOT}] Error generating schema since it has no root: ${schema}`
+        )
         return
       }
-      logger.error(`Error generating schema: ${schema}`)
+      logger.error(
+        `[${ErrorCode.SCHEMA_GENERATION_ERROR}] Error generating schema: ${schema}. Message: ${e.message}`
+      )
     }
   })
 

package/src/utils/serialize-import-map.ts

@@ -82,10 +82,6 @@ export const serializeImportMap = (
     }
     const variables = paths.get(path) || []
 
-    if (uniqueName === '__object') {
-      return
-    }
-
     const importName =
       originalName === uniqueName
         ? originalName

package/types/application-types.d.ts

@@ -8,7 +8,10 @@ import type { CLILogger } from '../src/services/cli-logger.service.js'
 import { PikkuCLIConfig } from '../types/config.d.ts'
 import { InspectorState } from '@pikku/inspector'
 
-export interface Config extends CoreConfig<PikkuCLIConfig> {}
+export interface Config extends CoreConfig<PikkuCLIConfig> {
+  // Preloaded inspector state from stateInput file (if provided)
+  preloadedInspectorState?: Omit<InspectorState, 'typesLookup'>
+}
 
 export interface SingletonServices extends CoreSingletonServices<Config> {
   logger: CLILogger

package/types/config.d.ts

@@ -64,9 +64,11 @@ export interface PikkuCLICoreOutputFiles {
   middlewareFile: string
   middlewareGroupsMetaFile: string
 
+  // Permissions
+  permissionsFile: string
+
   // Application bootstrap
   bootstrapFile: string
-  bootstrapFiles: Record<PikkuWiringTypes, string>
 }
 
 export type PikkuCLIInput = {
@@ -121,10 +123,13 @@ export type PikkuCLIInput = {
     >
   }
 
-  middlewareServices?: string[]
+  forceRequiredServices?: string[]
 
   schemasFromTypes?: string[]
 
+  stateOutput?: string
+  stateInput?: string
+
   filters: InspectorFilters
 } & PikkuCLICoreOutputFiles
 
@@ -142,6 +147,10 @@ export type PikkuCLIConfig = {
   tags?: string[]
   types?: string[]
 
+  userSessionType?: string
+  singletonServicesFactoryType?: string
+  sessionServicesFactoryType?: string
+
   configDir: string
   tsconfig: string
 
@@ -184,9 +193,12 @@ export type PikkuCLIConfig = {
     >
   }
 
-  middlewareServices?: string[]
+  forceRequiredServices?: string[]
 
   schemasFromTypes?: string[]
 
+  stateOutput?: string
+  stateInput?: string
+
   filters: InspectorFilters
 } & PikkuCLICoreOutputFiles

package/dist/.pikku/rpc/pikku-bootstrap-rpc.gen.d.ts

@@ -1,6 +0,0 @@
-/**
- * This file was generated by the @pikku/cli
- */
-import '../function/pikku-functions-meta.min.gen.js';
-import '../function/pikku-functions.gen.js';
-import '../schemas/register.gen.js';

package/dist/.pikku/rpc/pikku-bootstrap-rpc.gen.js

@@ -1,6 +0,0 @@
-/**
- * This file was generated by the @pikku/cli
- */
-import '../function/pikku-functions-meta.min.gen.js';
-import '../function/pikku-functions.gen.js';
-import '../schemas/register.gen.js';

package/dist/src/serialize-pikku-types.d.ts

@@ -1,4 +0,0 @@
-/**
- *
- */
-export declare const serializePikkuTypes: (userSessionTypeImport: string, userSessionTypeName: string, singletonServicesTypeImport: string, singletonServicesTypeName: string, sessionServicesTypeImport: string, sessionServicesTypeName: string, rpcMapTypeImport: string) => string;