@fabrika/provider-zerops 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.3.1",
+	"version": "0.3.2",
 	"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.2",
+		"@fabrika/auth-core": "^0.3.2",
+		"@fabrika/installation-init": "^0.3.2",
+		"@fabrika/provider-contract": "^0.3.2",
+		"@fabrika/proxy-core": "^0.3.2",
 		"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 }),
+	}
+}

package/src/installation/init.ts

@@ -23,18 +23,17 @@
 import {
 	action as consoleAction,
 	configureEnvironment,
-	confirm as promptConfirm,
+	type Confirmations,
+	confirmations,
 	type EnvironmentConfig,
 	ghRepoExists,
 	info as consoleInfo,
 	ok as consoleOk,
 	scaffoldSidecarRepository,
-	secretOrEnv,
-	select as promptSelect,
+	shellWord,
 	type SidecarScaffoldInput,
 	type SidecarScaffoldResult,
 	step as consoleStep,
-	text as promptText,
 	triggerPlatformWorkflow,
 	url,
 	warn as consoleWarn,
@@ -42,21 +41,10 @@ import {
 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 { assertPinnedTag, defaultCheckoutDir, defaultSidecarRepo, materializeSidecarScaffold, readPinnedTag, SIDECAR_FILES } 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'
-
-/** Everything `runInit` asks the operator. Injected so the flow can be exercised without a TTY. */
-export interface InitPrompts {
-	text(question: string, fallback?: string): Promise<string>
-	confirm(question: string, defaultYes?: boolean): Promise<boolean>
-	select<T>(question: string, options: { label: string; value: T }[]): Promise<T>
-	/** A hidden prompt, or the named environment variable when it is already set. NEVER echoed. */
-	secret(variable: string, question: string): Promise<string>
-}
+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 {
@@ -72,80 +60,15 @@ export interface InitEffects {
 
 export interface InitCollaborators {
 	readonly log: InitLog
-	readonly prompts: InitPrompts
+	readonly prompts: Confirmations
 	readonly effects: InitEffects
 }
 
-/** `<installation>` plus the one optional flag, so the repository can be named without a prompt. */
-export interface InitArguments {
-	readonly installation: string
-	readonly repo?: string
-}
-
-export const parseInitArgs = (argv: readonly string[]): InitArguments => {
-	let installation: string | undefined
-	let repo: string | undefined
-	for (const arg of argv) {
-		if (arg.startsWith('--repo=')) {
-			repo = arg.slice('--repo='.length).trim()
-			continue
-		}
-		if (arg.startsWith('-')) {
-			throw new Error(`unexpected argument \`${arg}\`. Usage: fabrika platform init --provider=zerops <installation> [--repo=<owner>/<name>]`)
-		}
-		if (installation !== undefined) {
-			throw new Error(`unexpected argument \`${arg}\`: name ONE installation`)
-		}
-		installation = arg.trim()
-	}
-	if (installation === undefined || installation === '') {
-		throw new Error('Zerops installation init requires an installation name, for example `fabrika platform init --provider=zerops test`')
-	}
-	if (repo !== undefined && !/^[^/\s]+\/[^/\s]+$/.test(repo)) {
-		throw new Error(`\`${repo}\` is not a <owner>/<name> repository`)
-	}
-	return { installation, ...(repo === undefined || repo === '' ? {} : { repo }) }
-}
-
-/**
- * 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. Refusing it here means the operator finds out at the prompt rather than in
- * a failed readiness check.
- */
-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
-}
-
 /** 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 }
 }
 
-/** Everything collected before anything leaves this disk. */
-interface Collected {
-	readonly repo: string
-	readonly fabrikaRef: string
-	readonly projectId: string
-	readonly environmentName: string
-	readonly placement: Placement
-	readonly apiBaseUrl?: string
-	readonly accessToken: string
-	readonly provisioningKey: string
-}
-
 export interface InspectPlatformInput {
 	readonly projectId: string
 	readonly accessToken: string
@@ -159,75 +82,6 @@ export interface PlatformInspection {
 	readonly proxyPublished: boolean
 }
 
-const requiredAnswer = async (prompts: InitPrompts, question: string, fallback?: string): Promise<string> => {
-	const answer = (await prompts.text(question, fallback)).trim()
-	if (answer === '') {
-		throw new Error(`${question} is required`)
-	}
-	return answer
-}
-
-const bareHost = (value: string, label: string): string => {
-	const host = value.trim()
-	if (host === '' || host.includes('/') || host.includes(':')) {
-		throw new Error(`\`${value}\` is not a bare hostname — ${label} carries no scheme and no port`)
-	}
-	return host
-}
-
-const collect = async (args: InitArguments, { log, prompts }: InitCollaborators): Promise<Collected> => {
-	log.step('The installation this repository will deploy')
-	log.info('Nothing leaves this machine until every question below is answered.')
-	const repo = args.repo ?? await requiredAnswer(prompts, 'Sidecar repository (<owner>/<name>)', defaultSidecarRepo(args.installation))
-	// Refused HERE, before the credential prompts and long before anything is created: a branch pin is a
-	// question for the operator, not a failure in their CI.
-	const fabrikaRef = assertPinnedTag(await requiredAnswer(prompts, 'fabrika-platform tag to pin (a published tag, never a branch)'))
-	const projectId = await requiredAnswer(prompts, 'Zerops project id (the project holding iam, operations, proxy and control)')
-	const environmentName = checkedEnvironmentName(await requiredAnswer(prompts, 'Installation environment name', args.installation))
-
-	const custom = await prompts.select('Where does this installation answer?', [
-		{ label: 'Zerops subdomains — derived from the proxy, and the deploy publishes them', value: false },
-		{ label: 'Custom domains — bound to the project balancer out of band', value: true },
-	])
-	const placement: Placement = custom
-		? {
-			hosts: {
-				iam: bareHost(await requiredAnswer(prompts, 'IAM hostname'), 'a platform host'),
-				control: bareHost(await requiredAnswer(prompts, 'Console hostname'), 'a platform host'),
-				operations: bareHost(await requiredAnswer(prompts, 'Operations ingest hostname'), 'a platform host'),
-			},
-		}
-		: {}
-
-	const apiBaseUrl = (await prompts.text('Zerops region API base (blank = the default region)', '')).trim()
-
-	log.step('Credentials')
-	log.info('Both already belong to the installation. Neither is generated here, printed, or written to disk;')
-	log.info('each is sent to GitHub over `gh` stdin and reaches the deploy as an Environment secret.')
-	const accessToken = await prompts.secret(
-		'FABRIKA_ZEROPS_ACCESS_TOKEN',
-		"Zerops access token (an INTEGRATION token scoped to this installation's projects, never a personal one)",
-	)
-	const provisioningKey = await prompts.secret(
-		'FABRIKA_IAM_PROVISIONING_KEY',
-		"IAM provisioning key (the px_ admin key this installation's IAM already holds)",
-	)
-	if (accessToken.trim() === '' || provisioningKey.trim() === '') {
-		throw new Error('both credentials are required: the deploy authenticates to Zerops and to IAM with them')
-	}
-
-	return {
-		repo,
-		fabrikaRef,
-		projectId,
-		environmentName,
-		placement,
-		accessToken: accessToken.trim(),
-		provisioningKey: provisioningKey.trim(),
-		...(apiBaseUrl === '' ? {} : { apiBaseUrl }),
-	}
-}
-
 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}\``)
@@ -318,47 +172,64 @@ export const sourceConnectionSettingsUrl = (placement: Placement, platform: Plat
 }
 
 /** The Environment the generated workflow reads. Secret VALUES appear here and nowhere else. */
-const environmentConfig = (installation: string, collected: Collected): EnvironmentConfig => ({
-	repo: collected.repo,
+const environmentConfig = (installation: string, input: InitInput): EnvironmentConfig => ({
+	repo: input.repo,
 	environment: installation,
 	secrets: {
-		FABRIKA_ZEROPS_ACCESS_TOKEN: collected.accessToken,
-		FABRIKA_IAM_PROVISIONING_KEY: collected.provisioningKey,
+		FABRIKA_ZEROPS_ACCESS_TOKEN: input.accessToken,
+		FABRIKA_IAM_PROVISIONING_KEY: input.provisioningKey,
 	},
 	vars: {
-		FABRIKA_ZEROPS_PROJECT_ID: collected.projectId,
-		FABRIKA_PLATFORM_ENVIRONMENT: collected.environmentName,
+		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',
-		...(collected.placement.hosts === undefined ? {} : {
-			FABRIKA_PLATFORM_IAM_HOST: collected.placement.hosts.iam,
-			FABRIKA_PLATFORM_CONSOLE_HOST: collected.placement.hosts.control,
-			FABRIKA_PLATFORM_OPERATIONS_HOST: collected.placement.hosts.operations,
+		...(input.hosts === undefined ? {} : {
+			FABRIKA_PLATFORM_IAM_HOST: input.hosts.iam,
+			FABRIKA_PLATFORM_CONSOLE_HOST: input.hosts.control,
+			FABRIKA_PLATFORM_OPERATIONS_HOST: input.hosts.operations,
 		}),
-		...(collected.apiBaseUrl === undefined ? {} : { FABRIKA_ZEROPS_API_URL: collected.apiBaseUrl }),
+		...(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 (collected: Collected, { log, prompts, effects }: InitCollaborators): Promise<void> => {
+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 ${collected.projectId} to check the access token and the id?`, true))) {
+	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: collected.projectId,
-		accessToken: collected.accessToken,
-		...(collected.apiBaseUrl === undefined ? {} : { apiBaseUrl: collected.apiBaseUrl }),
+		projectId: input.projectId,
+		accessToken: input.accessToken,
+		...(input.apiBaseUrl === undefined ? {} : { apiBaseUrl: input.apiBaseUrl }),
 	}).catch(() => {
 		throw new Error(
-			`Zerops project ${collected.projectId} could not be read: the access token does not grant it, or the id is wrong. `
+			`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} (${collected.projectId}) is readable with this token.`)
+	log.ok(`Zerops project ${name} (${input.projectId}) is readable with this token.`)
 }
 
 /**
@@ -366,16 +237,16 @@ const verifyProject = async (collected: Collected, { log, prompts, effects }: In
  *
  * Declining is not fatal: init then prints no origin rather than one it would have to guess.
  */
-const readPlatform = async (collected: Collected, { log, prompts, effects }: InitCollaborators): Promise<PlatformInspection | undefined> => {
+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 ${collected.projectId} for the console and IAM origins?`, true))) {
+	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: collected.projectId,
-		accessToken: collected.accessToken,
-		...(collected.apiBaseUrl === undefined ? {} : { apiBaseUrl: collected.apiBaseUrl }),
+		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')
 	})
@@ -388,52 +259,53 @@ const readPlatform = async (collected: Collected, { log, prompts, effects }: Ini
  * 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 (
-	installation: string,
-	collected: Collected,
-	{ log, prompts, effects }: InitCollaborators,
-): Promise<string | undefined> => {
+const scaffold = async (input: InitInput, { log, prompts, effects }: InitCollaborators): Promise<string | undefined> => {
 	log.step('Scaffold the sidecar repository')
-	const exists = await effects.repositoryExists(collected.repo)
+	const exists = await effects.repositoryExists(input.repo)
 	const question = exists
-		? `Refresh the pipeline on ${collected.repo} and push?`
-		: `Create ${collected.repo} (private) on GitHub and push the pipeline?`
+		? `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', [
-			`fabrika platform init --provider=zerops ${installation} --repo=${collected.repo}`,
+			rerunCommand(input),
 		])
 		return undefined
 	}
-	const dir = defaultCheckoutDir(installation)
 	const result = await effects.scaffold({
-		repo: collected.repo,
-		dir,
+		repo: input.repo,
+		dir: input.checkoutDir,
 		files: [...SIDECAR_FILES],
 		materialize: (target) =>
 			materializeSidecarScaffold(target, {
-				installation,
-				repo: collected.repo,
-				fabrikaRef: collected.fabrikaRef,
+				installation: input.installation,
+				repo: input.repo,
+				fabrikaRef: input.fabrikaRef,
 			}),
 	})
 	const pinned = await readPinnedTag(result.dir)
-	log.ok(`${collected.repo} ${result.created ? 'created' : 'refreshed'} — pinned fabrika tag ${pinned}`)
-	if (pinned !== collected.fabrikaRef) {
-		log.warn(`the existing pin ${pinned} was kept; ${collected.fabrikaRef} was not written, because fabrika.ref is operator-owned`)
+	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 (args: InitArguments, collaborators: InitCollaborators): Promise<void> => {
+export const runInit = async (input: InitInput, collaborators: InitCollaborators): Promise<void> => {
 	const { log, prompts, effects } = collaborators
-	log.info(`fabrika platform init — the ${args.installation} Zerops installation's sidecar repository`)
+	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.')
 
-	const collected = await collect(args, collaborators)
-	await verifyProject(collected, collaborators)
-	const platform = await readPlatform(collected, collaborators)
-	const settingsUrl = platform === undefined ? undefined : sourceConnectionSettingsUrl(collected.placement, platform)
+	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',
@@ -442,51 +314,51 @@ export const runInit = async (args: InitArguments, collaborators: InitCollaborat
 			: [url(settingsUrl)],
 	)
 
-	const dir = await scaffold(args.installation, collected, collaborators)
+	const dir = await scaffold(input, collaborators)
 	if (dir === undefined) {
 		return
 	}
 
-	log.step(`Configure the ${args.installation} GitHub Environment`)
-	const config = environmentConfig(args.installation, collected)
-	log.info(`${Object.keys(config.secrets).length} secret(s) and ${Object.keys(config.vars).length} variable(s) on ${collected.repo}.`)
-	if (!(await prompts.confirm(`Write them to the ${args.installation} Environment now (secret VALUES go to GitHub over \`gh\` stdin)?`, true))) {
+	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', [
-			`fabrika platform init --provider=zerops ${args.installation} --repo=${collected.repo}`,
+			rerunCommand(input),
 		])
 		return
 	}
 	await effects.configureEnvironment(config)
-	log.ok(`Environment ${args.installation} written: ${Object.keys(config.secrets).join(', ')} and ${Object.keys(config.vars).join(', ')}.`)
+	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 ${collected.repo} now?`, true))) {
+	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 ${collected.repo}`,
-			`or: ${url(`https://github.com/${collected.repo}/actions`)} → platform → Run workflow`,
+			`gh workflow run platform.yml --repo ${input.repo}`,
+			`or: ${url(`https://github.com/${input.repo}/actions`)} → platform → Run workflow`,
 		])
 	} else {
-		await effects.triggerWorkflow(collected.repo)
+		await effects.triggerWorkflow(input.repo)
 		log.ok('Platform workflow triggered.')
-		log.info(`Watch: ${url(`https://github.com/${collected.repo}/actions`)}   (or: gh run watch --repo ${collected.repo})`)
+		log.info(`Watch: ${url(`https://github.com/${input.repo}/actions`)}   (or: gh run watch --repo ${input.repo})`)
 	}
 
 	log.step('Done')
-	log.ok(`Sidecar repository: ${collected.repo} (local checkout: ${dir})`)
+	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(collected.placement, platform)
+	const iamOrigin = platform === undefined ? undefined : platformIamOrigin(input, platform)
 	log.action(
 		MACHINE_KEY_NEXT_STEP_TITLE,
-		machineKeyNextStepLines({ sidecarEnvironment: args.installation, ...(iamOrigin === undefined ? {} : { iamOrigin }) }),
+		machineKeyNextStepLines({ sidecarEnvironment: input.installation, ...(iamOrigin === undefined ? {} : { iamOrigin }) }),
 	)
 }
 
 /** The real collaborators: a TTY, `gh`, git, and one read of the Zerops API. */
-export const consoleInitCollaborators = (): InitCollaborators => ({
+export const consoleInitCollaborators = (input: InitInput): InitCollaborators => ({
 	log: {
 		step: (title) => consoleStep(title),
 		info: (message) => consoleInfo(message),
@@ -494,12 +366,13 @@ export const consoleInitCollaborators = (): InitCollaborators => ({
 		ok: (message) => consoleOk(message),
 		action: (title, lines) => consoleAction(title, [...lines]),
 	},
-	prompts: {
-		text: (question, fallback) => promptText(question, fallback),
-		confirm: (question, defaultYes) => promptConfirm(question, defaultYes),
-		select: (question, options) => promptSelect(question, options),
-		secret: (variable, question) => secretOrEnv(variable, question),
-	},
+	// 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),

package/src/installation/install-collaborators.ts

@@ -1,3 +1,4 @@
+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'
@@ -5,9 +6,7 @@ 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 interface InstallPrompts {
-	confirm(question: string, defaultYes?: boolean): Promise<boolean>
-}
+export type InstallPrompts = Confirmations
 
 /** Everything `runInstall` reaches the outside world through. */
 export interface InstallCollaborators {

package/src/installation/install-options.ts

@@ -8,6 +8,7 @@
 // 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 { describeArgument, readEnv, readFlag, requiredSetting, setting, UNATTENDED_FLAG } from '@fabrika/installation-init'
 import { parsePlatformScheme } from './placement-options'
 import { readInstallationSourceDir } from './source-options'
 
@@ -52,50 +53,12 @@ export const FABRIKA_REPOSITORY_URL = 'https://github.com/contember/fabrika-plat
 
 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)) {
@@ -104,7 +67,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 install --provider=zerops --help` for the surface',
 			)
 		}
@@ -135,7 +98,7 @@ const readScheme = (argv: readonly string[], env: Record<string, string | undefi
 }
 
 const readEnvironment = (argv: readonly string[], env: Record<string, string | undefined>): string =>
-	required(setting(argv, env, '--env', 'FABRIKA_PLATFORM_ENVIRONMENT'), '--env', 'FABRIKA_PLATFORM_ENVIRONMENT')
+	requiredSetting(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}`
@@ -158,7 +121,7 @@ const readProjectSource = (argv: readonly string[], env: Record<string, string |
 					+ 'exists takes --project-id=<id>, which names it by id',
 			)
 		}
-		return { kind: 'existing', projectId: required(projectId, '--project-id', 'FABRIKA_ZEROPS_PROJECT_ID') }
+		return { kind: 'existing', projectId: requiredSetting(projectId, '--project-id', 'FABRIKA_ZEROPS_PROJECT_ID') }
 	}
 	if (projectId !== undefined) {
 		const source = readFlag(argv, '--project-id') === undefined ? 'FABRIKA_ZEROPS_PROJECT_ID' : '--project-id'
@@ -181,8 +144,8 @@ export const parsePlatformInstallArgs = (
 		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'),
+		clientId: requiredSetting(setting(argv, env, '--client-id', 'FABRIKA_ZEROPS_CLIENT_ID'), '--client-id', 'FABRIKA_ZEROPS_CLIENT_ID'),
+		accessToken: requiredSetting(readEnv(env, 'FABRIKA_ZEROPS_ACCESS_TOKEN'), '(no flag)', 'FABRIKA_ZEROPS_ACCESS_TOKEN'),
 		environment: readEnvironment(argv, env),
 		scheme: readScheme(argv, env),
 		sourceDir,

package/src/installation/install.ts

@@ -4,7 +4,7 @@
 
 import {
 	action as consoleAction,
-	confirm as promptConfirm,
+	confirmations,
 	info as consoleInfo,
 	ok as consoleOk,
 	step as consoleStep,
@@ -24,10 +24,10 @@ import {
 } from './deploy'
 import { PLATFORM_PROXY_MANIFEST_TEMPLATE } from './generated/platform-proxy-manifest'
 import { derivePlatformHosts, type PlatformHosts, platformOrigin, ZEROPS_SUBDOMAIN_VARIABLE } from './hosts'
-import { checkedEnvironmentName } from './init'
+import { checkedEnvironmentName } from './init-options'
 import { assertRunning, type InstallCollaborators, type InstallPrompts } from './install-collaborators'
 import { installationServiceEnv, passOneProxyEnv, writeServiceEnv } from './install-environment'
-import { type PlatformInstallInput, UNATTENDED_FLAG } from './install-options'
+import type { PlatformInstallInput } from './install-options'
 import { resolveInstallationProject } from './install-project'
 import {
 	assertNoServiceIsBeingCreated,
@@ -226,39 +226,15 @@ const installPreparedPlatform = async (
 }
 
 /**
- * How this command's confirmations are answered — and the refusal when nothing can answer them.
- *
- * The confirmations are the only thing standing between a stray invocation and an installation: this
- * command generates six credentials, mints a Zerops token on the account and deploys. Every one of
- * them defaults to yes, so a pipe carrying blank lines answers all six of them with nobody reading
- * what they agree to. So a run with no terminal is refused unless the operator asked for it by name.
+ * The confirmations stand between a stray invocation and an installation: this command generates six
+ * credentials, mints a Zerops token on the account and deploys.
  */
 export const installPrompts = (
 	input: PlatformInstallInput,
 	stdin: { readonly isTTY?: boolean },
 	announce: (line: string) => void,
-): InstallPrompts => {
-	if (input.unattended) {
-		// The flag IS the yes, given once for the whole sequence; nothing reads stdin after it. Each
-		// question is still printed with the answer it was given, so an unattended run leaves the same
-		// record of what was agreed to that an interactive one does.
-		return {
-			confirm: (question) => {
-				announce(`${question} yes (${UNATTENDED_FLAG})`)
-				return Promise.resolve(true)
-			},
-		}
-	}
-	if (stdin.isTTY !== true) {
-		throw new Error(
-			"stdin is not a terminal, so nobody is here to confirm what this command does — it generates this installation's "
-				+ 'credentials, mints a Zerops integration token and deploys. Run it from a terminal, or pass `'
-				+ UNATTENDED_FLAG
-				+ '` to answer every confirmation yes unattended',
-		)
-	}
-	return { confirm: (question, defaultYes) => promptConfirm(question, defaultYes) }
-}
+): InstallPrompts =>
+	confirmations(input.unattended, stdin, announce, "generates this installation's credentials, mints a Zerops integration token and deploys")
 
 /** The real collaborators: a TTY for the confirmations, the Zerops API, and IAM's own schema reconciler. */
 export const consoleInstallCollaborators = (input: PlatformInstallInput, reconcileSchema: SchemaReconciler): InstallCollaborators => {

package/src/installation/sidecar.ts

@@ -119,4 +119,7 @@ export const readPinnedTag = async (dir: string): Promise<string> => {
 export const defaultSidecarRepo = (installation: string): string => `contember/fabrika-zerops-${installation}`
 
 /** Where the sidecar is checked out locally: `./fabrika-zerops-<installation>` under the cwd. */
-export const defaultCheckoutDir = (installation: string): string => resolve(process.cwd(), `fabrika-zerops-${installation}`)
+/** The sidecar checkout's directory name when `--checkout` is not given; `init` creates it and `upgrade` reads it. */
+export const defaultCheckoutName = (installation: string): string => `fabrika-zerops-${installation}`
+
+export const defaultCheckoutDir = (installation: string): string => resolve(process.cwd(), defaultCheckoutName(installation))

package/src/installation/upgrade-options.ts

@@ -8,6 +8,7 @@
 // The pin is checked BEFORE anything leaves this machine: `assertPinnedTag` refuses a branch or a SHA
 // (ADR-0025) without a network call, so `--to=main` fails on the spot rather than after a clone.
 
+import { describeArgument, readFlag } from '@fabrika/installation-init'
 import { assertPinnedTag, defaultCheckoutDir } from './sidecar'
 
 /** Where the sidecar repository this command edits is found. */
@@ -43,16 +44,6 @@ export const UPGRADE_DRY_RUN_FLAG = '--dry-run'
  */
 const REPO_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/
 
-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 assertKnownArguments = (argv: readonly string[]): void => {
 	for (const arg of argv) {
 		if (arg === UPGRADE_DRY_RUN_FLAG || !arg.startsWith('-')) {
@@ -61,7 +52,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}\`. Run \`fabrika platform upgrade --provider=zerops --help\` for the surface`,
+				`unexpected argument ${describeArgument(arg)}. Run \`fabrika platform upgrade --provider=zerops --help\` for the surface`,
 			)
 		}
 	}
@@ -71,7 +62,7 @@ const assertKnownArguments = (argv: readonly string[]): void => {
 const readInstallation = (argv: readonly string[]): string | undefined => {
 	const positional = argv.filter((arg) => !arg.startsWith('-'))
 	if (positional.length > 1) {
-		throw new Error(`unexpected argument \`${positional[1]}\`: name ONE installation`)
+		throw new Error('unexpected second positional argument: name ONE installation')
 	}
 	const installation = positional[0]?.trim()
 	return installation === undefined || installation === '' ? undefined : installation

package/src/managed-env.ts

@@ -1,7 +1,13 @@
 import type { JsonValue } from '@fabrika/provider-contract'
 import { z } from 'zod'
 import { renderYaml } from './compile'
-import { parseZeropsDescriptor, type PreparedZeropsDescriptor, selectZeropsDescriptorSetup } from './descriptor'
+import {
+	assertOwnRunWhenExtending,
+	executionZeropsDocument,
+	parseZeropsDescriptor,
+	type PreparedZeropsDescriptor,
+	selectZeropsDescriptorSetup,
+} from './descriptor'
 
 export type ManagedKey =
 	| 'FABRIKA_RELEASE'
@@ -93,7 +99,9 @@ export function overlayRelease(contents: string, setup: string | undefined, rele
 	const parsed = parseZeropsDescriptor(contents)
 	assertAuthoredManagedDocument(parsed.document)
 	const selected = selectZeropsDescriptorSetup(parsed, setup)
-	const entries = parsed.document['zerops']
+	assertOwnRunWhenExtending(parsed, selected)
+	const execution = executionZeropsDocument(parsed, selected)
+	const entries = execution['zerops']
 	if (!Array.isArray(entries)) throw new Error('zerops: descriptor requires setup entries')
 	const overlaid = release === null ? entries : entries.map((entry) => {
 		if (!isMapping(entry) || entry['setup'] !== selected) return entry
@@ -101,5 +109,5 @@ export function overlayRelease(contents: string, setup: string | undefined, rele
 		const env = isMapping(run['envVariables']) ? run['envVariables'] : {}
 		return { ...entry, run: { ...run, envVariables: { ...env, FABRIKA_RELEASE: release } } }
 	})
-	return { contents: renderYaml({ ...parsed.document, zerops: overlaid }), setup: selected }
+	return { contents: renderYaml({ ...execution, zerops: overlaid }), setup: selected }
 }

package/src/manifest.ts

@@ -4,7 +4,7 @@ import type { JsonValue, ProviderCodec } from '@fabrika/provider-contract'
 import { normalizeGateRule, proxyGateRuleFieldsSchema } from '@fabrika/proxy-core/manifest'
 import { z } from 'zod'
 import { compileImport, ENV_ISOLATION, OVERRIDE, renderYaml } from './compile'
-import { parseZeropsDescriptor, selectZeropsDescriptorSetup } from './descriptor'
+import { assertOwnRunWhenExtending, executionZeropsDocument, parseZeropsDescriptor, selectZeropsDescriptorSetup } from './descriptor'
 import { assertAuthoredManagedDocument, assertAuthoredManagedInputs } from './managed-env'
 import { allowedReferenceHosts, foreignReferenceHost } from './service-references'
 import type { ZeropsAppConfig, ZeropsNamespaceResourceRequirement, ZeropsProxySpec, ZeropsSharedPostgresBinding } from './types'
@@ -288,14 +288,17 @@ export function parseFabrikaManifest(value: unknown, expected: ManifestExpectati
 	if (!serviceHostnames.includes(deployService)) {
 		throw new Error('invalid fabrika manifest Zerops deploy service')
 	}
+	// Only the selected setup and what it extends reach this app's service, so a sibling setup for another
+	// placement may reference services this app does not own.
+	const selectedSetup = selectZeropsDescriptorSetup(parsedDescriptor, zeropsSetup)
+	assertOwnRunWhenExtending(parsedDescriptor, selectedSetup)
 	const foreignInDescriptor = foreignReferenceInValue(
-		parsedDescriptor.document,
+		executionZeropsDocument(parsedDescriptor, selectedSetup),
 		allowedReferenceHosts(serviceHostnames),
 	)
 	if (foreignInDescriptor !== null) {
 		throw new Error(`invalid fabrika manifest: zerops.yaml references service \`${foreignInDescriptor}\`, which this app does not own`)
 	}
-	selectZeropsDescriptorSetup(parsedDescriptor, zeropsSetup)
 	if (proxy !== undefined) {
 		const separator = proxy.upstream.indexOf(':')
 		const upstreamHostname = separator === -1 ? proxy.upstream : proxy.upstream.slice(0, separator)