@fabrika/provider-zerops 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.3.1",
+	"version": "0.3.3",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -43,11 +43,11 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth": "^0.3.1",
-		"@fabrika/auth-core": "^0.3.1",
-		"@fabrika/installation-init": "^0.3.1",
-		"@fabrika/provider-contract": "^0.3.1",
-		"@fabrika/proxy-core": "^0.3.1",
+		"@fabrika/auth": "^0.3.3",
+		"@fabrika/auth-core": "^0.3.3",
+		"@fabrika/installation-init": "^0.3.3",
+		"@fabrika/provider-contract": "^0.3.3",
+		"@fabrika/proxy-core": "^0.3.3",
 		"yaml": "^2.9.1"
 	}
 }

package/src/cli-args.ts

@@ -1,3 +1,4 @@
+import { describeArgument } from '@fabrika/installation-init'
 export interface ZeropsCliArgs {
 	command: string | undefined
 	subcommand: string | undefined
@@ -71,7 +72,7 @@ export const parseZeropsCliArgs = (argv: readonly string[]): ZeropsCliArgs => {
 		} else if (subcommand === undefined && command === 'namespace') {
 			subcommand = arg
 		} else {
-			throw new Error(`Unexpected argument: ${arg}`)
+			throw new Error(`Unexpected argument: ${describeArgument(arg)}`)
 		}
 	}
 

package/src/descriptor.ts

@@ -128,8 +128,52 @@ export const selectZeropsDescriptorSetup = (parsed: ZeropsDescriptor, setup?: st
 	return selected
 }
 
+const inheritanceSchema = z.object({
+	zerops: z.array(z.intersection(
+		descriptorMappingSchema,
+		z.object({ setup: z.string(), extends: z.union([z.string(), z.array(z.string())]).optional() }),
+	)),
+})
+
+/**
+ * The setup entries a deploy of `selected` applies: the selected one and, transitively, every setup it
+ * `extends`. Only these reach the running service; the other setups in the file never do.
+ */
+export const appliedZeropsSetups = (parsed: ZeropsDescriptor, selected: string): JsonValue[] => {
+	const document = inheritanceSchema.safeParse(parsed.document)
+	if (!document.success) return invalid('requires extends to name setups')
+	const applied: JsonValue[] = []
+	const visit = (name: string): void => {
+		const entry = document.data.zerops.find((candidate) => candidate.setup === name)
+		if (entry === undefined) return invalid(`extends unknown setup \`${name}\``)
+		if (applied.includes(entry)) return
+		applied.push(entry)
+		for (const parent of typeof entry.extends === 'string' ? [entry.extends] : entry.extends ?? []) visit(parent)
+	}
+	visit(selected)
+	return applied
+}
+
+/**
+ * Refuse a selected setup that `extends` another without its own `run`: Zerops merges `extends` per
+ * whole section, and the deploy writes `FABRIKA_RELEASE` into `run`, which would replace the inherited one.
+ */
+export const assertOwnRunWhenExtending = (parsed: ZeropsDescriptor, selected: string): void => {
+	const [entry] = appliedZeropsSetups(parsed, selected)
+	if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return
+	if (entry['extends'] !== undefined && entry['run'] === undefined) {
+		invalid(`setup \`${selected}\` extends another setup, so it must declare its own run section — the deploy writes FABRIKA_RELEASE into it`)
+	}
+}
+
+/** The document Zerops executes: the selected setup and what it extends, which is exactly what the ownership check read. */
+export const executionZeropsDocument = (parsed: ZeropsDescriptor, selected: string): { readonly [key: string]: JsonValue } => ({
+	...parsed.document,
+	zerops: appliedZeropsSetups(parsed, 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 }
+	return { contents: renderYaml(executionZeropsDocument(parsed, selected)), setup: selected }
 }

package/src/installation/admin-options.ts

@@ -8,6 +8,7 @@
 // and prompts for nothing — and a missing required value is an error naming both the flag and the
 // variable that would supply it.
 
+import { describeArgument, readEnv, requiredSetting, setting } from '@fabrika/installation-init'
 import { parsePlatformHostname, parsePlatformScheme } from './placement-options'
 
 /** Every input `runPlatformAdmin` takes from the operator. */
@@ -36,35 +37,6 @@ const FLAGS = ['--email', '--iam-host', '--scheme'] as const
  */
 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) {
@@ -73,7 +45,7 @@ const assertKnownArguments = (argv: readonly string[]): void => {
 		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 `
+				`unexpected argument ${describeArgument(arg)}. Credentials are read from the environment and have no flag; run `
 					+ '`fabrika platform admin --provider=zerops --help` for the surface',
 			)
 		}
@@ -92,7 +64,7 @@ const readScheme = (argv: readonly string[], env: Record<string, string | undefi
  * 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')
+	const host = requiredSetting(setting(argv, env, '--iam-host', 'FABRIKA_PLATFORM_IAM_HOST'), '--iam-host', 'FABRIKA_PLATFORM_IAM_HOST')
 	return parsePlatformHostname(host)
 }
 
@@ -119,7 +91,7 @@ export const parsePlatformAdminArgs = (
 ): PlatformAdminInput => {
 	assertKnownArguments(argv)
 	return {
-		email: required(setting(argv, env, '--email', 'FABRIKA_PLATFORM_ADMIN_EMAIL'), '--email', 'FABRIKA_PLATFORM_ADMIN_EMAIL'),
+		email: requiredSetting(setting(argv, env, '--email', 'FABRIKA_PLATFORM_ADMIN_EMAIL'), '--email', 'FABRIKA_PLATFORM_ADMIN_EMAIL'),
 		iamHost: readIamHost(argv, env),
 		scheme: readScheme(argv, env),
 		provisioningKey: provisioningKey(env),

package/src/installation/deploy-options.ts

@@ -12,6 +12,7 @@
 // The command is unattended by construction: nothing here prompts, and a missing required value is an
 // error naming both the flag and the variable that would supply it.
 
+import { describeArgument, readEnv, requiredSetting, setting } from '@fabrika/installation-init'
 import { parsePlatformHosts, parsePlatformScheme } from './placement-options'
 import { readInstallationSourceDir } from './source-options'
 
@@ -52,35 +53,6 @@ const FLAGS = [
 	'--source-dir',
 ] 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 (arg === '--dry-run') {
@@ -89,7 +61,7 @@ const assertKnownArguments = (argv: readonly string[]): void => {
 		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 `
+				`unexpected argument ${describeArgument(arg)}. Credentials are read from the environment and have no flag; run `
 					+ '`fabrika platform deploy --provider=zerops --help` for the surface',
 			)
 		}
@@ -123,7 +95,7 @@ const readProject = (argv: readonly string[], env: Record<string, string | undef
 	if (name === undefined) {
 		throw new Error('--project-id=<id> or FABRIKA_ZEROPS_PROJECT_ID is required (or --project-name with --client-id)')
 	}
-	const clientId = required(setting(argv, env, '--client-id', 'FABRIKA_ZEROPS_CLIENT_ID'), '--client-id', 'FABRIKA_ZEROPS_CLIENT_ID')
+	const clientId = requiredSetting(setting(argv, env, '--client-id', 'FABRIKA_ZEROPS_CLIENT_ID'), '--client-id', 'FABRIKA_ZEROPS_CLIENT_ID')
 	return { kind: 'name', clientId, name }
 }
 
@@ -140,12 +112,12 @@ export const parsePlatformDeployArgs = (
 	return {
 		project: readProject(argv, env),
 		// A dry run reads, and reading still needs a token; it is the one credential it cannot do without.
-		accessToken: required(readEnv(env, 'FABRIKA_ZEROPS_ACCESS_TOKEN'), '(no flag)', 'FABRIKA_ZEROPS_ACCESS_TOKEN'),
-		environment: required(setting(argv, env, '--env', 'FABRIKA_PLATFORM_ENVIRONMENT'), '--env', 'FABRIKA_PLATFORM_ENVIRONMENT'),
+		accessToken: requiredSetting(readEnv(env, 'FABRIKA_ZEROPS_ACCESS_TOKEN'), '(no flag)', 'FABRIKA_ZEROPS_ACCESS_TOKEN'),
+		environment: requiredSetting(setting(argv, env, '--env', 'FABRIKA_PLATFORM_ENVIRONMENT'), '--env', 'FABRIKA_PLATFORM_ENVIRONMENT'),
 		// Not required for a dry run: it authenticates a write this mode never makes.
 		iamAdminKey: dryRun
 			? readEnv(env, 'FABRIKA_IAM_PROVISIONING_KEY') ?? ''
-			: required(readEnv(env, 'FABRIKA_IAM_PROVISIONING_KEY'), '(no flag)', 'FABRIKA_IAM_PROVISIONING_KEY'),
+			: requiredSetting(readEnv(env, 'FABRIKA_IAM_PROVISIONING_KEY'), '(no flag)', 'FABRIKA_IAM_PROVISIONING_KEY'),
 		scheme: readScheme(argv, env),
 		dryRun,
 		...(hosts === undefined ? {} : { hosts }),

package/src/installation/index.ts

@@ -1,5 +1,12 @@
 import { reconcileSchema } from '@fabrika/auth'
-import { info as consoleInfo, ok as consoleOk, step as consoleStep, warn as consoleWarn } from '@fabrika/installation-init'
+import {
+	describeArgument,
+	info as consoleInfo,
+	ok as consoleOk,
+	step as consoleStep,
+	UNATTENDED_FLAG,
+	warn as consoleWarn,
+} from '@fabrika/installation-init'
 import type { SchemaReconciler } from '@fabrika/provider-contract'
 import type { InstallationCli, InstallationCommand } from '@fabrika/provider-contract/installation'
 import { createZeropsApi, defaultSleep } from '../index'
@@ -7,9 +14,10 @@ import { consoleAdminCollaborators, runPlatformAdmin } from './admin'
 import { parsePlatformAdminArgs, REISSUE_FLAG } from './admin-options'
 import { deployPlatform, PLATFORM_CONCURRENT_DEPLOY, PLATFORM_DEPLOY_ORDER, PLATFORM_SEQUENTIAL_DEPLOY } from './deploy'
 import { parsePlatformDeployArgs } from './deploy-options'
-import { consoleInitCollaborators, parseInitArgs, runInit } from './init'
+import { consoleInitCollaborators, runInit } from './init'
+import { parseInitArgs } from './init-options'
 import { consoleInstallCollaborators, runInstall } from './install'
-import { parsePlatformInstallArgs, UNATTENDED_FLAG } from './install-options'
+import { parsePlatformInstallArgs } from './install-options'
 import { prepareInstallationSource } from './installation-source'
 import { consoleDeployLog } from './log'
 import { generatedArtifacts } from './topology/artifacts'
@@ -34,7 +42,7 @@ const USAGE = `Zerops installation
 
 Commands:
   fabrika platform install --provider=zerops [options]
-  fabrika platform init    --provider=zerops <installation> [--repo=<owner>/<name>]
+  fabrika platform init    --provider=zerops <installation> --tag=<tag> --project-id=<id> [options]
   fabrika platform plan    --provider=zerops
   fabrika platform deploy  --provider=zerops [options]
   fabrika platform admin   --provider=zerops --email=<address> --iam-host=<host> [--scheme=<http|https>] [${REISSUE_FLAG}]
@@ -109,11 +117,12 @@ Creates and maintains the operator's SIDECAR REPOSITORY: the GitHub pipeline tha
 credentials. ADR-0025 puts that pipeline in a repository the operator owns — fabrika ships the
 generator, never the pipeline, because one public repository cannot hold every account's credentials.
 
-Interactive and laptop-side. It does the whole job and CONFIRMS before every step that leaves the
-operator's disk: reading the project, reading its control and proxy services, creating or pushing the
-repository, writing the Environment, and triggering the run.
-Declining a write stops there and prints what to run instead; a re-run is safe. Declining the read of
-control and proxy only leaves the console and IAM origins out of what init prints.
+Laptop-side and prompt-free: every value comes from a flag or the environment, so a pipeline or an
+agent runs it end to end. It CONFIRMS before every step that leaves the operator's disk: reading the
+project, reading its control and proxy services, creating or pushing the repository, writing the
+Environment, and triggering the run. A stdin that is not a terminal is refused unless \`${UNATTENDED_FLAG}\` is given.
+Declining a write stops there and prints the command that repeats the run; a re-run is safe. Declining
+the read of control and proxy only leaves the console and IAM origins out of what init prints.
 
 Init writes nothing to Zerops. It reads control and proxy only to print the console and IAM origins
 the installation records, and prints none it cannot verify. Public repositories deploy without a
@@ -129,16 +138,30 @@ file afterwards.
   <installation>                    names this installation: the GitHub Environment, the default
                                     repository \`contember/fabrika-zerops-<installation>\`, and the
                                     local checkout directory
-  --repo=<owner>/<name>             a different sidecar repository
+
+Options (a flag beats the environment variable beside it):
+
+  --repo=<owner>/<name>                                             a different sidecar repository
+  --checkout=<dir>                                                  the sidecar's local checkout, default
+                                                                    ./fabrika-zerops-<installation>; refused
+                                                                    inside another git repository
+  --tag=<tag>                       FABRIKA_PLATFORM_TAG            required; the published fabrika tag to pin
+  --project-id=<id>                 FABRIKA_ZEROPS_PROJECT_ID       required; the project holding the platform
+  --env=<name>                      FABRIKA_PLATFORM_ENVIRONMENT    default <installation>
+  --iam-host=<host>                 FABRIKA_PLATFORM_IAM_HOST       custom domains: all three hosts or none;
+  --console-host=<host>             FABRIKA_PLATFORM_CONSOLE_HOST   none derives them from the proxy's Zerops
+  --operations-host=<host>          FABRIKA_PLATFORM_OPERATIONS_HOST subdomains
+  ${UNATTENDED_FLAG}                                                             answer every confirmation yes —
+                                                                    required when stdin is not a terminal
 
 It writes TWO secrets into that Environment and GENERATES NEITHER — both already belong to the
-installation, so a value invented here would not be one it accepts:
+installation, so a value invented here would not be one it accepts. Both are environment only:
 
-  FABRIKA_ZEROPS_ACCESS_TOKEN       a Zerops INTEGRATION token scoped to this installation's projects
-  FABRIKA_IAM_PROVISIONING_KEY      the px_ admin key this installation's IAM was seeded with
+	FABRIKA_ZEROPS_ACCESS_TOKEN       required   the INTEGRATION token install minted (the \`control\` service's env)
+	FABRIKA_IAM_PROVISIONING_KEY      required   the px_ key install printed
+	FABRIKA_ZEROPS_API_URL            optional   region API base, when not the default
 
-Each is read from a hidden prompt or from the environment variable of the same name, sent to GitHub
-over \`gh\` stdin, and never printed and never written to disk.
+Each is sent to GitHub over \`gh\` stdin, and never printed and never written to disk.
 
 The generated pipeline pins a published TAG of contember/fabrika-platform and refuses a branch, at
 init and again in the workflow. It uploads that checkout's exact committed archive to every installation service.
@@ -273,7 +296,7 @@ const neverAborted = (): AbortSignal => new AbortController().signal
 
 const runPlan = (argv: readonly string[]): void => {
 	if (argv.length > 0) {
-		throw new Error(`Unexpected Zerops plan arguments: ${argv.join(' ')}`)
+		throw new Error(`Unexpected Zerops plan arguments: ${argv.map(describeArgument).join(' ')}`)
 	}
 	const artifacts = generatedArtifacts()
 	for (const artifact of artifacts) {
@@ -342,7 +365,8 @@ export const installationCli: InstallationCli = {
 			return
 		}
 		if (command === 'init') {
-			await runInit(parseInitArgs(argv), consoleInitCollaborators())
+			const input = parseInitArgs(argv, process.env)
+			await runInit(input, consoleInitCollaborators(input))
 			return
 		}
 		if (command === 'plan') {

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 }),
+	}
+}