@pikku/cli 0.12.89 → 0.12.91

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

@@ -1,22 +1,36 @@
 /**
- * This file was generated by @pikku/cli@0.12.89
+ * This file was generated by @pikku/cli@0.12.91
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { template } from '@pikku/core/workflow';
 import { type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult } from '@pikku/core/workflow';
-import type { PikkuWorkflowWire, PikkuScenarioWire, WorkflowStepOptions } from '@pikku/core/workflow';
+import type { PikkuWorkflowWire, PikkuScenarioWire, WorkflowStepOptions, ScenarioStepOptions } from '@pikku/core/workflow';
 export { WorkflowCancelledException };
 import type { PikkuFunctionSessionless, PikkuFunctionConfig } from '../function/pikku-function-types.gen.js';
 import type { FlattenedRPCMap } from '../rpc/pikku-rpc-wirings-map.internal.gen.d.js';
 import type { FlattenedWorkflowMap } from './pikku-workflow-map.gen.d.js';
 import type { AgentMap as FlattenedAgentMap } from '../agent/pikku-agent-map.gen.d.js';
+import type { FlattenedScenarioStepMap } from './pikku-scenario-step-map.gen.d.js';
+import type { TypedScenarioActors } from './pikku-scenario-actors.gen.js';
+export type { TypedScenarioActors };
 export { template };
 export interface TypedWorkflow extends PikkuWorkflowWire {
     do<K extends keyof FlattenedRPCMap>(stepName: string, rpcName: K, data: FlattenedRPCMap[K]['input'], options?: WorkflowStepOptions): Promise<FlattenedRPCMap[K]['output']>;
     do<K extends keyof FlattenedWorkflowMap>(stepName: string, workflowName: K, data: FlattenedWorkflowMap[K]['input'], options?: WorkflowStepOptions): Promise<FlattenedWorkflowMap[K]['output']>;
     do<T>(stepName: string, fn: () => T | Promise<T>, options?: WorkflowStepOptions): Promise<T>;
 }
-export type TypedScenario = TypedWorkflow & Omit<PikkuScenarioWire, keyof PikkuWorkflowWire>;
+/**
+ * The typed half of a scenario wire: `step` and its `given`/`when`/`then`
+ * sugar, narrowed to the names declared by `pikkuScenarioStep` in this project.
+ * The phase only changes the prose the reporter renders.
+ */
+export interface TypedScenarioSteps {
+    step<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
+    given<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
+    when<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
+    then<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
+}
+export type TypedScenario = TypedWorkflow & Omit<PikkuScenarioWire, keyof PikkuWorkflowWire | keyof TypedScenarioSteps> & TypedScenarioSteps;
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { InferSchemaOutput, PikkuPermission, PikkuMiddleware, NodeConfig, PikkuApprovalDescription } from '../function/pikku-function-types.gen.js';
 import type { ScopeId } from '../scopes/pikku-scopes.gen.js';
@@ -58,7 +72,39 @@ export declare function pikkuWorkflowComplexFunc<InputSchema extends StandardSch
 export declare function pikkuWorkflowComplexFunc<In, Out = unknown>(func: PikkuFunctionWorkflow<In, Out> | PikkuFunctionConfig<In, Out, 'workflow', PikkuFunctionWorkflow<In, Out>>): PikkuFunctionConfig<In, Out, 'workflow'>;
 export type PikkuScenarioConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = Omit<PikkuWorkflowConfigWithSchema<InputSchema, OutputSchema>, 'func' | 'auth' | 'scopes' | 'permissions'> & {
     func: PikkuFunctionScenario<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>;
+    /**
+     * Runs before the scenario body. Same signature as `func`, but its return
+     * value is discarded — a hook is setup, not a step, so it is never recorded
+     * on the ladder. Throwing skips the body and fails the run; `after` still
+     * runs.
+     */
+    before?: PikkuScenarioHook<InputSchema>;
+    /**
+     * Always runs after the scenario body, in a `finally`, whether it passed or
+     * failed. Throwing fails a run that would otherwise have passed; on an
+     * already-failed run it attaches as the `cause` and never replaces the
+     * original error.
+     */
+    after?: PikkuScenarioHook<InputSchema>;
+    /**
+     * Why this scenario is held out of a default run, stated where the scenario
+     * is. The scenario still appears in the plan and is reported as skipped
+     * rather than quietly omitted; naming it directly with `--flows` runs it
+     * anyway.
+     */
+    skip?: string;
 };
+/**
+ * A scenario lifecycle hook: the scenario's own `(services, data, wire)`
+ * signature with its result discarded.
+ */
+export type PikkuScenarioHook<InputSchema extends StandardSchemaV1 | undefined = undefined> = PikkuFunctionScenario<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, void>;
+/**
+ * Declares a scenario hook. Returns the function verbatim — a hook is never
+ * registered, so this exists purely to give an inline hook a call site to be
+ * contextually typed from, the way every other pikku primitive is.
+ */
+export declare function pikkuScenarioHook<In = unknown>(hook: PikkuFunctionScenario<In, void>): PikkuFunctionScenario<In, void>;
 /**
  * A scenario: a complex workflow that drives the app the way users do.
  * Steps run as actors over the REAL transport — `scenario.do(step, rpc,
@@ -67,6 +113,109 @@ export type PikkuScenarioConfigWithSchema<InputSchema extends StandardSchemaV1 |
  */
 export declare function pikkuScenario<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuScenarioConfigWithSchema<InputSchema, OutputSchema>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenario' | 'actors', PikkuFunctionScenario<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown>, InputSchema, OutputSchema>;
 export declare function pikkuScenario<In, Out = unknown>(func: PikkuFunctionScenario<In, Out> | PikkuFunctionConfig<In, Out, 'scenario' | 'actors', PikkuFunctionScenario<In, Out>>): PikkuFunctionConfig<In, Out, 'scenario' | 'actors'>;
+/**
+ * A scenario as a feature references it. Any `pikkuScenario` export is
+ * assignable; `In` is recovered from it so the paired form's `data` is
+ * checked against that scenario's own input.
+ */
+export type PikkuScenarioRef<In = any, Out = any> = PikkuFunctionConfig<In, Out, 'scenario' | 'actors', PikkuFunctionScenario<In, Out>, any, any>;
+/**
+ * One entry in a feature's `scenarios` list, validated against itself: a bare
+ * scenario, or a scenario paired with the input to run it with. The paired form
+ * is gherkin's `Examples:` written as an ordinary loop.
+ */
+export type PikkuFeatureEntry<Entry> = Entry extends {
+    scenario: PikkuScenarioRef<infer In>;
+} ? {
+    scenario: PikkuScenarioRef<In>;
+    data: In;
+} : Entry extends PikkuScenarioRef ? Entry : never;
+export type PikkuFeatureConfig<Scenarios extends readonly unknown[]> = {
+    /** Human-readable name. The export identifier is the id. */
+    name: string;
+    description?: string;
+    tags?: string[];
+    scenarios: {
+        [K in keyof Scenarios]: PikkuFeatureEntry<Scenarios[K]>;
+    };
+    /**
+     * Runs ONCE before the whole group — not before each scenario. Per-scenario
+     * setup is the scenario's own `before`; gherkin's `Background:` is
+     * deliberately not expressible here.
+     */
+    before?: PikkuScenarioHook;
+    after?: PikkuScenarioHook;
+};
+/**
+ * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
+ * Scenario structure. Scenarios are referenced by imported identifier, so a
+ * renamed or deleted scenario is a compile error rather than a silent skip.
+ *
+ * A scenario does not have to belong to a feature — a void-input scenario
+ * still runs standalone.
+ *
+ * ```ts
+ * export const credentialFeature = pikkuFeature({
+ *   name: 'Credential API',
+ *   tags: ['credential'],
+ *   before: startsMockOAuthServer,
+ *   after: stopsMockOAuthServer,
+ *   scenarios: [
+ *     credentialLazyLoadScenario,
+ *     ...['stripe', 'google'].map((name) => ({
+ *       scenario: credentialRoundTripScenario,
+ *       data: { name },
+ *     })),
+ *   ],
+ * })
+ * ```
+ */
+export declare function pikkuFeature<const Scenarios extends readonly unknown[]>(config: PikkuFeatureConfig<Scenarios>): PikkuFeatureConfig<Scenarios>;
+export type PikkuFunctionScenarioStep<In = unknown, Out = never, B extends boolean = false> = PikkuFunctionSessionless<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>;
+export type PikkuScenarioStepConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, B extends boolean = false> = {
+    /** Registered name — this is the string `scenario.step()` references. */
+    name: string;
+    /**
+     * What this step does, for the console and for whoever reads the source. It
+     * is also the fallback prose when no `template` is declared, in which case a
+     * reporter renders "Given the shopper buys an apple". Defaults to the call
+     * site's step name.
+     */
+    description?: string;
+    /**
+     * The prose a reporter renders for this step, with `{placeholders}` filled
+     * from the input the step was called with — `'sees {packageName}'` reports as
+     * "Then the admin sees @pikku/addon-todos". Every input field should appear,
+     * so the report names the values under test rather than repeating one
+     * sentence per call site.
+     */
+    template?: string;
+    /**
+     * This step drives a browser. The runner provisions one for the step's actor
+     * before calling it — which also makes an actor mandatory — and `wire.browser`
+     * is non-optional inside `func`.
+     */
+    browser?: B;
+    title?: string;
+    tags?: string[];
+    input?: InputSchema;
+    output?: OutputSchema;
+    errors?: Array<typeof PikkuError>;
+    func: PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B>;
+};
+export type PikkuScenarioStepConfig<In, Out, B extends boolean = false> = Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined, B>, 'func' | 'input' | 'output'> & {
+    func: PikkuFunctionScenarioStep<In, Out, B>;
+};
+/**
+ * A named, reusable scenario step. Unlike `scenario.do`, which can only name an
+ * RPC, a step's body is an ordinary pikku function — so it may drive a browser,
+ * invoke RPCs as its actor, or run a workflow.
+ *
+ * Steps are deliberately NOT registered as RPCs: a browser-driving step must
+ * never be network-callable.
+ */
+export declare function pikkuScenarioStep<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, B extends boolean = false>(config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema, B>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B>, InputSchema, OutputSchema>;
+export declare function pikkuScenarioStep<In, Out = unknown, B extends boolean = false>(config: PikkuScenarioStepConfig<In, Out, B>): PikkuFunctionConfig<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>;
 type TypedRef<T> = {
     $ref: string;
     path?: string;

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

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.89
+ * This file was generated by @pikku/cli@0.12.91
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { template } from '@pikku/core/workflow';
@@ -12,9 +12,47 @@ export function pikkuWorkflowFunc(func) {
 export function pikkuWorkflowComplexFunc(func) {
     return typeof func === 'function' ? { func } : func;
 }
+/**
+ * Declares a scenario hook. Returns the function verbatim — a hook is never
+ * registered, so this exists purely to give an inline hook a call site to be
+ * contextually typed from, the way every other pikku primitive is.
+ */
+export function pikkuScenarioHook(hook) {
+    return hook;
+}
 export function pikkuScenario(func) {
     return typeof func === 'function' ? { func } : func;
 }
+/**
+ * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
+ * Scenario structure. Scenarios are referenced by imported identifier, so a
+ * renamed or deleted scenario is a compile error rather than a silent skip.
+ *
+ * A scenario does not have to belong to a feature — a void-input scenario
+ * still runs standalone.
+ *
+ * ```ts
+ * export const credentialFeature = pikkuFeature({
+ *   name: 'Credential API',
+ *   tags: ['credential'],
+ *   before: startsMockOAuthServer,
+ *   after: stopsMockOAuthServer,
+ *   scenarios: [
+ *     credentialLazyLoadScenario,
+ *     ...['stripe', 'google'].map((name) => ({
+ *       scenario: credentialRoundTripScenario,
+ *       data: { name },
+ *     })),
+ *   ],
+ * })
+ * ```
+ */
+export function pikkuFeature(config) {
+    return config;
+}
+export function pikkuScenarioStep(config) {
+    return config;
+}
 export function pikkuWorkflowGraph(config) {
     return corePikkuWorkflowGraph(config);
 }

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

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

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

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

package/dist/bin/pikku-bin.mjs

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

package/dist/src/cli.wiring.js

@@ -18,6 +18,10 @@ import { dev } from './functions/commands/dev.js';
 import { serve } from './functions/commands/serve.js';
 import { dbMigrate } from './functions/commands/db-migrate.js';
 import { dbGenerate } from './functions/commands/db-generate.js';
+import { dbCodegen } from './functions/commands/db-codegen.js';
+import { dbCheck } from './functions/commands/db-check.js';
+import { dbBaseline } from './functions/commands/db-baseline.js';
+import { dbExport } from './functions/commands/db-export.js';
 import { dbSeed } from './functions/commands/db-seed.js';
 import { dbReset } from './functions/commands/db-reset.js';
 import { dbAudit } from './functions/commands/db-audit.js';
@@ -321,6 +325,22 @@ wireCLI({
                     func: dbGenerate,
                     description: 'Generate SQL migrations from detected schema changes',
                 }),
+                check: pikkuCLICommand({
+                    func: dbCheck,
+                    description: 'Report how the configured database differs from the schema its migrations define',
+                }),
+                baseline: pikkuCLICommand({
+                    func: dbBaseline,
+                    description: 'Record pending migrations as applied, for a database that already has what they describe',
+                }),
+                codegen: pikkuCLICommand({
+                    func: dbCodegen,
+                    description: 'Regenerate db/schema.gen.ts and db/zod.gen.ts from the migration files, without connecting to a database',
+                }),
+                export: pikkuCLICommand({
+                    func: dbExport,
+                    description: "Publish this package's schema so projects consuming it as an addon can create its tables",
+                }),
                 seed: pikkuCLICommand({
                     func: dbSeed,
                     description: 'Apply db/seed.sql to the dev database',
@@ -377,14 +397,36 @@ wireCLI({
                             description: 'Comma-separated flow names to run (default: all)',
                             short: 'f',
                         },
+                        features: {
+                            description: 'Comma-separated feature names to run (pikkuFeature exports) — the feature is the run unit, so its hooks run once around the group',
+                        },
                         tags: {
                             description: 'Comma-separated tags — run flows matching any',
                             short: 't',
                         },
+                        excludeTags: {
+                            description: 'Comma-separated tags to hold back — flows matching any are not run, unless named directly with --flows',
+                        },
                         coverage: {
                             description: 'Reset/snapshot server coverage per scenario (target must run with --coverage); writes coverage/scenario-coverage.json',
                             default: false,
                         },
+                        browser: {
+                            description: 'Run scenarios with browser steps. --no-browser skips them (they are reported as skipped, not failed)',
+                            default: true,
+                        },
+                        spawn: {
+                            description: "Start `pikku dev` on the environment's apiUrl for the run and stop it afterwards. Without it, the environment must already be serving",
+                            default: false,
+                        },
+                        keepAlive: {
+                            description: 'With --spawn, leave the server running after the run (dev loop)',
+                            default: false,
+                        },
+                        trace: {
+                            description: 'Keep every stack frame on a failure. Without it, only the project’s own frames are shown',
+                            default: false,
+                        },
                     },
                 }),
                 list: pikkuCLICommand({

package/dist/src/fabric/fabric-commands.d.ts

@@ -1,5 +1,7 @@
 export declare const fabricCommands: {
-    validate: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<Record<string, never>, {
+    validate: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
+        skipTypecheck?: boolean | undefined;
+    }, {
         ok: boolean;
         root: string;
         findings: {
@@ -9,7 +11,9 @@ export declare const fabricCommands: {
             path: string;
             fixHint: string;
         }[];
-    }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<Record<string, never>, {
+    }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
+        skipTypecheck?: boolean | undefined;
+    }, {
         ok: boolean;
         root: string;
         findings: {
@@ -19,7 +23,9 @@ export declare const fabricCommands: {
             path: string;
             fixHint: string;
         }[];
-    }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<Record<string, never>, {
+    }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<{
+        skipTypecheck?: boolean | undefined;
+    }, {
         ok: boolean;
         root: string;
         findings: {

package/dist/src/fabric/fabric-commands.js

@@ -48,6 +48,12 @@ export const fabricCommands = defineCLICommands({
         func: FabricValidate,
         render: renderValidate,
         description: 'Check the project structure for fabric compatibility — prints all missing or misconfigured items with fix hints',
+        options: {
+            skipTypecheck: {
+                description: 'Skip the frontend type-check the build container runs (structural checks only)',
+                default: false,
+            },
+        },
     }),
     smoke: pikkuCLICommand({
         func: FabricSmoke,

package/dist/src/fabric/functions/validate.function.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
-export declare const FabricValidateInput: z.ZodObject<{}, z.core.$strip>;
+export declare const FabricValidateInput: z.ZodObject<{
+    skipTypecheck: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
 export declare const FabricValidateOutput: z.ZodObject<{
     ok: z.ZodBoolean;
     root: z.ZodString;
@@ -15,8 +17,12 @@ export declare const FabricValidateOutput: z.ZodObject<{
         fixHint: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export declare function runValidate(startDir?: string): Promise<z.infer<typeof FabricValidateOutput>>;
-export declare const FabricValidate: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<Record<string, never>, {
+export declare function runValidate(startDir?: string, opts?: {
+    skipTypecheck?: boolean;
+}): Promise<z.infer<typeof FabricValidateOutput>>;
+export declare const FabricValidate: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
+    skipTypecheck?: boolean | undefined;
+}, {
     ok: boolean;
     root: string;
     findings: {
@@ -26,7 +32,9 @@ export declare const FabricValidate: import("../../../.pikku/pikku-types.gen.js"
         path: string;
         fixHint: string;
     }[];
-}, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<Record<string, never>, {
+}, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
+    skipTypecheck?: boolean | undefined;
+}, {
     ok: boolean;
     root: string;
     findings: {
@@ -36,7 +44,9 @@ export declare const FabricValidate: import("../../../.pikku/pikku-types.gen.js"
         path: string;
         fixHint: string;
     }[];
-}, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<Record<string, never>, {
+}, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<{
+    skipTypecheck?: boolean | undefined;
+}, {
     ok: boolean;
     root: string;
     findings: {

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

@@ -5,6 +5,7 @@ import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
 import { pikkuSessionlessFunc } from '../../../.pikku/pikku-types.gen.js';
 import { added, changed, removed, dim } from '../lib/output.js';
+import { typeCheckFrontends } from '../lib/frontend-typecheck.js';
 const FindingSchema = z.object({
     id: z.string(),
     severity: z.enum(['error', 'warn', 'info']),
@@ -12,7 +13,12 @@ const FindingSchema = z.object({
     path: z.string(),
     fixHint: z.string(),
 });
-export const FabricValidateInput = z.object({});
+export const FabricValidateInput = z.object({
+    skipTypecheck: z
+        .boolean()
+        .optional()
+        .describe('Skip the frontend type-check stage (structural checks only, much faster)'),
+});
 export const FabricValidateOutput = z.object({
     ok: z.boolean(),
     root: z.string(),
@@ -182,7 +188,7 @@ const POSTGRES_SQL_PATTERNS = [
     { re: /\bTSVECTOR\b/i, label: 'TSVECTOR' },
     { re: /\bARRAY\s*\[/i, label: 'ARRAY[…]' },
 ];
-export async function runValidate(startDir = process.cwd()) {
+export async function runValidate(startDir = process.cwd(), opts = {}) {
     const root = await findProjectRoot(startDir);
     const findings = [];
     const e = (id, message, path, fixHint) => {
@@ -838,19 +844,47 @@ export async function runValidate(startDir = process.cwd()) {
             info('config-missing', 'packages/functions/src/config.ts not found', join(fnDir, 'src', 'config.ts'), "Create src/config.ts: export const createConfig = pikkuConfig(async () => ({ sqliteDb: '.pikku-runtime/dev.db' }))");
         }
     }
+    // ── declared frontends ────────────────────────────────────────────────
+    // pikkufabric.config.json is unvalidated JSON, so every field below is a
+    // claim, not a guarantee: a null entry or a non-string cwd used to throw on
+    // property access and take down the whole validation run — the one thing that
+    // was supposed to report the broken config. Shape-check the entries once here
+    // and let the apps/ and type-check passes consume the narrowed list.
+    const declaredFrontends = [];
+    /** every syntactically valid cwd, including ones whose directory is missing */
+    const declaredCwdList = [];
+    const rawFrontends = fabricConfig?.frontends;
+    if (rawFrontends !== undefined &&
+        (!rawFrontends || typeof rawFrontends !== 'object')) {
+        e('frontends-invalid', 'pikkufabric.config.json "frontends" is not an object — no frontend will be built or type-checked', fabricConfigPath, `Set "frontends" to an object keyed by slug: { "app": { "cwd": "apps/app", "kind": "ssr" } }`);
+    }
+    else if (rawFrontends) {
+        for (const [slug, entry] of Object.entries(rawFrontends)) {
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+                e(`frontend-entry-invalid-${slug}`, `pikkufabric.config.json frontend "${slug}" is not an object`, fabricConfigPath, `Give "${slug}" an object value: { "cwd": "apps/${slug}", "kind": "ssr" }`);
+                continue;
+            }
+            const { cwd, deploy } = entry;
+            if (typeof cwd !== 'string' || cwd.trim() === '') {
+                e(`frontend-cwd-invalid-${slug}`, `pikkufabric.config.json frontend "${slug}" has no string "cwd" — the build container has nothing to build`, fabricConfigPath, `Set "cwd" to the app directory, e.g. { "${slug}": { "cwd": "apps/${slug}" } }`);
+                continue;
+            }
+            const rel = cwd.replace(/^\.\//, '');
+            declaredCwdList.push(rel);
+            const dir = join(root, rel);
+            if (!existsSync(dir)) {
+                // Reported here rather than inside the apps/ block below: a project
+                // without an apps/ directory used to validate cleanly while declaring a
+                // deployable frontend that does not exist.
+                e(`frontend-cwd-missing-${slug}`, `fabric.config.json frontend "${slug}" declares cwd "${rel}" but that directory does not exist`, dir, `Create the directory or update the cwd in fabric.config.json`);
+                continue;
+            }
+            declaredFrontends.push({ slug, cwd: rel, dir, deploy: deploy !== false });
+        }
+    }
     // ── apps/ vs fabric.config.json frontends ─────────────────────────────
     const appsDir = join(root, 'apps');
     if (existsSync(appsDir)) {
-        // Check declared frontends have a real directory on disk
-        if (fabricConfig) {
-            const frontends = (fabricConfig.frontends ?? {});
-            for (const [slug, fe] of Object.entries(frontends)) {
-                const cwd = fe.cwd?.replace(/^\.\//, '');
-                if (cwd && !existsSync(join(root, cwd))) {
-                    e(`frontend-cwd-missing-${slug}`, `fabric.config.json frontend "${slug}" declares cwd "${cwd}" but that directory does not exist`, join(root, cwd), `Create the directory or update the cwd in fabric.config.json`);
-                }
-            }
-        }
         // Check each app/ subdir is declared and has correct local deps
         let appEntries = [];
         try {
@@ -861,9 +895,7 @@ export async function runValidate(startDir = process.cwd()) {
         catch {
             /* ignore */
         }
-        const declaredCwds = fabricConfig
-            ? new Set(Object.values((fabricConfig.frontends ?? {})).map((f) => f.cwd?.replace(/^\.\//, '') ?? ''))
-            : null;
+        const declaredCwds = fabricConfig ? new Set(declaredCwdList) : null;
         for (const name of appEntries) {
             const appPath = join(appsDir, name);
             const cwd = `apps/${name}`;
@@ -1119,6 +1151,27 @@ export async function runValidate(startDir = process.cwd()) {
     if (!existsSync(sdkDir)) {
         info('functions-sdk-missing', 'packages/functions-sdk/ not found — generated RPC client and React Query hooks will not be available', sdkDir, lines('Create a workspace at `packages/functions-sdk/`.', 'Minimum structure:', '- packages/functions-sdk/package.json', '- packages/functions-sdk/src/pikku/', 'Point `pikku.config.json` clientFiles to:', '- packages/functions-sdk/src/pikku/rpc-map.gen.d.ts', '- packages/functions-sdk/src/pikku/api.gen.ts', 'This package is the home for generated client artifacts, not handwritten server code.'));
     }
+    // ── frontend type-check (what the build container actually runs) ───────
+    // Every check above is a heuristic standing in for this compile. The build
+    // container type-checks each deployable frontend and aborts the deploy on a
+    // non-zero exit, so running the same compile here is the difference between
+    // a 20-second local failure and a burned deploy out of the daily 10.
+    if (!opts.skipTypecheck) {
+        const frontends = declaredFrontends
+            .filter((fe) => fe.deploy)
+            .map((fe) => ({ name: fe.slug, dir: fe.dir }));
+        for (const result of await typeCheckFrontends(root, frontends)) {
+            if (result.skipped) {
+                w(`frontend-typecheck-skipped-${result.name}`, `could not type-check frontend "${result.name}" — ${result.skipped}`, result.dir, lines('The build container type-checks every deployable frontend and aborts the deploy if it fails.', 'Give the app a tsconfig.json and a "tsc" script so the same check runs locally.'));
+                continue;
+            }
+            if (result.errors.length === 0)
+                continue;
+            const shown = result.errors.slice(0, 20);
+            const extra = result.errors.length - shown.length;
+            e(`frontend-typecheck-${result.name}`, `frontend "${result.name}" does not type-check — the build container aborts the deploy on this`, result.dir, lines(...shown, ...(extra > 0 ? [`… and ${extra} more`] : []), '', `Reproduce with: cd ${result.dir.slice(root.length + 1)} && ${result.command}`));
+        }
+    }
     const ok = !findings.some((f) => f.severity === 'error');
     return { ok, root, findings };
 }
@@ -1126,7 +1179,7 @@ export const FabricValidate = pikkuSessionlessFunc({
     description: 'Check the current project structure for fabric compatibility. Prints all missing or misconfigured items with fix hints so an AI agent or developer can resolve them.',
     input: FabricValidateInput,
     output: FabricValidateOutput,
-    func: async (_services) => runValidate(),
+    func: async (_services, { skipTypecheck }) => runValidate(process.cwd(), { skipTypecheck }),
 });
 export const renderValidate = (_s, { ok, root, findings }) => {
     if (findings.length === 0) {

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

@@ -50,7 +50,17 @@ export declare function findProjectConfig(startDir?: string): Promise<{
  * 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>;
+/**
+ * Merge into the existing config rather than replacing it. `link` and `init`
+ * only know the projectId, so a plain write silently deleted every other key —
+ * including `frontends`, which is what tells the build container an app exists.
+ * The symptom is a deploy that succeeds having built no frontend at all, long
+ * after the link that caused it. Unknown keys are preserved too; nothing here
+ * has any business dropping config it does not understand.
+ */
+export declare function writeProjectConfig(cwd: string, config: Partial<ProjectConfig> & {
+    projectId: string;
+}): Promise<string>;
 export declare function readAuthFile(): Promise<AuthFile>;
 export declare function writeAuthFile(file: AuthFile): Promise<void>;
 export interface ResolvedApiContext {

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

@@ -31,10 +31,48 @@ export function isLinkedProjectId(projectId) {
         return false;
     return !/^__.*__$/.test(projectId);
 }
+/**
+ * Merge into the existing config rather than replacing it. `link` and `init`
+ * only know the projectId, so a plain write silently deleted every other key —
+ * including `frontends`, which is what tells the build container an app exists.
+ * The symptom is a deploy that succeeds having built no frontend at all, long
+ * after the link that caused it. Unknown keys are preserved too; nothing here
+ * has any business dropping config it does not understand.
+ */
 export async function writeProjectConfig(cwd, config) {
     const path = join(cwd, projectConfigName);
+    let existing = {};
+    if (existsSync(path)) {
+        // A read that fails for any reason other than the file's contents —
+        // permissions, a transient I/O error — tells us nothing about what the file
+        // holds. Rewriting it then is the exact clobber this function exists to
+        // prevent, so refuse the write instead.
+        let raw;
+        try {
+            raw = await readFile(path, 'utf8');
+        }
+        catch (error) {
+            throw new Error(`Cannot read ${projectConfigName} at ${path} (${error.message}) — refusing to overwrite it`);
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                existing = parsed;
+            }
+            else {
+                // Valid JSON that is not an object holds nothing we can merge, but it is
+                // still the user's file — say so rather than dropping it silently.
+                console.warn(`[fabric] ${projectConfigName} is not a JSON object — rewriting it`);
+            }
+        }
+        catch (error) {
+            // An unparseable config is not a reason to lose the link; warn and start
+            // fresh rather than throwing away the command the user just ran.
+            console.warn(`[fabric] ${projectConfigName} is not valid JSON (${error.message}) — rewriting it`);
+        }
+    }
     await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    await writeFile(path, JSON.stringify({ ...existing, ...config }, null, 2) + '\n', 'utf8');
     return path;
 }
 export async function readAuthFile() {