@pikku/cli 0.11.2 → 0.11.3

package/dist/src/functions/runtimes/nextjs/serialize-nextjs-http-wrapper.js

@@ -7,7 +7,7 @@ export const serializeNextJsHTTPWrapper = (routesMapPath, rpcMapPath, pikkuFetch
  */
 import { CorePikkuFetchOptions } from '@pikku/fetch'
 import type { HTTPWiringsMap, HTTPWiringHandlerOf, HTTPWiringsWithMethod } from '${routesMapPath}'
-import type { RPCMap } from '${rpcMapPath}'
+import type { FlattenedRPCMap } from '${rpcMapPath}'
 import { PikkuFetch } from '${pikkuFetchImport}'
 
 let _pikku: PikkuFetch | undefined
@@ -60,14 +60,16 @@ export const pikku = (options?: CorePikkuFetchOptions) => {
    *
    * @template Route - The route key with the POST method.
    * @param route - The route identifier.
-   * @param data - The input data for the POST request, defaults to null.
+   * @param data - The input data for the POST request (required if input type is defined).
    * @returns A promise that resolves to the output of the POST handler.
    */
   const dynamicPost = <Route extends HTTPWiringsWithMethod<'POST'>>(
     route: Route,
-    data: HTTPWiringHandlerOf<Route, 'POST'>['input'] = null
+    ...args: HTTPWiringHandlerOf<Route, 'POST'>['input'] extends null | undefined
+      ? [data?: HTTPWiringHandlerOf<Route, 'POST'>['input']]
+      : [data: NonNullable<HTTPWiringHandlerOf<Route, 'POST'>['input']>]
   ): Promise<HTTPWiringHandlerOf<Route, 'POST'>['output']> => {
-    return dynamicActionRequest(route, 'POST', data)
+    return dynamicActionRequest(route, 'POST', args[0] ?? null)
   }
 
   /**
@@ -75,14 +77,16 @@ export const pikku = (options?: CorePikkuFetchOptions) => {
    *
    * @template Route - The route key with the GET method.
    * @param route - The route identifier.
-   * @param data - The input data for the GET request, defaults to null.
+   * @param data - The input data for the GET request (required if input type is defined).
    * @returns A promise that resolves to the output of the GET handler.
    */
   const dynamicGet = <Route extends HTTPWiringsWithMethod<'GET'>>(
     route: Route,
-    data: HTTPWiringHandlerOf<Route, 'GET'>['input'] = null
+    ...args: HTTPWiringHandlerOf<Route, 'GET'>['input'] extends null | undefined
+      ? [data?: HTTPWiringHandlerOf<Route, 'GET'>['input']]
+      : [data: NonNullable<HTTPWiringHandlerOf<Route, 'GET'>['input']>]
   ): Promise<HTTPWiringHandlerOf<Route, 'GET'>['output']> => {
-    return dynamicActionRequest(route, 'GET', data)
+    return dynamicActionRequest(route, 'GET', args[0] ?? null)
   }
 
   /**
@@ -90,14 +94,16 @@ export const pikku = (options?: CorePikkuFetchOptions) => {
    *
    * @template Route - The route key with the PATCH method.
    * @param route - The route identifier.
-   * @param data - The input data for the PATCH request, defaults to null.
+   * @param data - The input data for the PATCH request (required if input type is defined).
    * @returns A promise that resolves to the output of the PATCH handler.
    */
   const dynamicPatch = <Route extends HTTPWiringsWithMethod<'PATCH'>>(
     route: Route,
-    data: HTTPWiringHandlerOf<Route, 'PATCH'>['input'] = null
+    ...args: HTTPWiringHandlerOf<Route, 'PATCH'>['input'] extends null | undefined
+      ? [data?: HTTPWiringHandlerOf<Route, 'PATCH'>['input']]
+      : [data: NonNullable<HTTPWiringHandlerOf<Route, 'PATCH'>['input']>]
   ): Promise<HTTPWiringHandlerOf<Route, 'PATCH'>['output']> => {
-    return dynamicActionRequest(route, 'PATCH', data)
+    return dynamicActionRequest(route, 'PATCH', args[0] ?? null)
   }
 
   /**
@@ -105,14 +111,16 @@ export const pikku = (options?: CorePikkuFetchOptions) => {
    *
    * @template Route - The route key with the DELETE method.
    * @param route - The route identifier.
-   * @param data - The input data for the DELETE request, defaults to null.
+   * @param data - The input data for the DELETE request (required if input type is defined).
    * @returns A promise that resolves to the output of the DELETE handler.
    */
   const dynamicDel = <Route extends HTTPWiringsWithMethod<'DELETE'>>(
     route: Route,
-    data: HTTPWiringHandlerOf<Route, 'DELETE'>['input'] = null
+    ...args: HTTPWiringHandlerOf<Route, 'DELETE'>['input'] extends null | undefined
+      ? [data?: HTTPWiringHandlerOf<Route, 'DELETE'>['input']]
+      : [data: NonNullable<HTTPWiringHandlerOf<Route, 'DELETE'>['input']>]
   ): Promise<HTTPWiringHandlerOf<Route, 'DELETE'>['output']> => {
-    return dynamicActionRequest(route, 'DELETE', data)
+    return dynamicActionRequest(route, 'DELETE', args[0] ?? null)
   }
 
   // Static Requests
@@ -122,14 +130,16 @@ export const pikku = (options?: CorePikkuFetchOptions) => {
    *
    * @template Route - The route key with the POST method.
    * @param route - The route identifier.
-   * @param data - The input data for the POST request, defaults to null.
+   * @param data - The input data for the POST request (required if input type is defined).
    * @returns A promise that resolves to the output of the POST handler.
    */
   const staticPost = <Route extends HTTPWiringsWithMethod<'POST'>>(
     route: Route,
-    data: HTTPWiringHandlerOf<Route, 'POST'>['input'] = null
+    ...args: HTTPWiringHandlerOf<Route, 'POST'>['input'] extends null | undefined
+      ? [data?: HTTPWiringHandlerOf<Route, 'POST'>['input']]
+      : [data: NonNullable<HTTPWiringHandlerOf<Route, 'POST'>['input']>]
   ): Promise<HTTPWiringHandlerOf<Route, 'POST'>['output']> => {
-    return staticActionRequest(route, 'POST', data)
+    return staticActionRequest(route, 'POST', args[0] ?? null)
   }
 
   /**
@@ -137,49 +147,53 @@ export const pikku = (options?: CorePikkuFetchOptions) => {
    *
    * @template Route - The route key with the GET method.
    * @param route - The route identifier.
-   * @param data - The input data for the GET request, defaults to null.
+   * @param data - The input data for the GET request (required if input type is defined).
    * @returns A promise that resolves to the output of the GET handler.
    */
   const staticGet = <Route extends HTTPWiringsWithMethod<'GET'>>(
     route: Route,
-    data: HTTPWiringHandlerOf<Route, 'GET'>['input'] = null
+    ...args: HTTPWiringHandlerOf<Route, 'GET'>['input'] extends null | undefined
+      ? [data?: HTTPWiringHandlerOf<Route, 'GET'>['input']]
+      : [data: NonNullable<HTTPWiringHandlerOf<Route, 'GET'>['input']>]
   ): Promise<HTTPWiringHandlerOf<Route, 'GET'>['output']> => {
-    return staticActionRequest(route, 'GET', data)
+    return staticActionRequest(route, 'GET', args[0] ?? null)
   }
 
   // RPC Requests
 
-  /**
-   * Type definition for RPC invocation.
-   */
-  type RPCInvoke = <Name extends keyof RPCMap>(
-    name: Name,
-    data: RPCMap[Name]['input']
-  ) => Promise<RPCMap[Name]['output']>
-
   /**
    * Makes a dynamic RPC request.
    *
-   * @template Name - The RPC function name from the RPCMap.
+   * @template Name - The RPC function name from the FlattenedRPCMap.
    * @param name - The RPC function identifier.
-   * @param data - The input data for the RPC request.
+   * @param data - The input data for the RPC request (required if input type is defined).
    * @returns A promise that resolves to the output of the RPC handler.
    */
-  const rpc: RPCInvoke = async (rpcName, data) => {
-    return dynamicActionRequest(\`/rpc/\${rpcName}\` as any, 'POST', { data }) as any
+  const rpc = async <Name extends keyof FlattenedRPCMap>(
+    rpcName: Name,
+    ...args: FlattenedRPCMap[Name]['input'] extends null | undefined
+      ? [data?: FlattenedRPCMap[Name]['input']]
+      : [data: NonNullable<FlattenedRPCMap[Name]['input']>]
+  ): Promise<FlattenedRPCMap[Name]['output']> => {
+    return dynamicActionRequest('/rpc/:rpcName' as '/rpc/:rpcName', 'POST', { rpcName, data: args[0] ?? null }) as unknown as FlattenedRPCMap[Name]['output']
   }
 
   /**
    * Makes a static RPC request.
    * Note: In HTTP wrapper context, both rpc and rpcStatic behave the same way.
    *
-   * @template Name - The RPC function name from the RPCMap.
+   * @template Name - The RPC function name from the FlattenedRPCMap.
    * @param name - The RPC function identifier.
-   * @param data - The input data for the RPC request.
+   * @param data - The input data for the RPC request (required if input type is defined).
    * @returns A promise that resolves to the output of the RPC handler.
    */
-  const staticRPC: RPCInvoke = async (rpcName, data) => {
-    return staticActionRequest(\`/rpc/\${rpcName}\` as any, 'POST', { data }) as any
+  const staticRPC = async <Name extends keyof FlattenedRPCMap>(
+    rpcName: Name,
+    ...args: FlattenedRPCMap[Name]['input'] extends null | undefined
+      ? [data?: FlattenedRPCMap[Name]['input']]
+      : [data: NonNullable<FlattenedRPCMap[Name]['input']>]
+  ): Promise<FlattenedRPCMap[Name]['output']> => {
+    return staticActionRequest('/rpc/:rpcName' as '/rpc/:rpcName', 'POST', { rpcName, data: args[0] ?? null }) as unknown as FlattenedRPCMap[Name]['output']
   }
 
   return {

package/dist/src/functions/wirings/channels/pikku-channels.js

@@ -15,7 +15,7 @@ export const pikkuChannels = pikkuVoidFunc({
         const importStatement = supportsImportAttributes
             ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
             : `import metaData from '${jsonImportPath}'`;
-        await writeFileInDir(logger, channelsWiringMetaFile, `import { pikkuState } from '@pikku/core'\nimport { ChannelsMeta } from '@pikku/core/channel'\n${importStatement}\npikkuState('channel', 'meta', metaData as ChannelsMeta)`);
+        await writeFileInDir(logger, channelsWiringMetaFile, `import { pikkuState } from '@pikku/core'\nimport { ChannelsMeta } from '@pikku/core/channel'\n${importStatement}\npikkuState(null, 'channel', 'meta', metaData as ChannelsMeta)`);
     },
     middleware: [
         logCommandInfoAndTime({

package/dist/src/functions/wirings/channels/pikku-command-channels.js

@@ -2,13 +2,29 @@ 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 { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { stripVerboseFields, hasVerboseFields, } from '../../../utils/strip-verbose-meta.js';
 export const pikkuChannels = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const visitState = await getInspectorState();
-        const { channelsWiringFile, channelsWiringMetaFile, packageMappings } = config;
+        const { channelsWiringFile, channelsWiringMetaFile, channelsWiringMetaJsonFile, packageMappings, schema, } = config;
         const { channels } = visitState;
         await writeFileInDir(logger, channelsWiringFile, serializeFileImports('addChannel', channelsWiringFile, channels.files, packageMappings));
-        await writeFileInDir(logger, channelsWiringMetaFile, `import { pikkuState } from '@pikku/core'\npikkuState('channel', 'meta', ${JSON.stringify(channels.meta, null, 2)})`);
+        // Write minimal JSON (runtime-only fields)
+        const minimalMeta = stripVerboseFields(channels.meta);
+        await writeFileInDir(logger, channelsWiringMetaJsonFile, JSON.stringify(minimalMeta, null, 2));
+        // Write verbose JSON only if it has additional fields
+        if (hasVerboseFields(channels.meta)) {
+            const verbosePath = channelsWiringMetaJsonFile.replace(/\.gen\.json$/, '-verbose.gen.json');
+            await writeFileInDir(logger, verbosePath, JSON.stringify(channels.meta, null, 2));
+        }
+        // Generate TypeScript file that imports the minimal JSON
+        const jsonImportPath = getFileImportRelativePath(channelsWiringMetaFile, channelsWiringMetaJsonFile, packageMappings);
+        const supportsImportAttributes = schema?.supportsImportAttributes ?? false;
+        const importStatement = supportsImportAttributes
+            ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
+            : `import metaData from '${jsonImportPath}'`;
+        await writeFileInDir(logger, channelsWiringMetaFile, `import { pikkuState } from '@pikku/core'\nimport type { ChannelsMeta } from '@pikku/core/channel'\n${importStatement}\npikkuState(null, 'channel', 'meta', metaData as ChannelsMeta)`);
         return true;
     },
     middleware: [

package/dist/src/functions/wirings/channels/serialize-channel-types.js

@@ -10,6 +10,12 @@ export const serializeChannelTypes = (functionTypesImportPath) => {
 import { CoreChannel, wireChannel as wireChannelCore } from '@pikku/core/channel'
 import { AssertHTTPWiringParams } from '@pikku/core/http'
 import type { PikkuFunctionConfig, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware } from '${functionTypesImportPath}'
+import type { ZodLike, CorePermissionGroup } from '@pikku/core'
+
+/**
+ * Helper type to infer the output type from a Zod schema
+ */
+type InferZodOutput<T> = T extends ZodLike<infer U> ? U : never
 
 /**
  * Type definition for WebSocket channels with typed data exchange.
@@ -60,21 +66,72 @@ export const pikkuChannelDisconnectionFunc = (
   return typeof func === 'function' ? { func } : func
 }
 
+/**
+ * Configuration object for channel functions with Zod schema validation.
+ */
+type PikkuChannelFuncConfigWithSchema<
+  InputSchema extends ZodLike,
+  OutputSchema extends ZodLike | undefined = undefined
+> = {
+  name?: string
+  tags?: string[]
+  expose?: boolean
+  internal?: boolean
+  func: PikkuFunctionSessionless<
+    InferZodOutput<InputSchema>,
+    OutputSchema extends ZodLike ? InferZodOutput<OutputSchema> : unknown,
+    'channel' | 'session' | 'rpc'
+  >
+  auth?: boolean
+  permissions?: CorePermissionGroup<PikkuPermission<InferZodOutput<InputSchema>>>
+  middleware?: PikkuMiddleware[]
+  input: InputSchema
+  output?: OutputSchema
+}
+
 /**
  * Creates a function that handles WebSocket channel messages.
  * Called when a message is received on a channel.
- * This is the same as pikkuSessionlessFunc but with ChannelData = unknown by default.
  *
- * @template In - Input type for channel messages
- * @template Out - Output type for channel responses
+ * Supports two patterns:
+ * 1. Generic types: \`pikkuChannelFunc<Input, Output>({ func: ... })\`
+ * 2. Zod schemas: \`pikkuChannelFunc({ input: z.object(...), func: ... })\`
+ *
+ * @template In - Input type for channel messages (inferred from schema if provided)
+ * @template Out - Output type for channel responses (inferred from schema if provided)
  * @param func - Function definition, either direct function or configuration object
  * @returns The normalized configuration object
+ *
+ * @example
+ * \`\`\`typescript
+ * // Pattern 1: Using generic types
+ * const handleMessage = pikkuChannelFunc<{text: string}, {received: boolean}>({
+ *   func: async (_services, { text }) => ({ received: true })
+ * })
+ *
+ * // Pattern 2: Using Zod schemas
+ * const messageInput = z.object({ text: z.string() })
+ * const messageOutput = z.object({ received: z.boolean() })
+ *
+ * const handleMessage = pikkuChannelFunc({
+ *   input: messageInput,
+ *   output: messageOutput,
+ *   func: async (_services, { text }) => ({ received: true })
+ * })
+ * \`\`\`
  */
-export const pikkuChannelFunc = <In, Out = unknown>(
+export function pikkuChannelFunc<
+  InputSchema extends ZodLike,
+  OutputSchema extends ZodLike | undefined = undefined
+>(
+  config: PikkuChannelFuncConfigWithSchema<InputSchema, OutputSchema>
+): PikkuFunctionConfig<InferZodOutput<InputSchema>, OutputSchema extends ZodLike ? InferZodOutput<OutputSchema> : unknown, 'channel' | 'session' | 'rpc'>
+export function pikkuChannelFunc<In, Out = unknown>(
   func:
     | PikkuFunctionSessionless<In, Out, 'channel' | 'session' | 'rpc'>
     | PikkuFunctionConfig<In, Out, 'channel' | 'session' | 'rpc'>
-) => {
+): PikkuFunctionConfig<In, Out, 'channel' | 'session' | 'rpc'>
+export function pikkuChannelFunc(func: any) {
   return typeof func === 'function' ? { func } : func
 }
 

package/dist/src/functions/wirings/channels/serialize-typed-channel-map.js

@@ -4,7 +4,6 @@ export const serializeTypedChannelsMap = (relativeToPath, packageMappings, types
     const { channels, requiredTypes } = generateChannels(functionsMeta, channelsMeta);
     typesMap.customTypes.forEach(({ references }) => {
         for (const reference of references) {
-            // Skip __object types (placeholder types for invalid/broken functions)
             if (reference !== '__object' && !reference.startsWith('__object_')) {
                 requiredTypes.add(reference);
             }
@@ -15,7 +14,7 @@ export const serializeTypedChannelsMap = (relativeToPath, packageMappings, types
     return `/**
  * This provides the structure needed for TypeScript to be aware of channels
  */
-    
+
 ${imports}
 ${serializedCustomTypes}
 

package/dist/src/functions/wirings/cli/pikku-command-cli.js

@@ -3,6 +3,7 @@ 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 { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { stripVerboseFields, hasVerboseFields, } from '../../../utils/strip-verbose-meta.js';
 export const pikkuCLI = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const visitState = await getInspectorState();
@@ -10,13 +11,20 @@ export const pikkuCLI = pikkuSessionlessFunc({
         const { cli } = visitState;
         // Generate CLI wirings file
         await writeFileInDir(logger, cliWiringsFile, serializeFileImports('wireCLI', cliWiringsFile, cli.files, packageMappings));
-        await writeFileInDir(logger, cliWiringMetaJsonFile, JSON.stringify(cli.meta, null, 2));
+        // Write minimal JSON (runtime-only fields)
+        const minimalMeta = stripVerboseFields(cli.meta);
+        await writeFileInDir(logger, cliWiringMetaJsonFile, JSON.stringify(minimalMeta, null, 2));
+        // Write verbose JSON only if it has additional fields
+        if (hasVerboseFields(cli.meta)) {
+            const verbosePath = cliWiringMetaJsonFile.replace(/\.gen\.json$/, '-verbose.gen.json');
+            await writeFileInDir(logger, verbosePath, JSON.stringify(cli.meta, null, 2));
+        }
         const jsonImportPath = getFileImportRelativePath(cliWiringMetaFile, cliWiringMetaJsonFile, packageMappings);
         const supportsImportAttributes = schema?.supportsImportAttributes ?? false;
         const importStatement = supportsImportAttributes
             ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
             : `import metaData from '${jsonImportPath}'`;
-        await writeFileInDir(logger, cliWiringMetaFile, `import { pikkuState } from '@pikku/core'\nimport { CLIMeta } from '@pikku/core/cli'\n${importStatement}\npikkuState('cli', 'meta', metaData as CLIMeta)`);
+        await writeFileInDir(logger, cliWiringMetaFile, `import { pikkuState } from '@pikku/core'\nimport { CLIMeta } from '@pikku/core/cli'\n${importStatement}\npikkuState(null, 'cli', 'meta', metaData as CLIMeta)`);
         return true;
     },
     middleware: [

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

@@ -0,0 +1 @@
+export declare const pikkuForgeNodes: any;

package/dist/src/functions/wirings/forge/pikku-command-forge-nodes.js

@@ -0,0 +1,90 @@
+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, rootDir, logger) => {
+    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 = pikkuSessionlessFunc({
+    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)) {
+                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 = {};
+        for (const [name, meta] of Object.entries(forgeNodes.meta)) {
+            // 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/dist/src/functions/wirings/forge/pikku-command-forge-types.d.ts

@@ -0,0 +1 @@
+export declare const pikkuForgeTypes: any;

package/dist/src/functions/wirings/forge/pikku-command-forge-types.js

@@ -0,0 +1,26 @@
+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 = pikkuSessionlessFunc({
+    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/dist/src/functions/wirings/forge/serialize-forge-types.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Generates type definitions for Forge wirings with typed category and RPC validation
+ */
+export declare const serializeForgeTypes: (rpcMapImportPath: string, categories: string[] | undefined) => string;

package/dist/src/functions/wirings/forge/serialize-forge-types.js

@@ -0,0 +1,90 @@
+/**
+ * Generates type definitions for Forge wirings with typed category and RPC validation
+ */
+export const serializeForgeTypes = (rpcMapImportPath, categories) => {
+    // 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/dist/src/functions/wirings/functions/pikku-command-function-types-split.js

@@ -21,7 +21,7 @@ export const pikkuFunctionTypesSplit = pikkuSessionlessFunc({
         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 } from '${getFileImportRelativePath(functionTypesFile, rpcInternalMapDeclarationFile, packageMappings)}'`, `import type { RequiredSingletonServices, RequiredWireServices } from '${getFileImportRelativePath(functionTypesFile, servicesFile, packageMappings)}'`, configTypeImport);
+        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: [

package/dist/src/functions/wirings/functions/pikku-command-function-types.js

@@ -5,8 +5,13 @@ import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-
 import { serializePikkuTypesHub } from './serialize-pikku-types-hub.js';
 export const pikkuFunctionTypes = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
-        const { typesDeclarationFile: typesFile, packageMappings, functionTypesFile, httpTypesFile, channelsTypesFile, schedulersTypesFile, queueTypesFile, mcpTypesFile, cliTypesFile, } = config;
-        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));
+        const { typesDeclarationFile: typesFile, packageMappings, functionTypesFile, httpTypesFile, channelsTypesFile, schedulersTypesFile, queueTypesFile, mcpTypesFile, cliTypesFile, forgeTypesFile, } = config;
+        const getImportPath = (file) => config.externalPackage
+            ? null
+            : getFileImportRelativePath(typesFile, file, packageMappings);
+        // Forge types are included for external packages (they need wireForgeNode/wireForgeCredential)
+        const getForgeImportPath = (file) => 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: [