@pikku/cli 0.11.2 → 0.11.3

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

@@ -0,0 +1,94 @@
+/**
+ * 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

@@ -44,9 +44,10 @@ export const pikkuFunctionTypesSplit: any = pikkuSessionlessFunc<void, void>({
       singletonServicesType.type,
       `import type { ${wireServicesType.type} } from '${getFileImportRelativePath(functionTypesFile, wireServicesType.typePath, packageMappings)}'`,
       wireServicesType.type,
-      `import type { TypedPikkuRPC } from '${getFileImportRelativePath(functionTypesFile, rpcInternalMapDeclarationFile, packageMappings)}'`,
+      `import type { TypedPikkuRPC, FlattenedRPCMap } from '${getFileImportRelativePath(functionTypesFile, rpcInternalMapDeclarationFile, packageMappings)}'`,
       `import type { RequiredSingletonServices, RequiredWireServices } from '${getFileImportRelativePath(functionTypesFile, servicesFile, packageMappings)}'`,
-      configTypeImport
+      configTypeImport,
+      config.externalPackageName
     )
 
     await writeFileInDir(logger, functionTypesFile, content)

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

@@ -16,20 +16,27 @@ export const pikkuFunctionTypes: any = pikkuSessionlessFunc<void, void>({
       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),
-      getFileImportRelativePath(typesFile, httpTypesFile, packageMappings),
-      getFileImportRelativePath(typesFile, channelsTypesFile, packageMappings),
-      getFileImportRelativePath(
-        typesFile,
-        schedulersTypesFile,
-        packageMappings
-      ),
-      getFileImportRelativePath(typesFile, queueTypesFile, packageMappings),
-      getFileImportRelativePath(typesFile, mcpTypesFile, packageMappings),
-      getFileImportRelativePath(typesFile, cliTypesFile, packageMappings)
+      getImportPath(httpTypesFile),
+      getImportPath(channelsTypesFile),
+      getImportPath(schedulersTypesFile),
+      getImportPath(queueTypesFile),
+      getImportPath(mcpTypesFile),
+      getImportPath(cliTypesFile),
+      getForgeImportPath(forgeTypesFile)
     )
 
     await writeFileInDir(logger, typesFile, content)

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

@@ -1,11 +1,12 @@
 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 {
-  generateRuntimeMeta,
-  serializeFunctionImports,
-} from './serialize-function-imports.js'
+import { serializeFunctionImports } from './serialize-function-imports.js'
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
+import {
+  stripVerboseFields,
+  hasVerboseFields,
+} from '../../../utils/strip-verbose-meta.js'
 
 export const pikkuFunctions: any = pikkuSessionlessFunc<
   void,
@@ -16,74 +17,83 @@ export const pikkuFunctions: any = pikkuSessionlessFunc<
     const {
       functionsMetaFile,
       functionsMetaJsonFile,
-      functionsMetaMinFile,
-      functionsMetaMinJsonFile,
       functionsFile,
       packageMappings,
       schema,
     } = config
 
+    // Write minimal JSON (runtime-only fields)
+    const minimalMeta = stripVerboseFields(functions.meta)
     await writeFileInDir(
       logger,
       functionsMetaJsonFile,
-      JSON.stringify(functions.meta, null, 2)
+      JSON.stringify(minimalMeta, null, 2)
     )
 
-    const fullJsonImportPath = getFileImportRelativePath(
+    // Write verbose JSON only if it has additional fields
+    if (hasVerboseFields(functions.meta)) {
+      const verbosePath = functionsMetaJsonFile.replace(
+        /\.gen\.json$/,
+        '-verbose.gen.json'
+      )
+      await writeFileInDir(
+        logger,
+        verbosePath,
+        JSON.stringify(functions.meta, null, 2)
+      )
+    }
+
+    const jsonImportPath = getFileImportRelativePath(
       functionsMetaFile,
       functionsMetaJsonFile,
       packageMappings
     )
 
     const supportsImportAttributes = schema?.supportsImportAttributes ?? false
-    const fullImportStatement = supportsImportAttributes
-      ? `import metaData from '${fullJsonImportPath}' with { type: 'json' }`
-      : `import metaData from '${fullJsonImportPath}'`
+    const importStatement = supportsImportAttributes
+      ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
+      : `import metaData from '${jsonImportPath}'`
 
-    await writeFileInDir(
-      logger,
-      functionsMetaFile,
-      `import { pikkuState, FunctionsMeta } from '@pikku/core'\n${fullImportStatement}\npikkuState('function', 'meta', metaData as FunctionsMeta)`
-    )
+    const packageName = config.externalPackageName
+      ? `'${config.externalPackageName}'`
+      : 'null'
 
-    const runtimeMeta = generateRuntimeMeta(functions.meta)
     await writeFileInDir(
       logger,
-      functionsMetaMinJsonFile,
-      JSON.stringify(runtimeMeta, null, 2)
+      functionsMetaFile,
+      `import { pikkuState, FunctionsMeta } from '@pikku/core'\n${importStatement}\npikkuState(${packageName}, 'function', 'meta', metaData as FunctionsMeta)`
     )
 
-    const minJsonImportPath = getFileImportRelativePath(
-      functionsMetaMinFile,
-      functionsMetaMinJsonFile,
-      packageMappings
-    )
+    // For external packages, register ALL functions (they'll be invoked by consumers)
+    // For main packages, only register functions that are invoked via internal RPCs
+    const isExternalPackage = !!config.externalPackageName
+    const hasRPCs = rpc.exposedFiles.size > 0 || rpc.internalFiles.size > 0
+    const hasFunctions = functions.files.size > 0
 
-    const minImportStatement = supportsImportAttributes
-      ? `import metaData from '${minJsonImportPath}' with { type: 'json' }`
-      : `import metaData from '${minJsonImportPath}'`
+    const shouldGenerateFunctionsFile = isExternalPackage
+      ? hasFunctions
+      : hasRPCs
 
-    await writeFileInDir(
-      logger,
-      functionsMetaMinFile,
-      `import { pikkuState, FunctionsRuntimeMeta } from '@pikku/core'\n${minImportStatement}\npikkuState('function', 'meta', metaData as FunctionsRuntimeMeta)`
-    )
+    if (shouldGenerateFunctionsFile) {
+      // For external packages, use all function files; for main packages, use internal RPC files
+      const filesToRegister = isExternalPackage
+        ? functions.files
+        : rpc.internalFiles
 
-    const hasRPCs = rpc.exposedFiles.size > 0 || rpc.internalFiles.size > 0
-    if (hasRPCs) {
       await writeFileInDir(
         logger,
         functionsFile,
         serializeFunctionImports(
           functionsFile,
-          rpc.internalFiles,
+          filesToRegister,
           functions.meta,
-          packageMappings
+          packageMappings,
+          config.externalPackageName
         )
       )
     }
 
-    return hasRPCs
+    return shouldGenerateFunctionsFile
   },
   middleware: [
     logCommandInfoAndTime({

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

@@ -41,7 +41,7 @@ export const serializeServicesMap = (
   })
 
   // Services that are always required internally by the framework
-  const defaultServices = ['config', 'logger', 'variables', 'schema']
+  const defaultServices = ['config', 'logger', 'variables', 'schema', 'secrets']
   defaultServices.forEach((service) => usedServices.add(service))
 
   // Create singleton services map: all singleton services with true/false based on usage

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

@@ -16,6 +16,7 @@ export const pikkuFunctionTypes: any = pikkuSessionlessFunc<void, void>({
       queueTypesFile,
       mcpTypesFile,
       cliTypesFile,
+      forgeTypesFile,
     } = config
 
     const content = serializePikkuTypesHub(
@@ -29,7 +30,8 @@ export const pikkuFunctionTypes: any = pikkuSessionlessFunc<void, void>({
       ),
       getFileImportRelativePath(typesFile, queueTypesFile, packageMappings),
       getFileImportRelativePath(typesFile, mcpTypesFile, packageMappings),
-      getFileImportRelativePath(typesFile, cliTypesFile, packageMappings)
+      getFileImportRelativePath(typesFile, cliTypesFile, packageMappings),
+      getFileImportRelativePath(typesFile, forgeTypesFile, packageMappings)
     )
 
     await writeFileInDir(logger, typesFile, content)

package/src/functions/wirings/functions/schemas.ts

@@ -2,11 +2,12 @@ import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
 import {
   saveSchemas,
   generateSchemas,
+  generateZodSchemas,
 } from '../../../utils/schema-generator.js'
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
 
 /**
- * Generate JSON schemas from TypeScript types
+ * Generate JSON schemas from TypeScript types and Zod schemas
  */
 export const pikkuSchemas: any = pikkuSessionlessFunc<
   void,
@@ -22,17 +23,26 @@ export const pikkuSchemas: any = pikkuSessionlessFunc<
       visitState.functions.meta,
       visitState.http.meta,
       config.schemasFromTypes,
-      config.schema?.additionalProperties
+      config.schema?.additionalProperties,
+      visitState.zodLookup
+    )
+
+    const zodSchemas = await generateZodSchemas(
+      logger,
+      visitState.zodLookup,
+      visitState.functions.typesMap
     )
 
     await saveSchemas(
       logger,
       config.schemaDirectory,
-      schemas,
+      { ...schemas, ...zodSchemas},
       visitState.functions.typesMap,
       visitState.functions.meta,
       config.schema?.supportsImportAttributes || true,
-      config.schemasFromTypes
+      config.schemasFromTypes,
+      visitState.zodLookup,
+      config.externalPackageName || null
     )
 
     return true

package/src/functions/wirings/functions/serialize-function-imports.ts

@@ -5,7 +5,9 @@ export const serializeFunctionImports = (
   outputPath: string,
   functionsMap: Map<string, { path: string; exportedName: string }>,
   functionsMeta: FunctionsMeta,
-  packageMappings: Record<string, string> = {}
+  packageMappings: Record<string, string> = {},
+  /** Package name for external packages (e.g., '@pikku/templates-function-external') */
+  externalPackageName?: string
 ) => {
   const serializedImports: string[] = [
     `/* Import and register functions used by RPCs */`,
@@ -19,6 +21,9 @@ export const serializeFunctionImports = (
     a[0].localeCompare(b[0])
   )
 
+  // Third argument to addFunction is the package name (null for main package)
+  const packageArg = externalPackageName ? `, '${externalPackageName}'` : ''
+
   for (const [name, { path, exportedName }] of sortedEntries) {
     const filePath = getFileImportRelativePath(
       outputPath,
@@ -30,14 +35,18 @@ export const serializeFunctionImports = (
     // For directly exported functions, we can just import and register them
     if (name === exportedName) {
       serializedImports.push(`import { ${exportedName} } from '${filePath}'`)
-      serializedRegistrations.push(`addFunction('${name}', ${exportedName})`)
+      serializedRegistrations.push(
+        `addFunction('${name}', ${exportedName}${packageArg})`
+      )
     }
     // For renamed functions, we need to import and alias them
     else {
       serializedImports.push(
         `import { ${exportedName} as ${name} } from '${filePath}'`
       )
-      serializedRegistrations.push(`addFunction('${name}', ${name})`)
+      serializedRegistrations.push(
+        `addFunction('${name}', ${name}${packageArg})`
+      )
     }
   }