@pikku/cli 0.12.43 → 0.12.44

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

@@ -8,18 +8,57 @@ import { serializeEmailsModule } from './serialize-emails.js';
 function sha256(input) {
     return createHash('sha256').update(input).digest('hex');
 }
-function extractVariables(...sources) {
+function resolveLocaleString(strings, dottedPath) {
+    let current = strings;
+    for (const segment of dottedPath.split('.')) {
+        if (!current || typeof current !== 'object' || !(segment in current))
+            return undefined;
+        current = current[segment];
+    }
+    return typeof current === 'string' ? current : undefined;
+}
+// Variables a template actually references — scoped to the locale keys and
+// partials it uses (transitively), not every string in the shared locale file.
+function collectTemplateVariables(rootSources, locales, partials) {
     const variables = new Set();
-    for (const source of sources) {
+    const visited = new Set();
+    const queue = [...rootSources];
+    while (queue.length > 0) {
+        const source = queue.shift();
+        if (!source)
+            continue;
         for (const match of source.matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) {
             const key = String(match[1]).trim();
-            if (!key || key === 'content' || key.startsWith('>'))
+            if (!key)
+                continue;
+            if (key.startsWith('>')) {
+                const name = key.slice(1).trim();
+                if (!visited.has(`partial:${name}`)) {
+                    visited.add(`partial:${name}`);
+                    if (partials[name])
+                        queue.push(partials[name]);
+                }
                 continue;
+            }
             const rootKey = key.split('.')[0];
-            if (rootKey === 't' || rootKey === 'theme' || rootKey === 'locale')
+            if (rootKey === 'content' ||
+                rootKey === 'subject' ||
+                rootKey === 'theme' ||
+                rootKey === 'locale') {
                 continue;
-            if (rootKey === 'subject')
+            }
+            if (rootKey === 't') {
+                const path = key.split('.').slice(1).join('.');
+                if (!path || visited.has(`t:${path}`))
+                    continue;
+                visited.add(`t:${path}`);
+                for (const strings of Object.values(locales)) {
+                    const resolved = resolveLocaleString(strings, path);
+                    if (resolved)
+                        queue.push(resolved);
+                }
                 continue;
+            }
             variables.add(rootKey);
         }
     }
@@ -37,18 +76,6 @@ function stableStringify(value) {
     }
     return JSON.stringify(value);
 }
-function collectStringLeaves(value) {
-    if (typeof value === 'string') {
-        return [value];
-    }
-    if (Array.isArray(value)) {
-        return value.flatMap((item) => collectStringLeaves(item));
-    }
-    if (value && typeof value === 'object') {
-        return Object.values(value).flatMap((nested) => collectStringLeaves(nested));
-    }
-    return [];
-}
 export const pikkuEmails = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
         return generateEmailsArtifacts(logger, config);
@@ -116,8 +143,10 @@ export async function generateEmailsArtifacts(logger, config) {
             readFile(join(emailDir, 'templates', `${templateName}.subject.txt`), 'utf8'),
             readFile(join(emailDir, 'templates', `${templateName}.text.txt`), 'utf8').catch(() => ''),
         ]);
-        const localeSources = Object.values(locales).flatMap((strings) => collectStringLeaves(strings));
-        const variables = extractVariables(html, subject, text, ...Object.values(partials), ...localeSources);
+        // layout.html wraps every template at render time (see serialize-emails),
+        // so include it as a discovery root or layout-only variables get dropped.
+        const layout = partials.layout ?? '';
+        const variables = collectTemplateVariables([html, subject, text, layout], locales, partials);
         const hashes = Object.fromEntries(Object.entries(locales).map(([locale, strings]) => {
             const localePayload = stableStringify({
                 templateName,

package/dist/src/scaffold/rpc-remote.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.43
+ * This file was generated by @pikku/cli@0.12.44
  */
 /**
  * Auto-generated remote internal RPC queue worker and HTTP endpoint

package/dist/src/services/cli-logger-forwarder.service.d.ts

@@ -1,7 +1,7 @@
 import type { Logger } from '@pikku/core/services';
 import { LogLevel } from '@pikku/core/services';
 import type { PikkuChannel } from '@pikku/core/channel';
-import type { ErrorCode } from '@pikku/inspector';
+import type { ErrorCode, CodedDiagnostic, DiagnosticSeverity } from '@pikku/inspector';
 /**
  * Log message structure sent through the channel
  */
@@ -29,6 +29,9 @@ export declare class CLILoggerForwarder implements Logger {
     warn(messageOrObj: string | Record<string, any>, ..._meta: any[]): void;
     debug(message: string, ..._meta: any[]): void;
     trace(message: string, ..._meta: any[]): void;
+    diagnostic({ severity, code, message }: CodedDiagnostic): void;
     critical(code: ErrorCode, message: string): void;
     hasCriticalErrors(): boolean;
+    hasBlockingDiagnostics(): boolean;
+    blockingSeverities(): DiagnosticSeverity[];
 }

package/dist/src/services/cli-logger-forwarder.service.js

@@ -59,13 +59,31 @@ export class CLILoggerForwarder {
     trace(message, ..._meta) {
         this.log('trace', LogLevel.trace, message);
     }
-    critical(code, message) {
+    diagnostic({ severity, code, message }) {
+        // Delegate tracking to the underlying CLILogger so the build gate still
+        // sees diagnostics emitted through the forwarder, then forward to the
+        // channel for display.
+        ;
+        this.logger.diagnostic?.({ severity, code, message });
         const url = `https://pikku.dev/docs/pikku-cli/errors/${code.toLowerCase()}`;
         const formattedMessage = `[${code}] ${message}\n  → ${url}`;
-        this.error(formattedMessage);
+        if (severity === 'warn')
+            this.warn(formattedMessage);
+        else
+            this.error(formattedMessage);
+    }
+    critical(code, message) {
+        this.diagnostic({ severity: 'critical', code, message });
     }
     hasCriticalErrors() {
         // The underlying logger (CLILogger) tracks critical errors
         return this.logger.hasCriticalErrors?.() ?? false;
     }
+    hasBlockingDiagnostics() {
+        // The underlying logger (CLILogger) owns failOn + diagnostic tracking
+        return this.logger.hasBlockingDiagnostics?.() ?? false;
+    }
+    blockingSeverities() {
+        return this.logger.blockingSeverities?.() ?? [];
+    }
 }

package/dist/src/services/cli-logger.service.d.ts

@@ -1,11 +1,12 @@
 import type { Logger } from '@pikku/core/services';
 import { LogLevel } from '@pikku/core/services';
-import type { ErrorCode } from '@pikku/inspector';
+import type { ErrorCode, DiagnosticSeverity, CodedDiagnostic } from '@pikku/inspector';
 export type CLIOutputMode = 'text' | 'json';
 export declare class CLILogger implements Logger {
     private silent;
     private level;
-    private criticalErrors;
+    private diagnostics;
+    private failOn;
     private outputMode;
     private jsonFlushHookRegistered;
     constructor({ logLogo, silent, }: {
@@ -42,7 +43,20 @@ export declare class CLILogger implements Logger {
         type?: string;
         data?: Record<string, unknown>;
     }): void;
+    diagnostic({ severity, code, message }: CodedDiagnostic): void;
+    /** Sugar for `diagnostic({ severity: 'critical', code, message })`. */
     critical(code: ErrorCode, message: string): void;
+    /**
+     * Configure which severities fail the build. Critical is always included.
+     */
+    setFailOn(severities: Iterable<DiagnosticSeverity>): void;
     hasCriticalErrors(): boolean;
+    /**
+     * True if any tracked diagnostic matches a severity configured to fail the
+     * build (default: critical only).
+     */
+    hasBlockingDiagnostics(): boolean;
+    /** Distinct severities among tracked diagnostics that would fail the build. */
+    blockingSeverities(): DiagnosticSeverity[];
     logLogo(): void;
 }

package/dist/src/services/cli-logger.service.js

@@ -9,7 +9,12 @@ const ANSI_ESCAPE_REGEX = /\x1B\[[0-?]*[ -/]*[@-~]/g;
 export class CLILogger {
     silent;
     level = LogLevel.info; // default to info level
-    criticalErrors = [];
+    diagnostics = [];
+    // Severities that should fail the build. Critical always blocks; error/warn
+    // are opt-in via --fail-on-error / --fail-on-warn.
+    failOn = new Set([
+        'critical',
+    ]);
     outputMode = 'text';
     jsonFlushHookRegistered = false;
     constructor({ logLogo, silent = false, }) {
@@ -138,14 +143,37 @@ export class CLILogger {
         const data = typeof message === 'string' ? undefined : message.data;
         this.emit('debug', msg, type, undefined, data);
     }
-    critical(code, message) {
+    diagnostic({ severity, code, message }) {
         const url = `${BASE_ERROR_URL}/${code.toLowerCase()}`;
         const formattedMessage = `[${code}] ${message}\n  → ${url}`;
-        this.criticalErrors.push(formattedMessage);
-        this.emit('critical', formattedMessage, undefined, code);
+        this.diagnostics.push({ severity, code, message });
+        // critical → bold red, error → red, warn → yellow. Always printed so the
+        // issue surfaces even when it doesn't fail the build.
+        this.emit(severity, formattedMessage, undefined, code);
+    }
+    /** Sugar for `diagnostic({ severity: 'critical', code, message })`. */
+    critical(code, message) {
+        this.diagnostic({ severity: 'critical', code, message });
+    }
+    /**
+     * Configure which severities fail the build. Critical is always included.
+     */
+    setFailOn(severities) {
+        this.failOn = new Set(['critical', ...severities]);
     }
     hasCriticalErrors() {
-        return this.criticalErrors.length > 0;
+        return this.diagnostics.some((d) => d.severity === 'critical');
+    }
+    /**
+     * True if any tracked diagnostic matches a severity configured to fail the
+     * build (default: critical only).
+     */
+    hasBlockingDiagnostics() {
+        return this.diagnostics.some((d) => this.failOn.has(d.severity));
+    }
+    /** Distinct severities among tracked diagnostics that would fail the build. */
+    blockingSeverities() {
+        return [...this.failOn].filter((s) => this.diagnostics.some((d) => d.severity === s));
     }
     logLogo() {
         if (this.silent || this.outputMode === 'json')

package/dist/src/services.js

@@ -79,6 +79,13 @@ export const createConfig = async (_variablesService, data) => {
     }
     logger.setLevel(logLevel);
     logger.setSilent(isSilent);
+    // Build gate: critical always fails; --fail-on-warn implies --fail-on-error.
+    const extraFailOn = [];
+    if (data.failOnWarn)
+        extraFailOn.push('warn', 'error');
+    else if (data.failOnError)
+        extraFailOn.push('error');
+    logger.setFailOn(extraFailOn);
     // Display logo unless in silent mode
     if (!isSilent && outputMode !== 'json') {
         logger.logLogo();

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../bin/pikku.ts","../src/cli.wiring.ts","../src/services.ts","../src/deploy/build-pipeline.ts","../src/deploy/provider-adapter.ts","../src/deploy/server-entry.ts","../src/deploy/analyzer/analyzer.ts","../src/deploy/analyzer/index.ts","../src/deploy/analyzer/manifest.ts","../src/deploy/bundler/bundler.ts","../src/deploy/bundler/dep-extractor.ts","../src/deploy/bundler/index.ts","../src/deploy/bundler/types.ts","../src/deploy/codegen/index.ts","../src/deploy/codegen/per-unit-codegen.ts","../src/deploy/plan/executor.ts","../src/deploy/plan/formatter.ts","../src/deploy/plan/index.ts","../src/deploy/plan/planner.ts","../src/deploy/plan/provider.ts","../src/deploy/plan/types.ts","../src/fabric/fabric-commands.ts","../src/fabric/functions/db-schema.function.ts","../src/fabric/functions/deploy-list.function.ts","../src/fabric/functions/deploy-units.function.ts","../src/fabric/functions/deploy.function.ts","../src/fabric/functions/domains-add.function.ts","../src/fabric/functions/domains-list.function.ts","../src/fabric/functions/domains-remove.function.ts","../src/fabric/functions/errors.function.ts","../src/fabric/functions/init.function.ts","../src/fabric/functions/link.function.ts","../src/fabric/functions/llm-key.function.ts","../src/fabric/functions/login.function.ts","../src/fabric/functions/logs.function.ts","../src/fabric/functions/metrics.function.ts","../src/fabric/functions/rollback.function.ts","../src/fabric/functions/secrets-list.function.ts","../src/fabric/functions/secrets-set.function.ts","../src/fabric/functions/smoke.function.ts","../src/fabric/functions/status.function.ts","../src/fabric/functions/trace.function.ts","../src/fabric/functions/validate-core.ts","../src/fabric/functions/validate.function.ts","../src/fabric/lib/config.ts","../src/fabric/lib/console-url.ts","../src/fabric/lib/git.ts","../src/fabric/lib/http.ts","../src/fabric/lib/not-implemented.ts","../src/fabric/lib/output.ts","../src/fabric/lib/prompt.ts","../src/fabric/lib/stage.ts","../src/fabric/sdk/http-map.gen.d.ts","../src/fabric/sdk/pikku-fetch.gen.ts","../src/fabric/sdk/pikku-rpc.gen.ts","../src/fabric/sdk/rpc-map.gen.d.ts","../src/functions/commands/all.ts","../src/functions/commands/binary.ts","../src/functions/commands/bootstrap.ts","../src/functions/commands/console.ts","../src/functions/commands/db-audit.ts","../src/functions/commands/db-generate.ts","../src/functions/commands/db-migrate.ts","../src/functions/commands/db-reset.ts","../src/functions/commands/db-seed.ts","../src/functions/commands/db-shared.ts","../src/functions/commands/deploy-apply.ts","../src/functions/commands/deploy-info.ts","../src/functions/commands/deploy-plan.ts","../src/functions/commands/dev.ts","../src/functions/commands/emails-init.ts","../src/functions/commands/enable.ts","../src/functions/commands/info.ts","../src/functions/commands/load-user-project.ts","../src/functions/commands/login.ts","../src/functions/commands/meta.ts","../src/functions/commands/new-addon.ts","../src/functions/commands/new-function.ts","../src/functions/commands/new-middleware.ts","../src/functions/commands/new-permission.ts","../src/functions/commands/new-wiring.ts","../src/functions/commands/pikku-command-bootstrap.ts","../src/functions/commands/pikku-command-summary.ts","../src/functions/commands/skills.ts","../src/functions/commands/tests-coverage.ts","../src/functions/commands/tests-init.ts","../src/functions/commands/versions-check.ts","../src/functions/commands/versions-init.ts","../src/functions/commands/versions-update.ts","../src/functions/commands/watch.ts","../src/functions/commands/workspace-validate.ts","../src/functions/db/annotation-parser.ts","../src/functions/db/better-auth-schema.ts","../src/functions/db/coercion-plugin.ts","../src/functions/db/db-codegen.ts","../src/functions/db/db-introspector.ts","../src/functions/db/db-migrator.ts","../src/functions/db/local-db.ts","../src/functions/db/zod-codegen.ts","../src/functions/db/postgres/pglite-kysely.ts","../src/functions/db/postgres/postgres-introspector.ts","../src/functions/db/postgres/postgres-migrator.ts","../src/functions/db/sqlite/seed.ts","../src/functions/db/sqlite/sqlite-introspector.ts","../src/functions/db/sqlite/sqlite-kysely.ts","../src/functions/db/sqlite/sqlite-migrator.ts","../src/functions/db/sqlite/sqlite-runtime-bun.ts","../src/functions/db/sqlite/sqlite-runtime-node.ts","../src/functions/db/sqlite/sqlite-runtime.ts","../src/functions/runtimes/fetch/index.ts","../src/functions/runtimes/nextjs/pikku-command-nextjs.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-worker-rpc-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-http-wrapper.ts","../src/functions/runtimes/tanstack-start/pikku-command-tanstack-start.ts","../src/functions/runtimes/tanstack-start/serialize-tanstack-start-shim.ts","../src/functions/runtimes/websocket/pikku-command-websocket-typed.ts","../src/functions/runtimes/websocket/serialize-websocket-wrapper.ts","../src/functions/validate/workspace-validate.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent-types.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent.ts","../src/functions/wirings/ai-agent/pikku-command-public-agent.ts","../src/functions/wirings/ai-agent/serialize-agent-map.ts","../src/functions/wirings/ai-agent/serialize-ai-agent-types.ts","../src/functions/wirings/ai-agent/serialize-public-agent.ts","../src/functions/wirings/auth/pikku-command-auth.ts","../src/functions/wirings/auth/serialize-auth-gen.ts","../src/functions/wirings/auth/serialize-auth-meta.ts","../src/functions/wirings/auth/serialize-auth-types.ts","../src/functions/wirings/channels/pikku-channels.ts","../src/functions/wirings/channels/pikku-command-channel-types.ts","../src/functions/wirings/channels/pikku-command-channels-map.ts","../src/functions/wirings/channels/pikku-command-channels.ts","../src/functions/wirings/channels/serialize-channel-types.ts","../src/functions/wirings/channels/serialize-typed-channel-map.ts","../src/functions/wirings/cli/pikku-command-cli-entry.ts","../src/functions/wirings/cli/pikku-command-cli-types.ts","../src/functions/wirings/cli/pikku-command-cli.ts","../src/functions/wirings/cli/serialize-channel-cli-client.ts","../src/functions/wirings/cli/serialize-channel-cli.ts","../src/functions/wirings/cli/serialize-cli-types.ts","../src/functions/wirings/cli/serialize-local-cli-bootstrap.ts","../src/functions/wirings/console/pikku-command-console-functions.ts","../src/functions/wirings/console/pikku-command-node-types.ts","../src/functions/wirings/console/pikku-command-nodes-meta.ts","../src/functions/wirings/console/serialize-console-functions.ts","../src/functions/wirings/console/serialize-node-types.ts","../src/functions/wirings/credentials/pikku-command-credentials.ts","../src/functions/wirings/credentials/serialize-credentials-types.ts","../src/functions/wirings/emails/pikku-command-emails.ts","../src/functions/wirings/emails/serialize-emails.ts","../src/functions/wirings/functions/pikku-command-addon-types.ts","../src/functions/wirings/functions/pikku-command-function-types-split.ts","../src/functions/wirings/functions/pikku-command-function-types.ts","../src/functions/wirings/functions/pikku-command-functions.ts","../src/functions/wirings/functions/pikku-command-services.ts","../src/functions/wirings/functions/schemas.ts","../src/functions/wirings/functions/serialize-addon-types.ts","../src/functions/wirings/functions/serialize-function-imports.ts","../src/functions/wirings/functions/serialize-function-types.ts","../src/functions/wirings/functions/serialize-pikku-types-hub.ts","../src/functions/wirings/gateway/pikku-command-gateway.ts","../src/functions/wirings/http/pikku-command-http-map.ts","../src/functions/wirings/http/pikku-command-http-routes.ts","../src/functions/wirings/http/pikku-command-http-types.ts","../src/functions/wirings/http/pikku-command-openapi.ts","../src/functions/wirings/http/pikku-http-routes.ts","../src/functions/wirings/http/serialize-fetch-wrapper.ts","../src/functions/wirings/http/serialize-http-types.ts","../src/functions/wirings/http/serialize-typed-http-map.ts","../src/functions/wirings/mcp/pikku-command-mcp-json.ts","../src/functions/wirings/mcp/pikku-command-mcp-types.ts","../src/functions/wirings/mcp/pikku-command-mcp.ts","../src/functions/wirings/mcp/serialize-mcp-types.ts","../src/functions/wirings/middleware/pikku-command-middleware.ts","../src/functions/wirings/middleware/serialize-middleware-imports.ts","../src/functions/wirings/package/pikku-command-package-types.ts","../src/functions/wirings/package/pikku-command-package.ts","../src/functions/wirings/package/serialize-package-types.ts","../src/functions/wirings/package/serialize-package.ts","../src/functions/wirings/permissions/pikku-command-permissions.ts","../src/functions/wirings/permissions/serialize-permissions-imports.ts","../src/functions/wirings/queue/pikku-command-queue-map.ts","../src/functions/wirings/queue/pikku-command-queue-service.ts","../src/functions/wirings/queue/pikku-command-queue-types.ts","../src/functions/wirings/queue/pikku-command-queue.ts","../src/functions/wirings/queue/pikku-queue-map.ts","../src/functions/wirings/queue/pikku-queue.ts","../src/functions/wirings/queue/serialize-queue-map.ts","../src/functions/wirings/queue/serialize-queue-meta.ts","../src/functions/wirings/queue/serialize-queue-types.ts","../src/functions/wirings/queue/serialize-queue-wrapper.ts","../src/functions/wirings/realtime/pikku-command-events-scaffold.ts","../src/functions/wirings/realtime/pikku-command-realtime.ts","../src/functions/wirings/realtime/serialize-events-scaffold.ts","../src/functions/wirings/realtime/serialize-realtime-client.ts","../src/functions/wirings/rpc/pikku-command-public-rpc.ts","../src/functions/wirings/rpc/pikku-command-react-query.ts","../src/functions/wirings/rpc/pikku-command-remote-rpc.ts","../src/functions/wirings/rpc/pikku-command-rpc-client.ts","../src/functions/wirings/rpc/pikku-command-rpc-map.ts","../src/functions/wirings/rpc/pikku-command-rpc.ts","../src/functions/wirings/rpc/serialize-public-rpc.ts","../src/functions/wirings/rpc/serialize-react-query-hooks.ts","../src/functions/wirings/rpc/serialize-remote-rpc.ts","../src/functions/wirings/rpc/serialize-rpc-wrapper.ts","../src/functions/wirings/rpc/serialize-typed-rpc-map.ts","../src/functions/wirings/scheduler/pikku-command-scheduler-types.ts","../src/functions/wirings/scheduler/pikku-command-scheduler.ts","../src/functions/wirings/scheduler/serialize-scheduler-meta.ts","../src/functions/wirings/scheduler/serialize-scheduler-types.ts","../src/functions/wirings/secrets/pikku-command-secrets.ts","../src/functions/wirings/secrets/serialize-secrets-types.ts","../src/functions/wirings/triggers/pikku-command-trigger-types.ts","../src/functions/wirings/triggers/pikku-command-trigger.ts","../src/functions/wirings/triggers/serialize-trigger-meta.ts","../src/functions/wirings/triggers/serialize-trigger-types.ts","../src/functions/wirings/variables/pikku-command-variables.ts","../src/functions/wirings/variables/serialize-variables-types.ts","../src/functions/wirings/workflow/pikku-command-workflow-routes.ts","../src/functions/wirings/workflow/pikku-command-workflow.ts","../src/functions/wirings/workflow/serialize-workflow-bootstrap-map.ts","../src/functions/wirings/workflow/serialize-workflow-map.ts","../src/functions/wirings/workflow/serialize-workflow-meta.ts","../src/functions/wirings/workflow/serialize-workflow-registration.ts","../src/functions/wirings/workflow/serialize-workflow-routes.ts","../src/functions/wirings/workflow/serialize-workflow-types.ts","../src/functions/workflows/all.workflow.ts","../src/middleware/log-command-info-and-time.ts","../src/scaffold/rpc-remote.gen.ts","../src/services/cli-logger-forwarder.service.ts","../src/services/cli-logger.service.ts","../src/utils/check-required-types.ts","../src/utils/cli-session.ts","../src/utils/command-summary.ts","../src/utils/contract-versions.ts","../src/utils/device-auth.ts","../src/utils/file-import-path.ts","../src/utils/file-imports-serializer.ts","../src/utils/file-writer.ts","../src/utils/generate-bootstrap-file.ts","../src/utils/get-cli-version.ts","../src/utils/parse-cli-filters.ts","../src/utils/pikku-cli-config.ts","../src/utils/pikku-files-and-methods.ts","../src/utils/serialize-import-map.ts","../src/utils/serialize-meta-ts.ts","../src/utils/serialize-schemas.ts","../src/utils/strip-verbose-meta.ts","../.pikku/pikku-bootstrap.gen.ts","../.pikku/pikku-meta-service.gen.ts","../.pikku/pikku-services.gen.ts","../.pikku/pikku-types.gen.ts","../.pikku/agent/pikku-agent-map.gen.d.ts","../.pikku/agent/pikku-agent-types.gen.ts","../.pikku/channel/pikku-channel-types.gen.ts","../.pikku/cli/pikku-cli-channel.ts","../.pikku/cli/pikku-cli-client.gen.ts","../.pikku/cli/pikku-cli-types.gen.ts","../.pikku/cli/pikku-cli-wirings-meta.gen.ts","../.pikku/cli/pikku-cli-wirings.gen.ts","../.pikku/cli/pikku-cli.gen.ts","../.pikku/console/pikku-node-types.gen.ts","../.pikku/function/pikku-function-types.gen.ts","../.pikku/function/pikku-functions-meta.gen.ts","../.pikku/function/pikku-functions.gen.ts","../.pikku/http/pikku-http-types.gen.ts","../.pikku/http/pikku-http-wirings-map.gen.d.ts","../.pikku/http/pikku-http-wirings-meta.gen.ts","../.pikku/http/pikku-http-wirings.gen.ts","../.pikku/mcp/pikku-mcp-types.gen.ts","../.pikku/node/pikku-node-types.gen.ts","../.pikku/queue/pikku-queue-types.gen.ts","../.pikku/queue/pikku-queue-workers-wirings-map.gen.d.ts","../.pikku/queue/pikku-queue-workers-wirings-meta.gen.ts","../.pikku/queue/pikku-queue-workers-wirings.gen.ts","../.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-map.internal.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-meta.internal.gen.ts","../.pikku/scheduler/pikku-scheduler-types.gen.ts","../.pikku/schemas/register.gen.ts","../.pikku/secrets/pikku-secret-types.gen.ts","../.pikku/secrets/pikku-secrets.gen.ts","../.pikku/trigger/pikku-trigger-types.gen.ts","../.pikku/variables/pikku-variable-types.gen.ts","../.pikku/variables/pikku-variables.gen.ts","../.pikku/workflow/pikku-workflow-map.gen.d.ts","../.pikku/workflow/pikku-workflow-types.gen.ts","../.pikku/workflow/pikku-workflow-wirings-meta.gen.ts","../.pikku/workflow/pikku-workflow-wirings.gen.ts","../types/application-types.d.ts","../types/bun-sqlite.d.ts","../types/config.d.ts"],"version":"5.9.3"}
+{"root":["../bin/pikku.ts","../src/cli.wiring.ts","../src/services.ts","../src/deploy/build-pipeline.ts","../src/deploy/provider-adapter.ts","../src/deploy/server-entry.ts","../src/deploy/analyzer/analyzer.ts","../src/deploy/analyzer/index.ts","../src/deploy/analyzer/manifest.ts","../src/deploy/bundler/bundler.ts","../src/deploy/bundler/dep-extractor.ts","../src/deploy/bundler/index.ts","../src/deploy/bundler/types.ts","../src/deploy/codegen/index.ts","../src/deploy/codegen/per-unit-codegen.ts","../src/deploy/plan/executor.ts","../src/deploy/plan/formatter.ts","../src/deploy/plan/index.ts","../src/deploy/plan/planner.ts","../src/deploy/plan/provider.ts","../src/deploy/plan/types.ts","../src/fabric/fabric-commands.ts","../src/fabric/functions/add.function.ts","../src/fabric/functions/db-schema.function.ts","../src/fabric/functions/deploy-list.function.ts","../src/fabric/functions/deploy-units.function.ts","../src/fabric/functions/deploy.function.ts","../src/fabric/functions/domains-add.function.ts","../src/fabric/functions/domains-list.function.ts","../src/fabric/functions/domains-remove.function.ts","../src/fabric/functions/errors.function.ts","../src/fabric/functions/init.function.ts","../src/fabric/functions/link.function.ts","../src/fabric/functions/llm-key.function.ts","../src/fabric/functions/login.function.ts","../src/fabric/functions/logs.function.ts","../src/fabric/functions/metrics.function.ts","../src/fabric/functions/publish.function.ts","../src/fabric/functions/rollback.function.ts","../src/fabric/functions/secrets-list.function.ts","../src/fabric/functions/secrets-set.function.ts","../src/fabric/functions/smoke.function.ts","../src/fabric/functions/status.function.ts","../src/fabric/functions/trace.function.ts","../src/fabric/functions/validate-core.ts","../src/fabric/functions/validate.function.ts","../src/fabric/lib/config.ts","../src/fabric/lib/console-url.ts","../src/fabric/lib/git.ts","../src/fabric/lib/http.ts","../src/fabric/lib/not-implemented.ts","../src/fabric/lib/output.ts","../src/fabric/lib/prompt.ts","../src/fabric/lib/stage.ts","../src/fabric/sdk/http-map.gen.d.ts","../src/fabric/sdk/pikku-fetch.gen.ts","../src/fabric/sdk/pikku-rpc.gen.ts","../src/fabric/sdk/rpc-map.gen.d.ts","../src/functions/commands/all.ts","../src/functions/commands/binary.ts","../src/functions/commands/bootstrap.ts","../src/functions/commands/console.ts","../src/functions/commands/db-audit.ts","../src/functions/commands/db-generate.ts","../src/functions/commands/db-migrate.ts","../src/functions/commands/db-reset.ts","../src/functions/commands/db-seed.ts","../src/functions/commands/db-shared.ts","../src/functions/commands/deploy-apply.ts","../src/functions/commands/deploy-info.ts","../src/functions/commands/deploy-plan.ts","../src/functions/commands/dev.ts","../src/functions/commands/emails-init.ts","../src/functions/commands/enable.ts","../src/functions/commands/info.ts","../src/functions/commands/load-user-project.ts","../src/functions/commands/login.ts","../src/functions/commands/meta.ts","../src/functions/commands/new-addon.ts","../src/functions/commands/new-function.ts","../src/functions/commands/new-middleware.ts","../src/functions/commands/new-permission.ts","../src/functions/commands/new-wiring.ts","../src/functions/commands/pikku-command-bootstrap.ts","../src/functions/commands/pikku-command-summary.ts","../src/functions/commands/skills.ts","../src/functions/commands/tests-coverage.ts","../src/functions/commands/tests-init.ts","../src/functions/commands/versions-check.ts","../src/functions/commands/versions-init.ts","../src/functions/commands/versions-update.ts","../src/functions/commands/watch.ts","../src/functions/commands/workspace-validate.ts","../src/functions/db/annotation-parser.ts","../src/functions/db/better-auth-schema.ts","../src/functions/db/coercion-plugin.ts","../src/functions/db/db-codegen.ts","../src/functions/db/db-introspector.ts","../src/functions/db/db-migrator.ts","../src/functions/db/local-db.ts","../src/functions/db/zod-codegen.ts","../src/functions/db/postgres/pglite-kysely.ts","../src/functions/db/postgres/postgres-introspector.ts","../src/functions/db/postgres/postgres-migrator.ts","../src/functions/db/sqlite/seed.ts","../src/functions/db/sqlite/sqlite-introspector.ts","../src/functions/db/sqlite/sqlite-kysely.ts","../src/functions/db/sqlite/sqlite-migrator.ts","../src/functions/db/sqlite/sqlite-runtime-bun.ts","../src/functions/db/sqlite/sqlite-runtime-node.ts","../src/functions/db/sqlite/sqlite-runtime.ts","../src/functions/runtimes/fetch/index.ts","../src/functions/runtimes/nextjs/pikku-command-nextjs.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-worker-rpc-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-http-wrapper.ts","../src/functions/runtimes/tanstack-start/pikku-command-tanstack-start.ts","../src/functions/runtimes/tanstack-start/serialize-tanstack-start-shim.ts","../src/functions/runtimes/websocket/pikku-command-websocket-typed.ts","../src/functions/runtimes/websocket/serialize-websocket-wrapper.ts","../src/functions/validate/workspace-validate.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent-types.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent.ts","../src/functions/wirings/ai-agent/pikku-command-public-agent.ts","../src/functions/wirings/ai-agent/serialize-agent-map.ts","../src/functions/wirings/ai-agent/serialize-ai-agent-types.ts","../src/functions/wirings/ai-agent/serialize-public-agent.ts","../src/functions/wirings/auth/pikku-command-auth.ts","../src/functions/wirings/auth/serialize-auth-gen.ts","../src/functions/wirings/auth/serialize-auth-meta.ts","../src/functions/wirings/auth/serialize-auth-types.ts","../src/functions/wirings/channels/pikku-channels.ts","../src/functions/wirings/channels/pikku-command-channel-types.ts","../src/functions/wirings/channels/pikku-command-channels-map.ts","../src/functions/wirings/channels/pikku-command-channels.ts","../src/functions/wirings/channels/serialize-channel-types.ts","../src/functions/wirings/channels/serialize-typed-channel-map.ts","../src/functions/wirings/cli/pikku-command-cli-entry.ts","../src/functions/wirings/cli/pikku-command-cli-types.ts","../src/functions/wirings/cli/pikku-command-cli.ts","../src/functions/wirings/cli/serialize-channel-cli-client.ts","../src/functions/wirings/cli/serialize-channel-cli.ts","../src/functions/wirings/cli/serialize-cli-types.ts","../src/functions/wirings/cli/serialize-local-cli-bootstrap.ts","../src/functions/wirings/console/pikku-command-console-functions.ts","../src/functions/wirings/console/pikku-command-node-types.ts","../src/functions/wirings/console/pikku-command-nodes-meta.ts","../src/functions/wirings/console/serialize-console-functions.ts","../src/functions/wirings/console/serialize-node-types.ts","../src/functions/wirings/credentials/pikku-command-credentials.ts","../src/functions/wirings/credentials/serialize-credentials-types.ts","../src/functions/wirings/emails/pikku-command-emails.ts","../src/functions/wirings/emails/serialize-emails.ts","../src/functions/wirings/functions/pikku-command-addon-types.ts","../src/functions/wirings/functions/pikku-command-function-types-split.ts","../src/functions/wirings/functions/pikku-command-function-types.ts","../src/functions/wirings/functions/pikku-command-functions.ts","../src/functions/wirings/functions/pikku-command-services.ts","../src/functions/wirings/functions/schemas.ts","../src/functions/wirings/functions/serialize-addon-types.ts","../src/functions/wirings/functions/serialize-function-imports.ts","../src/functions/wirings/functions/serialize-function-types.ts","../src/functions/wirings/functions/serialize-pikku-types-hub.ts","../src/functions/wirings/gateway/pikku-command-gateway.ts","../src/functions/wirings/http/pikku-command-http-map.ts","../src/functions/wirings/http/pikku-command-http-routes.ts","../src/functions/wirings/http/pikku-command-http-types.ts","../src/functions/wirings/http/pikku-command-openapi.ts","../src/functions/wirings/http/pikku-http-routes.ts","../src/functions/wirings/http/serialize-fetch-wrapper.ts","../src/functions/wirings/http/serialize-http-types.ts","../src/functions/wirings/http/serialize-typed-http-map.ts","../src/functions/wirings/mcp/pikku-command-mcp-json.ts","../src/functions/wirings/mcp/pikku-command-mcp-types.ts","../src/functions/wirings/mcp/pikku-command-mcp.ts","../src/functions/wirings/mcp/serialize-mcp-types.ts","../src/functions/wirings/middleware/pikku-command-middleware.ts","../src/functions/wirings/middleware/serialize-middleware-imports.ts","../src/functions/wirings/package/pikku-command-package-types.ts","../src/functions/wirings/package/pikku-command-package.ts","../src/functions/wirings/package/serialize-package-types.ts","../src/functions/wirings/package/serialize-package.ts","../src/functions/wirings/permissions/pikku-command-permissions.ts","../src/functions/wirings/permissions/serialize-permissions-imports.ts","../src/functions/wirings/queue/pikku-command-queue-map.ts","../src/functions/wirings/queue/pikku-command-queue-service.ts","../src/functions/wirings/queue/pikku-command-queue-types.ts","../src/functions/wirings/queue/pikku-command-queue.ts","../src/functions/wirings/queue/pikku-queue-map.ts","../src/functions/wirings/queue/pikku-queue.ts","../src/functions/wirings/queue/serialize-queue-map.ts","../src/functions/wirings/queue/serialize-queue-meta.ts","../src/functions/wirings/queue/serialize-queue-types.ts","../src/functions/wirings/queue/serialize-queue-wrapper.ts","../src/functions/wirings/realtime/pikku-command-events-scaffold.ts","../src/functions/wirings/realtime/pikku-command-realtime.ts","../src/functions/wirings/realtime/serialize-events-scaffold.ts","../src/functions/wirings/realtime/serialize-realtime-client.ts","../src/functions/wirings/rpc/pikku-command-public-rpc.ts","../src/functions/wirings/rpc/pikku-command-react-query.ts","../src/functions/wirings/rpc/pikku-command-remote-rpc.ts","../src/functions/wirings/rpc/pikku-command-rpc-client.ts","../src/functions/wirings/rpc/pikku-command-rpc-map.ts","../src/functions/wirings/rpc/pikku-command-rpc.ts","../src/functions/wirings/rpc/serialize-public-rpc.ts","../src/functions/wirings/rpc/serialize-react-query-hooks.ts","../src/functions/wirings/rpc/serialize-remote-rpc.ts","../src/functions/wirings/rpc/serialize-rpc-wrapper.ts","../src/functions/wirings/rpc/serialize-typed-rpc-map.ts","../src/functions/wirings/scheduler/pikku-command-scheduler-types.ts","../src/functions/wirings/scheduler/pikku-command-scheduler.ts","../src/functions/wirings/scheduler/serialize-scheduler-meta.ts","../src/functions/wirings/scheduler/serialize-scheduler-types.ts","../src/functions/wirings/secrets/pikku-command-secrets.ts","../src/functions/wirings/secrets/serialize-secrets-types.ts","../src/functions/wirings/triggers/pikku-command-trigger-types.ts","../src/functions/wirings/triggers/pikku-command-trigger.ts","../src/functions/wirings/triggers/serialize-trigger-meta.ts","../src/functions/wirings/triggers/serialize-trigger-types.ts","../src/functions/wirings/variables/pikku-command-variables.ts","../src/functions/wirings/variables/serialize-variables-types.ts","../src/functions/wirings/workflow/pikku-command-workflow-routes.ts","../src/functions/wirings/workflow/pikku-command-workflow.ts","../src/functions/wirings/workflow/serialize-workflow-bootstrap-map.ts","../src/functions/wirings/workflow/serialize-workflow-map.ts","../src/functions/wirings/workflow/serialize-workflow-meta.ts","../src/functions/wirings/workflow/serialize-workflow-registration.ts","../src/functions/wirings/workflow/serialize-workflow-routes.ts","../src/functions/wirings/workflow/serialize-workflow-types.ts","../src/functions/workflows/all.workflow.ts","../src/middleware/log-command-info-and-time.ts","../src/scaffold/rpc-remote.gen.ts","../src/services/cli-logger-forwarder.service.ts","../src/services/cli-logger.service.ts","../src/utils/check-required-types.ts","../src/utils/cli-session.ts","../src/utils/command-summary.ts","../src/utils/contract-versions.ts","../src/utils/device-auth.ts","../src/utils/file-import-path.ts","../src/utils/file-imports-serializer.ts","../src/utils/file-writer.ts","../src/utils/generate-bootstrap-file.ts","../src/utils/get-cli-version.ts","../src/utils/parse-cli-filters.ts","../src/utils/pikku-cli-config.ts","../src/utils/pikku-files-and-methods.ts","../src/utils/serialize-import-map.ts","../src/utils/serialize-meta-ts.ts","../src/utils/serialize-schemas.ts","../src/utils/strip-verbose-meta.ts","../.pikku/pikku-bootstrap.gen.ts","../.pikku/pikku-meta-service.gen.ts","../.pikku/pikku-services.gen.ts","../.pikku/pikku-types.gen.ts","../.pikku/agent/pikku-agent-map.gen.d.ts","../.pikku/agent/pikku-agent-types.gen.ts","../.pikku/channel/pikku-channel-types.gen.ts","../.pikku/cli/pikku-cli-channel.ts","../.pikku/cli/pikku-cli-client.gen.ts","../.pikku/cli/pikku-cli-types.gen.ts","../.pikku/cli/pikku-cli-wirings-meta.gen.ts","../.pikku/cli/pikku-cli-wirings.gen.ts","../.pikku/cli/pikku-cli.gen.ts","../.pikku/console/pikku-node-types.gen.ts","../.pikku/function/pikku-function-types.gen.ts","../.pikku/function/pikku-functions-meta.gen.ts","../.pikku/function/pikku-functions.gen.ts","../.pikku/http/pikku-http-types.gen.ts","../.pikku/http/pikku-http-wirings-map.gen.d.ts","../.pikku/http/pikku-http-wirings-meta.gen.ts","../.pikku/http/pikku-http-wirings.gen.ts","../.pikku/mcp/pikku-mcp-types.gen.ts","../.pikku/node/pikku-node-types.gen.ts","../.pikku/queue/pikku-queue-types.gen.ts","../.pikku/queue/pikku-queue-workers-wirings-map.gen.d.ts","../.pikku/queue/pikku-queue-workers-wirings-meta.gen.ts","../.pikku/queue/pikku-queue-workers-wirings.gen.ts","../.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-map.internal.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-meta.internal.gen.ts","../.pikku/scheduler/pikku-scheduler-types.gen.ts","../.pikku/schemas/register.gen.ts","../.pikku/secrets/pikku-secret-types.gen.ts","../.pikku/secrets/pikku-secrets.gen.ts","../.pikku/trigger/pikku-trigger-types.gen.ts","../.pikku/variables/pikku-variable-types.gen.ts","../.pikku/variables/pikku-variables.gen.ts","../.pikku/workflow/pikku-workflow-map.gen.d.ts","../.pikku/workflow/pikku-workflow-types.gen.ts","../.pikku/workflow/pikku-workflow-wirings-meta.gen.ts","../.pikku/workflow/pikku-workflow-wirings.gen.ts","../types/application-types.d.ts","../types/bun-sqlite.d.ts","../types/config.d.ts"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/cli",
-  "version": "0.12.43",
+  "version": "0.12.44",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "imports": {
@@ -28,10 +28,10 @@
     "@electric-sql/pglite": "^0.5.1",
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
     "@pikku/better-auth": "^0.12.9",
-    "@pikku/core": "^0.12.34",
+    "@pikku/core": "^0.12.35",
     "@pikku/deploy-cloudflare": "^0.12.3",
     "@pikku/fetch": "^0.12.3",
-    "@pikku/inspector": "^0.12.21",
+    "@pikku/inspector": "^0.12.22",
     "@pikku/kysely": "^0.12.16",
     "@pikku/kysely-node-sqlite": "^0.12.2",
     "@pikku/node-http-server": "^0.12.2",

package/skills/pikku-emails/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: pikku-emails
+description: "Use when working with Pikku's file-based email templates: authoring HTML/subject/text templates, locales, partials and theme, running `pikku emails generate`, and rendering/sending them through an EmailService.
+TRIGGER when: code uses renderEmailTemplate, EmailTemplateName, EmailService, SendTemplateEmailInput, LocalEmailService, or imports from .pikku/email/pikku-emails.gen.
+TRIGGER when: the project has an emails/ directory (templates/, locales/, partials/, theme.json) or emailTemplatesDir in pikku.config.json.
+TRIGGER when: user asks to add/edit a transactional email (verification, password reset, invitation, receipt), wire email sending, or translate an email.
+DO NOT TRIGGER when: user asks about i18n for the app UI (use pikku-i18n) or auth flows in general (use pikku-better-auth)."
+---
+
+# Pikku Emails
+
+Pikku compiles a directory of plain template files into a typed, dependency-free
+renderer. `pikku emails generate` reads `emailTemplatesDir` and writes
+`.pikku/email/pikku-emails.gen.ts` (the `renderEmailTemplate` function + per-template
+types) and `pikku-emails-meta.gen.json`. Templates are authored as files; the
+generated output is never edited by hand.
+
+## Agent Operating Procedure
+
+1. Edit source files under `emailTemplatesDir` only. Never edit `.pikku/email/*`.
+2. After any change run `pikku emails generate` (it is also part of `prebuild`, usually
+   `pikku bootstrap; pikku all; pikku emails generate`).
+3. Validate by importing `renderEmailTemplate` and rendering with sample data, or run the
+   project's typecheck — the generated `data` type will flag missing/wrong variables.
+4. Fix the source cause; do not patch generated files or update hashes by hand.
+
+## Config
+
+```jsonc
+// pikku.config.json
+{
+  "emailTemplatesDir": "emails",   // relative to rootDir; omit to disable emails
+  "outDir": ".pikku"               // gen lands in <outDir>/email/
+}
+```
+
+If `emailTemplatesDir` is unset the command is a no-op.
+
+## Directory layout
+
+```text
+emails/
+  theme.json                 # brand tokens: appName, fonts, colors
+  locales/
+    en.json                  # translation strings, nested namespaces
+    de.json                  # one file per locale (filename = locale key)
+  partials/
+    layout.html              # outer wrapper; must include {{content}}
+    footer.html              # reusable fragment, included with {{> footer}}
+  templates/
+    verify-email.html        # body (required)
+    verify-email.subject.txt # subject line (required)
+    verify-email.text.txt    # plain-text alternative (optional)
+```
+
+A template's **name** is its filename without the `.html` / `.subject.txt` / `.text.txt`
+suffix (`verify-email` above). `html` and `subject` are required; `text` is optional and,
+when present, becomes the plain-text MIME part.
+
+## Templating syntax
+
+Placeholders are `{{ ... }}`. Resolution order inside a template:
+
+- `{{appName}}` — from `data.appName`, falling back to `theme.appName`.
+- `{{theme.colors.accent}}`, `{{theme.fonts.body}}` — values from `theme.json`.
+- `{{t.verifyEmail.heading}}` — string from the active locale file (`locales/<locale>.json`).
+- `{{verifyUrl}}` — any other key is a **runtime variable**, supplied via `data`.
+- `{{> footer}}` — include a partial from `partials/`.
+- `{{content}}` / `{{subject}}` — only meaningful inside `partials/layout.html`
+  (the rendered body and subject). `layout.html` wraps every template if present.
+
+Locale strings may themselves contain variables and partial-free placeholders, e.g.
+`"subject": "{{inviterName}} invited you to join {{organizationName}}"`. These are
+resolved in the same pass, so a subject of `{{t.invitation.subject}}` expands fully.
+
+## Typed variables (per template)
+
+The generator extracts the runtime variables each template references and emits a typed
+`data` shape. Extraction is **scoped to the template**: it walks the template's
+html/subject/text, the partials it includes, and only the locale keys it actually
+references (transitively) — variables from unrelated locale entries do not leak in.
+
+```ts
+import {
+  renderEmailTemplate,
+  type EmailTemplateName,
+  type EmailTemplateVariables,
+} from './.pikku/email/pikku-emails.gen.js'
+
+// EmailTemplateVariables<'organization-invitation'> =
+//   { appName?: ...; inviteUrl?: ...; inviterName?: ...; organizationName?: ... }
+```
+
+To make a variable required-and-typed, reference it directly in the template body (not
+only in a locale string), so it shows up as that template's variable.
+
+## Rendering
+
+```ts
+const rendered = renderEmailTemplate({
+  name: 'verify-email',        // EmailTemplateName (autocompleted)
+  locale: 'en',                // optional, defaults to 'en'
+  data: { verifyUrl: url },    // EmailTemplateVariables<'verify-email'>
+})
+// rendered: { name, locale, subject, html, text?, variables, hash }
+```
+
+`hash` is a stable content hash (useful as an idempotency / dedupe key on outgoing mail).
+
+## Sending through an EmailService
+
+`@pikku/core/services` defines `EmailService.send(input)` where `input` is one of
+`SendTextEmailInput`, `SendHTMLEmailInput`, or `SendTemplateEmailInput`:
+
+```ts
+import type { EmailService } from '@pikku/core/services'
+
+await email.send({
+  to: user.email,
+  template: { name: 'verify-email', locale: user.locale, data: { verifyUrl } },
+})
+```
+
+`LocalEmailService` (dev/test) captures the payload as-is. To actually render templates
+before sending, wrap a delegate service: when `input.template` is present, call
+`renderEmailTemplate` and forward `subject` / `html` / `text` to the delegate (e.g. a
+Resend/SES/SMTP service). This wrapper is project-owned because `renderEmailTemplate`
+is generated per project; wire it in `services.ts` and inject it into functions.
+
+```ts
+async send(input: SendEmailInput) {
+  if (!('template' in input) || !input.template) return this.delegate.send(input)
+  const r = renderEmailTemplate(input.template as RenderEmailInput<EmailTemplateName>)
+  return this.delegate.send({
+    to: input.to, from: input.from, subject: r.subject, html: r.html,
+    ...(r.text ? { text: r.text } : {}),
+  })
+}
+```
+
+## Generated artifacts
+
+- `.pikku/email/pikku-emails.gen.ts` — `renderEmailTemplate`, `EmailTemplateName`,
+  `EmailLocale`, `EmailTemplateVariables<T>`, inlined templates/locales/partials/theme.
+- `.pikku/email/pikku-emails-meta.gen.json` — per-template `variables`, `hasHtml/Subject/Text`,
+  and per-locale content hashes. Both are regenerated; keep them out of hand edits and
+  (typically) git-ignored.
+
+## Gotchas
+
+- New template not appearing → you added `.html` but forgot `.subject.txt` (subject is
+  required), or didn't rerun `pikku emails generate`.
+- Variable typed `unknown`/missing → it's only in a locale string for a different template;
+  reference it in this template to scope it in.
+- Editing a locale string changes that template's content hash — expected; the hash covers
+  the strings the template uses.
+- `layout.html` must contain `{{content}}` or the body is dropped.