@prismicio/plugin-kit 0.0.1

package/src/createPluginSystemRunner.ts

@@ -0,0 +1,216 @@
+import _module from "node:module";
+
+import { defu } from "defu";
+
+import { createPluginHookSystem } from "./createPluginHookSystem";
+import {
+	createPluginSystemActions,
+	PluginSystemActions,
+} from "./createPluginSystemActions";
+import { createPluginSystemContext } from "./createPluginSystemContext";
+import {
+	createPluginSystemHelpers,
+	PluginSystemHelpers,
+} from "./createPluginSystemHelpers";
+import { LoadedPlugin, Plugin } from "./definePlugin";
+import { HookSystem } from "./lib/HookSystem";
+import {
+	PrismicConfigPluginRegistration,
+	PluginHookExtraArgs,
+	PluginHookTypes,
+	PluginHooks,
+	PrismicProject,
+} from "./types";
+
+/**
+ * @internal
+ */
+export const REQUIRED_ADAPTER_HOOKS: PluginHookTypes[] = [
+	"slice:create",
+	"slice:read",
+	"slice:rename",
+	"slice:delete",
+	"slice:update",
+	"slice-library:read",
+	"custom-type:create",
+	"custom-type:read",
+	"custom-type:rename",
+	"custom-type:delete",
+	"custom-type:update",
+	"custom-type-library:read",
+];
+
+type PluginSystemRunnerConstructorArgs = {
+	project: PrismicProject;
+	hookSystem: HookSystem<PluginHooks>;
+	nativePlugins: Record<string, Plugin>;
+};
+
+/**
+ * @internal
+ */
+export class PluginSystemRunner {
+	private _project: PrismicProject;
+	private _hookSystem: HookSystem<PluginHooks>;
+	private _nativePlugins: Record<string, Plugin>;
+
+	/**
+	 * Plugin System actions provided to hooks.
+	 *
+	 * IMPORTANT: Prefer creating your own abstraction over using `rawActions`
+	 * directly to prevent code breakage if this internal API changes.
+	 *
+	 * @internal
+	 */
+	rawActions: PluginSystemActions;
+
+	/**
+	 * Plugin System helpers provided to hooks.
+	 *
+	 * IMPORTANT: Prefer creating your own abstraction over using `rawHelpers`
+	 * directly to prevent code breakage if this internal API changes.
+	 *
+	 * @internal
+	 */
+	rawHelpers: PluginSystemHelpers;
+
+	// Methods forwarded to the plugin runner's hook system.
+	callHook: HookSystem<PluginHooks>["callHook"];
+	hooksForOwner: HookSystem<PluginHooks>["hooksForOwner"];
+	hooksForType: HookSystem<PluginHooks>["hooksForType"];
+	createScope: HookSystem<PluginHooks>["createScope"];
+
+	constructor({
+		project,
+		hookSystem,
+		nativePlugins,
+	}: PluginSystemRunnerConstructorArgs) {
+		this._project = project;
+		this._hookSystem = hookSystem;
+		this._nativePlugins = nativePlugins;
+
+		this.rawActions = createPluginSystemActions(
+			this._project,
+			this._hookSystem,
+		);
+		this.rawHelpers = createPluginSystemHelpers(this._project);
+
+		this.callHook = this._hookSystem.callHook.bind(this._hookSystem);
+		this.hooksForOwner = this._hookSystem.hooksForOwner.bind(this._hookSystem);
+		this.hooksForType = this._hookSystem.hooksForType.bind(this._hookSystem);
+		this.createScope = this._hookSystem.createScope.bind(this._hookSystem);
+	}
+
+	private async _loadPlugin(
+		pluginRegistration: PrismicConfigPluginRegistration,
+	): Promise<LoadedPlugin> {
+		// Sanitize registration
+		const { resolve, options = {} } =
+			typeof pluginRegistration === "object" && "resolve" in pluginRegistration
+				? pluginRegistration
+				: { resolve: pluginRegistration };
+
+		let plugin: Plugin | undefined = undefined;
+
+		if (typeof resolve === "string") {
+			plugin = this._nativePlugins[resolve];
+
+			if (!plugin) {
+				throw new Error(
+					`Could not resolve plugin \`${resolve}\`. Check that it has been installed.`,
+				);
+			}
+		} else {
+			plugin = resolve;
+		}
+
+		if (!plugin) {
+			throw new Error(`Could not load plugin: \`${resolve}\``);
+		}
+
+		const mergedOptions = defu(options, plugin.defaultOptions || {});
+
+		return {
+			...plugin,
+			resolve,
+			options: mergedOptions,
+		};
+	}
+
+	private async _setupPlugin(plugin: LoadedPlugin): Promise<void> {
+		const context = createPluginSystemContext({
+			actions: this.rawActions,
+			helpers: this.rawHelpers,
+			project: this._project,
+			plugin,
+		});
+		const hookSystemScope = this._hookSystem.createScope<PluginHookExtraArgs>(
+			plugin.meta.name,
+			[context],
+		);
+
+		// Run plugin setup with actions and context
+		try {
+			await plugin.setup({
+				...context,
+				hook: hookSystemScope.hook,
+				unhook: hookSystemScope.unhook,
+			});
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(
+					`Plugin \`${plugin.meta.name}\` errored during setup: ${error.message}`,
+					{ cause: error },
+				);
+			} else {
+				throw new Error(
+					`Plugin \`${plugin.meta.name}\` errored during setup: ${error}`,
+				);
+			}
+		}
+	}
+
+	private _validateAdapter(adapter: LoadedPlugin): void {
+		const hooks = this._hookSystem.hooksForOwner(adapter.meta.name);
+		const hookTypes = hooks.map((hook) => hook.meta.type);
+
+		const missingHooks = REQUIRED_ADAPTER_HOOKS.filter(
+			(requiredHookType) => !hookTypes.includes(requiredHookType),
+		);
+
+		if (missingHooks.length) {
+			throw new Error(
+				`Adapter \`${
+					adapter.meta.name
+				}\` is missing hooks: \`${missingHooks.join("`, `")}\``,
+			);
+		}
+	}
+
+	async init(): Promise<void> {
+		const adapter = await this._loadPlugin(this._project.config.adapter);
+		await this._setupPlugin(adapter);
+		this._validateAdapter(adapter);
+	}
+}
+
+type CreatePluginSystemRunnerArgs = {
+	project: PrismicProject;
+	nativePlugins: Record<string, Plugin>;
+};
+
+/**
+ * @internal
+ */
+export const createPluginSystemRunner = ({
+	project,
+	nativePlugins,
+}: CreatePluginSystemRunnerArgs): PluginSystemRunner => {
+	const hookSystem = createPluginHookSystem();
+
+	return new PluginSystemRunner({
+		project,
+		hookSystem,
+		nativePlugins,
+	});
+};

package/src/definePlugin.ts

@@ -0,0 +1,48 @@
+import { PluginSystemContext } from "./createPluginSystemContext";
+import { CreateScopeReturnType } from "./lib/HookSystem";
+import { PluginOptions, PluginHookExtraArgs, PluginHooks } from "./types";
+
+/**
+ * Plugin definition.
+ */
+export type Plugin<
+	TPluginOptions extends Record<string, unknown> = Record<string, unknown>,
+> = {
+	/**
+	 * Information about the plugin.
+	 */
+	meta: {
+		name: string;
+	};
+
+	/**
+	 * Default options.
+	 */
+	defaultOptions?: TPluginOptions;
+
+	/**
+	 * Plugin setup.
+	 */
+	setup: (
+		context: Omit<PluginSystemContext<TPluginOptions>, "actions"> &
+			Pick<
+				CreateScopeReturnType<PluginHooks, PluginHookExtraArgs<TPluginOptions>>,
+				"hook" | "unhook"
+			>,
+	) => void | Promise<void>;
+};
+
+/**
+ * @internal
+ */
+export type LoadedPlugin<TPluginOptions extends PluginOptions = PluginOptions> =
+	Plugin<TPluginOptions> & {
+		resolve: string | Plugin;
+		options: TPluginOptions;
+	};
+
+export const definePlugin = <
+	TPluginOptions extends PluginOptions = PluginOptions,
+>(
+	plugin: Plugin<TPluginOptions>,
+): Plugin<TPluginOptions> => plugin;

package/src/fs/buildCustomTypeDirectoryPath.ts

@@ -0,0 +1,19 @@
+import * as path from "node:path";
+
+import {
+	buildCustomTypeLibraryDirectoryPath,
+	BuildCustomTypeLibraryDirectoryPathArgs,
+} from "./buildCustomTypeLibraryDirectoryPath";
+
+export type BuildCustomTypeDirectoryPathArgs = {
+	customTypeID: string;
+} & BuildCustomTypeLibraryDirectoryPathArgs;
+
+export const buildCustomTypeDirectoryPath = (
+	args: BuildCustomTypeDirectoryPathArgs,
+): string => {
+	return path.join(
+		buildCustomTypeLibraryDirectoryPath(args),
+		args.customTypeID,
+	);
+};

package/src/fs/buildCustomTypeFilePath.ts

@@ -0,0 +1,16 @@
+import * as path from "node:path";
+
+import {
+	buildCustomTypeDirectoryPath,
+	BuildCustomTypeDirectoryPathArgs,
+} from "./buildCustomTypeDirectoryPath";
+
+export type BuildCustomTypeFilePathArgs = {
+	filename: string;
+} & BuildCustomTypeDirectoryPathArgs;
+
+export const buildCustomTypeFilePath = (
+	args: BuildCustomTypeFilePathArgs,
+): string => {
+	return path.join(buildCustomTypeDirectoryPath(args), args.filename);
+};

package/src/fs/buildCustomTypeLibraryDirectoryPath.ts

@@ -0,0 +1,16 @@
+import { PluginSystemHelpers } from "../createPluginSystemHelpers";
+
+import { CUSTOM_TYPES_LIBRARY_DIRNAME } from "./constants";
+
+export type BuildCustomTypeLibraryDirectoryPathArgs = {
+	absolute?: boolean;
+	helpers: PluginSystemHelpers;
+};
+
+export const buildCustomTypeLibraryDirectoryPath = (
+	args: BuildCustomTypeLibraryDirectoryPathArgs,
+): string => {
+	return args.absolute
+		? args.helpers.joinPathFromRoot(CUSTOM_TYPES_LIBRARY_DIRNAME)
+		: CUSTOM_TYPES_LIBRARY_DIRNAME;
+};

package/src/fs/buildSliceDirectoryPath.ts

@@ -0,0 +1,25 @@
+import * as path from "node:path";
+
+import {
+	buildSliceLibraryDirectoryPath,
+	BuildSliceLibraryDirectoryPathArgs,
+} from "./buildSliceLibraryDirectoryPath";
+import { pascalCase } from "./lib/pascalCase";
+import {
+	resolveSliceModel,
+	ResolveSliceModelArgs,
+} from "./lib/resolveSliceModel";
+
+export type BuildSliceDirectoryPathArgs = BuildSliceLibraryDirectoryPathArgs &
+	ResolveSliceModelArgs;
+
+export const buildSliceDirectoryPath = async (
+	args: BuildSliceDirectoryPathArgs,
+): Promise<string> => {
+	const model = await resolveSliceModel(args);
+
+	return path.join(
+		buildSliceLibraryDirectoryPath(args),
+		pascalCase(model.name),
+	);
+};

package/src/fs/buildSliceFilePath.ts

@@ -0,0 +1,16 @@
+import * as path from "node:path";
+
+import {
+	buildSliceDirectoryPath,
+	BuildSliceDirectoryPathArgs,
+} from "./buildSliceDirectoryPath";
+
+export type BuildSliceFilePathArgs = {
+	filename: string;
+} & BuildSliceDirectoryPathArgs;
+
+export const buildSliceFilePath = async (
+	args: BuildSliceFilePathArgs,
+): Promise<string> => {
+	return path.join(await buildSliceDirectoryPath(args), args.filename);
+};

package/src/fs/buildSliceLibraryDirectoryPath.ts

@@ -0,0 +1,17 @@
+import * as path from "node:path";
+
+import { PluginSystemHelpers } from "../createPluginSystemHelpers";
+
+export type BuildSliceLibraryDirectoryPathArgs = {
+	libraryID: string;
+	absolute?: boolean;
+	helpers: PluginSystemHelpers;
+};
+
+export const buildSliceLibraryDirectoryPath = (
+	args: BuildSliceLibraryDirectoryPathArgs,
+): string => {
+	return args.absolute
+		? args.helpers.joinPathFromRoot(args.libraryID)
+		: path.join(args.libraryID);
+};

package/src/fs/checkHasProjectFile.ts

@@ -0,0 +1,16 @@
+import { PluginSystemHelpers } from "../createPluginSystemHelpers";
+
+import { checkPathExists } from "./lib/checkPathExists";
+
+export type CheckHasProjectFileArgs = {
+	filename: string;
+	helpers: PluginSystemHelpers;
+};
+
+export const checkHasProjectFile = async (
+	args: CheckHasProjectFileArgs,
+): Promise<boolean> => {
+	const filePath = args.helpers.joinPathFromRoot(args.filename);
+
+	return checkPathExists(filePath);
+};

package/src/fs/checkIsTypeScriptProject.ts

@@ -0,0 +1,16 @@
+import {
+	checkHasProjectFile,
+	CheckHasProjectFileArgs,
+} from "./checkHasProjectFile";
+import { TSCONFIG_FILENAME } from "./constants";
+
+type CheckIsTypeScriptProjectArgs = Omit<CheckHasProjectFileArgs, "filename">;
+
+export const checkIsTypeScriptProject = async (
+	args: CheckIsTypeScriptProjectArgs,
+): Promise<boolean> => {
+	return checkHasProjectFile({
+		...args,
+		filename: TSCONFIG_FILENAME,
+	});
+};

package/src/fs/constants.ts

@@ -0,0 +1,15 @@
+/**
+ * Banner text added to files that should not be edited by users.
+ */
+export const NON_EDITABLE_FILE_BANNER =
+	"// Code generated by Prismic. DO NOT EDIT.";
+
+export const CUSTOM_TYPES_LIBRARY_DIRNAME = "customtypes";
+
+export const CUSTOM_TYPE_MODEL_FILENAME = "index.json";
+
+export const SHARED_SLICE_MODEL_FILENAME = "model.json";
+
+export const TSCONFIG_FILENAME = "tsconfig.json";
+
+export const GLOBAL_TYPESCRIPT_TYPES_FILENAME = "prismicio-types.d.ts";

package/src/fs/deleteCustomTypeDirectory.ts

@@ -0,0 +1,24 @@
+import {
+	buildCustomTypeDirectoryPath,
+	BuildCustomTypeDirectoryPathArgs,
+} from "./buildCustomTypeDirectoryPath";
+import { deleteProjectFile } from "./deleteProjectFile";
+
+export type DeleteCustomTypeDirectoryArgs = BuildCustomTypeDirectoryPathArgs;
+
+export const deleteCustomTypeDirectory = async (
+	args: DeleteCustomTypeDirectoryArgs,
+): Promise<string> => {
+	const dir = buildCustomTypeDirectoryPath(args);
+	const relativeDir = buildCustomTypeDirectoryPath({
+		...args,
+		absolute: false,
+	});
+
+	await deleteProjectFile({
+		filename: relativeDir,
+		helpers: args.helpers,
+	});
+
+	return dir;
+};

package/src/fs/deleteProjectFile.ts

@@ -0,0 +1,18 @@
+import { PluginSystemHelpers } from "../createPluginSystemHelpers";
+
+import * as fs from "./lib/fsLimit";
+
+export type DeleteProjectFileArgs = {
+	filename: string;
+	helpers: PluginSystemHelpers;
+};
+
+export const deleteProjectFile = async (
+	args: DeleteProjectFileArgs,
+): Promise<string> => {
+	const filePath = args.helpers.joinPathFromRoot(args.filename);
+
+	await fs.rm(filePath, { recursive: true });
+
+	return filePath;
+};

package/src/fs/deleteSliceDirectory.ts

@@ -0,0 +1,24 @@
+import {
+	buildSliceDirectoryPath,
+	BuildSliceDirectoryPathArgs,
+} from "./buildSliceDirectoryPath";
+import { deleteProjectFile } from "./deleteProjectFile";
+
+export type DeleteSliceDirectoryArgs = BuildSliceDirectoryPathArgs;
+
+export const deleteSliceDirectory = async (
+	args: DeleteSliceDirectoryArgs,
+): Promise<string> => {
+	const dir = await buildSliceDirectoryPath(args);
+	const relativeDir = await buildSliceDirectoryPath({
+		...args,
+		absolute: false,
+	});
+
+	await deleteProjectFile({
+		filename: relativeDir,
+		helpers: args.helpers,
+	});
+
+	return dir;
+};

package/src/fs/deleteSliceFile.ts

@@ -0,0 +1,24 @@
+import {
+	buildSliceFilePath,
+	BuildSliceFilePathArgs,
+} from "./buildSliceFilePath";
+import { deleteProjectFile } from "./deleteProjectFile";
+
+export type DeleteSliceFileArgs = BuildSliceFilePathArgs;
+
+export const deleteSliceFile = async (
+	args: DeleteSliceFileArgs,
+): Promise<string> => {
+	const filePath = await buildSliceFilePath(args);
+	const relativeFilePath = await buildSliceFilePath({
+		...args,
+		absolute: false,
+	});
+
+	await deleteProjectFile({
+		filename: relativeFilePath,
+		helpers: args.helpers,
+	});
+
+	return filePath;
+};

package/src/fs/index.ts

@@ -0,0 +1,103 @@
+///////////////////////////////////////////////////////////////////////////////
+//
+// Project helpers
+//
+///////////////////////////////////////////////////////////////////////////////
+
+export { checkIsTypeScriptProject } from "./checkIsTypeScriptProject";
+
+export { upsertGlobalTypeScriptTypes } from "./upsertGlobalTypeScriptTypes";
+export type { UpsertGlobalTypeScriptTypesArgs } from "./upsertGlobalTypeScriptTypes";
+
+export { checkHasProjectFile } from "./checkHasProjectFile";
+export type { CheckHasProjectFileArgs } from "./checkHasProjectFile";
+
+export { writeProjectFile } from "./writeProjectFile";
+export type { WriteProjectFileArgs } from "./writeProjectFile";
+
+export { readProjectFile } from "./readProjectFile";
+export type { ReadProjectFileArgs } from "./readProjectFile";
+
+export { deleteProjectFile } from "./deleteProjectFile";
+export type { DeleteProjectFileArgs } from "./deleteProjectFile";
+
+///////////////////////////////////////////////////////////////////////////////
+//
+// Slice helpers
+//
+///////////////////////////////////////////////////////////////////////////////
+
+export { buildSliceDirectoryPath } from "./buildSliceDirectoryPath";
+export type { BuildSliceDirectoryPathArgs } from "./buildSliceDirectoryPath";
+
+export { buildSliceFilePath } from "./buildSliceFilePath";
+export type { BuildSliceFilePathArgs } from "./buildSliceFilePath";
+
+export { buildSliceLibraryDirectoryPath } from "./buildSliceLibraryDirectoryPath";
+export type { BuildSliceLibraryDirectoryPathArgs } from "./buildSliceLibraryDirectoryPath";
+
+export { readSliceLibrary } from "./readSliceLibrary";
+export type {
+	ReadSliceLibraryArgs,
+	ReadSliceLibraryReturnType,
+} from "./readSliceLibrary";
+
+export { writeSliceFile } from "./writeSliceFile";
+export type { WriteSliceFileArgs } from "./writeSliceFile";
+
+export { writeSliceModel } from "./writeSliceModel";
+export type { WriteSliceModelArgs } from "./writeSliceModel";
+
+export { readSliceFile } from "./readSliceFile";
+export type { ReadSliceFileArgs } from "./readSliceFile";
+
+export { readSliceModel } from "./readSliceModel";
+export type {
+	ReadSliceModelArgs,
+	ReadSliceModelReturnType,
+} from "./readSliceModel";
+
+export { renameSlice } from "./renameSlice";
+export type { RenameSliceArgs } from "./renameSlice";
+
+export { deleteSliceFile } from "./deleteSliceFile";
+export type { DeleteSliceFileArgs } from "./deleteSliceFile";
+
+export { deleteSliceDirectory } from "./deleteSliceDirectory";
+export type { DeleteSliceDirectoryArgs } from "./deleteSliceDirectory";
+
+///////////////////////////////////////////////////////////////////////////////
+//
+// Custom type helpers
+//
+///////////////////////////////////////////////////////////////////////////////
+
+export { buildCustomTypeDirectoryPath } from "./buildCustomTypeDirectoryPath";
+export type { BuildCustomTypeDirectoryPathArgs } from "./buildCustomTypeDirectoryPath";
+
+export { buildCustomTypeFilePath } from "./buildCustomTypeFilePath";
+export type { BuildCustomTypeFilePathArgs } from "./buildCustomTypeFilePath";
+
+export { buildCustomTypeLibraryDirectoryPath } from "./buildCustomTypeLibraryDirectoryPath";
+export type { BuildCustomTypeLibraryDirectoryPathArgs } from "./buildCustomTypeLibraryDirectoryPath";
+
+export { readCustomTypeLibrary } from "./readCustomTypeLibrary";
+export type {
+	ReadCustomTypeLibraryArgs,
+	ReadCustomTypeLibraryReturnType,
+} from "./readCustomTypeLibrary";
+
+export { writeCustomTypeModel } from "./writeCustomTypeModel";
+export type { WriteCustomTypeModelArgs } from "./writeCustomTypeModel";
+
+export { readCustomTypeModel } from "./readCustomTypeModel";
+export type {
+	ReadCustomTypeModelArgs,
+	ReadCustomTypeModelReturnType,
+} from "./readCustomTypeModel";
+
+export { renameCustomType } from "./renameCustomType";
+export type { RenameCustomTypeArgs } from "./renameCustomType";
+
+export { deleteCustomTypeDirectory } from "./deleteCustomTypeDirectory";
+export type { DeleteCustomTypeDirectoryArgs } from "./deleteCustomTypeDirectory";

package/src/fs/lib/checkPathExists.ts

@@ -0,0 +1,13 @@
+import { PathLike } from "node:fs";
+
+import * as fs from "./fsLimit";
+
+export async function checkPathExists(path: PathLike): Promise<boolean> {
+	try {
+		await fs.access(path);
+
+		return true;
+	} catch {
+		return false;
+	}
+}