@pikku/core 0.12.93 → 0.12.95

package/src/services/email-template.ts

@@ -0,0 +1,254 @@
+/**
+ * The renderer behind a generated `pikku-emails.gen.ts`.
+ *
+ * The generated module supplies the assets — theme, locale strings, partials and
+ * the templates themselves — and a typed wrapper over `renderEmail`. Everything
+ * here is the same for every application, which is why it lives in core rather
+ * than in the string the CLI writes: this is HTML escaping, and code inside a
+ * template literal is never compiled, never linted, and testable only by
+ * matching the text it emits.
+ */
+
+export interface EmailTemplateHashes {
+  contentHash: string
+  htmlHash: string
+  subjectHash: string
+  textHash: string
+}
+
+export interface EmailTemplateAssets {
+  html: string
+  subject: string
+  text: string
+  variables: ReadonlyArray<string>
+  hashes: Record<string, EmailTemplateHashes>
+}
+
+export interface EmailAssets {
+  theme: Record<string, unknown>
+  locales: Record<string, Record<string, unknown>>
+  partials: Record<string, string>
+  templates: Record<string, EmailTemplateAssets>
+}
+
+export interface RenderEmailRequest {
+  name: string
+  locale?: string
+  data?: Record<string, unknown>
+}
+
+export interface RenderedEmailResult {
+  locale: string
+  subject: string
+  html: string
+  text?: string
+  variables: ReadonlyArray<string>
+  hash: string
+}
+
+const HTML_ESCAPES: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+}
+
+const escapeHtml = (value: string): string =>
+  value.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char] ?? char)
+
+// Matches the raw {{{ value }}} form before the escaped {{ value }} form, so the
+// opt-in escape hatch is never mistaken for a normal substitution.
+const TEMPLATE_TOKEN = /\{\{\{\s*([^{}]+?)\s*\}\}\}|\{\{\s*([^}]+?)\s*\}\}/g
+
+const PARTIAL_TOKEN = /\{\{\s*>\s*([a-zA-Z0-9-_/.]+)\s*\}\}/g
+
+const MAX_TEMPLATE_DEPTH = 5
+
+// theme.json and the locale files ship with the templates, so they are treated as
+// template-author input: expanded before caller data and allowed to contain their
+// own placeholders. Everything else is caller-supplied.
+const TRUSTED_ROOTS = ['theme', 't']
+
+const isTrustedKey = (key: string): boolean =>
+  TRUSTED_ROOTS.includes(String(key.split('.')[0]))
+
+const getNestedValue = (
+  source: Record<string, unknown>,
+  path: string
+): string => {
+  const segments = path.split('.')
+  let current: unknown = source
+  for (const segment of segments) {
+    // `hasOwn`, not `in`: `in` walks the prototype chain, so a path is answered
+    // by what an object inherits rather than only by what it carries. Nothing
+    // inherited reaches the output today — every step past a prototype hit lands
+    // on a function, which is neither traversed nor written — so this closes the
+    // lookup rather than fixing a value that escapes through it.
+    if (
+      !current ||
+      typeof current !== 'object' ||
+      !Object.hasOwn(current, segment)
+    ) {
+      return ''
+    }
+    current = (current as Record<string, unknown>)[segment]
+  }
+  return typeof current === 'string' || typeof current === 'number'
+    ? String(current)
+    : ''
+}
+
+const readToken = (rawTriple: unknown, rawDouble: unknown) => {
+  const raw = typeof rawTriple === 'string'
+  return { raw, key: String(raw ? rawTriple : rawDouble).trim() }
+}
+
+const expandPartials = (
+  source: string,
+  partials: Record<string, string>,
+  depth = 0
+): string => {
+  if (depth >= MAX_TEMPLATE_DEPTH) return source
+  let found = false
+  const expanded = source.replace(PARTIAL_TOKEN, (_match, partialName) => {
+    found = true
+    const partial = partials[String(partialName).trim()]
+    return typeof partial === 'string' ? partial : ''
+  })
+  return found ? expandPartials(expanded, partials, depth + 1) : expanded
+}
+
+const expandTrusted = (
+  source: string,
+  context: Record<string, unknown>,
+  escape: boolean
+): string => {
+  let rendered = source
+  for (let i = 0; i < MAX_TEMPLATE_DEPTH; i += 1) {
+    let found = false
+    const next = rendered.replace(
+      TEMPLATE_TOKEN,
+      (match, rawTriple, rawDouble) => {
+        const { raw, key } = readToken(rawTriple, rawDouble)
+        if (!isTrustedKey(key)) return match
+        found = true
+        const value = getNestedValue(context, key)
+        return raw || !escape ? value : escapeHtml(value)
+      }
+    )
+    if (!found || next === rendered) break
+    rendered = next
+  }
+  return rendered
+}
+
+// A single substitution pass — the replacement text is never rescanned, so a
+// caller-supplied value can never be reinterpreted as a template.
+const substitute = (
+  source: string,
+  context: Record<string, unknown>,
+  escape: boolean,
+  slot?: string
+): string =>
+  source.replace(TEMPLATE_TOKEN, (_match, rawTriple, rawDouble) => {
+    const { raw, key } = readToken(rawTriple, rawDouble)
+    // `content` is the layout's slot for the body that was already rendered and
+    // escaped, so it is the one value written in raw. Only the layout gets it:
+    // honouring it everywhere would let a caller pass `data.content` into a
+    // template that happens to name it and have it emitted unescaped.
+    if (slot !== undefined && key === slot) {
+      return typeof context[slot] === 'string' ? (context[slot] as string) : ''
+    }
+    if (key.startsWith('>')) {
+      return ''
+    }
+    const value = getNestedValue(context, key)
+    return raw || !escape ? value : escapeHtml(value)
+  })
+
+const renderTemplate = (
+  source: string,
+  partials: Record<string, string>,
+  context: Record<string, unknown>,
+  escape: boolean,
+  slot?: string
+): string => {
+  const composed = expandTrusted(
+    expandPartials(source, partials),
+    context,
+    escape
+  )
+  return substitute(composed, context, escape, slot)
+}
+
+export const renderEmail = (
+  { theme, locales, partials, templates }: EmailAssets,
+  { name, locale: requestedLocale, data }: RenderEmailRequest
+): RenderedEmailResult => {
+  const locale = requestedLocale ?? 'en'
+  const template = templates[name]
+  if (!template) {
+    throw new Error(`Unknown email template: ${name}`)
+  }
+
+  const strings = locales[locale]
+  if (!strings) {
+    throw new Error(`Unknown email locale: ${locale}`)
+  }
+
+  const values = data ?? {}
+  const appName =
+    (typeof values.appName === 'string' && values.appName) ||
+    getNestedValue(theme, 'appName')
+
+  const baseContext = {
+    ...values,
+    locale,
+    theme,
+    t: strings,
+    appName,
+  }
+
+  const subject = renderTemplate(
+    template.subject,
+    partials,
+    baseContext,
+    false
+  ).trim()
+
+  const htmlBody = renderTemplate(
+    template.html,
+    partials,
+    { ...baseContext, subject },
+    true
+  )
+
+  const html = partials.layout
+    ? renderTemplate(
+        partials.layout,
+        partials,
+        { ...baseContext, subject, content: htmlBody },
+        true,
+        'content'
+      )
+    : htmlBody
+
+  const text = template.text
+    ? renderTemplate(
+        template.text,
+        partials,
+        { ...baseContext, subject },
+        false
+      ).trim()
+    : undefined
+
+  return {
+    locale,
+    subject,
+    html,
+    ...(text ? { text } : {}),
+    variables: template.variables,
+    hash: template.hashes[locale]?.contentHash ?? '',
+  }
+}

package/src/services/http-personas.ts

@@ -51,7 +51,12 @@ export interface HttpPersonasConfig {
   operator?: OperatorSignInOptions
   /** Persona id → the declaration with its address filled in. */
   personas: Record<string, ResolvedPersona>
-  /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
+  /**
+   * Sign-in path under apiUrl, for whichever of the two paths is in use — an
+   * app that mounts auth under `/api` moves both. Default: the actor plugin's
+   * `/auth/sign-in/actor`, or `/auth/sign-in/fabric` for an operator.
+   * {@link OperatorSignInOptions.signInPath} overrides it.
+   */
   signInPath?: string
   /** Where the session (and its roles) is read back. Default `/auth/get-session`. */
   sessionPath?: string
@@ -92,7 +97,10 @@ export class HttpPersona implements ScenarioPersona {
   ) {
     this.jar = createCookieJar(config.apiUrl)
     if (config.operator) {
-      this.signIn = new OperatorSignIn(config.apiUrl, config.operator)
+      this.signIn = new OperatorSignIn(config.apiUrl, {
+        ...config.operator,
+        signInPath: config.operator.signInPath ?? config.signInPath,
+      })
     } else if (config.secret) {
       this.signIn = new ActorSignIn(
         config.apiUrl,

package/src/services/index.ts

@@ -53,6 +53,14 @@ export type {
   SendTemplateEmailInput,
   SendTextEmailInput,
 } from './email-service.js'
+export {
+  renderEmail,
+  type EmailAssets,
+  type EmailTemplateAssets,
+  type EmailTemplateHashes,
+  type RenderEmailRequest,
+  type RenderedEmailResult,
+} from './email-template.js'
 export {
   DEFAULT_WEBHOOK_RETRIES,
   PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,

package/src/services/persona-sign-in.test.ts

@@ -115,6 +115,28 @@ describe('operator persona sign-in', () => {
     assert.equal(stage.createdCount, 0)
   })
 
+  // An app that mounts auth somewhere other than the root moves both sign-in
+  // paths together, and `SCENARIO_SIGN_IN_PATH` is the only place it can say so.
+  test('honours a moved sign-in path the same way the actor path does', async () => {
+    const stage = await startStage([
+      { id: 'user-7', email: 'customer@personas.invalid' },
+    ])
+    servers.push(stage.server)
+
+    const personas = createHttpPersonas({
+      apiUrl: stage.apiUrl.replace(/\/api$/, ''),
+      operator: { token: OPERATOR_TOKEN },
+      signInPath: '/api/auth/sign-in/fabric',
+      rpcPath: '/api/rpc',
+      personas: { customer: persona('customer@personas.invalid') },
+    })
+
+    const result = (await personas.customer!.invoke('whoami', {})) as {
+      actingAs: string | null
+    }
+    assert.equal(result.actingAs, 'user-7')
+  })
+
   test('refuses a persona the stage has no account for', async () => {
     const stage = await startStage([])
     servers.push(stage.server)

package/src/wirings/agent/agent-helpers.test.ts

@@ -6,6 +6,7 @@ import {
   agentResume,
   agentApprove,
 } from './agent-helpers.js'
+import { agentCallOptions } from './agent-prepare.js'
 
 describe('agent helpers', () => {
   describe('agent', () => {
@@ -150,3 +151,65 @@ describe('agent helpers', () => {
     })
   })
 })
+
+describe('agentCallOptions', () => {
+  // An explicit `undefined` overrides the agent's own declared default with
+  // nothing, so a request that names no model would silently unset the one the
+  // agent declares.
+  test('a field nobody supplied is left out rather than sent as undefined', () => {
+    const options = agentCallOptions({
+      message: 'hello',
+      threadId: 't1',
+      resourceId: 'r1',
+    })
+    assert.equal('model' in options, false)
+    assert.equal('temperature' in options, false)
+    assert.equal('context' in options, false)
+    assert.equal('attachments' in options, false)
+  })
+
+  test('what was supplied is carried through unchanged', () => {
+    const options = agentCallOptions({
+      message: 'hello',
+      threadId: 't1',
+      resourceId: 'user-1',
+      model: 'a-model',
+      temperature: 0.2,
+      context: 'some context',
+      attachments: [{ type: 'image' as const, url: 'a.png' }],
+    })
+    assert.deepEqual(options, {
+      message: 'hello',
+      threadId: 't1',
+      resourceId: 'user-1',
+      attachments: [{ type: 'image' as const, url: 'a.png' }],
+      model: 'a-model',
+      temperature: 0.2,
+      context: 'some context',
+    })
+  })
+
+  // Zero is a temperature a caller can mean, and the falsy check every other
+  // field uses would drop it.
+  test('a temperature of zero survives, unlike an empty string', () => {
+    assert.equal(
+      agentCallOptions({
+        message: 'x',
+        threadId: 't',
+        resourceId: 'r',
+        temperature: 0,
+      }).temperature,
+      0
+    )
+    assert.equal(
+      'context' in
+        agentCallOptions({
+          message: 'x',
+          threadId: 't',
+          resourceId: 'r',
+          context: '',
+        }),
+      false
+    )
+  })
+})

package/src/wirings/agent/agent-prepare.ts

@@ -149,6 +149,31 @@ export function canAccessThread(
   )
 }
 
+/**
+ * An agent call with the fields nobody supplied left out.
+ *
+ * Omitted rather than passed as `undefined`, because an explicit `undefined`
+ * overrides the agent's own declared default with nothing — a request that
+ * names no model would silently unset the one the agent declares.
+ *
+ * Shared by the scaffolded `run` and `stream` routes, which receive the same
+ * input and differ only in what they do with the reply. `agentName` is not part
+ * of it: both callers pass that separately, because `rpc.agent.run` and
+ * `rpc.agent.stream` take it as their first argument and type the rest
+ * against it.
+ */
+export const agentCallOptions = (input: AgentInput): AgentInput => ({
+  message: input.message,
+  threadId: input.threadId,
+  resourceId: input.resourceId,
+  ...(input.attachments ? { attachments: input.attachments } : {}),
+  ...(input.model ? { model: input.model } : {}),
+  ...(input.temperature !== undefined
+    ? { temperature: input.temperature }
+    : {}),
+  ...(input.context ? { context: input.context } : {}),
+})
+
 export type StreamAgentOptions = {
   requiresToolApproval?: 'all' | 'explicit' | false
   onRunCreated?: (runId: string) => void

package/src/wirings/agent/index.ts

@@ -33,6 +33,7 @@ export {
   type StreamAgentOptions,
   ToolApprovalRequired,
   ToolCredentialRequired,
+  agentCallOptions,
   canAccessThread,
   isOwnedByPrincipal,
   threadOwnerConstraint,

package/src/wirings/persona/index.ts

@@ -16,6 +16,11 @@ export type {
   PersonaEnvironmentSubject,
 } from './persona-environments.js'
 export { personaEmail, personaEmails } from './persona-email.js'
+export {
+  APP_SCOPE_ROOT,
+  appScopeId,
+  buildAppScopeDefinition,
+} from './persona-app-scopes.js'
 export type {
   MailboxAllowlist,
   PersonaMailbox,

package/src/wirings/persona/persona-app-scopes.test.ts

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+import {
+  appScopeId,
+  buildAppScopeDefinition,
+  declaredApps,
+} from './persona-app-scopes.js'
+
+const persona = (id: string, app?: string) =>
+  ({ id, name: id, roles: [], goals: [], tags: [], runnable: true, app }) as any
+
+describe('declaredApps', () => {
+  test('deduplicates and sorts the apps the personas name', () => {
+    assert.deepEqual(
+      declaredApps([
+        persona('a', 'staff'),
+        persona('b', 'portal'),
+        persona('c', 'staff'),
+      ]),
+      ['portal', 'staff']
+    )
+  })
+
+  test('ignores personas that name no app', () => {
+    assert.deepEqual(declaredApps([persona('a'), persona('b', '')]), [])
+  })
+})
+
+describe('buildAppScopeDefinition', () => {
+  test('renders one grantable child per app under the app root', () => {
+    const definition = buildAppScopeDefinition([
+      persona('a', 'staff'),
+      persona('b', 'portal'),
+    ])
+
+    assert.equal(definition?.name, 'app')
+    assert.deepEqual(Object.keys(definition?.scopes ?? {}).sort(), [
+      'portal',
+      'staff',
+    ])
+    assert.equal(appScopeId('staff'), 'app:staff')
+  })
+
+  test('is null for a single-frontend product', () => {
+    assert.equal(buildAppScopeDefinition([persona('a')]), null)
+  })
+})

package/src/wirings/persona/persona-app-scopes.ts

@@ -0,0 +1,74 @@
+import type { ScopeDefinitionMeta, ScopeNodeMeta } from '../scope/scope.types.js'
+import type { PersonaMeta } from './persona.types.js'
+
+/**
+ * The root every app grant hangs off. One segment, so a grant of `app` alone
+ * means "may use all of them" under the same parent-grant rule the admin tree
+ * relies on — which is what a support operator or an internal tool wants, and
+ * what a per-app boolean column could never express.
+ */
+export const APP_SCOPE_ROOT = 'app'
+
+/** `app:staff` for `staff`. */
+export const appScopeId = (app: string) => `${APP_SCOPE_ROOT}:${app}`
+
+/**
+ * The apps named across the declared personas, sorted and deduplicated.
+ *
+ * The personas *are* the registry. There is no separate list of apps to keep in
+ * step, because a frontend nobody signs into is not a thing the auth layer has
+ * an opinion about — and the moment somebody does sign into it, they are a
+ * persona and they name it.
+ */
+export const declaredApps = (personas: PersonaMeta[]): string[] =>
+  [
+    ...new Set(
+      personas
+        .map((persona) => persona.app)
+        .filter((app): app is string => typeof app === 'string' && app !== '')
+    ),
+  ].sort()
+
+/**
+ * The `app` scope tree, synthesised from the personas that name an app.
+ *
+ * Which frontend a person may sign into is a different question from what they
+ * may do once inside it, but it is the same *kind* of question — a grant that
+ * an admin can make and revoke at runtime, that resolves at the session
+ * boundary, and that a restricted API key can decline to inherit. So it is
+ * carried as a scope rather than a `can_access_<app>` column: no migration per
+ * app, one query for "which apps may this user reach", and no second
+ * authorization mechanism to keep honest.
+ *
+ * Synthesised rather than written by hand because the declaration already
+ * exists. Asking an app to also spell out `defineScope({ app: { staff: {} } })`
+ * beside its personas invites the two to drift, and the failure that produces —
+ * a persona provisioned with a grant the vocabulary no longer declares — is one
+ * `pikku scopes prune` away from silently revoking sign-in.
+ *
+ * Null when no persona names an app, which is the single-frontend case: nothing
+ * to declare, and no empty root cluttering the console's grant list.
+ */
+export const buildAppScopeDefinition = (
+  personas: PersonaMeta[]
+): ScopeDefinitionMeta | null => {
+  const apps = declaredApps(personas)
+  if (apps.length === 0) {
+    return null
+  }
+
+  const scopes: Record<string, ScopeNodeMeta> = {}
+  for (const app of apps) {
+    scopes[app] = {
+      displayName: app,
+      description: `May sign in to the ${app} app`,
+    }
+  }
+
+  return {
+    name: APP_SCOPE_ROOT,
+    displayName: 'Apps',
+    description: 'Which frontend a person may sign in to',
+    scopes,
+  }
+}