@pikku/cli 0.12.28 → 0.12.30

package/dist/.pikku/rpc/pikku-rpc-wirings-meta.internal.gen.json

@@ -96,24 +96,28 @@
     "pikkuAIAgent": "pikkuAIAgent",
     "pikkuPublicAgent": "pikkuPublicAgent",
     "pikkuAuth": "pikkuAuth",
+    "pikkuChannels": "pikkuChannels",
+    "pikkuChannelTypes": "pikkuChannelTypes",
+    "pikkuChannelsMap": "pikkuChannelsMap",
+    "pikkuCommandChannels": "pikkuCommandChannels",
     "pikkuCLIEntry": "pikkuCLIEntry",
     "pikkuCLI": "pikkuCLI",
     "pikkuConsoleFunctions": "pikkuConsoleFunctions",
     "pikkuNodeTypes": "pikkuNodeTypes",
     "pikkuNodesMeta": "pikkuNodesMeta",
     "pikkuCredentials": "pikkuCredentials",
-    "pikkuGateway": "pikkuGateway",
     "pikkuFunctionTypesSplit": "pikkuFunctionTypesSplit",
     "pikkuFunctionTypes": "pikkuFunctionTypes",
     "pikkuFunctions": "pikkuFunctions",
     "pikkuServices": "pikkuServices",
-    "pikkuMCPJSON": "pikkuMCPJSON",
-    "pikkuMCPTypes": "pikkuMCPTypes",
-    "pikkuMCP": "pikkuMCP",
+    "pikkuGateway": "pikkuGateway",
     "pikkuHTTPMap": "pikkuHTTPMap",
     "pikkuCommandHTTP": "pikkuCommandHTTP",
     "pikkuHTTPTypes": "pikkuHTTPTypes",
     "pikkuHTTP": "pikkuHTTP",
+    "pikkuMCPJSON": "pikkuMCPJSON",
+    "pikkuMCPTypes": "pikkuMCPTypes",
+    "pikkuMCP": "pikkuMCP",
     "pikkuMiddleware": "pikkuMiddleware",
     "pikkuSecretDefinitionTypes": "pikkuSecretDefinitionTypes",
     "pikkuVariableDefinitionTypes": "pikkuVariableDefinitionTypes",
@@ -136,9 +140,5 @@
     "pikkuTriggerTypes": "pikkuTriggerTypes",
     "pikkuTrigger": "pikkuTrigger",
     "pikkuVariables": "pikkuVariables",
-    "pikkuWorkflowRoutes": "pikkuWorkflowRoutes",
-    "pikkuChannels": "pikkuChannels",
-    "pikkuChannelTypes": "pikkuChannelTypes",
-    "pikkuChannelsMap": "pikkuChannelsMap",
-    "pikkuCommandChannels": "pikkuCommandChannels"
+    "pikkuWorkflowRoutes": "pikkuWorkflowRoutes"
 }

package/dist/.pikku/scheduler/pikku-scheduler-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 /**
  * Scheduler-specific type definitions for tree-shaking optimization

package/dist/.pikku/scheduler/pikku-scheduler-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 /**
  * Scheduler-specific type definitions for tree-shaking optimization

package/dist/.pikku/schemas/register.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 import { addSchema } from '@pikku/core/schema';
 import * as PikkuSchemasOutput from './schemas/PikkuSchemasOutput.schema.json' with { type: 'json' };
@@ -192,20 +192,20 @@ import * as PikkuCLIEntryOutput from './schemas/PikkuCLIEntryOutput.schema.json'
 addSchema('PikkuCLIEntryOutput', PikkuCLIEntryOutput);
 import * as PikkuCLIOutput from './schemas/PikkuCLIOutput.schema.json' with { type: 'json' };
 addSchema('PikkuCLIOutput', PikkuCLIOutput);
-import * as PikkuGatewayOutput from './schemas/PikkuGatewayOutput.schema.json' with { type: 'json' };
-addSchema('PikkuGatewayOutput', PikkuGatewayOutput);
 import * as PikkuFunctionTypesSplitInput from './schemas/PikkuFunctionTypesSplitInput.schema.json' with { type: 'json' };
 addSchema('PikkuFunctionTypesSplitInput', PikkuFunctionTypesSplitInput);
 import * as PikkuFunctionsOutput from './schemas/PikkuFunctionsOutput.schema.json' with { type: 'json' };
 addSchema('PikkuFunctionsOutput', PikkuFunctionsOutput);
+import * as PikkuGatewayOutput from './schemas/PikkuGatewayOutput.schema.json' with { type: 'json' };
+addSchema('PikkuGatewayOutput', PikkuGatewayOutput);
 import * as PikkuCommandHTTPOutput from './schemas/PikkuCommandHTTPOutput.schema.json' with { type: 'json' };
 addSchema('PikkuCommandHTTPOutput', PikkuCommandHTTPOutput);
 import * as PikkuHTTPOutput from './schemas/PikkuHTTPOutput.schema.json' with { type: 'json' };
 addSchema('PikkuHTTPOutput', PikkuHTTPOutput);
-import * as PikkuMCPOutput from './schemas/PikkuMCPOutput.schema.json' with { type: 'json' };
-addSchema('PikkuMCPOutput', PikkuMCPOutput);
 import * as PikkuMiddlewareOutput from './schemas/PikkuMiddlewareOutput.schema.json' with { type: 'json' };
 addSchema('PikkuMiddlewareOutput', PikkuMiddlewareOutput);
+import * as PikkuMCPOutput from './schemas/PikkuMCPOutput.schema.json' with { type: 'json' };
+addSchema('PikkuMCPOutput', PikkuMCPOutput);
 import * as PikkuPackageOutput from './schemas/PikkuPackageOutput.schema.json' with { type: 'json' };
 addSchema('PikkuPackageOutput', PikkuPackageOutput);
 import * as PikkuPermissionsOutput from './schemas/PikkuPermissionsOutput.schema.json' with { type: 'json' };
@@ -222,13 +222,13 @@ import * as PikkuTriggerTypesInput from './schemas/PikkuTriggerTypesInput.schema
 addSchema('PikkuTriggerTypesInput', PikkuTriggerTypesInput);
 import * as PikkuTriggerOutput from './schemas/PikkuTriggerOutput.schema.json' with { type: 'json' };
 addSchema('PikkuTriggerOutput', PikkuTriggerOutput);
-import * as PikkuWorkflowRoutesOutput from './schemas/PikkuWorkflowRoutesOutput.schema.json' with { type: 'json' };
-addSchema('PikkuWorkflowRoutesOutput', PikkuWorkflowRoutesOutput);
 import * as PikkuPublicRPCOutput from './schemas/PikkuPublicRPCOutput.schema.json' with { type: 'json' };
 addSchema('PikkuPublicRPCOutput', PikkuPublicRPCOutput);
 import * as PikkuRemoteRPCOutput from './schemas/PikkuRemoteRPCOutput.schema.json' with { type: 'json' };
 addSchema('PikkuRemoteRPCOutput', PikkuRemoteRPCOutput);
 import * as PikkuRPCOutput from './schemas/PikkuRPCOutput.schema.json' with { type: 'json' };
 addSchema('PikkuRPCOutput', PikkuRPCOutput);
+import * as PikkuWorkflowRoutesOutput from './schemas/PikkuWorkflowRoutesOutput.schema.json' with { type: 'json' };
+addSchema('PikkuWorkflowRoutesOutput', PikkuWorkflowRoutesOutput);
 import * as PikkuCLIConfig from './schemas/PikkuCLIConfig.schema.json' with { type: 'json' };
 addSchema('PikkuCLIConfig', PikkuCLIConfig);

package/dist/.pikku/secrets/pikku-secret-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 export { wireSecret } from '@pikku/core/secret';
 export type { CoreSecret, SecretDefinitionMeta, SecretDefinitionsMeta } from '@pikku/core/secret';

package/dist/.pikku/secrets/pikku-secret-types.gen.js

@@ -1,4 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 export { wireSecret } from '@pikku/core/secret';

package/dist/.pikku/secrets/pikku-secrets.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 import { TypedSecretService as CoreTypedSecretService } from '@pikku/core/services';
 import type { SecretService } from '@pikku/core/services';

package/dist/.pikku/secrets/pikku-secrets.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 import { TypedSecretService as CoreTypedSecretService } from '@pikku/core/services';
 const CREDENTIALS_META = {};

package/dist/.pikku/trigger/pikku-trigger-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 /**
  * Trigger-specific type definitions for tree-shaking optimization

package/dist/.pikku/trigger/pikku-trigger-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 /**
  * Trigger-specific type definitions for tree-shaking optimization

package/dist/.pikku/variables/pikku-variable-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 export { wireVariable } from '@pikku/core/variable';
 export type { CoreVariable, VariableDefinitionMeta, VariableDefinitionsMeta } from '@pikku/core/variable';

package/dist/.pikku/variables/pikku-variable-types.gen.js

@@ -1,4 +1,4 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 export { wireVariable } from '@pikku/core/variable';

package/dist/.pikku/variables/pikku-variables.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 import { TypedVariablesService as CoreTypedVariablesService } from '@pikku/core/services';
 import type { VariablesService } from '@pikku/core/services';

package/dist/.pikku/variables/pikku-variables.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 import { TypedVariablesService as CoreTypedVariablesService } from '@pikku/core/services';
 const VARIABLES_META = {};

package/dist/.pikku/workflow/meta/allWorkflow.gen.json

@@ -225,9 +225,15 @@
         "Events scaffold": {
             "nodeId": "Events scaffold",
             "rpcName": "pikkuEventsScaffold",
-            "next": "Secret definition types",
+            "next": "Emails",
             "stepHash": "b5a547ac59ef"
         },
+        "Emails": {
+            "nodeId": "Emails",
+            "rpcName": "pikkuEmails",
+            "next": "Secret definition types",
+            "stepHash": "bb8361cb96cf"
+        },
         "Secret definition types": {
             "nodeId": "Secret definition types",
             "rpcName": "pikkuSecretDefinitionTypes",
@@ -521,5 +527,5 @@
     "entryNodeIds": [
         "Bootstrap inspect"
     ],
-    "graphHash": "1c85dee2bb48"
+    "graphHash": "359c0b7178dc"
 }

package/dist/.pikku/workflow/pikku-workflow-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { template } from '@pikku/core/workflow';

package/dist/.pikku/workflow/pikku-workflow-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { template } from '@pikku/core/workflow';

package/dist/.pikku/workflow/pikku-workflow-wirings-meta.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 import { pikkuState } from '@pikku/core/internal';
 import allWorkflowMeta from './meta/allWorkflow.gen.json' with { type: 'json' };

package/dist/.pikku/workflow/pikku-workflow-wirings.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.28
+ * This file was generated by @pikku/cli@0.12.30
  */
 import { addWorkflow } from '@pikku/core/workflow';
 import './pikku-workflow-wirings-meta.gen.js';

package/dist/bin/pikku-bin.mjs

@@ -11,8 +11,8 @@ async function checkForUpdate() {
     })
     if (!res.ok) return
     const { version: latest } = await res.json()
-    if (latest !== '0.12.28') {
-      process.stderr.write(`\n  Update available  0.12.28 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
+    if (latest !== '0.12.30') {
+      process.stderr.write(`\n  Update available  0.12.30 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
     }
   } catch {}
 }

package/dist/src/fabric/functions/validate-core.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
 import { z } from 'zod';
 import { added, changed, dim, removed } from '../lib/output.js';
 import { WorkspaceValidateOutput, readJsonSafe, readTextSafe, runWorkspaceValidate, } from '../../functions/validate/workspace-validate.js';
@@ -31,6 +32,53 @@ export async function runFabricValidate(startDir = process.cwd()) {
     const info = (id, message, path, fixHint) => {
         findings.push({ id, severity: 'info', message, path, fixHint });
     };
+    // These dirs are generated/runtime artefacts; committing them bloats PRs and causes stale issues
+    const gitignorePath = join(root, '.gitignore');
+    const REQUIRED_GITIGNORE_ENTRIES = [
+        {
+            name: '.pikku',
+            patterns: ['.pikku', '.pikku/', '/.pikku', '/.pikku/'],
+            reason: 'generated codegen artifacts will pollute commits and PRs',
+        },
+        {
+            name: '.pikku-runtime',
+            patterns: [
+                '.pikku-runtime',
+                '.pikku-runtime/',
+                '/.pikku-runtime',
+                '/.pikku-runtime/',
+            ],
+            reason: 'runtime state directory should not be committed',
+        },
+        {
+            name: '.opencode',
+            patterns: ['.opencode', '.opencode/', '/.opencode', '/.opencode/'],
+            reason: 'OpenCode session data should not be committed',
+        },
+        {
+            name: '*.gen.ts',
+            patterns: ['*.gen.ts', '**/*.gen.ts'],
+            reason: 'generated TypeScript files (by pikku and TanStack Start) should not be committed — they are regenerated at build time',
+        },
+        {
+            name: '*.gen.js',
+            patterns: ['*.gen.js', '**/*.gen.js'],
+            reason: 'generated JavaScript files (by pikku and TanStack Start) should not be committed — they are regenerated at build time',
+        },
+    ];
+    try {
+        const gitignoreText = await readFile(gitignorePath, 'utf8');
+        const lines = gitignoreText.split('\n').map((l) => l.trim());
+        for (const entry of REQUIRED_GITIGNORE_ENTRIES) {
+            const covered = lines.some((l) => entry.patterns.includes(l));
+            if (!covered) {
+                w(`${entry.name.replace(/[^a-z0-9]/gi, '-')}-not-gitignored`, `${entry.name} is not listed in .gitignore — ${entry.reason}`, gitignorePath, `Add "${entry.name}" to .gitignore`);
+            }
+        }
+    }
+    catch {
+        w('gitignore-missing', '.gitignore not found at project root — generated artifacts (.pikku, .pikku-runtime, .opencode) may be committed accidentally', gitignorePath, 'Create .gitignore and add ".pikku", ".pikku-runtime", and ".opencode" to it');
+    }
     const fabricConfigPath = join(root, 'fabric.config.json');
     const fabricConfig = await readJsonSafe(fabricConfigPath);
     if (!fabricConfig) {
@@ -69,6 +117,12 @@ export async function runFabricValidate(startDir = process.cwd()) {
             if (fnAllDeps['@pikku/kysely-postgres']) {
                 e('fn-pkg-postgres-dep', '@pikku/kysely-postgres is in packages/functions dependencies — Fabric uses SQLite/libSQL (Turso), not PostgreSQL', fnPkgPath, 'Remove @pikku/kysely-postgres and use @pikku/kysely-sqlite with LibsqlWebDialect instead');
             }
+            if (!fnPkg.dependencies?.['@pikku/schema-cfworker']) {
+                e('missing-schema-cfworker', '@pikku/schema-cfworker is not in dependencies — every Cloudflare worker entry requires it', fnPkgPath, 'Run `yarn add @pikku/schema-cfworker` in packages/functions — must be in dependencies, not devDependencies');
+            }
+            if (!fnPkg.dependencies?.['@pikku/kysely']) {
+                e('missing-pikku-kysely', '@pikku/kysely is not in dependencies — every Cloudflare worker entry requires it (KyselySecretService)', fnPkgPath, 'Run `yarn add @pikku/kysely` in packages/functions — must be in dependencies, not devDependencies');
+            }
         }
         const servicesPath = join(fnDir, 'src', 'services.ts');
         const servicesText = await readTextSafe(servicesPath);
@@ -90,6 +144,17 @@ export async function runFabricValidate(startDir = process.cwd()) {
                 e('missing-kysely-sqlite', 'services.ts imports @pikku/kysely-sqlite but it is not in root package.json', rootPkgPath, 'Add "@pikku/kysely-sqlite": "file:./vendor/pikku-kysely-sqlite.tgz" to dependencies');
             }
         }
+        // agent units — require explicit deps rather than CI injection
+        const agentMetaPath = join(fnDir, '.pikku', 'agent', 'pikku-agent-wirings-meta.gen.json');
+        const agentMeta = await readJsonSafe(agentMetaPath);
+        if (agentMeta && Object.keys(agentMeta.agentsMeta ?? {}).length > 0) {
+            if (!fnPkg?.dependencies?.['@pikku/ai-vercel']) {
+                e('missing-ai-vercel', 'Project declares agent units but @pikku/ai-vercel is not in dependencies', fnPkgPath, 'Run `yarn add @pikku/ai-vercel` in packages/functions — must be in dependencies, not devDependencies');
+            }
+            if (!fnPkg?.dependencies?.['@ai-sdk/openai-compatible']) {
+                e('missing-ai-sdk-openai-compatible', 'Project declares agent units but @ai-sdk/openai-compatible is not in dependencies', fnPkgPath, 'Run `yarn add @ai-sdk/openai-compatible` in packages/functions — must be in dependencies, not devDependencies');
+            }
+        }
         // db/sqlite/ — presence, numbering and SQL dialect
         const migrationsDir = join(fnDir, 'db', 'sqlite');
         if (!existsSync(migrationsDir)) {

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

@@ -1,4 +1,3 @@
-import { existsSync } from 'fs';
 import { join, resolve } from 'path';
 import { pikkuSessionlessFunc } from '#pikku';
 import chokidar from 'chokidar';
@@ -14,11 +13,11 @@ import { pikkuWebsocketHandler } from '@pikku/ws';
 import { PikkuNodeHTTPServer } from '@pikku/node-http-server';
 import { WebSocketServer } from 'ws';
 import { InMemorySchedulerService } from '@pikku/schedule';
-import { resolveDb, createKysely } from '../db/local-db.js';
+import { resolveDb, createKysely, parseDatabaseUrl, } from '../db/local-db.js';
 import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
 export const dev = pikkuSessionlessFunc({
     remote: true,
-    func: async ({ logger, config, getInspectorState }, { port, watch, hmr }, { rpc }) => {
+    func: async ({ logger, config, getInspectorState, variables }, { port, watch, hmr }, { rpc }) => {
         const resolvedPort = parseInt(port || '3000', 10);
         const hostname = 'localhost';
         const enableWatch = watch !== false;
@@ -40,8 +39,6 @@ export const dev = pikkuSessionlessFunc({
         const commandWorkflowRegistrations = new Map(pikkuState(null, 'workflows', 'registrations'));
         const workflowService = new InMemoryWorkflowService();
         const pikkuDir = resolve(config.rootDir, config.outDir);
-        const bootstrapExists = existsSync(resolve(pikkuDir, 'pikku-bootstrap.gen.ts')) ||
-            existsSync(resolve(pikkuDir, 'pikku-bootstrap.gen.js'));
         const runAll = async () => {
             await workflowService.runToCompletion('allWorkflow', {}, rpc);
         };
@@ -97,9 +94,6 @@ export const dev = pikkuSessionlessFunc({
                 pikkuState(null, 'workflows', 'registrations', previousWorkflowRegistrations);
             }
         };
-        if (bootstrapExists) {
-            await loadUserBootstrap(pikkuDir);
-        }
         await runAllWithCommandState();
         const inspectorState = await getInspectorState(true);
         const { pikkuConfigFactory, singletonServicesFactory } = inspectorState.filesAndMethods;
@@ -107,21 +101,19 @@ export const dev = pikkuSessionlessFunc({
             logger.error('createConfig and createSingletonServices must be defined in your project');
             return;
         }
-        if (!bootstrapExists) {
-            await loadUserBootstrap(pikkuDir);
-        }
+        await loadUserBootstrap(pikkuDir);
         workflowService.rewireQueueWorkers();
         const configModule = await loadUserModule(pikkuConfigFactory.file);
         const servicesModule = await loadUserModule(singletonServicesFactory.file);
         const userCreateConfig = configModule[pikkuConfigFactory.variable];
         const userCreateSingletonServices = servicesModule[singletonServicesFactory.variable];
         const userConfig = await userCreateConfig();
-        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 envDatabaseUrl = await variables.get('DATABASE_URL');
+        const effectiveDbConfig = envDatabaseUrl
+            ? parseDatabaseUrl(envDatabaseUrl)
+            : userConfig;
+        const resolvedDb = resolveDb(effectiveDbConfig, config.rootDir, config.outDir, config.runtimeDir);
+        const resolvedLocalDb = resolvedDb?.dialect === 'sqlite' ? resolvedDb : undefined;
         const kysely = resolvedLocalDb
             ? await createKysely(resolvedLocalDb)
             : undefined;

package/dist/src/functions/db/db-codegen.d.ts

@@ -4,6 +4,7 @@ export interface CodegenOptions {
     coercionFile: string;
     manifestFile?: string;
     classificationMapFile?: string;
+    schemaJsonFile?: string;
     camelCase?: boolean;
     rootDir?: string;
     migrationsDir?: string;

package/dist/src/functions/db/db-codegen.js

@@ -308,11 +308,43 @@ export async function generateSchemaTypes(introspector, options) {
     const classificationMapBody = options.classificationMapFile
         ? emitClassificationMap(tables)
         : null;
+    // ── pikku-db-schema.gen.json ─────────────────────────────────────────────────
+    let schemaJsonBody = null;
+    if (options.schemaJsonFile) {
+        const [fkResults, enums] = await Promise.all([
+            Promise.all(tableNames.map((name) => introspector.getForeignKeys(name))),
+            introspector.listEnums(),
+        ]);
+        const fkMap = new Map(tableNames.map((name, i) => [name, fkResults[i]]));
+        const jsonTables = tables.map((t) => ({
+            name: t.name,
+            columns: t.columns.map((c) => {
+                const fk = fkMap.get(t.name)?.find((f) => f.column === c.name);
+                return {
+                    name: c.name,
+                    type: c.type,
+                    nullable: !c.notNull && !c.pk,
+                    isPrimaryKey: c.pk,
+                    ...(fk
+                        ? {
+                            foreignKey: {
+                                table: fk.foreignTable,
+                                column: fk.foreignColumn,
+                            },
+                        }
+                        : {}),
+                };
+            }),
+        }));
+        schemaJsonBody =
+            JSON.stringify({ tables: jsonTables, enums }, null, 2) + '\n';
+    }
     // ── write files ───────────────────────────────────────────────────────────────
     let existingSchema = null;
     let existingCoercion = null;
     let existingManifest = null;
     let existingClassificationMap = null;
+    let existingSchemaJson = null;
     try {
         existingSchema = readFileSync(options.outFile, 'utf8');
     }
@@ -341,11 +373,20 @@ export async function generateSchemaTypes(introspector, options) {
             /* ok */
         }
     }
+    if (options.schemaJsonFile) {
+        try {
+            existingSchemaJson = readFileSync(options.schemaJsonFile, 'utf8');
+        }
+        catch {
+            /* ok */
+        }
+    }
     const schemaChanged = existingSchema !== schemaBody;
     const coercionChanged = existingCoercion !== coercionBody;
     const manifestChanged = manifestBody !== null && existingManifest !== manifestBody;
     const classificationMapChanged = classificationMapBody !== null &&
         existingClassificationMap !== classificationMapBody;
+    const schemaJsonChanged = schemaJsonBody !== null && existingSchemaJson !== schemaJsonBody;
     if (schemaChanged) {
         mkdirSync(dirname(options.outFile), { recursive: true });
         writeFileSync(options.outFile, schemaBody, 'utf8');
@@ -364,6 +405,10 @@ export async function generateSchemaTypes(introspector, options) {
         mkdirSync(dirname(options.classificationMapFile), { recursive: true });
         writeFileSync(options.classificationMapFile, classificationMapBody, 'utf8');
     }
+    if (schemaJsonChanged && options.schemaJsonFile && schemaJsonBody) {
+        mkdirSync(dirname(options.schemaJsonFile), { recursive: true });
+        writeFileSync(options.schemaJsonFile, schemaJsonBody, 'utf8');
+    }
     return {
         outFile: options.outFile,
         coercionFile: options.coercionFile,

package/dist/src/functions/db/db-introspector.d.ts

@@ -8,8 +8,20 @@ export interface ColumnInfo {
     /** True for virtual or stored generated columns — these are read-only and never inserted. */
     generated?: boolean;
 }
+export interface ForeignKeyInfo {
+    column: string;
+    foreignTable: string;
+    foreignColumn: string;
+}
+export interface EnumInfo {
+    name: string;
+    schema: string;
+    values: string[];
+}
 export interface DbIntrospector {
     listTables(): Promise<string[]>;
     getColumns(table: string): Promise<ColumnInfo[]>;
+    getForeignKeys(table: string): Promise<ForeignKeyInfo[]>;
+    listEnums(): Promise<EnumInfo[]>;
     close(): Promise<void>;
 }

package/dist/src/functions/db/local-db.d.ts

@@ -11,6 +11,7 @@ interface ResolvedDbBase {
     coercionFile: string;
     manifestFile: string;
     classificationMapFile: string;
+    schemaJsonFile: string;
     classificationsFile: string;
     classificationsGenJsonFile: string;
     zodFile: string;
@@ -27,6 +28,13 @@ export interface ResolvedPostgresDb extends ResolvedDbBase {
     connectionString: string;
 }
 export type ResolvedDb = ResolvedSqliteDb | ResolvedPostgresDb;
+/**
+ * Parse a DATABASE_URL string into the subset of UserConfigShape that resolveDb understands.
+ * - postgres(ql):// → { postgresUrl }
+ * - libsql:// or http(s):// → {} (remote, not handled by the CLI layer)
+ * - anything else → { sqliteDb } (local file path)
+ */
+export declare function parseDatabaseUrl(url: string): Pick<UserConfigShape, 'sqliteDb' | 'postgresUrl'>;
 /**
  * Resolve a UserConfigShape into an absolute-path descriptor.
  * Returns null when neither sqliteDb nor postgresUrl is configured.

package/dist/src/functions/db/local-db.js

@@ -15,6 +15,19 @@ import { seed as runSeed } from './sqlite/seed.js';
 import { PostgresMigrationExecutor } from './postgres/postgres-migrator.js';
 import { PostgresIntrospector } from './postgres/postgres-introspector.js';
 // ─── Resolution ───────────────────────────────────────────────────────────────
+/**
+ * Parse a DATABASE_URL string into the subset of UserConfigShape that resolveDb understands.
+ * - postgres(ql):// → { postgresUrl }
+ * - libsql:// or http(s):// → {} (remote, not handled by the CLI layer)
+ * - anything else → { sqliteDb } (local file path)
+ */
+export function parseDatabaseUrl(url) {
+    if (/^postgres(ql)?:\/\//.test(url))
+        return { postgresUrl: url };
+    if (/^(libsql|https?):\/\//.test(url))
+        return {};
+    return { sqliteDb: url };
+}
 /**
  * Resolve a UserConfigShape into an absolute-path descriptor.
  * Returns null when neither sqliteDb nor postgresUrl is configured.
@@ -27,6 +40,7 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
         coercionFile: join(outDir, 'db', 'coercion.gen.ts'),
         manifestFile: join(outDir, 'db', 'classification.gen.ts'),
         classificationMapFile: join(outDir, 'db', 'classification-map.gen.d.ts'),
+        schemaJsonFile: join(outDir, 'db', 'pikku-db-schema.gen.json'),
         classificationsFile: join(rootDir, 'db', 'annotations.ts'),
         classificationsGenJsonFile: join(outDir, 'db', 'annotations.gen.json'),
         zodFile: join(outDir, 'db', 'zod.gen.ts'),
@@ -82,6 +96,7 @@ export async function migrateAndCodegen(resolved) {
                 coercionFile: resolved.coercionFile,
                 manifestFile: resolved.manifestFile,
                 classificationMapFile: resolved.classificationMapFile,
+                schemaJsonFile: resolved.schemaJsonFile,
                 camelCase: resolved.camelCase,
                 rootDir: resolved.rootDir,
                 migrationsDir: resolved.migrationsDir,
@@ -107,7 +122,9 @@ export async function migrateAndCodegen(resolved) {
                     coercionFile: resolved.coercionFile,
                     manifestFile: resolved.manifestFile,
                     classificationMapFile: resolved.classificationMapFile,
+                    schemaJsonFile: resolved.schemaJsonFile,
                     camelCase: resolved.camelCase,
+                    rootDir: resolved.rootDir,
                     migrationsDir: resolved.migrationsDir,
                 });
             }

package/dist/src/functions/db/postgres/postgres-introspector.d.ts

@@ -1,4 +1,4 @@
-import type { DbIntrospector, ColumnInfo } from '../db-introspector.js';
+import type { DbIntrospector, ColumnInfo, ForeignKeyInfo, EnumInfo } from '../db-introspector.js';
 interface QueryClient {
     query<T = unknown>(sql: string, params?: unknown[]): Promise<{
         rows: T[];
@@ -11,6 +11,8 @@ export declare class PostgresIntrospector implements DbIntrospector {
     connect(): Promise<void>;
     listTables(): Promise<string[]>;
     getColumns(table: string): Promise<ColumnInfo[]>;
+    getForeignKeys(table: string): Promise<ForeignKeyInfo[]>;
+    listEnums(): Promise<EnumInfo[]>;
     close(): Promise<void>;
 }
 export {};