@pikku/cli 0.12.93 → 0.12.99

package/dist/src/functions/wirings/queue/serialize-queue-wrapper.js

@@ -1,6 +1,7 @@
 export const serializeQueueWrapper = (queueMapPath) => {
     return `
 import type { QueueService, QueueJob } from '@pikku/core/queue'
+import type { Safe } from '@pikku/core'
 import type { QueueMap, TypedPikkuQueue } from '${queueMapPath}'
 
 export class PikkuQueue implements TypedPikkuQueue {
@@ -8,7 +9,7 @@ export class PikkuQueue implements TypedPikkuQueue {
 
     public async add<Name extends keyof QueueMap>(
         queueName: Name,
-        data: QueueMap[Name]['input'],
+        data: Safe<QueueMap[Name]['input']>,
         options?: {
             priority?: number
             delay?: number

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

@@ -4,6 +4,7 @@ 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';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuEventsScaffold = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
         if (!config.scaffold?.events ||
@@ -15,7 +16,7 @@ export const pikkuEventsScaffold = pikkuSessionlessFunc({
             });
             return false;
         }
-        const authRequired = config.scaffold.events === 'auth';
+        const authRequired = resolveScaffoldFeature('events', config.scaffold.events).auth;
         const pikkuTypesImportPath = getFileImportRelativePath(config.eventsChannelFile, config.typesDeclarationFile, config.packageMappings);
         const { schemas, functions } = serializeEventsScaffold(authRequired, pikkuTypesImportPath);
         await writeFileInDir(logger, config.eventsSchemasFile, schemas);

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

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

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

@@ -0,0 +1,33 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializeRolesTypes } from './serialize-roles-types.js';
+import { validateAndBuildSystemRoleDefinitionsMeta } from '@pikku/core/role';
+export const pikkuRoles = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }, data) => {
+        const { rolesFile, rolesMetaJsonFile } = config;
+        if (!rolesFile) {
+            return;
+        }
+        // Same cold-start reasoning as Scopes: on a bare .pikku this runs before
+        // pikku-types.gen.ts exists, so it takes the zero state. The file only has
+        // to exist so personas can import SystemRoleName; the real Roles step
+        // regenerates it with the declarations once setup has run.
+        const bootstrap = data?.bootstrap ?? false;
+        const state = await getInspectorState(false, bootstrap, bootstrap);
+        const content = serializeRolesTypes({
+            definitions: state.systemRoles.definitions,
+        });
+        await writeFileInDir(logger, rolesFile, content);
+        if (rolesMetaJsonFile) {
+            const meta = validateAndBuildSystemRoleDefinitionsMeta(state.systemRoles.definitions);
+            await writeFileInDir(logger, rolesMetaJsonFile, JSON.stringify(meta, null, 2));
+        }
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Creating PikkuRoles types',
+            commandEnd: 'Created PikkuRoles types',
+        }),
+    ],
+});

package/dist/src/functions/wirings/roles/serialize-roles-types.d.ts

@@ -0,0 +1,14 @@
+import type { SystemRoleDefinitions } from '@pikku/core/role';
+export interface SerializeRolesOptions {
+    definitions: SystemRoleDefinitions;
+}
+/**
+ * Generates the `SystemRoleName` union and role metadata from
+ * `defineSystemRole` declarations.
+ *
+ * The union is what makes a persona's `roles: ['buyer']` checkable. Custom
+ * roles are deliberately absent: an admin can delete one from the console, so
+ * a persona pinned to it would silently stop testing what it claims to — the
+ * failure would be a scatter of 403s rather than a build error.
+ */
+export declare const serializeRolesTypes: ({ definitions }: SerializeRolesOptions) => string;

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

@@ -0,0 +1,55 @@
+const quote = (value) => `'${value.replace(/'/g, "\\'")}'`;
+/**
+ * Generates the `SystemRoleName` union and role metadata from
+ * `defineSystemRole` declarations.
+ *
+ * The union is what makes a persona's `roles: ['buyer']` checkable. Custom
+ * roles are deliberately absent: an admin can delete one from the console, so
+ * a persona pinned to it would silently stop testing what it claims to — the
+ * failure would be a scatter of 403s rather than a build error.
+ */
+export const serializeRolesTypes = ({ definitions }) => {
+    const names = [...new Set(definitions.map((d) => d.name))].sort();
+    const union = names.length > 0
+        ? `\n${names.map((name) => `  | ${quote(name)}`).join('\n')}`
+        : ' never';
+    return `/**
+ * This file was generated by the @pikku/cli
+ */
+import type { SystemRole, SystemRoleDefinitionsMeta } from '@pikku/core/role'
+import { flattenSystemRoleDefinitions } from '@pikku/core/role'
+import definitions from './pikku-roles-meta.gen.json' with { type: 'json' }
+
+/**
+ * Every role that ships with this application.
+ *
+ * Roles an admin composes in the console are not here and cannot be: they do
+ * not exist at build time, and can be deleted after it.
+ */
+export type SystemRoleName =${union}
+
+/**
+ * The declared role set, for a ScopeService to sync into its store.
+ *
+ * Derived from the metadata sidecar rather than inlined, so the import above
+ * forces tsc to emit the .json alongside this file — an addon publishes only
+ * its compiled output, and a host reads that .json to merge the addon's roles
+ * into its own union.
+ *
+ * Additive on removal: a deleted declaration leaves an inert row rather than
+ * revoking everyone's grant on deploy. Use \`pikku roles prune\` to remove them.
+ */
+export const SYSTEM_ROLES: SystemRole[] = flattenSystemRoleDefinitions(
+  Object.values(definitions as SystemRoleDefinitionsMeta)
+)
+
+/** Declared roles, keyed by name. Rendered by the console when granting. */
+export const SYSTEM_ROLES_META: Record<string, SystemRole> = Object.fromEntries(
+  SYSTEM_ROLES.map((role) => [role.name, role])
+)
+
+/** Whether a role name is declared in code, and therefore not editable. */
+export const isSystemRole = (name: string): boolean =>
+  Object.prototype.hasOwnProperty.call(SYSTEM_ROLES_META, name)
+`;
+};

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

@@ -4,6 +4,7 @@ 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';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuPublicRPC = pikkuSessionlessFunc({
     func: async ({ logger, config, variables }) => {
         const deployCodegenFlag = await variables.get('PIKKU_DEPLOY_CODEGEN');
@@ -12,7 +13,7 @@ export const pikkuPublicRPC = pikkuSessionlessFunc({
         }
         if (config.scaffold?.rpc && config.publicRpcSchemasFile) {
             const pathToPikkuTypes = getFileImportRelativePath(config.publicRpcFile, config.typesDeclarationFile, config.packageMappings);
-            const { schemas, functions } = serializePublicRPC(pathToPikkuTypes, config.scaffold.rpc === 'auth', config.globalHTTPPrefix || '');
+            const { schemas, functions } = serializePublicRPC(pathToPikkuTypes, resolveScaffoldFeature('rpc', config.scaffold.rpc).auth, config.globalHTTPPrefix || '');
             await writeFileInDir(logger, config.publicRpcSchemasFile, schemas);
             await writeFileInDir(logger, config.publicRpcFile, functions);
             await removeLegacyScaffoldFile(config.publicRpcFile);

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

@@ -3,8 +3,8 @@
  * scenario runner can reach it over `/rpc/<name>` exactly as before.
  *
  * They are registered sessionless: `auth` decides whether a session is
- * *required*, and a sessioned function would demand one regardless of the flag —
- * which is what made `scaffold.scenarios: true` (as opposed to `'auth'`) refuse
- * every call and log a warning about it.
+ * *required*, and a sessioned function would demand one regardless of the flag.
+ * `scaffold.scenarios: true` therefore requires a session; `{ auth: false }` is
+ * what opens them.
  */
 export declare const registerScenarioInstrumentation: (requireAuth: boolean) => void;

package/dist/src/functions/wirings/scenarios/register-scenario-instrumentation.js

@@ -79,9 +79,9 @@ const instrumentation = {
  * scenario runner can reach it over `/rpc/<name>` exactly as before.
  *
  * They are registered sessionless: `auth` decides whether a session is
- * *required*, and a sessioned function would demand one regardless of the flag —
- * which is what made `scaffold.scenarios: true` (as opposed to `'auth'`) refuse
- * every call and log a warning about it.
+ * *required*, and a sessioned function would demand one regardless of the flag.
+ * `scaffold.scenarios: true` therefore requires a session; `{ auth: false }` is
+ * what opens them.
  */
 export const registerScenarioInstrumentation = (requireAuth) => {
     const meta = pikkuState(null, 'function', 'meta');

package/dist/src/functions/wirings/scopes/serialize-scopes-types.d.ts

@@ -3,7 +3,7 @@ export interface SerializeScopesOptions {
     definitions: ScopeDefinitions;
 }
 /**
- * Generates the `ScopeId` union and scope metadata from `wireScope`
+ * Generates the `ScopeId` union and scope metadata from `defineScope`
  * declarations.
  *
  * The union carries every declared node plus a wildcard form for each node that

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

@@ -1,7 +1,7 @@
 import { flattenScopeDefinitions } from '@pikku/core/scope';
 const quote = (value) => `'${value.replace(/'/g, "\\'")}'`;
 /**
- * Generates the `ScopeId` union and scope metadata from `wireScope`
+ * Generates the `ScopeId` union and scope metadata from `defineScope`
  * declarations.
  *
  * The union carries every declared node plus a wildcard form for each node that

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

@@ -3,6 +3,7 @@ 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';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuUserAdminFunctions = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         if (!config.scaffold?.userAdmin ||
@@ -35,7 +36,7 @@ export const pikkuUserAdminFunctions = pikkuSessionlessFunc({
                 `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');
+        const { schemas, functions } = serializeUserAdminFunctions(pathToPikkuTypes, resolveScaffoldFeature('userAdmin', config.scaffold.userAdmin).auth);
         await writeFileInDir(logger, config.userAdminSchemasFile, schemas);
         await writeFileInDir(logger, config.userAdminFunctionsFile, functions);
         return true;

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

@@ -86,7 +86,7 @@ export const Success = z.object({
  * Auto-generated user management functions
  * Do not edit manually - regenerate with 'npx pikku'
  */
-import { pikkuFunc, wireScope } from '${pathToPikkuTypes}'
+import { pikkuFunc, defineScope } from '${pathToPikkuTypes}'
 import { callAdminApi } from '@pikku/better-auth'
 import {
   CreateUserInput,
@@ -103,7 +103,7 @@ import {
 // 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({
+defineScope({
   admin: {
     displayName: 'Administration',
     description: 'Capabilities that act on the application as a whole',

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

@@ -0,0 +1 @@
+export declare const pikkuVirtualUserFunctions: 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/virtual-user/pikku-command-virtual-user-functions.js

@@ -0,0 +1,42 @@
+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 { serializeVirtualUserFunctions } from './serialize-virtual-user-functions.js';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
+export const pikkuVirtualUserFunctions = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }) => {
+        if (!config.scaffold?.virtualUser ||
+            !config.virtualUserFunctionsFile ||
+            !config.virtualUserSchemasFile) {
+            logger.debug({
+                message: 'Skipping virtual user scaffold (set scaffold.virtualUser in pikku.config.json to enable).',
+                type: 'skip',
+            });
+            return false;
+        }
+        const state = await getInspectorState();
+        // A virtual user IS a persona — the generated functions sign in as one and
+        // run as them. With none declared the scaffold would emit RPCs whose only
+        // possible answer is "unknown persona". Fail the codegen instead of
+        // shipping that.
+        if (Object.keys(state.personas?.definitions ?? {}).length === 0) {
+            throw new Error(`"scaffold.virtualUser" is enabled but no personas are declared.\n` +
+                `A virtual user runs AS a persona, so there is nobody to run.\n` +
+                `Fix: declare one with definePersonas({ ... }), or remove ` +
+                `"scaffold.virtualUser" from pikku.config.json.`);
+        }
+        const pathToPikkuTypes = getFileImportRelativePath(config.virtualUserFunctionsFile, config.typesDeclarationFile, config.packageMappings);
+        const pathToPersonas = getFileImportRelativePath(config.virtualUserFunctionsFile, config.personasWiringFile, config.packageMappings);
+        const { schemas, functions } = serializeVirtualUserFunctions(pathToPikkuTypes, pathToPersonas, resolveScaffoldFeature('virtualUser', config.scaffold.virtualUser).auth);
+        await writeFileInDir(logger, config.virtualUserSchemasFile, schemas);
+        await writeFileInDir(logger, config.virtualUserFunctionsFile, functions);
+        return true;
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Generating virtual user functions',
+            commandEnd: 'Generated virtual user functions',
+        }),
+    ],
+});

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

@@ -0,0 +1,28 @@
+export interface VirtualUserGenOutput {
+    schemas: string;
+    functions: string;
+}
+/**
+ * Generate the virtual-user functions into the project scaffold: start a run,
+ * read one back, and the sessionless function that does the work.
+ *
+ * Scaffolded rather than shipped in an addon because the whole feature is
+ * derived from what the project already generates — its personas, its function
+ * meta, its scenarios — so there is nothing to configure and nothing to author.
+ * `pikku persona run` does the same thing from a terminal; this is the same run
+ * started over RPC, from CI or from a console, with the result kept.
+ *
+ * A virtual user is NOT a workflow and NOT a queued job. It explores, so no two
+ * attempts take the same steps and there is nothing to replay; and the run
+ * record already carries the progress a queue would only be holding on the way
+ * here. So `runVirtualUser` writes the record, kicks the run off without
+ * awaiting it, and returns the id. The one cost is stated on the record: a
+ * restart mid-run strands it at `running`.
+ *
+ * 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 serializeVirtualUserFunctions: (pathToPikkuTypes: string, pathToPersonas: string, requireAuth?: boolean) => VirtualUserGenOutput;