@pikku/cli 0.12.28 → 0.12.29

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.29
  */
 import { addSchema } from '@pikku/core/schema';
 import * as PikkuSchemasOutput from './schemas/PikkuSchemasOutput.schema.json' with { type: 'json' };
@@ -192,12 +192,12 @@ 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' };
@@ -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.29
  */
 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.29
  */
 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.29
  */
 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.29
  */
 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.29
  */
 /**
  * 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.29
  */
 /**
  * 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.29
  */
 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.29
  */
 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.29
  */
 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.29
  */
 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.29
  */
 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.29
  */
 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.29
  */
 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.29
  */
 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.29') {
+      process.stderr.write(`\n  Update available  0.12.29 → ${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

@@ -14,11 +14,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;
@@ -116,12 +116,12 @@ export const dev = pikkuSessionlessFunc({
         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/local-db.d.ts

@@ -27,6 +27,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.
@@ -108,6 +121,7 @@ export async function migrateAndCodegen(resolved) {
                     manifestFile: resolved.manifestFile,
                     classificationMapFile: resolved.classificationMapFile,
                     camelCase: resolved.camelCase,
+                    rootDir: resolved.rootDir,
                     migrationsDir: resolved.migrationsDir,
                 });
             }

package/dist/src/scaffold/rpc-remote.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.29
  */
 /**
  * Auto-generated remote internal RPC queue worker and HTTP endpoint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/cli",
-  "version": "0.12.28",
+  "version": "0.12.29",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "imports": {
@@ -29,7 +29,7 @@
     "@pikku/core": "^0.12.27",
     "@pikku/deploy-cloudflare": "^0.12.3",
     "@pikku/fetch": "^0.12.2",
-    "@pikku/inspector": "^0.12.14",
+    "@pikku/inspector": "^0.12.15",
     "@pikku/kysely": "^0.12.14",
     "@pikku/kysely-node-sqlite": "^0.12.1",
     "@pikku/node-http-server": "^0.12.1",

package/skills/pikku-workflow/SKILL.md

@@ -71,6 +71,28 @@ await workflow.sleep('Wait 5 minutes', '5min')
 await workflow.suspend('Awaiting approval')
 ```
 
+### Choosing the right wrapper
+
+| Wrapper | When to use |
+|---|---|
+| `pikkuWorkflowFunc` | **Default.** Use for all new workflows. DSL mode — serialisable, replay-safe. |
+| `pikkuWorkflowComplexFunc` | **Only with explicit user approval.** For workflows with patterns the DSL extractor cannot handle (e.g. dynamic inline functions). Not a general escape hatch — restructure first. |
+| `pikkuWorkflowGraph` | **Only with explicit user approval.** For genuine DAGs where there is a cyclic dependency between nodes or a Node.js-only import DSL cannot express. |
+
+**Conditional results** — the correct DSL pattern when a step only runs under some condition:
+
+```typescript
+// ✅ Declare at top level, assign inside block
+let result: { id: string } | null = null
+if (input.createFoo) {
+  result = await workflow.do('Create foo', 'createFoo', { ... })
+}
+// Use result?.id downstream
+
+// ❌ Do NOT declare const inside a block — DSL forbids block-scoped declarations
+// ❌ Do NOT switch to pikkuWorkflowComplexFunc to avoid the restriction
+```
+
 ### `pikkuWorkflowGraph(config)` — DAG Workflows
 
 ```typescript