@pikku/cli 0.12.85 → 0.12.88

package/dist/src/functions/wirings/realtime/pikku-command-events-scaffold.js

@@ -2,10 +2,13 @@ import { pikkuSessionlessFunc } from '#pikku';
 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 { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializeEventsScaffold } from './serialize-events-scaffold.js';
 export const pikkuEventsScaffold = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
-        if (!config.scaffold?.events || !config.eventsChannelFile) {
+        if (!config.scaffold?.events ||
+            !config.eventsChannelFile ||
+            !config.eventsSchemasFile) {
             logger.debug({
                 message: 'Skipping events scaffold (set scaffold.events in pikku.config.json to enable).',
                 type: 'skip',
@@ -14,7 +17,10 @@ export const pikkuEventsScaffold = pikkuSessionlessFunc({
         }
         const authRequired = config.scaffold.events === 'auth';
         const pikkuTypesImportPath = getFileImportRelativePath(config.eventsChannelFile, config.typesDeclarationFile, config.packageMappings);
-        await writeFileInDir(logger, config.eventsChannelFile, serializeEventsScaffold(authRequired, pikkuTypesImportPath));
+        const { schemas, functions } = serializeEventsScaffold(authRequired, pikkuTypesImportPath);
+        await writeFileInDir(logger, config.eventsSchemasFile, schemas);
+        await writeFileInDir(logger, config.eventsChannelFile, functions);
+        await removeLegacyScaffoldFile(config.eventsChannelFile);
         return true;
     },
     middleware: [

package/dist/src/functions/wirings/realtime/serialize-events-scaffold.d.ts

@@ -1,3 +1,7 @@
+export interface EventsGenOutput {
+    schemas: string;
+    functions: string;
+}
 /**
  * Generates the server-side `events.gen.ts` scaffold.
  *
@@ -16,8 +20,5 @@
  * Both routes call `eventHub.subscribe`/`unsubscribe` with the channel id;
  * publish-side ergonomics (envelope shape) are documented in the
  * pikku-realtime skill.
- *
- * Uses TypeScript generics (not named Zod schema constants) so schemas and
- * wiring calls can safely coexist in a single generated file.
  */
-export declare const serializeEventsScaffold: (authRequired: boolean, pikkuTypesImportPath: string) => string;
+export declare const serializeEventsScaffold: (authRequired: boolean, pikkuTypesImportPath: string) => EventsGenOutput;

package/dist/src/functions/wirings/realtime/serialize-events-scaffold.js

@@ -16,19 +16,25 @@
  * Both routes call `eventHub.subscribe`/`unsubscribe` with the channel id;
  * publish-side ergonomics (envelope shape) are documented in the
  * pikku-realtime skill.
- *
- * Uses TypeScript generics (not named Zod schema constants) so schemas and
- * wiring calls can safely coexist in a single generated file.
  */
 export const serializeEventsScaffold = (authRequired, pikkuTypesImportPath) => {
     const auth = authRequired ? 'true' : 'false';
-    return `import {
+    const schemas = `/**
+ * Auto-generated realtime event schemas
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { z } from 'zod'
+
+export const TopicRef = z.object({ topic: z.string() })
+`;
+    const functions = `import {
   pikkuChannelFunc,
   pikkuSessionlessFunc,
   wireChannel,
   wireHTTP,
   defineChannelRoutes,
 } from '${pikkuTypesImportPath}'
+import { TopicRef } from './events.schemas.gen.js'
 
 /**
  * Topic envelope clients receive: \`{ topic, data }\`. Functions that publish
@@ -40,13 +46,15 @@ export const serializeEventsScaffold = (authRequired, pikkuTypesImportPath) => {
  * the duplication; pick whichever style your project prefers.
  */
 
-export const realtimeSubscribe = pikkuChannelFunc<{ topic: string }>({
+export const realtimeSubscribe = pikkuChannelFunc({
+  input: TopicRef,
   func: async ({ eventHub }, { topic }, { channel }) => {
     await eventHub?.subscribe(topic, channel.channelId)
   },
 })
 
-export const realtimeUnsubscribe = pikkuChannelFunc<{ topic: string }>({
+export const realtimeUnsubscribe = pikkuChannelFunc({
+  input: TopicRef,
   func: async ({ eventHub }, { topic }, { channel }) => {
     await eventHub?.unsubscribe(topic, channel.channelId)
   },
@@ -74,7 +82,8 @@ wireChannel({
  * SSE per-topic stream. One connection = one subscription. The eventHub
  * cleans up automatically when the channel closes (onChannelClosed).
  */
-export const realtimeEventStream = pikkuSessionlessFunc<{ topic: string }, void>({
+export const realtimeEventStream = pikkuSessionlessFunc({
+  input: TopicRef,
   description: 'Auto-generated SSE stream for a single event-hub topic',
   func: async ({ eventHub }, { topic }, { channel }) => {
     if (!channel) {
@@ -95,4 +104,5 @@ wireHTTP({
   tags: ['pikku:realtime', 'sse'],
 })
 `;
+    return { schemas, functions };
 };

package/dist/src/functions/wirings/rpc/pikku-command-public-rpc.js

@@ -2,6 +2,7 @@ import { pikkuSessionlessFunc } from '#pikku';
 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 { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializePublicRPC } from './serialize-public-rpc.js';
 export const pikkuPublicRPC = pikkuSessionlessFunc({
     func: async ({ logger, config, variables }) => {
@@ -9,9 +10,12 @@ export const pikkuPublicRPC = pikkuSessionlessFunc({
         if (deployCodegenFlag === '1') {
             return false;
         }
-        if (config.scaffold?.rpc) {
+        if (config.scaffold?.rpc && config.publicRpcSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.publicRpcFile, config.typesDeclarationFile, config.packageMappings);
-            await writeFileInDir(logger, config.publicRpcFile, serializePublicRPC(pathToPikkuTypes, config.scaffold.rpc === 'auth', config.globalHTTPPrefix || ''));
+            const { schemas, functions } = serializePublicRPC(pathToPikkuTypes, config.scaffold.rpc === 'auth', config.globalHTTPPrefix || '');
+            await writeFileInDir(logger, config.publicRpcSchemasFile, schemas);
+            await writeFileInDir(logger, config.publicRpcFile, functions);
+            await removeLegacyScaffoldFile(config.publicRpcFile);
             return true;
         }
         return false;

package/dist/src/functions/wirings/rpc/pikku-command-remote-rpc.js

@@ -2,6 +2,7 @@ import { pikkuSessionlessFunc } from '#pikku';
 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 { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializeRemoteRPC } from './serialize-remote-rpc.js';
 export const pikkuRemoteRPC = pikkuSessionlessFunc({
     func: async ({ logger, config, variables }) => {
@@ -9,9 +10,12 @@ export const pikkuRemoteRPC = pikkuSessionlessFunc({
         if (deployCodegenFlag === '1') {
             return false;
         }
-        if (config.remoteRpcWorkersFile) {
+        if (config.remoteRpcWorkersFile && config.remoteRpcSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.remoteRpcWorkersFile, config.typesDeclarationFile, config.packageMappings);
-            await writeFileInDir(logger, config.remoteRpcWorkersFile, serializeRemoteRPC(pathToPikkuTypes));
+            const { schemas, functions } = serializeRemoteRPC(pathToPikkuTypes);
+            await writeFileInDir(logger, config.remoteRpcSchemasFile, schemas);
+            await writeFileInDir(logger, config.remoteRpcWorkersFile, functions);
+            await removeLegacyScaffoldFile(config.remoteRpcWorkersFile);
             return true;
         }
         return false;

package/dist/src/functions/wirings/rpc/serialize-public-rpc.d.ts

@@ -1,4 +1,8 @@
+export interface PublicRPCGenOutput {
+    schemas: string;
+    functions: string;
+}
 /**
  * Generate public RPC HTTP endpoint
  */
-export declare const serializePublicRPC: (pathToPikkuTypes: string, requireAuth?: boolean, globalHTTPPrefix?: string) => string;
+export declare const serializePublicRPC: (pathToPikkuTypes: string, requireAuth?: boolean, globalHTTPPrefix?: string) => PublicRPCGenOutput;

package/dist/src/functions/wirings/rpc/serialize-public-rpc.js

@@ -3,18 +3,28 @@
  */
 export const serializePublicRPC = (pathToPikkuTypes, requireAuth = true, globalHTTPPrefix = '') => {
     const authFlag = requireAuth ? 'true' : 'false';
-    return `/**
+    const schemas = `/**
+ * Auto-generated public RPC endpoint schemas
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { z } from 'zod'
+
+export const RPCCall = z.object({
+  rpcName: z.string(),
+  data: z.unknown().optional(),
+})
+`;
+    const functions = `/**
  * Auto-generated public RPC HTTP endpoint
  * Do not edit manually - regenerate with 'npx pikku'
  */
 import { pikkuSessionlessFunc, wireHTTP } from '${pathToPikkuTypes}'
+import { RPCCall } from './rpc-public.schemas.gen.js'
 
-export const rpcCaller = pikkuSessionlessFunc<
-  { rpcName: string; data?: unknown },
-  unknown
->({
+export const rpcCaller = pikkuSessionlessFunc({
   tags: ['pikku'],
   auth: ${authFlag},
+  input: RPCCall,
   func: async (_services, { rpcName, data }, { rpc }) => {
     return await rpc.exposed(rpcName, data)
   },
@@ -28,4 +38,5 @@ wireHTTP({
   func: rpcCaller,
 })
 `;
+    return { schemas, functions };
 };

package/dist/src/functions/wirings/rpc/serialize-remote-rpc.d.ts

@@ -1,4 +1,8 @@
+export interface RemoteRPCGenOutput {
+    schemas: string;
+    functions: string;
+}
 /**
  * Generate remote internal RPC queue worker and HTTP endpoint
  */
-export declare const serializeRemoteRPC: (pathToPikkuTypes: string) => string;
+export declare const serializeRemoteRPC: (pathToPikkuTypes: string) => RemoteRPCGenOutput;

package/dist/src/functions/wirings/rpc/serialize-remote-rpc.js

@@ -2,18 +2,28 @@
  * Generate remote internal RPC queue worker and HTTP endpoint
  */
 export const serializeRemoteRPC = (pathToPikkuTypes) => {
-    return `/**
+    const schemas = `/**
+ * Auto-generated remote internal RPC schemas
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { z } from 'zod'
+
+export const RemoteRPCCall = z.object({
+  rpcName: z.string(),
+  data: z.unknown().optional(),
+})
+`;
+    const functions = `/**
  * Auto-generated remote internal RPC queue worker and HTTP endpoint
  * Do not edit manually - regenerate with 'npx pikku'
  */
 import { pikkuSessionlessFunc, wireHTTP, wireQueueWorker } from '${pathToPikkuTypes}'
 import { pikkuRemoteAuthMiddleware } from '@pikku/core/middleware'
+import { RemoteRPCCall } from './rpc-remote.schemas.gen.js'
 
-export const remoteRPCHandler = pikkuSessionlessFunc<
-  { rpcName: string, data?: unknown },
-  unknown
->({
+export const remoteRPCHandler = pikkuSessionlessFunc({
   tags: ['pikku'],
+  input: RemoteRPCCall,
   func: async (_services, { rpcName, data }, { rpc }) => {
     return await (rpc.invoke as any)(rpcName, data)
   },
@@ -35,4 +45,5 @@ wireHTTP({
   func: remoteRPCHandler,
 })
 `;
+    return { schemas, functions };
 };

package/dist/src/functions/wirings/scenarios/pikku-command-scenario-functions.js

@@ -2,6 +2,7 @@ import { pikkuSessionlessFunc } from '#pikku';
 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 { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializeScenarioFunctions } from './serialize-scenario-functions.js';
 export const pikkuScenarioFunctions = pikkuSessionlessFunc({
     func: async ({ logger, config, variables }) => {
@@ -9,9 +10,14 @@ export const pikkuScenarioFunctions = pikkuSessionlessFunc({
         if (deployCodegenFlag === '1') {
             return false;
         }
-        if (config.scaffold?.scenarios && config.scenariosFunctionsFile) {
+        if (config.scaffold?.scenarios &&
+            config.scenariosFunctionsFile &&
+            config.scenariosSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.scenariosFunctionsFile, config.typesDeclarationFile, config.packageMappings);
-            await writeFileInDir(logger, config.scenariosFunctionsFile, serializeScenarioFunctions(pathToPikkuTypes, config.scaffold.scenarios === 'auth'));
+            const { schemas, functions } = serializeScenarioFunctions(pathToPikkuTypes, config.scaffold.scenarios === 'auth');
+            await writeFileInDir(logger, config.scenariosSchemasFile, schemas);
+            await writeFileInDir(logger, config.scenariosFunctionsFile, functions);
+            await removeLegacyScaffoldFile(config.scenariosFunctionsFile);
             return true;
         }
         return false;

package/dist/src/functions/wirings/scenarios/serialize-scenario-functions.d.ts

@@ -1,6 +1,10 @@
+export interface ScenarioGenOutput {
+    schemas: string;
+    functions: string;
+}
 /**
  * Generate the scenario instrumentation functions (`pikku scenario` coverage
  * snapshots and stub-call inspection) into the project scaffold, so scenario
  * runs work against any server without requiring the console addon.
  */
-export declare const serializeScenarioFunctions: (pathToPikkuTypes: string, requireAuth?: boolean) => string;
+export declare const serializeScenarioFunctions: (pathToPikkuTypes: string, requireAuth?: boolean) => ScenarioGenOutput;

package/dist/src/functions/wirings/scenarios/serialize-scenario-functions.js

@@ -5,7 +5,19 @@
  */
 export const serializeScenarioFunctions = (pathToPikkuTypes, requireAuth = true) => {
     const authFlag = requireAuth ? 'true' : 'false';
-    return `/**
+    const schemas = `/**
+ * Auto-generated scenario instrumentation schemas
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { z } from 'zod'
+
+export const StubCallsQuery = z.object({
+  service: z.string().optional(),
+})
+
+export const Enabled = z.object({ enabled: z.boolean() })
+`;
+    const functions = `/**
  * Auto-generated scenario instrumentation functions
  * Do not edit manually - regenerate with 'npx pikku'
  */
@@ -16,14 +28,10 @@ import {
   getStubTracker,
   isTestRun,
   type CoverageFunctionMeta,
-  type FunctionCoverageReport,
-  type StubCall,
 } from '@pikku/core/services'
+import { StubCallsQuery, Enabled } from './scenarios.schemas.gen.js'
 
-export const pikkuScenarioTakeLiveCoverage = pikkuFunc<
-  null,
-  FunctionCoverageReport | null
->({
+export const pikkuScenarioTakeLiveCoverage = pikkuFunc({
   tags: ['pikku'],
   title: 'Take Live Coverage',
   description:
@@ -50,16 +58,14 @@ export const pikkuScenarioTakeLiveCoverage = pikkuFunc<
   },
 })
 
-export const pikkuScenarioResetLiveCoverage = pikkuFunc<
-  null,
-  { enabled: boolean }
->({
+export const pikkuScenarioResetLiveCoverage = pikkuFunc({
   tags: ['pikku'],
   title: 'Reset Live Coverage',
   description:
     'Clears V8 precise-coverage call counts so the next takeLiveCoverage snapshot is attributable to a single scenario run. Reports enabled: false when the server was not started with coverage enabled.',
   expose: true,
   auth: ${authFlag},
+  output: Enabled,
   func: async ({ coverageService }) => {
     if (!coverageService) return { enabled: false }
     await coverageService.reset()
@@ -67,32 +73,32 @@ export const pikkuScenarioResetLiveCoverage = pikkuFunc<
   },
 })
 
-export const pikkuScenarioResetStubs = pikkuFunc<null, { enabled: boolean }>({
+export const pikkuScenarioResetStubs = pikkuFunc({
   tags: ['pikku'],
   title: 'Reset Stubs',
   description:
     'Clears recorded stub calls so the next getStubCalls result is attributable to a single scenario run. Reports enabled: false when the server was not started in test mode.',
   expose: true,
   auth: ${authFlag},
+  output: Enabled,
   func: async () => {
     getStubTracker().reset()
     return { enabled: isTestRun() }
   },
 })
 
-export const pikkuScenarioGetStubCalls = pikkuFunc<
-  { service?: string },
-  StubCall[]
->({
+export const pikkuScenarioGetStubCalls = pikkuFunc({
   tags: ['pikku'],
   title: 'Get Stub Calls',
   description:
     'Returns calls recorded against stubbed/spied services (via the stub()/spy() core utils). Empty unless the server records service calls (pikku dev --test).',
   expose: true,
   auth: ${authFlag},
+  input: StubCallsQuery,
   func: async (_services, data) => {
     return getStubTracker().getCalls(data?.service ?? undefined)
   },
 })
 `;
+    return { schemas, functions };
 };

package/dist/src/functions/wirings/user-admin/pikku-command-user-admin-functions.d.ts

@@ -0,0 +1 @@
+export declare const pikkuUserAdminFunctions: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/wirings/user-admin/pikku-command-user-admin-functions.js

@@ -0,0 +1,49 @@
+import { pikkuSessionlessFunc } from '#pikku';
+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 { serializeUserAdminFunctions } from './serialize-user-admin-functions.js';
+export const pikkuUserAdminFunctions = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }) => {
+        if (!config.scaffold?.userAdmin ||
+            !config.userAdminFunctionsFile ||
+            !config.userAdminSchemasFile) {
+            logger.debug({
+                message: 'Skipping user admin scaffold (set scaffold.userAdmin in pikku.config.json to enable).',
+                type: 'skip',
+            });
+            return false;
+        }
+        const { definition } = (await getInspectorState()).auth;
+        // These functions are thin wrappers over better-auth's admin() endpoints.
+        // Without that plugin the endpoints do not exist, so the scaffold would
+        // generate four RPCs that throw on every call and four scopes that grant
+        // nothing. Fail the codegen instead of shipping that.
+        if (!definition) {
+            throw new Error(`"scaffold.userAdmin" is enabled but no pikkuBetterAuth(...) was found in the project.\n` +
+                `User management wraps better-auth's admin() endpoints, so there is nothing to wrap.\n` +
+                `Fix: set up Better Auth before scaffolding user management, or remove ` +
+                `"scaffold.userAdmin" from pikku.config.json.`);
+        }
+        if (!definition.plugins.includes('admin')) {
+            throw new Error(`"scaffold.userAdmin" is enabled but better-auth is configured without the admin() plugin.\n` +
+                `Ban, delete, session-revocation and set-password are implemented by that plugin — without it ` +
+                `the generated functions would fail on every call.\n` +
+                `Fix: add admin() to the plugins array in ${definition.sourceFile}:\n` +
+                `  import { admin } from 'better-auth/plugins'\n` +
+                `  betterAuth({ plugins: [admin()] })\n` +
+                `Then re-run codegen. Or remove "scaffold.userAdmin" from pikku.config.json.`);
+        }
+        const pathToPikkuTypes = getFileImportRelativePath(config.userAdminFunctionsFile, config.typesDeclarationFile, config.packageMappings);
+        const { schemas, functions } = serializeUserAdminFunctions(pathToPikkuTypes, config.scaffold.userAdmin === 'auth');
+        await writeFileInDir(logger, config.userAdminSchemasFile, schemas);
+        await writeFileInDir(logger, config.userAdminFunctionsFile, functions);
+        return true;
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Generating user management functions',
+            commandEnd: 'Generated user management functions',
+        }),
+    ],
+});

package/dist/src/functions/wirings/user-admin/serialize-user-admin-functions.d.ts

@@ -0,0 +1,24 @@
+export interface UserAdminGenOutput {
+    schemas: string;
+    functions: string;
+}
+/**
+ * Generate the user-management functions into the project scaffold: the
+ * directory read plus the writes that wrap better-auth's `admin()` endpoints.
+ *
+ * Scaffolded rather than shipped in an addon because managing users is ordinary
+ * application behaviour: an app should not have to install the console — which
+ * exists to be served alongside a running dev server — just to list or ban its
+ * own users. The console UI calls these same functions when it is present.
+ *
+ * Each function is gated on its own `admin:users:*` scope. The writes are only
+ * meaningful where `admin()` is wired, which is why this file is generated only
+ * in that case.
+ *
+ * Emitted as two files. The schemas are zod, and the inspector reads a zod
+ * schema by importing the module that declares it — which it cannot do for the
+ * functions file, whose relative pikku-types import per-unit deploy codegen
+ * rewrites. Keeping the schemas in a sibling module that imports nothing but
+ * zod sidesteps that entirely.
+ */
+export declare const serializeUserAdminFunctions: (pathToPikkuTypes: string, requireAuth?: boolean) => UserAdminGenOutput;