@fabrika/app 0.8.2 → 0.9.0-cloudflare.2

package/src/contract/group.ts

@@ -115,7 +115,16 @@ export type SignsField<Sg, Purposes extends string> =
  * `fetch` refuses any other while the site runs; a public procedure declares none.
  */
 export interface EgressField {
-	readonly egress?: readonly `https://${string}`[]
+	readonly egress?: readonly `https://${string}`[] | Unavailable<"egress: 'public' is a cron job's only: record a row and kick a job that declares it">
+}
+
+/**
+ * A cron job's `egress`: its exact HTTPS origins, or `'public'`, every public host over HTTPS or HTTP on its default
+ * port, for a job that calls the websites its operators name (ADR-0070). The guard refuses IP addresses, local and
+ * internal names and the installation's own hosts, checks each redirect, and bounds each request's time and body.
+ */
+export interface JobEgressField {
+	readonly egress?: readonly `https://${string}`[] | 'public'
 }
 
 /** Each purpose `signs` names is one of `defineApp`'s `tokens`. */

package/src/contract/kit.ts

@@ -45,6 +45,7 @@ import {
 	type Schema,
 	type Surface,
 	surfaceKit,
+	terminalOf,
 	type WebhookMount,
 } from './define'
 import type {
@@ -56,6 +57,7 @@ import type {
 	GroupBuild,
 	GroupInput,
 	GroupKit,
+	JobEgressField,
 	KicksField,
 	LimitsOption,
 	LinkGroupKit,
@@ -73,13 +75,14 @@ type Owned<K extends string> = { readonly [P in K]?: never }
 
 /** The kit's types, computed once from the vocabulary, the tables' index, the imports and the token purposes. */
 export type KitOf<V, Ix, Imp extends KitImports, Tk extends TokenPurposes = Record<never, never>> = V extends
-	AppVocabulary<infer A, infer D, infer R, infer Dims, infer M> ? {
+	AppVocabulary<infer A, infer D, infer R, infer Dims, infer M, infer T> ? {
 		readonly action: A
 		readonly dimension: D
 		readonly creatable: CreatableDimension<Dims>
 		readonly role: R
 		readonly dimensions: Dims
 		readonly members: M
+		readonly terminal: [T] extends [never] ? false : true
 		readonly index: Ix
 		readonly tables: Ix extends { readonly tables: infer T } ? keyof T & string : never
 		readonly imports: Imp
@@ -94,7 +97,7 @@ export type CronOptions<Acts, S, U, Is, Ix extends AnyDbIndex, M = never, Ks = n
 	& MailerField<M>
 	& KicksField<Ks>
 	& SignsField<Sg, Purposes>
-	& EgressField
+	& JobEgressField
 
 /** The mail transport a job reaches, inferred from its optional field and then required, like a declared field. */
 type MailerField<M> =
@@ -555,6 +558,7 @@ function runtimeApp(vocabulary: AnyAppVocabulary, options: KitOptions | undefine
 					roles: vocabulary.roles,
 					...presentationOf(vocabulary),
 					...peopleOf(vocabulary),
+					...terminalOf(vocabulary),
 				},
 				dimensions: vocabulary.dimensions,
 				surface: declared,

package/src/contract/platform.ts

@@ -23,8 +23,8 @@ import {
 /**
  * The IAM vocabulary of a contract application, marked `contract` so IAM refuses every wildcard written for it: the
  * dimensions as scopes with their container, creator role and members actions; the actions; the roles, a membership
- * role with its scope and the roles that may assign it; the link mounts; the delegations; the workloads; and the locale,
- * display name and e-mail wording IAM names the application with. Every artifact
+ * role with its scope and the roles that may assign it; the link mounts; the delegations; the workloads; the locale,
+ * display name and e-mail wording IAM names the application with; and its terminal identification page. Every artifact
  * dimension is a scope, a file collection's `file:<name>` included, because access to a file is checked there.
  */
 export function schemaFromContract(artifact: ContractArtifact): AppSchema {
@@ -46,6 +46,7 @@ export function schemaFromContract(artifact: ContractArtifact): AppSchema {
 		...(artifact.mail === undefined ? {} : { mail: artifact.mail }),
 		...(artifact.members === undefined ? {} : { members: { manage: artifact.members.manage, list: artifact.members.list } }),
 		...(artifact.directory === 'labels' ? { directory: 'labels' } : {}),
+		...(artifact.terminal === undefined ? {} : { terminal: { identify: artifact.terminal.identify } }),
 	}
 }
 

package/src/contract/vocabulary.ts

@@ -2,20 +2,35 @@
 // nothing else, so the tables, the kit, the groups and the contract can each be typed by it without a cycle.
 // Browser-safe: plain data.
 
-import { type AppMembers, type DimensionDef, type Presentation, presentationOf, type RoleDefs, type Vocabulary, type WildcardMessage } from './define'
+import {
+	type AppMembers,
+	type DimensionDef,
+	type Presentation,
+	presentationOf,
+	type RoleDefs,
+	type TerminalDeclaration,
+	type Vocabulary,
+	type WildcardMessage,
+} from './define'
 
 /**
- * The vocabulary as `defineVocabulary` returned it, with its literal names, dimension definitions and the actions of its
- * people (`M`, `never` when it declares none).
+ * The vocabulary as `defineVocabulary` returned it, with its literal names, dimension definitions, the actions of its
+ * people (`M`, `never` when it declares none) and its terminal (`T`, `never` when it declares none).
  */
-export interface AppVocabulary<A extends string, D extends string, R extends string, Dims, M extends AppMembers<A> = never>
-	extends Vocabulary<A, D, R>
-{
+export interface AppVocabulary<
+	A extends string,
+	D extends string,
+	R extends string,
+	Dims,
+	M extends AppMembers<A> = never,
+	T extends TerminalDeclaration = never,
+> extends Vocabulary<A, D, R> {
 	readonly dimensions: Dims & { readonly [K in D]: DimensionDef<A, D, R> }
 	readonly members?: M
+	readonly terminal?: T
 }
 
-export type AnyAppVocabulary = AppVocabulary<string, string, string, unknown, AppMembers<string>>
+export type AnyAppVocabulary = AppVocabulary<string, string, string, unknown, AppMembers<string>, TerminalDeclaration>
 
 /**
  * Declares the dimensions, actions and roles, and how IAM names the application (`locale`, `displayName`). `src/vocabulary.ts` exports it; `defineTables`, `defineApp` and the
@@ -27,6 +42,7 @@ export function defineVocabulary<
 	const R extends string,
 	const Dims extends { readonly [K in D]: DimensionDef<NoInfer<A>, NoInfer<D>, NoInfer<R>> },
 	const M extends AppMembers<NoInfer<A>> = never,
+	const T extends TerminalDeclaration = never,
 >(
 	vocabulary: Presentation & {
 		readonly app: string
@@ -35,8 +51,9 @@ export function defineVocabulary<
 		readonly roles: RoleDefs<NoInfer<A>, NoInfer<D>, R>
 		readonly members?: M
 		readonly directory?: 'labels'
+		readonly terminal?: T
 	},
-): AppVocabulary<A, D, R, Dims, M> {
+): AppVocabulary<A, D, R, Dims, M, T> {
 	const people = vocabulary.members
 	return {
 		app: vocabulary.app,
@@ -46,5 +63,6 @@ export function defineVocabulary<
 		...presentationOf(vocabulary),
 		...(people === undefined ? {} : { members: people }),
 		...(vocabulary.directory === undefined ? {} : { directory: vocabulary.directory }),
+		...(vocabulary.terminal === undefined ? {} : { terminal: vocabulary.terminal }),
 	}
 }

package/src/dev/changes.ts

@@ -0,0 +1,35 @@
+// What a sync changes, read off its paths: whether the build owns one (then the commit needs a bootstrap run), whether
+// the migrations changed, and whether a web source did. Whether the contract changed is the digest's to say, not a path's.
+
+import { CONTRACT_FILE } from '../build.js'
+
+/** The application's migrations, as `fabrika db migrate` reads them. */
+export const MIGRATIONS_DIRECTORY = 'db/migrations/'
+
+/** Files whose change the build turns into something else: an install, or the generated run and build descriptors. */
+const BUILD_OWNED_FILES: ReadonlySet<string> = new Set(['package.json', 'bun.lock', 'bun.lockb', 'bunfig.toml', 'zerops.yaml', 'zerops.yml'])
+const BUILD_OWNED_DIRECTORIES = ['fabrika/', 'node_modules/'] as const
+
+/** Server code and the database: a change only there leaves the SPA as it is. */
+const SERVER_DIRECTORIES = ['src/', 'db/'] as const
+
+/** Why the change needs a bootstrap run, in one line, or null when the launcher may apply it. */
+export function bootstrapReason(paths: readonly string[]): string | null {
+	for (const path of paths) {
+		const why = BUILD_OWNED_FILES.has(path)
+			? 'the dependencies, the lockfile or the build descriptor'
+			: BUILD_OWNED_DIRECTORIES.some((directory) => path.startsWith(directory))
+			? 'the generated files or the installed packages'
+			: path !== CONTRACT_FILE && path.startsWith('fabrika.') && !path.includes('/')
+			? 'a fabrika.* file'
+			: null
+		if (why !== null) return `${path} changed, which is ${why}; that needs a bootstrap run: call bind_dev again`
+	}
+	return null
+}
+
+export const migrationsChanged = (paths: readonly string[]): boolean => paths.some((path) => path.startsWith(MIGRATIONS_DIRECTORY))
+
+/** A change outside the server code and the database may reach the SPA, so its build runs again. */
+export const webSourceChanged = (paths: readonly string[]): boolean =>
+	paths.some((path) => !SERVER_DIRECTORIES.some((directory) => path.startsWith(directory)))

package/src/dev/contract-digest.ts

@@ -0,0 +1,17 @@
+// The launcher's child that answers whether a commit changed the contract (ADR-0049). It runs in the application root
+// with no credential in its environment, loads the application module the launcher itself never loads, and prints the
+// digest the application's boot compares with `FABRIKA_CONTRACT_DIGEST`.
+
+import { contractDigest } from '@fabrika/auth-core'
+import { join } from 'node:path'
+import { IMPLEMENTATION_FILE } from '../build.js'
+import { compileContract } from '../contract/compile.js'
+import { isContractImplementation } from '../implement/implement.js'
+
+const module: unknown = await import(join(process.cwd(), IMPLEMENTATION_FILE))
+const app = typeof module === 'object' && module !== null ? Reflect.get(module, 'default') : undefined
+if (!isContractImplementation(app)) {
+	console.error(`${IMPLEMENTATION_FILE} does not default-export serve(contract, { … })`)
+	process.exit(1)
+}
+console.log(contractDigest(compileContract(app.contract, app.database?.tables ?? {})))

package/src/dev/index.ts

@@ -0,0 +1,11 @@
+// @fabrika/app/dev — the launcher of a `dev` environment, which the generated dev entrypoint runs (Bun only).
+
+export { bootstrapReason, migrationsChanged, webSourceChanged } from './changes.js'
+export {
+	type DevLauncher,
+	type DevLauncherOptions,
+	type DevSourceTransport,
+	readDevLauncherConfig,
+	runDevLauncher,
+	startDevLauncher,
+} from './launcher.js'