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

package/src/commands/tenant/policy/policyInput.ts

@@ -0,0 +1,210 @@
+import { CliError, ExitCode } from '@contember/cli-common'
+import type { AuthPolicyInput, AuthPolicyScope, MailType } from '@contember/graphql-client-tenant'
+import { readStdinText, type StdinReader } from '../../../lib/tenant/stdin.js'
+import { literalInput, resolveRequiredTenantInput, stdinInput, type TenantInputSource } from '../../../lib/tenant/input/index.js'
+import { humanText } from '../tenantOutput.js'
+
+/**
+ * Structured input (an `AuthPolicyInput`, a mail template body) is taken verbatim as text, either inline
+ * or from stdin, instead of being reassembled from a flag-per-field mini-syntax. Stdin needs its own
+ * boolean flag: a bare `-` sentinel is impossible, `InputParser.tryParseValue` treats any value starting
+ * with a dash as the next flag. Same shape as `member/membershipInput.ts`.
+ */
+export interface TextInputSources {
+	/** What is being read, used in the error messages, e.g. `policy`. */
+	label: string
+	/** The value passed inline, e.g. `--policy '{"scope":"global","roles":[]}'`. */
+	inline: string | undefined
+	inlineFlag: string
+	fromStdin: boolean
+	stdinFlag: string
+	/** Whether an explicitly selected empty value is meaningful. */
+	allowEmpty?: boolean
+}
+
+/** Resolves the value from exactly one of: the inline flag or stdin. */
+export const readTextInput = async (sources: TextInputSources, readStdin: StdinReader = readStdinText): Promise<string> => {
+	const selected: TenantInputSource<'value'>[] = []
+	if (sources.inline !== undefined) {
+		selected.push(literalInput('value', sources.inlineFlag, sources.inline))
+	}
+	if (sources.fromStdin) {
+		selected.push(stdinInput('value', sources.stdinFlag))
+	}
+	const resolved = await resolveRequiredTenantInput(selected, {
+		label: sources.label,
+		allowEmpty: sources.allowEmpty,
+		trailingLineEnding: 'preserve',
+	}, { readStdin })
+	return resolved.value
+}
+
+export const AUTH_POLICY_JSON_EXAMPLE = '{"scope":"project","project":"blog","roles":["admin"],"mfaRequired":true,"idleTimeout":"PT30M"}'
+
+const authPolicyScopes = {
+	global: 'global',
+	project: 'project',
+} satisfies Record<AuthPolicyScope, AuthPolicyScope>
+
+// `satisfies` keeps this exhaustive: a MailType added to the schema breaks the build here instead of
+// silently going unsupported.
+const mailTypes = {
+	EXISTING_USER_INVITED: 'EXISTING_USER_INVITED',
+	NEW_USER_INVITED: 'NEW_USER_INVITED',
+	RESET_PASSWORD_REQUEST: 'RESET_PASSWORD_REQUEST',
+	PASSWORDLESS_SIGN_IN: 'PASSWORDLESS_SIGN_IN',
+	FORCED_SIGN_OUT: 'FORCED_SIGN_OUT',
+	EMAIL_OTP: 'EMAIL_OTP',
+	BACKUP_CODES_EXHAUSTED: 'BACKUP_CODES_EXHAUSTED',
+	EMAIL_VERIFICATION: 'EMAIL_VERIFICATION',
+	EMAIL_CHANGE_VERIFY: 'EMAIL_CHANGE_VERIFY',
+	EMAIL_CHANGE_NOTIFY: 'EMAIL_CHANGE_NOTIFY',
+	UNUSUAL_LOGIN: 'UNUSUAL_LOGIN',
+} satisfies Record<MailType, MailType>
+
+export const mailTypeValues: MailType[] = Object.values(mailTypes)
+
+/** What identifies a mail template — it has no id, only this triple. Emitted as the result of add/remove. */
+export interface MailTemplateRef {
+	projectSlug: string | null
+	type: MailType
+	variant: string | null
+}
+
+export const describeMailTemplate = (ref: MailTemplateRef): string =>
+	[
+		ref.projectSlug === null ? 'global' : `project ${humanText(ref.projectSlug)}`,
+		humanText(ref.type),
+		ref.variant === null ? null : `variant ${humanText(ref.variant)}`,
+	]
+		.filter(it => it !== null)
+		.join(', ')
+
+/** Stable scalar form for quiet output. */
+export const formatMailTemplateRef = (ref: MailTemplateRef): string => `${ref.projectSlug ?? 'global'}:${ref.type}:${ref.variant ?? 'default'}`
+
+/** Omitted selects the default scope/variant; an explicitly empty selector is almost certainly a shell mistake. */
+export const parseOptionalMailTemplateSelector = (value: string | undefined, flag: '--project' | '--variant'): string | undefined => {
+	if (value === '') {
+		throw inputError(`${flag} must not be empty. Omit it to select the default.`, 'EMPTY_MAIL_TEMPLATE_SELECTOR')
+	}
+	return value
+}
+
+/** Case-insensitive, so `reset_password_request` works as well as the schema's `RESET_PASSWORD_REQUEST`. */
+export const parseMailType = (value: string): MailType => {
+	const normalized = value.toUpperCase()
+	const found = mailTypeValues.find(it => it === normalized)
+	if (found === undefined) {
+		throw inputError(`Unknown mail type "${value}". Expected one of: ${mailTypeValues.join(', ')}.`, 'UNKNOWN_MAIL_TYPE')
+	}
+	return found
+}
+
+const authPolicyFields = [
+	'scope',
+	'project',
+	'roles',
+	'mfaRequired',
+	'tokenExpiration',
+	'idleTimeout',
+	'mfaGraceDuration',
+	'rememberMeAllowed',
+]
+
+/** Parses the `AuthPolicyInput` JSON document. Unknown keys are rejected so a typo is not silently dropped. */
+export const parseAuthPolicyInput = (raw: string): AuthPolicyInput => {
+	const record = asRecord(parseJson(raw))
+	if (record === null) {
+		throw inputError('The policy must be a JSON object.', 'INVALID_POLICY')
+	}
+	const unknownFields = Object.keys(record).filter(it => !authPolicyFields.includes(it))
+	if (unknownFields.length > 0) {
+		throw inputError(`Unknown policy field(s): ${unknownFields.join(', ')}. Expected: ${authPolicyFields.join(', ')}.`, 'INVALID_POLICY')
+	}
+	const scope = readEnum(record.scope, Object.values(authPolicyScopes), 'scope')
+	const project = readOptionalString(record.project, 'project')
+	if (scope === 'project' && project === undefined) {
+		throw inputError('A project-scoped policy needs "project" (the project slug).', 'INVALID_POLICY')
+	}
+	if (scope === 'global' && project !== undefined) {
+		throw inputError('A global policy must not carry "project".', 'INVALID_POLICY')
+	}
+	return {
+		scope,
+		project,
+		roles: readStringArray(record.roles, 'roles'),
+		mfaRequired: readOptionalBoolean(record.mfaRequired, 'mfaRequired'),
+		tokenExpiration: readOptionalString(record.tokenExpiration, 'tokenExpiration'),
+		idleTimeout: readOptionalString(record.idleTimeout, 'idleTimeout'),
+		mfaGraceDuration: readOptionalString(record.mfaGraceDuration, 'mfaGraceDuration'),
+		rememberMeAllowed: readOptionalBoolean(record.rememberMeAllowed, 'rememberMeAllowed'),
+	}
+}
+
+export const inputError = (message: string, code: string): CliError => new CliError(message, { code, exitCode: ExitCode.InputError })
+
+const parseJson = (raw: string): unknown => {
+	try {
+		return JSON.parse(raw)
+	} catch {
+		throw new CliError('Cannot parse the policy as JSON.', {
+			code: 'INVALID_JSON',
+			exitCode: ExitCode.InputError,
+		})
+	}
+}
+
+/** Copies a plain JSON object into an indexable record — no cast, so every value stays `unknown`. */
+const asRecord = (value: unknown): Record<string, unknown> | null => {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+		return null
+	}
+	const result: Record<string, unknown> = {}
+	for (const [key, item] of Object.entries(value)) {
+		result[key] = item
+	}
+	return result
+}
+
+const readEnum = <T extends string>(value: unknown, allowed: T[], field: string): T => {
+	const found = allowed.find(it => it === value)
+	if (found === undefined) {
+		throw inputError(`"${field}" must be one of: ${allowed.join(', ')}.`, 'INVALID_POLICY')
+	}
+	return found
+}
+
+const readOptionalString = (value: unknown, field: string): string | undefined => {
+	if (value === undefined || value === null) {
+		return undefined
+	}
+	if (typeof value !== 'string') {
+		throw inputError(`"${field}" must be a string.`, 'INVALID_POLICY')
+	}
+	return value
+}
+
+const readOptionalBoolean = (value: unknown, field: string): boolean | undefined => {
+	if (value === undefined || value === null) {
+		return undefined
+	}
+	if (typeof value !== 'boolean') {
+		throw inputError(`"${field}" must be a boolean.`, 'INVALID_POLICY')
+	}
+	return value
+}
+
+const readStringArray = (value: unknown, field: string): string[] => {
+	if (!Array.isArray(value)) {
+		throw inputError(`"${field}" must be an array of strings.`, 'INVALID_POLICY')
+	}
+	const result: string[] = []
+	for (const item of value) {
+		if (typeof item !== 'string') {
+			throw inputError(`"${field}" must be an array of strings.`, 'INVALID_POLICY')
+		}
+		result.push(item)
+	}
+	return result
+}

package/src/commands/tenant/project/TenantConfigShowCommand.ts

@@ -0,0 +1,28 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+
+type Args = {}
+type Options = {}
+
+export class TenantConfigShowCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Show the tenant-wide configuration (signup, password policy, login, captcha, rate limits)')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		if (output.isQuiet) {
+			throw new CliError('Quiet output is not supported for tenant configuration.', {
+				code: 'QUIET_OUTPUT_UNSUPPORTED',
+				exitCode: ExitCode.InputError,
+			})
+		}
+		const config = await this.tenantClientProvider.project().configuration()
+		output.data(config)
+	}
+}

package/src/commands/tenant/project/TenantIdpListCommand.ts

@@ -0,0 +1,27 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { RemoteIdentityProvider } from '../../../lib/tenant/clients/TenantProjectClient.js'
+
+type Args = {}
+type Options = {}
+
+export class TenantIdpListCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('List configured identity providers')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const idps = await this.tenantClientProvider.project().listIdentityProviders()
+		output.table<RemoteIdentityProvider>(
+			[{ field: 'slug', name: 'Slug' }, { field: 'type', name: 'Type' }, { field: 'disabledAt', name: 'Disabled At' }],
+			idps,
+			'slug',
+		)
+	}
+}

package/src/commands/tenant/project/TenantProjectCreateCommand.ts

@@ -0,0 +1,67 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { resolveJsonConfigOption } from './jsonConfigOption.js'
+import { readStdinText, type StdinReader } from '../../../lib/tenant/stdin.js'
+import { assertGeneratedTenantToken, assertTenantCredentialContract, humanText, requireNonEmptyTenantName } from '../tenantOutput.js'
+
+type Args = {
+	slug: string
+}
+type Options = {
+	name?: string
+	config?: string
+	['config-stdin']?: boolean
+	['if-not-exists']?: boolean
+	['no-deploy-token']?: boolean
+}
+
+export class TenantProjectCreateCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdinFn: StdinReader = readStdinText,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Create a project')
+		configuration.argument('slug').description('Project slug')
+		configuration.option('name').valueRequired().description('Project display name (defaults to the slug on the server)')
+		configuration.option('config').valueRequired().description('Initial config as inline JSON')
+		configuration.option('config-stdin').valueNone().description('Read the initial config as JSON from stdin, instead of --config')
+		configuration.option('if-not-exists').valueNone().description('Do not fail if the project already exists')
+		configuration.option('no-deploy-token').valueNone().description('Skip issuing a deploy API key for the project')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const slug = input.getArgument('slug')
+		const name = requireNonEmptyTenantName(input.getOption('name'), 'Project')
+		const config = await resolveJsonConfigOption(input.getOption('config'), input.getOption('config-stdin') === true, this.readStdinFn)
+		const ifNotExists = input.getOption('if-not-exists') === true
+		const noDeployToken = input.getOption('no-deploy-token') === true
+
+		const result = await this.tenantClientProvider.project().createProject(slug, ifNotExists, { name, config, noDeployToken })
+		const created = result !== null
+		const data = { slug, created, deployerApiKey: result?.deployerApiKey ?? null }
+		if (result !== null) {
+			assertTenantCredentialContract(
+				noDeployToken ? result.deployerApiKey === null : result.deployerApiKey?.token !== null && result.deployerApiKey?.token !== undefined,
+				'deployer',
+			)
+		}
+		const generatedToken = data.deployerApiKey?.token === null || data.deployerApiKey?.token === undefined
+			? null
+			: assertGeneratedTenantToken(data.deployerApiKey.token, 'deployer')
+		if (data.deployerApiKey?.token !== null && data.deployerApiKey?.token !== undefined) {
+			output.warn('The deployer token is shown exactly once and cannot be retrieved again. Store it now.')
+		}
+		output.data(data, {
+			human: it => {
+				const safeSlug = humanText(it.slug)
+				const status = it.created ? `Project "${safeSlug}" created.` : `Project "${safeSlug}" already exists.`
+				return generatedToken === null ? status : `${status}\nDeployer token: ${generatedToken}`
+			},
+			quiet: it => generatedToken ?? it.slug,
+		})
+	}
+}

package/src/commands/tenant/project/TenantProjectListCommand.ts

@@ -0,0 +1,27 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { TenantProjectSummary } from '../../../lib/tenant/clients/TenantProjectClient.js'
+
+type Args = {}
+type Options = {}
+
+export class TenantProjectListCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('List projects on the tenant')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const projects = await this.tenantClientProvider.project().listProjects()
+		output.table<TenantProjectSummary>(
+			[{ field: 'id', name: 'ID' }, { field: 'name', name: 'Name' }, { field: 'slug', name: 'Slug' }],
+			projects,
+			'slug',
+		)
+	}
+}

package/src/commands/tenant/project/TenantProjectSecretSetCommand.ts

@@ -0,0 +1,63 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { readStdinText, type 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 = {
+	slug: string
+	key: string
+}
+type Options = {
+	value?: string
+	['value-env']?: string
+	['value-stdin']?: boolean
+}
+
+export class TenantProjectSecretSetCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdinFn: StdinReader = readStdinText,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Set a project secret from exactly one explicit input source')
+		configuration.argument('slug').description('Project slug')
+		configuration.argument('key').description('Secret key')
+		configuration.option('value').valueRequired().description(
+			'Secret value as a literal argument. The value is visible in shell history and process listings.',
+		)
+		configuration.option('value-env').valueRequired().description('Read the secret value from the named environment variable without modifying it.')
+		configuration.option('value-stdin').valueNone().description('Read the secret value from stdin. Removes exactly one trailing LF or CRLF.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const slug = input.getArgument('slug')
+		const key = input.getArgument('key')
+		const sources: TenantInputSource<'secret'>[] = []
+		const literalValue = input.getOption('value')
+		const environmentVariable = input.getOption('value-env')
+		if (literalValue !== undefined) {
+			sources.push(literalInput('secret', '--value', literalValue))
+		}
+		if (environmentVariable !== undefined) {
+			sources.push(environmentInput('secret', '--value-env', environmentVariable))
+		}
+		if (input.getOption('value-stdin') === true) {
+			sources.push(stdinInput('secret', '--value-stdin'))
+		}
+
+		const source = await resolveRequiredTenantInput(sources, {
+			label: 'project secret',
+			trailingLineEnding: sources.length === 1 && sources[0]?.kind === 'stdin' ? 'remove-one' : 'preserve',
+		}, { readStdin: this.readStdinFn })
+
+		await this.tenantClientProvider.project().setProjectSecret(slug, key, source.value)
+		output.data({ slug, key }, {
+			human: it => `Secret "${humanText(it.key)}" set on project "${humanText(it.slug)}".`,
+			quiet: it => it.key,
+		})
+	}
+}

package/src/commands/tenant/project/TenantProjectShowCommand.ts

@@ -0,0 +1,29 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+
+type Args = {
+	slug: string
+}
+type Options = {}
+
+export class TenantProjectShowCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Show a project by slug')
+		configuration.argument('slug').description('Project slug')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const slug = input.getArgument('slug')
+		const project = await this.tenantClientProvider.project().getProjectBySlug(slug)
+		if (!project) {
+			throw new CliError(`Project "${slug}" not found.`, { code: 'PROJECT_NOT_FOUND', exitCode: ExitCode.NotFound })
+		}
+		output.data(project, { quiet: it => it.slug })
+	}
+}

package/src/commands/tenant/project/TenantProjectUpdateCommand.ts

@@ -0,0 +1,66 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+import { resolveJsonConfigOption } from './jsonConfigOption.js'
+import { readStdinText, type StdinReader } from '../../../lib/tenant/stdin.js'
+import { humanText, requireNonEmptyTenantName } from '../tenantOutput.js'
+
+type Args = {
+	slug: string
+}
+type Options = {
+	name?: string
+	config?: string
+	['config-stdin']?: boolean
+	['merge-config']?: boolean
+}
+
+export class TenantProjectUpdateCommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+		private readonly readStdinFn: StdinReader = readStdinText,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description(`Update a project's name and/or config`)
+		configuration.argument('slug').description('Project slug')
+		configuration.option('name').valueRequired().description('New display name')
+		configuration.option('config').valueRequired().description('New config as inline JSON — replaces the config unless --merge-config is set')
+		configuration.option('config-stdin').valueNone().description('Read the new config as JSON from stdin, instead of --config')
+		configuration.option('merge-config').valueNone().description('Merge the new config into the existing one instead of replacing it')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const slug = input.getArgument('slug')
+		const name = requireNonEmptyTenantName(input.getOption('name'), 'Project')
+		const configOption = input.getOption('config')
+		const configFromStdin = input.getOption('config-stdin') === true
+		const configProvided = configOption !== undefined || configFromStdin
+		const mergeConfig = input.getOption('merge-config') === true
+
+		if (mergeConfig && !configProvided) {
+			throw new CliError('--merge-config requires --config or --config-stdin.', {
+				code: 'MERGE_CONFIG_WITHOUT_CONFIG',
+				exitCode: ExitCode.InputError,
+			})
+		}
+		if (name === undefined && !configProvided) {
+			throw new CliError('Nothing to update: pass --name and/or --config.', { code: 'NO_UPDATE_FIELDS', exitCode: ExitCode.InputError })
+		}
+		const config = await resolveJsonConfigOption(configOption, configFromStdin, this.readStdinFn)
+
+		await this.tenantClientProvider.project().updateProject(slug, {
+			name,
+			config,
+			mergeConfig: configProvided ? mergeConfig : undefined,
+		})
+		output.data(
+			{ slug, name: name ?? null, config: config ?? null, mergeConfig: configProvided ? mergeConfig : null },
+			{
+				human: it => `Project "${humanText(it.slug)}" updated.`,
+				quiet: it => it.slug,
+			},
+		)
+	}
+}

package/src/commands/tenant/project/TenantWhoAmICommand.ts

@@ -0,0 +1,22 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { TenantClientProvider } from '../../../lib/TenantClientProvider.js'
+
+type Args = {}
+type Options = {}
+
+export class TenantWhoAmICommand extends Command<Args, Options> {
+	constructor(
+		private readonly tenantClientProvider: TenantClientProvider,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Show the identity, global roles and project access of the current API token')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		const me = await this.tenantClientProvider.project().whoAmI()
+		output.data(me, { quiet: it => it.id })
+	}
+}

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

@@ -0,0 +1,9 @@
+// Commands of `tenant project`. Add one file per command here and re-export it below.
+export * from './TenantProjectListCommand.js'
+export * from './TenantProjectShowCommand.js'
+export * from './TenantProjectCreateCommand.js'
+export * from './TenantProjectUpdateCommand.js'
+export * from './TenantProjectSecretSetCommand.js'
+export * from './TenantConfigShowCommand.js'
+export * from './TenantIdpListCommand.js'
+export * from './TenantWhoAmICommand.js'

package/src/commands/tenant/project/jsonConfigOption.ts

@@ -0,0 +1,33 @@
+import { CliError, ExitCode } from '@contember/cli-common'
+import { readStdinText, type StdinReader } from '../../../lib/tenant/stdin.js'
+
+/**
+ * Resolves a `--config` / `--config-stdin` option pair into a parsed JSON value. A bare `-` cannot be used
+ * as a stdin sentinel here — the parser treats any value starting with `-` as the start of the next flag
+ * (`InputParser.tryParseValue`) — so stdin gets its own boolean flag instead. `undefined` in (neither flag
+ * given), `undefined` out — lets callers tell "not provided" apart from "explicitly cleared".
+ */
+export const resolveJsonConfigOption = async (
+	value: string | undefined,
+	fromStdin: boolean,
+	readStdinFn: StdinReader = readStdinText,
+): Promise<unknown> => {
+	if (value !== undefined && fromStdin) {
+		throw new CliError('Pass either --config or --config-stdin, not both.', {
+			code: 'CONFIG_CONFLICTING_SOURCE',
+			exitCode: ExitCode.InputError,
+		})
+	}
+	if (value === undefined && !fromStdin) {
+		return undefined
+	}
+	const raw = value !== undefined ? value : await readStdinFn()
+	try {
+		return JSON.parse(raw)
+	} catch (e) {
+		throw new CliError(`Invalid JSON in --config: ${e instanceof Error ? e.message : String(e)}`, {
+			code: 'INVALID_CONFIG_JSON',
+			exitCode: ExitCode.InputError,
+		})
+	}
+}

package/src/commands/tenant/tenantOutput.ts

@@ -0,0 +1,35 @@
+import { CliError, escapeTerminalText, ExitCode } from '@contember/cli-common'
+
+/** Escapes an untrusted fragment before it is interpolated into human-readable stdout. */
+export const humanText = (value: string): string => escapeTerminalText(value)
+
+export const requireNonEmptyTenantName = (value: string | undefined, subject: 'Person' | 'Project'): string | undefined => {
+	if (value !== undefined && value.trim() === '') {
+		throw new CliError(`${subject} name must not be empty.`, {
+			code: 'EMPTY_NAME',
+			exitCode: ExitCode.InputError,
+		})
+	}
+	return value
+}
+
+export const assertTenantCredentialContract = (valid: boolean, kind: 'API key' | 'deployer' | 'session'): void => {
+	if (!valid) {
+		invalidTenantCredential(kind)
+	}
+}
+
+/** Generated tenant credentials are 20 random bytes encoded as lowercase hexadecimal. */
+export const assertGeneratedTenantToken = (token: string, kind: 'API key' | 'deployer' | 'session'): string => {
+	if (!/^[0-9a-f]{40}$/.test(token)) {
+		invalidTenantCredential(kind)
+	}
+	return token
+}
+
+const invalidTenantCredential = (kind: 'API key' | 'deployer' | 'session'): never => {
+	throw new CliError(`The tenant API returned an invalid ${kind} token.`, {
+		code: 'TENANT_API_INVALID_CREDENTIAL',
+		exitCode: ExitCode.InternalError,
+	})
+}