@pikku/cli 0.12.24 → 0.12.26

package/dist/src/functions/commands/dev.js

@@ -3,7 +3,7 @@ import { join, resolve } from 'path';
 import { pikkuSessionlessFunc } from '#pikku';
 import chokidar from 'chokidar';
 import { pikkuDevReloader } from '@pikku/core/dev';
-import { ConsoleLogger, InMemoryQueueService, InMemoryWorkflowService, InMemoryTriggerService, InMemoryAIRunStateService, } from '@pikku/core/services';
+import { ConsoleLogger, LocalEmailService, InMemoryQueueService, InMemoryWorkflowService, InMemoryTriggerService, InMemoryAIRunStateService, } from '@pikku/core/services';
 import { KyselyAIStorageService, KyselyAIRunStateService, KyselyAgentRunService, } from '@pikku/kysely';
 import { stopSingletonServices } from '@pikku/core';
 import { pikkuState } from '@pikku/core/internal';
@@ -14,7 +14,7 @@ import { pikkuWebsocketHandler } from '@pikku/ws';
 import { PikkuNodeHTTPServer } from '@pikku/node-http-server';
 import { WebSocketServer } from 'ws';
 import { InMemorySchedulerService } from '@pikku/schedule';
-import { resolveLocalDb, createKysely } from '../db/local-db.js';
+import { resolveDb, createKysely } from '../db/local-db.js';
 import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
 export const dev = pikkuSessionlessFunc({
     remote: true,
@@ -23,6 +23,9 @@ export const dev = pikkuSessionlessFunc({
         const hostname = 'localhost';
         const enableWatch = watch !== false;
         const enableHmr = hmr !== false;
+        const watchDirectories = [
+            ...new Set([config.emailTemplatesDir, ...config.srcDirectories].filter(Boolean)),
+        ];
         const commandSingletonServices = pikkuState(null, 'package', 'singletonServices');
         const commandFunctionMeta = {
             ...pikkuState(null, 'function', 'meta'),
@@ -113,19 +116,25 @@ export const dev = pikkuSessionlessFunc({
         const userCreateConfig = configModule[pikkuConfigFactory.variable];
         const userCreateSingletonServices = servicesModule[singletonServicesFactory.variable];
         const userConfig = await userCreateConfig();
-        const resolvedLocalDb = resolveLocalDb(userConfig.dev?.db ?? true, config.rootDir, config.outDir, config.runtimeDir);
+        const resolvedDb = resolveDb(userConfig, config.rootDir, config.outDir, config.runtimeDir);
+        const resolvedLocalDb = resolvedDb?.dialect === 'sqlite'
+            ? resolvedDb
+            : userConfig.sqliteDb
+                ? resolveDb({ sqliteDb: userConfig.sqliteDb }, config.rootDir, config.outDir, config.runtimeDir)
+                : undefined;
         const kysely = resolvedLocalDb
             ? await createKysely(resolvedLocalDb)
             : undefined;
         const resolvedRuntimeDir = config.runtimeDir ?? join(config.rootDir, '.pikku-runtime');
-        const localContentConfig = userConfig.dev
-            ?.content
+        const localContentConfig = userConfig.content
             ? {
-                localFileUploadPath: join(resolvedRuntimeDir, 'content'),
-                uploadUrlPrefix: '/upload',
-                assetUrlPrefix: '/assets',
+                localFileUploadPath: userConfig.content.contentPath
+                    ? resolve(config.rootDir, userConfig.content.contentPath)
+                    : join(resolvedRuntimeDir, 'content'),
+                uploadUrlPrefix: userConfig.content.uploadUrlPrefix ?? '/upload',
+                assetUrlPrefix: userConfig.content.assetUrlPrefix ?? '/assets',
                 server: `http://${hostname}:${resolvedPort}`,
-                ...(userConfig.dev.content !== true ? userConfig.dev.content : {}),
+                sizeLimit: userConfig.content.sizeLimit,
             }
             : undefined;
         const localContent = localContentConfig
@@ -151,8 +160,10 @@ export const dev = pikkuSessionlessFunc({
         // single instance under both names so addons like @pikku/addon-console
         // can read runs in dev without projects having to wire their own backing
         // store.
+        const devLogger = new ConsoleLogger();
         const inMemoryServices = {
-            logger: new ConsoleLogger(),
+            logger: devLogger,
+            emailService: new LocalEmailService(),
             metaService: new LocalMetaService(pikkuDir),
             schedulerService,
             queueService: new InMemoryQueueService(),
@@ -205,20 +216,20 @@ export const dev = pikkuSessionlessFunc({
         });
         if (enableHmr) {
             await pikkuDevReloader({
-                srcDirectories: config.srcDirectories,
+                srcDirectories: watchDirectories,
                 logger,
             });
         }
         if (enableWatch) {
             const genIgnore = /\.gen\.tsx?$/;
-            configWatcher = chokidar.watch(config.srcDirectories, {
+            configWatcher = chokidar.watch(watchDirectories, {
                 ignoreInitial: true,
                 ignored: genIgnore,
             });
             const generatorWatcher = () => {
                 watcher?.close();
-                logger.info(`• Watching directories: \n  - ${config.srcDirectories.join('\n  - ')}`);
-                watcher = chokidar.watch(config.srcDirectories, {
+                logger.info(`• Watching directories: \n  - ${watchDirectories.join('\n  - ')}`);
+                watcher = chokidar.watch(watchDirectories, {
                     ignoreInitial: true,
                     ignored: genIgnore,
                 });

package/dist/src/functions/commands/emails-init.d.ts

@@ -0,0 +1,5 @@
+type EmailsInitInput = {
+    force?: boolean;
+};
+export declare const pikkuEmailsInit: import("#pikku").PikkuFunctionConfig<EmailsInitInput, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<EmailsInitInput, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<EmailsInitInput, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;
+export {};

package/dist/src/functions/commands/emails-init.js

@@ -0,0 +1,162 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { pikkuSessionlessFunc } from '#pikku';
+import { generateEmailsArtifacts } from '../wirings/emails/pikku-command-emails.js';
+const DEFAULT_EMAIL_DIR = 'emails';
+const DEFAULT_THEME = {
+    appName: 'Pikku App',
+    previewText: 'Your app can render localized emails out of the box.',
+    colors: {
+        background: '#f5f7fb',
+        surface: '#ffffff',
+        text: '#101828',
+        muted: '#475467',
+        border: '#d0d5dd',
+        primary: '#7c3aed',
+        primaryText: '#ffffff',
+        footer: '#667085',
+    },
+    fonts: {
+        body: "Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+    },
+};
+const DEFAULT_EN_LOCALE = {
+    helloWorld: {
+        subject: 'Hello from {{appName}}',
+        eyebrow: 'Email templates are live',
+        title: 'Your first Pikku email is ready',
+        intro: 'This starter template proves the pipeline works and gives you a place to shape your own visual language.',
+        body: 'Chat to your AI to create new emails, refine the theme, or localize every message for your product.',
+        cta: 'Open the email console',
+        footer: 'Built with Pikku email templates.',
+    },
+};
+const DEFAULT_DE_LOCALE = {
+    helloWorld: {
+        subject: 'Hallo von {{appName}}',
+        eyebrow: 'E-Mail-Vorlagen sind aktiv',
+        title: 'Deine erste Pikku-E-Mail ist bereit',
+        intro: 'Diese Startvorlage zeigt, dass die Pipeline funktioniert, und gibt dir einen Ausgangspunkt fuer dein eigenes Design.',
+        body: 'Sprich mit deiner KI, um neue E-Mails zu erstellen, das Theme zu verfeinern oder jede Nachricht zu lokalisieren.',
+        cta: 'E-Mail-Konsole oeffnen',
+        footer: 'Erstellt mit Pikku-E-Mail-Vorlagen.',
+    },
+};
+function layoutTemplate() {
+    return `<!doctype html>
+<html lang="{{locale}}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{subject}}</title>
+  </head>
+  <body style="margin:0;padding:32px 16px;background:{{theme.colors.background}};font-family:{{theme.fonts.body}};color:{{theme.colors.text}};">
+    <div style="max-width:640px;margin:0 auto;background:{{theme.colors.surface}};border:1px solid {{theme.colors.border}};border-radius:20px;overflow:hidden;">
+      {{content}}
+    </div>
+  </body>
+</html>
+`;
+}
+function footerPartial() {
+    return `<div style="padding:24px 32px;border-top:1px solid {{theme.colors.border}};font-size:13px;line-height:1.6;color:{{theme.colors.footer}};">
+  <p style="margin:0;">{{t.helloWorld.footer}}</p>
+</div>
+`;
+}
+function helloWorldHtml() {
+    return `<div style="padding:32px;">
+  <p style="margin:0 0 16px;font-size:12px;letter-spacing:0.12em;text-transform:uppercase;color:{{theme.colors.primary}};">
+    {{t.helloWorld.eyebrow}}
+  </p>
+  <h1 style="margin:0 0 16px;font-size:32px;line-height:1.15;color:{{theme.colors.text}};">
+    {{t.helloWorld.title}}
+  </h1>
+  <p style="margin:0 0 16px;font-size:16px;line-height:1.7;color:{{theme.colors.muted}};">
+    Hello {{userName}}. {{t.helloWorld.intro}}
+  </p>
+  <p style="margin:0 0 24px;font-size:16px;line-height:1.7;color:{{theme.colors.muted}};">
+    {{t.helloWorld.body}}
+  </p>
+  <a
+    href="{{previewUrl}}"
+    style="display:inline-block;padding:14px 18px;border-radius:999px;background:{{theme.colors.primary}};color:{{theme.colors.primaryText}};font-weight:600;text-decoration:none;"
+  >
+    {{t.helloWorld.cta}}
+  </a>
+</div>
+{{> footer}}
+`;
+}
+function helloWorldSubject() {
+    return `{{t.helloWorld.subject}}
+`;
+}
+function helloWorldText() {
+    return `{{t.helloWorld.title}}
+
+Hello {{userName}}.
+
+{{t.helloWorld.intro}}
+
+{{t.helloWorld.body}}
+
+{{t.helloWorld.cta}}: {{previewUrl}}
+`;
+}
+async function ensureFile(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, 'utf8');
+}
+async function updateJsonConfig(configDir, emailDir) {
+    const configPath = join(configDir, 'pikku.config.json');
+    if (!existsSync(configPath)) {
+        return false;
+    }
+    const raw = await readFile(configPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.emailTemplatesDir === 'string' && parsed.emailTemplatesDir) {
+        return false;
+    }
+    parsed.emailTemplatesDir = emailDir;
+    await writeFile(configPath, `${JSON.stringify(parsed, null, 2)}\n`, 'utf8');
+    return true;
+}
+export const pikkuEmailsInit = pikkuSessionlessFunc({
+    func: async ({ logger, config }, input) => {
+        const force = input?.force;
+        const configuredEmailDir = config.emailTemplatesDir ?? join(config.rootDir, DEFAULT_EMAIL_DIR);
+        const emailDir = config.emailTemplatesDir && config.emailTemplatesDir.length > 0
+            ? config.emailTemplatesDir
+            : join(config.rootDir, DEFAULT_EMAIL_DIR);
+        const files = [
+            [join(emailDir, 'theme.json'), `${JSON.stringify(DEFAULT_THEME, null, 2)}\n`],
+            [join(emailDir, 'locales', 'en.json'), `${JSON.stringify(DEFAULT_EN_LOCALE, null, 2)}\n`],
+            [join(emailDir, 'locales', 'de.json'), `${JSON.stringify(DEFAULT_DE_LOCALE, null, 2)}\n`],
+            [join(emailDir, 'partials', 'layout.html'), layoutTemplate()],
+            [join(emailDir, 'partials', 'footer.html'), footerPartial()],
+            [join(emailDir, 'templates', 'hello-world.html'), helloWorldHtml()],
+            [join(emailDir, 'templates', 'hello-world.subject.txt'), helloWorldSubject()],
+            [join(emailDir, 'templates', 'hello-world.text.txt'), helloWorldText()],
+        ];
+        const existing = !force
+            ? files.map(([path]) => path).filter((path) => existsSync(path))
+            : [];
+        if (existing.length > 0) {
+            logger.error(`Email scaffold already exists at ${existing[0]}. Use --force to overwrite.`);
+            process.exit(1);
+        }
+        await Promise.all(files.map(([path, content]) => ensureFile(path, content)));
+        const configUpdated = !config.emailTemplatesDir &&
+            (await updateJsonConfig(config.configDir, DEFAULT_EMAIL_DIR));
+        if (!config.emailTemplatesDir && !configUpdated) {
+            logger.warn('Unable to auto-update pikku.config.json. Add "emailTemplatesDir": "emails" manually.');
+        }
+        await generateEmailsArtifacts(logger, {
+            emailTemplatesDir: emailDir,
+            outDir: config.outDir,
+        });
+        logger.info(`Email templates initialized at ${configuredEmailDir}`);
+    },
+});

package/dist/src/functions/commands/load-user-project.js

@@ -1,7 +1,11 @@
 import { existsSync } from 'fs';
 import { join } from 'path';
+import { pathToFileURL } from 'url';
 import { register } from 'tsx/esm/api';
 let tsxRegistered = false;
+function isBunRuntime() {
+    return typeof globalThis.Bun !== 'undefined';
+}
 /**
  * Globally register tsx so subsequent `import()` calls go through Node's
  * normal resolver — yielding ONE module graph (and one shared pikkuState),
@@ -13,22 +17,27 @@ let tsxRegistered = false;
  * module state (e.g. `pikkuState` registrations from wireHTTPRoutes).
  */
 function ensureTsxRegistered() {
+    if (isBunRuntime())
+        return;
     if (tsxRegistered)
         return;
     register();
     tsxRegistered = true;
 }
+async function importUserPath(filePath) {
+    return import(pathToFileURL(filePath).href);
+}
 /**
  * Load the generated `pikku-bootstrap.gen.{ts,js}` from the user's project,
  * which in turn pulls in all wiring/meta files so they register into
  * `pikkuState`.
  */
 export async function loadUserBootstrap(pikkuDir) {
-    ensureTsxRegistered();
     const bootstrapTs = join(pikkuDir, 'pikku-bootstrap.gen.ts');
     const bootstrapJs = join(pikkuDir, 'pikku-bootstrap.gen.js');
     const bootstrapPath = existsSync(bootstrapTs) ? bootstrapTs : bootstrapJs;
-    await import(bootstrapPath);
+    ensureTsxRegistered();
+    await importUserPath(bootstrapPath);
 }
 /**
  * Import a user-source TypeScript file (e.g. their config or services
@@ -36,5 +45,5 @@ export async function loadUserBootstrap(pikkuDir) {
  */
 export async function loadUserModule(filePath) {
     ensureTsxRegistered();
-    return import(filePath);
+    return importUserPath(filePath);
 }

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

@@ -219,7 +219,7 @@ export const createSingletonServices = pikkuAddonServices(async (
   config,
   { secrets, variables }
 ) => {
-  const creds = await secrets.getSecretJSON<${pascalName}Secrets>('${screamingName}_CREDENTIALS')
+  const creds = await secrets.getSecret<${pascalName}Secrets>('${screamingName}_CREDENTIALS')
   const ${camelName} = new ${pascalName}Service(creds, variables)
 
   return { ${camelName} }
@@ -717,7 +717,7 @@ import { createSingletonServices } from './services.js'
 test('${name} addon', async () => {
   const secrets = new LocalSecretService()
   // Set up secrets for the service
-  // await secrets.setSecretJSON('${screamingName}_CREDENTIALS', { ... })
+  // await secrets.setSecret('${screamingName}_CREDENTIALS', { ... })
 
   const singletonServices = await createSingletonServices({}, { secrets })
   const rpc = rpcService.getContextRPCService(singletonServices as any, {})

package/dist/src/functions/commands/tests-coverage.d.ts

@@ -1,7 +1,10 @@
 export declare const pikkuTestsCoverage: import("#pikku").PikkuFunctionConfig<{
     noRun?: boolean;
+    aiOut?: string;
 }, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
     noRun?: boolean;
+    aiOut?: string;
 }, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<{
     noRun?: boolean;
+    aiOut?: string;
 }, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/commands/tests-coverage.js

@@ -92,6 +92,7 @@ function lineCoverage(fileCov, span) {
 export const pikkuTestsCoverage = pikkuSessionlessFunc({
     func: async ({ logger, config }, input) => {
         const noRun = input?.noRun ?? false;
+        const aiOut = input?.aiOut ?? null;
         const packageMappings = config.packageMappings ?? {};
         const srcDirs = config.srcDirectories ?? [];
         const functionsRelDir = Object.keys(packageMappings).find((key) => srcDirs.some((src) => src === key || src.startsWith(key + '/'))) ?? Object.keys(packageMappings)[0];
@@ -227,5 +228,38 @@ export const pikkuTestsCoverage = pikkuSessionlessFunc({
         console.log(`  ${summary.covered} covered · ${summary.partial} partial · ${summary.uncovered} uncovered · ${summary.unknown} unknown (overall ${(overallRatio * 100).toFixed(1)}%)`);
         if (uncovered.length)
             console.log(`  uncovered: ${uncovered.map((f) => f.name).join(', ')}`);
+        if (aiOut !== null) {
+            const generatedAt = new Date().toISOString();
+            const pct = Math.round(overallRatio * 100);
+            const needWork = functions.filter((f) => f.status !== 'covered');
+            const lines = [
+                `Coverage report — generated ${generatedAt}.`,
+                `Overall: ${pct}% (${summary.covered}/${summary.total} functions fully covered)`,
+                '',
+                needWork.length === 0
+                    ? 'All functions are fully covered — nothing to do!'
+                    : `Functions needing coverage (${needWork.length}):`,
+                ...needWork.flatMap((fn) => {
+                    const ratio = Math.round(fn.ratio * 100);
+                    const missed = fn.missedLines.length > 0 ? fn.missedLines.join(', ') : 'none';
+                    return [
+                        `- ${fn.name} [${fn.status}, ${ratio}% covered, ${fn.coveredLines}/${fn.totalLines} lines]`,
+                        `  file: ${fn.sourceFile}`,
+                        `  missed lines: ${missed}`,
+                    ];
+                }),
+            ];
+            if (needWork.length > 0) {
+                lines.push('', 'Write @pikku/cucumber Gherkin scenarios (no custom steps) in tests/tests/features/ to cover the missed lines above.', 'Use pikku meta to get versioned RPC names and function schemas before writing.', 'Run pikku tests coverage after writing to verify coverage improved.');
+            }
+            const prompt = lines.join('\n') + '\n';
+            if (aiOut === '-') {
+                process.stdout.write(prompt);
+            }
+            else {
+                writeFileSync(aiOut, prompt, 'utf-8');
+                console.log(`AI prompt → ${relative(config.rootDir, aiOut)}`);
+            }
+        }
     },
 });

package/dist/src/functions/commands/watch.js

@@ -4,21 +4,24 @@ import { pikkuDevReloader } from '@pikku/core/dev';
 export const watch = pikkuSessionlessFunc({
     remote: true,
     func: async ({ logger, config }, { hmr }, { rpc }) => {
+        const watchDirectories = [
+            ...new Set([config.emailTemplatesDir, ...config.srcDirectories].filter(Boolean)),
+        ];
         if (hmr) {
             await pikkuDevReloader({
-                srcDirectories: config.srcDirectories,
+                srcDirectories: watchDirectories,
                 logger,
             });
         }
-        const configWatcher = chokidar.watch(config.srcDirectories, {
+        const configWatcher = chokidar.watch(watchDirectories, {
             ignoreInitial: true,
             ignored: /.*\.gen\.tsx?/,
         });
         let watcher = new chokidar.FSWatcher({});
         const generatorWatcher = () => {
             watcher.close();
-            logger.info(`• Watching directories: \n  - ${config.srcDirectories.join('\n  - ')}`);
-            watcher = chokidar.watch(config.srcDirectories, {
+            logger.info(`• Watching directories: \n  - ${watchDirectories.join('\n  - ')}`);
+            watcher = chokidar.watch(watchDirectories, {
                 ignoreInitial: true,
                 ignored: /.*\.gen\.ts/,
             });

package/dist/src/functions/commands/workspace-validate.d.ts

@@ -0,0 +1,33 @@
+import { renderWorkspaceValidate } from '../validate/workspace-validate.js';
+export declare const workspaceValidate: import("#pikku").PikkuFunctionConfig<Record<string, never>, {
+    ok: boolean;
+    root: string;
+    findings: {
+        id: string;
+        severity: "info" | "warn" | "error";
+        message: string;
+        path: string;
+        fixHint: string;
+    }[];
+}, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<Record<string, never>, {
+    ok: boolean;
+    root: string;
+    findings: {
+        id: string;
+        severity: "info" | "warn" | "error";
+        message: string;
+        path: string;
+        fixHint: string;
+    }[];
+}, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<Record<string, never>, {
+    ok: boolean;
+    root: string;
+    findings: {
+        id: string;
+        severity: "info" | "warn" | "error";
+        message: string;
+        path: string;
+        fixHint: string;
+    }[];
+}, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;
+export { renderWorkspaceValidate };

package/dist/src/functions/commands/workspace-validate.js

@@ -0,0 +1,9 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { WorkspaceValidateInput, WorkspaceValidateOutput, renderWorkspaceValidate, runWorkspaceValidate, } from '../validate/workspace-validate.js';
+export const workspaceValidate = pikkuSessionlessFunc({
+    description: 'Check the current Pikku workspace structure for compatibility. Prints all missing or misconfigured items with fix hints.',
+    input: WorkspaceValidateInput,
+    output: WorkspaceValidateOutput,
+    func: async () => runWorkspaceValidate(),
+});
+export { renderWorkspaceValidate };

package/dist/src/functions/db/annotation-parser.d.ts

@@ -0,0 +1,31 @@
+import type { ColumnKind } from './coercion-plugin.js';
+type Classification = 'public' | 'private' | 'secret';
+type AnonymizeStrategy = 'fake:email' | 'fake:name' | 'hash' | 'keep' | null;
+export interface ColAnnotation {
+    kind?: ColumnKind;
+    /** TypeScript type string for @json columns, e.g. `string[]`. */
+    tsType?: string;
+    classification?: Classification;
+    anonymize?: AnonymizeStrategy;
+}
+/** Per-table, per-column annotation map built from migration SQL comments. */
+export type AnnotationMap = Record<string, Record<string, ColAnnotation>>;
+/**
+ * Determine column kind from naming conventions:
+ *   *_at / *_on            → date
+ *   is_* / has_* / can_*   → bool
+ */
+export declare function annotationFromName(colName: string): {
+    kind: ColumnKind;
+} | null;
+/**
+ * Parse `-- @bool | @date | @json [TsType] | @public | @private[:strategy] | @secret[:strategy]`
+ * inline annotations from migration SQL files in `migrationsDir`.
+ *
+ * Multiple annotations on the same comment line are supported, e.g.:
+ *   `deleted_at TIMESTAMP -- @date @private:keep`
+ *
+ * Covers both CREATE TABLE body lines and ALTER TABLE ... ADD [COLUMN] statements.
+ */
+export declare function parseAnnotations(migrationsDir: string): AnnotationMap;
+export {};

package/dist/src/functions/db/annotation-parser.js

@@ -0,0 +1,93 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Determine column kind from naming conventions:
+ *   *_at / *_on            → date
+ *   is_* / has_* / can_*   → bool
+ */
+export function annotationFromName(colName) {
+    if (/_at$|_on$/.test(colName))
+        return { kind: 'date' };
+    if (/^is_|^has_|^can_/.test(colName))
+        return { kind: 'bool' };
+    return null;
+}
+function parseStrategy(s) {
+    if (!s)
+        return null;
+    const valid = ['fake:email', 'fake:name', 'hash', 'keep'];
+    return valid.includes(s) ? s : null;
+}
+function parseComment(comment) {
+    const ann = {};
+    if (/@bool\b/i.test(comment)) {
+        ann.kind = 'bool';
+    }
+    else if (/@date\b/i.test(comment)) {
+        ann.kind = 'date';
+    }
+    else {
+        const jsonM = comment.match(/@json\b(?:\s+([^\s@]+))?/i);
+        if (jsonM) {
+            ann.kind = 'json';
+            if (jsonM[1])
+                ann.tsType = jsonM[1].trim();
+        }
+    }
+    const classM = comment.match(/@(public|private|secret)(?::([^\s@]+))?/i);
+    if (classM) {
+        ann.classification = classM[1].toLowerCase();
+        ann.anonymize = parseStrategy(classM[2]);
+    }
+    return ann;
+}
+/**
+ * Parse `-- @bool | @date | @json [TsType] | @public | @private[:strategy] | @secret[:strategy]`
+ * inline annotations from migration SQL files in `migrationsDir`.
+ *
+ * Multiple annotations on the same comment line are supported, e.g.:
+ *   `deleted_at TIMESTAMP -- @date @private:keep`
+ *
+ * Covers both CREATE TABLE body lines and ALTER TABLE ... ADD [COLUMN] statements.
+ */
+export function parseAnnotations(migrationsDir) {
+    let files;
+    try {
+        files = readdirSync(migrationsDir).filter((f) => f.endsWith('.sql')).sort();
+    }
+    catch {
+        return {};
+    }
+    const result = {};
+    function merge(tableName, colName, partial) {
+        if (!partial.kind && partial.classification === undefined)
+            return;
+        if (!result[tableName])
+            result[tableName] = {};
+        result[tableName][colName] = { ...result[tableName][colName], ...partial };
+    }
+    for (const file of files) {
+        const content = readFileSync(join(migrationsDir, file), 'utf8');
+        const createTablePattern = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?"?(\w+)"?\s*\(([^;]+)\)/gis;
+        let tableMatch;
+        while ((tableMatch = createTablePattern.exec(content)) !== null) {
+            const tableName = tableMatch[1].toLowerCase();
+            const body = tableMatch[2];
+            for (const line of body.split('\n')) {
+                const trimmed = line.trim();
+                if (/^(PRIMARY|UNIQUE|CHECK|FOREIGN|CONSTRAINT)/i.test(trimmed))
+                    continue;
+                const lineMatch = trimmed.match(/^(\w+)\s+\w[^-]*--\s*(.+?)\s*,?\s*$/);
+                if (!lineMatch)
+                    continue;
+                merge(tableName, lineMatch[1].toLowerCase(), parseComment(lineMatch[2]));
+            }
+        }
+        const alterPattern = /ALTER\s+TABLE\s+"?(\w+)"?\s+ADD\s+(?:COLUMN\s+)?"?(\w+)"?\s+\w[^;\n-]*(?:;\s*)?--\s*(.+?)(?:\r?\n|$)/gim;
+        let alterMatch;
+        while ((alterMatch = alterPattern.exec(content)) !== null) {
+            merge(alterMatch[1].toLowerCase(), alterMatch[2].toLowerCase(), parseComment(alterMatch[3]));
+        }
+    }
+    return result;
+}

package/dist/src/functions/db/coercion-plugin.d.ts

@@ -0,0 +1,7 @@
+import type { KyselyPlugin } from 'kysely';
+export type ColumnKind = 'date' | 'bool' | 'json';
+export type CoercionMap = Record<string, Record<string, ColumnKind>>;
+export interface CreateCoercionPluginOptions {
+    map: CoercionMap;
+}
+export declare function createCoercionPlugin(options: CreateCoercionPluginOptions): KyselyPlugin;