@fabrika/provider-zerops 0.0.26 → 0.3.1

package/src/descriptor.ts

@@ -0,0 +1,135 @@
+import type { JsonValue } from '@fabrika/provider-contract'
+import { isAlias, isMap, isNode, isScalar, isSeq, parseAllDocuments } from 'yaml'
+import { z } from 'zod'
+import { renderYaml } from './compile'
+
+export interface ZeropsDescriptor {
+	document: { readonly [key: string]: JsonValue }
+	setups: readonly string[]
+}
+
+export interface PreparedZeropsDescriptor {
+	contents: string
+	setup: string
+}
+
+const invalid = (reason: string): never => {
+	throw new Error(`invalid fabrika manifest: zerops.yaml ${reason}`)
+}
+
+const descriptorJsonSchema: z.ZodType<JsonValue, z.ZodTypeDef, unknown> = z.lazy(() =>
+	z.union([
+		z.string(),
+		z.number(),
+		z.boolean(),
+		z.null(),
+		z.array(descriptorJsonSchema),
+		descriptorMappingSchema,
+	])
+)
+// Zod records drop __proto__; descriptor mappings must preserve every decoded key and its order.
+const descriptorMappingSchema: z.ZodType<{ [key: string]: JsonValue }, z.ZodTypeDef, unknown> = z.preprocess(
+	(value) => typeof value === 'object' && value !== null && !Array.isArray(value) ? Object.entries(value) : null,
+	z.array(z.tuple([z.string(), descriptorJsonSchema])).transform((entries) => Object.fromEntries(entries)),
+)
+const phaseSchema = z.intersection(descriptorMappingSchema, z.object({ envVariables: z.record(z.string()).optional() }))
+const setupSchema = z.intersection(
+	descriptorMappingSchema,
+	z.object({
+		setup: z.string().refine((value) => value.trim() !== ''),
+		build: phaseSchema.optional(),
+		run: phaseSchema.optional(),
+	}),
+)
+const descriptorDocumentSchema = z.intersection(descriptorMappingSchema, z.object({ zerops: z.array(setupSchema).min(1) }))
+
+// Compare decimal significands, not binary floats: parsing must not silently round source digits.
+const decimalIdentity = (source: string): string => {
+	const match = /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/.exec(source)
+	if (match === null) return invalid('contains an unsupported numeric representation')
+	const fraction = match[3] ?? ''
+	const digits = `${match[2] ?? ''}${fraction}`.replace(/^0+/, '')
+	if (digits === '') return '0'
+	const significant = digits.replace(/0+$/, '')
+	const exponent = BigInt(match[4] ?? '0') - BigInt(fraction.length) + BigInt(digits.length - significant.length)
+	return `${match[1] === '-' ? '-' : ''}${significant}e${exponent}`
+}
+
+const decodeNode = (node: unknown): JsonValue => {
+	if (isAlias(node)) return invalid('must not contain aliases')
+	if (!isNode(node)) return invalid('contains an unsupported node')
+	if (node.tag !== undefined) return invalid('must not contain explicit tags')
+	if ('anchor' in node && node.anchor !== undefined) return invalid('must not contain anchors')
+	if (isMap(node)) {
+		const entries: Array<[string, JsonValue]> = []
+		const keys = new Set<string>()
+		for (const pair of node.items) {
+			const key = decodeNode(pair.key)
+			if (typeof key !== 'string') return invalid('requires string mapping keys')
+			if (key === '<<') return invalid('must not contain merge keys')
+			if (keys.has(key)) return invalid('must not contain duplicate keys')
+			keys.add(key)
+			entries.push([key, decodeNode(pair.value)])
+		}
+		return Object.fromEntries(entries)
+	}
+	if (isSeq(node)) return node.items.map(decodeNode)
+	if (!isScalar(node)) return invalid('contains an unsupported node')
+	const value: unknown = node.value
+	if (typeof value === 'bigint') {
+		const number = Number(value)
+		if (!Number.isSafeInteger(number)) return invalid('contains an inexact number')
+		return number
+	}
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))) return invalid('contains an inexact number')
+		if (node.source === undefined || decimalIdentity(node.source) !== decimalIdentity(String(value))) return invalid('contains an inexact number')
+		return value
+	}
+	if (typeof value === 'string' && /\p{Surrogate}/u.test(value)) return invalid('contains an invalid Unicode scalar')
+	if (value === null || typeof value === 'string' || typeof value === 'boolean') return value
+	return invalid('contains an unsupported scalar')
+}
+
+const parseDocument = (contents: string, schema: 'core' | 'yaml-1.1'): JsonValue => {
+	const documents = parseAllDocuments(contents, { schema, intAsBigInt: true, merge: false, resolveKnownTags: false, uniqueKeys: true })
+	const document = documents[0]
+	if (documents.length !== 1 || document === undefined) return invalid('requires exactly one mapping document')
+	if (document.errors.length > 0 || document.warnings.length > 0) return invalid('is not parseable YAML without errors or warnings')
+	return decodeNode(document.contents)
+}
+
+export const parseZeropsDescriptor = (contents: string): ZeropsDescriptor => {
+	// Go readers fold or reject these raw characters; escaped string data remains supported.
+	if (/[\u007f-\u009f\u2028\u2029\ufffe\uffff]/u.test(contents)) return invalid('contains raw characters unsupported by YAML-1.1 readers')
+	const document = parseDocument(contents, 'core')
+	const legacy = parseDocument(contents, 'yaml-1.1')
+	if (JSON.stringify(document) !== JSON.stringify(legacy)) return invalid('contains ambiguous plain scalars; quote them explicitly')
+	const result = descriptorDocumentSchema.safeParse(document)
+	if (!result.success) {
+		const path = result.error.issues[0]?.path ?? []
+		if (path.includes('envVariables')) return invalid('requires envVariables string mappings')
+		if (path.includes('build') || path.includes('run')) return invalid('requires build and run mappings')
+		if (path.length > 1) return invalid('requires string setup names')
+		return invalid(path.length === 0 ? 'requires a mapping document' : 'requires a nonempty zerops sequence')
+	}
+	const setups: string[] = []
+	for (const entry of result.data.zerops) {
+		if (setups.includes(entry.setup)) return invalid('must not contain duplicate setup names')
+		setups.push(entry.setup)
+	}
+	return { document: result.data, setups }
+}
+
+export const selectZeropsDescriptorSetup = (parsed: ZeropsDescriptor, setup?: string): string => {
+	const selected = setup ?? (parsed.setups.length === 1 ? parsed.setups[0] : undefined)
+	if (selected === undefined) return invalid('requires an explicit setup selector for multiple setups')
+	if (!parsed.setups.includes(selected)) return invalid('does not contain the selected setup')
+	return selected
+}
+
+export const prepareZeropsDescriptor = (contents: string, setup?: string): PreparedZeropsDescriptor => {
+	const parsed = parseZeropsDescriptor(contents)
+	const selected = selectZeropsDescriptorSetup(parsed, setup)
+	return { contents: renderYaml(parsed.document), setup: selected }
+}

package/src/index.ts

@@ -1,5 +1,4 @@
 export {
-	asAppVersionStatus,
 	createZeropsApi,
 	waitForProcess,
 	ZEROPS_ACTIVE,
@@ -36,7 +35,6 @@ export { defineApp, isZeropsAppConfig, useSharedPostgres, zeropsSharedServiceHos
 export type { ZeropsAuthoredAppConfig } from './authoring'
 export { parseZeropsCliArgs } from './cli-args'
 export type { ZeropsCliArgs } from './cli-args'
-export { zeropsTargetCodec } from './codec'
 export { defaultSleep, defaultZeropsCollaborators } from './collaborators'
 export type { Sleeper, ZeropsCollaboratorFactory, ZeropsCollaborators } from './collaborators'
 export {
@@ -49,10 +47,12 @@ export {
 	renderImportYaml,
 	renderYaml,
 } from './compile'
-export type { CompileInput, ZeropsImportDocument } from './compile'
-export { createZeropsControlProvider, zeropsStoredTargetCodec } from './control'
-export type { ZeropsBeforeDeploy, ZeropsBeforeDeployInput, ZeropsControlProviderOptions, ZeropsProviderExecutor, ZeropsStoredTarget } from './control'
+export type { CompileInput, ZeropsImportDocument, ZeropsJsonImportDocument } from './compile'
+export { createZeropsControlProvider, parseZeropsCheckpoint, zeropsStoredTargetCodec } from './control'
+export type { ZeropsControlProviderOptions, ZeropsStoredTarget } from './control'
+export { type PreparedZeropsDescriptor, prepareZeropsDescriptor } from './descriptor'
 export {
+	assertFabrikaManifestCoordinates,
 	compileFabrikaManifest,
 	createZeropsArtifactSourceDescriptor,
 	FABRIKA_MANIFEST_VERSION,
@@ -69,7 +69,9 @@ export {
 	compileZeropsNamespaceTopology,
 	createZeropsNamespaceCapabilities,
 	createZeropsNamespaceOperator,
-	ensureNamespaceProxyIam,
+	decodeZeropsNamespaceProxySource,
+	republishProxy,
+	verifyZeropsNamespaceProxySource,
 	ZEROPS_NAMESPACE_IAM_ISSUER_VARIABLE,
 	ZEROPS_NAMESPACE_IAM_KEY_VARIABLE,
 	ZEROPS_NAMESPACE_POSTGRES_HOSTNAME,
@@ -79,143 +81,37 @@ export {
 	zeropsNamespaceTargetCodec,
 } from './namespace'
 export type {
-	NamespaceProxyIamInput,
 	ZeropsNamespaceOperatorOptions,
 	ZeropsNamespaceOptions,
 	ZeropsNamespacePlanOptions,
 	ZeropsNamespacePostgres,
 	ZeropsNamespacePresetInput,
+	ZeropsNamespaceProxyBuild,
+	ZeropsNamespaceProxyDeployment,
+	ZeropsNamespaceProxySource,
 	ZeropsNamespacePublicAccess,
 	ZeropsNamespaceTarget,
 	ZeropsNamespaceTopology,
+	ZeropsProxyApi,
+	ZeropsProxyRepublishInput,
 } from './namespace'
-export { runZeropsNamespaceCommand } from './namespace-command'
-export type { ZeropsNamespaceCommandDependencies } from './namespace-command'
+export { postgresSchema as zeropsNamespacePostgresSchema } from './namespace/codec'
 export { buildZeropsPlan, resolveDeployHostname } from './plan'
-export type { ZeropsJobSpec, ZeropsPlan, ZeropsStepKind } from './plan'
-export { CANCELLED, createZeropsProvider, interpolateManifest, zeropsProvider } from './provider'
-export type { ZeropsProvider } from './provider'
+export type { ZeropsStep, ZeropsStepKind } from './plan'
+export { CANCELLED, createZeropsDeployer, interpolateManifest } from './provider'
+export type { ZeropsDeployResult, ZeropsDeployRun } from './provider'
 export type * from './schema.generated'
-export {
-	buildZeropsSourceCancelRequest,
-	buildZeropsSourceCancelResponse,
-	buildZeropsSourceCredentialActivateRequestV2,
-	buildZeropsSourceCredentialActivateResponseV2,
-	buildZeropsSourceCredentialBundleV2,
-	buildZeropsSourceCredentialStatusRequestV2,
-	buildZeropsSourceCredentialStatusResponseV2,
-	buildZeropsSourceErrorEnvelope,
-	buildZeropsSourceInstallationsVerifyRequest,
-	buildZeropsSourceInstallationsVerifyResponse,
-	buildZeropsSourceResolveRequest,
-	buildZeropsSourceResolveRequestV2,
-	buildZeropsSourceResolveResponse,
-	buildZeropsSourceResolveResponseV2,
-	buildZeropsSourceUploadRequest,
-	buildZeropsSourceUploadRequestV2,
-	buildZeropsSourceUploadResponse,
-	buildZeropsSourceUploadResponseV2,
-	buildZeropsSourceWebhookConfigureRequest,
-	buildZeropsSourceWebhookConfigureResponse,
-	decodeZeropsSourceCancelRequest,
-	decodeZeropsSourceCancelResponse,
-	decodeZeropsSourceCredentialActivateRequestV2,
-	decodeZeropsSourceCredentialActivateResponseV2,
-	decodeZeropsSourceCredentialBundleV2,
-	decodeZeropsSourceCredentialStatusRequestV2,
-	decodeZeropsSourceCredentialStatusResponseV2,
-	decodeZeropsSourceErrorEnvelope,
-	decodeZeropsSourceInstallationsVerifyRequest,
-	decodeZeropsSourceInstallationsVerifyResponse,
-	decodeZeropsSourceResolveRequest,
-	decodeZeropsSourceResolveRequestV2,
-	decodeZeropsSourceResolveResponse,
-	decodeZeropsSourceResolveResponseV2,
-	decodeZeropsSourceUploadRequest,
-	decodeZeropsSourceUploadRequestV2,
-	decodeZeropsSourceUploadResponse,
-	decodeZeropsSourceUploadResponseV2,
-	decodeZeropsSourceWebhookConfigureRequest,
-	decodeZeropsSourceWebhookConfigureResponse,
-	normalizeZeropsSourceRepository,
-	serializeZeropsSourceCredentialBundleV2,
-	sha256ZeropsSourceCredentialBundleV2,
-	ZEROPS_SOURCE_CANCEL_PATH,
-	ZEROPS_SOURCE_CREDENTIAL_ACTIVATE_PATH_V2,
-	ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2,
-	ZEROPS_SOURCE_CREDENTIAL_ENV_V2_PREFIX,
-	ZEROPS_SOURCE_CREDENTIAL_STATUS_PATH_V2,
-	ZEROPS_SOURCE_ERROR_CODES,
-	ZEROPS_SOURCE_ERROR_STAGES,
-	ZEROPS_SOURCE_INSTALLATIONS_VERIFY_PATH,
-	ZEROPS_SOURCE_PROTOCOL_VERSION,
-	ZEROPS_SOURCE_PROTOCOL_VERSION_V2,
-	ZEROPS_SOURCE_RESOLVE_PATH,
-	ZEROPS_SOURCE_RESOLVE_PATH_V2,
-	ZEROPS_SOURCE_UPLOAD_PATH,
-	ZEROPS_SOURCE_UPLOAD_PATH_V2,
-	ZEROPS_SOURCE_WEBHOOK_CONFIGURE_PATH,
-	zeropsSourceCredentialEnvV2,
-} from './source'
+export { isZeropsUploadDestination, normalizeZeropsSourceRepository } from './source'
+export type { ZeropsSourceRepository } from './source'
 export type {
-	ZeropsSourceCancelInput,
-	ZeropsSourceCancelRequestV1,
-	ZeropsSourceCancelResponseV1,
-	ZeropsSourceCancelResult,
-	ZeropsSourceClient,
-	ZeropsSourceClientV2,
-	ZeropsSourceCredentialActivateInput,
-	ZeropsSourceCredentialActivateRequestV2,
-	ZeropsSourceCredentialActivateResponseV2,
-	ZeropsSourceCredentialActiveStatusResponseV2,
-	ZeropsSourceCredentialAnonymousStatusResponseV2,
-	ZeropsSourceCredentialBundleV2,
-	ZeropsSourceCredentialManager,
-	ZeropsSourceCredentialManagerV2,
-	ZeropsSourceCredentialStatusInput,
-	ZeropsSourceCredentialStatusRequestV2,
-	ZeropsSourceCredentialStatusResponseV2,
-	ZeropsSourceDescriptor,
-	ZeropsSourceErrorCode,
-	ZeropsSourceErrorEnvelope,
-	ZeropsSourceErrorStage,
-	ZeropsSourceGitHubAppIdentityV1,
-	ZeropsSourceInstallationScopeV1,
-	ZeropsSourceInstallationsVerifyInput,
-	ZeropsSourceInstallationsVerifyRequestV1,
-	ZeropsSourceInstallationsVerifyResponseV1,
-	ZeropsSourceInstallationVerificationV1,
-	ZeropsSourcePrivateBindingV2,
-	ZeropsSourceRepository,
+	ZeropsSourceArchive,
+	ZeropsSourcePort,
+	ZeropsSourcePrivateBinding,
+	ZeropsSourceResolution,
 	ZeropsSourceResolveInput,
-	ZeropsSourceResolveInputV2,
-	ZeropsSourceResolveRequestV1,
-	ZeropsSourceResolveRequestV2,
-	ZeropsSourceResolveResponseV1,
-	ZeropsSourceResolveResponseV2,
-	ZeropsSourceResolveResult,
 	ZeropsSourceUploadInput,
-	ZeropsSourceUploadInputV2,
-	ZeropsSourceUploadRequestV1,
-	ZeropsSourceUploadRequestV2,
-	ZeropsSourceUploadResponseV1,
-	ZeropsSourceUploadResponseV2,
 	ZeropsSourceUploadResult,
-	ZeropsSourceWebhookConfigureInput,
-	ZeropsSourceWebhookConfigureRequestV1,
-	ZeropsSourceWebhookConfigureResponseV1,
-} from './source'
-export { createZeropsSourceConnectionAdmin, SourceConnectionAdminError } from './source-connection'
-export type {
-	SourceConnectionActivateInput,
-	SourceConnectionAdmin,
-	SourceConnectionAdminErrorCode,
-	SourceConnectionInspection,
-	SourceConnectionStatus,
-	SourceConnectionStatusInput,
-	SourceConnectionZeropsApi,
-	ZeropsSourceConnectionAdminOptions,
-} from './source-connection'
+} from './source/port'
 export type {
 	ZeropsAppConfig,
 	ZeropsCompilerOwnedProjectField,

package/src/installation/admin-options.ts

@@ -0,0 +1,128 @@
+// The CLI surface of `fabrika platform admin --provider=zerops`, parsed once.
+//
+// The same two rules `install-options.ts` and `deploy-options.ts` state: the CREDENTIAL comes from the
+// environment and only from the environment (there is no `--key`, 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.
+//
+// The command is unattended by construction — it is additive and idempotent, so it confirms nothing
+// and prompts for nothing — and a missing required value is an error naming both the flag and the
+// variable that would supply it.
+
+import { parsePlatformHostname, parsePlatformScheme } from './placement-options'
+
+/** Every input `runPlatformAdmin` takes from the operator. */
+export interface PlatformAdminInput {
+	/** The mailbox that identifies the first administrator. */
+	readonly email: string
+	/** IAM's public hostname — the address the proxy fronts, as `platform deploy` names it. */
+	readonly iamHost: string
+	/** The scheme a browser speaks to this installation. With `iamHost` it composes IAM's public origin. */
+	readonly scheme: 'http' | 'https'
+	/** The `px_` provisioning key `platform install` printed. Environment only. */
+	readonly provisioningKey: string
+	/** Replace an outstanding enrollment instead of reporting it. */
+	readonly reissue: boolean
+}
+
+const FLAGS = ['--email', '--iam-host', '--scheme'] as const
+
+/**
+ * The one way a second enrollment URL is ever issued.
+ *
+ * Printing the URL once is the property a re-run has to keep, so an outstanding enrollment is
+ * REPORTED rather than replaced. An enrollment that expired unopened would otherwise be a dead end —
+ * the only other way to issue one is a console nobody can sign in to yet — so the way out is a flag,
+ * which makes replacing the outstanding one an explicit choice.
+ */
+export const REISSUE_FLAG = '--reissue'
+
+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 (arg === REISSUE_FLAG) {
+			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 admin --provider=zerops --help` for the surface',
+			)
+		}
+	}
+}
+
+const readScheme = (argv: readonly string[], env: Record<string, string | undefined>): 'http' | 'https' => {
+	const raw = setting(argv, env, '--scheme', 'FABRIKA_PLATFORM_SCHEME')
+	return parsePlatformScheme(raw)
+}
+
+/**
+ * IAM's public hostname, checked to be one.
+ *
+ * A BARE hostname, the same coordinate `platform deploy` takes under the same name: the origin is
+ * composed from it and `--scheme`, so a value carrying either would compose a second one.
+ */
+const readIamHost = (argv: readonly string[], env: Record<string, string | undefined>): string => {
+	const host = required(setting(argv, env, '--iam-host', 'FABRIKA_PLATFORM_IAM_HOST'), '--iam-host', 'FABRIKA_PLATFORM_IAM_HOST')
+	return parsePlatformHostname(host)
+}
+
+/**
+ * The credential, and the one message that says why there is no flag for it.
+ *
+ * `required` would name a flag beside the variable, and there is none — a key on a command line lands
+ * in a CI log, a process listing and the shell history of whoever reproduced the run.
+ */
+const provisioningKey = (env: Record<string, string | undefined>): string => {
+	const value = readEnv(env, 'FABRIKA_IAM_PROVISIONING_KEY')
+	if (value === undefined) {
+		throw new Error(
+			'FABRIKA_IAM_PROVISIONING_KEY is required. It has no flag: the key platform install printed comes from the environment only.',
+		)
+	}
+	return value
+}
+
+/** Parse the command's arguments and environment into the one input `runPlatformAdmin` takes. */
+export const parsePlatformAdminArgs = (
+	argv: readonly string[],
+	env: Record<string, string | undefined>,
+): PlatformAdminInput => {
+	assertKnownArguments(argv)
+	return {
+		email: required(setting(argv, env, '--email', 'FABRIKA_PLATFORM_ADMIN_EMAIL'), '--email', 'FABRIKA_PLATFORM_ADMIN_EMAIL'),
+		iamHost: readIamHost(argv, env),
+		scheme: readScheme(argv, env),
+		provisioningKey: provisioningKey(env),
+		reissue: argv.includes(REISSUE_FLAG),
+	}
+}

package/src/installation/admin.ts

@@ -0,0 +1,123 @@
+// `fabrika platform admin --provider=zerops` — admit the first administrator to a running installation.
+//
+// `platform install` ends with a provisioning key and nobody who can sign in, and until this command
+// existed the four `/admin/rpc` calls that fix that lived in a throwaway script. The mechanics are
+// provider-neutral and live in `@fabrika/installation-init`; what belongs HERE is the Zerops-shaped
+// half — where this installation's IAM answers, and which credential reaches it.
+//
+// It confirms nothing and prompts for nothing. Every step is additive and idempotent, so there is
+// nothing for an operator to agree to, and `install`'s stdin rule (a non-terminal stdin is refused
+// without `--yes`) has nothing to guard here.
+
+import {
+	action as consoleAction,
+	createIamAdminClient,
+	ensureFirstAdministrator,
+	type FirstAdministratorApi,
+	type FirstAdministratorResult,
+} from '@fabrika/installation-init'
+import type { PlatformAdminInput } from './admin-options'
+import { REISSUE_FLAG } from './admin-options'
+import { platformOrigin } from './hosts'
+import { MACHINE_KEY_NEXT_STEP_TITLE, machineKeyNextStepLines } from './machine-key'
+
+/**
+ * Where this command's progress goes.
+ *
+ * The same rule the rest of this package's logging states: no helper here takes a secret value. The
+ * enrollment URL is a credential in transit and never travels through the log — it goes to `print`,
+ * which is stdout and nothing else.
+ */
+export interface AdminLog {
+	step(title: string): void
+	info(message: string): void
+	warn(message: string): void
+	ok(message: string): void
+}
+
+/** `AdminLog` plus the boxed hand-off the closing block uses — composed in below, not asked of the caller. */
+export interface AdminReportLog extends AdminLog {
+	action(title: string, lines: readonly string[]): void
+}
+
+export interface PlatformAdminCollaborators {
+	readonly client: FirstAdministratorApi
+	readonly log: AdminReportLog
+	/** stdout, for the command's one piece of DATA: the enrollment URL, on a line of its own. */
+	readonly print: (line: string) => void
+}
+
+/** The real collaborators: the typed admin client for this installation's public IAM, and the console. */
+export const consoleAdminCollaborators = (input: PlatformAdminInput, log: AdminLog): PlatformAdminCollaborators => ({
+	client: createIamAdminClient({ origin: platformOrigin(input.scheme, input.iamHost), provisioningKey: input.provisioningKey }),
+	log: { ...log, action: (title, lines) => consoleAction(title, [...lines]) },
+	print: (line) => console.info(line),
+})
+
+/**
+ * Admit the first administrator, and report exactly what was found rather than what was assumed.
+ *
+ * Nothing is printed before the whole sequence has succeeded except its progress: a failure — an
+ * unreachable IAM, a refused key, a 4xx — throws, and the CLI exits non-zero with that one message.
+ * No partial result and, above all, no URL.
+ */
+export const runPlatformAdmin = async (input: PlatformAdminInput, collaborators: PlatformAdminCollaborators): Promise<void> => {
+	const { client, log, print } = collaborators
+	const origin = platformOrigin(input.scheme, input.iamHost)
+
+	log.step('Admit the first administrator')
+	log.info(`${origin} · ${input.email}`)
+	if (input.scheme === 'http' && !isLoopback(input.iamHost)) {
+		// Two credentials cross this connection: the provisioning key going out, the enrollment URL
+		// coming back. On a loopback address that is a local composition; anywhere else it is a mistake.
+		log.warn('this speaks plain http to a host that is not loopback — the provisioning key and the enrollment URL both cross it in the clear')
+	}
+
+	const result = await ensureFirstAdministrator(client, { email: input.email, reissueEnrollment: input.reissue })
+	report(result, log)
+	announceEnrollment(result, log, print)
+	// The next command an operator runs needs an origin this one already holds and two keys it must not
+	// print. Naming both places is the difference between one `key issue` and a guessed hostname.
+	log.action(MACHINE_KEY_NEXT_STEP_TITLE, machineKeyNextStepLines({ iamOrigin: origin }))
+}
+
+const report = (result: FirstAdministratorResult, log: AdminLog): void => {
+	log.ok(
+		result.principal === 'invited'
+			? `invited ${result.email} as principal ${result.principalId}`
+			: `${result.email} already exists as principal ${result.principalId}`,
+	)
+	// `app: null` is the whole point: an `admin` grant scoped to the console's own app id leaves
+	// Delivery and Operations working while the Access plane refuses.
+	log.ok(result.grant === 'created' ? 'granted the cross-app `admin` role' : 'the cross-app `admin` role was already granted')
+}
+
+/**
+ * The one place the enrollment URL is ever written, and it is written once.
+ *
+ * A URL that sets a password is a credential: it goes to stdout on a line of its own, is stored
+ * nowhere, and is not repeated. The three other outcomes carry no URL at all and say what was found.
+ */
+const announceEnrollment = (result: FirstAdministratorResult, log: AdminLog, print: (line: string) => void): void => {
+	if (result.enrollment.state === 'already-set') {
+		log.ok('a password is already set for this principal — no enrollment was issued')
+		log.info('Sign in at the console. A forgotten password is a reset, which the Access plane issues to a signed-in administrator.')
+		return
+	}
+	if (result.enrollment.state === 'outstanding') {
+		log.warn(`an enrollment is already outstanding — a second one was NOT issued. Pass ${REISSUE_FLAG} to replace it if the first expired unopened`)
+		return
+	}
+	if (result.enrollment.state === 'emailed') {
+		log.ok(`the enrollment was emailed to ${result.enrollment.email}, valid until ${expiry(result.enrollment.expiresAt)}`)
+		return
+	}
+	log.ok(`enrollment issued, valid until ${expiry(result.enrollment.expiresAt)}`)
+	log.info('The URL below sets the first password. It is a credential: it is printed once, stored nowhere, and it expires.')
+	print(result.enrollment.url)
+}
+
+const expiry = (unixSeconds: number): string => new Date(unixSeconds * 1000).toISOString()
+
+/** Where `http` is a local composition rather than a credential crossing the open network. */
+const isLoopback = (host: string): boolean => host === 'localhost' || host.endsWith('.localhost') || host === '127.0.0.1' || host === '::1'