@pikku/cli 0.12.86 → 0.12.89

package/dist/src/fabric/functions/validate.function.js

@@ -605,8 +605,12 @@ export async function runValidate(startDir = process.cwd()) {
                 const pikkuGenDir = join(fnDir, '.pikku');
                 const typesGenTs = join(pikkuGenDir, 'pikku-types.gen.ts');
                 const typesGenJs = join(pikkuGenDir, 'pikku-types.gen.js');
+                // A warning, not an error: the wrapper is gitignored and recreated by
+                // the sandbox entrypoint and `fabric smoke`, so a freshly cloned or
+                // freshly scaffolded project never has it. As an error, "validate must
+                // pass clean" was unachievable from a clean checkout.
                 if (existsSync(typesGenTs) && !existsSync(typesGenJs)) {
-                    e('pikku-types-js-wrapper-missing', 'packages/functions/.pikku/pikku-types.gen.js is missing — the sandbox runs pikku dev via bare Node.js, which cannot load .ts files; without the .js wrapper it crashes with "Cannot find module \'#pikku/pikku-types.gen.js\'" on every restart', typesGenTs, lines('Create packages/functions/.pikku/pikku-types.gen.js:', "  import './pikku-types.gen.ts';", "  export * from './pikku-types.gen.ts';", 'Or run `pikku fabric smoke` to test the full boot locally (it creates the wrappers).', 'This file is gitignored — it must be recreated after every `pikku all` run.'));
+                    w('pikku-types-js-wrapper-missing', 'packages/functions/.pikku/pikku-types.gen.js is missing — the sandbox runs pikku dev via bare Node.js, which cannot load .ts files; without the .js wrapper it crashes with "Cannot find module \'#pikku/pikku-types.gen.js\'" on every restart', typesGenTs, lines('Create packages/functions/.pikku/pikku-types.gen.js:', "  import './pikku-types.gen.ts';", "  export * from './pikku-types.gen.ts';", 'Or run `pikku fabric smoke` to test the full boot locally (it creates the wrappers).', 'This file is gitignored — it must be recreated after every `pikku all` run.'));
                 }
             }
             const fnAllDeps = {
@@ -655,7 +659,13 @@ export async function runValidate(startDir = process.cwd()) {
             const usesLibsql = servicesText.includes('@pikku/kysely-sqlite') ||
                 servicesText.includes('LibsqlWebDialect');
             const usesProcessEnv = /\bprocess\.env\.[A-Z_]/.test(servicesText);
-            if (dbEngine !== 'postgres' && usesKysely && !usesLibsql) {
+            // Only a services.ts that BUILDS its own client can pick the wrong
+            // dialect. The starter template takes kysely from injection (pikku dev
+            // supplies node:sqlite, the Worker supplies libsql) and constructs
+            // nothing — flagging it told every fresh scaffold to import a dialect it
+            // must not use.
+            const constructsKysely = /new\s+Kysely\s*[<(]/.test(servicesText);
+            if (dbEngine !== 'postgres' && usesKysely && constructsKysely && !usesLibsql) {
                 e('services-wrong-db-adapter', 'services.ts uses Kysely but not LibsqlWebDialect — Fabric injects a Turso/libSQL DATABASE_URL at runtime, not a PostgreSQL URL', servicesPath, 'Import LibsqlWebDialect from @pikku/kysely-sqlite and replace the dialect: new Kysely({ dialect: new LibsqlWebDialect({ url: databaseUrl }) })');
             }
             if (usesProcessEnv) {

package/dist/src/fabric/lib/config.d.ts

@@ -42,6 +42,14 @@ export declare function findProjectConfig(startDir?: string): Promise<{
     path: string;
     config: ProjectConfig;
 } | null>;
+/**
+ * Templates ship `pikkufabric.config.json` with a `__PROJECT_ID__` placeholder
+ * so the file's shape is visible before the repo is linked. A placeholder is
+ * not a link: without this, `fabric init` on a fresh scaffold reports
+ * "Already linked: __PROJECT_ID__" and every other command sends the
+ * placeholder to the API as if it were a real id.
+ */
+export declare function isLinkedProjectId(projectId?: string | null): boolean;
 export declare function writeProjectConfig(cwd: string, config: ProjectConfig): Promise<string>;
 export declare function readAuthFile(): Promise<AuthFile>;
 export declare function writeAuthFile(file: AuthFile): Promise<void>;

package/dist/src/fabric/lib/config.js

@@ -19,6 +19,18 @@ export async function findProjectConfig(startDir = process.cwd()) {
         dir = parent;
     }
 }
+/**
+ * Templates ship `pikkufabric.config.json` with a `__PROJECT_ID__` placeholder
+ * so the file's shape is visible before the repo is linked. A placeholder is
+ * not a link: without this, `fabric init` on a fresh scaffold reports
+ * "Already linked: __PROJECT_ID__" and every other command sends the
+ * placeholder to the API as if it were a real id.
+ */
+export function isLinkedProjectId(projectId) {
+    if (!projectId)
+        return false;
+    return !/^__.*__$/.test(projectId);
+}
 export async function writeProjectConfig(cwd, config) {
     const path = join(cwd, projectConfigName);
     await mkdir(dirname(path), { recursive: true });
@@ -57,6 +69,8 @@ export async function resolveApiContext(opts = {}) {
     return {
         apiUrl,
         token: auth.tokens[apiUrl] ?? null,
-        projectId: projectFile?.config.projectId ?? null,
+        projectId: isLinkedProjectId(projectFile?.config.projectId)
+            ? projectFile.config.projectId
+            : null,
     };
 }

package/dist/src/fabric/lib/git.js

@@ -136,8 +136,8 @@ export async function assertNamedBranchDeploySafety(branch, cwd) {
     try {
         head = await localBranchHeadSha(branch, cwd);
     }
-    catch {
-        throw new Error(`Deployment blocked: local branch ${branch} does not exist.\nFetch or create it before deploying.`);
+    catch (error) {
+        throw new Error(`Deployment blocked: local branch ${branch} does not exist (${error.message}).\nFetch or create it before deploying.`);
     }
     const upstream = await upstreamForBranch(branch, cwd);
     if (!upstream) {

package/dist/src/functions/db/sqlite/sqlite-runtime-node.js

@@ -53,7 +53,20 @@ class NodeSqliteDatabase {
 }
 async function importNodeSqlite() {
     const dynamicImport = new Function('return import("node:sqlite")');
-    return dynamicImport();
+    try {
+        return await dynamicImport();
+    }
+    catch (error) {
+        // node ships node:sqlite unflagged only from 24. The raw failure is
+        // ERR_UNKNOWN_BUILTIN_MODULE, which reads like a broken install rather than
+        // a runtime that is simply too old — so say which it is and how to get past it.
+        if (error?.code === 'ERR_UNKNOWN_BUILTIN_MODULE') {
+            throw new Error(`This needs node:sqlite, which Node ${process.versions.node} does not provide ` +
+                `(it is unflagged from Node 24). Either upgrade Node, or run the CLI on bun, ` +
+                `which has it: \`bunx --bun pikku <command>\`.`, { cause: error });
+        }
+        throw error;
+    }
 }
 export async function createNodeSqliteRuntime() {
     const { DatabaseSync } = await importNodeSqlite();

package/dist/src/functions/wirings/queue/pikku-command-queue.js

@@ -10,8 +10,16 @@ export const pikkuCommandQueue = pikkuSessionlessFunc({
         const visitState = await getInspectorState();
         const { queueWorkersWiringFile, queueWorkersWiringMetaFile, queueWorkersWiringMetaJsonFile, packageMappings, schema, } = config;
         const { queueWorkers } = visitState;
-        if (queueWorkers.files.size === 0 ||
-            Object.keys(queueWorkers.meta).length === 0) {
+        // Gate on the meta alone, never on `files`. Workflows synthesise their own
+        // `wf-orchestrator-*` / `wf-step-*` queue meta during post-processing, and
+        // those entries have no declaring source file — so a project that uses
+        // workflows but hand-declares no `wireQueueWorker` has a full `meta` and an
+        // empty `files`. Bailing on `files.size === 0` there skipped writing the
+        // queue meta entirely, which left `pikkuState(queue,meta)` empty at runtime:
+        // `getOrchestratorQueueName()` then never found a per-workflow queue and
+        // EVERY workflow fell back to the single shared `pikku-workflow-orchestrator`,
+        // where one slow job head-of-line-blocks everything queued behind it.
+        if (Object.keys(queueWorkers.meta).length === 0) {
             return undefined;
         }
         const fullMeta = serializeQueueMeta(queueWorkers.meta);

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../bin/pikku.ts","../src/cli.wiring.ts","../src/services.ts","../src/deploy/build-pipeline.ts","../src/deploy/provider-adapter.ts","../src/deploy/server-entry.ts","../src/deploy/analyzer/analyzer.ts","../src/deploy/analyzer/index.ts","../src/deploy/analyzer/manifest.ts","../src/deploy/bundler/bun-bundler.ts","../src/deploy/bundler/bundler.interface.ts","../src/deploy/bundler/bundler.ts","../src/deploy/bundler/dep-extractor.ts","../src/deploy/bundler/index.ts","../src/deploy/bundler/node-bundler.ts","../src/deploy/bundler/types.ts","../src/deploy/codegen/index.ts","../src/deploy/codegen/per-unit-codegen.ts","../src/deploy/plan/executor.ts","../src/deploy/plan/formatter.ts","../src/deploy/plan/index.ts","../src/deploy/plan/planner.ts","../src/deploy/plan/provider.ts","../src/deploy/plan/types.ts","../src/fabric/fabric-commands.ts","../src/fabric/functions/add.function.ts","../src/fabric/functions/addon-verify.function.ts","../src/fabric/functions/db-schema.function.ts","../src/fabric/functions/deploy-list.function.ts","../src/fabric/functions/deploy-units.function.ts","../src/fabric/functions/deploy.function.ts","../src/fabric/functions/domains-add.function.ts","../src/fabric/functions/domains-list.function.ts","../src/fabric/functions/domains-remove.function.ts","../src/fabric/functions/errors.function.ts","../src/fabric/functions/init.function.ts","../src/fabric/functions/link.function.ts","../src/fabric/functions/llm-key.function.ts","../src/fabric/functions/login.function.ts","../src/fabric/functions/logs.function.ts","../src/fabric/functions/metrics.function.ts","../src/fabric/functions/publish.function.ts","../src/fabric/functions/rollback.function.ts","../src/fabric/functions/secrets-list.function.ts","../src/fabric/functions/secrets-set.function.ts","../src/fabric/functions/smoke.function.ts","../src/fabric/functions/status.function.ts","../src/fabric/functions/trace.function.ts","../src/fabric/functions/validate.function.ts","../src/fabric/lib/config.ts","../src/fabric/lib/console-url.ts","../src/fabric/lib/git.ts","../src/fabric/lib/http.ts","../src/fabric/lib/not-implemented.ts","../src/fabric/lib/output.ts","../src/fabric/lib/prompt.ts","../src/fabric/lib/stage.ts","../src/fabric/sdk/http-map.gen.d.ts","../src/fabric/sdk/pikku-fetch.gen.ts","../src/fabric/sdk/pikku-rpc.gen.ts","../src/fabric/sdk/rpc-map.gen.d.ts","../src/functions/commands/all.ts","../src/functions/commands/audit.ts","../src/functions/commands/binary.ts","../src/functions/commands/bootstrap.ts","../src/functions/commands/bun-coverage-loader.ts","../src/functions/commands/db-audit.ts","../src/functions/commands/db-generate.ts","../src/functions/commands/db-migrate.ts","../src/functions/commands/db-reset.ts","../src/functions/commands/db-seed.ts","../src/functions/commands/db-shared.ts","../src/functions/commands/deploy-apply.ts","../src/functions/commands/deploy-info.ts","../src/functions/commands/deploy-plan.ts","../src/functions/commands/dev-ai-runner.ts","../src/functions/commands/dev.ts","../src/functions/commands/emails-init.ts","../src/functions/commands/enable.ts","../src/functions/commands/import-n8n.ts","../src/functions/commands/info.ts","../src/functions/commands/load-user-project.ts","../src/functions/commands/login.ts","../src/functions/commands/meta.ts","../src/functions/commands/new-addon.ts","../src/functions/commands/new-function.ts","../src/functions/commands/new-middleware.ts","../src/functions/commands/new-permission.ts","../src/functions/commands/new-wiring.ts","../src/functions/commands/pikku-command-bootstrap.ts","../src/functions/commands/pikku-command-summary.ts","../src/functions/commands/scenario.ts","../src/functions/commands/scopes-audit.ts","../src/functions/commands/scopes-prune.ts","../src/functions/commands/scopes-shared.ts","../src/functions/commands/serve-console.ts","../src/functions/commands/serve.ts","../src/functions/commands/skills.ts","../src/functions/commands/start-coverage.ts","../src/functions/commands/versions-check.ts","../src/functions/commands/versions-init.ts","../src/functions/commands/versions-update.ts","../src/functions/commands/watch.ts","../src/functions/commands/workspace-validate.ts","../src/functions/db/annotation-parser.ts","../src/functions/db/better-auth-schema.ts","../src/functions/db/coercion-plugin.ts","../src/functions/db/db-codegen.ts","../src/functions/db/db-introspector.ts","../src/functions/db/db-migrator.ts","../src/functions/db/local-db.ts","../src/functions/db/zod-codegen.ts","../src/functions/db/postgres/pglite-kysely.ts","../src/functions/db/postgres/postgres-introspector.ts","../src/functions/db/postgres/postgres-migrator.ts","../src/functions/db/sqlite/seed.ts","../src/functions/db/sqlite/sqlite-introspector.ts","../src/functions/db/sqlite/sqlite-kysely.ts","../src/functions/db/sqlite/sqlite-migrator.ts","../src/functions/db/sqlite/sqlite-runtime-bun.ts","../src/functions/db/sqlite/sqlite-runtime-node.ts","../src/functions/db/sqlite/sqlite-runtime.ts","../src/functions/runtimes/fetch/index.ts","../src/functions/runtimes/nextjs/pikku-command-nextjs.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-worker-rpc-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-http-wrapper.ts","../src/functions/runtimes/tanstack-start/pikku-command-tanstack-start.ts","../src/functions/runtimes/tanstack-start/serialize-tanstack-start-shim.ts","../src/functions/runtimes/websocket/pikku-command-websocket-typed.ts","../src/functions/runtimes/websocket/serialize-websocket-wrapper.ts","../src/functions/validate/workspace-validate.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent-types.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent.ts","../src/functions/wirings/ai-agent/pikku-command-public-agent.ts","../src/functions/wirings/ai-agent/serialize-agent-map.ts","../src/functions/wirings/ai-agent/serialize-ai-agent-types.ts","../src/functions/wirings/ai-agent/serialize-public-agent.ts","../src/functions/wirings/auth/pikku-command-auth.ts","../src/functions/wirings/auth/serialize-auth-gen.ts","../src/functions/wirings/auth/serialize-auth-meta.ts","../src/functions/wirings/auth/serialize-auth-types.ts","../src/functions/wirings/channels/pikku-channels.ts","../src/functions/wirings/channels/pikku-command-channel-types.ts","../src/functions/wirings/channels/pikku-command-channels-map.ts","../src/functions/wirings/channels/pikku-command-channels.ts","../src/functions/wirings/channels/serialize-channel-types.ts","../src/functions/wirings/channels/serialize-typed-channel-map.ts","../src/functions/wirings/cli/pikku-command-cli-entry.ts","../src/functions/wirings/cli/pikku-command-cli-types.ts","../src/functions/wirings/cli/pikku-command-cli.ts","../src/functions/wirings/cli/serialize-channel-cli-client.ts","../src/functions/wirings/cli/serialize-channel-cli.ts","../src/functions/wirings/cli/serialize-cli-types.ts","../src/functions/wirings/cli/serialize-local-cli-bootstrap.ts","../src/functions/wirings/console/pikku-command-console-functions.ts","../src/functions/wirings/console/pikku-command-node-types.ts","../src/functions/wirings/console/pikku-command-nodes-meta.ts","../src/functions/wirings/console/serialize-console-functions.ts","../src/functions/wirings/console/serialize-node-types.ts","../src/functions/wirings/credentials/pikku-command-credentials.ts","../src/functions/wirings/credentials/serialize-credentials-types.ts","../src/functions/wirings/emails/pikku-command-emails.ts","../src/functions/wirings/emails/serialize-emails.ts","../src/functions/wirings/functions/pikku-command-addon-types.ts","../src/functions/wirings/functions/pikku-command-function-types-split.ts","../src/functions/wirings/functions/pikku-command-function-types.ts","../src/functions/wirings/functions/pikku-command-functions.ts","../src/functions/wirings/functions/pikku-command-services.ts","../src/functions/wirings/functions/schemas.ts","../src/functions/wirings/functions/serialize-addon-refs.ts","../src/functions/wirings/functions/serialize-addon-types.ts","../src/functions/wirings/functions/serialize-function-imports.ts","../src/functions/wirings/functions/serialize-function-types.ts","../src/functions/wirings/functions/serialize-pikku-types-hub.ts","../src/functions/wirings/gateway/pikku-command-gateway.ts","../src/functions/wirings/gateway/serialize-gateway-meta.ts","../src/functions/wirings/graph/pikku-command-graph-wirings.ts","../src/functions/wirings/graph/serialize-graph-wirings.ts","../src/functions/wirings/http/pikku-command-http-map.ts","../src/functions/wirings/http/pikku-command-http-routes.ts","../src/functions/wirings/http/pikku-command-http-types.ts","../src/functions/wirings/http/pikku-command-openapi.ts","../src/functions/wirings/http/pikku-http-routes.ts","../src/functions/wirings/http/serialize-fetch-wrapper.ts","../src/functions/wirings/http/serialize-http-types.ts","../src/functions/wirings/http/serialize-typed-http-map.ts","../src/functions/wirings/mcp/pikku-command-mcp-json.ts","../src/functions/wirings/mcp/pikku-command-mcp-types.ts","../src/functions/wirings/mcp/pikku-command-mcp.ts","../src/functions/wirings/mcp/serialize-mcp-types.ts","../src/functions/wirings/middleware/pikku-command-middleware.ts","../src/functions/wirings/middleware/serialize-middleware-imports.ts","../src/functions/wirings/package/pikku-command-package-types.ts","../src/functions/wirings/package/pikku-command-package.ts","../src/functions/wirings/package/serialize-package-types.ts","../src/functions/wirings/package/serialize-package.ts","../src/functions/wirings/permissions/pikku-command-permissions.ts","../src/functions/wirings/permissions/serialize-permissions-imports.ts","../src/functions/wirings/queue/pikku-command-queue-map.ts","../src/functions/wirings/queue/pikku-command-queue-service.ts","../src/functions/wirings/queue/pikku-command-queue-types.ts","../src/functions/wirings/queue/pikku-command-queue.ts","../src/functions/wirings/queue/pikku-queue-map.ts","../src/functions/wirings/queue/pikku-queue.ts","../src/functions/wirings/queue/serialize-queue-map.ts","../src/functions/wirings/queue/serialize-queue-meta.ts","../src/functions/wirings/queue/serialize-queue-types.ts","../src/functions/wirings/queue/serialize-queue-wrapper.ts","../src/functions/wirings/realtime/pikku-command-events-scaffold.ts","../src/functions/wirings/realtime/pikku-command-realtime.ts","../src/functions/wirings/realtime/serialize-events-scaffold.ts","../src/functions/wirings/realtime/serialize-realtime-client.ts","../src/functions/wirings/rpc/pikku-command-public-rpc.ts","../src/functions/wirings/rpc/pikku-command-react-query.ts","../src/functions/wirings/rpc/pikku-command-remote-rpc.ts","../src/functions/wirings/rpc/pikku-command-rpc-client.ts","../src/functions/wirings/rpc/pikku-command-rpc-map.ts","../src/functions/wirings/rpc/pikku-command-rpc.ts","../src/functions/wirings/rpc/serialize-public-rpc.ts","../src/functions/wirings/rpc/serialize-react-query-hooks.ts","../src/functions/wirings/rpc/serialize-remote-rpc.ts","../src/functions/wirings/rpc/serialize-rpc-wrapper.ts","../src/functions/wirings/rpc/serialize-typed-rpc-map.ts","../src/functions/wirings/scenarios/pikku-command-scenario-functions.ts","../src/functions/wirings/scenarios/serialize-scenario-functions.ts","../src/functions/wirings/scheduler/pikku-command-scheduler-types.ts","../src/functions/wirings/scheduler/pikku-command-scheduler.ts","../src/functions/wirings/scheduler/serialize-scheduler-meta.ts","../src/functions/wirings/scheduler/serialize-scheduler-types.ts","../src/functions/wirings/scopes/pikku-command-scopes.ts","../src/functions/wirings/scopes/serialize-scopes-types.ts","../src/functions/wirings/secrets/pikku-command-secrets.ts","../src/functions/wirings/secrets/serialize-secrets-types.ts","../src/functions/wirings/triggers/pikku-command-trigger-types.ts","../src/functions/wirings/triggers/pikku-command-trigger.ts","../src/functions/wirings/triggers/serialize-trigger-meta.ts","../src/functions/wirings/triggers/serialize-trigger-types.ts","../src/functions/wirings/user-admin/pikku-command-user-admin-functions.ts","../src/functions/wirings/user-admin/serialize-user-admin-functions.ts","../src/functions/wirings/variables/pikku-command-variables.ts","../src/functions/wirings/variables/serialize-variables-types.ts","../src/functions/wirings/webhook/pikku-command-webhook.ts","../src/functions/wirings/webhook/serialize-webhook.ts","../src/functions/wirings/workflow/pikku-command-workflow-routes.ts","../src/functions/wirings/workflow/pikku-command-workflow.ts","../src/functions/wirings/workflow/serialize-scenario-actors.ts","../src/functions/wirings/workflow/serialize-workflow-bootstrap-map.ts","../src/functions/wirings/workflow/serialize-workflow-map.ts","../src/functions/wirings/workflow/serialize-workflow-meta.ts","../src/functions/wirings/workflow/serialize-workflow-registration.ts","../src/functions/wirings/workflow/serialize-workflow-routes.ts","../src/functions/wirings/workflow/serialize-workflow-types.ts","../src/functions/workflows/all.workflow.ts","../src/middleware/log-command-info-and-time.ts","../src/server/bun-server-runner.ts","../src/server/dev-server-runner.interface.ts","../src/server/node-server-runner.ts","../src/services/cli-logger-forwarder.service.ts","../src/services/cli-logger.service.ts","../src/utils/assert-single-core-version.ts","../src/utils/check-required-types.ts","../src/utils/cli-session.ts","../src/utils/command-summary.ts","../src/utils/contract-versions.ts","../src/utils/detect-better-auth.ts","../src/utils/device-auth.ts","../src/utils/file-import-path.ts","../src/utils/file-imports-serializer.ts","../src/utils/file-writer.ts","../src/utils/generate-bootstrap-file.ts","../src/utils/get-cli-version.ts","../src/utils/meta-diff.ts","../src/utils/parse-cli-filters.ts","../src/utils/pikku-cli-config.ts","../src/utils/pikku-files-and-methods.ts","../src/utils/precise-coverage-map.ts","../src/utils/remove-legacy-scaffold-file.ts","../src/utils/serialize-import-map.ts","../src/utils/serialize-meta-ts.ts","../src/utils/serialize-schemas.ts","../src/utils/strip-verbose-meta.ts","../src/utils/tsc-check.ts","../.pikku/pikku-bootstrap.gen.ts","../.pikku/pikku-meta-service.gen.ts","../.pikku/pikku-services.gen.ts","../.pikku/pikku-types.gen.ts","../.pikku/agent/pikku-agent-map.gen.d.ts","../.pikku/agent/pikku-agent-types.gen.ts","../.pikku/auth/auth.types.ts","../.pikku/channel/pikku-channel-types.gen.ts","../.pikku/cli/pikku-cli-channel.ts","../.pikku/cli/pikku-cli-client.gen.ts","../.pikku/cli/pikku-cli-contracts-meta.gen.ts","../.pikku/cli/pikku-cli-types.gen.ts","../.pikku/cli/pikku-cli-wirings-meta.gen.ts","../.pikku/cli/pikku-cli-wirings.gen.ts","../.pikku/cli/pikku-cli.gen.ts","../.pikku/console/pikku-node-types.gen.ts","../.pikku/function/pikku-function-types.gen.ts","../.pikku/function/pikku-functions-meta.gen.ts","../.pikku/function/pikku-functions.gen.ts","../.pikku/http/pikku-http-types.gen.ts","../.pikku/mcp/pikku-mcp-types.gen.ts","../.pikku/node/pikku-node-types.gen.ts","../.pikku/queue/pikku-queue-types.gen.ts","../.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-map.internal.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-map.remote.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-meta.internal.gen.ts","../.pikku/scheduler/pikku-scheduler-types.gen.ts","../.pikku/schemas/register.gen.ts","../.pikku/scopes/pikku-scope-types.gen.ts","../.pikku/scopes/pikku-scopes.gen.ts","../.pikku/secrets/pikku-secret-types.gen.ts","../.pikku/secrets/pikku-secrets.gen.ts","../.pikku/trigger/pikku-trigger-types.gen.ts","../.pikku/variables/pikku-variable-types.gen.ts","../.pikku/variables/pikku-variables.gen.ts","../.pikku/workflow/pikku-workflow-map.gen.d.ts","../.pikku/workflow/pikku-workflow-types.gen.ts","../.pikku/workflow/pikku-workflow-wirings-meta.gen.ts","../.pikku/workflow/pikku-workflow-wirings.gen.ts","../types/application-types.d.ts","../types/bun-sqlite.d.ts","../types/config.d.ts"],"version":"6.0.3"}
+{"root":["../bin/pikku.ts","../src/cli.wiring.ts","../src/services.ts","../src/deploy/build-pipeline.ts","../src/deploy/provider-adapter.ts","../src/deploy/server-entry.ts","../src/deploy/analyzer/analyzer.ts","../src/deploy/analyzer/index.ts","../src/deploy/analyzer/manifest.ts","../src/deploy/bundler/bun-bundler.ts","../src/deploy/bundler/bundler.interface.ts","../src/deploy/bundler/bundler.ts","../src/deploy/bundler/dep-extractor.ts","../src/deploy/bundler/index.ts","../src/deploy/bundler/node-bundler.ts","../src/deploy/bundler/types.ts","../src/deploy/codegen/index.ts","../src/deploy/codegen/per-unit-codegen.ts","../src/deploy/plan/executor.ts","../src/deploy/plan/formatter.ts","../src/deploy/plan/index.ts","../src/deploy/plan/planner.ts","../src/deploy/plan/provider.ts","../src/deploy/plan/types.ts","../src/fabric/fabric-commands.ts","../src/fabric/functions/add.function.ts","../src/fabric/functions/addon-verify.function.ts","../src/fabric/functions/db-schema.function.ts","../src/fabric/functions/deploy-list.function.ts","../src/fabric/functions/deploy-units.function.ts","../src/fabric/functions/deploy.function.ts","../src/fabric/functions/domains-add.function.ts","../src/fabric/functions/domains-list.function.ts","../src/fabric/functions/domains-remove.function.ts","../src/fabric/functions/errors.function.ts","../src/fabric/functions/init.function.ts","../src/fabric/functions/link.function.ts","../src/fabric/functions/llm-key.function.ts","../src/fabric/functions/login.function.ts","../src/fabric/functions/logs.function.ts","../src/fabric/functions/metrics.function.ts","../src/fabric/functions/publish.function.ts","../src/fabric/functions/rollback.function.ts","../src/fabric/functions/secrets-list.function.ts","../src/fabric/functions/secrets-set.function.ts","../src/fabric/functions/smoke.function.ts","../src/fabric/functions/status.function.ts","../src/fabric/functions/trace.function.ts","../src/fabric/functions/validate.function.ts","../src/fabric/lib/config.ts","../src/fabric/lib/console-url.ts","../src/fabric/lib/git.ts","../src/fabric/lib/http.ts","../src/fabric/lib/not-implemented.ts","../src/fabric/lib/output.ts","../src/fabric/lib/prompt.ts","../src/fabric/lib/stage.ts","../src/fabric/sdk/http-map.gen.d.ts","../src/fabric/sdk/pikku-fetch.gen.ts","../src/fabric/sdk/pikku-rpc.gen.ts","../src/fabric/sdk/rpc-map.gen.d.ts","../src/functions/commands/all.ts","../src/functions/commands/audit.ts","../src/functions/commands/binary.ts","../src/functions/commands/bootstrap.ts","../src/functions/commands/bun-coverage-loader.ts","../src/functions/commands/db-audit.ts","../src/functions/commands/db-generate.ts","../src/functions/commands/db-migrate.ts","../src/functions/commands/db-reset.ts","../src/functions/commands/db-seed.ts","../src/functions/commands/db-shared.ts","../src/functions/commands/deploy-apply.ts","../src/functions/commands/deploy-info.ts","../src/functions/commands/deploy-plan.ts","../src/functions/commands/dev-ai-runner.ts","../src/functions/commands/dev.ts","../src/functions/commands/emails-init.ts","../src/functions/commands/enable.ts","../src/functions/commands/import-n8n.ts","../src/functions/commands/info.ts","../src/functions/commands/load-user-project.ts","../src/functions/commands/login.ts","../src/functions/commands/meta.ts","../src/functions/commands/new-addon.ts","../src/functions/commands/new-function.ts","../src/functions/commands/new-middleware.ts","../src/functions/commands/new-permission.ts","../src/functions/commands/new-wiring.ts","../src/functions/commands/pikku-command-bootstrap.ts","../src/functions/commands/pikku-command-summary.ts","../src/functions/commands/scenario.ts","../src/functions/commands/scopes-audit.ts","../src/functions/commands/scopes-prune.ts","../src/functions/commands/scopes-shared.ts","../src/functions/commands/serve-console.ts","../src/functions/commands/serve.ts","../src/functions/commands/skills.ts","../src/functions/commands/start-coverage.ts","../src/functions/commands/versions-check.ts","../src/functions/commands/versions-init.ts","../src/functions/commands/versions-update.ts","../src/functions/commands/watch.ts","../src/functions/commands/workspace-validate.ts","../src/functions/db/annotation-parser.ts","../src/functions/db/better-auth-schema.ts","../src/functions/db/coercion-plugin.ts","../src/functions/db/db-codegen.ts","../src/functions/db/db-introspector.ts","../src/functions/db/db-migrator.ts","../src/functions/db/local-db.ts","../src/functions/db/zod-codegen.ts","../src/functions/db/postgres/pglite-kysely.ts","../src/functions/db/postgres/postgres-introspector.ts","../src/functions/db/postgres/postgres-migrator.ts","../src/functions/db/sqlite/seed.ts","../src/functions/db/sqlite/sqlite-introspector.ts","../src/functions/db/sqlite/sqlite-kysely.ts","../src/functions/db/sqlite/sqlite-migrator.ts","../src/functions/db/sqlite/sqlite-runtime-bun.ts","../src/functions/db/sqlite/sqlite-runtime-node.ts","../src/functions/db/sqlite/sqlite-runtime.ts","../src/functions/runtimes/fetch/index.ts","../src/functions/runtimes/nextjs/pikku-command-nextjs.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-worker-rpc-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-backend-wrapper.ts","../src/functions/runtimes/nextjs/serialize-nextjs-http-wrapper.ts","../src/functions/runtimes/tanstack-start/pikku-command-tanstack-start.ts","../src/functions/runtimes/tanstack-start/serialize-tanstack-start-shim.ts","../src/functions/runtimes/websocket/pikku-command-websocket-typed.ts","../src/functions/runtimes/websocket/serialize-websocket-wrapper.ts","../src/functions/validate/workspace-validate.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent-types.ts","../src/functions/wirings/ai-agent/pikku-command-ai-agent.ts","../src/functions/wirings/ai-agent/pikku-command-public-agent.ts","../src/functions/wirings/ai-agent/serialize-agent-map.ts","../src/functions/wirings/ai-agent/serialize-ai-agent-types.ts","../src/functions/wirings/ai-agent/serialize-public-agent.ts","../src/functions/wirings/auth/pikku-command-auth.ts","../src/functions/wirings/auth/serialize-auth-gen.ts","../src/functions/wirings/auth/serialize-auth-meta.ts","../src/functions/wirings/auth/serialize-auth-types.ts","../src/functions/wirings/channels/pikku-channels.ts","../src/functions/wirings/channels/pikku-command-channel-types.ts","../src/functions/wirings/channels/pikku-command-channels-map.ts","../src/functions/wirings/channels/pikku-command-channels.ts","../src/functions/wirings/channels/serialize-channel-types.ts","../src/functions/wirings/channels/serialize-typed-channel-map.ts","../src/functions/wirings/cli/pikku-command-cli-entry.ts","../src/functions/wirings/cli/pikku-command-cli-types.ts","../src/functions/wirings/cli/pikku-command-cli.ts","../src/functions/wirings/cli/serialize-channel-cli-client.ts","../src/functions/wirings/cli/serialize-channel-cli.ts","../src/functions/wirings/cli/serialize-cli-types.ts","../src/functions/wirings/cli/serialize-local-cli-bootstrap.ts","../src/functions/wirings/console/pikku-command-console-functions.ts","../src/functions/wirings/console/pikku-command-node-types.ts","../src/functions/wirings/console/pikku-command-nodes-meta.ts","../src/functions/wirings/console/serialize-console-functions.ts","../src/functions/wirings/console/serialize-node-types.ts","../src/functions/wirings/credentials/pikku-command-credentials.ts","../src/functions/wirings/credentials/serialize-credentials-types.ts","../src/functions/wirings/emails/pikku-command-emails.ts","../src/functions/wirings/emails/serialize-emails.ts","../src/functions/wirings/functions/pikku-command-addon-types.ts","../src/functions/wirings/functions/pikku-command-function-types-split.ts","../src/functions/wirings/functions/pikku-command-function-types.ts","../src/functions/wirings/functions/pikku-command-functions.ts","../src/functions/wirings/functions/pikku-command-services.ts","../src/functions/wirings/functions/schemas.ts","../src/functions/wirings/functions/serialize-addon-refs.ts","../src/functions/wirings/functions/serialize-addon-types.ts","../src/functions/wirings/functions/serialize-function-imports.ts","../src/functions/wirings/functions/serialize-function-types.ts","../src/functions/wirings/functions/serialize-pikku-types-hub.ts","../src/functions/wirings/gateway/pikku-command-gateway.ts","../src/functions/wirings/gateway/serialize-gateway-meta.ts","../src/functions/wirings/graph/pikku-command-graph-wirings.ts","../src/functions/wirings/graph/serialize-graph-wirings.ts","../src/functions/wirings/http/pikku-command-http-map.ts","../src/functions/wirings/http/pikku-command-http-routes.ts","../src/functions/wirings/http/pikku-command-http-types.ts","../src/functions/wirings/http/pikku-command-openapi.ts","../src/functions/wirings/http/pikku-http-routes.ts","../src/functions/wirings/http/serialize-fetch-wrapper.ts","../src/functions/wirings/http/serialize-http-types.ts","../src/functions/wirings/http/serialize-typed-http-map.ts","../src/functions/wirings/mcp/pikku-command-mcp-json.ts","../src/functions/wirings/mcp/pikku-command-mcp-types.ts","../src/functions/wirings/mcp/pikku-command-mcp.ts","../src/functions/wirings/mcp/serialize-mcp-types.ts","../src/functions/wirings/middleware/pikku-command-middleware.ts","../src/functions/wirings/middleware/serialize-middleware-imports.ts","../src/functions/wirings/package/pikku-command-package-types.ts","../src/functions/wirings/package/pikku-command-package.ts","../src/functions/wirings/package/serialize-package-types.ts","../src/functions/wirings/package/serialize-package.ts","../src/functions/wirings/permissions/pikku-command-permissions.ts","../src/functions/wirings/permissions/serialize-permissions-imports.ts","../src/functions/wirings/queue/pikku-command-queue-map.ts","../src/functions/wirings/queue/pikku-command-queue-service.ts","../src/functions/wirings/queue/pikku-command-queue-types.ts","../src/functions/wirings/queue/pikku-command-queue.ts","../src/functions/wirings/queue/pikku-queue-map.ts","../src/functions/wirings/queue/pikku-queue.ts","../src/functions/wirings/queue/serialize-queue-map.ts","../src/functions/wirings/queue/serialize-queue-meta.ts","../src/functions/wirings/queue/serialize-queue-types.ts","../src/functions/wirings/queue/serialize-queue-wrapper.ts","../src/functions/wirings/realtime/pikku-command-events-scaffold.ts","../src/functions/wirings/realtime/pikku-command-realtime.ts","../src/functions/wirings/realtime/serialize-events-scaffold.ts","../src/functions/wirings/realtime/serialize-realtime-client.ts","../src/functions/wirings/rpc/pikku-command-public-rpc.ts","../src/functions/wirings/rpc/pikku-command-react-query.ts","../src/functions/wirings/rpc/pikku-command-remote-rpc.ts","../src/functions/wirings/rpc/pikku-command-rpc-client.ts","../src/functions/wirings/rpc/pikku-command-rpc-map.ts","../src/functions/wirings/rpc/pikku-command-rpc.ts","../src/functions/wirings/rpc/serialize-public-rpc.ts","../src/functions/wirings/rpc/serialize-react-query-hooks.ts","../src/functions/wirings/rpc/serialize-remote-rpc.ts","../src/functions/wirings/rpc/serialize-rpc-wrapper.ts","../src/functions/wirings/rpc/serialize-typed-rpc-map.ts","../src/functions/wirings/scenarios/pikku-command-scenario-functions.ts","../src/functions/wirings/scenarios/serialize-scenario-functions.ts","../src/functions/wirings/scheduler/pikku-command-scheduler-types.ts","../src/functions/wirings/scheduler/pikku-command-scheduler.ts","../src/functions/wirings/scheduler/serialize-scheduler-meta.ts","../src/functions/wirings/scheduler/serialize-scheduler-types.ts","../src/functions/wirings/scopes/pikku-command-scopes.ts","../src/functions/wirings/scopes/serialize-scopes-types.ts","../src/functions/wirings/secrets/pikku-command-secrets.ts","../src/functions/wirings/secrets/serialize-secrets-types.ts","../src/functions/wirings/triggers/pikku-command-trigger-types.ts","../src/functions/wirings/triggers/pikku-command-trigger.ts","../src/functions/wirings/triggers/serialize-trigger-meta.ts","../src/functions/wirings/triggers/serialize-trigger-types.ts","../src/functions/wirings/user-admin/pikku-command-user-admin-functions.ts","../src/functions/wirings/user-admin/serialize-user-admin-functions.ts","../src/functions/wirings/variables/pikku-command-variables.ts","../src/functions/wirings/variables/serialize-variables-types.ts","../src/functions/wirings/webhook/pikku-command-webhook.ts","../src/functions/wirings/webhook/serialize-webhook.ts","../src/functions/wirings/workflow/pikku-command-workflow-routes.ts","../src/functions/wirings/workflow/pikku-command-workflow.ts","../src/functions/wirings/workflow/serialize-scenario-actors.ts","../src/functions/wirings/workflow/serialize-workflow-bootstrap-map.ts","../src/functions/wirings/workflow/serialize-workflow-map.ts","../src/functions/wirings/workflow/serialize-workflow-meta.ts","../src/functions/wirings/workflow/serialize-workflow-registration.ts","../src/functions/wirings/workflow/serialize-workflow-routes.ts","../src/functions/wirings/workflow/serialize-workflow-types.ts","../src/functions/workflows/all.workflow.ts","../src/middleware/log-command-info-and-time.ts","../src/server/bun-server-runner.ts","../src/server/dev-server-runner.interface.ts","../src/server/node-server-runner.ts","../src/services/cli-logger-forwarder.service.ts","../src/services/cli-logger.service.ts","../src/utils/assert-single-core-version.ts","../src/utils/check-required-types.ts","../src/utils/cli-session.ts","../src/utils/command-summary.ts","../src/utils/contract-versions.ts","../src/utils/detect-better-auth.ts","../src/utils/device-auth.ts","../src/utils/file-import-path.ts","../src/utils/file-imports-serializer.ts","../src/utils/file-writer.ts","../src/utils/generate-bootstrap-file.ts","../src/utils/get-cli-version.ts","../src/utils/meta-diff.ts","../src/utils/parse-cli-filters.ts","../src/utils/pikku-cli-config.ts","../src/utils/pikku-files-and-methods.ts","../src/utils/precise-coverage-map.ts","../src/utils/remove-legacy-scaffold-file.ts","../src/utils/serialize-import-map.ts","../src/utils/serialize-meta-ts.ts","../src/utils/serialize-schemas.ts","../src/utils/strip-verbose-meta.ts","../src/utils/tsc-check.ts","../.pikku/pikku-bootstrap.gen.ts","../.pikku/pikku-meta-service.gen.ts","../.pikku/pikku-services.gen.ts","../.pikku/pikku-types.gen.ts","../.pikku/agent/pikku-agent-map.gen.d.ts","../.pikku/agent/pikku-agent-types.gen.ts","../.pikku/auth/auth.types.ts","../.pikku/channel/pikku-channel-types.gen.ts","../.pikku/cli/pikku-cli-channel.ts","../.pikku/cli/pikku-cli-client.gen.ts","../.pikku/cli/pikku-cli-contracts-meta.gen.ts","../.pikku/cli/pikku-cli-types.gen.ts","../.pikku/cli/pikku-cli-wirings-meta.gen.ts","../.pikku/cli/pikku-cli-wirings.gen.ts","../.pikku/cli/pikku-cli.gen.ts","../.pikku/console/pikku-node-types.gen.ts","../.pikku/function/pikku-function-types.gen.ts","../.pikku/function/pikku-functions-meta.gen.ts","../.pikku/function/pikku-functions.gen.ts","../.pikku/http/pikku-http-types.gen.ts","../.pikku/mcp/pikku-mcp-types.gen.ts","../.pikku/node/pikku-node-types.gen.ts","../.pikku/queue/pikku-queue-types.gen.ts","../.pikku/queue/pikku-queue-workers-wirings-map.gen.d.ts","../.pikku/queue/pikku-queue-workers-wirings-meta.gen.ts","../.pikku/queue/pikku-queue-workers-wirings.gen.ts","../.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-map.internal.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-map.remote.gen.d.ts","../.pikku/rpc/pikku-rpc-wirings-meta.internal.gen.ts","../.pikku/scheduler/pikku-scheduler-types.gen.ts","../.pikku/schemas/register.gen.ts","../.pikku/scopes/pikku-scope-types.gen.ts","../.pikku/scopes/pikku-scopes.gen.ts","../.pikku/secrets/pikku-secret-types.gen.ts","../.pikku/secrets/pikku-secrets.gen.ts","../.pikku/trigger/pikku-trigger-types.gen.ts","../.pikku/variables/pikku-variable-types.gen.ts","../.pikku/variables/pikku-variables.gen.ts","../.pikku/workflow/pikku-workflow-map.gen.d.ts","../.pikku/workflow/pikku-workflow-types.gen.ts","../.pikku/workflow/pikku-workflow-wirings-meta.gen.ts","../.pikku/workflow/pikku-workflow-wirings.gen.ts","../types/application-types.d.ts","../types/bun-sqlite.d.ts","../types/config.d.ts"],"version":"6.0.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/cli",
-  "version": "0.12.86",
+  "version": "0.12.89",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "imports": {
@@ -32,10 +32,10 @@
     "@pikku/bun-server": "^0.12.4",
     "@pikku/deploy-cloudflare": "^0.12.8",
     "@pikku/fetch": "^0.12.8",
-    "@pikku/inspector": "^0.12.45",
-    "@pikku/kysely": "^0.13.2",
+    "@pikku/inspector": "^0.12.46",
+    "@pikku/kysely": "^0.13.3",
     "@pikku/kysely-node-sqlite": "^0.12.3",
-    "@pikku/n8n-import": "^0.0.2",
+    "@pikku/n8n-import": "^0.0.3",
     "@pikku/node-http-server": "^0.12.6",
     "@pikku/openapi-parser": "^0.12.16",
     "@pikku/schedule": "^0.12.4",
@@ -60,10 +60,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.67"
+    "@pikku/core": "^0.12.69"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.67",
+    "@pikku/core": "^0.12.69",
     "@types/istanbul-lib-instrument": "^1.7.7",
     "@types/node": "^24.11.0",
     "@types/pg": "^8.11.0",

package/skills/pikku-concepts/SKILL.md

@@ -111,6 +111,22 @@ pikkuFunc({
 })
 ```
 
+**Generics XOR `input`/`output` — never both.** A function's data and return
+types come from *one* source: either the `input`/`output` schemas (preferred —
+they double as runtime validation and OpenAPI) or type generics
+(`pikkuFunc<In, Out>({ ... })`). Passing both makes the two disagree and forces
+`as any` casts. Do not annotate the `func` return type inline either — let the
+`output` schema (or the generic) be the single source of truth for the type.
+
+```typescript
+// Correct — schema-based (no generics, no inline return type)
+pikkuFunc({ input: MyInput, output: MyOutput, func: async (s, d) => { ... } })
+// Correct — generic-based (no input/output)
+pikkuFunc<MyIn, MyOut>({ func: async (s, d) => { ... } })
+// WRONG — mixing the two
+pikkuFunc<MyIn, MyOut>({ input: MyInput as any, func: async (s, d) => { ... } })
+```
+
 ## Schemas (Validation)
 
 Pikku uses Standard Schema — works with Zod, Valibot, ArkType:

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-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
 )
 ```
 
+**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).