@slicemachine/manager 0.0.0-alpha.dev-new-release-process.1

package/src/errors.ts

@@ -0,0 +1,85 @@
+import { HookError } from "@slicemachine/plugin-kit";
+
+export class SliceMachineError extends Error {
+	_sliceMachineError = true;
+	name = "SliceMachineError";
+}
+export class UnauthorizedError extends SliceMachineError {
+	name = "UnauthorizedError";
+}
+export class UnauthenticatedError extends SliceMachineError {
+	name = "UnauthenticatedError";
+	message = "Authenticate before trying again.";
+}
+export class NotFoundError extends SliceMachineError {
+	name = "NotFoundError";
+}
+export class UnexpectedDataError extends SliceMachineError {
+	name = "UnexpectedDataError";
+}
+export class InternalError extends SliceMachineError {
+	name = "InternalError";
+}
+export class PluginError extends SliceMachineError {
+	name = "PluginError";
+}
+export class PluginHookResultError extends SliceMachineError {
+	name = "PluginHookResultError";
+
+	constructor(errors: HookError[]) {
+		super(
+			`${errors.length} error${
+				errors.length === 1 ? "" : "s"
+			} were returned by one or more plugins.`,
+			{
+				cause: errors,
+			},
+		);
+	}
+}
+
+export const isSliceMachineError = (
+	error: unknown,
+): error is SliceMachineError => {
+	// TODO: Discuss a stronger way to serialize error for the client to detect with r19
+	// @ts-expect-error We don't want to add "dom" to tsconfig "lib" because of the TODO
+	if (typeof window !== "undefined") {
+		return typeof error === "object" && error !== null;
+	} else {
+		return (
+			typeof error === "object" &&
+			error !== null &&
+			"_sliceMachineError" in error
+		);
+	}
+};
+
+export const isUnauthorizedError = (
+	error: unknown,
+): error is UnauthorizedError => {
+	return isSliceMachineError(error) && error.name === UnauthorizedError.name;
+};
+
+export const isUnauthenticatedError = (
+	error: unknown,
+): error is UnauthenticatedError => {
+	return isSliceMachineError(error) && error.name === UnauthenticatedError.name;
+};
+
+export const isNotFoundError = (error: unknown): error is NotFoundError => {
+	return isSliceMachineError(error) && error.name === NotFoundError.name;
+};
+
+export const isUnexpectedDataError = (
+	error: unknown,
+): error is UnexpectedDataError => {
+	return isSliceMachineError(error) && error.name === UnexpectedDataError.name;
+};
+
+export const isInternalError = (error: unknown): error is InternalError => {
+	return isSliceMachineError(error) && error.name === InternalError.name;
+};
+
+export const isPluginError = (error: unknown): error is PluginError => {
+	return isSliceMachineError(error) && error.name === PluginError.name;
+};

package/src/index.ts

@@ -0,0 +1,46 @@
+// This file defines the root `@slicemachine/manager` export.
+// Non-Node.js-compatible exports should be defined in `./client.ts`.
+
+export type { CustomTypeFormat } from "./managers/customTypes/types";
+export type {
+	PrismicRepository,
+	FrameworkWroomTelemetryID,
+	StarterId,
+} from "./managers/prismicRepository/types";
+
+export type { SliceMachineManager } from "./managers/SliceMachineManager";
+export { createSliceMachineManager } from "./managers/createSliceMachineManager";
+export { createSliceMachineManagerMiddleware } from "./managers/createSliceMachineManagerMiddleware";
+export type { CreateSliceMachineManagerMiddlewareArgs } from "./managers/createSliceMachineManagerMiddleware";
+
+export type { Environment } from "./managers/prismicRepository/types";
+
+export type {
+	PrismicAuthManager,
+	PrismicUserProfile,
+	PrismicAuthState,
+} from "./auth/PrismicAuthManager";
+export { createPrismicAuthManager } from "./auth/createPrismicAuthManager";
+export { createPrismicAuthManagerMiddleware } from "./auth/createPrismicAuthManagerMiddleware";
+export type {
+	CreatePrismicAuthManagerMiddlewareArgs,
+	PrismicAuthCheckStatusResponse,
+} from "./auth/createPrismicAuthManagerMiddleware";
+
+export {
+	SliceMachineError,
+	UnauthorizedError,
+	UnauthenticatedError,
+	NotFoundError,
+	UnexpectedDataError,
+	InternalError,
+	PluginError,
+	PluginHookResultError,
+} from "./errors";
+
+export { DecodeError } from "./lib/DecodeError";
+
+export type { SliceMachineConfig, PackageManager } from "./types";
+export type { APIEndpoints } from "./constants/API_ENDPOINTS";
+
+export { REPOSITORY_NAME_VALIDATION } from "./constants/REPOSITORY_NAME_VALIDATION";

package/src/lib/DecodeError.ts

@@ -0,0 +1,22 @@
+import * as t from "io-ts";
+import { formatValidationErrors } from "io-ts-reporters";
+
+type DecodeErrorConstructorArgs<TInput = unknown> = {
+	input: TInput;
+	errors: t.Errors;
+};
+
+export class DecodeError<TInput = unknown> extends Error {
+	name = "DecodeError";
+	input: TInput;
+	errors: string[];
+
+	constructor(args: DecodeErrorConstructorArgs<TInput>) {
+		const formattedErrors = formatValidationErrors(args.errors);
+
+		super(formattedErrors.join(", "));
+
+		this.input = args.input;
+		this.errors = formattedErrors;
+	}
+}

package/src/lib/assertPluginsInitialized.ts

@@ -0,0 +1,11 @@
+import { SliceMachinePluginRunner } from "@slicemachine/plugin-kit";
+
+export function assertPluginsInitialized(
+	pluginRunner: SliceMachinePluginRunner | undefined,
+): asserts pluginRunner is NonNullable<typeof pluginRunner> {
+	if (pluginRunner == undefined) {
+		throw new Error(
+			"Plugins have not been initialized. Run `SliceMachineManager.plugins.prototype.initPlugins()` before re-calling this method.",
+		);
+	}
+}

package/src/lib/bufferCodec.ts

@@ -0,0 +1,10 @@
+import { Buffer } from "node:buffer";
+import * as t from "io-ts";
+
+export const bufferCodec = new t.Type<Buffer, Buffer, unknown>(
+	"Buffer",
+	(input): input is Buffer => Buffer.isBuffer(input),
+	(input, context) =>
+		Buffer.isBuffer(input) ? t.success(input) : t.failure(input, context),
+	t.identity,
+);

package/src/lib/buildPrismicRepositoryAPIEndpoint.ts

@@ -0,0 +1,16 @@
+import { API_ENDPOINTS } from "../constants/API_ENDPOINTS";
+
+export type BuildPrismicRepositoryAPIEndpointConfig = {
+	withCDN?: boolean;
+};
+
+export const buildPrismicRepositoryAPIEndpoint = (
+	repositoryName: string,
+	{ withCDN = true }: BuildPrismicRepositoryAPIEndpointConfig = {},
+): string => {
+	const baseEndpoint = new URL(API_ENDPOINTS.PrismicWroom);
+
+	return `${baseEndpoint.protocol}//${repositoryName}${withCDN ? ".cdn" : ""}.${
+		baseEndpoint.host
+	}/api/v2`;
+};

package/src/lib/castArray.ts

@@ -0,0 +1,3 @@
+export const castArray = <T>(input: T | readonly T[]): T[] => {
+	return Array.isArray(input) ? input : ([input] as T[]);
+};

package/src/lib/checkIsURLAccessible.ts

@@ -0,0 +1,7 @@
+import fetch from "./fetch";
+
+export const checkIsURLAccessible = async (url: string): Promise<boolean> => {
+	const res = await fetch(url);
+
+	return res.ok;
+};

package/src/lib/createContentDigest.ts

@@ -0,0 +1,12 @@
+import * as crypto from "node:crypto";
+
+/**
+ * Creates a content digest for a given input.
+ *
+ * @param input - The value used to create a digest digest.
+ *
+ * @returns The content digest of `input`.
+ */
+export const createContentDigest = (input: crypto.BinaryLike): string => {
+	return crypto.createHash("sha1").update(input).digest("hex");
+};

package/src/lib/decode.ts

@@ -0,0 +1,36 @@
+import * as t from "io-ts";
+import * as E from "fp-ts/Either";
+import { pipe } from "fp-ts/function";
+
+import { DecodeError } from "./DecodeError";
+
+export type DecodeReturnType<A, _O, I> =
+	| {
+			value: A;
+			error?: never;
+	  }
+	| {
+			value?: never;
+			error: DecodeError<I>;
+	  };
+
+export const decode = <A, O, I>(
+	codec: t.Type<A, O, I>,
+	input: I,
+): DecodeReturnType<A, O, I> => {
+	return pipe(
+		codec.decode(input),
+		E.foldW(
+			(errors) => {
+				return {
+					error: new DecodeError({ input, errors }),
+				};
+			},
+			(value) => {
+				return {
+					value,
+				};
+			},
+		),
+	);
+};

package/src/lib/decodeHookResult.ts

@@ -0,0 +1,36 @@
+import * as t from "io-ts";
+import { CallHookReturnType, HookError } from "@slicemachine/plugin-kit";
+
+import { DecodeError } from "./DecodeError";
+import { decode } from "./decode";
+
+export const decodeHookResult = <
+	A,
+	O,
+	I,
+	THookResult extends Awaited<CallHookReturnType>,
+>(
+	codec: t.Type<A, O, I>,
+	hookResult: THookResult,
+): {
+	data: A[];
+	errors: (HookError | DecodeError<I>)[];
+} => {
+	const data: A[] = [];
+	const errors: DecodeError<I>[] = [];
+
+	for (const dataElement of hookResult.data) {
+		const { value, error } = decode(codec, dataElement);
+
+		if (error) {
+			errors.push(error);
+		} else {
+			data.push(value);
+		}
+	}
+
+	return {
+		data,
+		errors: [...errors, ...hookResult.errors],
+	};
+};

package/src/lib/decodePackageJSON.ts

@@ -0,0 +1,18 @@
+import * as t from "io-ts";
+
+import { decode, DecodeReturnType } from "./decode";
+
+/**
+ * A minimally defined codec for package.json files. Only data needed for
+ * version detection is defined.
+ */
+const PackageJSONCodec = t.type({
+	version: t.string,
+});
+type PackageJSON = t.TypeOf<typeof PackageJSONCodec>;
+
+export const decodePackageJSON = (
+	input: unknown,
+): DecodeReturnType<PackageJSON, PackageJSON, unknown> => {
+	return decode(PackageJSONCodec, input);
+};

package/src/lib/decodeSliceMachineConfig.ts

@@ -0,0 +1,39 @@
+import * as t from "io-ts";
+
+import { SliceMachineConfig } from "../types";
+
+import { decode, DecodeReturnType } from "./decode";
+
+const SliceMachineConfigPluginRegistrationCodec = t.union([
+	t.string,
+	t.intersection([
+		t.type({
+			resolve: t.string,
+		}),
+		t.partial({
+			options: t.UnknownRecord,
+		}),
+	]),
+]);
+
+const SliceMachineConfigCodec = t.intersection([
+	t.type({
+		repositoryName: t.string,
+		adapter: SliceMachineConfigPluginRegistrationCodec,
+	}),
+	t.partial({
+		apiEndpoint: t.string,
+		libraries: t.array(t.string),
+		localSliceSimulatorURL: t.string,
+		plugins: t.array(SliceMachineConfigPluginRegistrationCodec),
+		labs: t.partial({ legacySliceUpgrader: t.boolean }),
+	}),
+]);
+
+// TODO: Maybe rename "decode" to "validate". "decode" exposes the `io-ts`
+// internals.
+export const decodeSliceMachineConfig = (
+	input: unknown,
+): DecodeReturnType<SliceMachineConfig, SliceMachineConfig, unknown> => {
+	return decode(SliceMachineConfigCodec, input);
+};

package/src/lib/fetch.ts

@@ -0,0 +1,46 @@
+// This temporary wrapper around `node-fetch` fixes an issue where quick
+// consecutive network requests cause failed requests.
+//
+// See https://github.com/node-fetch/node-fetch/issues/1735 for more details.
+//
+// TODO: Remove this wrapper and replace all imports with `node-fetch` if https://github.com/node-fetch/node-fetch/pull/1736 is merged.
+
+import * as http from "node:http";
+import * as https from "node:https";
+import baseFetch from "node-fetch";
+
+export * from "node-fetch";
+
+/**
+ * The default HTTP Agent with `keepAlive: true` used in `fetch()` requests.
+ */
+const DEFAULT_HTTP_AGENT = new http.Agent({ keepAlive: true });
+
+/**
+ * The default HTTPS Agent with `keepAlive: true` used in `fetch()` requests.
+ */
+const DEFAULT_HTTPS_AGENT = new https.Agent({ keepAlive: true });
+
+/**
+ * Patched `fetch()` from `node-fetch` that fixes a bug where quick consecutive
+ * network requests cause failed requests.
+ *
+ * Use this `fetch()` in place of `node-fetch`'s `fetch()`.
+ *
+ * @remarks
+ * `fetch()` is patched by setting an HTTP/HTTPS Agent with `keepAlive: true`.
+ * If you need to assign an Agent, be sure to retain the `keepAlive: true`
+ * option.
+ */
+const fetch: typeof baseFetch = (url, init) => {
+	return baseFetch(url, {
+		agent: (parsedURL) => {
+			return parsedURL.protocol === "http:"
+				? DEFAULT_HTTP_AGENT
+				: DEFAULT_HTTPS_AGENT;
+		},
+		...init,
+	});
+};
+
+export default fetch;

package/src/lib/fetchGitHubReleaseBodyForRelease.ts

@@ -0,0 +1,146 @@
+import * as t from "io-ts";
+import fetch from "./fetch";
+import pLimit from "p-limit";
+
+import { decode } from "./decode";
+
+const GITHUB_JSON_ACCEPT_HEADER = "application/vnd.github+json";
+
+/**
+ * A minimally defined codec for GitHub release metadata.
+ *
+ * @see https://docs.github.com/en/rest/releases/releases#get-a-release-by-tag-name
+ */
+const GitHubReleaseMetadata = t.type({
+	name: t.string,
+	body: t.union([t.null, t.string]),
+});
+export type GitHubReleaseMetadata = t.TypeOf<typeof GitHubReleaseMetadata>;
+
+type FetchAllGitHubReleasesArgs = {
+	repositoryOwner: string;
+	repositoryName: string;
+};
+
+const fetchAllGitHubReleases = async (
+	args: FetchAllGitHubReleasesArgs,
+): Promise<GitHubReleaseMetadata[]> => {
+	const res = await fetch(
+		`https://api.github.com/repos/${args.repositoryOwner}/${args.repositoryName}/releases`,
+		{
+			headers: {
+				Accept: GITHUB_JSON_ACCEPT_HEADER,
+			},
+		},
+	);
+
+	if (res.ok) {
+		const json = await res.json();
+
+		const { value, error } = decode(t.array(GitHubReleaseMetadata), json);
+
+		if (error) {
+			throw new Error(`Invalid GitHub Release response.`, { cause: error });
+		}
+
+		return value;
+	} else {
+		const text = await res.text();
+		throw new Error(`Invalid GitHub Release response.`, {
+			cause: text,
+		});
+	}
+};
+
+type FetchGitHubReleaseByVersionArgs = {
+	repositoryOwner: string;
+	repositoryName: string;
+	packageName?: string;
+	version: string;
+};
+
+const fetchGitHubReleaseByVersion = async (
+	args: FetchGitHubReleaseByVersionArgs,
+): Promise<GitHubReleaseMetadata | undefined> => {
+	let url: string;
+
+	if (args.packageName) {
+		url = `https://api.github.com/repos/${args.repositoryOwner}/${args.repositoryName}/releases/tags/${args.packageName}@${args.version}`;
+	} else {
+		url = `https://api.github.com/repos/${args.repositoryOwner}/${args.repositoryName}/releases/tags/${args.version}`;
+	}
+
+	const res = await fetch(url, {
+		headers: {
+			Accept: GITHUB_JSON_ACCEPT_HEADER,
+		},
+	});
+
+	if (res.ok) {
+		const json = await res.json();
+
+		const { value, error } = decode(GitHubReleaseMetadata, json);
+
+		if (error) {
+			throw new Error(`Invalid GitHub Release response.`, { cause: error });
+		}
+
+		return value;
+	}
+};
+
+type FetchGitHubReleaseBodyForReleaseArgs = {
+	repositoryOwner: string;
+	repositoryName: string;
+	packageName?: string;
+	version: string;
+	cache?: Record<string, GitHubReleaseMetadata | undefined>;
+};
+
+const _fetchGitHubReleaseBodyForRelease = async (
+	args: FetchGitHubReleaseBodyForReleaseArgs,
+): Promise<string | undefined> => {
+	const cache = args.cache || {};
+
+	if (Object.keys(cache).length < 1) {
+		const releases = await fetchAllGitHubReleases({
+			repositoryOwner: args.repositoryOwner,
+			repositoryName: args.repositoryName,
+		});
+
+		for (const release of releases) {
+			cache[release.name] = release;
+		}
+	}
+
+	if (args.version in cache) {
+		const release = cache[args.version];
+
+		return release?.body ?? undefined;
+	} else {
+		try {
+			const version = await fetchGitHubReleaseByVersion({
+				repositoryOwner: args.repositoryOwner,
+				repositoryName: args.repositoryName,
+				packageName: args.packageName,
+				version: args.version,
+			});
+
+			cache[args.version] = version;
+
+			return version?.body ?? undefined;
+		} catch {
+			cache[args.version] = undefined;
+
+			return undefined;
+		}
+	}
+};
+
+const limit = pLimit(1);
+
+export const fetchGitHubReleaseBodyForRelease = async (
+	...args: Parameters<typeof _fetchGitHubReleaseBodyForRelease>
+): ReturnType<typeof _fetchGitHubReleaseBodyForRelease> => {
+	return await limit(() => _fetchGitHubReleaseBodyForRelease(...args));
+};

package/src/lib/fetchNPMPackageVersions.ts

@@ -0,0 +1,46 @@
+import * as t from "io-ts";
+import fetch from "./fetch";
+
+import { decode } from "./decode";
+
+/**
+ * The Accept header value used when only metadata required for package
+ * installation is needed. The response includes all versions and some of their
+ * metadata.
+ *
+ * @see https://github.com/npm/registry/blob/cfe04736f34db9274a780184d1cdb2fb3e4ead2a/docs/responses/package-metadata.md#package-metadata
+ */
+const NPM_REGISTRY_ABBREVIATED_METADATA_ACCEPT_HEADER =
+	"application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*";
+
+/**
+ * A minimally defined codec for NPM registry package metadata. Only data needed
+ * for version detection is defined.
+ */
+const NPMRegistryPackageMetadataCodec = t.type({
+	versions: t.UnknownRecord,
+});
+
+type FetchNPMPackageVersionsArgs = {
+	packageName: string;
+};
+
+export const fetchNPMPackageVersions = async (
+	args: FetchNPMPackageVersionsArgs,
+): Promise<string[]> => {
+	const res = await fetch(`https://registry.npmjs.org/${args.packageName}`, {
+		headers: {
+			Accept: NPM_REGISTRY_ABBREVIATED_METADATA_ACCEPT_HEADER,
+		},
+	});
+
+	const json = await res.json();
+
+	const { value, error } = decode(NPMRegistryPackageMetadataCodec, json);
+
+	if (error) {
+		throw new Error(`Invalid NPM registry response.`, { cause: error });
+	}
+
+	return Object.keys(value.versions);
+};

package/src/lib/format.ts

@@ -0,0 +1,34 @@
+import prettier from "prettier";
+import { stripIndent } from "common-tags";
+
+type FormatOptions = {
+	prettier?: prettier.Options;
+	/**
+	 * Determines if a newline is included at the end of the formatted result.
+	 *
+	 * @defaultValue `true`
+	 */
+	includeNewlineAtEnd?: boolean;
+};
+
+export const format = async (
+	source: string,
+	filePath: string,
+	options?: FormatOptions,
+): Promise<string> => {
+	let formatted = stripIndent(source);
+
+	const prettierOptions = await prettier.resolveConfig(filePath);
+
+	formatted = await prettier.format(formatted, {
+		...prettierOptions,
+		filepath: filePath,
+		...(options?.prettier ?? {}),
+	});
+
+	if (options?.includeNewlineAtEnd === false) {
+		formatted.replace(/[\r\n]+$/, "");
+	}
+
+	return formatted;
+};

package/src/lib/functionCodec.ts

@@ -0,0 +1,16 @@
+import * as t from "io-ts";
+
+export const functionCodec = new t.Type<
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	Function,
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	Function,
+	unknown
+>(
+	"function",
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	(input: unknown): input is Function => typeof input === "function",
+	(input, context) =>
+		typeof input === "function" ? t.success(input) : t.failure(input, context),
+	t.identity,
+);