@pikku/cli 0.7.0 → 0.7.2

package/src/openapi-spec-generator.ts

@@ -0,0 +1,246 @@
+import { FunctionsMeta, HTTPRoutesMeta, pikkuState } from '@pikku/core'
+import _convertSchema from '@openapi-contrib/json-schema-to-openapi-schema'
+const convertSchema =
+  'default' in _convertSchema ? (_convertSchema.default as any) : _convertSchema
+
+interface OpenAPISpec {
+  openapi: string
+  info: {
+    title: string
+    version: string
+    description?: string
+    termsOfService?: string
+    contact?: {
+      name?: string
+      url?: string
+      email?: string
+    }
+    license?: {
+      name: string
+      url?: string
+    }
+  }
+  servers: { url: string; description?: string }[]
+  paths: Record<string, any>
+  components: {
+    schemas: Record<string, any>
+    responses?: Record<string, any>
+    parameters?: Record<string, any>
+    examples?: Record<string, any>
+    requestBodies?: Record<string, any>
+    headers?: Record<string, any>
+    securitySchemes?: Record<string, any>
+  }
+  security?: { [key: string]: any[] }[]
+  tags?: { name: string; description?: string }[]
+  externalDocs?: {
+    description?: string
+    url: string
+  }
+}
+
+export interface OpenAPISpecInfo {
+  info: {
+    title: string
+    version: string
+    description: string
+    termsOfService?: string
+    contact?: {
+      name?: string
+      url?: string
+      email?: string
+    }
+    license?: {
+      name: string
+      url?: string
+    }
+  }
+  servers: { url: string; description?: string }[]
+  tags?: { name: string; description?: string }[]
+  externalDocs?: {
+    description?: string
+    url: string
+  }
+  securitySchemes?: Record<string, any>
+  security?: { [key: string]: any[] }[]
+}
+
+const getErrorResponseForConstructorName = (constructorName: string) => {
+  const errors = Array.from(pikkuState('misc', 'errors').entries())
+  const foundError = errors.find(([e]) => e.name === constructorName)
+  if (foundError) {
+    return foundError[1]
+  }
+  return undefined
+}
+
+const convertSchemasToBodyPayloads = async (
+  functionsMeta: FunctionsMeta,
+  routesMeta: HTTPRoutesMeta,
+  schemas: Record<string, any>
+) => {
+  const requiredSchemas = new Set(
+    routesMeta
+      .map(({ inputTypes, pikkuFuncName }) => {
+        const output = functionsMeta[pikkuFuncName]?.outputs?.[0]
+        return [inputTypes?.body, output]
+      })
+      .flat()
+      .filter((schema) => !!schema)
+  )
+  const convertedEntries = await Promise.all(
+    Object.entries(schemas).map(async ([key, schema]) => {
+      if (requiredSchemas.has(key)) {
+        const convertedSchema = await convertSchema(schema, {
+          convertUnreferencedDefinitions: false,
+          dereference: { circular: 'ignore' },
+        })
+        return [key, convertedSchema]
+      }
+      return
+    })
+  )
+  return Object.fromEntries(convertedEntries.filter((s) => !!s))
+}
+
+export async function generateOpenAPISpec(
+  functionsMeta: FunctionsMeta,
+  routeMeta: HTTPRoutesMeta,
+  schemas: Record<string, any>,
+  additionalInfo: OpenAPISpecInfo
+): Promise<OpenAPISpec> {
+  const paths: Record<string, any> = {}
+
+  routeMeta.forEach((meta) => {
+    const { route, method, inputTypes, pikkuFuncName, params, query, docs } =
+      meta
+    const functionMeta = functionsMeta[pikkuFuncName]
+    if (!functionMeta) {
+      console.error(
+        `• No function metadata found for '${pikkuFuncName}' in route '${route}'.`
+      )
+      return
+    }
+    const output = functionMeta.outputs ? functionMeta.outputs[0] : undefined
+
+    const path = route.replace(/:(\w+)/g, '{$1}') // Convert ":param" to "{param}"
+
+    if (!paths[path]) {
+      paths[path] = {}
+    }
+
+    const responses = {}
+    docs?.errors?.forEach((error) => {
+      const errorResponse = getErrorResponseForConstructorName(error)
+      if (errorResponse) {
+        responses[errorResponse.status] = {
+          description: errorResponse.message,
+        }
+      }
+    })
+
+    const operation: any = {
+      description:
+        docs?.description ||
+        `This endpoint handles the ${method.toUpperCase()} request for the route ${route}.`,
+      tags: docs?.tags || [route.split('/')[1] || 'default'],
+      parameters: [],
+      responses: {
+        ...responses,
+        '200': {
+          description: 'Successful response',
+          content: output
+            ? {
+                'application/json': {
+                  schema:
+                    typeof output === 'string' &&
+                    ['boolean', 'string', 'number'].includes(output)
+                      ? { type: output }
+                      : { $ref: `#/components/schemas/${output}` },
+                },
+              }
+            : undefined,
+        },
+      },
+    }
+
+    const bodyType = inputTypes?.body
+    if (bodyType) {
+      operation.requestBody = {
+        required: true,
+        content: {
+          'application/json': {
+            schema:
+              typeof bodyType === 'string' &&
+              ['boolean', 'string', 'number'].includes(bodyType)
+                ? { type: bodyType }
+                : { $ref: `#/components/schemas/${bodyType}` },
+          },
+        },
+      }
+    }
+
+    if (params) {
+      operation.parameters = params.map((param) => ({
+        name: param,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      }))
+    }
+
+    if (query) {
+      operation.parameters.push(
+        ...query.map((query) => ({
+          name: query,
+          in: 'query',
+          required: false,
+          schema: { type: 'string' },
+        }))
+      )
+    }
+
+    paths[path][method] = operation
+  })
+
+  return {
+    openapi: '3.1.0',
+    info: additionalInfo.info,
+    servers: additionalInfo.servers,
+    paths,
+    components: {
+      schemas: await convertSchemasToBodyPayloads(
+        functionsMeta,
+        routeMeta,
+        schemas
+      ),
+      responses: {},
+      parameters: {},
+      examples: {},
+      requestBodies: {},
+      headers: {},
+      securitySchemes: additionalInfo.securitySchemes || {
+        ApiKeyAuth: {
+          type: 'apiKey',
+          in: 'header',
+          name: 'x-api-key',
+        },
+        BearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+        },
+      },
+    },
+    security: additionalInfo.security || [
+      {
+        ApiKeyAuth: [],
+      },
+      {
+        BearerAuth: [],
+      },
+    ],
+    tags: additionalInfo.tags,
+    externalDocs: additionalInfo.externalDocs,
+    // definitions
+  }
+}

package/src/pikku-cli-config.ts

@@ -0,0 +1,240 @@
+import { join, dirname, resolve, isAbsolute } from 'path'
+import { readdir, readFile } from 'fs/promises'
+import { OpenAPISpecInfo } from './openapi-spec-generator.js'
+import { InspectorFilters } from '@pikku/inspector'
+
+export interface PikkuCLICoreOutputFiles {
+  outDir?: string
+  functionsFile: string
+  functionsMetaFile: string
+  httpRoutesFile: string
+  httpRoutesMetaFile: string
+  channelsFile: string
+  channelsMetaFile: string
+  schedulersFile: string
+  schedulersMetaFile: string
+  rpcFile: string
+  schemaDirectory: string
+  typesDeclarationFile: string
+  httpRoutesMapDeclarationFile: string
+  channelsMapDeclarationFile: string
+  bootstrapFile: string
+}
+
+export type PikkuCLIConfig = {
+  $schema?: string
+
+  extends?: string
+
+  rootDir: string
+  srcDirectories: string[]
+  packageMappings: Record<string, string>
+  supportsImportAttributes: boolean
+
+  configDir: string
+  tsconfig: string
+
+  nextBackendFile?: string
+  nextHTTPFile?: string
+  fetchFile?: string
+  websocketFile?: string
+
+  openAPI?: {
+    outputFile: string
+    additionalInfo: OpenAPISpecInfo
+  }
+
+  filters: InspectorFilters
+} & PikkuCLICoreOutputFiles
+
+const CONFIG_DIR_FILES = [
+  'nextBackendFile',
+  'nextHTTPFile',
+  'fetchFile',
+  'websocketFile',
+]
+
+export const getPikkuCLIConfig = async (
+  configFile: string | undefined = undefined,
+  requiredFields: Array<keyof PikkuCLIConfig>,
+  tags: string[] = [],
+  exitProcess: boolean = false
+): Promise<PikkuCLIConfig> => {
+  const config = await _getPikkuCLIConfig(
+    configFile,
+    requiredFields,
+    tags,
+    exitProcess
+  )
+  return config
+}
+
+const _getPikkuCLIConfig = async (
+  configFile: string | undefined = undefined,
+  requiredFields: Array<keyof PikkuCLIConfig>,
+  tags: string[] = [],
+  exitProcess: boolean = false
+): Promise<PikkuCLIConfig> => {
+  if (!configFile) {
+    let execDirectory = process.cwd()
+    const files = await readdir(execDirectory)
+    const file = files.find((file) => /pikku\.config\.(ts|js|json)$/.test(file))
+    if (!file) {
+      const errorMessage =
+        '\nConfig file pikku.config.json not found\nExiting...'
+      if (exitProcess) {
+        console.error(errorMessage)
+        process.exit(1)
+      }
+      throw new Error(errorMessage)
+    }
+    configFile = join(execDirectory, file)
+  }
+
+  try {
+    let result: PikkuCLIConfig
+    const file = await readFile(configFile, 'utf-8')
+    const configDir = dirname(configFile)
+    const config: PikkuCLIConfig = JSON.parse(file)
+    if (config.extends) {
+      const extendedConfig = await getPikkuCLIConfig(
+        resolve(configDir, config.extends),
+        [],
+        tags,
+        exitProcess
+      )
+      result = {
+        ...extendedConfig,
+        ...config,
+        configDir,
+        packageMappings: {
+          ...extendedConfig.packageMappings,
+          ...config.packageMappings,
+        },
+      }
+    } else {
+      result = {
+        ...config,
+        configDir,
+        packageMappings: config.packageMappings || {},
+        rootDir: config.rootDir
+          ? resolve(configDir, config.rootDir)
+          : configDir,
+      }
+    }
+
+    if (result.outDir) {
+      if (!result.schemaDirectory) {
+        result.schemaDirectory = join(result.outDir, 'pikku-schemas')
+      }
+      if (!result.functionsFile) {
+        result.functionsFile = join(result.outDir, 'pikku-functions.gen.ts')
+      }
+      if (!result.functionsMetaFile) {
+        result.functionsMetaFile = join(
+          result.outDir,
+          'pikku-functions-meta.gen.ts'
+        )
+      }
+      if (!result.rpcFile) {
+        result.rpcFile = join(result.outDir, 'pikku-rpc.gen.ts')
+      }
+      if (!result.httpRoutesFile) {
+        result.httpRoutesFile = join(result.outDir, 'pikku-http-routes.gen.ts')
+      }
+      if (!result.httpRoutesMetaFile) {
+        result.httpRoutesMetaFile = join(
+          result.outDir,
+          'pikku-http-routes-meta.gen.ts'
+        )
+      }
+      if (!result.schedulersFile) {
+        result.schedulersFile = join(result.outDir, 'pikku-schedules.gen.ts')
+      }
+      if (!result.schedulersMetaFile) {
+        result.schedulersMetaFile = join(
+          result.outDir,
+          'pikku-schedules-meta.gen.ts'
+        )
+      }
+      if (!result.channelsFile) {
+        result.channelsFile = join(result.outDir, 'pikku-channels.gen.ts')
+      }
+      if (!result.channelsMetaFile) {
+        result.channelsMetaFile = join(
+          result.outDir,
+          'pikku-channels-meta.gen.ts'
+        )
+      }
+      if (!result.typesDeclarationFile) {
+        result.typesDeclarationFile = join(result.outDir, 'pikku-types.gen.ts')
+      }
+      if (!result.httpRoutesMapDeclarationFile) {
+        result.httpRoutesMapDeclarationFile = join(
+          result.outDir,
+          'pikku-routes-map.gen.d.ts'
+        )
+      }
+      if (!result.channelsMapDeclarationFile) {
+        result.channelsMapDeclarationFile = join(
+          result.outDir,
+          'pikku-channels-map.gen.d.ts'
+        )
+      }
+      if (!result.bootstrapFile) {
+        result.bootstrapFile = join(result.outDir, 'pikku-bootstrap.gen.ts')
+      }
+    }
+
+    if (requiredFields.length > 0) {
+      validateCLIConfig(result, requiredFields)
+    }
+
+    for (const objectKey of Object.keys(result)) {
+      if (objectKey.endsWith('File') || objectKey.endsWith('Directory')) {
+        const relativeTo = CONFIG_DIR_FILES.includes(objectKey)
+          ? result.configDir
+          : result.rootDir
+        if (result[objectKey]) {
+          if (!isAbsolute(result[objectKey])) {
+            result[objectKey] = join(relativeTo, result[objectKey])
+          }
+        }
+      }
+    }
+
+    result.filters = result.filters || {}
+    if (tags.length > 0) {
+      result.filters.tags = tags
+    }
+
+    if (!isAbsolute(result.tsconfig)) {
+      result.tsconfig = join(result.rootDir, result.tsconfig)
+    }
+
+    return result
+  } catch (e: any) {
+    console.error(e)
+    console.error(`Config file not found: ${configFile}`)
+    process.exit(1)
+  }
+}
+
+export const validateCLIConfig = (
+  cliConfig: PikkuCLIConfig,
+  required: Array<keyof PikkuCLIConfig>
+) => {
+  let errors: string[] = []
+  for (const key of required) {
+    if (!cliConfig[key]) {
+      errors.push(key)
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error(
+      `${errors.join(', ')} ${errors.length === 1 ? 'is' : 'are'} required in pikku.config.json`
+    )
+    process.exit(1)
+  }
+}

package/src/schema-generator.ts

@@ -0,0 +1,118 @@
+import { createGenerator, RootlessError } from 'ts-json-schema-generator'
+import { logInfo, writeFileInDir } from './utils.js'
+import { mkdir, writeFile } from 'fs/promises'
+import { FunctionsMeta, JSONValue } from '@pikku/core'
+import { HTTPRoutesMeta } from '@pikku/core/http'
+import { TypesMap } from '@pikku/inspector'
+
+export async function generateSchemas(
+  tsconfig: string,
+  typesMap: TypesMap,
+  functionMeta: FunctionsMeta,
+  httpRoutesMeta: HTTPRoutesMeta
+): Promise<Record<string, JSONValue>> {
+  const schemasSet = new Set(typesMap.customTypes.keys())
+  for (const { inputs, outputs } of Object.values(functionMeta)) {
+    const types = [...(inputs || []), ...(outputs || [])]
+    for (const type of types) {
+      const uniqueName = typesMap.getUniqueName(type)
+      if (uniqueName) {
+        schemasSet.add(uniqueName)
+      }
+    }
+  }
+  for (const { inputTypes } of httpRoutesMeta) {
+    if (inputTypes?.body) {
+      schemasSet.add(inputTypes.body)
+    }
+    if (inputTypes?.query) {
+      schemasSet.add(inputTypes.query)
+    }
+    if (inputTypes?.params) {
+      schemasSet.add(inputTypes.params)
+    }
+  }
+
+  const generator = createGenerator({
+    tsconfig,
+    skipTypeCheck: true,
+    topRef: false,
+    discriminatorType: 'open-api',
+  })
+  const schemas: Record<string, JSONValue> = {}
+  schemasSet.forEach((schema) => {
+    try {
+      schemas[schema] = generator.createSchema(schema) as JSONValue
+    } catch (e) {
+      // Ignore rootless errors
+      if (e instanceof RootlessError) {
+        console.error('Error generating schema since it has no root:', schema)
+        return
+      }
+      throw e
+    }
+  })
+
+  return schemas
+}
+
+export async function saveSchemas(
+  schemaParentDir: string,
+  schemas: Record<string, JSONValue>,
+  typesMap: TypesMap,
+  functionsMeta: FunctionsMeta,
+  supportsImportAttributes: boolean
+) {
+  await writeFileInDir(
+    `${schemaParentDir}/register.gen.ts`,
+    'export const empty = null;'
+  )
+
+  const desiredSchemas = new Set([
+    ...Object.values(functionsMeta)
+      .map(({ inputs, outputs }) => [
+        inputs?.[0] ? typesMap.getUniqueName(inputs[0]) : undefined,
+        outputs?.[0] ? typesMap.getUniqueName(outputs[0]) : undefined,
+      ])
+      .flat()
+      .filter(
+        (s) =>
+          !!s &&
+          !['boolean', 'string', 'number', 'null', 'undefined'].includes(s)
+      ),
+    ...typesMap.customTypes.keys(),
+  ])
+
+  if (desiredSchemas.size === 0) {
+    logInfo(`• Skipping schemas since none found.\x1b[0m`)
+    return
+  }
+
+  await mkdir(`${schemaParentDir}/schemas`, { recursive: true })
+  await Promise.all(
+    Object.entries(schemas).map(async ([schemaName, schema]) => {
+      if (desiredSchemas.has(schemaName)) {
+        await writeFile(
+          `${schemaParentDir}/schemas/${schemaName}.schema.json`,
+          JSON.stringify(schema),
+          'utf-8'
+        )
+      }
+    })
+  )
+
+  const schemaImports = Array.from(desiredSchemas)
+    .map(
+      (schema) => `
+import * as ${schema} from './schemas/${schema}.schema.json' ${supportsImportAttributes ? `with { type: 'json' }` : ''}
+addSchema('${schema}', ${schema})
+`
+    )
+    .join('\n')
+
+  await writeFileInDir(
+    `${schemaParentDir}/register.gen.ts`,
+    `import { addSchema } from '@pikku/core/schema'
+${schemaImports}`
+  )
+}

package/{dist/src/events/http/serialize-fetch-wrapper.js → src/serialize-fetch-wrapper.ts}

@@ -1,5 +1,5 @@
-export const serializeFetchWrapper = (routesMapPath) => {
-    return `
+export const serializeFetchWrapper = (routesMapPath: string) => {
+  return `
 import { CorePikkuFetch, HTTPMethod } from '@pikku/fetch'
 import type { RoutesMap, RouteHandlerOf, RoutesWithMethod } from '${routesMapPath}'
 
@@ -63,5 +63,5 @@ export class PikkuFetch extends CorePikkuFetch {
 }
 
 export const pikkuFetch = new PikkuFetch();
-`;
-};
+`
+}

package/src/serialize-import-map.ts

@@ -0,0 +1,34 @@
+import { TypesMap } from '@pikku/inspector'
+import { getFileImportRelativePath } from './utils.js'
+
+export const serializeImportMap = (
+  relativeToPath: string,
+  packageMappings: Record<string, string>,
+  typesMap: TypesMap,
+  requiredTypes: Set<string>
+) => {
+  const paths = new Map<string, string[]>()
+  Array.from(requiredTypes).forEach((requiredType) => {
+    const { originalName, uniqueName, path } =
+      typesMap.getTypeMeta(requiredType)
+    if (!path) {
+      // This is a custom type that exists in file, so we don't need to import it
+      return
+    }
+    const variables = paths.get(path) || []
+    if (originalName === uniqueName) {
+      variables.push(originalName)
+    } else {
+      variables.push(`${originalName} as ${uniqueName}`)
+    }
+    paths.set(path, variables)
+  })
+
+  const imports: string[] = []
+  for (const [path, variables] of paths.entries()) {
+    imports.push(
+      `import type { ${variables.join(', ')} } from '${getFileImportRelativePath(relativeToPath, path, packageMappings)}'`
+    )
+  }
+  return imports.join('\n')
+}

package/{dist/src/nextjs/serialize-nextjs-backend-wrapper.js → src/serialize-nextjs-backend-wrapper.ts}

@@ -1,5 +1,12 @@
-export const serializeNextJsBackendWrapper = (routesPath, routesMapPath, schemasPath, configImport, singleServicesFactoryImport, sessionServicesImport) => {
-    return `'server-only'
+export const serializeNextJsBackendWrapper = (
+  routesPath: string,
+  routesMapPath: string,
+  schemasPath: string,
+  configImport: string,
+  singleServicesFactoryImport: string,
+  sessionServicesImport: string
+) => {
+  return `'server-only'
   
 /**
  * This file provides a wrapper around the PikkuNextJS class to allow for methods to be type checked against your routes.
@@ -176,5 +183,5 @@ export const pikku = (_options?: any) => {
     staticPost
   }
 }
-`;
-};
+`
+}

package/{dist/src/nextjs/serialize-nextjs-http-wrapper.js → src/serialize-nextjs-http-wrapper.ts}

@@ -1,5 +1,8 @@
-export const serializeNextJsHTTPWrapper = (routesMapPath, pikkuFetchImport) => {
-    return `'server-only'
+export const serializeNextJsHTTPWrapper = (
+  routesMapPath: string,
+  pikkuFetchImport: string
+) => {
+  return `'server-only'
   
 /**
  * This file provides a wrapper around the PikkuNextJS class to allow for methods to be type checked against your routes.
@@ -156,5 +159,5 @@ export const pikku = (options?: CorePikkuFetchOptions) => {
     staticPost
   }
 }
-`;
-};
+`
+}