@fabrika/provider-zerops 0.2.0 → 0.3.2

package/src/installation/init-options.ts

@@ -0,0 +1,148 @@
+// The CLI surface of `fabrika platform init --provider=zerops`, parsed once.
+//
+// The same two rules `deploy-options.ts` states: every CREDENTIAL comes from the environment and only
+// from the environment, and everything else may come from a flag OR the environment, flag first.
+// Nothing here prompts — a missing required value is an error naming both the flag and the variable —
+// so a pipeline or an agent drives init end to end. Its confirmations stay, answered by `--yes`.
+
+import {
+	CHECKOUT_FLAG,
+	type CommandEnv,
+	describeArgument,
+	readEnv,
+	readFlag,
+	requiredSetting,
+	setting,
+	sidecarCheckoutDir,
+	UNATTENDED_FLAG,
+} from '@fabrika/installation-init'
+import { parsePlatformHosts } from './placement-options'
+import { assertPinnedTag, defaultCheckoutName, defaultSidecarRepo } from './sidecar'
+
+/** The name every bypass in this platform is gated on, and therefore the one name an installation cannot take. */
+const LOCAL_ENVIRONMENT = 'local'
+
+/** Every input `runInit` takes from the operator. */
+export interface InitInput {
+	/** Names the GitHub Environment, the default repository and the local checkout directory. */
+	readonly installation: string
+	readonly repo: string
+	/** The sidecar's local checkout: `--checkout`, or `fabrika-zerops-<installation>` in the working directory. */
+	readonly checkoutDir: string
+	/** The published fabrika-platform tag the sidecar pins in `fabrika.ref`. */
+	readonly fabrikaRef: string
+	readonly projectId: string
+	/** The name this installation calls itself — written to every service as `ENVIRONMENT`. */
+	readonly environmentName: string
+	/** All three or none: none derives them from the proxy's Zerops subdomains. */
+	readonly hosts?: { readonly iam: string; readonly control: string; readonly operations: string }
+	/** Region API base, when the installation is not on the default one. */
+	readonly apiBaseUrl?: string
+	/** The Zerops INTEGRATION token `platform install` minted. Environment only. */
+	readonly accessToken: string
+	/** The `px_` key this installation's IAM was seeded with. Environment only. */
+	readonly provisioningKey: string
+	/** `--yes`: answer every confirmation yes. */
+	readonly unattended: boolean
+}
+
+const FLAGS = ['--repo', CHECKOUT_FLAG, '--tag', '--project-id', '--env', '--iam-host', '--console-host', '--operations-host'] as const
+
+const REPO_PATTERN = /^[^/\s]+\/[^/\s]+$/
+
+/**
+ * The installation's environment name, refused when it claims to be local.
+ *
+ * The same refusal the services enforce at boot: `local` is the value `localDevLogin`, the ephemeral
+ * signing key and the credential-less caller path are all gated on, and a deployed installation is
+ * never a loopback address.
+ */
+export const checkedEnvironmentName = (declared: string): string => {
+	const trimmed = declared.trim()
+	if (trimmed === '') {
+		throw new Error('an installation environment name is required — it is written to every service as ENVIRONMENT')
+	}
+	if (trimmed === LOCAL_ENVIRONMENT) {
+		throw new Error(
+			`\`${LOCAL_ENVIRONMENT}\` is refused: it is the name every development bypass is gated on, and a deployed `
+				+ 'installation is not a loopback address. Name it after the installation instead',
+		)
+	}
+	return trimmed
+}
+
+const assertKnownArguments = (argv: readonly string[]): void => {
+	for (const arg of argv) {
+		if (arg === UNATTENDED_FLAG || !arg.startsWith('-')) {
+			continue
+		}
+		const name = arg.split('=')[0] ?? arg
+		if (!FLAGS.some((flag) => flag === name) || !arg.includes('=')) {
+			throw new Error(
+				`unexpected argument ${describeArgument(arg)}. Credentials are read from the environment and have no flag; run `
+					+ '`fabrika platform init --provider=zerops --help` for the surface',
+			)
+		}
+	}
+}
+
+const readInstallation = (argv: readonly string[]): string => {
+	const positional = argv.filter((arg) => !arg.startsWith('-')).map((arg) => arg.trim())
+	if (positional.length > 1) {
+		throw new Error('unexpected second positional argument: name ONE installation')
+	}
+	const installation = positional[0]
+	if (installation === undefined || installation === '') {
+		throw new Error('Zerops installation init requires an installation name, for example `fabrika platform init --provider=zerops test`')
+	}
+	return installation
+}
+
+const readRepo = (argv: readonly string[], installation: string): string => {
+	const repo = readFlag(argv, '--repo')
+	if (repo === undefined) {
+		return defaultSidecarRepo(installation)
+	}
+	if (!REPO_PATTERN.test(repo)) {
+		throw new Error(`\`${repo}\` is not a <owner>/<name> repository`)
+	}
+	return repo
+}
+
+/** A credential, with the one message that says why there is no flag for it. */
+const credential = (env: CommandEnv, variable: string, what: string): string => {
+	const value = readEnv(env, variable)
+	if (value === undefined) {
+		throw new Error(`${variable} is required: ${what}. It has no flag — a credential on a command line lands in logs and shell history`)
+	}
+	return value
+}
+
+/** Parse the command's arguments and environment into the one input `runInit` takes. */
+export const parseInitArgs = (argv: readonly string[], env: CommandEnv, cwd: string = process.cwd()): InitInput => {
+	assertKnownArguments(argv)
+	const installation = readInstallation(argv)
+	const hosts = parsePlatformHosts({
+		iam: setting(argv, env, '--iam-host', 'FABRIKA_PLATFORM_IAM_HOST'),
+		control: setting(argv, env, '--console-host', 'FABRIKA_PLATFORM_CONSOLE_HOST'),
+		operations: setting(argv, env, '--operations-host', 'FABRIKA_PLATFORM_OPERATIONS_HOST'),
+	})
+	const apiBaseUrl = readEnv(env, 'FABRIKA_ZEROPS_API_URL')
+	return {
+		installation,
+		repo: readRepo(argv, installation),
+		checkoutDir: sidecarCheckoutDir(readFlag(argv, CHECKOUT_FLAG), defaultCheckoutName(installation), cwd),
+		fabrikaRef: assertPinnedTag(requiredSetting(setting(argv, env, '--tag', 'FABRIKA_PLATFORM_TAG'), '--tag', 'FABRIKA_PLATFORM_TAG')),
+		projectId: requiredSetting(setting(argv, env, '--project-id', 'FABRIKA_ZEROPS_PROJECT_ID'), '--project-id', 'FABRIKA_ZEROPS_PROJECT_ID'),
+		environmentName: checkedEnvironmentName(setting(argv, env, '--env', 'FABRIKA_PLATFORM_ENVIRONMENT') ?? installation),
+		accessToken: credential(
+			env,
+			'FABRIKA_ZEROPS_ACCESS_TOKEN',
+			"the Zerops INTEGRATION token `platform install` minted, read from the `control` service's environment",
+		),
+		provisioningKey: credential(env, 'FABRIKA_IAM_PROVISIONING_KEY', 'the px_ key `platform install` printed'),
+		unattended: argv.includes(UNATTENDED_FLAG),
+		...(hosts === undefined ? {} : { hosts }),
+		...(apiBaseUrl === undefined ? {} : { apiBaseUrl }),
+	}
+}

package/src/installation/init.ts

@@ -0,0 +1,394 @@
+// `fabrika platform init --provider=zerops <installation>` — maintain the operator's sidecar repository
+// for an installation that ALREADY EXISTS.
+//
+// ── What this does, and the one thing it does not ─────────────────────────────────────────────────
+//
+// It reads the installation's `control` and `proxy` configuration, creates
+// `<owner>/fabrika-zerops-<installation>`, pushes the pipeline that calls
+// `fabrika platform deploy --provider=zerops`, writes the GitHub Environment that pipeline reads, and
+// triggers it. It does NOT create the installation: `platform install` owns the first bring-up.
+//
+// ── It does the whole job, and confirms before every step that leaves this disk ───────────────────
+//
+// Reading the project, reading its services, creating or pushing the repository, writing the Environment,
+// and triggering the workflow each ask first. Full automation, never silent. Declining a write stops the outward steps and prints
+// what to run instead; `init` is idempotent, so the answer to a declined step is to run it again. Declining the read of
+// `control` and `proxy` only leaves the console and IAM origins out of what init prints.
+//
+// ── Credentials ───────────────────────────────────────────────────────────────────────────────────
+//
+// Two deployment credentials, and this command generates neither. Both already belong to the
+// installation. It writes nothing to Zerops. GitHub App setup belongs to the authenticated Control UI.
+
+import {
+	action as consoleAction,
+	configureEnvironment,
+	type Confirmations,
+	confirmations,
+	type EnvironmentConfig,
+	ghRepoExists,
+	info as consoleInfo,
+	ok as consoleOk,
+	scaffoldSidecarRepository,
+	shellWord,
+	type SidecarScaffoldInput,
+	type SidecarScaffoldResult,
+	step as consoleStep,
+	triggerPlatformWorkflow,
+	url,
+	warn as consoleWarn,
+} from '@fabrika/installation-init'
+import { createZeropsApi, type ZeropsApi, type ZeropsService } from '../index'
+import { PLATFORM_PROXY_MANIFEST_TEMPLATE } from './generated/platform-proxy-manifest'
+import { derivePlatformHosts, ZEROPS_SUBDOMAIN_VARIABLE } from './hosts'
+import type { InitInput } from './init-options'
+import type { InitLog } from './log'
+import { MACHINE_KEY_NEXT_STEP_TITLE, machineKeyNextStepLines } from './machine-key'
+import { materializeSidecarScaffold, readPinnedTag, SIDECAR_FILES } from './sidecar'
+
+/** Everything `runInit` does outside the operator's own disk. Every one of them is confirmed first. */
+export interface InitEffects {
+	/** Only decides how the scaffold confirmation is phrased; the scaffold itself re-reads it. */
+	repositoryExists(repo: string): Promise<boolean>
+	scaffold(input: SidecarScaffoldInput): Promise<SidecarScaffoldResult>
+	configureEnvironment(config: EnvironmentConfig): Promise<void>
+	triggerWorkflow(repo: string): Promise<void>
+	/** Read one Zerops project's name — the cheapest proof that the token and the project id agree. */
+	describeProject(input: { projectId: string; accessToken: string; apiBaseUrl?: string }): Promise<string>
+	inspectPlatform(input: InspectPlatformInput): Promise<PlatformInspection>
+}
+
+export interface InitCollaborators {
+	readonly log: InitLog
+	readonly prompts: Confirmations
+	readonly effects: InitEffects
+}
+
+/** Where this installation answers, as far as `init` needs to know it. */
+interface Placement {
+	readonly hosts?: { readonly iam: string; readonly control: string; readonly operations: string }
+}
+
+export interface InspectPlatformInput {
+	readonly projectId: string
+	readonly accessToken: string
+	readonly apiBaseUrl?: string
+}
+
+/** What `init` reads off the live installation to print origins it can verify. Values are never logged. */
+export interface PlatformInspection {
+	readonly controlEnv: ReadonlyMap<string, string>
+	readonly proxyEnv: ReadonlyMap<string, string>
+	readonly proxyPublished: boolean
+}
+
+const oneService = (services: readonly ZeropsService[], name: string): ZeropsService | undefined => {
+	const matches = services.filter((service) => service.name === name)
+	if (matches.length > 1) throw new Error(`Zerops project has ${matches.length} services named \`${name}\``)
+	return matches[0]
+}
+
+/** Read `control` and `proxy` without writing anything. */
+export const inspectPlatform = async (projectId: string, api: ZeropsApi, signal: AbortSignal): Promise<PlatformInspection> => {
+	const services = await api.listProjectServices({ projectId, signal })
+	const control = oneService(services, 'control')
+	if (control === undefined || control.id === '') throw new Error(`Zerops project ${projectId} has no \`control\` service`)
+	const proxy = oneService(services, 'proxy')
+	if (proxy === undefined || proxy.id === '') throw new Error(`Zerops project ${projectId} has no \`proxy\` service`)
+	const readEnv = async (serviceId: string): Promise<Map<string, string>> =>
+		new Map((await api.listServiceEnv({ serviceId, signal })).map((item) => [item.key, item.content]))
+	return {
+		controlEnv: await readEnv(control.id),
+		proxyEnv: await readEnv(proxy.id),
+		proxyPublished: proxy.subdomainAccess === true,
+	}
+}
+
+const strictHttpsOrigin = (hostValue: string): string | undefined => {
+	const host = hostValue.trim().toLowerCase()
+	const labels = host.split('.')
+	if (
+		host === '' || host.length > 253 || labels.some((label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))
+	) {
+		return undefined
+	}
+	try {
+		const parsed = new URL(`https://${host}`)
+		if (parsed.origin !== `https://${host}` || parsed.hostname !== host || parsed.port !== '' || parsed.username !== '' || parsed.password !== '') {
+			return undefined
+		}
+		return parsed.origin
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * IAM's PUBLIC origin as the installation itself records it, or nothing when init would have to guess.
+ *
+ * `platform install` writes it to `control` as `FABRIKA_IAM_ISSUER`, so this reads the live value
+ * rather than re-deriving one — and refuses it when the operator named a different IAM host, because
+ * a printed origin an operator then pastes into `FABRIKA_IAM_RPC_URL` must be the one that answers.
+ */
+export const platformIamOrigin = (placement: Placement, platform: PlatformInspection): string | undefined => {
+	const issuer = platform.controlEnv.get('FABRIKA_IAM_ISSUER')
+	if (issuer === undefined) return undefined
+	let hostname: string
+	try {
+		const parsed = new URL(issuer.trim())
+		if (parsed.protocol !== 'https:' || parsed.port !== '' || parsed.username !== '' || parsed.password !== '') return undefined
+		if (parsed.pathname !== '/' || parsed.search !== '' || parsed.hash !== '') return undefined
+		hostname = parsed.hostname
+	} catch {
+		return undefined
+	}
+	const origin = strictHttpsOrigin(hostname)
+	if (origin === undefined) return undefined
+	if (placement.hosts !== undefined && placement.hosts.iam.trim().toLowerCase() !== hostname) return undefined
+	return origin
+}
+
+/** Return a verified live console URL, or no URL when init would have to guess. */
+export const sourceConnectionSettingsUrl = (placement: Placement, platform: PlatformInspection): string | undefined => {
+	const liveHost = platform.controlEnv.get('FABRIKA_CONTROL_DOMAIN')
+	if (liveHost === undefined) return undefined
+	const origin = strictHttpsOrigin(liveHost)
+	if (origin === undefined) return undefined
+	const host = new URL(origin).hostname
+	if (placement.hosts !== undefined) {
+		if (placement.hosts.control.toLowerCase() !== host) return undefined
+		return `${origin}/settings/source`
+	}
+	if (!platform.proxyPublished) return undefined
+	const subdomains = platform.proxyEnv.get(ZEROPS_SUBDOMAIN_VARIABLE)
+	if (subdomains === undefined || subdomains.trim() === '') return undefined
+	try {
+		const listeners = PLATFORM_PROXY_MANIFEST_TEMPLATE.apps.map((app) => ({ service: app.service, port: app.port }))
+		if (derivePlatformHosts(subdomains, listeners).control.toLowerCase() !== host) return undefined
+		return `${origin}/settings/source`
+	} catch {
+		return undefined
+	}
+}
+
+/** The Environment the generated workflow reads. Secret VALUES appear here and nowhere else. */
+const environmentConfig = (installation: string, input: InitInput): EnvironmentConfig => ({
+	repo: input.repo,
+	environment: installation,
+	secrets: {
+		FABRIKA_ZEROPS_ACCESS_TOKEN: input.accessToken,
+		FABRIKA_IAM_PROVISIONING_KEY: input.provisioningKey,
+	},
+	vars: {
+		FABRIKA_ZEROPS_PROJECT_ID: input.projectId,
+		FABRIKA_PLATFORM_ENVIRONMENT: input.environmentName,
+		// Stated rather than defaulted, so the Environment describes the whole deploy.
+		FABRIKA_PLATFORM_SCHEME: 'https',
+		...(input.hosts === undefined ? {} : {
+			FABRIKA_PLATFORM_IAM_HOST: input.hosts.iam,
+			FABRIKA_PLATFORM_CONSOLE_HOST: input.hosts.control,
+			FABRIKA_PLATFORM_OPERATIONS_HOST: input.hosts.operations,
+		}),
+		...(input.apiBaseUrl === undefined ? {} : { FABRIKA_ZEROPS_API_URL: input.apiBaseUrl }),
+	},
+})
+
+/** The command that repeats this run, with every value but the two credentials, which stay in the environment. */
+const rerunCommand = (input: InitInput): string =>
+	[
+		'fabrika platform init --provider=zerops',
+		...[
+			input.installation,
+			`--repo=${input.repo}`,
+			`--checkout=${input.checkoutDir}`,
+			`--tag=${input.fabrikaRef}`,
+			`--project-id=${input.projectId}`,
+			`--env=${input.environmentName}`,
+			...(input.hosts === undefined
+				? []
+				: [`--iam-host=${input.hosts.iam}`, `--console-host=${input.hosts.control}`, `--operations-host=${input.hosts.operations}`]),
+		].map(shellWord),
+	].join(' ')
+
+/** Read the project back, so a wrong token or a mistyped id fails here rather than in someone's CI. */
+const verifyProject = async (input: InitInput, { log, prompts, effects }: InitCollaborators): Promise<void> => {
+	log.step('Check the token against the project')
+	if (!(await prompts.confirm(`Read Zerops project ${input.projectId} to check the access token and the id?`, true))) {
+		log.info('Skipped. A wrong token or project id will surface in the first pipeline run instead.')
+		return
+	}
+	// A caught error is never re-thrown as itself: it may quote a request URL or a platform payload, and
+	// this is the one step holding both credentials. A short sentence naming the two causes is enough.
+	const name = await effects.describeProject({
+		projectId: input.projectId,
+		accessToken: input.accessToken,
+		...(input.apiBaseUrl === undefined ? {} : { apiBaseUrl: input.apiBaseUrl }),
+	}).catch(() => {
+		throw new Error(
+			`Zerops project ${input.projectId} could not be read: the access token does not grant it, or the id is wrong. `
+				+ 'Nothing has been created — check both and run init again',
+		)
+	})
+	log.ok(`Zerops project ${name} (${input.projectId}) is readable with this token.`)
+}
+
+/**
+ * Read the live `control` and `proxy` configuration, so the origins init prints are ones the installation records.
+ *
+ * Declining is not fatal: init then prints no origin rather than one it would have to guess.
+ */
+const readPlatform = async (input: InitInput, { log, prompts, effects }: InitCollaborators): Promise<PlatformInspection | undefined> => {
+	log.step('Read the installation')
+	if (!(await prompts.confirm(`Read \`control\` and \`proxy\` in Zerops project ${input.projectId} for the console and IAM origins?`, true))) {
+		log.info('Skipped. No console or IAM origin will be printed.')
+		return undefined
+	}
+	return effects.inspectPlatform({
+		projectId: input.projectId,
+		accessToken: input.accessToken,
+		...(input.apiBaseUrl === undefined ? {} : { apiBaseUrl: input.apiBaseUrl }),
+	}).catch(() => {
+		throw new Error('the `control` and `proxy` services could not be read; no credential value is shown. Inspect them in Zerops, then run init again')
+	})
+}
+
+/**
+ * Create or refresh the sidecar repository — the first step that leaves this disk.
+ *
+ * Returns the local checkout, or `undefined` when the operator declined, which stops every later
+ * outward step: an Environment cannot be written to a repository that does not exist, and a workflow
+ * cannot be triggered without one.
+ */
+const scaffold = async (input: InitInput, { log, prompts, effects }: InitCollaborators): Promise<string | undefined> => {
+	log.step('Scaffold the sidecar repository')
+	const exists = await effects.repositoryExists(input.repo)
+	const question = exists
+		? `Refresh the pipeline on ${input.repo} and push?`
+		: `Create ${input.repo} (private) on GitHub and push the pipeline?`
+	if (!(await prompts.confirm(question, true))) {
+		log.action('OPERATOR ACTION — nothing was created; run init again when ready', [
+			rerunCommand(input),
+		])
+		return undefined
+	}
+	const result = await effects.scaffold({
+		repo: input.repo,
+		dir: input.checkoutDir,
+		files: [...SIDECAR_FILES],
+		materialize: (target) =>
+			materializeSidecarScaffold(target, {
+				installation: input.installation,
+				repo: input.repo,
+				fabrikaRef: input.fabrikaRef,
+			}),
+	})
+	const pinned = await readPinnedTag(result.dir)
+	log.ok(`${input.repo} ${result.created ? 'created' : 'refreshed'} — pinned fabrika tag ${pinned}`)
+	if (pinned !== input.fabrikaRef) {
+		log.warn(`the existing pin ${pinned} was kept; ${input.fabrikaRef} was not written, because fabrika.ref is operator-owned`)
+	}
+	return result.dir
+}
+
+/** Run the whole thing for `<installation>`. */
+export const runInit = async (input: InitInput, collaborators: InitCollaborators): Promise<void> => {
+	const { log, prompts, effects } = collaborators
+	log.info(`fabrika platform init — the ${input.installation} Zerops installation's sidecar repository`)
+	log.info('This UPDATES an installation that already exists. It does not create one.')
+
+	log.step('The installation this repository will deploy')
+	log.info(`repository ${input.repo}, pinned to ${input.fabrikaRef}; Zerops project ${input.projectId}, environment \`${input.environmentName}\``)
+	log.info(
+		input.hosts === undefined
+			? "hosts: derived from the proxy's Zerops subdomains"
+			: `hosts: iam ${input.hosts.iam}, console ${input.hosts.control}, operations ${input.hosts.operations}`,
+	)
+	await verifyProject(input, collaborators)
+	const platform = await readPlatform(input, collaborators)
+	const settingsUrl = platform === undefined ? undefined : sourceConnectionSettingsUrl(input, platform)
+	log.info('Public repositories deploy without a GitHub App. Connect private GitHub source in Control.')
+	log.action(
+		'OPERATOR ACTION — connect GitHub source in Control',
+		settingsUrl === undefined
+			? ['Deploy the platform, then open Settings → Source in the authenticated Control console. No unverified URL was guessed.']
+			: [url(settingsUrl)],
+	)
+
+	const dir = await scaffold(input, collaborators)
+	if (dir === undefined) {
+		return
+	}
+
+	log.step(`Configure the ${input.installation} GitHub Environment`)
+	const config = environmentConfig(input.installation, input)
+	log.info(`${Object.keys(config.secrets).length} secret(s) and ${Object.keys(config.vars).length} variable(s) on ${input.repo}.`)
+	if (!(await prompts.confirm(`Write them to the ${input.installation} Environment now (secret VALUES go to GitHub over \`gh\` stdin)?`, true))) {
+		log.action('OPERATOR ACTION — the pipeline cannot run until the Environment holds these', [
+			rerunCommand(input),
+		])
+		return
+	}
+	await effects.configureEnvironment(config)
+	log.ok(`Environment ${input.installation} written: ${Object.keys(config.secrets).join(', ')} and ${Object.keys(config.vars).join(', ')}.`)
+
+	log.step('Trigger the deploy')
+	log.info("The pipeline runs the whole ordered sequence in the operator's CI; this machine deploys nothing.")
+	if (!(await prompts.confirm(`Run the platform workflow on ${input.repo} now?`, true))) {
+		log.action('OPERATOR ACTION — run it when ready', [
+			`gh workflow run platform.yml --repo ${input.repo}`,
+			`or: ${url(`https://github.com/${input.repo}/actions`)} → platform → Run workflow`,
+		])
+	} else {
+		await effects.triggerWorkflow(input.repo)
+		log.ok('Platform workflow triggered.')
+		log.info(`Watch: ${url(`https://github.com/${input.repo}/actions`)}   (or: gh run watch --repo ${input.repo})`)
+	}
+
+	log.step('Done')
+	log.ok(`Sidecar repository: ${input.repo} (local checkout: ${dir})`)
+	log.info('Roll this installation forward by bumping fabrika.ref to a newer published tag and pushing.')
+	log.info("Who may administer the installation is IAM's to say: this repository holds no admission list to close later.")
+	// The origin comes off the live control service, never from what was typed here: an operator who
+	// pastes a guessed hostname into FABRIKA_IAM_RPC_URL gets "Unable to connect" and no explanation.
+	const iamOrigin = platform === undefined ? undefined : platformIamOrigin(input, platform)
+	log.action(
+		MACHINE_KEY_NEXT_STEP_TITLE,
+		machineKeyNextStepLines({ sidecarEnvironment: input.installation, ...(iamOrigin === undefined ? {} : { iamOrigin }) }),
+	)
+}
+
+/** The real collaborators: a TTY, `gh`, git, and one read of the Zerops API. */
+export const consoleInitCollaborators = (input: InitInput): InitCollaborators => ({
+	log: {
+		step: (title) => consoleStep(title),
+		info: (message) => consoleInfo(message),
+		warn: (message) => consoleWarn(message),
+		ok: (message) => consoleOk(message),
+		action: (title, lines) => consoleAction(title, [...lines]),
+	},
+	// First, before anything is contacted: a run nobody can confirm does not start.
+	prompts: confirmations(
+		input.unattended,
+		process.stdin,
+		(line) => consoleInfo(line),
+		'creates or pushes the sidecar repository, writes its GitHub Environment secrets and triggers the platform workflow',
+	),
+	effects: {
+		repositoryExists: (repo) => ghRepoExists(repo),
+		scaffold: (input) => scaffoldSidecarRepository(input),
+		configureEnvironment: (config) => configureEnvironment(config),
+		triggerWorkflow: (repo) => triggerPlatformWorkflow(repo),
+		describeProject: async ({ projectId, accessToken, apiBaseUrl }) => {
+			const api = createZeropsApi({ token: accessToken, ...(apiBaseUrl === undefined ? {} : { baseUrl: apiBaseUrl }) })
+			const project = await api.getProject({ projectId, signal: new AbortController().signal })
+			if (project.id === '') {
+				throw new Error(`Zerops project ${projectId} could not be read with this token`)
+			}
+			return project.name
+		},
+		inspectPlatform: async (input) => {
+			const api = createZeropsApi({ token: input.accessToken, ...(input.apiBaseUrl === undefined ? {} : { baseUrl: input.apiBaseUrl }) })
+			return inspectPlatform(input.projectId, api, new AbortController().signal)
+		},
+	},
+})

package/src/installation/install-collaborators.ts

@@ -0,0 +1,27 @@
+import type { Confirmations } from '@fabrika/installation-init'
+import type { SchemaReconciler } from '@fabrika/provider-contract'
+import type { Sleeper, ZeropsApi } from '../index'
+import type { PlatformSourcePreparer } from './installation-source'
+import type { InitLog } from './log'
+import type { PlatformUploadFetch } from './platform-upload'
+
+/** The one question this command asks. Injected so the flow can be exercised without a TTY. */
+export type InstallPrompts = Confirmations
+
+/** Everything `runInstall` reaches the outside world through. */
+export interface InstallCollaborators {
+	readonly prepareSource: PlatformSourcePreparer
+	readonly uploadFetch: PlatformUploadFetch
+	readonly api: ZeropsApi
+	readonly reconcileSchema: SchemaReconciler
+	readonly sleep: Sleeper
+	readonly log: InitLog
+	readonly prompts: InstallPrompts
+	readonly signal: AbortSignal
+}
+
+export const assertRunning = (signal: AbortSignal): void => {
+	if (signal.aborted) {
+		throw new Error('the Zerops platform install was cancelled')
+	}
+}