@fabrika/provider-zerops 0.0.1

package/src/manifest.ts

@@ -0,0 +1,442 @@
+import type { AppActionDef, AppGates, AppSchema, AppScopeDef, GateRule, RoleDef } from '@fabrika/auth-core'
+import type { JsonValue, ProviderCodec } from '@fabrika/provider-contract'
+import { compileImport, ENV_ISOLATION, OVERRIDE, renderYaml } from './compile'
+import type { ZeropsAppConfig, ZeropsNamespaceResourceRequirement, ZeropsProxySpec, ZeropsSharedPostgresBinding } from './types'
+
+export const FABRIKA_MANIFEST_VERSION = 2
+export const ZEROPS_SERVICE_HOSTNAME_PATTERN = /^[a-z0-9]{1,25}$/
+
+/**
+ * The one reference an app may declare for the namespace-owned PostgreSQL service.
+ *
+ * Restated here rather than imported from `./namespace` — that module imports THIS one, and the
+ * literal is part of the manifest's parse contract, so it belongs on the parsing side. The reasoning
+ * for the database path and the TLS mode lives with `ZEROPS_SHARED_POSTGRES_CONNECTION_STRING`; a test
+ * asserts the two never diverge.
+ */
+const SHARED_POSTGRES_CONNECTION_STRING: ZeropsSharedPostgresBinding['connectionString'] =
+	'${postgres_connectionString}/${postgres_dbName}?sslmode=require'
+
+export interface FabrikaImportDocument {
+	readonly project?: { readonly [key: string]: JsonValue }
+	readonly services: ReadonlyArray<{ readonly [key: string]: JsonValue }>
+}
+
+export interface FabrikaManifest {
+	manifestVersion: typeof FABRIKA_MANIFEST_VERSION
+	app: {
+		id: string
+		env: string
+		schema?: AppSchema
+		pipeline: {
+			secrets: string[]
+			vars: string[]
+		}
+	}
+	target: {
+		platform: 'zerops'
+		/** The canonical document used both for resource claims and the Zerops API payload. */
+		importDocument: FabrikaImportDocument
+		deployService: string
+		zeropsSetup?: string
+		proxy?: ZeropsProxySpec
+		namespaceResources?: ZeropsNamespaceResourceRequirement[]
+	}
+}
+
+export interface ManifestExpectation {
+	appId?: string
+	env?: string
+}
+
+const prop = (value: unknown, key: string): unknown => typeof value === 'object' && value !== null ? Reflect.get(value, key) : undefined
+
+const jsonValue = (value: unknown): JsonValue => {
+	if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+		return value
+	}
+	if (Array.isArray(value)) {
+		return value.map(jsonValue)
+	}
+	if (typeof value === 'object') {
+		const result: { [key: string]: JsonValue } = {}
+		for (const [key, entry] of Object.entries(value)) {
+			if (entry !== undefined) {
+				result[key] = jsonValue(entry)
+			}
+		}
+		return result
+	}
+	throw new Error(`Fabrika manifest contains a non-JSON ${typeof value} value`)
+}
+
+const jsonObject = (value: unknown, label: string): { [key: string]: JsonValue } => {
+	const parsed = jsonValue(value)
+	if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+		throw new Error(`invalid fabrika manifest ${label}`)
+	}
+	return parsed
+}
+
+const string = (value: unknown, key: string): string | undefined => {
+	const candidate = prop(value, key)
+	return typeof candidate === 'string' ? candidate : undefined
+}
+
+const nonEmptyString = (value: unknown, key: string): string | undefined => {
+	const candidate = string(value, key)
+	return candidate !== undefined && candidate !== '' ? candidate : undefined
+}
+
+const stringArray = (value: unknown, key: string): string[] | undefined => {
+	const candidate = prop(value, key)
+	if (!Array.isArray(candidate) || candidate.some((item) => typeof item !== 'string' || item === '')) {
+		return undefined
+	}
+	return candidate
+}
+
+const optionalString = (value: unknown, key: string): string | null => {
+	const candidate = prop(value, key)
+	if (candidate === undefined) {
+		return null
+	}
+	return typeof candidate === 'string' && candidate !== '' ? candidate : null
+}
+
+function parseScope(value: unknown): AppScopeDef | null {
+	const type = nonEmptyString(value, 'type')
+	const label = optionalString(value, 'label')
+	if (type === undefined || (prop(value, 'label') !== undefined && label === null)) {
+		return null
+	}
+	return label === null ? { type } : { type, label }
+}
+
+function parseAction(value: unknown): AppActionDef | null {
+	const action = nonEmptyString(value, 'action')
+	const description = optionalString(value, 'description')
+	if (action === undefined || (prop(value, 'description') !== undefined && description === null)) {
+		return null
+	}
+	return description === null ? { action } : { action, description }
+}
+
+function parseRole(value: unknown): RoleDef | null {
+	const name = nonEmptyString(value, 'name')
+	const description = optionalString(value, 'description')
+	const permissions = stringArray(value, 'permissions')
+	if (name === undefined || permissions === undefined || (prop(value, 'description') !== undefined && description === null)) {
+		return null
+	}
+	return description === null ? { name, permissions } : { name, description, permissions }
+}
+
+function parseSchema(value: unknown): AppSchema | null {
+	const rawScopes = prop(value, 'scopes')
+	const rawActions = prop(value, 'actions')
+	const rawRoles = prop(value, 'roles')
+	if (!Array.isArray(rawScopes) || !Array.isArray(rawActions) || typeof rawRoles !== 'object' || rawRoles === null || Array.isArray(rawRoles)) {
+		return null
+	}
+	const scopes: AppScopeDef[] = []
+	for (const raw of rawScopes) {
+		const scope = parseScope(raw)
+		if (scope === null) return null
+		scopes.push(scope)
+	}
+	const actions: AppActionDef[] = []
+	for (const raw of rawActions) {
+		const action = parseAction(raw)
+		if (action === null) return null
+		actions.push(action)
+	}
+	const roles: Record<string, RoleDef> = {}
+	for (const [key, raw] of Object.entries(rawRoles)) {
+		const role = parseRole(raw)
+		if (key === '' || role === null) return null
+		roles[key] = role
+	}
+	return { scopes, actions, roles }
+}
+
+function parseGate(value: unknown): GateRule | null {
+	const path = nonEmptyString(value, 'path')
+	const kind = string(value, 'kind')
+	if (path === undefined || !path.startsWith('/')) return null
+	if (kind === 'public' || kind === 'human') return { path, kind }
+	if (kind !== 'service') return null
+	const rawCredential = prop(value, 'credential')
+	if (rawCredential === undefined) return { path, kind }
+	const location = string(rawCredential, 'in')
+	const name = nonEmptyString(rawCredential, 'name')
+	if ((location !== 'header' && location !== 'query' && location !== 'cookie') || name === undefined) return null
+	return { path, kind, credential: { in: location, name } }
+}
+
+function parseGates(value: unknown): AppGates | null {
+	const rawRules = prop(value, 'rules')
+	if (!Array.isArray(rawRules)) return null
+	const rules: GateRule[] = []
+	for (const raw of rawRules) {
+		const rule = parseGate(raw)
+		if (rule === null) return null
+		rules.push(rule)
+	}
+	return { rules }
+}
+
+const parseNamespaceResources = (value: unknown): ZeropsNamespaceResourceRequirement[] | null => {
+	if (!Array.isArray(value)) return null
+	const resources: ZeropsNamespaceResourceRequirement[] = []
+	let hasPostgres = false
+	for (const resource of value) {
+		if (
+			string(resource, 'resourceKey') !== 'service:postgres'
+			|| string(resource, 'hostname') !== 'postgres'
+			|| string(resource, 'connectionString') !== SHARED_POSTGRES_CONNECTION_STRING
+		) {
+			return null
+		}
+		if (hasPostgres) return null
+		hasPostgres = true
+		resources.push({
+			resourceKey: 'service:postgres',
+			hostname: 'postgres',
+			connectionString: SHARED_POSTGRES_CONNECTION_STRING,
+		})
+	}
+	return resources
+}
+
+function parseProxy(value: unknown): ZeropsProxySpec | null {
+	const upstream = nonEmptyString(value, 'upstream')
+	const gates = parseGates(prop(value, 'gates'))
+	return upstream === undefined || gates === null ? null : { upstream, gates }
+}
+
+const parseImportDocument = (value: unknown): FabrikaImportDocument => {
+	if (value === undefined) {
+		throw new Error('invalid fabrika manifest Zerops import document')
+	}
+	const raw = jsonObject(value, 'Zerops import document')
+	const unknownKeys = Object.keys(raw).filter((key) => key !== 'project' && key !== 'services')
+	if (unknownKeys.length > 0) {
+		throw new Error(`invalid fabrika manifest Zerops import document field \`${unknownKeys[0]}\``)
+	}
+	const rawServices = raw['services']
+	if (!Array.isArray(rawServices) || rawServices.length === 0) {
+		throw new Error('invalid fabrika manifest Zerops import services')
+	}
+	const services: Array<{ readonly [key: string]: JsonValue }> = []
+	const hostnames = new Set<string>()
+	for (const [index, rawService] of rawServices.entries()) {
+		const service = jsonObject(rawService, `Zerops import service ${index}`)
+		const hostname = service['hostname']
+		if (typeof hostname !== 'string' || !ZEROPS_SERVICE_HOSTNAME_PATTERN.test(hostname)) {
+			throw new Error(`invalid fabrika manifest Zerops service hostname at index ${index}`)
+		}
+		if (hostnames.has(hostname)) {
+			throw new Error(`invalid fabrika manifest: duplicate Zerops service hostname \`${hostname}\``)
+		}
+		if (typeof service['type'] !== 'string' || service['type'] === '') {
+			throw new Error(`invalid fabrika manifest Zerops service type for \`${hostname}\``)
+		}
+		// `override: true` is required on EVERY service class, managed included — without it the platform
+		// rejects a re-apply of the whole document as a name collision (see `compile.ts`).
+		if (service['envIsolation'] !== ENV_ISOLATION || service['override'] !== OVERRIDE) {
+			throw new Error(`invalid fabrika manifest Zerops service invariants for \`${hostname}\``)
+		}
+		if (service['envSecrets'] !== undefined || service['dotEnvSecrets'] !== undefined) {
+			throw new Error('invalid fabrika manifest: Zerops import contains a forbidden environment field')
+		}
+		hostnames.add(hostname)
+		services.push(service)
+	}
+	const rawProject = raw['project']
+	let project: { readonly [key: string]: JsonValue } | undefined
+	if (rawProject !== undefined) {
+		project = jsonObject(rawProject, 'Zerops import project')
+		if (project['envIsolation'] !== ENV_ISOLATION || project['envVariables'] !== undefined) {
+			throw new Error('invalid fabrika manifest: Zerops import contains a forbidden project environment field')
+		}
+	}
+	return project === undefined ? { services } : { project, services }
+}
+
+export const manifestServiceHostnames = (manifest: FabrikaManifest): string[] =>
+	manifest.target.importDocument.services.map((service) => {
+		const hostname = service['hostname']
+		if (typeof hostname !== 'string') {
+			throw new Error('invalid canonical Zerops service hostname')
+		}
+		return hostname
+	})
+
+export const renderFabrikaImportYaml = (manifest: FabrikaManifest): string => renderYaml(manifest.target.importDocument)
+
+/** Render the codeless import used before registration has a deploy-service id. */
+export const renderFabrikaProvisioningYaml = (manifest: FabrikaManifest): string =>
+	renderYaml({
+		...(manifest.target.importDocument.project === undefined ? {} : { project: manifest.target.importDocument.project }),
+		services: manifest.target.importDocument.services.map((service) => ({ ...service, startWithoutCode: true })),
+	})
+
+export function parseFabrikaManifest(value: unknown, expected: ManifestExpectation = {}): FabrikaManifest {
+	if (prop(value, 'manifestVersion') !== FABRIKA_MANIFEST_VERSION) {
+		throw new Error(`unsupported fabrika manifest version (expected ${FABRIKA_MANIFEST_VERSION})`)
+	}
+	const rawApp = prop(value, 'app')
+	const id = nonEmptyString(rawApp, 'id')
+	const env = nonEmptyString(rawApp, 'env')
+	const rawPipeline = prop(rawApp, 'pipeline')
+	const secrets = stringArray(rawPipeline, 'secrets')
+	const vars = stringArray(rawPipeline, 'vars')
+	if (id === undefined || env === undefined || secrets === undefined || vars === undefined) {
+		throw new Error('invalid fabrika manifest app metadata')
+	}
+	if (expected.appId !== undefined && expected.appId !== id) {
+		throw new Error(`manifest app drift: expected \`${expected.appId}\`, got \`${id}\``)
+	}
+	if (expected.env !== undefined && expected.env !== env) {
+		throw new Error(`manifest environment drift: expected \`${expected.env}\`, got \`${env}\``)
+	}
+	const rawSchema = prop(rawApp, 'schema')
+	let schema: AppSchema | undefined
+	if (rawSchema !== undefined) {
+		const parsed = parseSchema(rawSchema)
+		if (parsed === null) {
+			throw new Error('invalid fabrika manifest schema')
+		}
+		schema = parsed
+	}
+
+	const rawTarget = prop(value, 'target')
+	const rawImportDocument = prop(rawTarget, 'importDocument')
+	const deployService = nonEmptyString(rawTarget, 'deployService')
+	if (
+		string(rawTarget, 'platform') !== 'zerops'
+		|| deployService === undefined
+	) {
+		throw new Error('invalid fabrika manifest Zerops target')
+	}
+	const importDocument = parseImportDocument(rawImportDocument)
+	const serviceHostnames = importDocument.services.map((service) => {
+		const hostname = service['hostname']
+		if (typeof hostname !== 'string') {
+			throw new Error('invalid fabrika manifest Zerops service hostname')
+		}
+		return hostname
+	})
+	if (!serviceHostnames.includes(deployService)) {
+		throw new Error('invalid fabrika manifest Zerops deploy service')
+	}
+	const zeropsSetup = optionalString(rawTarget, 'zeropsSetup')
+	if (prop(rawTarget, 'zeropsSetup') !== undefined && zeropsSetup === null) {
+		throw new Error('invalid fabrika manifest zeropsSetup')
+	}
+	const rawProxy = prop(rawTarget, 'proxy')
+	let proxy: ZeropsProxySpec | undefined
+	if (rawProxy !== undefined) {
+		const parsed = parseProxy(rawProxy)
+		if (parsed === null) {
+			throw new Error('invalid fabrika manifest proxy declaration')
+		}
+		proxy = parsed
+		const separator = parsed.upstream.indexOf(':')
+		const upstreamHostname = separator === -1 ? parsed.upstream : parsed.upstream.slice(0, separator)
+		if (!serviceHostnames.includes(upstreamHostname)) {
+			throw new Error(`invalid fabrika manifest: proxy upstream service \`${upstreamHostname}\` is not owned by this app`)
+		}
+	}
+	const rawNamespaceResources = prop(rawTarget, 'namespaceResources')
+	let namespaceResources: ZeropsNamespaceResourceRequirement[] | undefined
+	if (rawNamespaceResources !== undefined) {
+		const parsed = parseNamespaceResources(rawNamespaceResources)
+		if (parsed === null) {
+			throw new Error('invalid fabrika manifest namespace resources')
+		}
+		namespaceResources = parsed
+	}
+	if (namespaceResources?.some((resource) => serviceHostnames.includes(resource.hostname)) === true) {
+		throw new Error('invalid fabrika manifest: an app cannot declare a namespace-owned service')
+	}
+
+	return {
+		manifestVersion: FABRIKA_MANIFEST_VERSION,
+		app: {
+			id,
+			env,
+			...(schema !== undefined ? { schema } : {}),
+			pipeline: { secrets, vars },
+		},
+		target: {
+			platform: 'zerops',
+			importDocument,
+			deployService,
+			...(zeropsSetup !== null ? { zeropsSetup } : {}),
+			...(proxy !== undefined ? { proxy } : {}),
+			...(namespaceResources !== undefined ? { namespaceResources } : {}),
+		},
+	}
+}
+
+export function compileFabrikaManifest(config: ZeropsAppConfig, env: string): FabrikaManifest {
+	if (config.target.services === undefined) {
+		throw new Error('fabrika app build requires a source Zerops config')
+	}
+	const declaredVars = config.pipeline?.vars ?? []
+	const prior: Record<string, string | undefined> = {}
+	for (const name of declaredVars) {
+		prior[name] = process.env[name]
+		process.env[name] = `\${${name}}`
+	}
+	try {
+		const document = compileImport({ target: config.target, ctx: { env } })
+		const serviceHostnames = document.services.map((service) => service.hostname)
+		const deployService = config.target.deployService ?? (serviceHostnames.length === 1 ? serviceHostnames[0] : undefined)
+		if (deployService === undefined || !serviceHostnames.includes(deployService)) {
+			throw new Error('fabrika app build: a multi-service Zerops app must name a valid deployService')
+		}
+		if (config.target.namespaceResources?.some((resource) => serviceHostnames.includes(resource.hostname)) === true) {
+			throw new Error('fabrika app build: an app cannot declare a namespace-owned service')
+		}
+		const manifest: FabrikaManifest = {
+			manifestVersion: FABRIKA_MANIFEST_VERSION,
+			app: {
+				id: config.id,
+				env,
+				...(config.schema !== undefined ? { schema: config.schema } : {}),
+				pipeline: {
+					secrets: [...(config.pipeline?.secrets ?? [])],
+					vars: [...declaredVars],
+				},
+			},
+			target: {
+				platform: 'zerops',
+				importDocument: parseImportDocument(document),
+				deployService,
+				...(config.target.zeropsSetup !== undefined ? { zeropsSetup: config.target.zeropsSetup } : {}),
+				...(config.target.proxy !== undefined ? { proxy: config.target.proxy } : {}),
+				...(config.target.namespaceResources !== undefined ? { namespaceResources: [...config.target.namespaceResources] } : {}),
+			},
+		}
+		return parseFabrikaManifest(manifest, { appId: config.id, env })
+	} finally {
+		for (const name of declaredVars) {
+			const value = prior[name]
+			if (value === undefined) {
+				delete process.env[name]
+			} else {
+				process.env[name] = value
+			}
+		}
+	}
+}
+
+/** Provider artifact codec. Its envelope version and manifest payload version advance independently. */
+export const zeropsArtifactCodec: ProviderCodec<FabrikaManifest> = {
+	version: 2,
+	encode: jsonValue,
+	decode: (payload) => parseFabrikaManifest(payload),
+}

package/src/namespace-command.ts

@@ -0,0 +1,209 @@
+import type { JsonValue, ProviderDeploymentNamespace, ProviderNamespacePlan } from '@fabrika/provider-contract'
+import type { ZeropsCliArgs } from './cli-args'
+import { createZeropsNamespaceOperator, type ZeropsNamespacePostgres, zeropsNamespaceTargetCodec } from './namespace'
+
+export interface ZeropsNamespaceCommandDependencies {
+	readonly source: Readonly<Record<string, string | undefined>>
+	readonly fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>
+	readonly write: (value: string) => void
+}
+
+const required = (value: string | undefined, label: string): string => {
+	if (value === undefined || value.trim() === '') {
+		throw new Error(`${label} is required`)
+	}
+	return value.trim()
+}
+
+const postgres = (args: ZeropsCliArgs): ZeropsNamespacePostgres | undefined => {
+	const type = args.postgresType
+	const profile = args.postgresProfile
+	if (type === undefined && profile === undefined) return undefined
+	if (type === undefined) {
+		throw new Error('--postgres-type is required with --postgres-profile')
+	}
+	if (type === 'postgresql:ha@18') {
+		if (
+			profile !== undefined
+			&& profile !== 'oltp-staging'
+			&& profile !== 'oltp-production'
+			&& profile !== 'oltp-enterprise'
+			&& profile !== 'olap-production'
+			&& profile !== 'writeheavy-production'
+		) {
+			throw new Error(`--postgres-profile ${profile} is not supported by ${type}`)
+		}
+		return profile === undefined ? { type } : { type, profile }
+	}
+	if (type === 'postgresql:single@18') {
+		if (
+			profile !== undefined
+			&& profile !== 'oltp-hobby'
+			&& profile !== 'oltp-staging'
+			&& profile !== 'oltp-production'
+			&& profile !== 'olap-production'
+			&& profile !== 'writeheavy-production'
+		) {
+			throw new Error(`--postgres-profile ${profile} is not supported by ${type}`)
+		}
+		return profile === undefined ? { type } : { type, profile }
+	}
+	throw new Error('--postgres-type must be postgresql:ha@18 or postgresql:single@18')
+}
+
+const planOptions = (args: ZeropsCliArgs): { [key: string]: JsonValue } | undefined => {
+	const values: { [key: string]: JsonValue } = {}
+	if (args.projectName !== undefined) values['projectName'] = required(args.projectName, '--project-name')
+	if (args.corePackage !== undefined) values['corePackage'] = required(args.corePackage, '--core-package')
+	if (args.publicAccess !== undefined) values['publicAccess'] = required(args.publicAccess, '--public-access')
+	const database = postgres(args)
+	if (database !== undefined) {
+		values['postgres'] = database.profile === undefined ? { type: database.type } : { type: database.type, profile: database.profile }
+	}
+	return Object.keys(values).length === 0 ? undefined : values
+}
+
+const namespacePlan = (
+	args: ZeropsCliArgs,
+	source: Readonly<Record<string, string | undefined>>,
+): ProviderNamespacePlan => {
+	// `FABRIKA_ZEROPS_*` because Zerops reserves the bare `ZEROPS_` prefix and refuses to store a custom
+	// variable using it (`userDataZeropsPrefixForbidden`).
+	const proxyBuildFromGit = required(
+		args.proxyBuildFromGit ?? source['FABRIKA_ZEROPS_PROXY_BUILD_FROM_GIT'],
+		'--proxy-build-from-git or FABRIKA_ZEROPS_PROXY_BUILD_FROM_GIT',
+	)
+	const operator = createZeropsNamespaceOperator({ proxyBuildFromGit })
+	const options = planOptions(args)
+	return operator.plan({
+		id: required(args.namespaceId, '--id'),
+		env: required(args.env, '--env'),
+		preset: required(args.preset, '--preset'),
+		...(args.exclusiveAppId === undefined ? {} : { exclusiveAppId: required(args.exclusiveAppId, '--exclusive-app') }),
+		...(options === undefined ? {} : { options }),
+	})
+}
+
+const outputJson = (value: unknown): string => `${JSON.stringify(value, null, '\t')}\n`
+
+const responseText = async (response: Response): Promise<string> => {
+	const text = await response.text()
+	if (response.ok) return text.trim() === '' ? 'null' : text
+	let message = `Control API request failed (${response.status})`
+	try {
+		const body: unknown = JSON.parse(text)
+		if (typeof body === 'object' && body !== null) {
+			const error = Reflect.get(body, 'error')
+			if (typeof error === 'string' && error !== '') message = error
+		}
+	} catch {
+		if (text.trim() !== '' && text.length < 500) message = text
+	}
+	throw new Error(message)
+}
+
+const controlCoordinates = (
+	args: ZeropsCliArgs,
+	source: Readonly<Record<string, string | undefined>>,
+): { baseUrl: URL; token: string } => {
+	const value = required(args.controlUrl ?? source['FABRIKA_CONTROL_URL'], '--control-url or FABRIKA_CONTROL_URL')
+	const token = required(source['FABRIKA_CONTROL_TOKEN'], 'FABRIKA_CONTROL_TOKEN')
+	let baseUrl: URL
+	try {
+		baseUrl = new URL(value)
+	} catch {
+		throw new Error('--control-url or FABRIKA_CONTROL_URL must be an absolute URL')
+	}
+	if (baseUrl.protocol !== 'https:' && baseUrl.protocol !== 'http:') {
+		throw new Error('--control-url or FABRIKA_CONTROL_URL must use http or https')
+	}
+	return { baseUrl, token }
+}
+
+const callControl = async (
+	deps: ZeropsNamespaceCommandDependencies,
+	coordinates: { baseUrl: URL; token: string },
+	path: string,
+	body?: unknown,
+): Promise<void> => {
+	const response = await deps.fetch(new URL(path, coordinates.baseUrl), {
+		method: 'POST',
+		headers: {
+			accept: 'application/json',
+			authorization: `Bearer ${coordinates.token}`,
+			...(body === undefined ? {} : { 'content-type': 'application/json' }),
+		},
+		...(body === undefined ? {} : { body: JSON.stringify(body) }),
+	})
+	const text = await responseText(response)
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(text)
+	} catch {
+		parsed = text
+	}
+	deps.write(outputJson(parsed))
+}
+
+const createBody = (namespace: ProviderDeploymentNamespace): object => ({
+	id: namespace.id,
+	env: namespace.env,
+	...(namespace.exclusiveAppId === undefined ? {} : { exclusiveAppId: namespace.exclusiveAppId }),
+	target: namespace.target,
+})
+
+const adoptBody = (namespace: ProviderDeploymentNamespace): object => ({
+	env: namespace.env,
+	...(namespace.exclusiveAppId === undefined ? {} : { exclusiveAppId: namespace.exclusiveAppId }),
+	target: namespace.target,
+})
+
+/** Execute one namespace command. All command inputs are validated before the first fetch. */
+export const runZeropsNamespaceCommand = async (
+	args: ZeropsCliArgs,
+	deps: ZeropsNamespaceCommandDependencies,
+): Promise<void> => {
+	const subcommand = required(args.subcommand, 'namespace command')
+	if (subcommand === 'plan') {
+		deps.write(outputJson(namespacePlan(args, deps.source)))
+		return
+	}
+	if (subcommand === 'reconcile') {
+		const id = required(args.namespaceId, '--id')
+		const control = controlCoordinates(args, deps.source)
+		await callControl(deps, control, `/api/namespaces/${encodeURIComponent(id)}/reconcile`)
+		return
+	}
+	if (subcommand !== 'create' && subcommand !== 'adopt') {
+		throw new Error(`Unknown namespace command: ${subcommand}`)
+	}
+
+	const planned = namespacePlan(args, deps.source)
+	const control = controlCoordinates(args, deps.source)
+	if (subcommand === 'create') {
+		await callControl(deps, control, '/api/namespaces', createBody(planned.namespace))
+		return
+	}
+
+	const projectId = required(args.projectId, '--project-id')
+	const decoded = zeropsNamespaceTargetCodec.decode(planned.namespace.target.payload)
+	const namespace: ProviderDeploymentNamespace = {
+		...planned.namespace,
+		target: {
+			provider: 'zerops',
+			version: zeropsNamespaceTargetCodec.version,
+			payload: zeropsNamespaceTargetCodec.encode({
+				...decoded,
+				managed: false,
+				projectId,
+				ready: false,
+			}),
+		},
+	}
+	await callControl(
+		deps,
+		control,
+		`/api/namespaces/${encodeURIComponent(namespace.id)}/adopt`,
+		adoptBody(namespace),
+	)
+}