@pikku/cli 0.12.85 → 0.12.88

package/dist/src/functions/wirings/user-admin/serialize-user-admin-functions.js

@@ -0,0 +1,283 @@
+/**
+ * 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 const serializeUserAdminFunctions = (pathToPikkuTypes, requireAuth = true) => {
+    const authFlag = requireAuth ? 'true' : 'false';
+    const schemas = `/**
+ * Auto-generated user management schemas
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { z } from 'zod'
+
+/**
+ * A user, as the directory sees one. Ban state is optional because those
+ * columns belong to better-auth's \`admin()\` plugin: a host without it reports
+ * no ban state at all, which a client can render as "unknown" rather than as a
+ * misleading "not banned".
+ */
+export const User = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string().optional(),
+  image: z.string().optional(),
+  createdAt: z.string().optional(),
+  banned: z.boolean().optional(),
+  banReason: z.string().optional(),
+  banExpires: z.string().optional(),
+})
+
+export const ListUsersInput = z.object({
+  search: z.string().optional(),
+  limit: z.number().int().positive().optional(),
+})
+
+export const ListUsersOutput = z.object({
+  users: z.array(User),
+})
+
+export const CreateUserInput = z.object({
+  email: z.string(),
+  password: z.string(),
+  name: z.string().optional(),
+})
+
+export const CreateUserOutput = z.object({
+  userId: z.string(),
+})
+
+/** Every write targets one user by id. */
+export const UserRef = z.object({
+  userId: z.string(),
+})
+
+export const SetUserBannedInput = z.object({
+  userId: z.string(),
+  banned: z.boolean(),
+  reason: z.string().optional(),
+  expiresInSeconds: z.number().int().positive().optional(),
+})
+
+export const SetUserPasswordInput = z.object({
+  userId: z.string(),
+  newPassword: z.string(),
+})
+
+export const Success = z.object({
+  success: z.boolean(),
+})
+`;
+    const functions = `/**
+ * Auto-generated user management functions
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { pikkuFunc, wireScope } from '${pathToPikkuTypes}'
+import { callAdminApi } from '@pikku/better-auth'
+import {
+  CreateUserInput,
+  CreateUserOutput,
+  ListUsersInput,
+  ListUsersOutput,
+  SetUserBannedInput,
+  SetUserPasswordInput,
+  Success,
+  UserRef,
+} from './user-admin.schemas.gen.js'
+
+// pikku requires every declaration of a shared scope root to be identical, so
+// this is the whole \`admin\` tree — not just the leaves gated below. It must stay
+// byte-identical to ADMIN_SCOPE_TREE in @pikku/better-auth and to the copy in
+// @pikku/addon-console, or codegen fails with conflicting declarations.
+wireScope({
+  admin: {
+    displayName: 'Administration',
+    description: 'Capabilities that act on the application as a whole',
+    scopes: {
+      impersonate: { description: 'Act as another user' },
+      credentials: {
+        description: 'Application-wide credentials',
+        scopes: {
+          link: { description: 'Bind a shared credential for every user' },
+        },
+      },
+      users: {
+        description: 'The user directory',
+        scopes: {
+          list: { description: 'List and search users' },
+          create: { description: 'Create users out of band' },
+          ban: { description: 'Ban and unban users' },
+          remove: { description: 'Delete users and all their data' },
+          sessions: { description: "Revoke a user's sessions" },
+          password: { description: "Set a user's password" },
+        },
+      },
+    },
+  },
+})
+
+/**
+ * Synthetic principals — the platform credential owner, fabric service users
+ * and agent actors — are not people, so they never belong in a directory a
+ * human picks from.
+ */
+const isPerson = (row: any) =>
+  row.fabric !== true && row.actor !== true && row.id !== 'pikku-platform'
+
+export const pikkuAdminListUsers = pikkuFunc({
+  tags: ['pikku'],
+  title: 'List Users',
+  description:
+    'Lists and searches the user directory, read through the auth adapter rather than an admin endpoint so it works on any database better-auth supports.',
+  expose: true,
+  auth: ${authFlag},
+  scopes: ['admin:users:list'],
+  input: ListUsersInput,
+  output: ListUsersOutput,
+  func: async ({ auth }, { search, limit }) => {
+    const ctx = await (await auth()).$context
+    const rows = (await ctx.adapter.findMany({
+      model: 'user',
+      limit: limit ?? 200,
+      where: search
+        ? [{ field: 'email', operator: 'contains', value: search }]
+        : undefined,
+    })) as any[]
+
+    return {
+      users: rows.filter(isPerson).map((row) => ({
+        id: row.id,
+        email: row.email,
+        name: row.name ?? undefined,
+        image: row.image ?? undefined,
+        createdAt: row.createdAt
+          ? new Date(row.createdAt).toISOString()
+          : undefined,
+        banned: typeof row.banned === 'boolean' ? row.banned : undefined,
+        banReason: row.banReason ?? undefined,
+        banExpires: row.banExpires
+          ? new Date(row.banExpires).toISOString()
+          : undefined,
+      })),
+    }
+  },
+})
+
+export const pikkuAdminCreateUser = pikkuFunc({
+  tags: ['pikku'],
+  title: 'Create User',
+  description:
+    'Creates a user directly, for provisioning an account out of band rather than through your sign-up flow. better-auth enforces the configured password bounds and rejects a duplicate email.',
+  expose: true,
+  auth: ${authFlag},
+  scopes: ['admin:users:create'],
+  input: CreateUserInput,
+  output: CreateUserOutput,
+  func: async ({ auth }, { email, password, name }, { http }) => {
+    const created: any = await callAdminApi(auth, http, (api, headers) =>
+      api.createUser!({
+        body: { email, password, name: name ?? email },
+        headers,
+      })
+    )
+    return { userId: created?.user?.id ?? created?.id }
+  },
+})
+
+export const pikkuAdminSetUserBanned = pikkuFunc({
+  tags: ['pikku'],
+  title: 'Ban or Unban User',
+  description:
+    'Bans a user — revoking their sessions and blocking sign-in — or lifts an existing ban. An expiry lets the ban lapse on its own; without one it holds until it is lifted.',
+  expose: true,
+  auth: ${authFlag},
+  scopes: ['admin:users:ban'],
+  input: SetUserBannedInput,
+  output: Success,
+  func: async (
+    { auth },
+    { userId, banned, reason, expiresInSeconds },
+    { http }
+  ) => {
+    await callAdminApi(auth, http, (api, headers) =>
+      banned
+        ? api.banUser!({
+            body: { userId, banReason: reason, banExpiresIn: expiresInSeconds },
+            headers,
+          })
+        : api.unbanUser!({ body: { userId }, headers })
+    )
+    return { success: true }
+  },
+})
+
+export const pikkuAdminRemoveUser = pikkuFunc({
+  tags: ['pikku'],
+  title: 'Remove User',
+  description:
+    'Permanently deletes a user along with their sessions and linked accounts. Cannot be undone.',
+  expose: true,
+  auth: ${authFlag},
+  scopes: ['admin:users:remove'],
+  input: UserRef,
+  output: Success,
+  func: async ({ auth }, { userId }, { http }) => {
+    await callAdminApi(auth, http, (api, headers) =>
+      api.removeUser!({ body: { userId }, headers })
+    )
+    return { success: true }
+  },
+})
+
+export const pikkuAdminRevokeUserSessions = pikkuFunc({
+  tags: ['pikku'],
+  title: 'Revoke User Sessions',
+  description:
+    'Signs a user out of every device by deleting all of their sessions. They keep their account and can sign in again.',
+  expose: true,
+  auth: ${authFlag},
+  scopes: ['admin:users:sessions'],
+  input: UserRef,
+  output: Success,
+  func: async ({ auth }, { userId }, { http }) => {
+    await callAdminApi(auth, http, (api, headers) =>
+      api.revokeUserSessions!({ body: { userId }, headers })
+    )
+    return { success: true }
+  },
+})
+
+export const pikkuAdminSetUserPassword = pikkuFunc({
+  tags: ['pikku'],
+  title: "Set User's Password",
+  description:
+    'Sets a user password out of band, for when they cannot complete a reset themselves. better-auth enforces the configured length bounds.',
+  expose: true,
+  auth: ${authFlag},
+  scopes: ['admin:users:password'],
+  input: SetUserPasswordInput,
+  output: Success,
+  func: async ({ auth }, { userId, newPassword }, { http }) => {
+    await callAdminApi(auth, http, (api, headers) =>
+      api.setUserPassword!({ body: { userId, newPassword }, headers })
+    )
+    return { success: true }
+  },
+})
+`;
+    return { schemas, functions };
+};

package/dist/src/functions/wirings/webhook/pikku-command-webhook.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 { serializeWebhook } from './serialize-webhook.js';
 export const pikkuWebhook = pikkuSessionlessFunc({
     func: async ({ logger, config, variables }) => {
@@ -9,9 +10,12 @@ export const pikkuWebhook = pikkuSessionlessFunc({
         if (deployCodegenFlag === '1') {
             return false;
         }
-        if (config.webhookWorkersFile) {
+        if (config.webhookWorkersFile && config.webhookSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.webhookWorkersFile, config.typesDeclarationFile, config.packageMappings);
-            await writeFileInDir(logger, config.webhookWorkersFile, serializeWebhook(pathToPikkuTypes));
+            const { schemas, functions } = serializeWebhook(pathToPikkuTypes);
+            await writeFileInDir(logger, config.webhookSchemasFile, schemas);
+            await writeFileInDir(logger, config.webhookWorkersFile, functions);
+            await removeLegacyScaffoldFile(config.webhookWorkersFile);
             return true;
         }
         return false;

package/dist/src/functions/wirings/webhook/serialize-webhook.d.ts

@@ -1,14 +1,11 @@
+export interface WebhookGenOutput {
+    schemas: string;
+    functions: string;
+}
 /**
  * Generate the outgoing webhook delivery queue worker.
  *
- * The payload type is an inline TS literal (not zod): the inspector imports a
- * zod schema's declaring module at codegen time, and the wiring file's
- * pikku-types import can go stale between deploy per-unit codegen runs, which
- * would fail schema generation before the wiring gets rewritten. TS-based
- * schema generation goes through the type checker instead, so it never
- * imports this file.
- *
  * The handler is inlined: it is wired exactly once, so a named export would
  * only be indirection.
  */
-export declare const serializeWebhook: (pathToPikkuTypes: string) => string;
+export declare const serializeWebhook: (pathToPikkuTypes: string) => WebhookGenOutput;

package/dist/src/functions/wirings/webhook/serialize-webhook.js

@@ -1,34 +1,41 @@
 /**
  * Generate the outgoing webhook delivery queue worker.
  *
- * The payload type is an inline TS literal (not zod): the inspector imports a
- * zod schema's declaring module at codegen time, and the wiring file's
- * pikku-types import can go stale between deploy per-unit codegen runs, which
- * would fail schema generation before the wiring gets rewritten. TS-based
- * schema generation goes through the type checker instead, so it never
- * imports this file.
- *
  * The handler is inlined: it is wired exactly once, so a named export would
  * only be indirection.
  */
 export const serializeWebhook = (pathToPikkuTypes) => {
-    return `/**
+    const schemas = `/**
+ * Auto-generated outgoing webhook delivery schemas
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { z } from 'zod'
+
+export const WebhookDelivery = z.object({
+  url: z.string(),
+  event: z.string().optional(),
+  body: z.string(),
+  headers: z.record(z.string(), z.string()),
+  deliveryId: z.string().optional(),
+})
+`;
+    const functions = `/**
  * Auto-generated outgoing webhook delivery queue worker
  * Do not edit manually - regenerate with 'npx pikku'
  */
 import { pikkuSessionlessFunc, wireQueueWorker } from '${pathToPikkuTypes}'
 import { pikkuWebhookWorkerFunc } from '@pikku/core/services'
+import { WebhookDelivery } from './webhook.schemas.gen.js'
 
 wireQueueWorker({
   name: 'pikku-outgoing-webhooks',
   tags: ['pikku'],
-  func: pikkuSessionlessFunc<
-    { url: string, event?: string, body: string, headers: Record<string, string>, deliveryId?: string },
-    void
-  >({
+  func: pikkuSessionlessFunc({
     tags: ['pikku'],
+    input: WebhookDelivery,
     func: async (services, data) => pikkuWebhookWorkerFunc(services, data),
   }),
 })
 `;
+    return { schemas, functions };
 };

package/dist/src/functions/wirings/workflow/pikku-command-workflow-routes.js

@@ -2,12 +2,18 @@ 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 { serializeWorkflowRoutes } from './serialize-workflow-routes.js';
 export const pikkuWorkflowRoutes = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
-        if (config.scaffold?.workflow && config.workflowRoutesFile) {
+        if (config.scaffold?.workflow &&
+            config.workflowRoutesFile &&
+            config.workflowRoutesSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.workflowRoutesFile, config.typesDeclarationFile, config.packageMappings);
-            await writeFileInDir(logger, config.workflowRoutesFile, serializeWorkflowRoutes(pathToPikkuTypes, config.scaffold?.workflow === 'auth'));
+            const { schemas, functions } = serializeWorkflowRoutes(pathToPikkuTypes, config.scaffold?.workflow === 'auth');
+            await writeFileInDir(logger, config.workflowRoutesSchemasFile, schemas);
+            await writeFileInDir(logger, config.workflowRoutesFile, functions);
+            await removeLegacyScaffoldFile(config.workflowRoutesFile);
             return true;
         }
         return false;

package/dist/src/functions/wirings/workflow/serialize-workflow-routes.d.ts

@@ -1,4 +1,8 @@
+export interface WorkflowRoutesGenOutput {
+    schemas: string;
+    functions: string;
+}
 /**
  * Generate catch-all HTTP routes for workflow operations
  */
-export declare const serializeWorkflowRoutes: (pathToPikkuTypes: string, requireAuth?: boolean) => string;
+export declare const serializeWorkflowRoutes: (pathToPikkuTypes: string, requireAuth?: boolean) => WorkflowRoutesGenOutput;

package/dist/src/functions/wirings/workflow/serialize-workflow-routes.js

@@ -3,13 +3,53 @@
  */
 export const serializeWorkflowRoutes = (pathToPikkuTypes, requireAuth = true) => {
     const authFlag = requireAuth ? 'true' : 'false';
-    return `/**
+    const schemas = `/**
+ * Auto-generated workflow route schemas
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { z } from 'zod'
+
+export const WorkflowStart = z.object({
+  workflowName: z.string(),
+  data: z.unknown().optional(),
+})
+
+export const GraphStart = z.object({
+  workflowName: z.string(),
+  nodeId: z.string(),
+  data: z.unknown().optional(),
+})
+
+export const WorkflowRunRef = z.object({
+  workflowName: z.string(),
+  runId: z.string(),
+})
+
+export const WorkflowRunId = z.object({ runId: z.string() })
+
+export const WorkflowApproval = z.object({
+  workflowName: z.string(),
+  runId: z.string(),
+  reason: z.string(),
+  decision: z.unknown(),
+})
+
+export const Acknowledged = z.object({ ok: z.literal(true) })
+`;
+    const functions = `/**
  * Workflow HTTP catch-all routes
  * Do not edit manually - regenerate with 'npx pikku'
  */
 import { pikkuSessionlessFunc, wireHTTPRoutes } from '${pathToPikkuTypes}'
 import { MissingServiceError } from '@pikku/core/errors'
-import type { WorkflowRunStatus } from '@pikku/core/workflow'
+import {
+  WorkflowStart,
+  GraphStart,
+  WorkflowRunRef,
+  WorkflowRunId,
+  WorkflowApproval,
+  Acknowledged,
+} from './workflow-routes.schemas.gen.js'
 
 function assertWorkflowService(workflowService: unknown): asserts workflowService {
   if (!workflowService) throw new MissingServiceError('workflowService is required')
@@ -19,12 +59,11 @@ function assertWorkflowRunService(workflowRunService: unknown): asserts workflow
   if (!workflowRunService) throw new MissingServiceError('workflowRunService is required')
 }
 
-export const workflowStarter = pikkuSessionlessFunc<
-  { workflowName: string; data?: unknown },
-  { runId: string }
->({
+export const workflowStarter = pikkuSessionlessFunc({
   tags: ['pikku'],
   auth: ${authFlag},
+  input: WorkflowStart,
+  output: WorkflowRunId,
   // workflowService is destructured (even though we delegate via rpc) so the
   // analyzer assigns workflow-state capability to this unit — without it,
   // rpc.startWorkflow() runs against a container missing workflowService.
@@ -34,24 +73,20 @@ export const workflowStarter = pikkuSessionlessFunc<
   },
 })
 
-export const workflowRunner = pikkuSessionlessFunc<
-  { workflowName: string; data?: unknown },
-  unknown
->({
+export const workflowRunner = pikkuSessionlessFunc({
   tags: ['pikku'],
   auth: ${authFlag},
+  input: WorkflowStart,
   func: async ({ workflowService }, { workflowName, data }, { rpc }) => {
     assertWorkflowService(workflowService)
     return await workflowService.runToCompletion(workflowName, data ?? {}, rpc)
   },
 })
 
-export const workflowStatusChecker = pikkuSessionlessFunc<
-  { workflowName: string; runId: string },
-  WorkflowRunStatus
->({
+export const workflowStatusChecker = pikkuSessionlessFunc({
   tags: ['pikku'],
   auth: ${authFlag},
+  input: WorkflowRunRef,
   func: async ({ workflowService }, { runId }) => {
     assertWorkflowService(workflowService)
     const status = await workflowService.getRunStatus(runId)
@@ -64,12 +99,10 @@ export const workflowStatusChecker = pikkuSessionlessFunc<
  * Minimal workflow status stream — sends step names and statuses only.
  * Use this for user-facing frontends where internal details should not be exposed.
  */
-export const workflowStatusStream = pikkuSessionlessFunc<
-  { workflowName: string; runId: string },
-  unknown
->({
+export const workflowStatusStream = pikkuSessionlessFunc({
   tags: ['pikku'],
   auth: ${authFlag},
+  input: WorkflowRunRef,
   func: async ({ workflowRunService }, { runId }, { channel }) => {
     assertWorkflowRunService(workflowRunService)
     if (!channel) return
@@ -151,12 +184,10 @@ export const workflowStatusStream = pikkuSessionlessFunc<
  * Full workflow status stream — includes output, error, and child run IDs.
  * Use this for admin consoles and internal tooling.
  */
-export const workflowStatusStreamFull = pikkuSessionlessFunc<
-  { workflowName: string; runId: string },
-  unknown
->({
+export const workflowStatusStreamFull = pikkuSessionlessFunc({
   tags: ['pikku'],
   auth: ${authFlag},
+  input: WorkflowRunRef,
   func: async ({ workflowRunService }, { runId }, { channel }) => {
     assertWorkflowRunService(workflowRunService)
     if (!channel) return
@@ -238,12 +269,11 @@ export const workflowStatusStreamFull = pikkuSessionlessFunc<
   },
 })
 
-export const graphStarter = pikkuSessionlessFunc<
-  { workflowName: string; nodeId: string; data?: unknown },
-  { runId: string }
->({
+export const graphStarter = pikkuSessionlessFunc({
   tags: ['pikku'],
   auth: ${authFlag},
+  input: GraphStart,
+  output: WorkflowRunId,
   // See workflowStarter — destructure workflowService so the analyzer
   // assigns workflow-state capability to this unit.
   func: async ({ workflowService }, { workflowName, nodeId, data }, { rpc }) => {
@@ -261,18 +291,17 @@ export const graphStarter = pikkuSessionlessFunc<
  * run. Gate this route with your own auth/permissions to control WHO may
  * approve: the framework does not model approver identity.
  */
-export const workflowApprover = pikkuSessionlessFunc<
-  { workflowName: string; runId: string; reason: string; decision: unknown },
-  { ok: true }
->({
+export const workflowApprover = pikkuSessionlessFunc({
   tags: ['pikku'],
   auth: ${authFlag},
+  input: WorkflowApproval,
+  output: Acknowledged,
   // See workflowStarter — destructure workflowService so the analyzer
   // assigns workflow-state capability to this unit.
   func: async ({ workflowService }, { runId, reason, decision }) => {
     assertWorkflowService(workflowService)
     await workflowService.approveStep(runId, reason, decision)
-    return { ok: true }
+    return { ok: true as const }
   },
 })
 
@@ -320,4 +349,5 @@ wireHTTPRoutes({
   },
 })
 `;
+    return { schemas, functions };
 };

package/dist/src/functions/workflows/all.workflow.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'fs';
 import { pikkuWorkflowComplexFunc } from '#pikku/workflow/pikku-workflow-types.gen.js';
 import { assertSingleCoreVersion } from '../../utils/assert-single-core-version.js';
+import { pruneLegacyScaffoldFiles } from '../../utils/remove-legacy-scaffold-file.js';
 import { PikkuTypecheckFailedError, renderTscFull, renderTscSummary, runProjectTypecheck, } from '../../utils/tsc-check.js';
 const scaffoldFiles = (config) => {
     const files = [];
@@ -21,6 +22,11 @@ const scaffoldFiles = (config) => {
             file: config.scenariosFunctionsFile,
             generator: 'pikkuScenarioFunctions',
         });
+    if (config.scaffold?.userAdmin && config.userAdminFunctionsFile)
+        files.push({
+            file: config.userAdminFunctionsFile,
+            generator: 'pikkuUserAdminFunctions',
+        });
     if (config.scaffold?.agent && config.publicAgentFile)
         files.push({
             file: config.publicAgentFile,
@@ -39,6 +45,7 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         // Preflight: a split @pikku/core install silently breaks wiring registration
         // (workflows/RPCs "disappear"), so refuse to codegen against it.
         await assertSingleCoreVersion(config.rootDir, logger);
+        await pruneLegacyScaffoldFiles(config);
         const allImports = [];
         let typesDeclarationFileExists = true;
         if (!existsSync(config.outDir)) {
@@ -144,6 +151,7 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             workflow.do('Public RPC', 'pikkuPublicRPC', null),
             workflow.do('Console functions', 'pikkuConsoleFunctions', null),
             workflow.do('Scenario functions', 'pikkuScenarioFunctions', null),
+            workflow.do('User admin functions', 'pikkuUserAdminFunctions', null),
             workflow.do('Events scaffold', 'pikkuEventsScaffold', null),
             workflow.do('Emails', 'pikkuEmails', null),
             workflow.do('Secret definition types', 'pikkuSecretDefinitionTypes', null),