@pikku/cli 0.12.92 → 0.12.96

package/dist/src/functions/commands/new-addon.js

@@ -110,7 +110,23 @@ function sanitizeAddonName(raw) {
         name = `x${name}`;
     return name || raw;
 }
-function getAddonFiles(vars, flags) {
+/**
+ * `--display-name` and `--description` are free-form prose, so an apostrophe in
+ * them is ordinary — "Bob's CRM". `JSON.stringify` emits a valid, escaped
+ * string literal; interpolating the raw text into a quoted one terminates the
+ * string and the scaffolded file no longer parses. Prose composed with other
+ * words is stringified as a whole, not swapped in place.
+ */
+const literal = (value) => JSON.stringify(value);
+/**
+ * The same prose inside a generated template literal, where a backtick or a
+ * `${` opens an interpolation rather than ending the string — so the emitted
+ * message keeps its own `\${response.status}` holes.
+ */
+const inTemplate = (value) => value.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+/** The same prose on a `//` comment line, where a newline ends the comment. */
+const inComment = (value) => value.replace(/\s+/g, ' ').trim();
+export function getAddonFiles(vars, flags) {
     const { name, camelName, pascalName, screamingName, displayName, description, category, } = vars;
     const files = {};
     // package.json
@@ -205,7 +221,7 @@ ${description}
 6. Build: \`yarn install && yarn pikku && yarn build\`
 `;
     // src/index.ts
-    files['src/index.ts'] = `// ${displayName} functions
+    files['src/index.ts'] = `// ${inComment(displayName)} functions
 // export { ${camelName}Operation } from './functions/operation.function.js'
 `;
     // src/services.ts
@@ -224,10 +240,10 @@ export const createWireServices = pikkuAddonWireServices(
     }
     const cred = await wire.getCredential<{ token: string; expiresAt?: number }>('${camelName}')
     if (!cred?.token) {
-      throw new UnauthorizedError('No ${displayName} session — sign in again')
+      throw new UnauthorizedError(${literal(`No ${displayName} session — sign in again`)})
     }
     if (cred.expiresAt && cred.expiresAt * 1000 < Date.now()) {
-      throw new UnauthorizedError('${displayName} session expired — sign in again')
+      throw new UnauthorizedError(${literal(`${displayName} session expired — sign in again`)})
     }
     const ${camelName} = new ${pascalName}Service(cred, variables)
 
@@ -275,7 +291,7 @@ export const createWireServices = pikkuAddonWireServices(
     }
     const cred = await wire.getCredential<{ accessToken: string }>('${camelName}')
     if (!cred?.accessToken) {
-      throw new UnauthorizedError('No ${displayName} connection — connect ${displayName} first')
+      throw new UnauthorizedError(${literal(`No ${displayName} connection — connect ${displayName} first`)})
     }
     const ${camelName} = new ${pascalName}Service(cred, variables)
 
@@ -363,7 +379,7 @@ export class ${pascalName}Service {
 
     if (!response.ok) {
       const errorText = await response.text()
-      throw new Error(\`${displayName} API error (\${response.status}): \${errorText}\`)
+      throw new Error(\`${inTemplate(displayName)} API error (\${response.status}): \${errorText}\`)
     }
 
     return response.json() as Promise<T>
@@ -416,7 +432,7 @@ export class ${pascalName}Service {
 
     if (!response.ok) {
       const errorText = await response.text()
-      throw new Error(\`${displayName} API error (\${response.status}): \${errorText}\`)
+      throw new Error(\`${inTemplate(displayName)} API error (\${response.status}): \${errorText}\`)
     }
 
     return response.json() as Promise<T>
@@ -464,7 +480,7 @@ export class ${pascalName}Service {
 
     if (!response.ok) {
       const errorText = await response.text()
-      throw new Error(\`${displayName} API error (\${response.status}): \${errorText}\`)
+      throw new Error(\`${inTemplate(displayName)} API error (\${response.status}): \${errorText}\`)
     }
 
     return response.json() as Promise<T>
@@ -507,7 +523,7 @@ export class ${pascalName}Service {
 
     if (!response.ok) {
       const errorText = await response.text()
-      throw new Error(\`${displayName} API error (\${response.status}): \${errorText}\`)
+      throw new Error(\`${inTemplate(displayName)} API error (\${response.status}): \${errorText}\`)
     }
 
     return response.json() as Promise<T>
@@ -550,16 +566,16 @@ export interface Services extends CoreServices<SingletonServices> {}
     // Conditional: credential / secret file
     if (flags.credential === 'apikey') {
         files[`src/${name}.credential.ts`] = `import { z } from 'zod'
-import { wireCredential } from '@pikku/core/credential'
+import { defineCredential } from '@pikku/core/credential'
 
 export const ${camelName}CredentialSchema = z.object({
-  apiKey: z.string().describe('${displayName} API key'),
+  apiKey: z.string().describe(${literal(`${displayName} API key`)}),
 })
 
-wireCredential({
+defineCredential({
   name: '${camelName}',
-  displayName: '${displayName}',
-  description: '${description}',
+  displayName: ${literal(displayName)},
+  description: ${literal(description)},
   type: 'wire',
   schema: ${camelName}CredentialSchema,
 })
@@ -567,21 +583,21 @@ wireCredential({
     }
     else if (flags.credential === 'bearer') {
         const credentialFields = flags.delegated
-            ? `  token: z.string().describe('${displayName} session token captured at delegated sign-in'),
+            ? `  token: z.string().describe(${literal(`${displayName} session token captured at delegated sign-in`)}),
   expiresAt: z.number().optional().describe('Token expiry (epoch seconds)'),
   tenantId: z.string().optional().describe('Upstream tenant id'),`
-            : `  token: z.string().describe('${displayName} bearer token'),`;
+            : `  token: z.string().describe(${literal(`${displayName} bearer token`)}),`;
         files[`src/${name}.credential.ts`] = `import { z } from 'zod'
-import { wireCredential } from '@pikku/core/credential'
+import { defineCredential } from '@pikku/core/credential'
 
 export const ${camelName}CredentialSchema = z.object({
 ${credentialFields}
 })
 
-wireCredential({
+defineCredential({
   name: '${camelName}',
-  displayName: '${displayName}',
-  description: '${description}',
+  displayName: ${literal(displayName)},
+  description: ${literal(description)},
   type: 'wire',
   schema: ${camelName}CredentialSchema,
 })
@@ -589,18 +605,18 @@ wireCredential({
     }
     else if (flags.oauth || flags.credential === 'oauth2') {
         files[`src/${name}.credential.ts`] = `import { z } from 'zod'
-import { wireCredential } from '@pikku/core/credential'
-import { wireSecret } from '@pikku/core/secret'
+import { defineCredential } from '@pikku/core/credential'
+import { defineSecret } from '@pikku/core/secret'
 
 export const ${camelName}TokenSchema = z.object({
   accessToken: z.string(),
   refreshToken: z.string().optional(),
 })
 
-wireCredential({
+defineCredential({
   name: '${camelName}',
-  displayName: '${displayName}',
-  description: '${description}',
+  displayName: ${literal(displayName)},
+  description: ${literal(description)},
   type: 'wire',
   schema: ${camelName}TokenSchema,
   oauth2: {
@@ -612,29 +628,29 @@ wireCredential({
   },
 })
 
-wireSecret({
+defineSecret({
   name: '${camelName}OAuthApp',
-  displayName: '${displayName} OAuth App',
-  description: 'OAuth2 app credentials for ${displayName}',
+  displayName: ${literal(`${displayName} OAuth App`)},
+  description: ${literal(`OAuth2 app credentials for ${displayName}`)},
   secretId: '${screamingName}_OAUTH_APP',
 })
 `;
     }
     else if (flags.secret) {
         files[`src/${name}.secret.ts`] = `import { z } from 'zod'
-import { wireSecret } from '@pikku/core/secret'
+import { defineSecret } from '@pikku/core/secret'
 
 export const ${camelName}SecretsSchema = z.object({
-  apiKey: z.string().describe('${displayName} API key'),
+  apiKey: z.string().describe(${literal(`${displayName} API key`)}),
   // Add other secret fields as needed
 })
 
 export type ${pascalName}Secrets = z.infer<typeof ${camelName}SecretsSchema>
 
-wireSecret({
+defineSecret({
   name: '${camelName}',
-  displayName: '${displayName} API',
-  description: '${description}',
+  displayName: ${literal(`${displayName} API`)},
+  description: ${literal(description)},
   secretId: '${screamingName}_CREDENTIALS',
   schema: ${camelName}SecretsSchema,
 })
@@ -643,13 +659,13 @@ wireSecret({
     // Conditional: variable file
     if (flags.variable) {
         files[`src/${name}.variable.ts`] = `import { z } from 'zod'
-import { wireVariable } from '@pikku/core/variable'
+import { defineVariable } from '@pikku/core/variable'
 
 export const ${camelName}VariableSchema = z.string().optional().describe('TODO: describe this variable')
 
-wireVariable({
+defineVariable({
   name: '${camelName}_variable',
-  displayName: '${displayName} Variable',
+  displayName: ${literal(`${displayName} Variable`)},
   description: 'TODO: describe this variable',
   variableId: '${screamingName}_VARIABLE',
   schema: ${camelName}VariableSchema,

package/dist/src/functions/commands/persona-sync.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Provision the declared personas into an environment: their accounts, and the
+ * roles they declare.
+ *
+ * This is deployment, not seeding. `pikku db seed` applies a project's test
+ * fixtures and does not run in production; an accountable persona doing a real
+ * job in production still needs an account and its grants, and this is where
+ * they come from.
+ *
+ * Additive in the same way `syncSystemRoles` is: it creates and grants, and
+ * never deletes or revokes. Removing a persona from the code leaves their
+ * account and their grants standing until somebody decides otherwise — which is
+ * the point, because the alternative is a rolling deploy quietly locking out the
+ * teammate that the older replica is still running.
+ *
+ * It needs both halves of an environment: its API, to sign the persona in, and
+ * its database, to write the grants. They must be the same deployment — the
+ * command has no way to check that, so pointing it at a stage's API and a local
+ * database provisions nobody usefully.
+ */
+export declare const personaSync: import("#pikku").PikkuFunctionConfig<{
+    environment: string;
+    apiUrl?: string;
+    dryRun?: boolean;
+}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
+    environment: string;
+    apiUrl?: string;
+    dryRun?: boolean;
+}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
+    environment: string;
+    apiUrl?: string;
+    dryRun?: boolean;
+}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/persona-sync.js

@@ -0,0 +1,151 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { createHttpPersonas } from '@pikku/core/persona';
+import { personaEnvironmentRefusal } from '@pikku/core/persona';
+import { resolvePersonas } from '../../utils/resolve-personas.js';
+import { resolveEnvironment } from './environment.js';
+import { loadDeclaredRoles, openScopeServiceForRoles } from './roles-shared.js';
+/**
+ * The user id behind a persona's address.
+ *
+ * Read straight off better-auth's own `user` table rather than through the
+ * ScopeService, because the ScopeService has no notion of an address — its
+ * grants are keyed by user id, and `pikku_user_role.user_id` already FKs into
+ * this exact table. Looking it up anywhere else would mean inventing a second
+ * account concept for personas, which is the one thing this command exists to
+ * avoid: a persona is a user, provisioned the way users are.
+ */
+const userIdByEmail = async (db, email) => {
+    const row = await db
+        .selectFrom('user')
+        .select('id')
+        .where('email', '=', email)
+        .executeTakeFirst();
+    return row ? String(row.id) : null;
+};
+/**
+ * Provision the declared personas into an environment: their accounts, and the
+ * roles they declare.
+ *
+ * This is deployment, not seeding. `pikku db seed` applies a project's test
+ * fixtures and does not run in production; an accountable persona doing a real
+ * job in production still needs an account and its grants, and this is where
+ * they come from.
+ *
+ * Additive in the same way `syncSystemRoles` is: it creates and grants, and
+ * never deletes or revokes. Removing a persona from the code leaves their
+ * account and their grants standing until somebody decides otherwise — which is
+ * the point, because the alternative is a rolling deploy quietly locking out the
+ * teammate that the older replica is still running.
+ *
+ * It needs both halves of an environment: its API, to sign the persona in, and
+ * its database, to write the grants. They must be the same deployment — the
+ * command has no way to check that, so pointing it at a stage's API and a local
+ * database provisions nobody usefully.
+ */
+export const personaSync = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config, getInspectorState, variables }, { environment, apiUrl, dryRun }) => {
+        const state = await getInspectorState(true, false, false, true);
+        const personas = resolvePersonas(state.personas?.definitions ?? [], config.scenarios?.emailDomain);
+        if (Object.keys(personas).length === 0) {
+            logger.info('persona sync: no personas are declared — add a definePersonas({ … }) call.');
+            return;
+        }
+        const environments = config.environments ?? {};
+        const env = resolveEnvironment({ environment, environments, apiUrl });
+        // The same rule that decides who may *run* against an environment decides
+        // who may be provisioned into it. Two rules would drift, and the one that
+        // drifted would leave an account standing in production for a persona the
+        // engine then refuses to sign in.
+        //
+        // A `runnable: false` persona is still provisioned: their account is the
+        // whole reason they were declared, because other people act on it.
+        const eligible = [];
+        const skipped = [];
+        for (const [id, persona] of Object.entries(personas)) {
+            const refusal = personaEnvironmentRefusal(id, persona, environment, environments);
+            if (refusal) {
+                skipped.push(refusal);
+                continue;
+            }
+            eligible.push([id, persona]);
+        }
+        if (eligible.length === 0) {
+            logger.info(`persona sync: no persona may act in '${environment}' — ${skipped.length} declared persona(s) were all skipped.`);
+            logger.info('  Run with --dry-run for the reasons, or give the persona this environment and disposition `accountable` if it is production.');
+            return;
+        }
+        if (dryRun) {
+            logger.info(`persona sync (dry run): ${eligible.length} persona(s) would be provisioned into '${environment}' at ${env.apiUrl}:`);
+            for (const [id, persona] of eligible) {
+                logger.info(`  ${id.padEnd(20)} ${persona.email}${persona.roles.length
+                    ? ` -> ${persona.roles.join(' + ')}`
+                    : ' (no roles)'}`);
+            }
+            for (const refusal of skipped) {
+                logger.info(`  skipped: ${refusal}`);
+            }
+            logger.info('Re-run without --dry-run to apply.');
+            return;
+        }
+        const secret = await variables.get('SCENARIO_ACTOR_SECRET');
+        if (!secret) {
+            throw new Error('SCENARIO_ACTOR_SECRET is not set — a persona account cannot be created. ' +
+                'Export it in the environment running this command (never put it in pikku.config.json).');
+        }
+        const declaredRoles = await loadDeclaredRoles(config.rolesMetaJsonFile, logger);
+        if (!declaredRoles) {
+            throw new Error('role metadata not found');
+        }
+        const signedIn = createHttpPersonas({
+            apiUrl: env.apiUrl,
+            secret,
+            personas: Object.fromEntries(eligible),
+            signInPath: env.signInPath,
+            rpcPath: env.rpcPath,
+        });
+        // Roles are synced on the way in, so a grant can name a role this deploy
+        // introduced. Both that sync and everything below are additive.
+        const opened = await openScopeServiceForRoles({ config, logger }, declaredRoles, 'pikku persona sync');
+        if (!opened) {
+            return;
+        }
+        try {
+            let accounts = 0;
+            let granted = 0;
+            let held = 0;
+            for (const [id, persona] of eligible) {
+                // Signing in is what creates the account: the actor plugin upserts an
+                // `actor: true` user row on first sign-in, and nothing else does.
+                // `sessionRoles()` is the public call that forces it — its answer is a
+                // by-product here, not the reason for the call.
+                await signedIn[id].sessionRoles();
+                accounts++;
+                if (persona.roles.length === 0) {
+                    logger.info(`  ${id.padEnd(20)} ${persona.email} (no roles)`);
+                    continue;
+                }
+                const userId = await userIdByEmail(opened.db, persona.email);
+                if (!userId) {
+                    throw new Error(`persona sync: signed '${id}' in at ${env.apiUrl}, but no user row for ${persona.email} exists in the database this command opened. ` +
+                        `That database is not the one '${environment}' runs on, so its grants would land nowhere.`);
+                }
+                const already = new Set(await opened.service.listUserRoles(userId));
+                const missing = persona.roles.filter((role) => !already.has(role));
+                for (const role of missing) {
+                    await opened.service.addUserToRole(userId, role);
+                }
+                granted += missing.length;
+                held += persona.roles.length - missing.length;
+                logger.info(`  ${id.padEnd(20)} ${persona.email} -> ${persona.roles.join(' + ')}${missing.length === 0 ? ' (already held)' : ''}`);
+            }
+            logger.info(`persona sync: ${accounts} account(s) in '${environment}', ${granted} role grant(s) applied, ${held} already held`);
+            if (skipped.length > 0) {
+                logger.info(`  ${skipped.length} persona(s) skipped — they do not act in '${environment}'. Run with --dry-run for the reasons.`);
+            }
+        }
+        finally {
+            await opened.destroy();
+        }
+    },
+});

package/dist/src/functions/commands/persona.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Run one declared persona against a real stage as a virtual user.
+ *
+ * Everything it needs is already in the project: the catalogue is the function
+ * meta, the intents are the scenarios' own prose, the identity is the persona
+ * signing in over the app's real auth, and the scopes come from the roles they
+ * declared. The only new input is which person to be — everything else is a
+ * flag for narrowing or replaying a run.
+ *
+ * This is deliberately not a test runner. It asserts nothing, and a green run
+ * proves nothing — what it produces is findings, and the absence of them is
+ * only ever "not this time, not with this seed".
+ */
+export declare const personaRun: import("#pikku").PikkuFunctionConfig<{
+    environment: string;
+    persona: string;
+    disposition?: string;
+    goals?: string;
+    steps?: string;
+    mutations?: string;
+    duration?: string;
+    seed?: string;
+    model?: string;
+    apiUrl?: string;
+    allowApproval?: boolean;
+    skipRoleCheck?: boolean;
+    out?: string;
+}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
+    environment: string;
+    persona: string;
+    disposition?: string;
+    goals?: string;
+    steps?: string;
+    mutations?: string;
+    duration?: string;
+    seed?: string;
+    model?: string;
+    apiUrl?: string;
+    allowApproval?: boolean;
+    skipRoleCheck?: boolean;
+    out?: string;
+}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
+    environment: string;
+    persona: string;
+    disposition?: string;
+    goals?: string;
+    steps?: string;
+    mutations?: string;
+    duration?: string;
+    seed?: string;
+    model?: string;
+    apiUrl?: string;
+    allowApproval?: boolean;
+    skipRoleCheck?: boolean;
+    out?: string;
+}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+/** Who this app is for, and what each of them wants, without running anything. */
+export declare const personaList: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;