@contember/cli 2.1.0-rc.3 → 2.2.0-alpha.10

package/src/commands/tenant/member/TenantMemberInviteCommand.ts

@@ -0,0 +1,88 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import type { InviteMethod } from '@contember/graphql-client-tenant'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { formatMemberships, requireOptionValue } from './memberOptions.js'
+import { configureMembershipOptions, MembershipOptions, readMembershipInputSource, resolveNonEmptyMemberships } from './membershipInput.js'
+import { readStdinText, StdinReader } from '../../../lib/tenant/stdin.js'
+import { humanText, requireNonEmptyTenantName } from '../tenantOutput.js'
+
+type Args = {}
+
+type Options = MembershipOptions & {
+	project?: string
+	email?: string
+	name?: string
+	method?: string
+	['mail-variant']?: string
+}
+
+const inviteMethods: InviteMethod[] = ['CREATE_PASSWORD', 'RESET_PASSWORD']
+
+/**
+ * `tenant member invite`
+ *
+ * The mail-sending half of the invite pair. `tenant member invite-unmanaged` is a separate command rather
+ * than a flag here: the two mutations share no options at all (mail method and variant versus a password
+ * or a reset token hash), and only one of them handles a secret.
+ */
+export class TenantMemberInviteCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdin: StdinReader = readStdinText,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Invite a person to a project by e-mail')
+		configuration.option('project').valueRequired().required().description('Project slug.')
+		configuration.option('email').valueRequired().required().description('E-mail address of the invited person.')
+		configuration.option('name').valueRequired().description('Name of the invited person. Used only when the person does not exist yet.')
+		configuration.option('method').valueRequired().description(
+			`How the person gets their credentials: ${inviteMethods.join(' or ')} (default ${inviteMethods[0]}).`,
+		)
+		configuration.option('mail-variant').valueRequired().description('Mail template variant to use.')
+		configureMembershipOptions(configuration)
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const projectSlug = requireOptionValue(input.getOption('project'), 'project')
+		const email = requireOptionValue(input.getOption('email'), 'email')
+		const name = requireNonEmptyTenantName(input.getOption('name'), 'Person')
+		const memberships = await resolveNonEmptyMemberships(readMembershipInputSource(input), this.readStdin)
+
+		output.info(`Inviting ${email} to project ${projectSlug} as ${formatMemberships(memberships)}`)
+		const result = await this.tenantClientProvider.member().invite({
+			projectSlug,
+			email,
+			name,
+			memberships,
+			options: { method: parseInviteMethod(input.getOption('method')), mailVariant: input.getOption('mail-variant') },
+		})
+
+		output.data(
+			{ projectSlug, ...result },
+			{
+				human: it =>
+					it.isNew
+						? `Invited ${humanText(it.email ?? email)} to ${humanText(it.projectSlug)}. Identity: ${humanText(it.identityId)}`
+						: `${humanText(it.email ?? email)} already existed and was added to ${humanText(it.projectSlug)}. Identity: ${humanText(it.identityId)}`,
+				quiet: it => it.identityId,
+			},
+		)
+	}
+}
+
+const parseInviteMethod = (value: string | undefined): InviteMethod | undefined => {
+	if (value === undefined) {
+		return undefined
+	}
+	const method = inviteMethods.find(it => it === value.toUpperCase())
+	if (method === undefined) {
+		throw new CliError(`Option --method must be one of ${inviteMethods.join(', ')}, got "${value}".`, {
+			code: 'INVALID_INPUT',
+			exitCode: ExitCode.InputError,
+		})
+	}
+	return method
+}

package/src/commands/tenant/member/TenantMemberInviteUnmanagedCommand.ts

@@ -0,0 +1,135 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { formatMemberships, requireOptionValue } from './memberOptions.js'
+import { configureMembershipOptions, MembershipOptions, readMembershipInputSource, resolveNonEmptyMemberships } from './membershipInput.js'
+import { readStdinText, StdinReader } from '../../../lib/tenant/stdin.js'
+import { environmentInput, literalInput, resolveRequiredTenantInput, stdinInput, type TenantInputSource } from '../../../lib/tenant/input/index.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {}
+
+type Options = MembershipOptions & {
+	project?: string
+	email?: string
+	password?: string
+	['password-env']?: string
+	['password-stdin']?: boolean
+	['reset-token-hash']?: string
+	['reset-token-hash-env']?: string
+	['reset-token-hash-stdin']?: boolean
+}
+
+/**
+ * `tenant member invite-unmanaged`
+ *
+ * The no-mail half of the invite pair — the caller sets the credential itself. Kept apart from
+ * `tenant member invite` because the option sets are disjoint and this one handles a secret.
+ *
+ * The password is never a positional argument. `--password-env` is the safe form: only the variable name
+ * reaches the shell history and the process list.
+ *
+ * `unmanagedInvite` accepts a `name` in the schema but its resolver ignores it, so no `--name` is offered.
+ */
+export class TenantMemberInviteUnmanagedCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdin: StdinReader = readStdinText,
+		private readonly env: NodeJS.ProcessEnv = process.env,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Invite a person to a project without sending any e-mail')
+		configuration.option('project').valueRequired().required().description('Project slug.')
+		configuration.option('email').valueRequired().required().description('E-mail address of the invited person.')
+		configuration.option('password-env').valueRequired().description(
+			'Name of the environment variable holding the initial password. Preferred over --password.',
+		)
+		configuration.option('password').valueRequired().description(
+			'Initial password. Visible in the shell history and in the process list — prefer --password-env.',
+		)
+		configuration.option('password-stdin').valueNone().description('Read the initial password from stdin.')
+		configuration.option('reset-token-hash').valueRequired().description('Hex encoded sha256 of a password reset token to store for the person.')
+		configuration.option('reset-token-hash-env').valueRequired().description('Read the password reset token hash from the named environment variable.')
+		configuration.option('reset-token-hash-stdin').valueNone().description('Read the password reset token hash from stdin.')
+		configureMembershipOptions(configuration)
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const projectSlug = requireOptionValue(input.getOption('project'), 'project')
+		const email = requireOptionValue(input.getOption('email'), 'email')
+		const passwordFromStdin = input.getOption('password-stdin') === true
+		const resetTokenHashFromStdin = input.getOption('reset-token-hash-stdin') === true
+		if (input.getOption('memberships-stdin') === true && (passwordFromStdin || resetTokenHashFromStdin)) {
+			throw new CliError('Only one value can consume stdin. Combine --memberships-stdin with an environment-backed credential instead.', {
+				code: 'AMBIGUOUS_STDIN_INPUT',
+				exitCode: ExitCode.InputError,
+			})
+		}
+		const memberships = await resolveNonEmptyMemberships(readMembershipInputSource(input), this.readStdin)
+		const credentialSources: TenantInputSource<'password' | 'reset-token-hash'>[] = []
+		const password = input.getOption('password')
+		const passwordEnv = input.getOption('password-env')
+		const resetTokenHash = input.getOption('reset-token-hash')
+		const resetTokenHashEnv = input.getOption('reset-token-hash-env')
+		if (password !== undefined) {
+			credentialSources.push(literalInput('password', '--password', password))
+		}
+		if (passwordEnv !== undefined) {
+			credentialSources.push(environmentInput('password', '--password-env', passwordEnv))
+		}
+		if (passwordFromStdin) {
+			credentialSources.push(stdinInput('password', '--password-stdin'))
+		}
+		if (resetTokenHash !== undefined) {
+			credentialSources.push(literalInput('reset-token-hash', '--reset-token-hash', resetTokenHash))
+		}
+		if (resetTokenHashEnv !== undefined) {
+			credentialSources.push(environmentInput('reset-token-hash', '--reset-token-hash-env', resetTokenHashEnv))
+		}
+		if (resetTokenHashFromStdin) {
+			credentialSources.push(stdinInput('reset-token-hash', '--reset-token-hash-stdin'))
+		}
+		const credential = await resolveRequiredTenantInput(credentialSources, { label: 'unmanaged invite credential' }, {
+			readStdin: this.readStdin,
+			readEnvironment: name => this.env[name],
+		})
+		const credentialValue = credential.kind === 'stdin' ? removeOneTrailingLineEnding(credential.value) : credential.value
+		if (credentialValue === '') {
+			throw new CliError('The selected unmanaged invite credential source resolved to an empty value.', {
+				code: 'EMPTY_INPUT_VALUE',
+				exitCode: ExitCode.InputError,
+			})
+		}
+		if (credential.name === 'reset-token-hash' && !/^[0-9a-f]{64}$/.test(credentialValue)) {
+			throw new CliError('The password reset token hash must be a 64-character hexadecimal SHA-256 hash.', {
+				code: 'INVALID_RESET_TOKEN_HASH',
+				exitCode: ExitCode.InputError,
+			})
+		}
+
+		output.info(`Creating an unmanaged membership for ${email} in project ${projectSlug} as ${formatMemberships(memberships)}`)
+		const result = await this.tenantClientProvider.member().unmanagedInvite({
+			projectSlug,
+			email,
+			memberships,
+			options: credential.name === 'password'
+				? { password: credentialValue }
+				: { resetTokenHash: credentialValue },
+		})
+
+		output.data(
+			{ projectSlug, ...result },
+			{
+				human: it =>
+					it.isNew
+						? `Created ${humanText(it.email ?? email)} in ${humanText(it.projectSlug)}. Identity: ${humanText(it.identityId)}`
+						: `${humanText(it.email ?? email)} already existed and was added to ${humanText(it.projectSlug)}. Identity: ${humanText(it.identityId)}`,
+				quiet: it => it.identityId,
+			},
+		)
+	}
+}
+
+const removeOneTrailingLineEnding = (value: string): string => value.replace(/(?:\r\n|\n)$/, '')

package/src/commands/tenant/member/TenantMemberListCommand.ts

@@ -0,0 +1,94 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import type { MemberType } from '@contember/graphql-client-tenant'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import type { TenantProjectMember } from '../../../lib/tenant/clients/index.js'
+import { parsePaginationLimit, parsePaginationOffset } from '../../../lib/tenant/input/pagination.js'
+import { formatMemberships, requireOptionValue } from './memberOptions.js'
+
+type Args = {}
+
+type Options = {
+	project?: string
+	identity?: string[]
+	email?: string[]
+	person?: string[]
+	type?: string
+	limit?: string
+	offset?: string
+}
+
+const memberTypes: MemberType[] = ['PERSON', 'API_KEY']
+
+/** `tenant member list` */
+export class TenantMemberListCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('List the members of a project with their memberships')
+		configuration.option('project').valueRequired().required().description('Project slug.')
+		configuration.option('identity').valueArray().description('Filter by identity id. Repeat for several ids.')
+		configuration.option('email').valueArray().description('Filter by e-mail. Repeat for several addresses.')
+		configuration.option('person').valueArray().description('Filter by person id. Repeat for several ids.')
+		configuration.option('type').valueRequired().description(`Filter by member type: ${memberTypes.join(' or ')}.`)
+		configuration.option('limit').valueRequired().description('Maximum number of members to return.')
+		configuration.option('offset').valueRequired().description('Number of members to skip.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const projectSlug = requireOptionValue(input.getOption('project'), 'project')
+		const email = input.getOption('email')
+		const personId = input.getOption('person')
+		const memberType = parseMemberType(input.getOption('type'))
+		if (memberType === 'API_KEY' && (email !== undefined || personId !== undefined)) {
+			throw new CliError('Options --email and --person cannot be combined with --type API_KEY.', {
+				code: 'INVALID_MEMBER_FILTER',
+				exitCode: ExitCode.InputError,
+			})
+		}
+		const members = await this.tenantClientProvider.member().listProjectMembers(projectSlug, {
+			filter: {
+				identityId: input.getOption('identity'),
+				email,
+				personId,
+				memberType,
+			},
+			limit: parsePaginationLimit(input.getOption('limit')),
+			offset: parsePaginationOffset(input.getOption('offset')),
+		})
+
+		output.table<TenantProjectMember>(
+			[
+				{ field: 'identityId', name: 'Identity' },
+				{ field: 'email', name: 'E-mail' },
+				{ field: 'name', name: 'Name' },
+				{ field: 'description', name: 'Description' },
+				{ field: 'memberships', name: 'Memberships', format: formatMemberships },
+			],
+			members,
+			'identityId',
+		)
+
+		if (members.length === 0) {
+			// the tenant API returns an empty list instead of an error when the token may not see members
+			output.info(`No members found in project ${projectSlug}. The token may also lack the "project.view members" permission.`)
+		}
+	}
+}
+
+const parseMemberType = (value: string | undefined): MemberType | undefined => {
+	if (value === undefined) {
+		return undefined
+	}
+	const memberType = memberTypes.find(it => it === value.toUpperCase())
+	if (memberType === undefined) {
+		throw new CliError(`Option --type must be one of ${memberTypes.join(', ')}, got "${value}".`, {
+			code: 'INVALID_INPUT',
+			exitCode: ExitCode.InputError,
+		})
+	}
+	return memberType
+}

package/src/commands/tenant/member/TenantMemberRemoveCommand.ts

@@ -0,0 +1,48 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { requireConfirmation } from '../../../lib/tenant/confirmation.js'
+import { humanText } from '../tenantOutput.js'
+import { requireOptionValue } from './memberOptions.js'
+
+type Args = {}
+
+type Options = {
+	project?: string
+	identity?: string
+	yes?: boolean
+}
+
+/** `tenant member remove` */
+export class TenantMemberRemoveCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Remove an identity from a project')
+		configuration.option('project').valueRequired().required().description('Project slug.')
+		configuration.option('identity').valueRequired().required().description('Identity id of the member to remove.')
+		configuration.option('yes').valueNone().description('Do not ask for confirmation.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<number | void> {
+		const projectSlug = requireOptionValue(input.getOption('project'), 'project')
+		const identityId = requireOptionValue(input.getOption('identity'), 'identity')
+
+		await requireConfirmation({
+			yes: input.getOption('yes') === true,
+			output,
+			warning: `Identity ${identityId} will lose all its memberships in project ${projectSlug}.`,
+		})
+
+		output.info(`Removing identity ${identityId} from project ${projectSlug}`)
+		await this.tenantClientProvider.member().removeProjectMember(projectSlug, identityId)
+
+		output.data(
+			{ projectSlug, identityId, removed: true },
+			{ human: it => `Identity ${humanText(it.identityId)} was removed from ${humanText(it.projectSlug)}.`, quiet: it => it.identityId },
+		)
+	}
+}

package/src/commands/tenant/member/TenantMemberUpdateCommand.ts

@@ -0,0 +1,58 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { formatMemberships, requireOptionValue } from './memberOptions.js'
+import { configureMembershipOptions, MembershipOptions, readMembershipInputSource, resolveMemberships } from './membershipInput.js'
+import { readStdinText, StdinReader } from '../../../lib/tenant/stdin.js'
+import { requireConfirmation } from '../../../lib/tenant/confirmation.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {}
+
+type Options = MembershipOptions & {
+	project?: string
+	identity?: string
+	yes?: boolean
+}
+
+/** `tenant member update` */
+export class TenantMemberUpdateCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdin: StdinReader = readStdinText,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Replace the memberships of an existing project member')
+		configuration.option('project').valueRequired().required().description('Project slug.')
+		configuration.option('identity').valueRequired().required().description('Identity id of the member.')
+		configuration.option('yes').valueNone().description('Confirm replacing the membership list with an empty list.')
+		configureMembershipOptions(configuration)
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const projectSlug = requireOptionValue(input.getOption('project'), 'project')
+		const identityId = requireOptionValue(input.getOption('identity'), 'identity')
+		const memberships = await resolveMemberships(readMembershipInputSource(input), this.readStdin)
+		if (memberships.length === 0) {
+			await requireConfirmation({
+				yes: input.getOption('yes') === true,
+				output,
+				warning: `This will remove every membership of identity ${identityId} in project ${projectSlug}.`,
+			})
+		}
+
+		// the mutation replaces the whole list, so anything the caller omits is dropped
+		output.info(`Replacing the memberships of identity ${identityId} in project ${projectSlug} with ${formatMemberships(memberships)}`)
+		await this.tenantClientProvider.member().updateProjectMember(projectSlug, identityId, memberships)
+
+		output.data(
+			{ projectSlug, identityId, memberships },
+			{
+				human: it => `Identity ${humanText(it.identityId)} in ${humanText(it.projectSlug)} now has: ${formatMemberships(it.memberships)}`,
+				quiet: it => it.identityId,
+			},
+		)
+	}
+}

package/src/commands/tenant/member/index.ts

@@ -0,0 +1,9 @@
+// Commands of `tenant member`. Add one file per command here and re-export it below.
+// `membershipInput.ts` and `memberOptions.ts` stay unexported on purpose: the five tenant barrels merge
+// into `commands/tenant/index.ts`. Other domains taking `memberships` import them by path.
+export * from './TenantMemberAddCommand.js'
+export * from './TenantMemberInviteCommand.js'
+export * from './TenantMemberInviteUnmanagedCommand.js'
+export * from './TenantMemberListCommand.js'
+export * from './TenantMemberRemoveCommand.js'
+export * from './TenantMemberUpdateCommand.js'

package/src/commands/tenant/member/memberOptions.ts

@@ -0,0 +1,29 @@
+import { CliError, ExitCode } from '@contember/cli-common'
+import { humanText } from '../tenantOutput.js'
+
+/**
+ * Reads an option the parser already enforces as required. The parser guarantees presence, not a
+ * non-empty value, and the option type stays optional — this keeps the command free of a cast.
+ */
+export const requireOptionValue = (value: string | undefined, name: string): string => {
+	if (value === undefined || value === '') {
+		throw new CliError(`Option --${name} is required and must not be empty.`, { code: 'INVALID_INPUT', exitCode: ExitCode.InputError })
+	}
+	return value
+}
+
+/** Both the fetched `TenantMembership` and the `MembershipInput` sent to the API, which differ only in readonly-ness. */
+export interface MembershipLike {
+	readonly role: string
+	readonly variables: readonly { readonly name: string; readonly values: readonly string[] }[]
+}
+
+/** Human-mode rendering of a membership list. `--json` and `--quiet` always see the raw structure. */
+export const formatMemberships = (memberships: readonly MembershipLike[]): string =>
+	memberships
+		.map(it =>
+			it.variables.length === 0
+				? humanText(it.role)
+				: `${humanText(it.role)} (${it.variables.map(v => `${humanText(v.name)}: ${v.values.map(humanText).join(', ')}`).join('; ')})`
+		)
+		.join(', ')

package/src/commands/tenant/member/membershipInput.ts

@@ -0,0 +1,155 @@
+import { CliError, CommandConfiguration, ExitCode } from '@contember/cli-common'
+import type { MembershipInput } from '@contember/graphql-client-tenant'
+import type { StdinReader } from '../../../lib/tenant/stdin.js'
+
+/** `Arguments` is not part of the `@contember/cli-common` public surface, so the widest form is spelled out here. */
+type AnyArguments = Record<string, string | string[] | undefined>
+
+/**
+ * The options every command taking `memberships: [MembershipInput!]!` declares.
+ *
+ * There are deliberately exactly two ways in, and no third one:
+ *
+ * - `--role <role>`, repeatable — a membership with no variables, which is the whole shape a human
+ *   needs for `--role editor`;
+ * - `--memberships <json>` / `--memberships-stdin` — the complete `MembershipInput[]` structure, which is
+ *   what a script or an agent already holds.
+ *
+ * A compact string syntax for variables (`editor:locale=en,cs`) is intentionally not offered: it breaks
+ * the moment a value contains the separator, and the JSON form costs an agent nothing.
+ */
+export type MembershipOptions = {
+	role?: string[]
+	memberships?: string
+	['memberships-stdin']?: boolean
+}
+
+export const MEMBERSHIPS_JSON_EXAMPLE = '[{"role":"editor","variables":[{"name":"locale","values":["cs","en"]}]}]'
+
+/** `roleDescription` exists for `tenant api-key create`, where `--role` also names a global tenant role. */
+export const configureMembershipOptions = (
+	configuration: CommandConfiguration<AnyArguments, MembershipOptions>,
+	{ roleDescription = 'Membership role without variables. Repeat for several roles.' }: { roleDescription?: string } = {},
+): void => {
+	configuration.option('role').valueArray().description(roleDescription)
+	configuration.option('memberships').valueRequired().description(
+		`Memberships as JSON, e.g. '${MEMBERSHIPS_JSON_EXAMPLE}'. Not combinable with --role.`,
+	)
+	configuration.option('memberships-stdin').valueNone().description('Read the memberships JSON from stdin instead of --memberships.')
+}
+
+/** The raw values of {@link MembershipOptions}, read by the command so no generic `Input` has to be passed around. */
+export interface MembershipInputSource {
+	roles: string[] | undefined
+	json: string | undefined
+	fromStdin: boolean
+}
+
+export const readMembershipInputSource = (input: {
+	getOption(name: 'role'): string[] | undefined
+	getOption(name: 'memberships'): string | undefined
+	getOption(name: 'memberships-stdin'): boolean | undefined
+}): MembershipInputSource => ({
+	roles: input.getOption('role'),
+	json: input.getOption('memberships'),
+	fromStdin: input.getOption('memberships-stdin') === true,
+})
+
+export const resolveMemberships = async (source: MembershipInputSource, readStdin: StdinReader): Promise<MembershipInput[]> => {
+	const roles = source.roles ?? []
+	const hasJson = source.json !== undefined
+	if (hasJson && source.fromStdin) {
+		throw membershipInputError('Pass the memberships either as --memberships or as --memberships-stdin, not both.')
+	}
+	if (roles.length > 0 && (hasJson || source.fromStdin)) {
+		throw membershipInputError('Pass the memberships either as --role or as JSON (--memberships / --memberships-stdin), not both.')
+	}
+	if (roles.length > 0) {
+		return roles.map(role => ({ role, variables: [] }))
+	}
+	if (hasJson) {
+		return parseMemberships(source.json ?? '', '--memberships')
+	}
+	if (source.fromStdin) {
+		return parseMemberships(await readStdin(), 'stdin')
+	}
+	throw membershipInputError(
+		`No memberships given. Pass --role <role> for a role without variables, or the full structure as --memberships '${MEMBERSHIPS_JSON_EXAMPLE}'.`,
+	)
+}
+
+/** Creation operations must not create an identity with no project access. */
+export const resolveNonEmptyMemberships = async (source: MembershipInputSource, readStdin: StdinReader): Promise<MembershipInput[]> => {
+	const memberships = await resolveMemberships(source, readStdin)
+	if (memberships.length === 0) {
+		throw membershipInputError('At least one membership is required for this operation.')
+	}
+	return memberships
+}
+
+const membershipInputError = (message: string, details?: unknown): CliError =>
+	new CliError(message, { code: 'INVALID_MEMBERSHIPS', exitCode: ExitCode.InputError, details })
+
+const parseMemberships = (json: string, origin: string): MembershipInput[] => {
+	if (json.trim() === '') {
+		throw membershipInputError(`Empty memberships JSON read from ${origin}.`)
+	}
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(json)
+	} catch (e) {
+		throw membershipInputError(`Memberships read from ${origin} are not valid JSON: ${e instanceof Error ? e.message : String(e)}`)
+	}
+	if (!Array.isArray(parsed)) {
+		throw membershipInputError(`Memberships read from ${origin} must be a JSON array, got ${describeJson(parsed)}.`)
+	}
+	return parsed.map((it, index) => parseMembership(it, `${origin}[${index}]`))
+}
+
+const parseMembership = (value: unknown, path: string): MembershipInput => {
+	const record = asRecord(value, path)
+	assertNoUnknownKeys(record, ['role', 'variables'], path)
+	const role = record.role
+	if (typeof role !== 'string' || role === '') {
+		throw membershipInputError(`${path}.role must be a non-empty string.`)
+	}
+	const variables = record.variables
+	if (variables === undefined || variables === null) {
+		return { role, variables: [] }
+	}
+	if (!Array.isArray(variables)) {
+		throw membershipInputError(`${path}.variables must be an array, got ${describeJson(variables)}.`)
+	}
+	return { role, variables: variables.map((it, index) => parseVariable(it, `${path}.variables[${index}]`)) }
+}
+
+const parseVariable = (value: unknown, path: string): { name: string; values: string[] } => {
+	const record = asRecord(value, path)
+	assertNoUnknownKeys(record, ['name', 'values'], path)
+	const name = record.name
+	if (typeof name !== 'string' || name === '') {
+		throw membershipInputError(`${path}.name must be a non-empty string.`)
+	}
+	const values = record.values
+	if (!Array.isArray(values) || values.some(it => typeof it !== 'string')) {
+		throw membershipInputError(`${path}.values must be an array of strings.`)
+	}
+	return { name, values: values.filter(it => typeof it === 'string') }
+}
+
+const asRecord = (value: unknown, path: string): Record<string, unknown> => {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+		throw membershipInputError(`${path} must be an object, got ${describeJson(value)}.`)
+	}
+	return { ...value }
+}
+
+// a typo'd key would otherwise be dropped without a word, which is the worst possible failure for a script
+const assertNoUnknownKeys = (record: Record<string, unknown>, known: string[], path: string): void => {
+	const unknown = Object.keys(record).filter(it => !known.includes(it))
+	if (unknown.length > 0) {
+		throw membershipInputError(`${path} has unknown ${unknown.length === 1 ? 'key' : 'keys'} ${unknown.join(', ')}. Allowed: ${known.join(', ')}.`)
+	}
+}
+
+const describeJson = (value: unknown): string => (value === null ? 'null' : Array.isArray(value) ? 'an array' : typeof value)

package/src/commands/tenant/person/TenantIdentityRoleAddCommand.ts

@@ -0,0 +1,44 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { humanText } from '../tenantOutput.js'
+
+type Args = {
+	identityId: string
+	role: string[]
+}
+
+type Options = {}
+
+interface IdentityRolesResult {
+	identityId: string
+	added: string[]
+	/** All global roles of the identity after the change, or null when the token may not read them. */
+	roles: string[] | null
+}
+
+export class TenantIdentityRoleAddCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Grant global (project-independent) roles to an identity.')
+		configuration.argument('identityId').description('Identity id, as listed by "tenant person list".')
+		configuration.argument('role').variadic().description('One or more global roles to grant.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const identityId = input.getArgument('identityId')
+		const added = input.getArgument('role')
+
+		const roles = await this.tenantClientProvider.person().addGlobalIdentityRoles(identityId, added)
+
+		output.info(`Granted ${added.join(', ')} to identity ${identityId}.`)
+		output.data<IdentityRolesResult>(
+			{ identityId, added, roles },
+			{ human: it => it.roles === null ? humanText(it.identityId) : it.roles.map(humanText).join(', '), quiet: it => it.identityId },
+		)
+	}
+}