@slicemachine/manager 0.15.4-dev-next-release.3 → 0.15.4-dev-environments.6

package/src/managers/prismicRepository/sortEnvironments.ts

@@ -0,0 +1,55 @@
+import { Environment } from "./types";
+
+/**
+ * Sorts a list of environments using the following criteria:
+ *
+ * - The production environment is always first.
+ * - Staging environments are always after production, before development
+ *   environments, and sorted alphabetically by name.
+ * - The development environment is always last.
+ *
+ * It assumes the list of environments contains one production environment and
+ * at most one dev environment.
+ *
+ * @param environments - The environments to sort.
+ *
+ * @returns The sorted environments.
+ */
+export function sortEnvironments(environments: Environment[]): Environment[] {
+	return [...environments].sort((a, b) => {
+		switch (a.kind) {
+			case "prod": {
+				return -1;
+			}
+
+			case "stage": {
+				switch (b.kind) {
+					case "prod": {
+						return 1;
+					}
+
+					case "stage": {
+						return a.name.localeCompare(b.name);
+					}
+
+					case "dev":
+					default: {
+						return -1;
+					}
+				}
+			}
+
+			case "dev": {
+				return 1;
+			}
+
+			default: {
+				if (b.kind === undefined) {
+					return a.name.localeCompare(b.name);
+				}
+
+				return 1;
+			}
+		}
+	});
+}

package/src/managers/prismicRepository/types.ts

@@ -155,3 +155,15 @@ export type StarterId =
 	| "nuxt_multi_page"
 	| "nuxt_blog"
 	| "nuxt_multi_lang";
+
+export const Environment = t.type({
+	kind: t.union([t.literal("prod"), t.literal("stage"), t.literal("dev")]),
+	name: t.string,
+	domain: t.string,
+	users: t.array(
+		t.type({
+			id: t.string,
+		}),
+	),
+});
+export type Environment = t.TypeOf<typeof Environment>;

package/src/managers/project/ProjectManager.ts

@@ -4,16 +4,28 @@ import * as path from "node:path";
 import { createRequire } from "node:module";
 import { detect as niDetect } from "@antfu/ni";
 import { ExecaChildProcess } from "execa";
-
+import {
+	HookError,
+	CallHookReturnType,
+	ProjectEnvironmentUpdateHook,
+} from "@slicemachine/plugin-kit";
+import * as t from "io-ts";
+
+import { DecodeError } from "../../lib/DecodeError";
 import { assertPluginsInitialized } from "../../lib/assertPluginsInitialized";
+import { decodeHookResult } from "../../lib/decodeHookResult";
 import { decodeSliceMachineConfig } from "../../lib/decodeSliceMachineConfig";
 import { format } from "../../lib/format";
 import { installDependencies } from "../../lib/installDependencies";
 import { locateFileUpward } from "../../lib/locateFileUpward";
 
-import { PackageManager, SliceMachineConfig } from "../../types";
+import {
+	PackageManager,
+	SliceMachineConfig,
+	OnlyHookErrors,
+} from "../../types";
 
-import { SliceMachineError, InternalError } from "../../errors";
+import { SliceMachineError, InternalError, PluginError } from "../../errors";
 
 import { SLICE_MACHINE_CONFIG_FILENAME } from "../../constants/SLICE_MACHINE_CONFIG_FILENAME";
 import { TS_CONFIG_FILENAME } from "../../constants/TS_CONFIG_FILENAME";
@@ -57,6 +69,15 @@ type ProjectManagerInstallDependenciesReturnType = {
 	execaProcess: ExecaChildProcess;
 };
 
+type ProjectManagerReadEnvironmentReturnType = {
+	environment: string | undefined;
+	errors: (DecodeError | HookError)[];
+};
+
+type ProjectManagerUpdateEnvironmentArgs = {
+	environment: string | undefined;
+};
+
 export class ProjectManager extends BaseManager {
 	private _cachedRoot: string | undefined;
 	private _cachedSliceMachineConfigPath: string | undefined;
@@ -195,12 +216,43 @@ export class ProjectManager extends BaseManager {
 		return path.dirname(sliceMachinePackageJSONPath);
 	}
 
+	/**
+	 * Returns the project's repository name (i.e. the production environment). It
+	 * ignores the currently selected environment.
+	 *
+	 * Use this method to retrieve the production environment domain.
+	 *
+	 * @returns The project's repository name.
+	 */
 	async getRepositoryName(): Promise<string> {
 		const sliceMachineConfig = await this.getSliceMachineConfig();
 
 		return sliceMachineConfig.repositoryName;
 	}
 
+	/**
+	 * Returns the currently selected environment domain if set. If an environment
+	 * is not set, it returns the project's repository name (the production
+	 * environment).
+	 *
+	 * Use this method to retrieve the repository name to be sent with Prismic API
+	 * requests.
+	 *
+	 * @returns The resolved repository name.
+	 */
+	async getResolvedRepositoryName(): Promise<string> {
+		const repositoryName = await this.getRepositoryName();
+
+		const supportsEnvironments = this.project.checkSupportsEnvironments();
+		if (!supportsEnvironments) {
+			return repositoryName;
+		}
+
+		const { environment } = await this.project.readEnvironment();
+
+		return environment ?? repositoryName;
+	}
+
 	async getAdapterName(): Promise<string> {
 		const sliceMachineConfig = await this.getSliceMachineConfig();
 		const adapterName =
@@ -312,4 +364,80 @@ export class ProjectManager extends BaseManager {
 			throw error;
 		}
 	}
+
+	checkSupportsEnvironments(): boolean {
+		assertPluginsInitialized(this.sliceMachinePluginRunner);
+
+		return (
+			this.sliceMachinePluginRunner.hooksForType("project:environment:read")
+				.length > 0 &&
+			this.sliceMachinePluginRunner.hooksForType("project:environment:update")
+				.length > 0
+		);
+	}
+
+	async readEnvironment(): Promise<ProjectManagerReadEnvironmentReturnType> {
+		assertPluginsInitialized(this.sliceMachinePluginRunner);
+
+		await this._assertAdapterSupportsEnvironments();
+
+		const hookResult = await this.sliceMachinePluginRunner.callHook(
+			"project:environment:read",
+			undefined,
+		);
+		const { data, errors } = decodeHookResult(
+			t.type({
+				environment: t.union([t.undefined, t.string]),
+			}),
+			hookResult,
+		);
+
+		// An undefined value is equivalent to the production environment.
+		// We cast to undefined.
+		const repositoryName = await this.project.getRepositoryName();
+		const environmentDomain =
+			data[0]?.environment === repositoryName
+				? undefined
+				: data[0]?.environment;
+
+		return {
+			environment: environmentDomain,
+			errors,
+		};
+	}
+
+	async updateEnvironment(
+		args: ProjectManagerUpdateEnvironmentArgs,
+	): Promise<OnlyHookErrors<CallHookReturnType<ProjectEnvironmentUpdateHook>>> {
+		assertPluginsInitialized(this.sliceMachinePluginRunner);
+
+		await this._assertAdapterSupportsEnvironments();
+
+		const repositoryName = await this.project.getRepositoryName();
+		const environment =
+			args.environment === repositoryName ? undefined : args.environment;
+
+		const hookResult = await this.sliceMachinePluginRunner.callHook(
+			"project:environment:update",
+			{ environment },
+		);
+
+		return {
+			errors: hookResult.errors,
+		};
+	}
+
+	private async _assertAdapterSupportsEnvironments(): Promise<void> {
+		assertPluginsInitialized(this.sliceMachinePluginRunner);
+
+		const supportsEnvironments = this.checkSupportsEnvironments();
+
+		if (!supportsEnvironments) {
+			const adapterName = await this.project.getAdapterName();
+
+			throw new PluginError(
+				`${adapterName} does not support environments. Use an adapter that implements the \`project:environment:read\` and \`project:environment:update\` hooks to use environments.`,
+			);
+		}
+	}
 }

package/src/managers/screenshots/ScreenshotsManager.ts

@@ -183,13 +183,13 @@ export class ScreenshotsManager extends BaseManager {
 		body?: unknown;
 	}): Promise<Response> {
 		const authenticationToken = await this.user.getAuthenticationToken();
-		const sliceMachineConfig = await this.project.getSliceMachineConfig();
+		const repositoryName = await this.project.getRepositoryName();
 
 		return await fetch(args.url, {
 			body: args.body ? JSON.stringify(args.body) : undefined,
 			headers: {
 				Authorization: `Bearer ${authenticationToken}`,
-				Repository: sliceMachineConfig.repositoryName,
+				Repository: repositoryName,
 				"User-Agent": SLICE_MACHINE_USER_AGENT,
 				...(args.body ? { "Content-Type": "application/json" } : {}),
 			},

package/src/managers/slices/SlicesManager.ts

@@ -110,12 +110,6 @@ type SliceMachineManagerUpdateSliceScreenshotArgs = {
 	data: Buffer;
 };
 
-type SliceMachineManagerDeleteSliceScreenshotArgs = {
-	libraryID: string;
-	sliceID: string;
-	variationID: string;
-};
-
 type SliceMachineManagerReadSliceMocksArgs = {
 	libraryID: string;
 	sliceID: string;
@@ -157,36 +151,6 @@ type SliceMachineManagerDeleteSliceArgs = {
 	sliceID: string;
 };
 
-type SliceMachineManagerDeleteSliceReturnType = {
-	errors: (DecodeError | HookError)[];
-};
-
-type SliceMachineManagerRenameSliceVariationArgs = {
-	libraryID: string;
-	sliceID: string;
-	/**
-	 * Current ID of the variation to rename.
-	 */
-	variationID: string;
-	model: Variation;
-};
-
-type SliceMachineManagerRenameSliceVariationReturnType = {
-	errors: (DecodeError | HookError)[];
-	assetsErrors: (DecodeError | HookError)[];
-};
-
-type SliceMachineManagerDeleteSliceVariationArgs = {
-	libraryID: string;
-	sliceID: string;
-	variationID: string;
-};
-
-type SliceMachineManagerDeleteSliceVariationReturnType = {
-	errors: (DecodeError | HookError)[];
-	assetsErrors: (DecodeError | HookError)[];
-};
-
 type SliceMachineManagerConvertLegacySliceToSharedSliceArgs = {
 	model: CompositeSlice | LegacySlice;
 	src: {
@@ -207,6 +171,10 @@ type SliceMachineManagerConvertLegacySliceToSharedSliceReturnType = {
 	errors: (DecodeError | HookError)[];
 };
 
+type SliceMachineManagerDeleteSliceReturnType = {
+	errors: (DecodeError | HookError)[];
+};
+
 export class SlicesManager extends BaseManager {
 	async readSliceLibrary(
 		args: SliceLibraryReadHookData,
@@ -459,184 +427,6 @@ export class SlicesManager extends BaseManager {
 		}
 	}
 
-	async renameSliceVariation(
-		args: SliceMachineManagerRenameSliceVariationArgs,
-	): Promise<SliceMachineManagerRenameSliceVariationReturnType> {
-		assertPluginsInitialized(this.sliceMachinePluginRunner);
-
-		// TODO: Remove when we support renaming variation ID, see: DT-1708
-		if (args.variationID !== args.model.id) {
-			throw new Error(
-				"Renaming variation ID is not supported yet by the backend, only rename its name! For more information, see: https://linear.app/prismic/issue/DT-1708",
-			);
-		}
-
-		const { model, errors: readSliceErrors } = await this.readSlice({
-			libraryID: args.libraryID,
-			sliceID: args.sliceID,
-		});
-
-		if (model) {
-			// Find and rename the variation
-			const updatedModel = {
-				...model,
-				variations: model.variations.map((variation) => {
-					if (variation.id === args.variationID) {
-						// Matches the slice we want to rename
-						return args.model;
-					} else if (variation.id === args.model.id) {
-						// Matches any other slice that has the ID of the renamed variation and throw.
-						// This should be validated on the frontend first for better UX, this is only backend validation.
-						throw new Error(
-							`Cannot rename variation \`${args.variationID}\` to \`${args.model.id}\`. A variation already exists with that ID in slice \`${args.sliceID}\` from library \`${args.libraryID}\`, try deleting it first or choose another variation ID to rename that slice.`,
-						);
-					}
-
-					return variation;
-				}),
-			};
-			const updateSliceHookResult =
-				await this.sliceMachinePluginRunner.callHook("slice:update", {
-					libraryID: args.libraryID,
-					model: updatedModel,
-				});
-
-			// If variation ID has changed, we need to rename assets accordingly
-			const assetsErrors: (DecodeError<unknown> | HookError<unknown>)[] = [];
-			if (args.variationID !== args.model.id) {
-				// Renaming screenshot
-				const { data: screenshot, errors: readSliceScreenshotErrors } =
-					await this.readSliceScreenshot({
-						libraryID: args.libraryID,
-						sliceID: args.sliceID,
-						variationID: args.variationID,
-					});
-				assetsErrors.push(...readSliceScreenshotErrors);
-
-				if (screenshot) {
-					// Delete old ID screenshot
-					const { errors: deleteSliceScreenshotErrors } =
-						await this.deleteSliceScreenshot({
-							libraryID: args.libraryID,
-							sliceID: args.sliceID,
-							variationID: args.variationID,
-						});
-					assetsErrors.push(...deleteSliceScreenshotErrors);
-
-					// Create new ID screenshot
-					const { errors: updateSliceScreenshotErrors } =
-						await this.updateSliceScreenshot({
-							libraryID: args.libraryID,
-							sliceID: args.sliceID,
-							variationID: args.model.id,
-							data: screenshot,
-						});
-					assetsErrors.push(...updateSliceScreenshotErrors);
-				}
-
-				// Renaming mocks
-				const { mocks, errors: readSliceMocksErrors } =
-					await this.readSliceMocks({
-						libraryID: args.libraryID,
-						sliceID: args.sliceID,
-					});
-				assetsErrors.push(...readSliceMocksErrors);
-
-				if (mocks?.length) {
-					const { errors: updateSliceMocksErrors } =
-						await this.updateSliceMocks({
-							libraryID: args.libraryID,
-							sliceID: args.sliceID,
-							mocks: mocks.map((mock) => {
-								if (mock.variation === args.variationID) {
-									return {
-										...mock,
-										variation: args.model.id,
-									};
-								}
-
-								return mock;
-							}),
-						});
-					assetsErrors.push(...updateSliceMocksErrors);
-				}
-			}
-
-			return {
-				errors: updateSliceHookResult.errors,
-				assetsErrors,
-			};
-		} else {
-			return {
-				errors: readSliceErrors,
-				assetsErrors: [],
-			};
-		}
-	}
-
-	async deleteSliceVariation(
-		args: SliceMachineManagerDeleteSliceVariationArgs,
-	): Promise<SliceMachineManagerDeleteSliceVariationReturnType> {
-		assertPluginsInitialized(this.sliceMachinePluginRunner);
-
-		const { model, errors: readSliceErrors } = await this.readSlice({
-			libraryID: args.libraryID,
-			sliceID: args.sliceID,
-		});
-
-		if (model) {
-			// Remove variation from model and update it
-			const updatedModel = {
-				...model,
-				variations: model.variations.filter(
-					(variation) => variation.id !== args.variationID,
-				),
-			};
-			const updateSliceHookResult =
-				await this.sliceMachinePluginRunner.callHook("slice:update", {
-					libraryID: args.libraryID,
-					model: updatedModel,
-				});
-
-			// Cleanup deleted variation screenshot
-			const { errors: deleteSliceScreenshotErrors } =
-				await this.deleteSliceScreenshot(args);
-
-			// Cleanup deleted variation mocks
-			const { mocks, errors: readSliceMocksErrors } = await this.readSliceMocks(
-				{
-					libraryID: args.libraryID,
-					sliceID: args.sliceID,
-				},
-			);
-			let updateSliceMocksErrors: SliceMachineManagerUpdateSliceMocksArgsReturnType["errors"] =
-				[];
-			if (mocks?.length) {
-				updateSliceMocksErrors = (
-					await this.updateSliceMocks({
-						libraryID: args.libraryID,
-						sliceID: args.sliceID,
-						mocks: mocks.filter((mock) => mock.variation !== args.variationID),
-					})
-				).errors;
-			}
-
-			return {
-				errors: updateSliceHookResult.errors,
-				assetsErrors: [
-					...deleteSliceScreenshotErrors,
-					...readSliceMocksErrors,
-					...updateSliceMocksErrors,
-				],
-			};
-		} else {
-			return {
-				errors: readSliceErrors,
-				assetsErrors: [],
-			};
-		}
-	}
-
 	async convertLegacySliceToSharedSlice(
 		args: SliceMachineManagerConvertLegacySliceToSharedSliceArgs,
 	): Promise<SliceMachineManagerConvertLegacySliceToSharedSliceReturnType> {
@@ -764,12 +554,12 @@ export class SlicesManager extends BaseManager {
 				});
 
 			const authenticationToken = await this.user.getAuthenticationToken();
-			const sliceMachineConfig = await this.project.getSliceMachineConfig();
+			const repositoryName = await this.project.getResolvedRepositoryName();
 
 			// TODO: Create a single shared client.
 			const client = prismicCustomTypesClient.createClient({
 				endpoint: API_ENDPOINTS.PrismicModels,
-				repositoryName: sliceMachineConfig.repositoryName,
+				repositoryName,
 				token: authenticationToken,
 				userAgent: args.userAgent || SLICE_MACHINE_USER_AGENT,
 				fetch,
@@ -860,25 +650,6 @@ export class SlicesManager extends BaseManager {
 		};
 	}
 
-	async deleteSliceScreenshot(
-		args: SliceMachineManagerDeleteSliceScreenshotArgs,
-	): Promise<OnlyHookErrors<CallHookReturnType<SliceAssetUpdateHook>>> {
-		assertPluginsInitialized(this.sliceMachinePluginRunner);
-
-		const hookResult = await this.sliceMachinePluginRunner.callHook(
-			"slice:asset:delete",
-			{
-				libraryID: args.libraryID,
-				sliceID: args.sliceID,
-				assetID: `screenshot-${args.variationID}.png`,
-			},
-		);
-
-		return {
-			errors: hookResult.errors,
-		};
-	}
-
 	async readSliceMocks(
 		args: SliceMachineManagerReadSliceMocksArgs,
 	): Promise<SliceMachineManagerReadSliceMocksReturnType> {
@@ -981,11 +752,11 @@ export class SlicesManager extends BaseManager {
 
 	async fetchRemoteSlices(): Promise<SharedSlice[]> {
 		const authenticationToken = await this.user.getAuthenticationToken();
-		const sliceMachineConfig = await this.project.getSliceMachineConfig();
+		const repositoryName = await this.project.getResolvedRepositoryName();
 
 		const client = prismicCustomTypesClient.createClient({
 			endpoint: API_ENDPOINTS.PrismicModels,
-			repositoryName: sliceMachineConfig.repositoryName,
+			repositoryName,
 			token: authenticationToken,
 			userAgent: SLICE_MACHINE_USER_AGENT,
 			fetch,