@pikku/cli 0.12.26 → 0.12.27

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

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.26
+ * This file was generated by @pikku/cli@0.12.27
  */
 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.26
+ * This file was generated by @pikku/cli@0.12.27
  */
 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.26
+ * This file was generated by @pikku/cli@0.12.27
  */
 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.26') {
-      process.stderr.write(`\n  Update available  0.12.26 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
+    if (latest !== '0.12.27') {
+      process.stderr.write(`\n  Update available  0.12.27 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
     }
   } catch {}
 }

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

@@ -90,10 +90,10 @@ 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');
             }
         }
-        // db/migrations/ — presence, numbering and SQL dialect
-        const migrationsDir = join(fnDir, 'db', 'migrations');
+        // db/sqlite/ — presence, numbering and SQL dialect
+        const migrationsDir = join(fnDir, 'db', 'sqlite');
         if (!existsSync(migrationsDir)) {
-            e('migrations-dir-missing', 'packages/functions/db/migrations/ not found', migrationsDir, 'Create db/migrations/ and add numbered .sql files (e.g. 0001-init.sql) using SQLite-compatible syntax');
+            e('migrations-dir-missing', 'packages/functions/db/sqlite/ not found', migrationsDir, 'Create db/sqlite/ and add numbered .sql files (e.g. 0001-init.sql) using SQLite-compatible syntax');
         }
         else {
             try {
@@ -125,10 +125,10 @@ export async function runFabricValidate(startDir = process.cwd()) {
                 // readdir failure — skip
             }
         }
-        // db/seed.sql
-        const seedPath = join(fnDir, 'db', 'seed.sql');
+        // db/sqlite-seed.sql
+        const seedPath = join(fnDir, 'db', 'sqlite-seed.sql');
         if (!existsSync(seedPath)) {
-            e('seed-sql-missing', 'packages/functions/db/seed.sql not found', seedPath, 'Create db/seed.sql with idempotent INSERT OR IGNORE statements for demo/test data');
+            e('seed-sql-missing', 'packages/functions/db/sqlite-seed.sql not found', seedPath, 'Create db/sqlite-seed.sql with idempotent INSERT OR IGNORE statements for demo/test data');
         }
     }
     const appsDir = join(root, 'apps');

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

@@ -6,6 +6,7 @@ import { type SeedResult } from './sqlite/seed.js';
 import type { UserConfigShape } from '../commands/db-shared.js';
 interface ResolvedDbBase {
     migrationsDir: string;
+    seedFile: string;
     schemaFile: string;
     coercionFile: string;
     manifestFile: string;
@@ -16,7 +17,6 @@ export interface ResolvedSqliteDb extends ResolvedDbBase {
     dialect: 'sqlite';
     dbFile: string;
     runtimeDir: string;
-    seedFile: string;
 }
 export interface ResolvedPostgresDb extends ResolvedDbBase {
     dialect: 'postgres';

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

@@ -17,8 +17,9 @@ import { PostgresIntrospector } from './postgres/postgres-introspector.js';
  * Returns null when neither sqliteDb nor postgresUrl is configured.
  */
 export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
-    const base = (sub) => ({
+    const base = (sub, seedFileName) => ({
         migrationsDir: resolveAgainst(rootDir, sub),
+        seedFile: resolveAgainst(rootDir, seedFileName),
         schemaFile: join(outDir, 'db', 'schema.d.ts'),
         coercionFile: join(outDir, 'db', 'coercion.gen.ts'),
         manifestFile: join(outDir, 'db', 'classification.gen.ts'),
@@ -32,7 +33,7 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
         return {
             dialect: 'postgres',
             connectionString: userConfig.postgresUrl,
-            ...base('db/postgres'),
+            ...base('db/postgres', 'db/postgres-seed.sql'),
         };
     }
     if (userConfig.sqliteDb) {
@@ -43,8 +44,7 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
             dialect: 'sqlite',
             dbFile: resolveAgainst(rootDir, userConfig.sqliteDb),
             runtimeDir: resolvedRuntimeDir,
-            seedFile: resolveAgainst(rootDir, 'db/seed.sql'),
-            ...base('db/sqlite'),
+            ...base('db/sqlite', 'db/sqlite-seed.sql'),
         };
     }
     return null;

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

@@ -142,10 +142,13 @@ export async function runWorkspaceValidate(startDir = process.cwd()) {
         if (!servicesText) {
             w('services-missing', 'packages/functions/src/services.ts not found', servicesPath, 'Create services.ts and export your service factory for the workspace');
         }
-        const migrationsDir = join(fnDir, 'db', 'migrations');
         const authEnabled = await hasAuthSessionMiddleware(fnDir);
         const configText = await readTextSafe(join(fnDir, 'src', 'config.ts'));
         const hasConfiguredDevDb = /sqliteDb/.test(configText ?? '');
+        const hasPostgresUrl = /postgresUrl/.test(configText ?? '');
+        const migrationsDir = hasPostgresUrl
+            ? join(fnDir, 'db', 'postgres')
+            : join(fnDir, 'db', 'sqlite');
         let createsAppUser = false;
         let createsAuthVerificationToken = false;
         if (existsSync(migrationsDir)) {

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/cli",
-  "version": "0.12.26",
+  "version": "0.12.27",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "imports": {
@@ -26,11 +26,11 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.25",
+    "@pikku/core": "^0.12.26",
     "@pikku/deploy-cloudflare": "^0.12.3",
     "@pikku/fetch": "^0.12.2",
     "@pikku/inspector": "^0.12.13",
-    "@pikku/kysely": "^0.12.12",
+    "@pikku/kysely": "^0.12.13",
     "@pikku/kysely-node-sqlite": "^0.12.1",
     "@pikku/node-http-server": "^0.12.1",
     "@pikku/openapi-parser": "^0.12.10",

package/skills/pikku-middleware/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: pikku-middleware
+description: 'Use when adding any middleware to a Pikku app — global HTTP middleware, tag-scoped middleware (including service-to-service bearer auth), per-route middleware, session-setting middleware, or understanding middleware execution order and priority.
+TRIGGER when: user wants middleware on some or all routes, machine-to-machine auth, tag-scoped cross-cutting concerns, global interceptors, or middleware priority/order questions.
+DO NOT TRIGGER when: user asks about permissions/authorization checks (use pikku-permissions), auth strategies like authBearer/authCookie (use pikku-security), or deployment.'
+installGroups: [core]
+---
+
+# Pikku Middleware
+
+## Agent Operating Procedure
+
+1. Discover before editing. Run `pikku info middleware --verbose` and `pikku info tags --json` to understand the existing middleware and tag landscape.
+2. Identify the source files that own the behavior — wirings files, not generated output.
+3. Register middleware at module load time — in a `wirings/*.ts` file, never inside a function body.
+4. Validate: run `pikku all` after adding or changing middleware; run `pikku tsc` to confirm type safety.
+
+## The `pikkuMiddleware` Factory
+
+```typescript
+import { pikkuMiddleware } from '#pikku'
+
+// Simple: just a function
+const myMiddleware = pikkuMiddleware(async (services, wire, next) => {
+  // runs before the function
+  await next()
+  // runs after the function (optional)
+})
+
+// With metadata (name + priority)
+const telemetryMiddleware = pikkuMiddleware({
+  name: 'my-telemetry',
+  priority: 'highest',
+  func: async (services, wire, next) => {
+    const start = performance.now()
+    try {
+      await next()
+    } finally {
+      services.logger.info({ duration: Math.round(performance.now() - start) })
+    }
+  },
+})
+```
+
+The `wire` object gives you:
+- `wire.http` — inbound HTTP context (headers, URL, cookies)
+- `wire.setSession(session)` — set the session for this request
+- `wire.getSession()` — read the current session
+- `wire.session` — the session set so far (may be undefined)
+
+Throw a typed error to abort: `UnauthorizedError`, `ForbiddenError`, etc. from `@pikku/core/errors`.
+
+## Scoping: Five Levels
+
+From broadest to narrowest:
+
+```typescript
+// 1. Wire-agnostic global: all wire types (HTTP, Queue, Channel, Trigger, Workflow, ...)
+addGlobalMiddleware([telemetryOuter()])
+
+// 2. HTTP global: all HTTP routes
+addHTTPMiddleware('*', [cors(), authBearer()])
+
+// 3. Prefix-based: URL pattern
+addHTTPMiddleware('/admin/*', [auditLog])
+
+// 4. Tag-based: any wiring with matching tag
+addTagMiddleware('machine-agent', [bearerAuth])  // tag on function or wire
+
+// 5. Inline: per-wiring
+wireHTTP({
+  route: '/books/:id',
+  func: getBook,
+  middleware: [cacheControl],
+})
+```
+
+## Global Middleware (`addGlobalMiddleware`)
+
+`addGlobalMiddleware` registers middleware that runs before everything else — across every wire type: HTTP, Queue, Channel, Trigger, Scheduler, Workflow, Agent, CLI, MCP. Use it for cross-cutting concerns like telemetry that must wrap every invocation regardless of transport.
+
+```typescript
+import { addGlobalMiddleware } from '@pikku/core'
+import { telemetryOuter, telemetryInner } from '@pikku/core/middleware'
+
+// Outer telemetry: wraps the full call (highest priority)
+addGlobalMiddleware([telemetryOuter({ environmentId: env.STAGE_ID })])
+
+// Inner telemetry: closest to the function body (lowest priority)
+addGlobalMiddleware([telemetryInner({ environmentId: env.STAGE_ID })])
+```
+
+`telemetryOuter` ships with `priority: 'highest'` and `telemetryInner` with `priority: 'lowest'` — so even if both are added in the same call, priority sorting places outer first regardless of array order.
+
+## HTTP & Prefix Middleware (`addHTTPMiddleware`)
+
+```typescript
+import { addHTTPMiddleware } from '@pikku/core/http'
+import { cors, authBearer } from '@pikku/core/middleware'
+
+// All routes
+addHTTPMiddleware('*', [cors({ origin: 'https://app.example.com', credentials: true })])
+
+// Scoped to /api/* prefix
+addHTTPMiddleware('/api/*', [rateLimit({ maxRequests: 100, windowMs: 60_000 })])
+```
+
+## Tag Middleware (`addTagMiddleware`)
+
+Tag middleware fires for any wiring (function or wire object) that carries a matching tag. This is the canonical approach for service-to-service bearer auth, rate limiting a group, or any cross-cutting concern scoped to a subset of routes.
+
+### Setting Tags
+
+```typescript
+// On the function definition
+export const myFunc = pikkuSessionlessFunc({
+  auth: false,
+  tags: ['machine-agent'],
+  func: async (services, input) => { ... },
+})
+
+// On the wire object
+wireHTTP({
+  route: '/internal/action',
+  method: 'post',
+  auth: false,
+  tags: ['internal'],
+  func: myFunc,
+})
+```
+
+Tags from the function definition and the wire object are merged — middleware from both tag sets runs.
+
+### Registering Tag Middleware
+
+```typescript
+import { addTagMiddleware } from '.pikku/pikku-types.gen.js'
+
+addTagMiddleware('machine-agent', [machineAgentBearerAuth])
+```
+
+Call at module load time — typically in the same `wirings/*.ts` file as the `wireHTTP` calls that use the tag.
+
+## Middleware Execution Order
+
+**Scope resolution order (broadest → narrowest):**
+
+```
+global → httpGroup/* → httpGroup/prefix → wiringTags → wiringMiddleware → funcTags → funcMiddleware → function body
+```
+
+**Within each scope, sorted by priority:**
+
+```
+highest → high → medium (default) → low → lowest
+```
+
+Set priority using the config-object form of `pikkuMiddleware`:
+
+```typescript
+const earlyMiddleware = pikkuMiddleware({
+  name: 'early',
+  priority: 'highest',   // 'highest' | 'high' | 'medium' | 'low' | 'lowest'
+  func: async (services, wire, next) => { ... },
+})
+```
+
+Within the same priority level, registration order is preserved. Priority is the primary sort key — use it when a middleware must run before or after others regardless of registration order (e.g. telemetry wrapping everything, session extraction before auth checks).
+
+## Common Patterns
+
+### Service-to-Service Bearer Auth
+
+The canonical pattern for a server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent):
+
+**On the server (the service being called):**
+
+```typescript
+// lib/host-token.ts
+let _token: string | null = null
+export const setToken = (t: string) => { _token = t }
+export const getToken = () => _token
+```
+
+```typescript
+// wirings/http.wiring.ts
+import { timingSafeEqual } from 'node:crypto'
+import { addTagMiddleware, pikkuMiddleware } from '../../.pikku/pikku-types.gen.js'
+import { UnauthorizedError } from '@pikku/core/errors'
+import { getToken } from '../lib/host-token.js'
+
+const bearerAuth = pikkuMiddleware(async (_services, { http }, next) => {
+  const authHeader = http?.request?.header?.('authorization') || http?.request?.header?.('Authorization')
+  const token = getToken()
+  const expected = token ? `Bearer ${token}` : null
+  if (
+    !expected ||
+    !authHeader ||
+    authHeader.length !== expected.length ||
+    !timingSafeEqual(Buffer.from(authHeader), Buffer.from(expected))
+  ) {
+    throw new UnauthorizedError()
+  }
+  return next()
+})
+
+addTagMiddleware('machine-agent', [bearerAuth])
+```
+
+```typescript
+// functions/my.function.ts
+export const myFunc = pikkuSessionlessFunc({
+  expose: true,
+  auth: false,
+  tags: ['machine-agent'],
+  func: async (services, input) => { ... },
+})
+```
+
+**On the client (the caller):**
+
+Use the generated `RPCInvoke` type from `.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts` — never hand-write the input/output types:
+
+```typescript
+import type { RPCInvoke } from '../../backends/my-service/.pikku/rpc/pikku-rpc-wirings-map.gen.d.js'
+
+export function getServiceRPC(baseUrl: string, token: string): RPCInvoke {
+  return async (name: string, data?: unknown) => {
+    const res = await fetch(`${baseUrl}/rpc/${String(name)}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify({ data: data ?? {} }),
+    })
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      throw new Error(`rpc ${String(name)} failed: ${res.status} ${text}`)
+    }
+    return res.json()
+  } as RPCInvoke
+}
+```
+
+### Session-Setting Middleware
+
+```typescript
+const apiKeyAuth = pikkuMiddleware(async ({ kysely }, { http, setSession, session }, next) => {
+  if (session) return next()  // already authenticated
+
+  const header = http?.request?.header?.('x-api-key')
+  if (!header) return next()
+
+  const row = await kysely.selectFrom('apiKey').select('userId').where('key', '=', header).executeTakeFirst()
+  if (row) setSession?.({ userId: row.userId })
+
+  return next()
+})
+
+addTagMiddleware('api-key-auth', [apiKeyAuth])
+```
+
+Functions tagged `'api-key-auth'` with `auth: true` reject requests without a valid key; those with `auth: false` can inspect the session but won't reject.
+
+### Request Logging / Audit
+
+```typescript
+const auditLog = pikkuMiddleware(async ({ logger, db }, wire, next) => {
+  const start = Date.now()
+  await next()
+  await db.createAuditLog({ duration: Date.now() - start })
+})
+
+addHTTPMiddleware('/admin/*', [auditLog])
+```
+
+## After Changes
+
+```bash
+pikku all        # regenerate metadata so new tags are picked up
+pikku tsc        # type-check
+```

package/skills/pikku-permissions/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: pikku-permissions
+description: 'Use when adding authorization checks to Pikku functions or routes — pikkuPermission, pikkuAuth, per-function permissions, pattern-based permissions, or understanding OR/AND permission logic.
+TRIGGER when: user wants to restrict who can call a function, check resource ownership, add role-based access, or understand where permission checks belong.
+DO NOT TRIGGER when: user asks about middleware or request interception (use pikku-middleware), authentication strategies (use pikku-security), or session management.'
+installGroups: [core]
+---
+
+# Pikku Permissions
+
+## The Rule
+
+**ALWAYS put authorization checks in the `permissions` field of `pikkuFunc` or `pikkuSessionlessFunc` — NEVER inside the `func` body.**
+
+This includes: org access checks, repo access checks, role checks, resource ownership, and any other authorization logic. The `permissions` field runs before `func`, is visible to the inspector, and is the only place Pikku enforces authorization.
+
+```typescript
+// CORRECT
+export const deleteBook = pikkuFunc({
+  func: async ({ db }, { bookId }) => {
+    await db.deleteBook(bookId)
+  },
+  permissions: {
+    owner: isBookOwner,   // ← authorization here
+  },
+})
+
+// WRONG — permission check inside func body
+export const deleteBook = pikkuFunc({
+  func: async ({ db }, { bookId }, { session }) => {
+    if (!session) throw new UnauthorizedError()  // ← never do this
+    await db.deleteBook(bookId)
+  },
+})
+```
+
+## Agent Operating Procedure
+
+1. Discover before editing. Run `pikku info permissions --verbose` and `pikku info functions --verbose` to understand what permissions are already defined and applied.
+2. Define permission checkers in a `src/permissions.ts` or domain-specific `src/lib/*-permissions.ts` file.
+3. Apply them via the `permissions` field on the function, or via `addHTTPPermission` / `addPermission` for pattern/tag-based application.
+4. Validate: run `pikku tsc` to confirm permission checker signatures are correct.
+
+## Permission Factories
+
+### `pikkuAuth(fn)` — Session-Only Checks
+
+Use for checks that only need the session — no request data required.
+
+```typescript
+import { pikkuAuth } from '#pikku'
+
+export const isAuthenticated = pikkuAuth(
+  async (_services, session) => !!session
+)
+
+export const isAdmin = pikkuAuth(
+  async (_services, session) => session?.role === 'admin'
+)
+```
+
+### `pikkuPermission(fn)` — Data-Aware Checks
+
+Use when authorization depends on the actual request data (e.g., resource ownership).
+
+```typescript
+import { pikkuPermission } from '#pikku'
+
+export const isBookOwner = pikkuPermission(
+  async ({ db }, { bookId }, { session }) => {
+    const book = await db.getBook(bookId)
+    return book?.authorId === session?.userId
+  }
+)
+
+export const hasBookAccess = pikkuPermission(
+  async ({ db }, { bookId }, { session }) => {
+    return await db.hasAccess(session?.userId, bookId)
+  }
+)
+```
+
+## OR / AND Logic
+
+```typescript
+permissions: {
+  admin: isAdmin,                              // OR: admins can access
+  owner: isBookOwner,                          // OR: owners can access
+  reviewer: [isAuthenticated, hasBookAccess],  // AND: both must pass
+}
+// Logic: admin OR owner OR (isAuthenticated AND hasBookAccess)
+```
+
+Groups are OR'd. Entries within a group array are AND'd.
+
+## Where to Apply Permissions
+
+### Per-Function (preferred)
+
+```typescript
+export const deleteBook = pikkuFunc({
+  func: async ({ db }, { bookId }) => {
+    await db.deleteBook(bookId)
+  },
+  permissions: {
+    admin: isAdmin,
+    owner: isBookOwner,
+  },
+})
+```
+
+### Pattern-Based (`addHTTPPermission`)
+
+```typescript
+import { addHTTPPermission } from '@pikku/core/http'
+
+addHTTPPermission('/admin/*', { admin: isAdmin })
+```
+
+### Tag-Based (`addPermission`)
+
+```typescript
+import { addPermission } from '.pikku/pikku-types.gen.js'
+
+addPermission('internal', { machine: isMachineAgent })
+```
+
+## Complete Example
+
+```typescript
+// src/permissions.ts
+import { pikkuAuth, pikkuPermission } from '#pikku'
+
+export const isAuthenticated = pikkuAuth(
+  async (_services, session) => !!session
+)
+
+export const isAdmin = pikkuAuth(
+  async (_services, session) => session?.role === 'admin'
+)
+
+export const isOrgMember = pikkuPermission(
+  async ({ db }, { orgId }, { session }) => {
+    return await db.isMember(session?.userId, orgId)
+  }
+)
+
+// src/functions/org.function.ts
+export const deleteOrg = pikkuFunc({
+  func: async ({ db }, { orgId }) => {
+    await db.deleteOrg(orgId)
+  },
+  permissions: {
+    admin: isAdmin,
+    owner: [isAuthenticated, isOrgMember],
+  },
+})
+```
+
+## After Changes
+
+```bash
+pikku tsc        # verify permission checker types are correct
+pikku all        # regenerate if wirings changed
+```