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

package/src/commands/migrations/MigrationDiffCommand.ts

@@ -1,11 +1,13 @@
-import { Command, CommandConfiguration, Input } from '@contember/cli-common'
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
 import { InvalidSchemaException } from '@contember/schema-migrations'
-import prompts from 'prompts'
-import { MigrationCreator, SchemaVersionBuilder } from '@contember/migrations-client'
-import { SchemaLoader } from '../../lib/schema/SchemaLoader'
-import { MigrationPrinter } from '../../lib/migrations/MigrationPrinter'
-import { MigrationExecutionFacade } from '../../lib/migrations/MigrationExecutionFacade'
-import { printValidationErrors } from '../../lib/schema/SchemaValidationPrinter'
+import { MigrationCreator, MigrationsResolver, SchemaStateManager, SchemaVersionBuilder } from '@contember/migrations-client'
+import { SchemaLoader } from '../../lib/schema/SchemaLoader.js'
+import { MigrationPrinter } from '../../lib/migrations/MigrationPrinter.js'
+import { MigrationExecutionFacade } from '../../lib/migrations/MigrationExecutionFacade.js'
+import { printValidationErrors } from '../../lib/schema/SchemaValidationPrinter.js'
+import { promptConfirm, promptSelect } from '../../lib/prompt/index.js'
+
+type MigrationExecutor = Pick<MigrationExecutionFacade, 'execute'>
 
 type Args = {
 	migrationName: string
@@ -15,6 +17,7 @@ type Options = {
 	execute?: true
 	yes?: true
 	'skip-initial-schema-validation'?: true
+	'recreate-views'?: true
 }
 
 export class MigrationDiffCommand extends Command<Args, Options> {
@@ -23,7 +26,9 @@ export class MigrationDiffCommand extends Command<Args, Options> {
 		private readonly schemaVersionBuilder: SchemaVersionBuilder,
 		private readonly migrationCreator: MigrationCreator,
 		private readonly migrationPrinter: MigrationPrinter,
-		private readonly migrationExecutorFacade: MigrationExecutionFacade,
+		private readonly migrationExecutorFacade: MigrationExecutor,
+		private readonly schemaStateManager: SchemaStateManager,
+		private readonly migrationsResolver: MigrationsResolver,
 	) {
 		super()
 	}
@@ -38,30 +43,95 @@ export class MigrationDiffCommand extends Command<Args, Options> {
 			.description('Do not ask for confirmation.')
 
 		configuration.option('skip-initial-schema-validation')
+		configuration //
+			.option('recreate-views')
+			.valueNone()
+			.description(
+				'Drop & recreate changed views instead of updating them in-place (CREATE OR REPLACE VIEW). Use when an in-place view update fails with SQLSTATE 42P16.',
+			)
 	}
 
-	protected async execute(input: Input<Args, Options>): Promise<void> {
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
 		const migrationName = input.getArgument('migrationName')
 		let shouldExecute = input.getOption('execute')
 		const yes = input.getOption('yes')
 		const skipInitialSchemaValidation = input.getOption('skip-initial-schema-validation') === true
+		const recreateViews = input.getOption('recreate-views') === true
 
 		const schema = await this.schemaLoader.loadSchema()
+		let stateMode = await this.schemaStateManager.isStateMode()
+		let initializeStateMode = false
+
+		// New project (no migrations yet) defaults to schema state mode. To opt out, create a migration first (e.g. `migrations blank`).
+		if (!stateMode && (await this.migrationsResolver.getSchemaMigrations()).length === 0) {
+			output.info('No migrations found — enabling schema state mode for this project.')
+			output.info('ACL, validation, actions and settings will be managed in the state/ directory instead of migrations.')
+			stateMode = true
+			initializeStateMode = true
+		}
+
 		try {
 			const initialSchema = await this.schemaVersionBuilder.buildSchema()
 			const result = await this.migrationCreator.prepareMigration(initialSchema, schema, migrationName, {
 				skipInitialSchemaValidation: skipInitialSchemaValidation,
+				skipNonModelDiffers: stateMode,
+				recreateViews,
 			})
+
+			const schemaState = stateMode ? SchemaStateManager.schemaStateFromSchema(schema) : undefined
+			const stateChanged = schemaState ? await this.schemaStateManager.writeState(schemaState, { dryRun: true }) : false
+
 			if (result === null) {
-				console.log('Nothing to do')
+				if (stateChanged) {
+					if (!yes) {
+						if (!output.canPrompt()) {
+							throw new CliError('TTY not available. Pass --yes to confirm the schema state update.', {
+								code: 'TTY_UNAVAILABLE',
+								exitCode: ExitCode.InputError,
+							})
+						}
+						const confirmed = await promptConfirm(output, {
+							message: 'Write the schema state changes?',
+							initial: false,
+						})
+						if (!confirmed) {
+							throw abortedError('Schema state update')
+						}
+					}
+					if (schemaState === undefined) {
+						throw new CliError('Schema state is unavailable', { code: 'SCHEMA_STATE_UNAVAILABLE', exitCode: ExitCode.InternalError })
+					}
+					if (initializeStateMode) {
+						await this.schemaStateManager.extractState(schema)
+					} else {
+						await this.schemaStateManager.writeState(schemaState)
+					}
+				} else {
+					output.info('Nothing to do')
+				}
+				if (stateChanged && shouldExecute) {
+					output.info('Syncing schema state to server...')
+					await this.migrationExecutorFacade.execute({
+						force: false,
+						requireConfirmation: false,
+					})
+				}
+				output.data(
+					{ migration: null, stateUpdated: stateChanged, executed: stateChanged && shouldExecute === true },
+					{ human: value => value.stateUpdated ? 'Schema state updated' : 'Nothing to do', quiet: value => value.stateUpdated },
+				)
 				return
 			}
 			this.migrationPrinter.printMigrationDescription(result.initialSchema, result.migration, { noSql: true })
 
 			if (!yes) {
-				const { action } = await prompts({
-					type: 'select',
-					name: 'action',
+				if (!output.canPrompt()) {
+					throw new CliError('TTY not available. Pass --yes to confirm execution.', {
+						code: 'TTY_UNAVAILABLE',
+						exitCode: ExitCode.InputError,
+					})
+				}
+				const action = await promptSelect(output, {
 					message: 'Do you want to continue?',
 					choices: [
 						{ value: 'yes', title: 'Yes' },
@@ -70,8 +140,7 @@ export class MigrationDiffCommand extends Command<Args, Options> {
 					],
 				})
 				if (!action || action === 'no') {
-					console.log('Aborting')
-					return
+					throw abortedError('Migration creation')
 				}
 				if (action === 'execute') {
 					shouldExecute = true
@@ -79,22 +148,49 @@ export class MigrationDiffCommand extends Command<Args, Options> {
 			}
 
 			const filename = await this.migrationCreator.saveMigration(result.migration)
+			if (stateChanged) {
+				if (schemaState === undefined) {
+					throw new CliError('Schema state is unavailable', { code: 'SCHEMA_STATE_UNAVAILABLE', exitCode: ExitCode.InternalError })
+				}
+				if (initializeStateMode) {
+					await this.schemaStateManager.extractState(schema)
+				} else {
+					await this.schemaStateManager.writeState(schemaState)
+				}
+			}
+			if (stateChanged) {
+				output.info('Schema state files updated')
+			}
 
-			console.log(`${filename} created`)
+			if (shouldExecute) {
+				await this.migrationExecutorFacade.execute({
+					force: false,
+					requireConfirmation: yes
+						? false
+						: migrations => migrations.some(migration => migration.name !== result.migration.name),
+				})
+			}
+			output.data(
+				{ migration: filename, stateUpdated: stateChanged, executed: shouldExecute === true },
+				{ human: value => `${value.migration} created`, quiet: value => value.migration },
+			)
 		} catch (e) {
 			if (e instanceof InvalidSchemaException) {
-				printValidationErrors(e.validationErrors, e.message)
-
-				return
+				printValidationErrors(e.validationErrors, e.message, output)
+				throw new CliError(e.message, {
+					code: 'SCHEMA_INVALID',
+					exitCode: ExitCode.InputError,
+					details: e.validationErrors,
+					cause: e,
+				})
 			}
 			throw e
 		}
-
-		if (shouldExecute) {
-			await this.migrationExecutorFacade.execute({
-				force: false,
-				requireConfirmation: migrations => migrations.length !== 1 && !yes,
-			})
-		}
 	}
 }
+
+const abortedError = (operation: string): CliError =>
+	new CliError(`${operation} aborted`, {
+		code: 'OPERATION_ABORTED',
+		exitCode: ExitCode.InputError,
+	})

package/src/commands/migrations/MigrationExecuteCommand.ts

@@ -1,5 +1,5 @@
-import { Command, CommandConfiguration, Input } from '@contember/cli-common'
-import { MigrationExecutionFacade } from '../../lib/migrations/MigrationExecutionFacade'
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { MigrationExecutionFacade } from '../../lib/migrations/MigrationExecutionFacade.js'
 
 type Args = {}
 
@@ -7,11 +7,14 @@ type Options = {
 	until?: string
 	force: boolean
 	yes?: boolean
+	['no-snapshot']?: boolean
 }
 
+type MigrationExecutor = Pick<MigrationExecutionFacade, 'execute'>
+
 export class MigrationExecuteCommand extends Command<Args, Options> {
 	constructor(
-		private readonly migrationExecutorFacade: MigrationExecutionFacade,
+		private readonly migrationExecutorFacade: MigrationExecutor,
 	) {
 		super()
 	}
@@ -23,20 +26,29 @@ export class MigrationExecuteCommand extends Command<Args, Options> {
 		configuration.option('until')
 			.valueRequired()
 			.description('Execute all migrations leading up to, and inclusive of, a specified migration')
+		configuration.option('no-snapshot')
+			.valueNone()
+			.description('Do not bootstrap a fresh database from snapshot.json; replay every migration instead')
 		configuration //
 			.option('yes')
 			.valueNone()
 			.description('Do not ask for confirmation.')
 	}
 
-	protected async execute(input: Input<Args, Options>): Promise<void> {
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
 		const force = input.getOption('force')
 		const until = input.getOption('until')
 
-		await this.migrationExecutorFacade.execute({
+		const changed = await this.migrationExecutorFacade.execute({
 			force,
 			until,
 			requireConfirmation: !input.getOption('yes'),
+			useSnapshot: input.getOption('no-snapshot') !== true,
+		})
+		const result = { status: changed ? 'completed' : 'noop', until: until ?? null }
+		output.data(result, {
+			human: value => value.status === 'completed' ? 'Migrations executed' : 'No migrations to execute',
+			quiet: value => value.status,
 		})
 	}
 }

package/src/commands/migrations/MigrationInitStateCommand.ts

@@ -0,0 +1,47 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { SchemaStateManager } from '@contember/migrations-client'
+import { SchemaLoader } from '../../lib/schema/SchemaLoader.js'
+
+type Args = {}
+
+type Options = {}
+
+type InitStateResult = {
+	enabled: true
+	changed: boolean
+}
+
+export class MigrationInitStateCommand extends Command<Args, Options> {
+	constructor(
+		private readonly schemaLoader: SchemaLoader,
+		private readonly schemaStateManager: SchemaStateManager,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Enables schema state mode by extracting ACL, validation, actions and settings into the state/ directory')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<number> {
+		if (await this.schemaStateManager.isStateMode()) {
+			output.info('Schema state mode is already enabled')
+			writeMachineResult(output, { enabled: true, changed: false })
+			return 0
+		}
+
+		const schema = await this.schemaLoader.loadSchema()
+		await this.schemaStateManager.extractState(schema)
+
+		output.info('Schema state mode enabled. ACL, validation, actions and settings are now managed in the state/ directory.')
+		output.info('These parts of the schema will no longer be written into migrations.')
+		writeMachineResult(output, { enabled: true, changed: true })
+		return 0
+	}
+}
+
+const writeMachineResult = (output: Output, result: InitStateResult): void => {
+	if (output.mode !== 'human') {
+		output.data(result, { quiet: value => value.changed })
+	}
+}

package/src/commands/migrations/MigrationRebaseCommand.ts

@@ -1,6 +1,9 @@
-import { Command, CommandConfiguration, Input } from '@contember/cli-common'
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
 import { Migration, MigrationsResolver } from '@contember/migrations-client'
-import { MigrationRebaseFacade } from '../../lib/migrations/MigrationRebaseFacade'
+import { MigrationRebaseFacade } from '../../lib/migrations/MigrationRebaseFacade.js'
+import { promptConfirm } from '../../lib/prompt/index.js'
+
+type MigrationRebaser = Pick<MigrationRebaseFacade, 'rebase'>
 
 type Args = {
 	migration: string[]
@@ -13,7 +16,7 @@ type Options = {
 export class MigrationRebaseCommand extends Command<Args, Options> {
 	constructor(
 		private readonly migrationsResolver: MigrationsResolver,
-		private readonly migrationRebaseFacade: MigrationRebaseFacade,
+		private readonly migrationRebaseFacade: MigrationRebaser,
 	) {
 		super()
 	}
@@ -27,20 +30,39 @@ export class MigrationRebaseCommand extends Command<Args, Options> {
 			.description('Do not ask for confirmation.')
 	}
 
-	protected async execute(input: Input<Args, Options>): Promise<void> {
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
 		const migrationNames = input.getArgument('migration')
 
 		const migrations: Migration[] = []
 		for (const migrationName of migrationNames) {
 			const migration = await this.migrationsResolver.findSchemaMigrationByVersion(migrationName)
 			if (!migration) {
-				throw `Migration ${migrationName} not found`
+				throw new CliError(`Migration ${migrationName} not found`, { code: 'MIGRATION_NOT_FOUND', exitCode: ExitCode.NotFound })
 			}
 			migrations.push(migration)
 		}
 
-		console.log('Rebasing: ' + migrations.map(it => it.name).join(', '))
+		output.info('Rebasing: ' + migrations.map(it => it.name).join(', '))
+		if (!input.getOption('yes')) {
+			if (!output.canPrompt()) {
+				throw new CliError('TTY not available. Pass --yes to confirm rebasing.', {
+					code: 'TTY_UNAVAILABLE',
+					exitCode: ExitCode.InputError,
+				})
+			}
+			const confirmed = await promptConfirm(output, {
+				message: 'Rewrite these migrations?',
+				initial: false,
+			})
+			if (!confirmed) {
+				throw new CliError('Migration rebase aborted', { code: 'OPERATION_ABORTED', exitCode: ExitCode.InputError })
+			}
+		}
 		await this.migrationRebaseFacade.rebase(migrations)
-		console.log('Done')
+		const result = { migrations: migrations.map(it => it.name), count: migrations.length }
+		output.data(result, {
+			human: value => `Rebased ${value.count} migration(s)`,
+			quiet: value => value.migrations,
+		})
 	}
 }

package/src/commands/migrations/MigrationSnapshotCommand.ts

@@ -0,0 +1,69 @@
+import { CliError, Command, CommandConfiguration, ExitCode, Input, Output } from '@contember/cli-common'
+import { MigrationSnapshotFacade } from '../../lib/migrations/MigrationSnapshotFacade.js'
+import { promptConfirm } from '../../lib/prompt/index.js'
+
+type Args = {}
+
+type Options = {
+	yes?: true
+}
+
+export class MigrationSnapshotCommand extends Command<Args, Options> {
+	constructor(
+		private readonly migrationSnapshotFacade: MigrationSnapshotFacade,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description(
+			'Creates a schema snapshot (snapshot.json) that bootstraps a fresh database in one step instead of replaying every migration',
+		)
+		configuration.option('yes').valueNone().description('Do not ask for confirmation.')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<number> {
+		const snapshot = await this.migrationSnapshotFacade.prepare()
+		output.info(`Will collapse ${snapshot.covers.length} migrations up to ${snapshot.version} into snapshot.json.`)
+
+		if (snapshot.contentMigrations.length > 0) {
+			output.warn('')
+			output.warn(`Warning: ${snapshot.contentMigrations.length} content (data) migration(s) are covered by this snapshot:`)
+			snapshot.contentMigrations.forEach(version => output.warn(`  - ${version}`))
+			output.warn('Their data effects are NOT reproduced when bootstrapping from the snapshot.')
+			output.warn('Seed any required data manually for local development.')
+		}
+
+		if (!input.getOption('yes')) {
+			if (!output.canPrompt()) {
+				throw new CliError('TTY not available. Pass --yes to confirm snapshot creation.', {
+					code: 'TTY_UNAVAILABLE',
+					exitCode: ExitCode.InputError,
+				})
+			}
+			const confirmed = await promptConfirm(output, {
+				message: 'Write snapshot.json?',
+				initial: false,
+			})
+			if (!confirmed) {
+				throw new CliError('Snapshot creation aborted', {
+					code: 'OPERATION_ABORTED',
+					exitCode: ExitCode.InputError,
+				})
+			}
+		}
+
+		await this.migrationSnapshotFacade.write(snapshot)
+		const result = {
+			version: snapshot.version,
+			coveredMigrations: snapshot.covers.length,
+			contentMigrations: snapshot.contentMigrations,
+			path: 'snapshot.json',
+		}
+		output.data(result, {
+			human: value => `Snapshot created: ${value.coveredMigrations} migrations collapsed up to ${value.version}.`,
+			quiet: value => value.path,
+		})
+		return 0
+	}
+}

package/src/commands/migrations/MigrationStatusCommand.ts

@@ -1,9 +1,8 @@
-import { Command, CommandConfiguration, Input } from '@contember/cli-common'
-import { MigrationFilesManager, MigrationState, sortMigrations, SystemClient } from '@contember/migrations-client'
-import chalk from 'chalk'
-import { MigrationsStatusFacade } from '../../lib/migrations/MigrationsStatusFacade'
-import { MigrationPrinter } from '../../lib/migrations/MigrationPrinter'
-import { SystemClientProvider } from '../../lib/SystemClientProvider'
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { MigrationFilesManager, MigrationState, sortMigrations } from '@contember/migrations-client'
+import { MigrationsStatusFacade } from '../../lib/migrations/MigrationsStatusFacade.js'
+import { MigrationPrinter, migrationStatusColumns } from '../../lib/migrations/MigrationPrinter.js'
+import { SystemClientProvider } from '../../lib/SystemClientProvider.js'
 
 type Args = {}
 
@@ -13,12 +12,20 @@ type Options = {
 	['restore-missing']?: true
 }
 
+type MigrationStatusResolver = Pick<MigrationsStatusFacade, 'resolveMigrationsStatus'>
+type MigrationFileWriter = Pick<MigrationFilesManager, 'createFile'>
+type MigrationStatusPrinter = Pick<MigrationPrinter, 'statusRows'>
+
+interface MigrationSystemClientProvider {
+	get(): Pick<ReturnType<SystemClientProvider['get']>, 'getExecutedMigration'>
+}
+
 export class MigrationStatusCommand extends Command<Args, Options> {
 	constructor(
-		private readonly migrationsStatusFacade: MigrationsStatusFacade,
-		private readonly migrationFilesManager: MigrationFilesManager,
-		private readonly systemClientProvider: SystemClientProvider,
-		private readonly migrationPrinter: MigrationPrinter,
+		private readonly migrationsStatusFacade: MigrationStatusResolver,
+		private readonly migrationFilesManager: MigrationFileWriter,
+		private readonly systemClientProvider: MigrationSystemClientProvider,
+		private readonly migrationPrinter: MigrationStatusPrinter,
 	) {
 		super()
 	}
@@ -39,7 +46,7 @@ export class MigrationStatusCommand extends Command<Args, Options> {
 			.description('Restores migrations locally missing')
 	}
 
-	protected async execute(input: Input<Args, Options>): Promise<number> {
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<number> {
 		const onlyErrors = input.getOption('only-errors')
 		const onlyToExecute = input.getOption('only-to-execute')
 		const restoreMissing = input.getOption('restore-missing')
@@ -49,7 +56,7 @@ export class MigrationStatusCommand extends Command<Args, Options> {
 		if (restoreMissing) {
 			const missing = status.errorMigrations.filter(it => it.state === MigrationState.EXECUTED_MISSING)
 			for (const migration of missing) {
-				console.log(`Restoring migration ${migration.name}`)
+				output.info(`Restoring migration ${migration.name}`)
 				const fullMigration = await this.systemClientProvider.get().getExecutedMigration(migration.version)
 				await this.migrationFilesManager.createFile(
 					JSON.stringify(
@@ -73,12 +80,13 @@ export class MigrationStatusCommand extends Command<Args, Options> {
 			])
 			: status.allMigrations
 
-		console.log(this.migrationPrinter.printStatusTable(filtered))
+		// the status is the answer of this command, so it goes to stdout — as a table, JSON or bare names
+		output.table(migrationStatusColumns, this.migrationPrinter.statusRows(filtered), 'migration')
 
 		const hasErrors = status.errorMigrations.length > 0
 
 		if (hasErrors) {
-			console.error(chalk.redBright('Some migrations are broken'))
+			output.error('Some migrations are broken')
 		}
 
 		return hasErrors ? 1 : 0

package/src/commands/migrations/MigrationVerifySnapshotCommand.ts

@@ -0,0 +1,27 @@
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
+import { MigrationSnapshotFacade } from '../../lib/migrations/MigrationSnapshotFacade.js'
+
+type Args = {}
+
+type Options = {}
+
+export class MigrationVerifySnapshotCommand extends Command<Args, Options> {
+	constructor(
+		private readonly migrationSnapshotFacade: MigrationSnapshotFacade,
+	) {
+		super()
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Verifies that snapshot.json still matches a full replay of all migrations')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<number> {
+		const result = await this.migrationSnapshotFacade.verify()
+		output.data(result, {
+			human: value => value.message,
+			quiet: value => value.ok,
+		})
+		return result.ok ? 0 : 1
+	}
+}

package/src/commands/migrations/index.ts

@@ -1,7 +1,10 @@
-export * from './MigrationAmendCommand'
-export * from './MigrationBlankCommand'
-export * from './MigrationDescribeCommand'
-export * from './MigrationDiffCommand'
-export * from './MigrationExecuteCommand'
-export * from './MigrationStatusCommand'
-export * from './MigrationRebaseCommand'
+export * from './MigrationAmendCommand.js'
+export * from './MigrationBlankCommand.js'
+export * from './MigrationDescribeCommand.js'
+export * from './MigrationDiffCommand.js'
+export * from './MigrationExecuteCommand.js'
+export * from './MigrationInitStateCommand.js'
+export * from './MigrationStatusCommand.js'
+export * from './MigrationRebaseCommand.js'
+export * from './MigrationSnapshotCommand.js'
+export * from './MigrationVerifySnapshotCommand.js'

package/src/commands/misc/CommandsCommand.ts

@@ -0,0 +1,74 @@
+import { Command, CommandConfiguration, CommandManager, globalOptions, Input, mergeOptions, Output } from '@contember/cli-common'
+
+type Args = {}
+type Options = {}
+
+interface CommandInfo {
+	name: string
+	group: string | null
+	description: string
+	aliases: string[]
+	arguments: { name: string; description: string | null; optional: boolean; variadic: boolean }[]
+	options: {
+		name: string
+		shortcut: string | null
+		description: string | null
+		mode: string
+		required: boolean
+		deprecated: boolean
+		global: boolean
+	}[]
+}
+
+/** Machine readable catalog of the whole CLI — the entry point for an agent discovering the available commands. */
+export class CommandsCommand extends Command<Args, Options> {
+	private commandManager: CommandManager | undefined = undefined
+
+	/** Set by the container: the catalog contains this very command, so the dependency cannot be constructor injected. */
+	public setCommandManager(commandManager: CommandManager): void {
+		this.commandManager = commandManager
+	}
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
+		configuration.description('Lists all commands with their arguments and options')
+	}
+
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		if (this.commandManager === undefined) {
+			throw new Error('Command manager is not set')
+		}
+		const commands = this.commandManager.getCommands().map((entry): CommandInfo => {
+			const configuration = entry.create().getConfiguration()
+			const commandOptions = configuration.getOptions()
+			return {
+				name: entry.name,
+				group: entry.group ?? null,
+				description: configuration.getDescription(),
+				aliases: [...entry.aliases],
+				arguments: configuration.getArguments().map(it => ({
+					name: it.name,
+					description: it.description ?? null,
+					optional: it.optional,
+					variadic: it.variadic,
+				})),
+				options: mergeOptions(commandOptions, globalOptions).map(it => ({
+					name: it.name,
+					shortcut: it.shortcut ?? null,
+					description: it.description ?? null,
+					mode: it.mode,
+					required: it.required,
+					deprecated: it.deprecated,
+					global: !commandOptions.includes(it),
+				})),
+			}
+		})
+
+		output.data(commands, {
+			human: it => {
+				const width = Math.max(0, ...it.map(command => command.name.length))
+				return it.map(command => `${command.name.padEnd(width)}    ${command.description}`).join('\n')
+			},
+			quiet: it => it.map(command => command.name),
+		})
+	}
+}

package/src/commands/misc/VersionCommand.ts

@@ -1,17 +1,24 @@
-import { Command, CommandConfiguration } from '@contember/cli-common'
+import { Command, CommandConfiguration, Input, Output } from '@contember/cli-common'
 
-export class VersionCommand extends Command<{}, {}> {
+type Args = {}
+type Options = {}
+
+/**
+ * The reference implementation of the output contract: the value goes to stdout through `output.data`,
+ * which renders it as plain text for a human, as JSON with --json and bare with --quiet.
+ */
+export class VersionCommand extends Command<Args, Options> {
 	constructor(
 		private readonly version: string,
 	) {
 		super()
 	}
-	protected configure(configuration: CommandConfiguration<{}, {}>): void {
+
+	protected configure(configuration: CommandConfiguration<Args, Options>): void {
 		configuration.description('Prints Contember CLI version')
 	}
 
-	protected async execute(): Promise<void | number> {
-		console.log(this.version)
-		return 0
+	protected async execute(input: Input<Args, Options>, output: Output): Promise<void> {
+		output.data(this.version, it => it)
 	}
 }