@pikku/cli 0.12.85 → 0.12.88

package/skills/pikku-fabric/SKILL.md

@@ -55,7 +55,7 @@ Fabric apps use SQLite, accessed via Kysely with the libSQL HTTP adapter. NOT Po
 ```typescript
 import { Kysely, CamelCasePlugin } from 'kysely'
 import { LibsqlWebDialect } from '@pikku/kysely-sqlite'
-import type { DB } from './types/db.types.js'
+import type { DB } from '#pikku/db/schema.gen.js'
 
 const databaseUrl = await variables.get('DATABASE_URL')
 let kysely: Kysely<DB>
@@ -75,18 +75,31 @@ Fabric injects `DATABASE_URL` as a variable binding when the stage starts. In lo
 
 ### Migrations
 
-Migrations are plain `.sql` files in `packages/functions/db/migrations/`, numbered sequentially:
+Migrations are plain `.sql` files at the **project root**, in a directory named
+for the engine — `db/sqlite/` for SQLite/libSQL stages, `db/postgres/` for
+Postgres ones. Never `db/migrations/`, and never under `packages/functions/`:
+the deploy pipeline stages `db/<engine>/*.sql` from the root and applies them
+after upload, so a migration anywhere else is silently never run.
 
 ```
-db/migrations/
+db/sqlite/
   0001-init.sql
   0002-add-users.sql
 ```
 
-Run migrations: `pikku db migrate`  
-Generate Kysely types after migrations: `yarn db:types` (uses kysely-codegen)
+Numbers must be consecutive and gap-free, and an applied migration is frozen —
+correct a mistake with a new forward migration, never by editing or renaming one
+that has already run (the recorded hash will no longer match).
 
-**NEVER hand-edit `src/types/db.types.ts`** — it is generated by kysely-codegen.
+Run migrations: `pikku db migrate`. It also regenerates `.pikku/db/schema.gen.ts`
+(Kysely types) and `.pikku/db/zod.gen.ts` — there is no separate types step.
+
+**NEVER hand-edit the generated schema** — write a migration and re-run.
+
+A Better Auth app has a second constraint: the plugins you enable (`admin()`,
+`actor()`, …) each declare columns, and `pikku db migrate` refuses to run while
+the applied schema is missing any of them. `pikku db generate` writes the
+migration that closes the gap.
 
 ### Column conventions
 
@@ -135,28 +148,27 @@ packages/functions/
     services.ts        # pikkuServices factory (singleton)
     middleware.ts      # Shared middleware
     permissions.ts     # Shared permissions
-    types/
-      db.types.ts      # Generated by kysely-codegen — NEVER hand-edit
-  db/
-    migrations/        # Plain .sql files, numbered sequentially
-  .pikku/              # Generated by pikku all — gitignored
+  .pikku/
+    db/schema.gen.ts   # Kysely types, written by `pikku db migrate` — NEVER hand-edit
+apps/app/              # Frontend(s)
+db/sqlite/             # Plain .sql migrations, numbered, gap-free (project root)
 pikku.config.json      # Pikku + deploy config (project root)
-fabric.config.json     # Fabric environment + frontend config (project root)
+pikkufabric.config.json # Fabric project link + frontends (project root)
 ```
 
-## `fabric.config.json`
+## `pikkufabric.config.json`
 
-Declares environments and frontend dev servers:
+Links the repo to a Fabric project and declares its frontends:
 
 ```json
 {
   "projectId": "my-project-id",
   "production": {
-    "branch": "main"
+    "domain": "example.com"
   },
   "frontends": {
     "app": {
-      "cwd": "apps/next-app",
+      "cwd": "apps/app",
       "primary": true,
       "deploy": true,
       "kind": "ssr",
@@ -170,7 +182,11 @@ Declares environments and frontend dev servers:
 }
 ```
 
-- `production.branch`: the git branch that maps to the production stage
+- `projectId`: written by `pikku fabric init` / `link`. Templates ship the
+  `__PROJECT_ID__` placeholder — that is *not* a link, and the CLI treats it as
+  unlinked.
+- `production.domain`: optional custom domain. Production always maps to `main`;
+  without a domain it lives on the platform `*.pikkufabric.app` hostnames.
 - `frontends`: each entry declares a frontend app with its dev command and port
 
 ## RPC is the default transport
@@ -198,6 +214,63 @@ Add `wireHTTP` only when you need a specific REST shape (webhooks, third-party c
 - Every new or changed function must have a real description.
 - If function metadata would show `missing description`, the work is not finished yet.
 
+## Run it locally
+
+A Fabric app is two processes: the pikku API server (`:3000`) and the frontend
+(vite). The starter template's `bun run dev` starts **both** and takes the whole
+session down if either dies — a frontend running against a dead API looks like an
+app bug and is the single most common way to waste an hour here.
+
+```bash
+bun run prebuild   # pikku all — codegen must be current before the server boots
+bun run dev
+```
+
+Then open the app, sign up as a real user, and click through what you built.
+**HTTP 200 is not evidence.** These are client-rendered pages: the server returns
+200 with an empty shell, so a page whose component throws still looks fine to
+curl. Either open it in a browser or drive it headlessly and assert on rendered
+text.
+
+Secrets come from `process.env`, which the CLI populates from a `.env` in the
+working directory. `BETTER_AUTH_SECRET` is required — without it the first
+sign-up fails with `Requested secret not found`, which names no key and points at
+no file. The starter template generates one on first `bun run dev`.
+
+If you are running the two processes yourself rather than through the template's
+script, run `pikku dev` from the **project root** (it resolves `srcDirectories`
+relative to the config, so a nested cwd yields a doubled watch path and no hot
+reload).
+
+## Deploy
+
+```bash
+pikku fabric login              # opens a browser; needs a human, wait for it
+pikku fabric init https://github.com/<owner>/<repo>
+pikku fabric validate           # must pass clean
+pikku fabric deploy plan --production
+pikku fabric deploy apply --production --auto-apply
+```
+
+`apply` confirms before deploying, and with no TTY to ask — CI, an agent shell —
+it refuses rather than hangs. `--auto-apply` supplies that confirmation; drop it
+only when a human is at a real terminal.
+
+`init` adopts a **GitHub** repo, and adoption goes through the Pikku Fabric
+GitHub App — the app has to be installed on the account or org that owns the
+repo, and if it is installed with "selected repositories" this one must be in
+the selection. There is no CLI flag that works around a missing installation:
+`init` returns "Connect the GitHub account '<owner>'". Send the user to install
+it, or create the project in the console instead (which provisions a Fabric-hosted
+git repo you push to) and write the returned `projectId` into
+`pikkufabric.config.json` yourself.
+
+Deploy refuses to run unless the target branch equals its upstream — the guard
+compares `main` against `main@{upstream}`. So the remote you pushed to must be
+the one the branch tracks; a stale `origin` left over from scaffolding blocks
+the deploy with "local HEAD … ≠ remote …" even though your code is pushed.
+`git branch --set-upstream-to=<remote>/main main` before deploying.
+
 ## Versioning
 
 Functions with `expose: true` are versioned via `versions.pikku.json`. When you change a function's input or output schema, you must bump its version number — otherwise `pikku all` will report a breaking change and callers' generated clients become stale.
@@ -221,7 +294,7 @@ These apply in every Fabric app:
 - **No `as any`** — fix types properly.
 - **No generic `Error`** — throw `NotFoundError`, `ConflictError`, `BadRequestError`, `UnauthorizedError` from `@pikku/core/errors`.
 - **No auth checks in function bodies** — use `permissions:` field on the function config with a `pikkuPermission` factory.
-- **No hand-editing `db.types.ts`** — always regenerate with `yarn db:types` after migrations.
+- **No hand-editing `.pikku/db/schema.gen.ts`** — write a migration and re-run `pikku db migrate`.
 - **One runtime unit per file** — never define multiple functions/workflows in a single source file.
 - **Workflow steps don't need manual wiring** — `pikkuSessionlessFunc` step functions in `*.steps.ts` files are auto-discovered by codegen.
 
@@ -235,7 +308,7 @@ pikku fabric validate --json
 
 Fix every `error` and `warn` in the output before continuing. Then:
 
-1. **Replace the database layer**: swap PostgreSQL/MySQL queries for Kysely + libSQL. Convert schema to SQLite-compatible SQL migrations in `db/migrations/`.
+1. **Replace the database layer**: swap PostgreSQL/MySQL queries for Kysely + libSQL. Convert schema to SQLite-compatible SQL migrations in `db/sqlite/`.
 2. **Replace route handlers with pikkuFuncs**: extract business logic into `pikkuFunc`/`pikkuSessionlessFunc`, add `wireHTTP` or `expose: true` for transport.
 3. **Replace DI/IoC with pikkuServices**: move service construction to `createSingletonServices` in `services.ts`.
 4. **Replace `process.env` calls** with `wireVariable`/`wireSecret` + `variables.get()`.

package/skills/pikku-fabric-debug/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: pikku-fabric-debug
+description: 'Debug a deployed Fabric stage from the CLI — read logs, find recent errors, follow a single request end-to-end by traceId, and check request/error/latency metrics. TRIGGER when: a deployed Fabric app is erroring, timing out, or behaving differently than local; the user asks "why is prod failing", "check the logs", "what happened to this request"; or a deploy succeeded but the app misbehaves. DO NOT TRIGGER when: the failure reproduces locally (debug it locally), the deploy itself failed (use pikku-fabric — that is a build/config problem, not a runtime one), or the project is not deployed to Fabric.'
+installGroups: [fabric]
+---
+
+# Debugging a deployed Fabric stage
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Reproduce locally first. If it fails locally too, debug it there — the
+   deployed stage adds cost and latency to every iteration.
+2. Start from `errors`, not `logs`. Errors are already filtered and carry the
+   traceId that unlocks the rest.
+3. Follow one trace end-to-end before forming a theory. A single failing request
+   tells you more than a hundred unrelated log lines.
+4. Fix the source cause and redeploy. Never leave the diagnosis at "it is flaky".
+5. Confirm the fix against the same stage — recheck `errors` for the function.
+
+Every command below requires a logged-in CLI and a linked project. Both fail
+with the exact remediation if not:
+
+```
+Not logged in. Run `pikku fabric login` first.
+No fabric project linked. Run `pikku fabric link` first.
+```
+
+## The loop
+
+**1 — What is broken?**
+
+```bash
+pikku fabric errors -b main                 # branch defaults to main
+pikku fabric errors -b main --function createOrder
+```
+
+Prints a `WHEN | FUNCTION | TRACE | MESSAGE` table. The message is **truncated
+to 100 characters** — treat it as a label, not the full error. The TRACE column
+is the input to the next step.
+
+**2 — What happened in that one request?**
+
+```bash
+pikku fabric trace <traceId> -b main
+pikku fabric trace <traceId> -b main --json
+```
+
+`--branch` is **required** here (no default). Each event prints as:
+
+```
+<timestamp> <scriptName> <wireType>:<wireId> <duration>ms — <error|message|outcome>
+```
+
+This is the whole request across the stage — every unit it touched, in order,
+with per-event durations. The last event before the failure is where to look.
+
+**3 — Is it one request or the whole stage?**
+
+```bash
+pikku fabric metrics -b main                       # last 24h
+pikku fabric metrics -b main --hours 2 --function createOrder
+```
+
+Rows are `reqs= err= (rate%) avg= min= max=` per bucket. A single bad request
+with a healthy error rate is a data problem; a climbing error rate is a
+deployment or dependency problem. `--json` additionally returns a `wireTypes`
+breakdown (requests per http/queue/scheduler/…) that the table output omits.
+
+**4 — Wider context around the failure**
+
+```bash
+pikku fabric logs -b main
+pikku fabric logs -b main --level warn
+pikku fabric logs -b main -f              # follow
+```
+
+`--branch` is **required** — `logs` throws `Specify --branch <branch-name>.`
+without it, even though the flag reads as optional.
+
+**5 — Is the running code the code you think it is?**
+
+```bash
+pikku fabric status     # active + in-flight deployment, per stage, with gitSha
+```
+
+Check this *before* deep-diving. A stage still serving an older `gitSha`, or a
+deploy stuck in flight, explains a whole class of "my fix did nothing".
+
+## Known gaps — do not misread these as bugs in your app
+
+- **`pikku fabric logs --since` and `--deployment` are accepted and ignored.**
+  They are declared as options but the command never reads them, so
+  `--since 15m` silently returns the same default window as no flag at all. Do
+  not conclude "nothing happened in the last 15 minutes" from it. Narrow by
+  `--level`, or by `--function` via `errors`, instead.
+- **`--follow` is a 2-second client-side poll, not a server stream.** It
+  dedups against what it already printed, so it behaves like `tail -f`, but new
+  entries can appear up to ~2s late and it holds the process open until killed.
+
+## What NOT to do
+
+- **Do not SSH anywhere or query the telemetry backend directly.** These
+  commands are the supported surface; anything lower-level is Fabric-internal
+  and will not exist for your project.
+- **Do not debug by redeploying with added `console.log`s.** Get the traceId,
+  read the trace. A deploy cycle per hypothesis is the slow path.
+- **Do not read the truncated `errors` message as the full error.** Always
+  confirm against `trace` before changing code.
+- **Do not treat an empty `errors` table as "the app is fine"** — a request that
+  returns a wrong 200 logs nothing. Check `metrics` for the outcome mix.

package/skills/pikku-permissions/SKILL.md

@@ -49,20 +49,36 @@ export const deleteBook = pikkuFunc({
 
 ### `pikkuAuth(fn)` — Session-Only Checks
 
-Use for checks that only need the session — no request data required.
+Use for checks that read the session but need no request data — and that assert
+something **beyond** merely having a session (a flag, a tier, a claim).
 
 ```typescript
 import { pikkuAuth } from '#pikku'
 
-export const isAuthenticated = pikkuAuth(
-  async (_services, session) => !!session
+// Good: a real gate on the session's contents, not just its existence.
+export const isVerified = pikkuAuth(
+  async (_services, session) => !!session?.emailVerified
 )
+```
 
-export const isAdmin = pikkuAuth(
-  async (_services, session) => session?.role === 'admin'
-)
+**Do NOT write an "is signed in" permission.** A checker that just returns
+`!!session` is not authorization — it re-checks authentication, which the
+function already enforces. A function that needs a signed-in user sets
+`auth: true` (the default for `pikkuFunc`); it does not also carry a
+`permissions: { signedIn }`.
+
+```typescript
+// WRONG — redundant with auth: true; adds a permission that gates nothing.
+export const isSignedIn = pikkuAuth(async (_s, session) => !!session)
+pikkuFunc({ auth: true, permissions: { signedIn: isSignedIn }, /* ... */ })
+
+// RIGHT — auth: true already requires the session; permissions are for capability.
+pikkuFunc({ auth: true, /* ... */ })
 ```
 
+A permission answers "*may this user do this?*" (role, ownership, tier) — never
+"*is there a session?*".
+
 ### `pikkuPermission(fn)` — Data-Aware Checks
 
 Use when authorization depends on the actual request data (e.g., resource ownership).
@@ -88,11 +104,11 @@ export const hasBookAccess = pikkuPermission(
 
 ```typescript
 permissions: {
-  admin: isAdmin,                              // OR: admins can access
+  verified: isVerified,                        // OR: verified users can access
   owner: isBookOwner,                          // OR: owners can access
   reviewer: [isAuthenticated, hasBookAccess],  // AND: both must pass
 }
-// Logic: admin OR owner OR (isAuthenticated AND hasBookAccess)
+// Logic: verified OR owner OR (isAuthenticated AND hasBookAccess)
 ```
 
 Groups are OR'd. Entries within a group array are AND'd.
@@ -107,7 +123,7 @@ export const deleteBook = pikkuFunc({
     await db.deleteBook(bookId)
   },
   permissions: {
-    admin: isAdmin,
+    verified: isVerified,
     owner: isBookOwner,
   },
 })
@@ -146,8 +162,8 @@ export const isAuthenticated = pikkuAuth(
   async (_services, session) => !!session
 )
 
-export const isAdmin = pikkuAuth(
-  async (_services, session) => session?.role === 'admin'
+export const isVerified = pikkuAuth(
+  async (_services, session) => !!session?.emailVerified
 )
 
 export const isOrgMember = pikkuPermission(
@@ -162,7 +178,7 @@ export const deleteOrg = pikkuFunc({
     await db.deleteOrg(orgId)
   },
   permissions: {
-    admin: isAdmin,
+    verified: isVerified,
     owner: [isAuthenticated, isOrgMember],
   },
 })

package/skills/pikku-react/SKILL.md

@@ -36,15 +36,44 @@ import {
 Five exports. `usePikkuRealtime` is only valid when you wired a
 `PikkuRealtime` class via `createPikku` — see step 3 below.
 
+## Resolving the server URL
+
+Every client (`createPikku`, realtime, the auth client) resolves its base
+through one shared helper in `src/lib/env.ts`. Write this once:
+
+```ts
+// Endpoints come from env, never hardcoded.
+export function apiUrl(): string {
+  // SSR: the client hooks only run in the browser, so a placeholder is fine.
+  if (import.meta.env.SSR) {
+    return import.meta.env.VITE_API_URL ?? '/__api'
+  }
+  return import.meta.env.VITE_API_URL ?? `${window.location.origin}/api`
+}
+```
+
+**Never fall back to `http://localhost:3000`.** `import.meta.env.VITE_API_URL`
+is substituted by Vite at *build* time, so any deploy that supplies the URL as
+a *runtime* env var or platform binding leaves it `undefined` in the shipped
+bundle — the fallback is then the only branch that ever runs in the browser. A
+localhost fallback means every request from a deployed app goes to the user's
+own machine. `origin + '/api'` is same-origin, needs no build-time knowledge of
+the domain, and is correct wherever the app is served from.
+
+For local dev, set `VITE_API_URL`, or proxy `/api` → your backend in
+`vite.config.ts` under `server.proxy`. One `/api` entry also covers
+`/api/auth/*`; only add more entries for root-level routes outside `/api`.
+
 ## Setup at the app root
 
 ```tsx
 import { createPikku, PikkuProvider } from '@pikku/react'
 import { PikkuFetch } from './pikku/pikku-fetch.gen'
 import { PikkuRPC } from './pikku/pikku-rpc.gen'
+import { apiUrl } from './lib/env'
 
 const pikku = createPikku(PikkuFetch, PikkuRPC, {
-  serverUrl: import.meta.env.VITE_API_URL ?? 'http://localhost:3000',
+  serverUrl: apiUrl(),
 })
 
 createRoot(document.getElementById('root')!).render(
@@ -62,7 +91,7 @@ the `PikkuRealtime` class as the third argument and the instance gets a
 import { PikkuRealtime } from './pikku/realtime.gen'
 
 const pikku = createPikku(PikkuFetch, PikkuRPC, PikkuRealtime, {
-  serverUrl: import.meta.env.VITE_API_URL ?? 'http://localhost:3000',
+  serverUrl: apiUrl(),
 })
 // pikku.fetch / pikku.rpc / pikku.realtime — all share the same fetch
 // (server URL + auth configured once).
@@ -159,7 +188,7 @@ or set headers on the fetch instance after creation. Common pattern:
 
 ```tsx
 const pikku = createPikku(PikkuFetch, PikkuRPC, {
-  serverUrl: '...',
+  serverUrl: apiUrl(),
   fetchOptions: {
     onRequest: (req) => {
       const token = localStorage.getItem('token')

package/skills/pikku-react-query/SKILL.md

@@ -59,9 +59,11 @@ import { PikkuProvider, createPikku } from '@pikku/react'
 import { PikkuFetch } from './pikku/pikku-fetch.gen'
 import { PikkuRPC } from './pikku/pikku-rpc.gen'
 
+import { apiUrl } from './lib/env'
+
 const queryClient = new QueryClient()
 const pikku = createPikku(PikkuFetch, PikkuRPC, {
-  serverUrl: import.meta.env.VITE_API_URL ?? 'http://localhost:3000',
+  serverUrl: apiUrl(),
 })
 
 <QueryClientProvider client={queryClient}>
@@ -75,6 +77,41 @@ The two generated files come from `pikku.config.json`'s
 `clientFiles.fetchFile` and `clientFiles.rpcWiringsFile`. Hooks live in
 the file at `clientFiles.reactQueryFile` (typically `api.gen.ts`).
 
+`apiUrl()` is the shared server-URL helper — see **pikku-react**. Never
+inline `?? 'http://localhost:3000'`: a deploy that supplies the URL as a
+runtime binding leaves `import.meta.env.VITE_API_URL` undefined in the
+bundle, so the fallback is the branch that actually runs.
+
+## TanStack Start (SSR)
+
+Under Start the provider mounts in `routes/__root.tsx` rather than
+`main.tsx`, and the same module is evaluated on the server. Three things
+differ:
+
+1. **`apiUrl()` must have an SSR branch.** `window` is undefined during
+   render; return the build-time var or a placeholder (the client hooks
+   only fire in the browser).
+2. **Build auth clients lazily.** Better Auth validates its baseURL with
+   `new URL(...)` at construction, so a module-scope `createAuthClient`
+   crashes SSR on the placeholder. Memoize it behind a getter:
+
+   ```ts
+   let _authClient: ReturnType<typeof createAuthClient> | undefined
+   export const authClient = () =>
+     (_authClient ??= createAuthClient({ baseURL: `${apiUrl()}/auth` }))
+   ```
+
+3. **The auth baseURL needs the `/auth` suffix.** Better Auth only
+   appends its default `/api/auth` when the baseURL carries no path.
+   `apiUrl()` already ends in `/api`, so a bare `apiUrl()` leaves the
+   client calling `/api/get-session` and 404ing.
+
+Server functions that need typed RPC access use the generated shim:
+
+```bash
+pikku tanstack-start   # emits the makeApi server-function shim
+```
+
 ## The hooks
 
 All hooks are imported from your generated `api.gen.ts`:

package/skills/pikku-realtime/SKILL.md

@@ -160,7 +160,7 @@ const pikku = createPikku(
   PikkuFetch,
   PikkuRPC,
   PikkuRealtime, // pass the realtime class as the third arg
-  { serverUrl: import.meta.env.VITE_API_URL ?? 'http://localhost:3000' }
+  { serverUrl: apiUrl() } // shared env helper — see pikku-react
 )
 // pikku.fetch / pikku.rpc / pikku.realtime — all share the same fetch.
 

package/skills/pikku-security/SKILL.md

@@ -36,7 +36,7 @@ const login = pikkuFunc({
   auth: false,
   func: async ({ jwt, db }, { email, password }, { setSession }) => {
     const user = await db.verifyCredentials(email, password)
-    setSession({ userId: user.id, role: user.role })
+    setSession({ userId: user.id })
     return { token: jwt.sign({ userId: user.id }) }
   },
 })
@@ -80,7 +80,7 @@ addHTTPMiddleware('*', [authAPIKey({ source: 'all' })])
 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 isVerified = pikkuAuth(async (_services, session) => !!session?.emailVerified)
 
 // wirings/auth.wiring.ts
 import { authCookie } from '@pikku/core/middleware'
@@ -95,7 +95,7 @@ export const login = pikkuFunc({
   auth: false,
   func: async ({ jwt, db }, { email, password }, { setSession }) => {
     const user = await db.verifyCredentials(email, password)
-    setSession({ userId: user.id, role: user.role })
+    setSession({ userId: user.id })
     return { token: jwt.sign({ userId: user.id }) }
   },
 })

package/skills/pikku-template-clone/SKILL.md

@@ -2,6 +2,7 @@
 name: pikku-template-clone
 description: 'Standard cleanup to run right after a Pikku template is cloned or scaffolded into a new project. TRIGGER when: a Pikku template was just cloned/scaffolded (via `npm create pikku`, `git clone <template>`, or the user says "I cloned the kanban template / starter / template"), or the working tree still looks like an untouched template (template README, placeholder `@project/*` name in package.json). DO NOT TRIGGER when: working in an established project mid-feature, or editing the template repo itself.'
 allowed-tools: Bash(git status *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *)
+installGroups: [core]
 ---
 
 # Pikku Template Post-Clone Cleanup

package/cli.schema.json

@@ -1 +0,0 @@
-{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"configFile":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"wires":{"type":"array","items":{"type":"string"}},"excludeWires":{"type":"array","items":{"type":"string"}},"userSessionType":{"type":"string"},"singletonServicesFactoryType":{"type":"string"},"wireServicesFactoryType":{"type":"string"},"outDir":{"type":"string"},"schemaDirectory":{"type":"string"},"typesDeclarationFile":{"type":"string"},"functionsFile":{"type":"string"},"functionsMetaFile":{"type":"string"},"functionsMetaJsonFile":{"type":"string"},"functionTypesFile":{"type":"string"},"httpWiringsFile":{"type":"string"},"httpWiringMetaFile":{"type":"string"},"httpWiringMetaJsonFile":{"type":"string"},"httpContractsMetaJsonFile":{"type":"string"},"httpContractsMetaFile":{"type":"string"},"httpMapDeclarationFile":{"type":"string"},"httpTypesFile":{"type":"string"},"gatewaysWiringFile":{"type":"string"},"gatewaysWiringMetaFile":{"type":"string"},"gatewaysWiringMetaJsonFile":{"type":"string"},"channelsWiringFile":{"type":"string"},"channelsWiringMetaFile":{"type":"string"},"channelsWiringMetaJsonFile":{"type":"string"},"channelContractsMetaJsonFile":{"type":"string"},"channelContractsMetaFile":{"type":"string"},"channelsMapDeclarationFile":{"type":"string"},"channelsTypesFile":{"type":"string"},"rpcInternalWiringMetaFile":{"type":"string"},"rpcInternalWiringMetaJsonFile":{"type":"string"},"rpcInternalMapDeclarationFile":{"type":"string"},"rpcMapDeclarationFile":{"type":"string"},"rpcRemoteMapDeclarationFile":{"type":"string"},"remoteRpcWorkersFile":{"type":"string"},"graphWiringsFile":{"type":"string"},"webhookWorkersFile":{"type":"string"},"publicRpcFile":{"type":"string"},"publicAgentFile":{"type":"string"},"consoleFunctionsFile":{"type":"string"},"scenariosFunctionsFile":{"type":"string"},"workflowRoutesFile":{"type":"string"},"eventsChannelFile":{"type":"string"},"triggersTypesFile":{"type":"string"},"triggersWiringFile":{"type":"string"},"triggersWiringMetaFile":{"type":"string"},"triggersWiringMetaJsonFile":{"type":"string"},"triggerSourcesMetaFile":{"type":"string"},"triggerSourcesMetaJsonFile":{"type":"string"},"schedulersWiringFile":{"type":"string"},"schedulersWiringMetaFile":{"type":"string"},"schedulersWiringMetaJsonFile":{"type":"string"},"schedulersTypesFile":{"type":"string"},"queueWorkersWiringFile":{"type":"string"},"queueWorkersWiringMetaFile":{"type":"string"},"queueWorkersWiringMetaJsonFile":{"type":"string"},"queueMapDeclarationFile":{"type":"string"},"queueTypesFile":{"type":"string"},"workflowsWiringFile":{"type":"string"},"workflowsWiringMetaFile":{"type":"string"},"workflowsWorkersFile":{"type":"string"},"workflowMapDeclarationFile":{"type":"string"},"workflowTypesFile":{"type":"string"},"workflowMetaDir":{"type":"string"},"scenarioActorsFile":{"type":"string"},"mcpWiringsFile":{"type":"string"},"mcpWiringsMetaFile":{"type":"string"},"mcpWiringsMetaJsonFile":{"type":"string"},"mcpTypesFile":{"type":"string"},"mcpJsonFile":{"type":"string"},"agentWiringsFile":{"type":"string"},"agentWiringMetaFile":{"type":"string"},"agentWiringMetaJsonFile":{"type":"string"},"agentTypesFile":{"type":"string"},"agentMapDeclarationFile":{"type":"string"},"cliWiringsFile":{"type":"string"},"cliWiringMetaFile":{"type":"string"},"cliWiringMetaJsonFile":{"type":"string"},"cliContractsMetaJsonFile":{"type":"string"},"cliContractsMetaFile":{"type":"string"},"cliBootstrapFile":{"type":"string"},"cliTypesFile":{"type":"string"},"servicesFile":{"type":"string"},"middlewareFile":{"type":"string"},"middlewareGroupsMetaJsonFile":{"type":"string"},"permissionsFile":{"type":"string"},"permissionsGroupsMetaJsonFile":{"type":"string"},"bootstrapFile":{"type":"string"},"packageFile":{"type":"string"},"addonTypesFile":{"type":"string"},"nodeTypesFile":{"type":"string"},"secretTypesFile":{"type":"string"},"secretsFile":{"type":"string"},"secretsMetaJsonFile":{"type":"string"},"credentialsFile":{"type":"string"},"credentialsMetaJsonFile":{"type":"string"},"scopeTypesFile":{"type":"string"},"scopesFile":{"type":"string"},"scopesMetaJsonFile":{"type":"string"},"variableTypesFile":{"type":"string"},"variablesFile":{"type":"string"},"variablesMetaJsonFile":{"type":"string"},"$schema":{"type":"string"},"extends":{"type":"string"},"rootDir":{"type":"string"},"runtimeDir":{"type":"string","description":"Runtime artifacts directory (dev.db, content, tmp). Resolved relative to rootDir. Defaults to <rootDir>/.pikku-runtime."},"srcDirectories":{"type":"array","items":{"type":"string"}},"ignoreFiles":{"type":"array","items":{"type":"string"}},"packageMappings":{"type":"object","additionalProperties":{"type":"string"}},"addon":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"categories":{"type":"array","items":{"type":"string"}},"icon":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"serverlessIncompatible":{"type":"array","items":{"type":"string"}},"openapi":{"type":"object","properties":{"version":{"type":"string"},"hash":{"type":"string"}},"required":["version","hash"],"additionalProperties":false}},"additionalProperties":false}]},"addonName":{"type":"string"},"configDir":{"type":"string"},"tsconfig":{"type":"string"},"clientFiles":{"type":"object","properties":{"fetchFile":{"type":"string"},"websocketFile":{"type":"string"},"rpcWiringsFile":{"type":"string"},"reactQueryFile":{"type":"string"},"realtimeFile":{"type":"string"},"realtimeEventHubTopicsImport":{"type":"string","description":"Optional import for the EventHubTopics type so the realtime client is fully typed. Format: `<path>#<TypeName>` resolved relative to `realtimeFile`. Example: `../types/eventhub-topics.js#EventHubTopics`. If unset, the generated client treats topics as `Record<string, unknown>`."},"queueWiringsFile":{"type":"string"},"mcpJsonFile":{"type":"string"},"nextBackendFile":{"type":"string"},"nextHTTPFile":{"type":"string"},"nextBackendTransport":{"type":"string","enum":["local","worker-rpc","http"],"description":"Transport used by the generated nextBackendFile wrapper.\n- `'local'` (default): function code is loaded in-process via bootstrap +   createSingletonServices. Required for Node/dev runs.\n- `'worker-rpc'`: SSR dispatches every call through an injected `Fetcher`   ({ fetch(req): Promise<Response> }). Function code is NOT bundled into   the SSR worker. Pair with `nextBackendFetcherImport` to point at your   resolver module.\n- `'http'`: SSR dispatches every call through the generated `PikkuFetch`   client. Use this when your Next app should call a separately running   local/server API instead of importing function code in-process."},"nextBackendFetcherImport":{"type":"string","description":"Module that exports a `fetcher: Fetcher` (or default export) used by the worker-RPC variant of the next backend wrapper. Resolved relative to `nextBackendFile`. Required when `nextBackendTransport === 'worker-rpc'`."},"startServerFnsFile":{"type":"string","description":"Emit a TanStack Start server-function shim into this file. The shim exports `makeApi(): PikkuRPC` — a typed caller over the generated RPC map for use in Start loaders, actions and components. It reads the API base URL from `import.meta.env.VITE_API_URL` (throws if unset). Requires `rpcWiringsFile` (where the `PikkuRPC` class is generated)."}},"additionalProperties":false},"emailTemplatesDir":{"type":"string","description":"Directory containing email templates, locales, partials, and theme.json."},"authFile":{"type":"string","description":"Path to write the generated Better Auth wiring file (auth.gen.ts). Must be within srcDirectories so wireSecret calls are picked up by the inspector. Example: \"src/auth.gen.ts\""},"authTypesFile":{"type":"string","description":"Path to write the generated typed `pikkuBetterAuth` re-export (auth.types.ts). Defaults to `{outDir}/auth/auth.types.ts`. Re-exported from `#pikku` so user code can `import { pikkuBetterAuth } from '#pikku'` with project-typed services."},"authMetaJsonFile":{"type":"string","description":"Path to write the generated Better Auth metadata (auth-meta.gen.json) — the enabled social providers and plugins the console SSO page reads via getAuthProviders. Defaults to `{outDir}/auth/pikku-auth-meta.gen.json`."},"openAPI":{"type":"object","properties":{"outputFile":{"type":"string"},"additionalInfo":{"$ref":"#/definitions/OpenAPISpecInfo"}},"required":["outputFile","additionalInfo"],"additionalProperties":false},"schema":{"type":"object","properties":{"additionalProperties":{"type":"boolean"},"supportsImportAttributes":{"type":"boolean"}},"additionalProperties":false},"db":{"type":"object","properties":{"engine":{"type":"string","enum":["sqlite","postgres"]},"pgVersion":{"type":"number"}},"additionalProperties":false},"cli":{"type":"object","properties":{"entrypoints":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","properties":{"type":{"type":"string","const":"local"},"path":{"type":"string"}},"required":["type","path"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"channel"},"name":{"type":"string"},"route":{"type":"string"},"wirePath":{"type":"string"},"path":{"type":"string"}},"required":["type","wirePath"],"additionalProperties":false},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"type":{"type":"string","const":"local"},"path":{"type":"string"}},"required":["type","path"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"channel"},"name":{"type":"string"},"route":{"type":"string"},"wirePath":{"type":"string"},"path":{"type":"string"}},"required":["type","wirePath"],"additionalProperties":false}]}}]}}},"additionalProperties":false},"workflows":{"type":"object","properties":{"orchestratorQueue":{"type":"string"},"workerQueue":{"type":"string"}},"additionalProperties":false},"scenarios":{"type":"object","properties":{"actors":{"type":"object","additionalProperties":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"jobTitle":{"type":"string"},"personality":{"type":"string"}},"required":["email"],"additionalProperties":false},"description":"Global scenario actor registry — any scenario can impersonate any actor"},"environments":{"type":"object","additionalProperties":{"type":"object","properties":{"apiUrl":{"type":"string"},"signInPath":{"type":"string","description":"Actor sign-in path under apiUrl. Default: /auth/sign-in/actor"},"rpcPath":{"type":"string","description":"Exposed-RPC prefix under apiUrl. Default: /rpc"}},"required":["apiUrl"],"additionalProperties":false},"description":"Environments `pikku scenario run <environment>` can target; the actor secret comes from SCENARIO_ACTOR_SECRET, never config"}},"additionalProperties":false},"scaffold":{"type":"object","properties":{"addonDir":{"type":"string"},"functionDir":{"type":"string"},"wiringDir":{"type":"string"},"middlewareDir":{"type":"string"},"permissionDir":{"type":"string"},"pikkuDir":{"type":"string"},"graph":{"type":"boolean","description":"Wire the pikku addon-graph package so pikkuWorkflowGraph can reference its native transforms like graph:editFields."},"rpc":{"$ref":"#/definitions/PikkuScaffoldFeature"},"console":{"$ref":"#/definitions/PikkuScaffoldFeature"},"scenarios":{"$ref":"#/definitions/PikkuScaffoldFeature"},"agent":{"$ref":"#/definitions/PikkuScaffoldFeature"},"workflow":{"$ref":"#/definitions/PikkuScaffoldFeature"},"events":{"$ref":"#/definitions/PikkuScaffoldFeature"},"remoteRpc":{"$ref":"#/definitions/PikkuScaffoldFeature"},"webhook":{"type":"boolean","description":"The outgoing webhook delivery worker exposes no endpoint of its own, so it has no auth dimension — it is on or off."}},"additionalProperties":false},"addons":{"type":"object","properties":{"addonDir":{"type":"string"}},"additionalProperties":false,"description":"Community-registry addons installed via `pikku fabric addon add`. The source is copied into the project shadcn-style; each lands in `<addonDir>/<name>/` and the dir is registered as a yarn workspace so `wireAddon({ package })` resolves it by name. `addonDir` defaults to `addons` (top-level, outside the app's TS scan). Install provenance is tracked in pikku-addons.json."},"tests":{"type":"object","properties":{"outputDir":{"type":"string"}},"additionalProperties":false},"forceRequiredServices":{"type":"array","items":{"type":"string"}},"schemasFromTypes":{"type":"array","items":{"type":"string"}},"stateOutput":{"type":"string"},"stateInput":{"type":"string"},"verboseMeta":{"type":"boolean"},"security":{"type":"boolean","description":"Run the data-classification security lint (scans function return types for Private/Pii/Secret leaks). Off by default — it forces expensive return-type inference on every function and is not part of codegen. Enable here to always run it, or per-invocation via `pikku all --security`. Pair with `failOnError` to gate a build/CI on leaks."},"tsc":{"type":"boolean","description":"After codegen, run a real `tsc --noEmit` over the project's tsconfig and fail on type errors. `tsc` prints full diagnostics with code frames; `tscSummary` prints a compact one-line-per-error render (no code frames, capped) that's cheap for AI agents / CI logs. Off by default; enable per invocation via `pikku all --tsc` / `--tsc-summary`."},"tscSummary":{"type":"boolean"},"diff":{"type":"boolean","description":"After a successful codegen run, emit a structural diff of the generated `.pikku` meta (functions/wirings/workflows/emails added/removed/changed vs the state before this run) as a `PIKKU_DIFF <json>` line on stdout. Only emitted on exit 0. Off by default; enable per invocation via `pikku all --diff`. Consumed by the sandbox \"what changed\" build card."},"lint":{"type":"object","properties":{"servicesNotDestructured":{"type":"string","enum":["off","warn","error"]},"wiresNotDestructured":{"type":"string","enum":["off","warn","error"]},"functionDynamicImport":{"type":"string","enum":["off","warn","error"]}},"additionalProperties":false},"addonMetaJsonFile":{"type":"string"},"globalHTTPPrefix":{"type":"string"},"binary":{"type":"object","properties":{"entrypoint":{"type":"string"},"output":{"type":"string"},"targets":{"type":"array","items":{"type":"string"}}},"required":["entrypoint","output"],"additionalProperties":false},"deploy":{"type":"object","properties":{"providers":{"type":"object","additionalProperties":{"type":"string"}},"defaultProvider":{"type":"string"},"serverlessIncompatible":{"type":"array","items":{"type":"string"}},"defaultTarget":{"type":"string","enum":["serverless","server"],"description":"Default deploy target for functions that don't declare an explicit `deploy` flag and don't use a serverless-incompatible service. Defaults to 'serverless'."}},"required":["providers"],"additionalProperties":false},"namedFilters":{"type":"object","additionalProperties":{"$ref":"#/definitions/InspectorFilters"},"description":"Named filter presets keyed by name, used via CLI --filter <name>."},"filters":{"$ref":"#/definitions/InspectorFilters"}},"required":["addonTypesFile","agentMapDeclarationFile","agentTypesFile","agentWiringMetaFile","agentWiringMetaJsonFile","agentWiringsFile","bootstrapFile","channelContractsMetaFile","channelContractsMetaJsonFile","channelsMapDeclarationFile","channelsTypesFile","channelsWiringFile","channelsWiringMetaFile","channelsWiringMetaJsonFile","cliBootstrapFile","cliContractsMetaFile","cliContractsMetaJsonFile","cliTypesFile","cliWiringMetaFile","cliWiringMetaJsonFile","cliWiringsFile","configDir","consoleFunctionsFile","credentialsFile","credentialsMetaJsonFile","eventsChannelFile","filters","functionTypesFile","functionsFile","functionsMetaFile","functionsMetaJsonFile","gatewaysWiringFile","gatewaysWiringMetaFile","gatewaysWiringMetaJsonFile","httpContractsMetaFile","httpContractsMetaJsonFile","httpMapDeclarationFile","httpTypesFile","httpWiringMetaFile","httpWiringMetaJsonFile","httpWiringsFile","mcpJsonFile","mcpTypesFile","mcpWiringsFile","mcpWiringsMetaFile","mcpWiringsMetaJsonFile","middlewareFile","middlewareGroupsMetaJsonFile","nodeTypesFile","outDir","packageFile","packageMappings","permissionsFile","permissionsGroupsMetaJsonFile","publicAgentFile","publicRpcFile","queueMapDeclarationFile","queueTypesFile","queueWorkersWiringFile","queueWorkersWiringMetaFile","queueWorkersWiringMetaJsonFile","rootDir","rpcInternalMapDeclarationFile","rpcInternalWiringMetaFile","rpcInternalWiringMetaJsonFile","rpcMapDeclarationFile","rpcRemoteMapDeclarationFile","scenarioActorsFile","scenariosFunctionsFile","schedulersTypesFile","schedulersWiringFile","schedulersWiringMetaFile","schedulersWiringMetaJsonFile","schemaDirectory","scopeTypesFile","scopesFile","scopesMetaJsonFile","secretTypesFile","secretsFile","secretsMetaJsonFile","servicesFile","srcDirectories","triggerSourcesMetaFile","triggerSourcesMetaJsonFile","triggersTypesFile","triggersWiringFile","triggersWiringMetaFile","triggersWiringMetaJsonFile","tsconfig","typesDeclarationFile","variableTypesFile","variablesFile","variablesMetaJsonFile","workflowMapDeclarationFile","workflowMetaDir","workflowRoutesFile","workflowTypesFile","workflowsWiringFile","workflowsWiringMetaFile","workflowsWorkersFile"],"definitions":{"OpenAPISpecInfo":{"type":"object","properties":{"info":{"type":"object","properties":{"title":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"termsOfService":{"type":"string"},"contact":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false},"license":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name"],"additionalProperties":false}},"required":["title","version","description"],"additionalProperties":false},"servers":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"}},"required":["url"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name"],"additionalProperties":false}},"externalDocs":{"type":"object","properties":{"description":{"type":"string"},"url":{"type":"string"}},"required":["url"],"additionalProperties":false},"securitySchemes":{"type":"object"},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{}}}}},"required":["info","servers"],"additionalProperties":false},"PikkuScaffoldFeature":{"type":["string","boolean"],"enum":["auth","no-auth",false]},"InspectorFilters":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"wires":{"type":"array","items":{"type":"string"}},"directories":{"type":"array","items":{"type":"string"}},"httpRoutes":{"type":"array","items":{"type":"string"}},"httpMethods":{"type":"array","items":{"type":"string"}},"excludeNames":{"type":"array","items":{"type":"string"}},"excludeTags":{"type":"array","items":{"type":"string"}},"excludeWires":{"type":"array","items":{"type":"string"}},"excludeDirectories":{"type":"array","items":{"type":"string"}},"excludeHttpRoutes":{"type":"array","items":{"type":"string"}},"excludeHttpMethods":{"type":"array","items":{"type":"string"}},"target":{"type":"array","items":{"type":"string","enum":["serverless","server"]}},"excludeTarget":{"type":"array","items":{"type":"string","enum":["serverless","server"]}},"serverlessIncompatible":{"type":"array","items":{"type":"string"}},"defaultTarget":{"type":"string","enum":["serverless","server"]}},"additionalProperties":false}}}