@slicemachine/manager 0.1.1-dev-plugins.3

package/src/managers/project/ProjectManager.ts

@@ -0,0 +1,165 @@
+import * as fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import { createRequire } from "node:module";
+
+import { decodeSliceMachineConfig } from "../../lib/decodeSliceMachineConfig";
+import { locateFileUpward } from "../../lib/locateFileUpward";
+
+import { SliceMachineConfig } from "../../types";
+
+import { SLICE_MACHINE_CONFIG_FILENAME } from "../../constants/SLICE_MACHINE_CONFIG_FILENAME";
+import { TS_CONFIG_FILENAME } from "../../constants/TS_CONFIG_FILENAME";
+import { SLICE_MACHINE_NPM_PACKAGE_NAME } from "../../constants/SLICE_MACHINE_NPM_PACKAGE_NAME";
+
+import { BaseManager } from "../BaseManager";
+import { format } from "../../lib/format";
+
+type ProjectManagerGetSliceMachineConfigPathArgs = {
+	ignoreCache?: boolean;
+};
+
+type ProjectManagerGetRootArgs = {
+	ignoreCache?: boolean;
+};
+
+type ProjectManagerCheckIsTypeScriptArgs = {
+	rootOverride?: string;
+};
+
+type ProjectManagerWriteSliceMachineConfigArgs = {
+	config: SliceMachineConfig;
+	path?: string;
+};
+
+export class ProjectManager extends BaseManager {
+	private _cachedRoot: string | undefined;
+	private _cachedSliceMachineConfigPath: string | undefined;
+	private _cachedSliceMachineConfig: SliceMachineConfig | undefined;
+
+	async getSliceMachineConfigPath(
+		args?: ProjectManagerGetSliceMachineConfigPathArgs,
+	): Promise<string> {
+		if (this._cachedSliceMachineConfigPath && !args?.ignoreCache) {
+			return this._cachedSliceMachineConfigPath;
+		}
+
+		try {
+			this._cachedSliceMachineConfigPath = await locateFileUpward(
+				SLICE_MACHINE_CONFIG_FILENAME,
+				{ startDir: this.cwd },
+			);
+		} catch (error) {
+			throw new Error(
+				`Could not find a ${SLICE_MACHINE_CONFIG_FILENAME} file. Please create a config file at the root of your project.`,
+			);
+		}
+
+		return this._cachedSliceMachineConfigPath;
+	}
+
+	async getRoot(args?: ProjectManagerGetRootArgs): Promise<string> {
+		if (this._cachedRoot && !args?.ignoreCache) {
+			return this._cachedRoot;
+		}
+
+		const sliceMachineConfigFilePath = await this.getSliceMachineConfigPath({
+			ignoreCache: args?.ignoreCache,
+		});
+
+		this._cachedRoot = path.dirname(sliceMachineConfigFilePath);
+
+		return this._cachedRoot;
+	}
+
+	async suggestRoot(): Promise<string> {
+		const suggestedRootPackageJSON = await locateFileUpward("package.json", {
+			startDir: this.cwd,
+		});
+
+		return path.dirname(suggestedRootPackageJSON);
+	}
+
+	async suggestSliceMachineConfigPath(): Promise<string> {
+		const suggestedRoot = await this.suggestRoot();
+
+		return path.resolve(suggestedRoot, SLICE_MACHINE_CONFIG_FILENAME);
+	}
+
+	async checkIsTypeScript(
+		args?: ProjectManagerCheckIsTypeScriptArgs,
+	): Promise<boolean> {
+		const root = args?.rootOverride || (await this.getRoot());
+		const rootTSConfigPath = path.resolve(root, TS_CONFIG_FILENAME);
+
+		// We just care if the file exists, we don't need access to it
+		return existsSync(rootTSConfigPath);
+	}
+
+	async getSliceMachineConfig(): Promise<SliceMachineConfig> {
+		if (this._cachedSliceMachineConfig) {
+			return this._cachedSliceMachineConfig;
+		} else {
+			return await this.loadSliceMachineConfig();
+		}
+	}
+
+	async writeSliceMachineConfig(
+		args: ProjectManagerWriteSliceMachineConfigArgs,
+	): Promise<void> {
+		const configFilePath =
+			args.path || (await this.getSliceMachineConfigPath());
+
+		const config = await format(
+			JSON.stringify(args.config, null, 2),
+			configFilePath,
+		);
+
+		await fs.writeFile(configFilePath, config, "utf-8");
+		delete this._cachedSliceMachineConfig; // Clear config cache
+	}
+
+	async loadSliceMachineConfig(): Promise<SliceMachineConfig> {
+		// TODO: Reload plugins with a fresh plugin runner. Plugins may
+		// have been added or removed.
+
+		const configFilePath = await this.getSliceMachineConfigPath();
+
+		let rawConfig: unknown | undefined;
+		try {
+			const contents = await fs.readFile(configFilePath, "utf8");
+			rawConfig = JSON.parse(contents);
+		} catch {
+			// noop
+		}
+
+		if (!rawConfig) {
+			// TODO: Write a more friendly and useful message.
+			throw new Error("No config found.");
+		}
+
+		const { value: sliceMachineConfig, error } =
+			decodeSliceMachineConfig(rawConfig);
+
+		if (error) {
+			// TODO: Write a more friendly and useful message.
+			throw new Error(`Invalid config. ${error.errors.join(", ")}`);
+		}
+
+		// Allow cached config reading using `SliceMachineManager.prototype.getProjectConfig()`.
+		this._cachedSliceMachineConfig = sliceMachineConfig;
+
+		return sliceMachineConfig;
+	}
+
+	async locateSliceMachineUIDir(): Promise<string> {
+		const projectRoot = await this.getRoot();
+
+		const require = createRequire(path.join(projectRoot, "index.js"));
+		const sliceMachinePackageJSONPath = require.resolve(
+			`${SLICE_MACHINE_NPM_PACKAGE_NAME}/package.json`,
+		);
+
+		return path.dirname(sliceMachinePackageJSONPath);
+	}
+}

package/src/managers/screenshots/ScreenshotsManager.ts

@@ -0,0 +1,242 @@
+import * as t from "io-ts";
+import { fileTypeFromBuffer } from "file-type";
+import fetch, { FormData, Blob } from "node-fetch";
+// puppeteer is lazy-loaded in captureSliceSimulatorScreenshot
+import type { BrowserContext, Viewport } from "puppeteer";
+
+import { checkIsURLAccessible } from "../../lib/checkIsURLAccessible";
+import { createContentDigest } from "../../lib/createContentDigest";
+import { decode } from "../../lib/decode";
+
+import { S3ACL } from "../../types";
+import { SLICE_MACHINE_USER_AGENT } from "../../constants/SLICE_MACHINE_USER_AGENT";
+import { API_ENDPOINTS } from "../../constants/API_ENDPOINTS";
+import { InternalError } from "../../errors";
+
+import { BaseManager } from "../BaseManager";
+
+const SLICE_SIMULATOR_LOAD_TIMEOUT = 10_000; // ms
+const SLICE_SIMULATOR_ROOT_SELECTOR = "#root";
+
+const DEFAULT_SCREENSHOT_VIEWPORT: Viewport = {
+	width: 1200,
+	height: 800,
+};
+
+export function assertS3ACLInitialized(
+	s3ACL: S3ACL | undefined,
+): asserts s3ACL is NonNullable<typeof s3ACL> {
+	if (s3ACL == undefined) {
+		throw new Error(
+			"An S3 ACL has not been initialized. Run `SliceMachineManager.screenshots.prototype.initS3ACL()` before re-calling this method.",
+		);
+	}
+}
+
+export function assertBrowserContextInitialized(
+	browserContext: BrowserContext | undefined,
+): asserts browserContext is NonNullable<typeof browserContext> {
+	if (browserContext == undefined) {
+		throw new Error(
+			"A browser context has not been initialized. Run `SliceMachineManager.screenshots.prototype.initBrowserContext()` before re-calling this method.",
+		);
+	}
+}
+
+type ScreenshotsManagerCaptureSliceSimulatorScreenshotArgs = {
+	libraryID: string;
+	sliceID: string;
+	variationID: string;
+	viewport?: Viewport;
+};
+
+type ScreenshotsManagerCaptureSliceSimulatorScreenshotReturnType = {
+	data: Buffer;
+};
+
+type ScreenshotsManagerUploadScreenshotArgs = {
+	data: Buffer;
+	keyPrefix?: string;
+};
+
+type ScreenshotsManagerUploadScreenshotReturnType = {
+	url: string;
+};
+
+export class ScreenshotsManager extends BaseManager {
+	private _browserContext: BrowserContext | undefined;
+	private _s3ACL: S3ACL | undefined;
+
+	async initBrowserContext(): Promise<void> {
+		if (this._browserContext) {
+			return;
+		}
+
+		let puppeteer: typeof import("puppeteer");
+		try {
+			// Lazy-load Puppeteer only once it is needed.
+			puppeteer = await import("puppeteer");
+		} catch {
+			throw new InternalError(
+				"Screenshots require Puppeteer but Puppeteer was not found. Check that the `puppeteer` package is installed before trying again.",
+			);
+		}
+
+		const browser = await puppeteer.launch();
+
+		this._browserContext = await browser.createIncognitoBrowserContext();
+	}
+
+	async initS3ACL(): Promise<void> {
+		if (this._s3ACL) {
+			return;
+		}
+
+		const sliceMachineConfig = await this.project.getSliceMachineConfig();
+		const authenticationToken = await this.user.getAuthenticationToken();
+
+		const awsACLURL = new URL("create", API_ENDPOINTS.AwsAclProvider);
+		const awsACLRes = await fetch(awsACLURL.toString(), {
+			headers: {
+				Authorization: `Bearer ${authenticationToken}`,
+				"User-Agent": SLICE_MACHINE_USER_AGENT,
+				Repository: sliceMachineConfig.repositoryName,
+			},
+		});
+		const awsACLJSON = await awsACLRes.json();
+
+		const { value: awsACL, error } = decode(
+			t.intersection([
+				t.type({
+					values: t.type({
+						url: t.string,
+						fields: t.record(t.string, t.string),
+					}),
+					imgixEndpoint: t.string,
+				}),
+				t.partial({
+					message: t.string,
+					Message: t.string,
+					error: t.string,
+				}),
+			]),
+			awsACLJSON,
+		);
+
+		if (error) {
+			throw new Error(`Invalid AWS ACL response from ${awsACLURL}`);
+		}
+
+		const errorMessage = awsACL.error || awsACL.message || awsACL.Message;
+		if (errorMessage) {
+			throw new Error(`Failed to create an AWS ACL: ${errorMessage}`);
+		}
+
+		this._s3ACL = {
+			uploadEndpoint: awsACL.values.url,
+			requiredFormDataFields: awsACL.values.fields,
+			imgixEndpoint: awsACL.imgixEndpoint,
+		};
+	}
+
+	// TODO: Abstract to a generic `captureScreenshot()` method that is
+	// used within a Slice-specific method in SliceManager.
+	async captureSliceSimulatorScreenshot(
+		args: ScreenshotsManagerCaptureSliceSimulatorScreenshotArgs,
+	): Promise<ScreenshotsManagerCaptureSliceSimulatorScreenshotReturnType> {
+		assertBrowserContextInitialized(this._browserContext);
+
+		const sliceMachineConfig = await this.project.getSliceMachineConfig();
+
+		if (!sliceMachineConfig.localSliceSimulatorURL) {
+			// TODO: Provide a more helpful error message.
+			throw new Error(
+				"A local Slice Simulator URL must be configured in your Slice Machine configuration file.",
+			);
+		}
+
+		const url = new URL(sliceMachineConfig.localSliceSimulatorURL);
+		url.searchParams.set("lid", args.libraryID);
+		url.searchParams.set("sid", args.sliceID);
+		url.searchParams.set("vid", args.variationID);
+
+		const isURLAccessible = await checkIsURLAccessible(url.toString());
+
+		if (!isURLAccessible) {
+			throw new Error(`Slice Simulator URL is not accessible: ${url}`);
+		}
+
+		const page = await this._browserContext.newPage();
+		page.setViewport(args.viewport || DEFAULT_SCREENSHOT_VIEWPORT);
+
+		// TODO: I removed `goto`'s `{ waitUntil: "networkidle2" }` option.
+		// Good idea? Bad idea?
+		await page.goto(url.toString());
+		await page.waitForSelector(SLICE_SIMULATOR_ROOT_SELECTOR, {
+			timeout: SLICE_SIMULATOR_LOAD_TIMEOUT,
+		});
+
+		const element = await page.$(SLICE_SIMULATOR_ROOT_SELECTOR);
+		if (!element) {
+			const baseURL = new URL(url.pathname, url.origin);
+
+			throw new Error(
+				`Slice Simulator could not find the element to screenshot. Verify the URL is correct: ${baseURL}`,
+			);
+		}
+
+		const data = (await element.screenshot({ encoding: "binary" })) as Buffer;
+
+		return {
+			data,
+		};
+	}
+
+	async uploadScreenshot(
+		args: ScreenshotsManagerUploadScreenshotArgs,
+	): Promise<ScreenshotsManagerUploadScreenshotReturnType> {
+		assertS3ACLInitialized(this._s3ACL);
+
+		const formData = new FormData();
+
+		for (const requiredFormDataFieldKey in this._s3ACL.requiredFormDataFields) {
+			formData.append(
+				requiredFormDataFieldKey,
+				this._s3ACL.requiredFormDataFields[requiredFormDataFieldKey],
+			);
+		}
+
+		const contentDigest = createContentDigest(args.data);
+		const fileType = await fileTypeFromBuffer(args.data);
+		const fileName = fileType
+			? `${contentDigest}.${fileType.ext}`
+			: contentDigest;
+		const key = args.keyPrefix ? `${args.keyPrefix}/${fileName}` : fileName;
+
+		formData.set("key", key);
+
+		if (fileType) {
+			formData.set("Content-Type", fileType.mime);
+		}
+
+		formData.set("file", new Blob([args.data], { type: fileType?.mime }));
+
+		const res = await fetch(this._s3ACL.uploadEndpoint, {
+			method: "POST",
+			body: formData,
+		});
+
+		if (res.ok) {
+			const url = new URL(key, this._s3ACL.imgixEndpoint);
+			url.searchParams.set("auto", "compress,format");
+
+			return {
+				url: url.toString(),
+			};
+		} else {
+			throw new Error(
+				`Unable to upload screenshot with status code: ${res.status}`,
+			);
+		}
+	}
+}

package/src/managers/simulator/SimulatorManager.ts

@@ -0,0 +1,151 @@
+import * as t from "io-ts";
+import { HookError } from "@slicemachine/plugin-kit";
+import fetch from "node-fetch";
+
+import { DecodeError } from "../../lib/DecodeError";
+import { assertPluginsInitialized } from "../../lib/assertPluginsInitialized";
+import { castArray } from "../../lib/castArray";
+import { decode } from "../../lib/decode";
+import { decodeHookResult } from "../../lib/decodeHookResult";
+import { functionCodec } from "../../lib/functionCodec";
+import { markdownToHTML } from "../../lib/markdownToHTML";
+
+import { UnexpectedDataError } from "../../errors";
+
+import { BaseManager } from "../BaseManager";
+
+const sliceSimulatorSetupStepCodec = t.intersection([
+	t.type({
+		title: t.string,
+		body: t.string,
+	}),
+	t.partial({
+		description: t.string,
+		validate: functionCodec,
+	}),
+]);
+
+const SliceSimulatorSetupStepValidationMessageCodec = t.type({
+	title: t.string,
+	message: t.string,
+});
+type SliceSimulatorSetupStepValidationMessageCodec = t.TypeOf<
+	typeof SliceSimulatorSetupStepValidationMessageCodec
+>;
+
+export type SimulatorManagerReadSliceSimulatorSetupStep = {
+	title: string;
+	description?: string;
+	body: string;
+	/**
+	 * Determines if the step is completed.
+	 *
+	 * This proeprty is `undefined` if the project's adapter does not provide a
+	 * validation function for the step; we cannot know if the step is complete
+	 * without a validator.
+	 */
+	isComplete: boolean | undefined;
+	validationMessages: SliceSimulatorSetupStepValidationMessageCodec[];
+};
+
+export type SimulatorManagerReadSliceSimulatorSetupStepsReturnType = {
+	steps: SimulatorManagerReadSliceSimulatorSetupStep[];
+	errors: (DecodeError | HookError)[];
+};
+
+export class SimulatorManager extends BaseManager {
+	async getLocalSliceSimulatorURL(): Promise<string | undefined> {
+		const sliceMachineConfig = await this.project.getSliceMachineConfig();
+
+		return sliceMachineConfig.localSliceSimulatorURL;
+	}
+
+	/**
+	 * @throws {@link UnexpectedDataError} Thrown if the project is not configured
+	 *   with a Slice Simulator URL.
+	 */
+	async checkIsLocalSliceSimulatorURLAccessible(): Promise<boolean> {
+		const localSliceSimulatorURL = await this.getLocalSliceSimulatorURL();
+
+		if (!localSliceSimulatorURL) {
+			throw new UnexpectedDataError(
+				"The project has not been configured with a Slice Simulator URL. Add a `localSliceSimulatorURL` property to your project's configuration to fix this error.",
+			);
+		}
+
+		const res = await fetch(localSliceSimulatorURL);
+
+		return res.ok;
+	}
+
+	async readSliceSimulatorSetupSteps(): Promise<SimulatorManagerReadSliceSimulatorSetupStepsReturnType> {
+		assertPluginsInitialized(this.sliceMachinePluginRunner);
+
+		const hookResult = await this.sliceMachinePluginRunner.callHook(
+			"slice-simulator:setup:read",
+			undefined,
+		);
+		const { data, errors } = decodeHookResult(
+			t.array(sliceSimulatorSetupStepCodec),
+			hookResult,
+		);
+
+		const steps = await Promise.all(
+			data[0].map(async (step) => {
+				const bodyHTML = await markdownToHTML(step.body);
+
+				const res: SimulatorManagerReadSliceSimulatorSetupStep = {
+					title: step.title,
+					description: step.description,
+					body: bodyHTML,
+					isComplete: undefined,
+					validationMessages: [],
+				};
+
+				if (step.validate) {
+					const validationResult = await step.validate();
+					const { value: validationMessages, error } = decode(
+						t.array(SliceSimulatorSetupStepValidationMessageCodec),
+						validationResult == null ? [] : castArray(validationResult),
+					);
+
+					if (error) {
+						// TODO: We may want to do
+						// something with the error,
+						// like log to the console.
+						// This branch should only be
+						// reached if the adapter
+						// returns invalid data.
+
+						return res;
+					}
+
+					const isComplete = validationMessages.length < 1;
+
+					const processedValidationMessages = await Promise.all(
+						validationMessages.map(async (validationMessage) => {
+							const messageHTML = await markdownToHTML(
+								validationMessage.message,
+							);
+
+							return {
+								...validationMessage,
+								message: messageHTML,
+							};
+						}),
+					);
+
+					res.isComplete = isComplete;
+					res.validationMessages = processedValidationMessages;
+				}
+
+				return res;
+			}),
+		);
+
+		return {
+			steps,
+			errors,
+		};
+	}
+}