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

package/src/lib/errors/TransportError.ts

@@ -0,0 +1,260 @@
+import { CliError, ExitCode } from '@contember/cli-common'
+import { GraphQlClientError, GraphQlErrorType } from '@contember/graphql-client'
+
+export interface TransportErrorContext {
+	/** Human-readable service name used in error messages. */
+	readonly service: string
+	/** Stable machine-readable prefix, for example `TENANT_API`. */
+	readonly codePrefix: string
+	/** Endpoint only. Credentials, query parameters, and fragments are removed. */
+	readonly url?: string
+}
+
+export type HttpErrorKind = 'forbidden' | 'not-found' | 'conflict' | 'transient' | 'input' | 'internal'
+
+export interface HttpStatusClassification {
+	readonly kind: HttpErrorKind
+	readonly codeSuffix: string
+	readonly exitCode: ExitCode
+}
+
+export interface HttpErrorResponse {
+	readonly status: number
+	readonly retryAfter?: string | null
+}
+
+/** Classifies HTTP failures independently of any particular API client. */
+export const classifyHttpStatus = (status: number): HttpStatusClassification => {
+	if (status === 401) {
+		return { kind: 'forbidden', codeSuffix: 'UNAUTHORIZED', exitCode: ExitCode.Forbidden }
+	}
+	if (status === 403) {
+		return { kind: 'forbidden', codeSuffix: 'FORBIDDEN', exitCode: ExitCode.Forbidden }
+	}
+	if (status === 404) {
+		return { kind: 'not-found', codeSuffix: 'NOT_FOUND', exitCode: ExitCode.NotFound }
+	}
+	if (status === 408) {
+		return { kind: 'transient', codeSuffix: 'TIMEOUT', exitCode: ExitCode.Transient }
+	}
+	if (status === 409) {
+		return { kind: 'conflict', codeSuffix: 'CONFLICT', exitCode: ExitCode.Conflict }
+	}
+	if (status === 425) {
+		return { kind: 'transient', codeSuffix: 'TOO_EARLY', exitCode: ExitCode.Transient }
+	}
+	if (status === 429) {
+		return { kind: 'transient', codeSuffix: 'RATE_LIMITED', exitCode: ExitCode.Transient }
+	}
+	if (status >= 500 && status <= 599) {
+		return { kind: 'transient', codeSuffix: 'SERVER_ERROR', exitCode: ExitCode.Transient }
+	}
+	if (status >= 400 && status <= 499) {
+		return { kind: 'input', codeSuffix: 'BAD_REQUEST', exitCode: ExitCode.InputError }
+	}
+	return { kind: 'internal', codeSuffix: 'HTTP_ERROR', exitCode: ExitCode.InternalError }
+}
+
+/** Creates a safe CLI error for a received HTTP failure without copying its body. */
+export const toHttpTransportError = (
+	response: HttpErrorResponse,
+	context: TransportErrorContext,
+	cause?: unknown,
+): CliError => {
+	const classification = classifyHttpStatus(response.status)
+	return new CliError(`${context.service} request failed with HTTP ${response.status}`, {
+		code: `${context.codePrefix}_${classification.codeSuffix}`,
+		exitCode: classification.exitCode,
+		details: createDetails(context, {
+			status: response.status,
+			retryAfter: sanitizeRetryAfter(response.retryAfter),
+		}),
+		cause: sanitizeCause(cause, context),
+	})
+}
+
+/**
+ * Normalizes an error thrown by a transport call. Call this only at a transport boundary: a plain
+ * thrown error is treated as a rejected network operation and is therefore retryable.
+ */
+export const toTransportError = (error: unknown, context: TransportErrorContext): CliError => {
+	if (error instanceof CliError) {
+		return error
+	}
+	if (error instanceof GraphQlClientError) {
+		return graphQlTransportError(error, context)
+	}
+	return new CliError(`${context.service} request failed: network error`, {
+		code: `${context.codePrefix}_UNREACHABLE`,
+		exitCode: ExitCode.Transient,
+		details: createDetails(context, { status: null }),
+		cause: sanitizeCause(error, context),
+	})
+}
+
+interface TransportErrorDetails {
+	readonly type?: GraphQlErrorType
+	readonly url?: string
+	readonly status: number | null
+	readonly retryAfter?: string
+}
+
+const graphQlTransportError = (error: GraphQlClientError, context: TransportErrorContext): CliError => {
+	const graphQlCodes = extractGraphQlCodes(error)
+	const semantic = classifyGraphQlCodes(graphQlCodes)
+	if (semantic !== null) {
+		return createGraphQlError(error, context, semantic)
+	}
+
+	if (error.type === 'aborted') {
+		return createGraphQlError(
+			error,
+			context,
+			{ kind: 'transient', codeSuffix: 'ABORTED', exitCode: ExitCode.Transient },
+		)
+	}
+	if (error.type === 'network error') {
+		return createGraphQlError(
+			error,
+			context,
+			{ kind: 'transient', codeSuffix: 'UNREACHABLE', exitCode: ExitCode.Transient },
+		)
+	}
+	if (error.type === 'invalid response body') {
+		return createGraphQlError(
+			error,
+			context,
+			{ kind: 'internal', codeSuffix: 'INVALID_RESPONSE', exitCode: ExitCode.InternalError },
+		)
+	}
+	if (error.response !== undefined && error.response.status >= 400) {
+		return createGraphQlError(error, context, classifyHttpStatus(error.response.status))
+	}
+	if (error.type === 'server error') {
+		return createGraphQlError(
+			error,
+			context,
+			{ kind: 'transient', codeSuffix: 'SERVER_ERROR', exitCode: ExitCode.Transient },
+		)
+	}
+	if (error.type === 'unauthorized') {
+		return createGraphQlError(
+			error,
+			context,
+			{ kind: 'forbidden', codeSuffix: 'UNAUTHORIZED', exitCode: ExitCode.Forbidden },
+		)
+	}
+	if (error.type === 'forbidden') {
+		return createGraphQlError(
+			error,
+			context,
+			{ kind: 'forbidden', codeSuffix: 'FORBIDDEN', exitCode: ExitCode.Forbidden },
+		)
+	}
+	return createGraphQlError(
+		error,
+		context,
+		{ kind: 'input', codeSuffix: error.type === 'bad request' ? 'BAD_REQUEST' : 'ERROR', exitCode: ExitCode.InputError },
+	)
+}
+
+const createGraphQlError = (
+	error: GraphQlClientError,
+	context: TransportErrorContext,
+	classification: HttpStatusClassification,
+): CliError =>
+	new CliError(`${context.service} request failed: ${describeFailure(classification.kind)}`, {
+		code: `${context.codePrefix}_${classification.codeSuffix}`,
+		exitCode: classification.exitCode,
+		details: createDetails(
+			{ ...context, url: error.request.url },
+			{
+				type: error.type,
+				status: error.response?.status ?? null,
+				retryAfter: sanitizeRetryAfter(error.response?.headers.get('retry-after')),
+			},
+		),
+		cause: sanitizeCause(error, context),
+	})
+
+const describeFailure = (kind: HttpErrorKind): string => {
+	switch (kind) {
+		case 'forbidden':
+			return 'authentication or permission denied'
+		case 'not-found':
+			return 'resource not found'
+		case 'conflict':
+			return 'conflict'
+		case 'transient':
+			return 'temporary failure'
+		case 'input':
+			return 'request rejected'
+		case 'internal':
+			return 'invalid response'
+	}
+}
+
+const authGraphQlCodes = new Set(['ForbiddenError', 'FORBIDDEN', 'UNAUTHENTICATED', 'UNAUTHORIZED'])
+const serverGraphQlCodes = new Set(['INTERNAL_SERVER_ERROR', 'InternalServerError'])
+
+const classifyGraphQlCodes = (codes: readonly string[]): HttpStatusClassification | null => {
+	if (codes.some(code => authGraphQlCodes.has(code))) {
+		return { kind: 'forbidden', codeSuffix: 'FORBIDDEN', exitCode: ExitCode.Forbidden }
+	}
+	if (codes.some(code => serverGraphQlCodes.has(code))) {
+		return { kind: 'transient', codeSuffix: 'SERVER_ERROR', exitCode: ExitCode.Transient }
+	}
+	return null
+}
+
+const extractGraphQlCodes = (error: GraphQlClientError): readonly string[] => {
+	const values: readonly unknown[] = error.errors ?? []
+	return values.flatMap(value => {
+		if (typeof value !== 'object' || value === null || !('extensions' in value)) {
+			return []
+		}
+		const extensions = value.extensions
+		if (typeof extensions !== 'object' || extensions === null || !('code' in extensions) || typeof extensions.code !== 'string') {
+			return []
+		}
+		return [extensions.code]
+	})
+}
+
+const createDetails = (
+	context: TransportErrorContext,
+	values: Omit<TransportErrorDetails, 'url'>,
+): TransportErrorDetails => {
+	const safeUrl = context.url === undefined ? undefined : sanitizeUrl(context.url)
+	return {
+		status: values.status,
+		...(values.type === undefined ? {} : { type: values.type }),
+		...(safeUrl === undefined ? {} : { url: safeUrl }),
+		...(values.retryAfter === undefined ? {} : { retryAfter: values.retryAfter }),
+	}
+}
+
+const sanitizeUrl = (value: string): string | undefined => {
+	try {
+		const url = new URL(value)
+		return `${url.protocol}//${url.host}${url.pathname}`
+	} catch {
+		return undefined
+	}
+}
+
+const sanitizeCause = (cause: unknown, context: TransportErrorContext): Error | undefined =>
+	cause === undefined ? undefined : new Error(`${context.service} transport failure`)
+
+const sanitizeRetryAfter = (value: string | null | undefined): string | undefined => {
+	if (value === undefined || value === null) {
+		return undefined
+	}
+	if (/^\d{1,10}$/.test(value)) {
+		return value
+	}
+	if (/^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(value)) {
+		return value
+	}
+	return undefined
+}

package/src/lib/errors/index.ts

@@ -0,0 +1 @@
+export * from './TransportError.js'

package/src/lib/maskToken.ts

@@ -1 +1,9 @@
-export const maskToken = (token: string) => token.replace(/^(\w{3}).+(\w{3})$/, '$1***$2')
+const recognizableToken = /^[A-Za-z0-9._~-]{12,}$/
+
+/** Keeps a small fingerprint for recognizable credentials and hides every other value completely. */
+export const maskToken = (token: string): string => {
+	if (!recognizableToken.test(token)) {
+		return '***'
+	}
+	return `${token.slice(0, 3)}***${token.slice(-3)}`
+}

package/src/lib/migrations/MigrationExecutionFacade.ts

@@ -1,4 +1,3 @@
-import prompts from 'prompts'
 import { MigrationPrinter } from './MigrationPrinter.js'
 import {
 	isSchemaMigration,
@@ -8,6 +7,7 @@ import {
 	SchemaState,
 	SchemaStateManager,
 	SchemaVersionBuilder,
+	SnapshotFile,
 } from '@contember/migrations-client'
 import { MigrationsStatusFacade } from './MigrationsStatusFacade.js'
 import { MigrationSnapshotFacade } from './MigrationSnapshotFacade.js'
@@ -15,6 +15,9 @@ import { MigrationVersionHelper } from '@contember/engine-common'
 import { SystemClientProvider } from '../SystemClientProvider.js'
 import { TenantClientProvider } from '../TenantClientProvider.js'
 import { RemoteProjectProvider } from '../project/RemoteProjectProvider.js'
+import { CliError, ExitCode, Output } from '@contember/cli-common'
+import { GraphQlClientError } from '@contember/graphql-client'
+import { promptSelect } from '../prompt/index.js'
 
 export class MigrationExecutionFacade {
 	constructor(
@@ -27,6 +30,7 @@ export class MigrationExecutionFacade {
 		private readonly migrationStatusFacade: MigrationsStatusFacade,
 		private readonly schemaStateManager: SchemaStateManager,
 		private readonly migrationSnapshotFacade: MigrationSnapshotFacade,
+		private readonly output: Output = new Output(),
 	) {
 	}
 
@@ -36,85 +40,120 @@ export class MigrationExecutionFacade {
 		until,
 		additionalMessage,
 		useSnapshot = true,
+		onConfirmed,
 	}: {
 		requireConfirmation: boolean | ((migrations: MigrationToExecuteOkStatus[]) => boolean)
 		force?: boolean
 		until?: string
 		additionalMessage?: string
 		useSnapshot?: boolean
+		onConfirmed?: () => void
 	}): Promise<boolean> => {
 		const project = this.projectProvider.get()
-		await this.tenantClientProvider.get().createProject(project.name, true)
-
 		const stateMode = await this.schemaStateManager.isStateMode()
 		let schemaState = stateMode ? await this.schemaStateManager.readState() : undefined
+		const localMigrations = await this.migrationStatusFacade.getLocalMigrationFiles()
 
 		// The state files always reflect the latest schema. When migrating to an older version, that
 		// state may reference parts of the model that don't exist yet, so skip it rather than push an
-		// inconsistent overlay. Run `migrations:execute` without `--until` to sync the schema state.
+		// inconsistent overlay. Run `migrations execute` without `--until` to sync the schema state.
 		if (until && schemaState) {
-			console.log(
-				'Warning: schema state was not applied because --until targets a specific migration; the state files reflect the latest schema. Run migrations:execute without --until to sync it.',
+			this.output.warn(
+				'Warning: schema state was not applied because --until targets a specific migration; the state files reflect the latest schema. Run "migrations execute" without --until to sync it.',
 			)
 			schemaState = undefined
 		}
-
-		if (useSnapshot) {
-			await this.tryApplySnapshot({ until, schemaState })
+		if (localMigrations.length === 0 && !schemaState) {
+			this.output.info('No migrations to execute')
+			return false
 		}
 
-		const status = await this.migrationStatusFacade.resolveMigrationsStatus({ force })
-		const migrations = until
-			? status.migrationsToExecute.filter(it => it.version <= MigrationVersionHelper.extractVersion(until))
-			: status.migrationsToExecute
-		if (migrations.length === 0 && !schemaState) {
-			console.log('No migrations to execute')
-			return true
+		let migrationsToConfirm: MigrationToExecuteOkStatus[] = []
+		if (localMigrations.length > 0) {
+			const status = await this.resolvePreflightStatus({ force })
+			migrationsToConfirm = until
+				? status.migrationsToExecute.filter(it => it.version <= MigrationVersionHelper.extractVersion(until))
+				: status.migrationsToExecute
+			if (migrationsToConfirm.length === 0 && !schemaState) {
+				this.output.info('No migrations to execute')
+				return false
+			}
+			if (migrationsToConfirm.length > 0) {
+				this.output.info('Will execute following migrations:')
+				migrationsToConfirm.forEach(it => this.output.info(it.name))
+			}
 		}
-		if (migrations.length > 0) {
-			console.log('Will execute following migrations:')
-			migrations.forEach(it => console.log(it.name))
+		if (schemaState && localMigrations.length === 0) {
+			this.output.info('Will update schema state')
 		}
-		if (schemaState && migrations.length === 0) {
-			console.log('Updating schema state')
+		if (additionalMessage) {
+			this.output.info(additionalMessage)
 		}
-		additionalMessage && console.log(additionalMessage)
 
-		if (migrations.length > 0 && (typeof requireConfirmation === 'function' ? requireConfirmation(migrations) : requireConfirmation)) {
-			if (!process.stdin.isTTY) {
-				throw 'TTY not available. Pass --yes option to confirm execution.'
+		if (typeof requireConfirmation === 'function' ? requireConfirmation(migrationsToConfirm) : requireConfirmation) {
+			if (!this.output.canPrompt()) {
+				throw new CliError('TTY not available. Pass --yes to confirm execution.', {
+					code: 'TTY_UNAVAILABLE',
+					exitCode: ExitCode.InputError,
+				})
 			}
 			do {
-				const { action } = await prompts({
-					type: 'select',
-					name: 'action',
+				const action = await promptSelect(this.output, {
 					message: 'Do you want to continue?',
 					choices: [
-						{ value: 'yes', title: 'Execute migrations' },
-						{ value: 'describe', title: 'Describe migrations' },
+						{ value: 'yes', title: migrationsToConfirm.length > 0 ? 'Execute migrations' : 'Update schema state' },
+						...(migrationsToConfirm.length > 0 ? [{ value: 'describe', title: 'Describe migrations' }] : []),
 						{ value: 'no', title: 'Abort' },
 					],
 				})
 				if (action === 'describe') {
-					const schema = await this.schemaVersionBuilder.buildSchemaUntil(migrations[0].version)
-					for (const migration of migrations) {
-						const migrationContent = await migration.localMigration.getContent()
-						if (!isSchemaMigration(migrationContent)) {
-							continue
+					const schema = await this.schemaVersionBuilder.buildSchemaUntil(migrationsToConfirm[0].version)
+					for (const migration of migrationsToConfirm) {
+						const content = await migration.localMigration.getContent()
+						if (isSchemaMigration(content)) {
+							this.migrationPrinter.printMigrationDescription(schema, content, { noSql: true })
 						}
-
-						await this.migrationPrinter.printMigrationDescription(schema, migrationContent, {
-							noSql: true,
-						})
 					}
-				} else if (action === 'yes') {
+					continue
+				}
+				if (action === 'yes') {
+					onConfirmed?.()
 					break
-				} else {
-					return false
 				}
+				throw new CliError('Migration execution aborted', {
+					code: 'OPERATION_ABORTED',
+					exitCode: ExitCode.InputError,
+				})
 			} while (true)
 		}
 
+		await this.tenantClientProvider.get().createProject(project.name, true, { noDeployToken: true })
+
+		const snapshot = useSnapshot ? await this.getSnapshotToApply({ until }) : undefined
+
+		let status = await this.migrationStatusFacade.resolveMigrationsStatus({ force })
+		let migrations = until
+			? status.migrationsToExecute.filter(it => it.version <= MigrationVersionHelper.extractVersion(until))
+			: status.migrationsToExecute
+		if (schemaState && migrations.length === 0) {
+			this.output.info('Updating schema state')
+		}
+		if (snapshot) {
+			this.output.info(`Will bootstrap from snapshot (${snapshot.covers.length} migrations up to ${snapshot.version})`)
+		}
+		if (migrations.length === 0 && !schemaState && !snapshot) {
+			this.output.info('No pending migrations to execute')
+			return false
+		}
+
+		if (snapshot) {
+			await this.applySnapshot(snapshot, schemaState)
+			status = await this.migrationStatusFacade.resolveMigrationsStatus({ force })
+			migrations = until
+				? status.migrationsToExecute.filter(it => it.version <= MigrationVersionHelper.extractVersion(until))
+				: status.migrationsToExecute
+		}
+
 		try {
 			await this.migrationExecutor.executeMigrations({
 				client: this.systemClientProvider.get(),
@@ -126,15 +165,15 @@ export class MigrationExecutionFacade {
 					projectName: project.name,
 					schemaVersionBuilder: this.schemaVersionBuilder,
 				},
-				log: message => console.log(message),
+				log: message => this.output.info(message),
 				force,
 			})
 		} catch (e) {
 			if (isViewReplaceFailure(e)) {
-				console.error(
+				this.output.error(
 					"\nAn in-place view update (CREATE OR REPLACE VIEW) failed — Postgres rejects it (SQLSTATE 42P16) when a view's"
 						+ ' output columns changed (e.g. reordered or retyped) even though its fields did not.\n'
-						+ 'Re-generate the migration with `migrations:diff <name> --recreate-views` to drop & recreate the affected'
+						+ 'Re-generate the migration with `migrations diff <name> --recreate-views` to drop & recreate the affected'
 						+ ' views (and their dependants) instead.\n',
 				)
 			}
@@ -143,19 +182,37 @@ export class MigrationExecutionFacade {
 		return true
 	}
 
-	private async tryApplySnapshot({ until, schemaState }: { until?: string; schemaState?: SchemaState }): Promise<void> {
+	private async resolvePreflightStatus({ force }: { force?: boolean }) {
+		try {
+			return await this.migrationStatusFacade.resolveMigrationsStatus({ force })
+		} catch (error) {
+			const projectNotFound = error instanceof CliError
+				? error.code === 'SYSTEM_API_NOT_FOUND'
+				: error instanceof GraphQlClientError && error.response?.status === 404
+			if (!projectNotFound) {
+				throw error
+			}
+			return await this.migrationStatusFacade.resolveMigrationsStatusFromExecuted([], { force })
+		}
+	}
+
+	private async getSnapshotToApply({ until }: { until?: string }): Promise<SnapshotFile | undefined> {
 		const executed = await this.systemClientProvider.get().listExecutedMigrations()
 		const snapshot = await this.migrationSnapshotFacade.getUsableSnapshot(executed)
 		if (!snapshot) {
-			return
+			return undefined
 		}
 		if (until && snapshot.version > MigrationVersionHelper.extractVersion(until)) {
 			// snapshot reaches past the requested target — fall back to a normal replay
-			return
+			return undefined
 		}
-		console.log(`Bootstrapping from snapshot (collapses ${snapshot.covers.length} migrations up to ${snapshot.version})`)
+		return snapshot
+	}
+
+	private async applySnapshot(snapshot: SnapshotFile, schemaState?: SchemaState): Promise<void> {
+		this.output.info(`Bootstrapping from snapshot (collapses ${snapshot.covers.length} migrations up to ${snapshot.version})`)
 		if (snapshot.contentMigrations.length > 0) {
-			console.warn(
+			this.output.warn(
 				`Note: ${snapshot.contentMigrations.length} content migration(s) are covered by the snapshot; their data is NOT reproduced.`,
 			)
 		}
@@ -167,26 +224,27 @@ export class MigrationExecutionFacade {
 				// The project was migrated between our emptiness check and the server call (e.g. a
 				// concurrent execute on a fresh database). Fall back to a normal replay rather than
 				// crashing — the subsequent status resolution will pick up whatever is left to run.
-				console.warn('Snapshot skipped: the project is no longer empty. Falling back to a full replay.')
+				this.output.warn('Snapshot skipped: the project is no longer empty. Falling back to a full replay.')
 				return
 			}
 			throw e
 		}
-		console.log('Snapshot applied')
+		this.output.info('Snapshot applied')
 	}
 }
 
-const isProjectNotEmptyError = (e: unknown): boolean =>
-	Array.isArray(e) && e.some(it => it !== null && typeof it === 'object' && (it as { code?: unknown }).code === MigrateErrorCode.ProjectNotEmpty)
+const isProjectNotEmptyError = (e: unknown): boolean => Array.isArray(e) && e.some(it => hasCode(it, MigrateErrorCode.ProjectNotEmpty))
 
 // A failed `updateView` modification surfaces as MIGRATION_FAILED whose developerMessage embeds the failing
 // statement (`CREATE OR REPLACE VIEW …`). Since each modification's SQL is executed in isolation, that string
 // is a precise signal that an in-place view update — and not some other statement — is what Postgres rejected.
 const isViewReplaceFailure = (e: unknown): boolean =>
 	Array.isArray(e) && e.some(it =>
-		it !== null
-		&& typeof it === 'object'
-		&& (it as { code?: unknown }).code === MigrateErrorCode.MigrationFailed
-		&& typeof (it as { message?: unknown }).message === 'string'
-		&& (it as { message: string }).message.includes('CREATE OR REPLACE VIEW')
+		hasCode(it, MigrateErrorCode.MigrationFailed)
+		&& 'message' in it
+		&& typeof it.message === 'string'
+		&& it.message.includes('CREATE OR REPLACE VIEW')
 	)
+
+const hasCode = (value: unknown, code: MigrateErrorCode): value is object & { code: MigrateErrorCode } =>
+	value !== null && typeof value === 'object' && 'code' in value && value.code === code