@fabrika/app 0.8.2 → 0.9.0-cloudflare.1

package/src/testing/endpoint-access.ts

@@ -58,6 +58,13 @@ export type ReachOutcome = { readonly answered: true } | { readonly answered: fa
 /** Column → value of the row of the table that owns the endpoint's dimension, in both scopes: the author's seed. */
 export type Seed = Readonly<Record<string, SampleValue>>
 
+/**
+ * Table → column → value: one row of each application table the handler reads for the caller's own scope, seeded
+ * before a leak or an own case asks and removed once it is over, with every row that refers to it, so no other case
+ * finds it. Both scopes may see it, so its values are never counted as the other scope's.
+ */
+export type AppRows = Readonly<Record<string, Seed>>
+
 export interface EndpointAccessKit {
 	/**
 	 * A caller holding the endpoint's action in one scope names an object (`on`) or a scope value (`in`) of another;
@@ -66,16 +73,18 @@ export interface EndpointAccessKit {
 	denied(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<DeniedOutcome>
 	/**
 	 * A caller of the other scope asks first, then a caller of one scope asks for its own object (`on`), its list
-	 * (`over`) or, for every table that lies in the dimension, its scope value (`in`).
+	 * (`over`) or, for every table that lies in the dimension, its scope value (`in`). `appRows` are seeded first, as
+	 * for `own`.
 	 */
-	leaked(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<LeakOutcome>
+	leaked(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed, appRows?: AppRows): Promise<LeakOutcome>
 	/**
 	 * A caller that holds only the endpoint's action asks for its own object: a person or a script in its scope, or, on
 	 * a link mount, the holder of a link bound to the object. A write action reads its own target. Where IAM requires more
 	 * of the caller, it holds that too: a member manager an assigning role and the assigned role's actions, a link's
-	 * issuer the actions the link grants.
+	 * issuer the actions the link grants. `appRows` are the rows of application tables its handler reads (the guide a link
+	 * holder downloads), each seeded first.
 	 */
-	own(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed): Promise<DeniedOutcome>
+	own(endpoint: string, input: Readonly<Record<string, unknown>>, seed?: Seed, appRows?: AppRows): Promise<DeniedOutcome>
 	/**
 	 * An `app` or a `creates` endpoint asked by a caller who holds its action in one value of a dimension only, never
 	 * globally: refused (403), by the proxy for `app` and by IAM for `creates`, since both need a global grant.
@@ -724,147 +733,181 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 		return { fetch, rows: (await rowsIn(own, rowFields(input))).rows }
 	}
 
-	const accessKit: EndpointAccessKit = {
-		async denied(endpoint, input, seed = {}) {
-			const row = endpointOf(endpoint)
-			const { action, access } = row
-			if (access.form !== 'on' && access.form !== 'in') {
-				throw new Error(`${endpoint} has the access form ${access.form}; only on and in name an object or a scope value`)
-			}
-			const scopes = await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input)
-			const asked = addressing(input, access.from, scopes.other)
-			const { status } = await ask(row, holding(row, input, scopes.own.grants, scopes.own.chain), asked, scopes.own.chain)
-			return { status }
-		},
-		async leaked(endpoint, input, seed = {}) {
-			const row = endpointOf(endpoint)
-			const { action, access } = row
-			if (access.form === 'in') {
-				const scopes = await inScopesOf(action, access.dimension, fieldOf(row.input, access.from), seed)
-				const grants = (targets: readonly InTarget[]): Grant[] =>
-					targets.flatMap(({ target, chain }) => holding(row, input, [{ action, scope: { type: access.dimension, value: target } }], chain))
-				const marks: string[] = []
-				for (const side of scopes.other) {
-					const answer = await ask(row, grants(scopes.other), addressing(input, access.from, side), side.chain)
-					marks.push(...answer.marks)
+	// The cases of one call: `removals` takes the removal of the application rows it seeds, which `drained` runs once
+	// the call and the runs it kicked are over. A list per call, so a concurrent case never removes the rows another
+	// was given; the generated cases run one after another, since a row a required foreign key needed is shared.
+	const accessKitOf = (removals: (() => Promise<void>)[]): EndpointAccessKit => {
+		/** One row of each application table `appRows` names, for this call only. */
+		const seedAppRows = async (appRows: AppRows): Promise<void> => {
+			if (Object.keys(appRows).length === 0) return
+			removals.push((await postgres.seedApplicationRows(tables, appRows)).remove)
+		}
+
+		return {
+			async denied(endpoint, input, seed = {}) {
+				const row = endpointOf(endpoint)
+				const { action, access } = row
+				if (access.form !== 'on' && access.form !== 'in') {
+					throw new Error(`${endpoint} has the access form ${access.form}; only on and in name an object or a scope value`)
 				}
-				const answers = []
-				for (const side of scopes.own) {
-					answers.push(await ask(row, grants(scopes.own), addressing(input, access.from, side), side.chain))
+				const scopes = await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input)
+				const asked = addressing(input, access.from, scopes.other)
+				const { status } = await ask(row, holding(row, input, scopes.own.grants, scopes.own.chain), asked, scopes.own.chain)
+				return { status }
+			},
+			async leaked(endpoint, input, seed = {}, appRows = {}) {
+				const row = endpointOf(endpoint)
+				const { action, access } = row
+				if (access.form === 'in') {
+					await seedAppRows(appRows)
+					const scopes = await inScopesOf(action, access.dimension, fieldOf(row.input, access.from), seed)
+					const grants = (targets: readonly InTarget[]): Grant[] =>
+						targets.flatMap(({ target, chain }) => holding(row, input, [{ action, scope: { type: access.dimension, value: target } }], chain))
+					const marks: string[] = []
+					for (const side of scopes.other) {
+						const answer = await ask(row, grants(scopes.other), addressing(input, access.from, side), side.chain)
+						marks.push(...answer.marks)
+					}
+					const answers = []
+					for (const side of scopes.own) {
+						answers.push(await ask(row, grants(scopes.own), addressing(input, access.from, side), side.chain))
+					}
+					return leakOutcome(answers, [...scopes.values, ...marks])
 				}
-				return leakOutcome(answers, [...scopes.values, ...marks])
-			}
-			if (access.form !== 'on' && access.form !== 'over') {
-				throw new Error(`${endpoint} has the access form ${access.form}; only on, in and over answer with rows of a scope`)
-			}
-			const scopes = access.form === 'on'
-				? await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input)
-				: await listScopesOf(action, access.dimension)
-			const from = access.form === 'on' ? access.from : null
-			const other = await ask(
-				row,
-				holding(row, input, scopes.other.grants, scopes.other.chain),
-				addressing(input, from, scopes.other),
-				scopes.other.chain,
-			)
-			const answer = await ask(
-				row,
-				holding(row, input, scopes.own.grants, scopes.own.chain),
-				addressing(input, from, scopes.own),
-				scopes.own.chain,
-			)
-			return leakOutcome([answer], [...scopes.other.values, ...other.marks])
-		},
-		async own(endpoint, input, seed = {}) {
-			const row = endpointOf(endpoint)
-			const { action, access } = row
-			if (access.form !== 'on') {
-				throw new Error(`${endpoint} has the access form ${access.form}; only on addresses an object of its own`)
-			}
-			if (row.link !== null) {
-				const holder = await linkHolder(row, row.link, seed, input)
-				const { status } = await askAs(row, holder.fetch, { ...input, ...holder.rows })
+				if (access.form !== 'on' && access.form !== 'over') {
+					throw new Error(`${endpoint} has the access form ${access.form}; only on, in and over answer with rows of a scope`)
+				}
+				await seedAppRows(appRows)
+				const scopes = access.form === 'on'
+					? await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input)
+					: await listScopesOf(action, access.dimension)
+				const from = access.form === 'on' ? access.from : null
+				const other = await ask(
+					row,
+					holding(row, input, scopes.other.grants, scopes.other.chain),
+					addressing(input, from, scopes.other),
+					scopes.other.chain,
+				)
+				const answer = await ask(
+					row,
+					holding(row, input, scopes.own.grants, scopes.own.chain),
+					addressing(input, from, scopes.own),
+					scopes.own.chain,
+				)
+				return leakOutcome([answer], [...scopes.other.values, ...other.marks])
+			},
+			async own(endpoint, input, seed = {}, appRows = {}) {
+				const row = endpointOf(endpoint)
+				const { action, access } = row
+				if (access.form !== 'on') {
+					throw new Error(`${endpoint} has the access form ${access.form}; only on addresses an object of its own`)
+				}
+				await seedAppRows(appRows)
+				if (row.link !== null) {
+					const holder = await linkHolder(row, row.link, seed, input)
+					const { status } = await askAs(row, holder.fetch, { ...input, ...holder.rows })
+					return { status }
+				}
+				const scopes = await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input)
+				const { status } = await ask(
+					row,
+					holding(row, input, scopes.own.grants, scopes.own.chain),
+					addressing(input, access.from, scopes.own),
+					scopes.own.chain,
+				)
 				return { status }
+			},
+			async scoped(endpoint, input) {
+				const row = globalEndpointOf(endpoint)
+				const dimension = row.access.form === 'creates' ? row.access.dimension : scopeTypeOf(kit.artifact.dimensions)
+				const { status } = await ask(row, [{ action: row.action, scope: { type: dimension, value: freshValue(dimension, 'own', undefined) } }], input, [])
+				return { status }
+			},
+			async anyone(endpoint, input) {
+				const row = kit.artifact.endpoints.find((candidate) => candidate.id === endpoint)
+				if (row?.kind !== 'public') {
+					throw new Error(`${endpoint} is not a public procedure of the contract`)
+				}
+				const response = await kit.fetch(row.path, {
+					method: row.method,
+					headers: { 'Content-Type': 'application/json', Origin: kit.origin, 'Sec-Fetch-Site': 'same-origin' },
+					body: JSON.stringify(input),
+				})
+				const status = response.status
+				const challenged = status === 400 && errorType(await response.text()) === 'challenge_failed'
+				return status >= 500 || status === 401 || status === 403 || challenged ? { answered: false, status } : { answered: true }
+			},
+			async global(endpoint, input) {
+				const row = globalEndpointOf(endpoint)
+				const { status } = await askAs(row, callerFor(row, [], [{ action: row.action }]).fetch, input)
+				// Neither form refuses with 404, so a 404 is the handler's own answer (a row the sampled input names is missing).
+				return status >= 500 || status === 401 || status === 403 ? { answered: false, status } : { answered: true }
+			},
+			async capability(endpoint, capability, input, seed = {}) {
+				const capabilities = capabilitiesEndpointOf(endpoint)
+				const named = capabilities.get(capability)
+				if (named === undefined) {
+					throw new Error(`${endpoint} has no capability '${capability}' (capabilities: ${[...capabilities.keys()].join(', ')})`)
+				}
+				const grants: Grant[] = []
+				const global: { readonly action: string }[] = []
+				let asked = input
+				for (const [name, other] of capabilities) {
+					if (name === capability) continue
+					if (other.access.form === 'over') {
+						global.push({ action: other.action })
+					} else if (other.access.form === 'on' || other.access.form === 'in') {
+						const { own } = await scopesOf(other.action, other.access.dimension, fieldOf(other.input, other.access.from), {}, input)
+						asked = addressing(asked, other.access.from, own)
+						grants.push(...own.grants)
+					}
+				}
+				const { access } = named
+				if (access.form === 'on' || access.form === 'in') {
+					const scopes = await scopesOf(named.action, access.dimension, fieldOf(named.input, access.from), seed, input)
+					asked = addressing(asked, access.from, scopes.other)
+					grants.push(...scopes.own.grants)
+				}
+				const { status } = await askAs(named, callerFor(named, grants, global).fetch, asked)
+				return { status }
+			},
+		}
+	}
+	// Each case waits for the runs its requests kicked, so the suite's teardown never closes the database under one, and
+	// only then removes its application rows, which those runs may still read. Every step runs whatever failed before
+	// it, and the case's own error is thrown first.
+	const drained =
+		<A extends readonly unknown[], R>(method: (kit: EndpointAccessKit) => (...args: A) => Promise<R>) => async (...args: A): Promise<R> => {
+			const removals: (() => Promise<void>)[] = []
+			let outcome: { readonly ok: true; readonly value: R } | { readonly ok: false; readonly error: unknown }
+			try {
+				outcome = { ok: true, value: await method(accessKitOf(removals))(...args) }
+			} catch (error) {
+				outcome = { ok: false, error }
 			}
-			const scopes = await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input)
-			const { status } = await ask(
-				row,
-				holding(row, input, scopes.own.grants, scopes.own.chain),
-				addressing(input, access.from, scopes.own),
-				scopes.own.chain,
-			)
-			return { status }
-		},
-		async scoped(endpoint, input) {
-			const row = globalEndpointOf(endpoint)
-			const dimension = row.access.form === 'creates' ? row.access.dimension : scopeTypeOf(kit.artifact.dimensions)
-			const { status } = await ask(row, [{ action: row.action, scope: { type: dimension, value: freshValue(dimension, 'own', undefined) } }], input, [])
-			return { status }
-		},
-		async anyone(endpoint, input) {
-			const row = kit.artifact.endpoints.find((candidate) => candidate.id === endpoint)
-			if (row?.kind !== 'public') {
-				throw new Error(`${endpoint} is not a public procedure of the contract`)
-			}
-			const response = await kit.fetch(row.path, {
-				method: row.method,
-				headers: { 'Content-Type': 'application/json', Origin: kit.origin, 'Sec-Fetch-Site': 'same-origin' },
-				body: JSON.stringify(input),
-			})
-			const status = response.status
-			const challenged = status === 400 && errorType(await response.text()) === 'challenge_failed'
-			return status >= 500 || status === 401 || status === 403 || challenged ? { answered: false, status } : { answered: true }
-		},
-		async global(endpoint, input) {
-			const row = globalEndpointOf(endpoint)
-			const { status } = await askAs(row, callerFor(row, [], [{ action: row.action }]).fetch, input)
-			// Neither form refuses with 404, so a 404 is the handler's own answer (a row the sampled input names is missing).
-			return status >= 500 || status === 401 || status === 403 ? { answered: false, status } : { answered: true }
-		},
-		async capability(endpoint, capability, input, seed = {}) {
-			const capabilities = capabilitiesEndpointOf(endpoint)
-			const named = capabilities.get(capability)
-			if (named === undefined) {
-				throw new Error(`${endpoint} has no capability '${capability}' (capabilities: ${[...capabilities.keys()].join(', ')})`)
-			}
-			const grants: Grant[] = []
-			const global: { readonly action: string }[] = []
-			let asked = input
-			for (const [name, other] of capabilities) {
-				if (name === capability) continue
-				if (other.access.form === 'over') {
-					global.push({ action: other.action })
-				} else if (other.access.form === 'on' || other.access.form === 'in') {
-					const { own } = await scopesOf(other.action, other.access.dimension, fieldOf(other.input, other.access.from), {}, input)
-					asked = addressing(asked, other.access.from, own)
-					grants.push(...own.grants)
+			const failures: unknown[] = []
+			for (const step of [() => kit.drain(), ...removals]) {
+				try {
+					await step()
+				} catch (error) {
+					failures.push(error)
 				}
 			}
-			const { access } = named
-			if (access.form === 'on' || access.form === 'in') {
-				const scopes = await scopesOf(named.action, access.dimension, fieldOf(named.input, access.from), seed, input)
-				asked = addressing(asked, access.from, scopes.other)
-				grants.push(...scopes.own.grants)
+			if (!outcome.ok) {
+				if (failures.length === 0) throw outcome.error
+				throw new AggregateError([outcome.error, ...failures], 'the case failed, and so did its cleanup')
 			}
-			const { status } = await askAs(named, callerFor(named, grants, global).fetch, asked)
-			return { status }
-		},
-	}
-	// Each case waits for the runs its requests kicked, so the suite's teardown never closes the database under one.
-	const drained = <A extends readonly unknown[], R>(method: (...args: A) => Promise<R>) => async (...args: A): Promise<R> => {
-		try {
-			return await method(...args)
-		} finally {
-			await kit.drain()
+			if (failures.length === 1) throw failures[0]
+			if (failures.length > 1) throw new AggregateError(failures, 'the cleanup of the case failed')
+			return outcome.value
 		}
-	}
 	return Object.freeze({
-		denied: drained(accessKit.denied),
-		leaked: drained(accessKit.leaked),
-		own: drained(accessKit.own),
-		scoped: drained(accessKit.scoped),
-		global: drained(accessKit.global),
-		anyone: drained(accessKit.anyone),
-		capability: drained(accessKit.capability),
+		denied: drained((cases) => cases.denied),
+		leaked: drained((cases) => cases.leaked),
+		own: drained((cases) => cases.own),
+		scoped: drained((cases) => cases.scoped),
+		global: drained((cases) => cases.global),
+		anyone: drained((cases) => cases.anyone),
+		capability: drained((cases) => cases.capability),
 	})
 }

package/src/testing/kit.ts

@@ -16,13 +16,16 @@ import {
 	FABRIKA_IAM_ISSUER,
 	FABRIKA_TOKEN_KEYS,
 	type IamMembershipRpc,
+	type IamTerminalRpc,
 	isNormalizedMailbox,
 	type Jwks,
 	MAX_ACCESS_TOKEN_BYTES,
+	MAX_APPLICATION_TOKEN_BYTES,
 	normalizeEmailIdentity,
 	type PermissionEntry,
 	PROXY_TOKEN_HEADER,
 	SESSION_COOKIE,
+	type TerminalFailure,
 	TOKEN_ALG,
 	UNTRUSTED_FORWARD_HEADERS,
 	workloadKeyVariable,
@@ -78,6 +81,14 @@ import {
 import { endpointProxy } from './proxy'
 
 export const TEST_ISSUER = 'https://iam.test'
+
+/** The kit's IAM without a terminal: no identification is open, so every one is `not_found`. */
+const noIdentification = (): Promise<TerminalFailure> => Promise.resolve({ ok: false, reason: 'not_found' })
+const NO_IDENTIFICATIONS: IamTerminalRpc = Object.freeze({
+	inspectIdentification: noIdentification,
+	assertIdentity: noIdentification,
+	cancelIdentification: noIdentification,
+})
 export const TEST_ENVIRONMENT = 'test'
 const KEY_ID = 'test-key'
 const TOKEN_TTL_SECONDS = 300
@@ -112,6 +123,11 @@ export interface TestKitOptions {
 	 * kit's proxy obtains each delegation grant from it. Without it the kit's IAM answers them under IAM's rules.
 	 */
 	readonly membership?: IamMembershipRpc
+	/**
+	 * IAM's identifications at a terminal (ADR-0067), for a contract that declares one. Without it the kit's IAM knows no
+	 * open identification: `inspect` answers null and `assert` `not_found`.
+	 */
+	readonly terminals?: IamTerminalRpc
 	/**
 	 * Each import's owner, by the import's name: its origin and edge key, which the platform writes as the import's
 	 * framework variables, and how a request reaches it — usually the owner kit's `fetch`.
@@ -428,6 +444,7 @@ export function bootTestKit<C extends AnyContract>(
 		...dev,
 		...(options.revealHandlerErrors === undefined ? {} : { revealHandlerErrors: options.revealHandlerErrors }),
 		membership,
+		terminals: options.terminals ?? (artifact.terminal === undefined ? undefined : NO_IDENTIFICATIONS),
 		connectBindings,
 		workloadTokens,
 		mailStandIn: options.mail === 'none' ? 'none' : mail,
@@ -523,7 +540,7 @@ export function bootTestKit<C extends AnyContract>(
 
 	const scope = <D extends DimensionOf<C>>(dimension: D, value: string): TestScope<D> => Object.freeze({ type: dimension, value })
 
-	/** The caller's token, or why IAM signs none: a disabled principal, or a token above `MAX_ACCESS_TOKEN_BYTES`. */
+	/** The caller's token, or why IAM signs none: a disabled principal, or a token above IAM's bound for it. */
 	async function mint(caller: TestCaller): Promise<{ readonly ok: true; readonly token: string; readonly expiresAt: number } | MintRefusal> {
 		if (caller.disabled) return { ok: false, reason: 'disabled' }
 		const now = Math.floor(Date.now() / 1000)
@@ -542,7 +559,8 @@ export function bootTestKit<C extends AnyContract>(
 		})
 		const { privateKey } = await signing
 		const token = await new SignJWT({ ...claims }).setProtectedHeader({ alg: TOKEN_ALG, kid: KEY_ID }).sign(privateKey)
-		if (token.length > MAX_ACCESS_TOKEN_BYTES) return { ok: false, reason: 'token_too_large' }
+		// IAM bounds a workload's own token as any installation token, and a token the proxy injects at the application's.
+		if (token.length > (caller.app === null ? MAX_APPLICATION_TOKEN_BYTES : MAX_ACCESS_TOKEN_BYTES)) return { ok: false, reason: 'token_too_large' }
 		byToken.set(token, { caller, expiresAt: claims.exp })
 		return { ok: true, token, expiresAt: claims.exp }
 	}

package/src/testing/proxy.ts

@@ -19,7 +19,7 @@ import {
 	type TokenCache,
 } from '@fabrika/proxy-core'
 import { applyCrossOriginHeaders, crossOriginHeaders } from '@fabrika/proxy-core/headers'
-import { contractProxyTable } from '@fabrika/proxy-core/manifest'
+import { contractProxyEntry, contractProxyTable } from '@fabrika/proxy-core/manifest'
 
 /** What the proxy did with a request: answered it itself, or forwarded it with what only the proxy may set. */
 export type ProxyOutcome =
@@ -66,14 +66,14 @@ const ASSERTED_HEADERS = [PROXY_TOKEN_HEADER, REQUEST_ID_HEADER, ENDPOINT_HEADER
 export function endpointProxy(options: EndpointProxyOptions): TestProxy {
 	const verify = createVerifyService({
 		manifest: {
-			apps: [{
+			apps: [contractProxyEntry({
 				id: options.appId,
 				hosts: [options.host],
 				upstream: 'app',
 				scheme: 'https',
-				...contractProxyTable(options.artifact),
-				...(options.crossOrigins === undefined || options.crossOrigins.length === 0 ? {} : { crossOrigins: [...options.crossOrigins] }),
-			}],
+				table: contractProxyTable(options.artifact),
+				...(options.crossOrigins === undefined ? {} : { crossOrigins: options.crossOrigins }),
+			})],
 		},
 		iam: options.iam,
 		issuer: options.issuer,

package/types/src/agent-skill.d.ts

@@ -0,0 +1,29 @@
+export declare const APP_AGENT_SKILL_NAME = "fabrika-app";
+export interface AppAgentSkillReference {
+    /** The file's path in the skill directory, `references/<topic>.md`: the path `SKILL.md` names it by. */
+    readonly path: string;
+    /** The topic `get_app_rules` answers it under: its file name without `.md`. */
+    readonly topic: string;
+    readonly text: string;
+}
+export interface AppAgentSkill {
+    /** The `version` of the frontmatter: the version of the `@fabrika/app` that ships it. */
+    readonly version: string;
+    /** The whole `SKILL.md`, frontmatter included: what a skill directory holds. */
+    readonly text: string;
+    /** `SKILL.md` without the frontmatter. */
+    readonly body: string;
+    /** The reference files, by path. */
+    readonly references: readonly AppAgentSkillReference[];
+}
+/** The skill of this package. */
+export declare function readAppAgentSkill(): AppAgentSkill;
+/** The skill in `skillDir`, the `skill/` directory of an installed `@fabrika/app`. */
+export declare function readAppAgentSkillAt(skillDir: string): AppAgentSkill;
+/**
+ * The skill of the `@fabrika/app` an application installed: the nearest `node_modules/@fabrika/app` from `appRoot`
+ * up, as Bun resolves the package. `null` when the application has not installed it.
+ */
+export declare function installedAppAgentSkill(appRoot: string): AppAgentSkill | null;
+/** The `AGENTS.md` of an application repository: the skill's body, then each reference file. */
+export declare function renderAgentsFile(skill: AppAgentSkill): string;

package/types/src/build-recipe.d.ts

@@ -0,0 +1,70 @@
+export { CONTRACT_APP_ID_PATTERN } from './contract/app-id.js';
+export { FILE_SCAN_JOB, FILE_SWEEP_JOB } from './files/job-names.js';
+/** The TypeScript release of the platform's type check; the application's own `typescript` is not run. */
+export declare const PLATFORM_TYPESCRIPT_VERSION = "5.9.3";
+/** A `c.cron` job name, which a crontab line carries unquoted. */
+export declare const CONTRACT_JOB_NAME_PATTERN: RegExp;
+/** Five cron fields of digits and `*`, `/`, `,`, `-` only. */
+export declare const CRON_SCHEDULE_PATTERN: RegExp;
+/** What one contract application's recipe depends on. `contractRecipe` refuses a value that a shell would read as more. */
+export interface ContractRecipeInput {
+    readonly appId: string;
+    /** The `@fabrika/check` release whose reader read the application (ADR-0062). */
+    readonly checkRelease: string;
+    /** The absolute directory the build runs in: the checker reads the source there. */
+    readonly sourceRoot: string;
+    /** The absolute directory the built application runs from: each generated script starts there. */
+    readonly runtimeRoot: string;
+    /** With a database, every container migrates and checks its schema before the server starts. */
+    readonly database: boolean;
+    /** Whether the build uploads its source maps, last and never failing the build. */
+    readonly sourceMaps: boolean;
+    readonly jobs: readonly {
+        readonly name: string;
+        readonly schedule: string;
+    }[];
+    /** The contract declares a file collection: the sweep of removed files is scheduled. */
+    readonly files: boolean;
+    /** A file collection scans its uploads: the scan pass is scheduled. */
+    readonly scan: boolean;
+}
+/** One build step: a command run in the source root, or a generated file written there, line by line. */
+export type ContractBuildStep = {
+    readonly run: string;
+} | {
+    readonly write: string;
+    readonly lines: readonly string[];
+};
+/** One check of the build: a command run in the source root that fails the build. */
+export interface ContractCheck {
+    readonly name: 'tests' | 'tsc' | 'fabrika-check';
+    readonly command: string;
+}
+export interface ContractRecipe {
+    /** The steps after the authored SPA commands, in order. */
+    readonly build: readonly ContractBuildStep[];
+    /** The checks among `build`, in its order. */
+    readonly checks: readonly ContractCheck[];
+    /** The generated scripts every container runs before `start`, in order; any failure stops the activation. */
+    readonly init: readonly string[];
+    /** The generated script that starts the server, which only `exec`s it. */
+    readonly start: string;
+    /** The command the start script `exec`s, run from the runtime root. */
+    readonly serve: readonly string[];
+    /** The command that migrates the application's database, run from the runtime root. */
+    readonly migrate: readonly string[];
+    /** The jobs to schedule, each on one container; a command runs from the runtime root. */
+    readonly jobs: readonly {
+        readonly schedule: string;
+        readonly command: string;
+    }[];
+}
+/**
+ * The recipe of one contract application. The application's tests run first: they are authored code, so everything
+ * after them is reinstalled, regenerated or checked again. They run `--isolate`, as the application skill runs them: a
+ * test file's DOM globals otherwise leak into the next file. `tsc` runs before the checker, as in the skill's loop: the
+ * usual quick fix of a type error is a cast or an `any`, which only the checker refuses, so the checker is the last word
+ * on the code. The build has no database, so the schema checks run as init scripts, after the migrations and before the
+ * readiness window opens.
+ */
+export declare function contractRecipe(input: ContractRecipeInput): ContractRecipe;

package/types/src/build.d.ts

@@ -0,0 +1,29 @@
+/** An application root with this file is a contract application. The paths equal `@fabrika/check`'s layout. */
+export declare const CONTRACT_FILE = "fabrika.contract.ts";
+/** Relative to the application root. */
+export declare const GENERATED_ENTRY_FILE = "fabrika/entry.generated.ts";
+/** The module whose default export is `serve(contract, …)`, relative to the application root. */
+export declare const IMPLEMENTATION_FILE = "src/app.ts";
+/** The application's migrations as a module, relative to the application root: a Worker reads no file system. */
+export declare const GENERATED_MIGRATIONS_FILE = "fabrika/migrations.generated.ts";
+/** Where an application keeps its migrations, relative to its root; `fabrika db new` writes there. */
+export declare const MIGRATIONS_DIRECTORY = "db/migrations";
+export type EntryRuntime = 'bun' | 'cloudflare';
+export * from './build-recipe.js';
+export { CLOUDFLARE_APPLICATION_BINDING, CLOUDFLARE_APPLICATION_CLASS, CLOUDFLARE_FILES_BINDING } from './cloudflare/names.js';
+/** The entrypoint source for one runtime. */
+export declare function generatedEntry(runtime: EntryRuntime): string;
+/** Writes the entrypoint under `root` and returns its path; the Cloudflare one also writes the migrations module it imports. */
+export declare function writeGeneratedEntry(root: string, runtime: EntryRuntime): Promise<string>;
+/** The application's migrations under `root`, every `.sql` file of `db/migrations` by name; none without the directory. */
+export declare function applicationMigrations(root: string): Promise<readonly {
+    readonly name: string;
+    readonly sql: string;
+}[]>;
+/** The migrations module source: the files' names and texts, verbatim, so their checksums stay the files'. */
+export declare function generatedMigrations(migrations: readonly {
+    readonly name: string;
+    readonly sql: string;
+}[]): string;
+/** Writes the migrations module under `root` and returns its path. */
+export declare function writeGeneratedMigrations(root: string): Promise<string>;