@fabrika/provider-zerops 0.2.0 → 0.3.1

package/src/installation/manifest.ts

@@ -0,0 +1,95 @@
+// Composing the platform's three apps with whatever else the installation's one proxy already fronts.
+//
+// ── Why this is a MERGE and not a write ───────────────────────────────────────────────────────────
+//
+// On the `light` tier an application shares the platform's project and therefore the platform proxy's
+// single `FABRIKA_PROXY_MANIFEST_JSON`. The live document on `fabrika-test` carries a fourth app —
+// `notes` → `notesapi:3000` on listener 8084 — beside the three platform ones. `platformProxyManifest`
+// deliberately emits only the platform apps (it is generated from the platform's own gate modules and
+// knows nothing about applications), so writing it alone would DELETE every application entry and take
+// the deployed applications offline at the next proxy build.
+//
+// So: read the live value, compose, write. That composition is this command's job and nothing else's.
+//
+// ── What happens to an entry the platform does not know about ─────────────────────────────────────
+//
+// Carried through byte-for-byte, in its live order, after the platform apps — with ONE exception. A
+// host belongs to exactly one app (`parseProxyManifest` refuses two apps claiming one, and rightly:
+// route order would otherwise decide which app answers). The platform's three listeners are addresses
+// the platform OWNS, so a live entry standing on one of them is superseded rather than carried, and
+// the deploy says so out loud.
+//
+// That exception is not hypothetical: WU1 corrected IAM's app id from `iam-local` to `iam`, so the
+// live document's `iam-local` claims the platform's own IAM host under a name the platform no longer
+// uses. Carrying it would produce a manifest `parseProxyManifest` rejects, which the proxy build then
+// fails on — a fail-closed outcome, but a needlessly confusing one.
+//
+// Superseding is itself CLOSED: the dropped host stops resolving to anything, it does not fall through
+// to some other app. A genuinely misplaced application therefore goes dark and is reported, instead of
+// quietly being served by the console.
+
+import { findDuplicateProxyHost, parseProxyManifestJson, type ProxyManifest } from '@fabrika/proxy-core/manifest'
+
+/** The composed document plus what happened to every live entry that was not the platform's. */
+export interface MergedProxyManifest {
+	readonly manifest: ProxyManifest
+	/** App ids carried through from the live manifest, in their live order. */
+	readonly carried: readonly string[]
+	/** Live entries the platform's own listeners displaced, with the host that collided. */
+	readonly superseded: readonly { readonly id: string; readonly host: string }[]
+}
+
+/**
+ * Compose the platform's apps with the application entries already in a live manifest.
+ *
+ * `live` is `null` when the proxy carries no manifest yet (a first deploy) — the result is then the
+ * platform document alone. An UNPARSEABLE live value is a different thing entirely and throws: it may
+ * be a manifest this build is too old to read, and silently replacing it would drop applications this
+ * code cannot see. Refusing is what keeps "must not take a deployed app offline" true in the one case
+ * where the deploy genuinely cannot tell.
+ */
+export const mergePlatformProxyManifest = (platform: ProxyManifest, live: ProxyManifest | null): MergedProxyManifest => {
+	const platformIds = new Set(platform.apps.map((app) => app.id))
+	const platformHosts = new Set(platform.apps.flatMap((app) => app.hosts))
+	const carried: string[] = []
+	const superseded: { id: string; host: string }[] = []
+	const apps = [...platform.apps]
+	for (const app of live?.apps ?? []) {
+		if (platformIds.has(app.id)) {
+			continue
+		}
+		const collision = app.hosts.find((host) => platformHosts.has(host))
+		if (collision !== undefined) {
+			superseded.push({ id: app.id, host: collision })
+			continue
+		}
+		carried.push(app.id)
+		apps.push(app)
+	}
+	// Both inputs are already parsed manifests, so a duplicate host is the one invariant composing can break.
+	// A duplicate host between two APPLICATION entries — which this function cannot fix — is refused
+	// here rather than at the proxy's next build.
+	if (findDuplicateProxyHost(apps) !== null) {
+		throw new Error('the composed proxy manifest is not one the proxy would accept — two application entries claim one host')
+	}
+	return { manifest: { apps }, carried, superseded }
+}
+
+/**
+ * The live manifest a proxy service currently carries.
+ *
+ * Absent means "no manifest yet". Present-but-unparseable throws: see `mergePlatformProxyManifest`.
+ */
+export const readLiveProxyManifest = (value: string | undefined): ProxyManifest | null => {
+	if (value === undefined || value.trim() === '') {
+		return null
+	}
+	const manifest = parseProxyManifestJson(value)
+	if (manifest === null) {
+		throw new Error(
+			`the proxy's current FABRIKA_PROXY_MANIFEST_JSON cannot be parsed by this build — refusing to replace a document whose `
+				+ 'application entries cannot be read',
+		)
+	}
+	return manifest
+}

package/src/installation/placement-options.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod'
+
+const scheme = z.enum(['http', 'https']).default('https')
+const bareHostname = z.string().refine(
+	(host) => !host.includes('/') && !host.includes(':'),
+	(host) => ({ message: `\`${host}\` is not a bare hostname — a platform host carries no scheme and no port` }),
+)
+const hosts = z.object({ iam: bareHostname, control: bareHostname, operations: bareHostname })
+
+export const parsePlatformScheme = (raw: string | undefined): 'http' | 'https' => {
+	const parsed = scheme.safeParse(raw)
+	if (!parsed.success) throw new Error('--scheme must be http or https')
+	return parsed.data
+}
+export const parsePlatformHostname = (raw: string): string => {
+	const parsed = bareHostname.safeParse(raw)
+	if (!parsed.success) throw new Error(`\`${raw}\` is not a bare hostname — a platform host carries no scheme and no port`)
+	return parsed.data
+}
+export const parsePlatformHosts = (
+	raw: { iam: string | undefined; control: string | undefined; operations: string | undefined },
+): { iam: string; control: string; operations: string } | undefined => {
+	if (raw.iam === undefined && raw.control === undefined && raw.operations === undefined) return undefined
+	const parsed = hosts.safeParse(raw)
+	if (parsed.success) return parsed.data
+	if (raw.iam === undefined || raw.control === undefined || raw.operations === undefined) {
+		throw new Error(
+			'name every platform host or none: --iam-host, --console-host and --operations-host go together '
+				+ "(omitting all three derives them from the proxy's Zerops subdomains)",
+		)
+	}
+	throw new Error(parsed.error.issues[0]?.message ?? 'invalid platform hosts')
+}

package/src/installation/platform-source.ts

@@ -0,0 +1,106 @@
+import { mkdir, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createZeropsArtifactSourceDescriptor, ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES, type ZeropsArtifactSourceDescriptor } from '../index'
+
+export interface PreparedPlatformSource {
+	commitSha: string
+	descriptor: ZeropsArtifactSourceDescriptor
+	archivePath: string
+	dispose(): Promise<void>
+}
+
+// The caller must separately establish that the executing CLI belongs to this checkout.
+export async function preparePlatformSource(sourceDir: string, signal: AbortSignal): Promise<PreparedPlatformSource> {
+	signal.throwIfAborted()
+	const root = await realpath(sourceDir)
+	const git = (args: string[], cwd = root, env: Record<string, string> = {}) => runGit(cwd, args, signal, env)
+	const topLevel = (await git(['rev-parse', '--show-toplevel'])).trimEnd()
+	if (await realpath(topLevel) !== root) throw new Error('Platform source directory must be the Git repository root')
+	const commitSha = (await git(['rev-parse', '--verify', 'HEAD^{commit}'])).trim()
+	if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commitSha)) throw new Error('Invalid platform source commit')
+	const tree = await git(['ls-tree', '-rz', commitSha])
+	if (tree.split('\0').some((entry) => entry.startsWith('160000 '))) throw new Error('Platform source submodules are not supported')
+	const tracked = await git(['ls-files', '-v', '-z'])
+	if (tracked.split('\0').some((entry) => entry !== '' && !entry.startsWith('H '))) {
+		throw new Error('Platform source requires a full checkout without skip-worktree or assume-unchanged entries')
+	}
+	await git(['diff', '--no-ext-diff', '--no-textconv', '--quiet', '--cached', commitSha, '--'])
+	await git(['diff', '--no-ext-diff', '--no-textconv', '--quiet', '--'])
+	const descriptorEntry = await git(['ls-tree', '-z', commitSha, '--', 'zerops.yaml'])
+	if (!/^100(?:644|755) blob [a-f0-9]+\tzerops\.yaml\0$/.test(descriptorEntry)) {
+		throw new Error('Platform source requires a regular root zerops.yaml')
+	}
+	const size = Number((await git(['cat-file', '-s', `${commitSha}:zerops.yaml`])).trim())
+	if (!Number.isSafeInteger(size) || size <= 0 || size > ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES) {
+		throw new Error('Platform source zerops.yaml is empty or exceeds the descriptor size limit')
+	}
+	const contents = await git(['show', `${commitSha}:zerops.yaml`])
+	const descriptor = await createZeropsArtifactSourceDescriptor(contents)
+	const objectDirectory = (await git(['rev-parse', '--path-format=absolute', '--git-path', 'objects'])).trimEnd()
+	const objectFormat = (await git(['rev-parse', '--show-object-format'])).trim()
+	if (objectFormat !== 'sha1' && objectFormat !== 'sha256') throw new Error('Unsupported Git object format')
+	signal.throwIfAborted()
+	const temporary = await mkdtemp(join(tmpdir(), 'fabrika-platform-source-'))
+	const dispose = () => rm(temporary, { recursive: true, force: true })
+	try {
+		const repository = join(temporary, 'repository.git')
+		await git(['init', '--bare', `--object-format=${objectFormat}`, '--template=', repository], temporary)
+		// Override nested committed attributes too: archive must neither omit nor transform Git blob bytes.
+		await mkdir(join(repository, 'info'))
+		await writeFile(join(repository, 'info', 'attributes'), '* -export-ignore -export-subst -text -eol -crlf -ident -working-tree-encoding -filter\n')
+		const archivePath = join(temporary, 'source.tar.gz')
+		await git(['archive', '--format=tar.gz', `--output=${archivePath}`, commitSha], repository, {
+			GIT_OBJECT_DIRECTORY: objectDirectory,
+		})
+		signal.throwIfAborted()
+		const archived = (await new Bun.Archive(await Bun.file(archivePath).arrayBuffer()).files('zerops.yaml')).get('zerops.yaml')
+		if (!archived || archived.size !== size) throw new Error('Archived platform descriptor differs from the committed descriptor')
+		const archivedContents = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(await archived.arrayBuffer())
+		if (archivedContents !== contents) throw new Error('Archived platform descriptor differs from the committed descriptor')
+		signal.throwIfAborted()
+		return { commitSha, descriptor, archivePath, dispose }
+	} catch (error) {
+		await dispose()
+		throw error
+	}
+}
+
+// installation-init capture inherits stderr and has no cancellation; source commands must do neither.
+async function runGit(cwd: string, args: string[], signal: AbortSignal, extraEnv: Record<string, string>): Promise<string> {
+	signal.throwIfAborted()
+	const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')))
+	try {
+		const child = Bun.spawn(['git', '-c', 'core.attributesFile=/dev/null', '-c', 'core.fsmonitor=false', ...args], {
+			cwd,
+			env: {
+				...env,
+				GIT_CONFIG_NOSYSTEM: '1',
+				GIT_CONFIG_GLOBAL: '/dev/null',
+				GIT_ATTR_NOSYSTEM: '1',
+				GIT_NO_REPLACE_OBJECTS: '1',
+				GIT_NO_LAZY_FETCH: '1',
+				...extraEnv,
+			},
+			stdin: 'ignore',
+			stdout: 'pipe',
+			stderr: 'ignore',
+		})
+		const abort = () => child.kill()
+		signal.addEventListener('abort', abort, { once: true })
+		try {
+			if (signal.aborted) abort()
+			const [bytes, exitCode] = await Promise.all([new Response(child.stdout).arrayBuffer(), child.exited])
+			signal.throwIfAborted()
+			if (exitCode !== 0) throw new Error('Git source check failed')
+			return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)
+		} finally {
+			signal.removeEventListener('abort', abort)
+			child.kill()
+			await child.exited
+		}
+	} catch {
+		signal.throwIfAborted()
+		throw new Error('Git platform source preparation failed; verify a clean tracked index and worktree and valid UTF-8 source metadata')
+	}
+}

package/src/installation/platform-upload.ts

@@ -0,0 +1,34 @@
+import { isZeropsUploadDestination } from '../index'
+
+export type PlatformUploadFetch = (url: string, init: RequestInit) => Promise<Response>
+
+export const validatePlatformUploadUrl = (value: string): void => {
+	if (!isZeropsUploadDestination(value)) {
+		throw new Error('Zerops archive upload destination rejected')
+	}
+}
+
+export const uploadPlatformArchive = async (
+	url: string,
+	archivePath: string,
+	signal: AbortSignal,
+	uploadFetch: PlatformUploadFetch,
+): Promise<void> => {
+	validatePlatformUploadUrl(url)
+	const uploadSignal = AbortSignal.any([signal, AbortSignal.timeout(10 * 60_000)])
+	const body = Bun.file(archivePath).stream()
+	try {
+		const response = await uploadFetch(url, {
+			method: 'PUT',
+			body,
+			redirect: 'error',
+			signal: uploadSignal,
+		})
+		await response.body?.cancel()
+		if (uploadSignal.aborted || !response.ok) throw new Error('upload rejected')
+	} catch {
+		throw new Error('Zerops archive upload failed')
+	} finally {
+		if (!body.locked) await body.cancel().catch(() => {})
+	}
+}

package/src/installation/proxy-manifest.ts

@@ -0,0 +1,113 @@
+// The proxy manifest a platform installation is configured with, split into the half that is the same
+// on every installation and the half that is one account's.
+//
+// ── Why a template rather than a `ProxyManifest` with the hosts left out ──────────────────────────
+//
+// `parseProxyManifest` refuses an app that declares no hosts, and rightly — a host-less app is fronted
+// by nothing and gates nothing. So the committed half cannot BE a manifest with empty hosts; it is a
+// type of its own, and `resolvePlatformProxyManifest` is the one way to turn it into the document the
+// proxy parses.
+//
+// ── The split ────────────────────────────────────────────────────────────────────────────────────
+//
+//   template   which apps exist, their ids, the private service each is dialed at, the public listener
+//              each answers on, and their gates. True of every installation, so it is GENERATED into
+//              `src/generated/` and reviewed in a diff.
+//   placement  the hostnames and the browser-facing scheme. `proxy-292c-8080.prg1.zerops.app` names one
+//              account's project, and a production installation binds custom domains instead, so
+//              whoever is deploying supplies these.
+//
+// Nothing in this file imports the packages that OWN the gates. That is the point of the split: the
+// gate sets live in `@fabrika/control` (private) and reach a deployed installation as DATA, through the
+// generated artifact, so the published deploy path never depends on a package it cannot resolve.
+
+import type { AppGates } from '@fabrika/auth-core'
+import { parseProxyManifest, type ProxyManifest } from '@fabrika/proxy-core/manifest'
+
+/** The platform services an installation's proxy fronts. Each name is a service hostname in the topology. */
+export type PlatformProxyService = 'iam' | 'control' | 'operations'
+
+/** One fronted app, in the form that is the same on every installation. */
+export interface PlatformProxyApp {
+	/** The IAM app id. It is the audience of every token the proxy mints for this app's host. */
+	readonly id: string
+	/** The topology service that answers for it. */
+	readonly service: PlatformProxyService
+	/**
+	 * The proxy's public listener this app answers on.
+	 *
+	 * On a `zerops-subdomain` installation a port IS a hostname — Zerops mints one generated host per
+	 * HTTP port — so this is the only installation-independent half of `hosts`. A custom-domain
+	 * installation ignores it: every domain arrives on one listener and the `Host` header decides.
+	 */
+	readonly port: number
+	/** Where the proxy dials it over the project's private network. */
+	readonly upstream: string
+	/** Owned by the service's own gate module and copied in by the generator. Never written by hand. */
+	readonly gates: AppGates
+}
+
+/** Everything about an installation's manifest that does not depend on WHICH installation it is. */
+export interface PlatformProxyManifestTemplate {
+	readonly apps: readonly PlatformProxyApp[]
+}
+
+/**
+ * The template's entry for one platform service.
+ *
+ * The app IDS live in the template, so a caller that needs one — the deploy's schema reconcile needs
+ * the console's — reads it from there rather than restating a literal that could drift from the
+ * document the proxy is actually configured with.
+ */
+export const platformProxyAppFor = (
+	template: PlatformProxyManifestTemplate,
+	service: PlatformProxyService,
+): PlatformProxyApp => {
+	const app = template.apps.find((candidate) => candidate.service === service)
+	if (app === undefined) {
+		throw new Error(`the platform proxy manifest template fronts no \`${service}\` service`)
+	}
+	return app
+}
+
+/** Where one app answers in a particular composition. */
+export interface PlatformProxyPlacement {
+	/** Public hostnames, without a port — `parseProxyManifest` refuses a `:port` suffix. */
+	readonly hosts: readonly string[]
+	/** Overrides the private dial address. The local composition runs IAM on a port of its own. */
+	readonly upstream?: string
+}
+
+/** One composition of the platform: a deployed installation, or the local Docker stack. */
+export interface PlatformProxyComposition {
+	/** The scheme the BROWSER speaks to these apps — configuration, never a header (see `ProxyApp.scheme`). */
+	readonly scheme: 'http' | 'https'
+	readonly placement: Readonly<Record<PlatformProxyService, PlatformProxyPlacement>>
+}
+
+/**
+ * Bind a template to one composition and get the document the proxy actually parses.
+ *
+ * The result is returned THROUGH `parseProxyManifest`, so a duplicate id, a repeated host or a `:port`
+ * suffix is refused right here instead of at a deployed proxy's next build.
+ */
+export const resolvePlatformProxyManifest = (
+	template: PlatformProxyManifestTemplate,
+	composition: PlatformProxyComposition,
+): ProxyManifest => {
+	const apps = template.apps.map((app) => {
+		const placement = composition.placement[app.service]
+		return {
+			id: app.id,
+			hosts: [...placement.hosts],
+			upstream: placement.upstream ?? app.upstream,
+			gates: app.gates,
+			scheme: composition.scheme,
+		}
+	})
+	const manifest = parseProxyManifest({ apps })
+	if (manifest === null) {
+		throw new Error('the resolved platform proxy manifest is not one the proxy would accept')
+	}
+	return manifest
+}

package/src/installation/secrets.ts

@@ -0,0 +1,79 @@
+// The six values `fabrika platform install --provider=zerops` GENERATES, and their shapes.
+//
+// Every one of them is written to a Zerops service and never stored anywhere else — there is no `.env`
+// on this path, deliberately (see `init.ts`). Only the provisioning key is ever printed, once, at the
+// end of the install, because `platform init` asks the operator for it afterwards.
+//
+// The shapes are not free choices. Each one is what the consuming code already parses:
+//
+//   • `FABRIKA_IAM_SIGNING_KEYS` is a JSON array of PRIVATE JWKs, index 0 the active signer
+//     (`@fabrika/iam`'s `Signer.fromPrivateJwks`). ES256 / P-256, RFC 7638 thumbprint `kid`.
+//   • A `px_` key is IAM's own credential spelling, and every shared secret must be at least 32
+//     characters or the service refuses to boot — 32 random bytes at base64url is 43.
+//   • The vault KEK is 32 RAW BYTES at base64, not base64url: `@fabrika/control` imports it as an
+//     AES key, and base64url is a different alphabet.
+//
+// Nothing here re-reads an existing value. `install` is a bring-up; rotating a live installation's
+// signing keys or vault KEK is not something a bring-up may do by accident, so the command refuses to
+// run against a project that already carries these keys rather than generating over them.
+
+import { createHash, generateKeyPairSync, randomBytes } from 'node:crypto'
+
+/**
+ * A 256-bit secret in base64url, never starting with `-` or `_`.
+ *
+ * The re-roll is copied from `@fabrika/local-stack`'s `prepare.ts` and it is not superstition: a
+ * credential beginning with `-` reads as a FLAG to anything that later takes it on a command line, no
+ * matter how it is quoted. One rolled password beginning with `-` made `mc alias set` print its usage
+ * and loop forever. It costs nothing and removes a bug that appears about one install in sixteen.
+ */
+const randomSecret = (): string => {
+	for (;;) {
+		const value = randomBytes(32).toString('base64url')
+		if (!value.startsWith('-') && !value.startsWith('_')) {
+			return value
+		}
+	}
+}
+
+/** The `px_` prefix IAM's own credentials carry, so a key looks like what it is wherever it turns up. */
+const randomPxKey = (): string => `px_${randomSecret()}`
+
+/**
+ * One ES256 (EC P-256) private JWK with an RFC 7638 thumbprint `kid`, shaped exactly as IAM's
+ * `Signer.fromPrivateJwks` loads it.
+ */
+const generateEs256Jwk = (): JsonWebKey & { kid: string; alg: string; use: string } => {
+	const { privateKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' })
+	const jwk = privateKey.export({ format: 'jwk' })
+	// RFC 7638 thumbprint over the canonical EC members, in lexicographic order (crv, kty, x, y).
+	const thumbprint = createHash('sha256').update(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y })).digest('base64url')
+	return { ...jwk, kid: thumbprint, alg: 'ES256', use: 'sig' }
+}
+
+/** Everything one installation is seeded with. Several of these are shared by more than one service. */
+export interface InstallationSecrets {
+	/** IAM's token-signing material: a JSON array of ES256 private JWKs, index 0 active. */
+	readonly signingKeys: string
+	/** Gates IAM's management `/rpc/*` surface. Held by IAM, control and Operations. */
+	readonly rpcKey: string
+	/** Gates IAM's `/auth/mint/*` surface, which the proxy calls on the cold path. */
+	readonly proxyKey: string
+	/** The `px_` admin bearer IAM admits as a synthetic global admin. The one value this command prints. */
+	readonly provisioningKey: string
+	/** The catalog credential control and Operations share. No `px_` prefix — it is not an IAM credential. */
+	readonly operationsSyncKey: string
+	/** The control plane's vault KEK: 32 raw bytes at base64. Its loss is unrecoverable by design. */
+	readonly vaultKey: string
+}
+
+/** Roll one installation's secrets. Pure entropy in, no I/O, nothing persisted. */
+export const generateInstallationSecrets = (): InstallationSecrets => ({
+	signingKeys: JSON.stringify([generateEs256Jwk()]),
+	rpcKey: randomPxKey(),
+	proxyKey: randomPxKey(),
+	provisioningKey: randomPxKey(),
+	operationsSyncKey: randomSecret(),
+	// base64, NOT base64url: the vault imports these bytes as an AES key.
+	vaultKey: randomBytes(32).toString('base64'),
+})

package/src/installation/sidecar.ts

@@ -0,0 +1,122 @@
+// What the operator's sidecar repository contains, and the one rule about its pin.
+//
+// ── Why a sidecar repository at all ───────────────────────────────────────────────────────────────
+//
+// [ADR-0025](../../../docs/decisions/0025-the-operator-installs-the-platform-fabrika-deploys-apps.md):
+// a pipeline that deploys an installation needs write access to that installation's cloud account, and
+// this is ONE public repository installed by many operators. So the pipeline cannot live here. fabrika
+// ships the generator; the operator owns the pipeline, its GitHub Environment, and the credentials in
+// it.
+//
+// ── The pin is a TAG, and this file is where that is enforced twice ───────────────────────────────
+//
+// `fabrika.ref` names a published tag of `contember/fabrika-platform`, never a branch: a namespace
+// proxy and an installation both build from tags, so a moving ref would make "which version is this
+// installation running" unanswerable. `assertPinnedTag` refuses a branch when init writes the file, and
+// the generated workflow refuses one again at run time — two gates, because the file is operator-owned
+// after creation and the second gate is the only one that sees what the operator later wrote.
+//
+// ── The templates are not Cloudflare's ────────────────────────────────────────────────────────────
+//
+// The shape is the same (a workflow, a ref, a README, a `.gitignore`) and almost nothing else is.
+// Cloudflare's workflow runs three deploy stages because on that provider the ORDER lives in the
+// pipeline; this one runs a single step because on Zerops the order is inside the command (ADR-0027).
+// Cloudflare builds a runner image and needs a GitHub App; Zerops has no runner at all (ADR-0003).
+
+import { resolve } from 'node:path'
+
+const TEMPLATES = resolve(import.meta.dir, 'templates')
+
+/** Everything the scaffold stages: the CLI-owned trio plus the operator-owned, write-once pin. */
+export const SIDECAR_FILES = ['.gitignore', 'README.md', 'fabrika.ref', '.github/workflows/platform.yml'] as const
+
+/** The file that pins which published fabrika tag this installation runs. */
+export const FABRIKA_REF_FILE = 'fabrika.ref'
+
+/** What a rendered sidecar repository is named after. */
+export interface SidecarValues {
+	/** The operator's name for this installation. The GitHub Environment is named after it too. */
+	readonly installation: string
+	/** `<owner>/<name>` of the sidecar repository itself. */
+	readonly repo: string
+	/** The published fabrika tag to pin, used only when `fabrika.ref` does not exist yet. */
+	readonly fabrikaRef: string
+}
+
+/**
+ * A published release tag: `v` and a semantic version.
+ *
+ * The same shape `scripts/release.ts` accepts, restated rather than imported — that script is not a
+ * package and this check has to hold in a published tarball.
+ */
+const TAG_PATTERN = /^v(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+
+/** The pinned ref, or an error naming what was found. A branch is refused, deliberately and loudly. */
+export const assertPinnedTag = (ref: string): string => {
+	const trimmed = ref.trim()
+	if (trimmed === '') {
+		throw new Error('a published fabrika tag is required, for example v0.1.0')
+	}
+	if (!TAG_PATTERN.test(trimmed)) {
+		throw new Error(
+			`\`${trimmed}\` is not a published tag. A sidecar repository pins a TAG such as v0.1.0 and never a branch: `
+				+ 'an installation that tracked a moving ref could not say which version it runs (ADR-0025)',
+		)
+	}
+	return trimmed
+}
+
+/** Substitute every placeholder in a template. */
+const render = async (name: string, values: SidecarValues): Promise<string> => {
+	const raw = await Bun.file(resolve(TEMPLATES, name)).text()
+	return raw
+		.replaceAll('{{INSTALLATION}}', values.installation)
+		.replaceAll('{{REPO}}', values.repo)
+		.replaceAll('{{FABRIKA_REF}}', values.fabrikaRef)
+}
+
+const write = async (dir: string, rel: string, content: string): Promise<void> => {
+	await Bun.write(resolve(dir, rel), content)
+}
+
+/**
+ * Write the sidecar files into `dir`.
+ *
+ * The workflow, the README and the `.gitignore` are CLI-owned and refreshed on every run, so a fix to
+ * the generated pipeline reaches every installation on its operator's next `init`. `fabrika.ref` is
+ * written ONLY when absent: bumping it is how an operator rolls the installation forward, and a refresh
+ * that reset it would silently roll them back.
+ *
+ * An existing `fabrika.ref` is validated rather than ignored — a sidecar that has drifted onto a branch
+ * is exactly the case the two gates exist for, and finding it here beats finding it in a failed run.
+ */
+export const materializeSidecarScaffold = async (dir: string, values: SidecarValues): Promise<void> => {
+	assertPinnedTag(values.fabrikaRef)
+	const pin = Bun.file(resolve(dir, FABRIKA_REF_FILE))
+	const existing = (await pin.exists()) ? (await pin.text()).trim() : undefined
+	if (existing !== undefined) {
+		assertPinnedTag(existing)
+	}
+	await write(dir, '.gitignore', await Bun.file(resolve(TEMPLATES, 'gitignore')).text())
+	await write(dir, 'README.md', await render('README.md', values))
+	await write(dir, '.github/workflows/platform.yml', await render('platform.yml', values))
+	if (existing === undefined) {
+		await write(dir, FABRIKA_REF_FILE, await render('fabrika.ref', values))
+	}
+}
+
+/** The pin a checkout carries, for the closing summary. */
+export const readPinnedTag = async (dir: string): Promise<string> => {
+	const file = Bun.file(resolve(dir, FABRIKA_REF_FILE))
+	return (await file.exists()) ? (await file.text()).trim() : ''
+}
+
+/**
+ * The default sidecar repository for an installation, following the `contember/vozka-platform-mangoweb`
+ * precedent: named so its relation to the installation is obvious. A parameter, never a constant — one
+ * operator's installations are not another's.
+ */
+export const defaultSidecarRepo = (installation: string): string => `contember/fabrika-zerops-${installation}`
+
+/** Where the sidecar is checked out locally: `./fabrika-zerops-<installation>` under the cwd. */
+export const defaultCheckoutDir = (installation: string): string => resolve(process.cwd(), `fabrika-zerops-${installation}`)

package/src/installation/source-options.ts

@@ -0,0 +1,12 @@
+export const readInstallationSourceDir = (argv: readonly string[], env: Record<string, string | undefined>): string => {
+	if (argv.some((arg) => arg === '--from-git' || arg.startsWith('--from-git=')) || env['FABRIKA_ZEROPS_BUILD_FROM_GIT'] !== undefined) {
+		throw new Error(
+			'Mutable installation Git sources are refused. Remove --from-git and unset FABRIKA_ZEROPS_BUILD_FROM_GIT; run the CLI from a clean full checkout with --source-dir=<checkout>.',
+		)
+	}
+	const values = argv.filter((arg) => arg.startsWith('--source-dir='))
+	if (values.length > 1) throw new Error('--source-dir was given more than once')
+	const value = values[0]?.slice('--source-dir='.length).trim()
+	if (!value) throw new Error('--source-dir=<checkout> is required; run the CLI from that clean full checkout')
+	return value
+}