@contember/cli 2.2.0-alpha.3 → 2.2.0-alpha.4

package/src/lib/tenant/TenantApiTransport.ts

@@ -0,0 +1,200 @@
+import { CliError, ExitCode } from '@contember/cli-common'
+import { GraphQlClient } from '@contember/graphql-client'
+import { Fetcher, TextWriter, util } from 'graphql-ts-client-api'
+import { toTransportError } from '../errors/TransportError.js'
+
+/** Normalizes any endpoint the user may have configured into the tenant GraphQL endpoint. */
+export const createTenantApiUrl = (url: string): string => {
+	if (url.endsWith('/')) {
+		url = url.substring(0, url.length - 1)
+	}
+	if (url.endsWith('/tenant')) {
+		return url
+	}
+	return url + '/tenant'
+}
+
+/** The shape every tenant `*Response` mutation payload shares. */
+export interface TenantMutationResult {
+	readonly ok: boolean
+	readonly error?: {
+		readonly code: string
+		readonly developerMessage?: string | null
+		readonly weakPasswordReasons?: readonly unknown[] | null
+		readonly recommendedAction?: unknown
+	} | null
+}
+
+/**
+ * The single transport every tenant domain client is built on.
+ *
+ * Usage — see `clients/README.md`:
+ *
+ * ```ts
+ * const personsFetcher = query$.persons(person$$)                       // built once, fetchers are immutable
+ * const result = await this.transport.exec(personsFetcher, { limit })   // variables are typed by the fetcher
+ * this.transport.assertOk(result.disablePerson, 'disablePerson')        // mutation payloads only
+ * ```
+ *
+ * Everything thrown out of here is a {@link CliError} with a stable `code` and the `ExitCode`
+ * matching the taxonomy, so no command has to translate tenant errors itself.
+ */
+export class TenantApiTransport {
+	constructor(
+		private readonly apiClient: GraphQlClient,
+	) {
+	}
+
+	public static create(url: string, apiToken: string): TenantApiTransport {
+		return new TenantApiTransport(new GraphQlClient({ url: createTenantApiUrl(url), apiToken }))
+	}
+
+	public get apiUrl(): string {
+		return this.apiClient.apiUrl
+	}
+
+	/** Runs a `graphql-ts-client-api` fetcher as a query or a mutation, depending on the fetcher's root type. */
+	public async exec<TData extends object, TVariables extends object>(
+		fetcher: Fetcher<'Query' | 'Mutation', TData, TVariables>,
+		variables: TVariables,
+	): Promise<TData> {
+		try {
+			return await this.apiClient.execute<TData>(buildRequestDocument(fetcher), { variables })
+		} catch (e) {
+			throw toTenantApiError(e)
+		}
+	}
+
+	/** Turns a failed tenant mutation payload into a {@link CliError} carrying the tenant error code. */
+	public assertOk(result: TenantMutationResult | null | undefined, operation: string): void {
+		if (result?.ok === true) {
+			return
+		}
+		throw tenantMutationError(result, operation)
+	}
+}
+
+/** Builds the operation document out of a fetcher — the variable declarations are derived from its variable map. */
+export const buildRequestDocument = (fetcher: Fetcher<'Query' | 'Mutation', object, object>): string => {
+	const writer = new TextWriter()
+	writer.text(fetcher.fetchableType.name.toLowerCase())
+	if (fetcher.variableTypeMap.size !== 0) {
+		writer.scope({ type: 'ARGUMENTS', multiLines: fetcher.variableTypeMap.size > 2, suffix: ' ' }, () => {
+			util.iterateMap(fetcher.variableTypeMap, ([name, type]) => {
+				writer.seperator()
+				writer.text(`$${name}: ${type}`)
+			})
+		})
+	}
+	writer.text(fetcher.toString())
+	writer.text(fetcher.toFragmentString())
+	return writer.toString()
+}
+
+export const tenantMutationError = (result: TenantMutationResult | null | undefined, operation: string): CliError => {
+	const code = result?.error?.code ?? 'UNKNOWN'
+	const developerMessage = result?.error?.developerMessage ?? null
+	const details: Record<string, unknown> = { operation, code, developerMessage }
+	const weakPasswordReasons = result?.error?.weakPasswordReasons?.filter(isWeakPasswordReason)
+	if (weakPasswordReasons !== undefined && weakPasswordReasons.length > 0) {
+		details.weakPasswordReasons = weakPasswordReasons
+	}
+	const recommendedAction = result?.error?.recommendedAction
+	if (isSignUpRecommendedAction(recommendedAction)) {
+		details.recommendedAction = recommendedAction
+	}
+	return new CliError(`${operation} failed: ${code}${developerMessage ? ` — ${developerMessage}` : ''}`, {
+		code,
+		exitCode: tenantErrorCodeToExitCode(code),
+		details,
+	})
+}
+
+const weakPasswordReasons = [
+	'TOO_SHORT',
+	'MISSING_UPPERCASE',
+	'MISSING_LOWERCASE',
+	'MISSING_DIGIT',
+	'MISSING_SPECIAL',
+	'INVALID_PATTERN',
+	'BLACKLISTED',
+	'COMPROMISED',
+]
+
+const isWeakPasswordReason = (value: unknown): value is string => typeof value === 'string' && weakPasswordReasons.includes(value)
+
+const isSignUpRecommendedAction = (value: unknown): value is string => value === 'SIGN_IN' || value === 'RESET_PASSWORD'
+
+/**
+ * The tenant API returns a per-mutation error code enum (see `tenant.graphql`). Only the codes that are
+ * not plain input errors are listed — everything unlisted falls back to {@link ExitCode.InputError}.
+ */
+const tenantErrorCodeExitCodes = new Map<string, ExitCode>([
+	// conflicts
+	['ALREADY_EXISTS', ExitCode.Conflict],
+	['ALREADY_MEMBER', ExitCode.Conflict],
+	['EMAIL_ALREADY_EXISTS', ExitCode.Conflict],
+	['PERSON_ALREADY_EXISTS', ExitCode.Conflict],
+	['PERSON_ALREADY_DISABLED', ExitCode.Conflict],
+
+	// not found
+	['NOT_FOUND', ExitCode.NotFound],
+	['IDENTITY_NOT_FOUND', ExitCode.NotFound],
+	['KEY_NOT_FOUND', ExitCode.NotFound],
+	['PERSON_NOT_FOUND', ExitCode.NotFound],
+	['PROJECT_NOT_FOUND', ExitCode.NotFound],
+	['PROVIDER_NOT_FOUND', ExitCode.NotFound],
+	['ROLE_NOT_FOUND', ExitCode.NotFound],
+	['SESSION_NOT_FOUND', ExitCode.NotFound],
+	['TEMPLATE_NOT_FOUND', ExitCode.NotFound],
+	['TOKEN_NOT_FOUND', ExitCode.NotFound],
+	['VARIABLE_NOT_FOUND', ExitCode.NotFound],
+	['UNKNOWN_EMAIL', ExitCode.NotFound],
+	['UNKNOWN_PERSON_ID', ExitCode.NotFound],
+	['NOT_MEMBER', ExitCode.NotFound],
+
+	// auth / permission
+	['INVALID_CREDENTIALS', ExitCode.Forbidden],
+	['PERSON_DISABLED', ExitCode.Forbidden],
+	['EMAIL_NOT_VERIFIED', ExitCode.Forbidden],
+	['MFA_REQUIRED', ExitCode.Forbidden],
+	['MFA_ENROLLMENT_REQUIRED', ExitCode.Forbidden],
+	['OTP_REQUIRED', ExitCode.Forbidden],
+	['INVALID_OTP_TOKEN', ExitCode.Forbidden],
+	['PASSWORDLESS_DISABLED', ExitCode.Forbidden],
+	['NOT_POSSIBLE_SIGN_OUT_WITH_PERMANENT_API_KEY', ExitCode.Forbidden],
+
+	// retryable
+	['RATE_LIMITED', ExitCode.Transient],
+	['RATE_LIMIT_EXCEEDED', ExitCode.Transient],
+
+	// server-side failures the caller cannot fix by changing the input
+	['INIT_ERROR', ExitCode.InternalError],
+	['UNKNOWN', ExitCode.InternalError],
+])
+
+/** Maps a tenant error code onto the exit-code taxonomy. Unknown codes fall back on the naming convention. */
+export const tenantErrorCodeToExitCode = (code: string): ExitCode => {
+	const known = tenantErrorCodeExitCodes.get(code)
+	if (known !== undefined) {
+		return known
+	}
+	// codes added to the schema later follow the same naming, so the taxonomy holds without a CLI release
+	if (code.endsWith('_NOT_FOUND')) {
+		return ExitCode.NotFound
+	}
+	if (code.startsWith('ALREADY_') || code.includes('_ALREADY_')) {
+		return ExitCode.Conflict
+	}
+	if (code.includes('RATE_LIMIT')) {
+		return ExitCode.Transient
+	}
+	return ExitCode.InputError
+}
+
+/** Normalizes a transport-level failure without exposing the GraphQL request or response body. */
+export const toTenantApiError = (error: unknown): CliError =>
+	toTransportError(error, {
+		service: 'Tenant API',
+		codePrefix: 'TENANT_API',
+	})

package/src/lib/tenant/TenantConfigApplier.ts

@@ -1,72 +1,215 @@
-import { TenantClient } from './TenantClient.js'
+import { Output } from '@contember/cli-common'
+import { authPolicyKey, describeAuthPolicy } from './authPolicy.js'
+import { type RemoteAuthPolicy, TenantPolicyClient, TenantProjectClient } from './clients/index.js'
 import { TenantConfig } from './tenantConfig.js'
 
 export interface TenantConfigApplyOptions {
 	dryRun?: boolean
 }
 
+/** The slice of the domain clients the applier drives — structural, so a test can pass a fake. */
+export interface TenantConfigApplierClients {
+	readonly project: Pick<TenantProjectClient, 'configure' | 'listIdentityProviders' | 'addIdp' | 'updateIdp' | 'enableIdp' | 'disableIdp'>
+	readonly policy: Pick<TenantPolicyClient, 'addMailTemplate' | 'listAuthPolicies' | 'createAuthPolicy' | 'updateAuthPolicy'>
+}
+
+export type TenantConfigActionType =
+	| 'configure'
+	| 'addIdp'
+	| 'updateIdp'
+	| 'enableIdp'
+	| 'disableIdp'
+	| 'addMailTemplate'
+	| 'createAuthPolicy'
+	| 'updateAuthPolicy'
+
+/** One step of the apply plan. In a dry run it is what would be done, otherwise what was done. */
+export interface TenantConfigAction {
+	action: TenantConfigActionType
+	target: string | null
+}
+
+export type TenantConfigWarningCode = 'UNMANAGED_AUTH_POLICY'
+
+/** Server-side state the config does not cover. Nothing is pruned, so it stays in effect. */
+export interface TenantConfigWarning {
+	code: TenantConfigWarningCode
+	target: string
+	message: string
+}
+
+/**
+ * The outcome of an apply. Warnings are returned rather than only printed: `output.warn` is silent
+ * outside human mode, and an unmanaged policy is exactly what an agent running `--json` needs to see.
+ */
+export interface TenantConfigPlan {
+	actions: TenantConfigAction[]
+	warnings: TenantConfigWarning[]
+}
+
 /**
  * Applies a {@link TenantConfig} to a tenant idempotently:
- * - `configure` is a partial merge, so it is always (re)sent.
+ * - `configure` is a partial merge and is sent only when the schema maps at least one value to a database change.
  * - identity providers are added or updated based on the current state, then
  *   enabled/disabled to match `disabled`.
  * - mail templates are upserted server-side by `addMailTemplate`.
+ * - auth policies are matched to existing rows by what they target (scope,
+ *   project, role set) and created or updated accordingly; every policy the
+ *   config does not cover is warned about, including when the config lists none.
  *
  * Nothing is ever removed — entries missing from the config are left untouched.
+ *
+ * Returns the plan as data; the caller prints it. The applier itself only reports each action on stderr.
  */
 export class TenantConfigApplier {
-	public async apply(client: TenantClient, config: TenantConfig, options: TenantConfigApplyOptions = {}): Promise<void> {
-		const dryRun = options.dryRun === true
-		const log = (message: string) => console.log(`${dryRun ? '[dry-run] ' : ''}${message}`)
+	constructor(
+		private readonly output: Output = new Output(),
+	) {
+	}
 
-		if (config.config) {
-			log('configure: applying global tenant config')
-			if (!dryRun) {
-				await client.configure(config.config)
+	public async apply(
+		clients: TenantConfigApplierClients,
+		config: TenantConfig,
+		options: TenantConfigApplyOptions = {},
+	): Promise<TenantConfigPlan> {
+		const dryRun = options.dryRun === true
+		const actions: TenantConfigAction[] = []
+		const warnings: TenantConfigWarning[] = []
+		const warn = (code: TenantConfigWarningCode, target: string, message: string) => {
+			warnings.push({ code, target, message })
+			this.output.warn(message)
+		}
+		const run = async (action: TenantConfigActionType, target: string | null, execute: () => Promise<void>) => {
+			actions.push({ action, target })
+			if (dryRun) {
+				return
 			}
+			// info, not progress: `tenant apply` mostly runs in CI, where a non-TTY progress line would leave no record of what was touched
+			this.output.info(target === null ? action : `${action}: ${target}`)
+			await execute()
+		}
+
+		// Up front, before anything has been written: two entries targeting the same
+		// scope/project/roles are one policy to the applier but two rows server-side.
+		assertDistinctAuthPolicies(config.authPolicies)
+		const existingAuthPolicies = config.authPolicies === undefined ? undefined : await clients.policy.listAuthPolicies()
+		assertDistinctExistingAuthPolicies(existingAuthPolicies)
+
+		if (config.config && hasEffectiveConfigValue(config.config)) {
+			const globalConfig = config.config
+			await run('configure', null, () => clients.project.configure(globalConfig))
 		}
 
 		if (config.identityProviders && Object.keys(config.identityProviders).length > 0) {
-			const existing = await client.listIdentityProviders()
+			const existing = await clients.project.listIdentityProviders()
 			const existingBySlug = new Map(existing.map(it => [it.slug, it]))
 
 			for (const [slug, idp] of Object.entries(config.identityProviders)) {
 				const current = existingBySlug.get(slug)
 				if (!current) {
-					log(`addIDP: ${slug} (${idp.type})`)
-					if (!dryRun) {
-						await client.addIdp(slug, idp.type, idp.configuration, idp.options)
-					}
+					await run('addIdp', slug, () => clients.project.addIdp(slug, idp.type, idp.configuration, idp.options))
 				} else {
-					log(`updateIDP: ${slug} (${idp.type})`)
-					if (!dryRun) {
-						await client.updateIdp(slug, idp.type, idp.configuration, idp.options)
-					}
+					await run('updateIdp', slug, () => clients.project.updateIdp(slug, idp.type, idp.configuration, idp.options))
 				}
 
 				const wantDisabled = idp.disabled === true
 				const isDisabled = current ? current.disabledAt !== null : false
 				if (wantDisabled && !isDisabled) {
-					log(`disableIDP: ${slug}`)
-					if (!dryRun) {
-						await client.disableIdp(slug)
-					}
+					await run('disableIdp', slug, () => clients.project.disableIdp(slug))
 				} else if (!wantDisabled && isDisabled) {
-					log(`enableIDP: ${slug}`)
-					if (!dryRun) {
-						await client.enableIdp(slug)
-					}
+					await run('enableIdp', slug, () => clients.project.enableIdp(slug))
 				}
 			}
 		}
 
 		if (config.mailTemplates && config.mailTemplates.length > 0) {
 			for (const template of config.mailTemplates) {
-				log(`addMailTemplate: ${template.type}${template.variant ? `/${template.variant}` : ''}`)
-				if (!dryRun) {
-					await client.addMailTemplate(template)
+				const target = `${template.type}${template.variant ? `/${template.variant}` : ''}`
+				await run('addMailTemplate', target, () => clients.policy.addMailTemplate(template))
+			}
+		}
+
+		// `[]` is meaningful here, unlike for the other sections: it says "I manage
+		// policies and there are none", which is exactly when the warning below matters.
+		if (config.authPolicies) {
+			const existing = existingAuthPolicies ?? []
+			const existingByKey = new Map(existing.map(it => [authPolicyKey(it), it]))
+			const managedKeys = new Set(config.authPolicies.map(authPolicyKey))
+
+			for (const policy of config.authPolicies) {
+				const current = existingByKey.get(authPolicyKey(policy))
+				const target = describeAuthPolicy(policy)
+				if (!current) {
+					await run('createAuthPolicy', target, async () => {
+						await clients.policy.createAuthPolicy(policy)
+					})
+				} else {
+					await run('updateAuthPolicy', target, () => clients.policy.updateAuthPolicy(current.id, policy))
+				}
+			}
+
+			// Policies are aggregated strictest-wins, so one left behind by a config
+			// edit keeps enforcing. Nothing is pruned, but silence would hide it.
+			for (const policy of existing) {
+				if (!managedKeys.has(authPolicyKey(policy))) {
+					const target = describeAuthPolicy(policy)
+					warn('UNMANAGED_AUTH_POLICY', target, `Auth policy ${target} exists but is not in the config; it stays in effect.`)
 				}
 			}
 		}
+
+		return { actions, warnings }
+	}
+}
+
+const assertDistinctExistingAuthPolicies = (policies: readonly RemoteAuthPolicy[] | undefined): void => {
+	const seen = new Set<string>()
+	for (const policy of policies ?? []) {
+		const key = authPolicyKey(policy)
+		if (seen.has(key)) {
+			throw new Error(
+				`Duplicate existing auth policy: ${describeAuthPolicy(policy)}. Resolve duplicate rows before applying the tenant config.`,
+			)
+		}
+		seen.add(key)
+	}
+}
+
+/**
+ * A policy's identity is its target, so two config entries with the same
+ * scope/project/roles are indistinguishable to the applier but produce two rows
+ * server-side — the second of which would then be silently orphaned on the next
+ * run. Cheaper to reject than to reconcile.
+ */
+const assertDistinctAuthPolicies = (policies: TenantConfig['authPolicies']): void => {
+	const seen = new Set<string>()
+	for (const policy of policies ?? []) {
+		const key = authPolicyKey(policy)
+		if (seen.has(key)) {
+			throw `Duplicate auth policy in the config: ${describeAuthPolicy(policy)}. Policies are identified by scope, project and role set.`
+		}
+		seen.add(key)
+	}
+}
+
+/** Null clears only the fields that the tenant update command maps to a nullable database column. */
+const nullableConfigClearPaths = new Set([
+	'passwordless.url',
+	'password.pattern',
+	'login.maxTokenExpiration',
+	'captcha.provider',
+	'captcha.threshold',
+])
+
+const hasEffectiveConfigValue = (value: unknown, path: readonly string[] = []): boolean => {
+	if (value === undefined) {
+		return false
+	}
+	if (value === null) {
+		return nullableConfigClearPaths.has(path.join('.'))
+	}
+	if (typeof value !== 'object') {
+		return true
 	}
+	return Object.entries(value).some(([key, item]) => hasEffectiveConfigValue(item, [...path, key]))
 }

package/src/lib/tenant/TenantConnection.ts

@@ -0,0 +1,8 @@
+export interface TenantConnection {
+	readonly endpoint: string
+	readonly token: string
+}
+
+export interface TenantConnectionSource {
+	get(): TenantConnection
+}

package/src/lib/tenant/TenantConnectionProvider.ts

@@ -0,0 +1,21 @@
+import { CliError, ExitCode } from '@contember/cli-common'
+import type { TenantConnection, TenantConnectionSource } from './TenantConnection.js'
+import { TenantConnectionResolver } from './TenantConnectionResolver.js'
+
+export class TenantConnectionProvider implements TenantConnectionSource {
+	constructor(
+		private readonly resolver: TenantConnectionResolver,
+	) {
+	}
+
+	public get(): TenantConnection {
+		const connection = this.resolver.resolve()
+		if (!connection) {
+			throw new CliError('Tenant connection not defined. Set CONTEMBER_DSN, or CONTEMBER_API_URL and CONTEMBER_API_TOKEN.', {
+				code: 'TENANT_CONNECTION_NOT_DEFINED',
+				exitCode: ExitCode.InputError,
+			})
+		}
+		return connection
+	}
+}

package/src/lib/tenant/TenantConnectionResolver.ts

@@ -0,0 +1,31 @@
+import { parseDsn } from '../dsn.js'
+import type { CliEnv } from '../env.js'
+import type { TenantConnection } from './TenantConnection.js'
+
+export class TenantConnectionResolver {
+	constructor(
+		private readonly cliEnv: CliEnv,
+	) {
+	}
+
+	public resolve(): TenantConnection | undefined {
+		let endpoint: string | undefined
+		let token: string | undefined
+		if (this.cliEnv.dsn) {
+			;({ endpoint, token } = parseDsn(this.cliEnv.dsn))
+		} else {
+			endpoint = this.cliEnv.apiUrl
+			token = this.cliEnv.apiToken
+		}
+		if (!endpoint || !token) {
+			return undefined
+		}
+		if (endpoint.endsWith('/')) {
+			endpoint = endpoint.slice(0, -1)
+		}
+		if (endpoint.endsWith('.contember.cloud') && !endpoint.includes('://api-')) {
+			endpoint += '/_api'
+		}
+		return { endpoint, token }
+	}
+}

package/src/lib/tenant/authPolicy.ts

@@ -0,0 +1,20 @@
+interface AuthPolicyIdentity {
+	scope: string
+	project?: string | null
+	roles: readonly string[]
+}
+
+/**
+ * Identity of a policy for reconciliation purposes. `auth_policy` has no unique
+ * constraint beyond its generated id, so the config is matched against existing
+ * rows by what the policy actually *targets*: a scope, an optional project and a
+ * set of roles. Roles are sorted because `AuthPolicyResolver` treats them as a
+ * set (it matches with `roles.some(...)`), so ordering carries no meaning.
+ */
+export const authPolicyKey = (policy: AuthPolicyIdentity): string => JSON.stringify([policy.scope, policy.project ?? null, [...policy.roles].sort()])
+
+/** Human-readable label for logs and error messages. */
+export const describeAuthPolicy = (policy: AuthPolicyIdentity): string => {
+	const target = policy.scope === 'project' ? `project:${policy.project ?? '?'}` : 'global'
+	return `${target} [${[...policy.roles].sort().join(', ')}]`
+}

package/src/lib/tenant/clients/README.md

@@ -0,0 +1,84 @@
+# Tenant domain clients
+
+One class per tenant domain, all sharing a single `TenantApiTransport`
+(`../TenantApiTransport.ts`). Add methods to the class that owns the domain — never a new client, and
+never a raw `GraphQlClient`.
+
+| Client                 | Owns                                                          |
+| ---------------------- | ------------------------------------------------------------- |
+| `TenantProjectClient`  | projects, project secrets, global config, identity providers, `me` |
+| `TenantPersonClient`   | persons, global identity roles, sessions                       |
+| `TenantMemberClient`   | project memberships, invites                                   |
+| `TenantApiKeyClient`   | api keys                                                       |
+| `TenantPolicyClient`   | auth policies, mail templates, auth log                        |
+
+## The pattern
+
+### 1. Declare the fetcher at module level
+
+Fetchers from `@contember/graphql-client-tenant` are immutable and reusable, so build them once at
+module load — not per call.
+
+```ts
+import { mutation$, person$$, query$, disablePersonError$$, disablePersonResponse$$ } from '@contember/graphql-client-tenant'
+
+const personsFetcher = query$.persons(person$$)
+const disablePersonFetcher = mutation$.disablePerson(disablePersonResponse$$.error(disablePersonError$$))
+```
+
+`x$` is the empty fetcher for type `X`, `x$$` selects all its scalar fields, and `.field(childFetcher)`
+descends into a reference or a list. Field arguments become GraphQL variables of the same name.
+
+### 2. Call `transport.exec(fetcher, variables)`
+
+```ts
+public async listPersons({ filter, limit, offset }: ListPersonsArgs = {}): Promise<TenantPerson[]> {
+	const result = await this.transport.exec(personsFetcher, { filter, limit, offset })
+	return result.persons.map(it => ({ id: it.id, email: it.email ?? null }))
+}
+```
+
+`exec` works the same for queries and mutations — the root type comes from the fetcher. `variables` is
+typed by the fetcher, so a missing or misnamed variable is a compile error.
+
+**Return a CLI-owned type, not the wire type.** Generated selections mark nullable fields as
+`?: T` (optional, never `null`); commands print JSON, so map them to `T | null` explicitly. That also
+keeps the command layer independent of codegen churn.
+
+### 3. Assert mutation payloads with `transport.assertOk`
+
+Every tenant mutation returns `{ ok, error { code, developerMessage } }`. Do not read `ok` yourself:
+
+```ts
+public async disablePerson(personId: string): Promise<void> {
+	const result = await this.transport.exec(disablePersonFetcher, { personId })
+	this.transport.assertOk(result.disablePerson, `disablePerson(${personId})`)
+}
+```
+
+The string is the operation label used in the error message. Only branch on a code yourself when a
+specific code is *not* an error for the caller — see `TenantProjectClient.createProject`, where
+`ignoreExisting` swallows `ALREADY_EXISTS`.
+
+## Error normalization — already done for you
+
+Never throw a string and never catch to re-wrap. Everything that leaves the transport is already a
+`CliError` with a stable `code` and the right `ExitCode`:
+
+- **Mutation payload errors** → `code` is the tenant error code verbatim (`ALREADY_EXISTS`,
+  `PERSON_NOT_FOUND`, …), so `--json` gives an agent `.error.code` it can branch on. The exit code
+  comes from `tenantErrorCodeToExitCode`: `*_NOT_FOUND` → `NotFound`, `ALREADY_*` → `Conflict`,
+  rate limits → `Transient`, permission/MFA failures → `Forbidden`, everything else → `InputError`.
+- **Transport failures** → `TENANT_API_UNREACHABLE` / `TENANT_API_SERVER_ERROR` / `TENANT_API_ABORTED`
+  (`Transient`, retryable), `TENANT_API_UNAUTHORIZED` / `TENANT_API_FORBIDDEN` (`Forbidden`),
+  `TENANT_API_BAD_REQUEST` (`InputError`), `TENANT_API_INVALID_RESPONSE` (`InternalError`). A
+  resolver-level `ForbiddenError` GraphQL extension is detected too, whatever the HTTP status.
+
+If a code maps to the wrong class, fix the table in `TenantApiTransport.ts` — do not special-case it
+in a client or a command.
+
+## Getting a client
+
+- In a command wired through DI: `TenantClientProvider` (`../../TenantClientProvider.ts`) exposes
+  `project()`, `person()`, `member()`, `apiKey()` and `policy()`.
+- From an explicit endpoint and token: `createTenantClients(TenantApiTransport.create(url, token))`.