@fabrika/provider-zerops 0.2.0 → 0.3.1

package/src/installation/install-environment.ts

@@ -0,0 +1,193 @@
+import { encodeProxyManifestJson, FABRIKA_PROXY_MANIFEST_JSON } from '@fabrika/proxy-core/manifest'
+import type { ZeropsNamespaceProxySource } from '../index'
+import type { PlatformDeployService, ResolvedService } from './deploy'
+import { type PlatformHosts, platformOrigin } from './hosts'
+import { assertRunning, type InstallCollaborators } from './install-collaborators'
+import { FABRIKA_ZEROPS_PROXY_SOURCE_JSON, serializeNamespaceProxySource } from './installation-source'
+import type { InstallationSecrets } from './secrets'
+
+/** The private address the proxy dials IAM at inside the project, and pass 1's placeholder issuer. */
+export const PRIVATE_IAM_UPSTREAM = 'iam:3000'
+const PRIVATE_IAM_URL = `http://${PRIVATE_IAM_UPSTREAM}`
+
+/** The canonical fabrika PostgreSQL DSN on Zerops — see `src/topology/setups.ts` for why both suffixes exist. */
+const POSTGRES_URL = '${db_connectionTlsString}/${db_dbName}?sslmode=require'
+
+/** The light tier's one object-storage service, as the platform's own `${service_variable}` references. */
+const STORAGE = {
+	bucket: '${storage_bucketName}',
+	accessKeyId: '${storage_accessKeyId}',
+	secretAccessKey: '${storage_secretAccessKey}',
+	endpoint: '${storage_apiUrl}',
+} as const
+
+/**
+ * The four variables pass 1 writes on the proxy, and nothing else.
+ *
+ * The manifest is EMPTY on purpose: it is the only legal document that can be written before the hosts
+ * exist, and the build bakes whatever is here (`src/topology/setups.ts`). `FABRIKA_IAM_ISSUER` is the private
+ * address rather than the public issuer for the same reason — the public one is not known yet — and
+ * `deployPlatform` corrects it in pass 2, before the manifest it belongs to is applied.
+ */
+export const passOneProxyEnv = (secrets: InstallationSecrets): ReadonlyMap<string, string> =>
+	new Map([
+		[FABRIKA_PROXY_MANIFEST_JSON, encodeProxyManifestJson({ apps: [] })],
+		['FABRIKA_IAM_ISSUER', PRIVATE_IAM_URL],
+		['FABRIKA_IAM_KEY', secrets.proxyKey],
+		['FABRIKA_PROXY_SESSION_OWNER_JSON', 'null'],
+	])
+
+/** What `installationServiceEnv` needs. Everything in it is settled before the first write. */
+export interface InstallationEnvInput {
+	readonly environment: string
+	readonly scheme: 'http' | 'https'
+	readonly hosts: PlatformHosts
+	readonly clientId: string
+	readonly proxySource: ZeropsNamespaceProxySource
+	readonly apiBaseUrl?: string
+	readonly secrets: InstallationSecrets
+	/** The Zerops integration token minted for the control plane. Never logged, never printed. */
+	readonly zeropsAccessToken: string
+}
+
+/**
+ * EVERY variable this command places, per service.
+ *
+ * Pure, and exported, because the matrix is the thing most worth pinning: a name that is right on
+ * Cloudflare and wrong on Bun is a silent no-op rather than a failure. Two spelling rules run through
+ * it, both verified against the runtimes rather than assumed:
+ *
+ *   • IAM's Bun runtime reads `ISSUER` and `ENVIRONMENT` UNPREFIXED and everything else with the
+ *     `FABRIKA_IAM_` prefix (`packages/iam/src/node/runtime.ts`). The prefixed spellings below are the
+ *     ones that file actually reads; the unprefixed ones are the ones it actually reads too.
+ *   • No key any service declares in its own `zerops.yaml` appears here — `PORT`,
+ *     `FABRIKA_IAM_RPC_URL`, `FABRIKA_OPERATIONS_URL`, `FABRIKA_CONTROL_ASSETS_DIR`,
+ *     `FABRIKA_CONTROL_URL`, `FABRIKA_PROXY_MANIFEST`, `FABRIKA_PROXY_PORT`. The env API refuses those
+ *     (`provider-zerops/src/api.ts`), because the conflict cannot be resolved to a record id.
+ *
+ * The proxy manifest is deliberately absent: pass 1 writes an empty one and `deployPlatform` owns the
+ * real one, in the same run as the code it describes (ADR-0027).
+ */
+export const installationServiceEnv = (input: InstallationEnvInput): ReadonlyMap<PlatformDeployService, ReadonlyMap<string, string>> => {
+	const { secrets } = input
+	const iamOrigin = platformOrigin(input.scheme, input.hosts.iam)
+	const operationsOrigin = platformOrigin(input.scheme, input.hosts.operations)
+	const control = new Map([
+		['FABRIKA_CONTROL_DATABASE_URL', POSTGRES_URL],
+		['ENVIRONMENT', input.environment],
+		// A bare HOST, not an origin: `controlPublicOrigin` accepts either, and this is also what the
+		// same-origin check on both first-party gateways is decided against.
+		['FABRIKA_CONTROL_DOMAIN', input.hosts.control],
+		['FABRIKA_IAM_ISSUER', iamOrigin],
+		['OPERATIONS_ARTIFACT_ORIGIN', operationsOrigin],
+		['FABRIKA_CONTROL_RUN_LOGS_BUCKET', STORAGE.bucket],
+		['FABRIKA_CONTROL_RUN_LOGS_ACCESS_KEY_ID', STORAGE.accessKeyId],
+		['FABRIKA_CONTROL_RUN_LOGS_SECRET_ACCESS_KEY', STORAGE.secretAccessKey],
+		['FABRIKA_CONTROL_RUN_LOGS_ENDPOINT', STORAGE.endpoint],
+		['FABRIKA_IAM_RPC_KEY', secrets.rpcKey],
+		['OPERATIONS_SYNC_KEY', secrets.operationsSyncKey],
+		['FABRIKA_CONTROL_VAULT_KEY', secrets.vaultKey],
+		['FABRIKA_IAM_PROVISIONING_KEY', secrets.provisioningKey],
+		['FABRIKA_ZEROPS_CLIENT_ID', input.clientId],
+		[FABRIKA_ZEROPS_PROXY_SOURCE_JSON, serializeNamespaceProxySource(input.proxySource)],
+		// The PUBLIC IAM origin an application project's proxy reaches: there is no private network
+		// between Zerops projects (ADR-0006).
+		['FABRIKA_ZEROPS_PROXY_IAM_URL', iamOrigin],
+		['FABRIKA_ZEROPS_PROXY_IAM_KEY', secrets.proxyKey],
+		['FABRIKA_ZEROPS_ACCESS_TOKEN', input.zeropsAccessToken],
+	])
+	if (input.apiBaseUrl !== undefined) {
+		// Only when the installation is not on the default region. Control spells it `_API_BASE_URL` while
+		// the CLI reads `FABRIKA_ZEROPS_API_URL`; they are different processes reading different sources.
+		control.set('FABRIKA_ZEROPS_API_BASE_URL', input.apiBaseUrl)
+	}
+	return new Map<PlatformDeployService, ReadonlyMap<string, string>>([
+		[
+			'iam',
+			new Map([
+				['FABRIKA_IAM_DATABASE_URL', POSTGRES_URL],
+				['ENVIRONMENT', input.environment],
+				['ISSUER', iamOrigin],
+				// Password only, by decision: OIDC needs an identity provider the operator has not been
+				// asked for. Both are STATED because IAM's own defaults are the other way round — OIDC on,
+				// password off — and it refuses to boot with neither.
+				['FABRIKA_IAM_OIDC_ENABLED', 'false'],
+				['FABRIKA_IAM_PASSWORD_ENABLED', 'true'],
+				['FABRIKA_IAM_SIGNING_KEYS', secrets.signingKeys],
+				['FABRIKA_IAM_RPC_KEY', secrets.rpcKey],
+				['FABRIKA_IAM_PROXY_KEY', secrets.proxyKey],
+				['FABRIKA_IAM_PROVISIONING_KEY', secrets.provisioningKey],
+			]),
+		],
+		[
+			'operations',
+			new Map([
+				['FABRIKA_OPERATIONS_DATABASE_URL', POSTGRES_URL],
+				['FABRIKA_OPERATIONS_BLOB_BUCKET', STORAGE.bucket],
+				['FABRIKA_OPERATIONS_BLOB_ACCESS_KEY_ID', STORAGE.accessKeyId],
+				['FABRIKA_OPERATIONS_BLOB_SECRET_ACCESS_KEY', STORAGE.secretAccessKey],
+				['FABRIKA_OPERATIONS_BLOB_ENDPOINT', STORAGE.endpoint],
+				['FABRIKA_OPERATIONS_PUBLIC_HOST', input.hosts.operations],
+				['ENVIRONMENT', input.environment],
+				['FABRIKA_IAM_ISSUER', iamOrigin],
+				['OPERATIONS_SYNC_KEY', secrets.operationsSyncKey],
+				['FABRIKA_IAM_RPC_KEY', secrets.rpcKey],
+			]),
+		],
+		['control', control],
+		[
+			'proxy',
+			new Map([
+				['ENVIRONMENT', input.environment],
+				// Compared byte-for-byte against a token's `iss`, so this is the PUBLIC issuer and not the
+				// private `iam:3000` pass 1 wrote.
+				['FABRIKA_IAM_ISSUER', iamOrigin],
+				['FABRIKA_IAM_KEY', secrets.proxyKey],
+				['FABRIKA_PROXY_SESSION_OWNER_JSON', JSON.stringify({ issuer: iamOrigin, upstream: PRIVATE_IAM_UPSTREAM })],
+			]),
+		],
+	])
+}
+
+/**
+ * The keys whose VALUE this command generates, per service.
+ *
+ * Their presence on a live service is what "this project already holds an installation" means, and it is
+ * checked by KEY only — a value is never read back for comparison. `__tests__/install.test.ts` pins this
+ * against the matrix above, so a new generated secret cannot be added without appearing here.
+ */
+export const GENERATED_SECRET_KEYS: ReadonlyMap<PlatformDeployService, readonly string[]> = new Map<PlatformDeployService, readonly string[]>([
+	['iam', ['FABRIKA_IAM_SIGNING_KEYS', 'FABRIKA_IAM_RPC_KEY', 'FABRIKA_IAM_PROXY_KEY', 'FABRIKA_IAM_PROVISIONING_KEY']],
+	['operations', ['OPERATIONS_SYNC_KEY', 'FABRIKA_IAM_RPC_KEY']],
+	[
+		'control',
+		[
+			'FABRIKA_IAM_RPC_KEY',
+			'OPERATIONS_SYNC_KEY',
+			'FABRIKA_CONTROL_VAULT_KEY',
+			'FABRIKA_IAM_PROVISIONING_KEY',
+			'FABRIKA_ZEROPS_PROXY_IAM_KEY',
+			'FABRIKA_ZEROPS_ACCESS_TOKEN',
+		],
+	],
+	['proxy', ['FABRIKA_IAM_KEY']],
+])
+
+/**
+ * Write a set of variables, reporting the KEYS — never a value, not even in a debug line.
+ *
+ * Write-first and unconditional: half of these are generated secrets, and a read-compare-write over a
+ * value the platform may or may not hand back verbatim would make the outcome depend on something
+ * nobody has pinned. `PUT /user-data/{id}` replaces in place, so a repeat costs a call and nothing else.
+ */
+export const writeServiceEnv = async (
+	service: ResolvedService,
+	desired: ReadonlyMap<string, string>,
+	{ api, log, signal }: InstallCollaborators,
+): Promise<void> => {
+	for (const [key, value] of desired) {
+		assertRunning(signal)
+		await api.putServiceEnv({ serviceId: service.id, key, value, signal })
+	}
+	log.ok(`${service.hostname}: wrote ${[...desired.keys()].join(', ')}`)
+}

package/src/installation/install-options.ts

@@ -0,0 +1,193 @@
+// The CLI surface of `fabrika platform install --provider=zerops`, parsed once.
+//
+// The same two rules `deploy-options.ts` states, for the same reasons: every CREDENTIAL comes from the
+// environment and only from the environment (there is no `--token`, and an unknown flag is an error, so
+// one cannot arrive on a command line), and everything else may come from a flag OR the environment.
+//
+// Unlike a deploy this command is INTERACTIVE — it confirms before every step that leaves the
+// operator's disk — but nothing here prompts: a missing required value is an error naming both the flag
+// and the variable that would supply it, so a mistyped install fails before it contacts anything.
+
+import { parsePlatformScheme } from './placement-options'
+import { readInstallationSourceDir } from './source-options'
+
+/** The only tier a bootstrap can install. See `assertInstallableTier`. */
+export type InstallablePlatformTier = 'light'
+
+/**
+ * Where the installation's project comes from.
+ *
+ * A UNION rather than an optional id beside a boolean, because the two mistakes worth making
+ * unrepresentable are "neither" and "both": the parser is the only place that can tell them apart, and
+ * downstream code must not have to ask a second time.
+ */
+export type InstallProjectSource =
+	/** One the operator created, empty, by hand. */
+	| { readonly kind: 'existing'; readonly projectId: string }
+	/** One this command creates, from the same declaration the provisioning import is compiled from. */
+	| { readonly kind: 'create'; readonly projectName: string }
+
+/** Every input `runInstall` takes from the operator. */
+export interface PlatformInstallInput {
+	/** The project this installation is brought up in — named, or created here. */
+	readonly project: InstallProjectSource
+	/** The client the project belongs to — required, because the control plane's token is minted on it. */
+	readonly clientId: string
+	/** Zerops personal access token. Environment only. */
+	readonly accessToken: string
+	/** Region API base, when the installation is not on the default one. */
+	readonly apiBaseUrl?: string
+	/** The name this installation calls itself — written to every platform service as `ENVIRONMENT`. */
+	readonly environment: string
+	/** The scheme a browser speaks to this installation. */
+	readonly scheme: 'http' | 'https'
+	readonly sourceDir: string
+	readonly tier: InstallablePlatformTier
+	/** `--yes`: answer every confirmation yes, for a bring-up with nobody at the keyboard. */
+	readonly unattended: boolean
+}
+
+/** The canonical public release repository used for namespace proxy source identities. */
+export const FABRIKA_REPOSITORY_URL = 'https://github.com/contember/fabrika-platform'
+
+const FLAGS = ['--project-id', '--project-name', '--client-id', '--env', '--scheme', '--source-dir', '--tier'] as const
+
+/**
+ * The one way this command runs with nobody watching it.
+ *
+ * Every confirmation defaults to yes, so a pipe carrying blank lines answers all six of them with
+ * nobody reading what they agree to — which is why saying yes unattended is a FLAG and never an
+ * inference: it makes the choice explicit, and it puts it in the shell history of whoever ran it.
+ */
+export const UNATTENDED_FLAG = '--yes'
+
+/** `--create-project`: bring the project up too, instead of naming one the operator made. */
+export const CREATE_PROJECT_FLAG = '--create-project'
+
+/** The two flags that carry no value. Written with one, they are `unexpected argument` like any other. */
+const BOOLEAN_FLAGS = [UNATTENDED_FLAG, CREATE_PROJECT_FLAG] as const
+
+const readFlag = (argv: readonly string[], name: string): string | undefined => {
+	const prefix = `${name}=`
+	const matches = argv.filter((arg) => arg.startsWith(prefix))
+	if (matches.length > 1) {
+		throw new Error(`${name} was given more than once`)
+	}
+	const value = matches[0]?.slice(prefix.length)
+	return value === undefined || value.trim() === '' ? undefined : value.trim()
+}
+
+const readEnv = (env: Record<string, string | undefined>, name: string): string | undefined => {
+	const value = env[name]
+	return value === undefined || value.trim() === '' ? undefined : value.trim()
+}
+
+const setting = (
+	argv: readonly string[],
+	env: Record<string, string | undefined>,
+	flag: string,
+	variable: string,
+): string | undefined => readFlag(argv, flag) ?? readEnv(env, variable)
+
+const required = (value: string | undefined, flag: string, variable: string): string => {
+	if (value === undefined) {
+		throw new Error(`${flag}=<value> or ${variable} is required`)
+	}
+	return value
+}
+
+const assertKnownArguments = (argv: readonly string[]): void => {
+	for (const arg of argv) {
+		if (BOOLEAN_FLAGS.some((flag) => flag === arg)) {
+			continue
+		}
+		const name = arg.split('=')[0] ?? arg
+		if (!FLAGS.some((flag) => flag === name) || !arg.includes('=')) {
+			throw new Error(
+				`unexpected argument \`${arg}\`. Credentials are read from the environment and have no flag; run `
+					+ '`fabrika platform install --provider=zerops --help` for the surface',
+			)
+		}
+	}
+}
+
+/**
+ * The tier this command can bring up.
+ *
+ * Only `light`, and that is a property of the topology rather than a limitation of the flow: the light
+ * tier is the only one that emits a services-only provisioning document, because it is the only one an
+ * operator installs into a project they created themselves. The standard tier is TWO projects that
+ * fabrika creates, which is a different command with a different failure mode.
+ */
+const assertInstallableTier = (raw: string | undefined): InstallablePlatformTier => {
+	if (raw === undefined || raw === 'light') {
+		return 'light'
+	}
+	throw new Error(
+		`--tier=${raw} cannot be installed into a project you created: only the light tier emits a services-only `
+			+ 'provisioning document. The standard tier is two projects fabrika creates itself',
+	)
+}
+
+const readScheme = (argv: readonly string[], env: Record<string, string | undefined>): 'http' | 'https' => {
+	const raw = setting(argv, env, '--scheme', 'FABRIKA_PLATFORM_SCHEME')
+	return parsePlatformScheme(raw)
+}
+
+const readEnvironment = (argv: readonly string[], env: Record<string, string | undefined>): string =>
+	required(setting(argv, env, '--env', 'FABRIKA_PLATFORM_ENVIRONMENT'), '--env', 'FABRIKA_PLATFORM_ENVIRONMENT')
+
+/** The name a created project takes when the operator did not choose one: the installation's own. */
+const defaultProjectName = (environment: string): string => `fabrika-${environment}`
+
+/**
+ * Decide which project this run installs into, and refuse the two ways of asking for both.
+ *
+ * `--project-id` and `--create-project` are alternatives, not a pair — one of them names a project
+ * that exists and the other makes one, and a run that was given both cannot be resolved to the operator's
+ * intent. The refusal names the SOURCE the id came from, because an id inherited from a shell that
+ * exported `FABRIKA_ZEROPS_PROJECT_ID` is the case where the collision is invisible on the command line.
+ */
+const readProjectSource = (argv: readonly string[], env: Record<string, string | undefined>): InstallProjectSource => {
+	const projectId = setting(argv, env, '--project-id', 'FABRIKA_ZEROPS_PROJECT_ID')
+	const projectName = readFlag(argv, '--project-name')
+	if (!argv.includes(CREATE_PROJECT_FLAG)) {
+		if (projectName !== undefined) {
+			throw new Error(
+				`--project-name names a project to CREATE, so it needs ${CREATE_PROJECT_FLAG} beside it. Installing into a project that already `
+					+ 'exists takes --project-id=<id>, which names it by id',
+			)
+		}
+		return { kind: 'existing', projectId: required(projectId, '--project-id', 'FABRIKA_ZEROPS_PROJECT_ID') }
+	}
+	if (projectId !== undefined) {
+		const source = readFlag(argv, '--project-id') === undefined ? 'FABRIKA_ZEROPS_PROJECT_ID' : '--project-id'
+		throw new Error(
+			`${CREATE_PROJECT_FLAG} creates the project and ${source} names one that already exists — pass one or the other, never both`,
+		)
+	}
+	return { kind: 'create', projectName: projectName ?? defaultProjectName(readEnvironment(argv, env)) }
+}
+
+/** Parse the command's arguments and environment into the one input `runInstall` takes. */
+export const parsePlatformInstallArgs = (
+	argv: readonly string[],
+	env: Record<string, string | undefined>,
+): PlatformInstallInput => {
+	const sourceDir = readInstallationSourceDir(argv, env)
+	assertKnownArguments(argv)
+	const apiBaseUrl = readEnv(env, 'FABRIKA_ZEROPS_API_URL')
+	return {
+		project: readProjectSource(argv, env),
+		// Named even when the project id is known: `POST /client/{id}/integration-token` is addressed by
+		// CLIENT, and the project read does not hand one back.
+		clientId: required(setting(argv, env, '--client-id', 'FABRIKA_ZEROPS_CLIENT_ID'), '--client-id', 'FABRIKA_ZEROPS_CLIENT_ID'),
+		accessToken: required(readEnv(env, 'FABRIKA_ZEROPS_ACCESS_TOKEN'), '(no flag)', 'FABRIKA_ZEROPS_ACCESS_TOKEN'),
+		environment: readEnvironment(argv, env),
+		scheme: readScheme(argv, env),
+		sourceDir,
+		tier: assertInstallableTier(setting(argv, env, '--tier', 'FABRIKA_PLATFORM_TIER')),
+		unattended: argv.includes(UNATTENDED_FLAG),
+		...(apiBaseUrl === undefined ? {} : { apiBaseUrl }),
+	}
+}

package/src/installation/install-project.ts

@@ -0,0 +1,201 @@
+import { ENV_ISOLATION, renderYaml, type ZeropsProjectMode, type ZeropsProjectStatus } from '../index'
+import { assertRunning, type InstallCollaborators } from './install-collaborators'
+import type { PlatformInstallInput } from './install-options'
+import { lightTopology } from './install-provisioning'
+
+/** The project compute tier each installable platform tier requires. `corePackage` is upgrade-only. */
+const REQUIRED_PROJECT_MODE: ZeropsProjectMode = 'LIGHT'
+
+/** The one project state this command may install into. */
+const PROJECT_ACTIVE: ZeropsProjectStatus = 'ACTIVE'
+
+/**
+ * Project states a bring-up cannot come back from, so waiting them out is only a slower failure.
+ *
+ * `NEW`, `CREATING` and `STARTING` are on the way to `ACTIVE` and are waited on; so is a status this
+ * build has never seen, which can therefore cost time and never be read as success. These four are the
+ * other direction, and the message must NOT offer `--project-id`: resuming into a `FAILED` or `DELETING`
+ * project installs nothing.
+ */
+const PROJECT_UNUSABLE: ReadonlySet<ZeropsProjectStatus> = new Set<ZeropsProjectStatus>(['FAILED', 'DELETING', 'STOPPING', 'STOPPED'])
+
+/** Live-measured: a created project reads `NEW` at t+1 s and `ACTIVE` at about t+20 s. */
+const PROJECT_POLL_INTERVAL_MS = 2_000
+
+/** The number of SLEEPS, so the wait is 60 × 2 s = two minutes spread between 61 reads. */
+const PROJECT_POLL_ATTEMPTS = (2 * 60_000) / PROJECT_POLL_INTERVAL_MS
+
+/** Consecutive `getProject` failures ridden out before the wait gives the run back to the operator. */
+const PROJECT_READ_FAILURES = 3
+
+/**
+ * The document `--create-project` applies, carrying a `project:` block and NO services.
+ *
+ * Taken from the same declaration the provisioning import is compiled from, so `envIsolation: service`
+ * and `corePackage: LIGHT` — the two settings a project accepts at CREATION only and never afterwards —
+ * have exactly one source. Only the name is this run's. `renderImportYaml` is not the renderer here
+ * because it refuses a document with no services, and this one deliberately has none: the services arrive
+ * through the services-only import, into the project this creates.
+ */
+const createProjectYaml = (environment: string, projectName: string): string => {
+	const declared = lightTopology(environment).provision.document.project
+	if (declared === undefined || declared.corePackage !== REQUIRED_PROJECT_MODE || declared.envIsolation !== ENV_ISOLATION) {
+		throw new Error(`the light platform topology declares no \`${REQUIRED_PROJECT_MODE}\` project with \`envIsolation: ${ENV_ISOLATION}\` to create`)
+	}
+	return renderYaml({ project: { ...declared, name: projectName }, services: [] })
+}
+
+/** One poll of the created project: its status, or the failure the read itself ended in. */
+type ProjectRead =
+	| { readonly ok: true; readonly status: ZeropsProjectStatus | undefined }
+	| { readonly ok: false; readonly failure: unknown }
+
+/**
+ * Wait for a created project to be `ACTIVE`.
+ *
+ * Live-measured (2026-08-21): the import answers in about a second and the project then reads `NEW` →
+ * `CREATING` → `ACTIVE` at about t+20 s. Whether a service import into a `CREATING` project succeeds is
+ * NOT measured, so this waits rather than finds out.
+ *
+ * Three outcomes, and the difference between them is what the operator is told to do next. `ACTIVE`
+ * returns. A state in `PROJECT_UNUSABLE` throws WITHOUT a resume hint, because the project is spent. A
+ * transient state, an unknown one, or a read that fails outright is waited out — a 5xx on the read says
+ * nothing about the project, so a few in a row are ridden out before the run is handed back, and it is
+ * handed back with the id, because by then a project exists that the operator would otherwise leak.
+ */
+const waitForProjectActive = async (projectId: string, { api, sleep, signal }: InstallCollaborators): Promise<void> => {
+	let failures = 0
+	let last: ZeropsProjectStatus | 'unreadable' | undefined
+	for (let attempt = 0;; attempt += 1) {
+		assertRunning(signal)
+		const read: ProjectRead = await api.getProject({ projectId, signal }).then(
+			(project): ProjectRead => ({ ok: true, status: project.status }),
+			(failure: unknown): ProjectRead => ({ ok: false, failure }),
+		)
+		if (!read.ok) {
+			failures += 1
+			last = 'unreadable'
+			if (failures > PROJECT_READ_FAILURES) {
+				throw new Error(
+					`Zerops project ${projectId} was created but could not be read ${failures} times in a row. Re-run the install with `
+						+ `--project-id=${projectId} instead of --create-project`,
+					{ cause: read.failure },
+				)
+			}
+		} else {
+			failures = 0
+			last = read.status
+			if (read.status === PROJECT_ACTIVE) {
+				return
+			}
+			if (read.status !== undefined && PROJECT_UNUSABLE.has(read.status)) {
+				throw new Error(
+					`Zerops project ${projectId} reads \`${read.status}\`, which a bring-up cannot recover from: the project exists and nothing `
+						+ 'can be installed into it. Delete it and run the install again — do NOT resume into this one',
+				)
+			}
+		}
+		if (attempt >= PROJECT_POLL_ATTEMPTS) {
+			throw new Error(
+				`Zerops project ${projectId} still reads \`${last ?? 'no status'}\` after two minutes (${PROJECT_POLL_ATTEMPTS + 1} reads, `
+					+ `${PROJECT_POLL_INTERVAL_MS / 1_000} s apart). It exists and may yet settle — re-run the install with `
+					+ `--project-id=${projectId} instead of --create-project`,
+			)
+		}
+		await sleep(PROJECT_POLL_INTERVAL_MS, signal)
+	}
+}
+
+/**
+ * Create the project this installation is brought up in, and wait for it to be usable.
+ *
+ * The id is reported BEFORE the wait, and that ordering is the whole point of the line: an interrupted
+ * run has already spent a project on the account, and this id is the only way back to it.
+ */
+const createProject = async (
+	input: PlatformInstallInput,
+	environment: string,
+	projectName: string,
+	collaborators: InstallCollaborators,
+): Promise<string> => {
+	const { api, log, signal } = collaborators
+	assertRunning(signal)
+	const result = await api.importProject({
+		clientId: input.clientId,
+		yaml: createProjectYaml(environment, projectName),
+		signal,
+	})
+	if (result.projectId === '') {
+		throw new Error(`Zerops created a project named ${projectName} with no id — nothing can be installed into it`)
+	}
+	log.ok(
+		`created Zerops project ${result.projectId} (${result.projectName ?? projectName}) — resume with --project-id=${result.projectId} if this `
+			+ 'run is interrupted',
+	)
+	await waitForProjectActive(result.projectId, collaborators)
+	return result.projectId
+}
+
+/** Read the project and refuse anything the topology cannot be installed into. */
+const resolveProject = async (
+	input: PlatformInstallInput,
+	projectId: string,
+	{ api, log, signal }: InstallCollaborators,
+): Promise<{ id: string; name: string }> => {
+	const project = await api.getProject({ projectId, signal })
+	if (project.id === '') {
+		throw new Error(`Zerops project ${projectId} could not be read with this token`)
+	}
+	if (project.mode === undefined) {
+		// Not a mismatch, so not a refusal: the client narrows an unknown value to absent, and blocking an
+		// install on a field the API did not state would be refusing on an absence of evidence.
+		log.warn(`Zerops did not state project ${project.name}'s mode; the ${input.tier} tier expects ${REQUIRED_PROJECT_MODE}`)
+	} else if (project.mode !== REQUIRED_PROJECT_MODE) {
+		throw new Error(
+			`Zerops project ${project.name} is ${project.mode} and the ${input.tier} tier needs ${REQUIRED_PROJECT_MODE}. \`corePackage\` is `
+				+ 'upgrade-only and its upgrade is partly destructive, so this is not something an install may change — create the project '
+				+ `with core package ${REQUIRED_PROJECT_MODE}, or install a tier that matches`,
+		)
+	}
+	return { id: project.id, name: project.name }
+}
+
+/**
+ * Settle which project this run installs into — the operator's, or one created here.
+ *
+ * ONE confirmation either way, and both cover the read that follows: a created project is read back
+ * through the same `resolveProject` an operator-made one goes through, so the core package is checked on
+ * the project that will actually be installed into rather than on the document that asked for it.
+ */
+export const resolveInstallationProject = async (
+	input: PlatformInstallInput,
+	environment: string,
+	collaborators: InstallCollaborators,
+): Promise<{ id: string; name: string }> => {
+	const { log, prompts } = collaborators
+	const source = input.project
+	if (source.kind === 'existing') {
+		log.step('Resolve the project the operator created')
+		// One confirmation covers every READ this step makes — the project, its services, and which variable
+		// KEYS those services already carry. None of them changes anything.
+		if (
+			!(await prompts.confirm(`Read Zerops project ${source.projectId} and its services? (the token, the id, the core package, what exists)`, true))
+		) {
+			throw new Error('declined: nothing was contacted, and re-running the install is safe')
+		}
+		return resolveProject(input, source.projectId, collaborators)
+	}
+	log.step('Create the project this installation is brought up in')
+	log.info('`envIsolation` and `corePackage` are settable at project CREATION only, which is why the project is created from here.')
+	if (
+		!(await prompts.confirm(
+			`CREATE Zerops project \`${source.projectName}\` (core package ${REQUIRED_PROJECT_MODE}, envIsolation ${ENV_ISOLATION}) on client `
+				+ `${input.clientId}, then read it back?`,
+			true,
+		))
+	) {
+		throw new Error('declined: no project was created, and re-running the install is safe')
+	}
+	const projectId = await createProject(input, environment, source.projectName, collaborators)
+	return resolveProject(input, projectId, collaborators)
+}