@fabrika/app 0.9.0-dev.2 → 0.9.0-dev.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/app",
-	"version": "0.9.0-dev.2",
+	"version": "0.9.0-dev.4",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -93,6 +93,11 @@
 			"types": "./types/src/dev/wire.d.ts",
 			"default": "./src/dev/wire.ts"
 		},
+		"./dev/changes": {
+			"bun": "./src/dev/changes.ts",
+			"types": "./types/src/dev/changes.d.ts",
+			"default": "./src/dev/changes.ts"
+		},
 		"./agent-skill": {
 			"bun": "./src/agent-skill.ts",
 			"types": "./types/src/agent-skill.d.ts",
@@ -104,14 +109,14 @@
 		"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
 	},
 	"dependencies": {
-		"@fabrika/auth": "0.9.0-dev.2",
-		"@fabrika/auth-core": "0.9.0-dev.2",
-		"@fabrika/db": "0.9.0-dev.2",
-		"@fabrika/email": "0.9.0-dev.2",
-		"@fabrika/jwks": "0.9.0-dev.2",
-		"@fabrika/platform": "0.9.0-dev.2",
-		"@fabrika/platform-node": "0.9.0-dev.2",
-		"@fabrika/proxy-core": "0.9.0-dev.2",
+		"@fabrika/auth": "0.9.0-dev.4",
+		"@fabrika/auth-core": "0.9.0-dev.4",
+		"@fabrika/db": "0.9.0-dev.4",
+		"@fabrika/email": "0.9.0-dev.4",
+		"@fabrika/jwks": "0.9.0-dev.4",
+		"@fabrika/platform": "0.9.0-dev.4",
+		"@fabrika/platform-node": "0.9.0-dev.4",
+		"@fabrika/proxy-core": "0.9.0-dev.4",
 		"altcha-lib": "2.6.0",
 		"jose": "^5.9.0"
 	},

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabrika-app
-version: 0.9.0-dev.2
+version: 0.9.0-dev.4
 description: >
   How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
   slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors

package/skill/references/app-setup.md

@@ -19,20 +19,20 @@ the SPA is added with it.
 		"test": "bun test --isolate"
 	},
 	"dependencies": {
-		"@fabrika/app": "0.9.0-dev.2",
-		"@fabrika/db": "0.9.0-dev.2",
-		"@fabrika/provider-zerops": "0.9.0-dev.2",
-		"@fabrika/proxy-core": "0.9.0-dev.2",
-		"@fabrika/ui": "0.9.0-dev.2",
+		"@fabrika/app": "0.9.0-dev.4",
+		"@fabrika/db": "0.9.0-dev.4",
+		"@fabrika/provider-zerops": "0.9.0-dev.4",
+		"@fabrika/proxy-core": "0.9.0-dev.4",
+		"@fabrika/ui": "0.9.0-dev.4",
 		"kysely": "0.29.6",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"zod": "^3.25.76"
 	},
 	"devDependencies": {
-		"@fabrika/check": "0.9.0-dev.2",
-		"@fabrika/cli": "0.9.0-dev.2",
-		"@fabrika/platform": "0.9.0-dev.2",
+		"@fabrika/check": "0.9.0-dev.4",
+		"@fabrika/cli": "0.9.0-dev.4",
+		"@fabrika/platform": "0.9.0-dev.4",
 		"@happy-dom/global-registrator": "^20.11.2",
 		"@types/bun": "latest",
 		"@types/react": "^19.0.0",

package/src/dev/launcher.ts

@@ -18,7 +18,7 @@ import { fileURLToPath } from 'node:url'
 import { z } from 'zod/v4'
 import { makeProcessUndumpable } from '../undumpable.js'
 import { bootstrapReason, migrationsChanged, webSourceChanged } from './changes.js'
-import { OutputRing, type OutputSink, processOutput, readLines } from './output.js'
+import { OutputRing, type OutputSink, type OutputStream, processOutput, readLines } from './output.js'
 import {
 	DEV_SOURCE_REPORT_PATH,
 	DEV_SOURCE_WAIT_MS,
@@ -123,13 +123,23 @@ interface RunningApplication {
 
 interface CommandResult {
 	readonly exitCode: number | null
+	/** The signal that ended the command, when one did: it never exited on its own. */
+	readonly signal: string | null
 	readonly lines: readonly string[]
 }
 
+/** Bun echoes the script it runs (`$ bun build-web.ts`) on stderr; it names the command, not a failure. */
+const BUN_SCRIPT_ECHO = /^\$ \S/
+
 type SyncOutcome =
-	| { readonly kind: 'applied'; readonly migrations: boolean; readonly web: boolean }
+	| { readonly kind: 'applied'; readonly migrations: boolean; readonly spaFailure: string | null }
 	| { readonly kind: 'refused'; readonly reason: string }
 
+/** Control answers 409 to the container of a bootstrap run that a newer one replaced. */
+class SupersededError extends Error {}
+
+const SUPERSEDED = 'a newer bootstrap run replaced this container; it stops following Control and serves until it is stopped'
+
 const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
 
 /** Every value of the environment a log line must never show: the database credentials and every key, secret or token. */
@@ -176,6 +186,8 @@ class Launcher {
 	private crashes = 0
 	private stopped = false
 	private reportFailing = false
+	/** A newer bootstrap run replaced this container: it keeps serving until the platform stops it, and asks nothing. */
+	private superseded = false
 
 	constructor(private readonly options: DevLauncherOptions) {
 		this.root = options.root
@@ -225,7 +237,12 @@ class Launcher {
 		while (!this.stopped) {
 			try {
 				return await this.wait(false)
-			} catch {
+			} catch (error) {
+				if (error instanceof SupersededError) {
+					this.say(SUPERSEDED, 'stderr')
+					this.superseded = true
+					return null
+				}
 				if (Date.now() >= deadline) {
 					this.say('Control did not answer at boot; serving the files this container holds', 'stderr')
 					return null
@@ -238,13 +255,18 @@ class Launcher {
 
 	private async follow(): Promise<void> {
 		let backoff = 1_000
-		while (!this.stopped) {
+		while (!this.stopped && !this.superseded) {
 			let answer: DevWaitAnswer
 			try {
 				answer = await this.wait(true)
 				backoff = 1_000
-			} catch {
+			} catch (error) {
 				if (this.stopped) return
+				if (error instanceof SupersededError) {
+					this.say(SUPERSEDED, 'stderr')
+					this.superseded = true
+					return
+				}
 				this.say(`the long poll on Control failed; retrying in ${backoff / 1000} s`, 'stderr')
 				await sleep(backoff)
 				backoff = Math.min(backoff * 2, 15_000)
@@ -255,9 +277,19 @@ class Launcher {
 	}
 
 	private async wait(hold: boolean): Promise<DevWaitAnswer> {
-		const body = encodeDevWaitRequest({ head: this.state.head, reset: this.state.reset, checks: this.state.checks, hold })
+		const body = encodeDevWaitRequest({
+			bootstrap: this.config.head,
+			head: this.state.head,
+			reset: this.state.reset,
+			checks: this.state.checks,
+			hold,
+		})
 		const signal = AbortSignal.any([this.controller.signal, AbortSignal.timeout(DEV_SOURCE_WAIT_MS + 15_000)])
 		const response = await this.fetch(this.request(DEV_SOURCE_WAIT_PATH, body, signal))
+		if (response.status === 409) {
+			await response.body?.cancel()
+			throw new SupersededError()
+		}
 		if (!response.ok) throw new Error(`the source receiver answered ${response.status}`)
 		const parsed = parseDevWaitAnswer(await response.json())
 		if (!parsed.ok) throw new Error('the source receiver answered a body this release does not read')
@@ -274,7 +306,9 @@ class Launcher {
 	}
 
 	private async report(): Promise<void> {
+		if (this.superseded) return
 		const body = encodeDevReport({
+			bootstrap: this.config.head,
 			head: this.state.head,
 			status: this.status,
 			target: this.target,
@@ -299,7 +333,9 @@ class Launcher {
 		if (this.state.checks === null) this.state = { ...this.state, checks: answer.checks }
 		let changed = boot
 		let migrate = boot
-		let web = false
+		let spaFailure: string | null = null
+		const reset = answer.reset > (this.state.reset ?? answer.reset)
+		if (answer.sync !== null || reset) this.ring.mark()
 		if (answer.sync !== null) {
 			const outcome = await this.writeSync(answer.sync)
 			if (outcome.kind === 'refused') {
@@ -311,16 +347,15 @@ class Launcher {
 			} else {
 				changed = true
 				migrate ||= outcome.migrations
-				web = outcome.web
+				spaFailure = outcome.spaFailure
 			}
 		}
-		const reset = answer.reset > (this.state.reset ?? answer.reset)
-		if (changed || reset) await this.converge({ migrate: migrate || reset, reset, web, resetTo: answer.reset })
+		if (changed || reset) await this.converge({ migrate: migrate || reset, reset, spaFailure, resetTo: answer.reset })
 		if (answer.checks > (this.state.checks ?? answer.checks)) await this.check(answer.checks)
 	}
 
 	/** Bring the database, the SPA and the running application to the files on disk, then report. */
-	private async converge(steps: { migrate: boolean; reset: boolean; web: boolean; resetTo: number }): Promise<void> {
+	private async converge(steps: { migrate: boolean; reset: boolean; spaFailure: string | null; resetTo: number }): Promise<void> {
 		this.status = steps.reset ? 'resetting' : 'syncing'
 		void this.report()
 		let failure: string | null = null
@@ -331,7 +366,7 @@ class Launcher {
 			this.state = { ...this.state, reset: steps.resetTo }
 		}
 		if (failure === null && steps.migrate) failure = await this.timed('the migration', () => this.migrate())
-		if (failure === null && steps.web) failure = await this.timed('the SPA build', () => this.buildSpa())
+		if (failure === null) failure = steps.spaFailure
 		const served = await this.timed('the restart until healthy', () => this.restartApplication())
 		failure ??= served
 		this.status = failure === null ? 'serving' : 'failed'
@@ -360,14 +395,21 @@ class Launcher {
 			sync.files.map(async (file) => ({ path: file.path, content: await readFile(join(this.root, file.path)).catch(() => null) })),
 		)
 		await this.writeFiles(sync.files)
-		const changedContract = await this.contractChange()
+		const web = this.config.spaBuild.length > 0 && webSourceChanged(paths)
+		// The SPA build runs beside the digest: a refusal is rare, and then the build runs again over the restored files.
+		const [changedContract, spaFailure] = await Promise.all([this.contractChange(), web ? this.spaBuild() : null])
 		if (changedContract !== null) {
 			await this.writeFiles(previous)
+			if (web) await this.spaBuild()
 			return { kind: 'refused', reason: changedContract }
 		}
 		this.state = { ...this.state, head: sync.to }
 		this.say(`synced ${sync.files.length} files to ${sync.to}`)
-		return { kind: 'applied', migrations: migrationsChanged(paths), web: this.config.spaBuild.length > 0 && webSourceChanged(paths) }
+		return { kind: 'applied', migrations: migrationsChanged(paths), spaFailure }
+	}
+
+	private spaBuild(): Promise<string | null> {
+		return this.timed('the SPA build', () => this.buildSpa())
 	}
 
 	private async writeFiles(files: readonly { readonly path: string; readonly content: string | Uint8Array | null }[]): Promise<void> {
@@ -447,7 +489,12 @@ class Launcher {
 
 	private async buildSpa(): Promise<string | null> {
 		for (const command of this.config.spaBuild) {
-			const result = await this.run(['sh', '-c', command], this.commandEnvironment)
+			const result = await this.run(
+				['sh', '-c', command],
+				this.commandEnvironment,
+				CHECK_TIMEOUT_MS,
+				(stream, line) => stream === 'stderr' && BUN_SCRIPT_ECHO.test(line) ? 'stdout' : stream,
+			)
 			if (result.exitCode !== 0) return `the SPA command \`${command}\` failed: ${lastLine(result)}`
 		}
 		return null
@@ -460,12 +507,17 @@ class Launcher {
 		const results: DevCheckResult[] = []
 		for (const check of this.config.checks) {
 			this.say(`check ${check.name}: ${check.command}`)
+			const started = performance.now()
 			const result = await this.run(['sh', '-c', check.command], this.commandEnvironment, CHECK_TIMEOUT_MS)
+			const durationMs = Math.round(performance.now() - started)
+			const killed = result.signal === null ? [] : [killedLine(check.name, result.signal, durationMs >= CHECK_TIMEOUT_MS)]
+			for (const line of killed) this.say(line, 'stderr')
 			results.push({
 				name: check.name,
 				ok: result.exitCode === 0,
 				exitCode: result.exitCode,
-				output: result.lines.slice(-CHECK_OUTPUT_LINES).map((line) => line.slice(0, 2_000)),
+				durationMs,
+				output: [...result.lines.slice(-(CHECK_OUTPUT_LINES - killed.length)), ...killed].map((line) => line.slice(0, 2_000)),
 			})
 		}
 		this.checkResults = { request, head: this.state.head, results }
@@ -477,17 +529,22 @@ class Launcher {
 	}
 
 	/** Run a command in the root; its output goes to the log, and its lines are returned. */
-	private async run(argv: readonly string[], env: Record<string, string>, timeoutMs = CHECK_TIMEOUT_MS): Promise<CommandResult> {
+	private async run(
+		argv: readonly string[],
+		env: Record<string, string>,
+		timeoutMs = CHECK_TIMEOUT_MS,
+		classify: (stream: OutputStream, line: string) => OutputStream = (stream) => stream,
+	): Promise<CommandResult> {
 		const child = Bun.spawn([...argv], { cwd: this.root, env, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
 		const lines: string[] = []
-		const collect = (stream: 'stdout' | 'stderr') => (line: string) => {
+		const collect = (stream: OutputStream) => (line: string) => {
 			lines.push(line)
-			this.ring.push(stream, line)
+			this.ring.push(classify(stream, line), line)
 		}
 		const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs)
 		await Promise.all([readLines(child.stdout, collect('stdout')), readLines(child.stderr, collect('stderr')), child.exited])
 		clearTimeout(timer)
-		return { exitCode: child.exitCode, lines }
+		return { exitCode: child.exitCode, signal: child.signalCode === null ? null : String(child.signalCode), lines }
 	}
 
 	private async restartApplication(): Promise<string | null> {
@@ -571,6 +628,12 @@ class Launcher {
 	}
 }
 
+/** Why a check has no exit code: the launcher's timeout, or a signal from outside, most often the out-of-memory killer. */
+const killedLine = (name: string, signal: string, timedOut: boolean): string =>
+	timedOut
+		? `check ${name} was killed (${signal}) after the ${CHECK_TIMEOUT_MS / 60_000}-minute timeout; it failed`
+		: `check ${name} was killed (${signal}) before it finished, most likely because the container ran out of memory; it failed`
+
 const lastLine = (result: CommandResult): string => [...result.lines].reverse().find((line) => line.trim() !== '')?.trim() ?? 'no output'
 
 /** The process environment with its string values only. */

package/src/dev/output.ts

@@ -16,10 +16,14 @@ export const processOutput: OutputSink = {
 	},
 }
 
-/** The newest `capacity` lines, numbered from 0 since the launcher started, with every known secret value replaced. */
+/**
+ * The newest `capacity` lines, numbered from 0 since the launcher started, with every known secret value replaced. A
+ * mark starts the lines a report carries: those of the newest sync or reset, and the output after it.
+ */
 export class OutputRing {
 	private readonly lines: DevLogLine[] = []
 	private next = 0
+	private marked = 0
 
 	constructor(private readonly capacity: number, private readonly secrets: readonly string[], private readonly sink: OutputSink) {}
 
@@ -31,9 +35,15 @@ export class OutputRing {
 		if (this.lines.length > this.capacity) this.lines.shift()
 	}
 
-	/** The newest `count` lines, oldest first. */
+	/** Report from the next line on: the lines before it belong to an older head. */
+	mark(): void {
+		this.marked = this.next
+	}
+
+	/** The newest `count` lines since the mark, oldest first. */
 	tail(count: number): DevLogLine[] {
-		return this.lines.slice(Math.max(0, this.lines.length - count))
+		const since = this.lines.filter((line) => line.n >= this.marked)
+		return since.slice(Math.max(0, since.length - count))
 	}
 
 	private redact(text: string): string {

package/src/dev/wire.ts

@@ -32,7 +32,14 @@ export function isSourcePath(path: string): boolean {
 
 const sourcePath = z.string().refine(isSourcePath, 'not a repository-relative path')
 
+/**
+ * The commit the container's bootstrap run built (`DevLauncherConfig.head`). Control answers only the container of the
+ * newest bootstrap run: a container a newer bootstrap replaces still runs for a while, and must not sync or report.
+ */
+const bootstrap = commitSha
+
 export const devWaitRequestSchema = z.object({
+	bootstrap,
 	/** The commit whose files the container holds now. */
 	head: commitSha,
 	/** The reset generation it applied last; null for a container with no record of one, which adopts the answer's. */
@@ -81,6 +88,7 @@ export const devCheckResultSchema = z.object({
 	name: z.string().min(1).max(64),
 	ok: z.boolean(),
 	exitCode: z.number().int().nullable(),
+	durationMs: z.number().int().min(0),
 	/** The last lines of its output. */
 	output: z.array(z.string().max(DEV_REPORT_MAX_LINE_CHARACTERS)).max(DEV_REPORT_MAX_LINES),
 }).strict()
@@ -88,6 +96,7 @@ export const devCheckResultSchema = z.object({
 export type DevCheckResult = z.infer<typeof devCheckResultSchema>
 
 export const devReportSchema = z.object({
+	bootstrap,
 	/** The commit whose files the container holds now. */
 	head: commitSha,
 	status: z.enum(DEV_STATUSES),

package/types/src/dev/output.d.ts

@@ -5,16 +5,22 @@ export interface OutputSink {
 }
 /** The launcher process's own stdout and stderr. */
 export declare const processOutput: OutputSink;
-/** The newest `capacity` lines, numbered from 0 since the launcher started, with every known secret value replaced. */
+/**
+ * The newest `capacity` lines, numbered from 0 since the launcher started, with every known secret value replaced. A
+ * mark starts the lines a report carries: those of the newest sync or reset, and the output after it.
+ */
 export declare class OutputRing {
     private readonly capacity;
     private readonly secrets;
     private readonly sink;
     private readonly lines;
     private next;
+    private marked;
     constructor(capacity: number, secrets: readonly string[], sink: OutputSink);
     push(stream: OutputStream, text: string): void;
-    /** The newest `count` lines, oldest first. */
+    /** Report from the next line on: the lines before it belong to an older head. */
+    mark(): void;
+    /** The newest `count` lines since the mark, oldest first. */
     tail(count: number): DevLogLine[];
     private redact;
 }

package/types/src/dev/wire.d.ts

@@ -15,6 +15,7 @@ export declare const DEV_REPORT_MAX_MESSAGE_CHARACTERS = 500;
  */
 export declare function isSourcePath(path: string): boolean;
 export declare const devWaitRequestSchema: z.ZodObject<{
+    bootstrap: z.ZodString;
     head: z.ZodString;
     reset: z.ZodNullable<z.ZodNumber>;
     checks: z.ZodNullable<z.ZodNumber>;
@@ -70,10 +71,12 @@ export declare const devCheckResultSchema: z.ZodObject<{
     name: z.ZodString;
     ok: z.ZodBoolean;
     exitCode: z.ZodNullable<z.ZodNumber>;
+    durationMs: z.ZodNumber;
     output: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
 export type DevCheckResult = z.infer<typeof devCheckResultSchema>;
 export declare const devReportSchema: z.ZodObject<{
+    bootstrap: z.ZodString;
     head: z.ZodString;
     status: z.ZodEnum<{
         failed: "failed";
@@ -101,6 +104,7 @@ export declare const devReportSchema: z.ZodObject<{
             name: z.ZodString;
             ok: z.ZodBoolean;
             exitCode: z.ZodNullable<z.ZodNumber>;
+            durationMs: z.ZodNumber;
             output: z.ZodArray<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;