@prismicio/cli 0.0.1

package/src/core/project.ts

@@ -0,0 +1,148 @@
+import type {
+	PackageManager,
+	PrismicConfig,
+	PrismicManager,
+} from "@prismicio/manager";
+import chalk from "chalk";
+
+import { type Framework, detectFramework } from "../core/framework";
+import { listr, listrRun } from "../utils/listr";
+import { updateSentryContext } from "../utils/sentry";
+
+type DetectProjectStateArgs = {
+	manager: PrismicManager;
+	commandType: "init" | "sync";
+};
+
+export async function detectProjectState(
+	args: DetectProjectStateArgs,
+): Promise<void> {
+	const { manager, commandType } = args;
+
+	let prismicConfig: PrismicConfig | undefined;
+
+	try {
+		prismicConfig = await manager.project.getPrismicConfig();
+	} catch {
+		// We want to manage the error depending on the need to be initialized or not
+	}
+
+	const legacyConfigExists = await manager.project.checkLegacyConfigExists();
+
+	if (commandType === "init" && (prismicConfig || legacyConfigExists)) {
+		throw new Error("Project has already been initialized.");
+	} else if (commandType === "sync" && !prismicConfig) {
+		if (legacyConfigExists) {
+			await manager.project.migrateLegacyConfig();
+		} else {
+			throw new Error("Project requires initialization before syncing.");
+		}
+	}
+}
+
+export type ProjectContext = {
+	framework: Framework;
+	packageManager: PackageManager;
+};
+
+export async function detectProjectContext(
+	manager: PrismicManager,
+): Promise<ProjectContext> {
+	let framework: Framework | undefined;
+	let packageManager: PackageManager | undefined;
+
+	await listrRun([
+		{
+			title: "Detecting environment...",
+			task: (_, parentTask) =>
+				listr([
+					{
+						title: "Detecting framework...",
+						task: async (_, task) => {
+							framework = await detectFramework(manager.cwd);
+
+							// Update Sentry context for the framework
+							updateSentryContext({ framework: framework.telemetryID });
+
+							task.title = `Detected framework ${chalk.cyan(framework.name)}`;
+						},
+					},
+					{
+						title: "Detecting package manager...",
+						task: async (_, task) => {
+							packageManager = await manager.project.detectPackageManager({
+								root: manager.cwd,
+							});
+
+							task.title = `Detected package manager ${chalk.cyan(
+								packageManager,
+							)}`;
+
+							if (!framework) {
+								throw new Error(
+									"Project framework must be available through context to proceed",
+								);
+							}
+
+							parentTask.title = `Detected framework ${chalk.cyan(
+								framework.name,
+							)} and package manager ${chalk.cyan(packageManager)}`;
+						},
+					},
+				]),
+		},
+	]);
+
+	if (!framework) {
+		throw new Error(
+			"Project framework must be available through context to proceed",
+		);
+	}
+
+	if (!packageManager) {
+		throw new Error(
+			"Project package manager must be available through context to proceed",
+		);
+	}
+
+	return {
+		framework,
+		packageManager,
+	};
+}
+
+type CreatePrismicConfigArgs = {
+	manager: PrismicManager;
+	projectContext: ProjectContext;
+	repositoryName: string;
+};
+
+export async function createPrismicConfig(
+	args: CreatePrismicConfigArgs,
+): Promise<void> {
+	const { manager, projectContext, repositoryName } = args;
+	const { framework } = projectContext;
+
+	return listrRun([
+		{
+			title: "Creating Prismic configuration...",
+			task: async (_, parentTask) => {
+				parentTask.title = "Creating Prismic configuration...";
+
+				const prismicConfigPath =
+					await manager.project.suggestPrismicConfigPath();
+
+				await manager.project.writePrismicConfig({
+					config: {
+						repositoryName,
+						adapter: framework.adapterName,
+						libraries: ["./slices"],
+					},
+					path: prismicConfigPath,
+				});
+
+				parentTask.title = "Created Prismic configuration";
+			},
+		},
+	]);
+}

package/src/core/repository.ts

@@ -0,0 +1,51 @@
+import type { PrismicManager } from "@prismicio/manager";
+
+import { listrRun } from "../utils/listr";
+import { updateSentryContext } from "../utils/sentry";
+
+export type ValidateRepositoryArgs = {
+	manager: PrismicManager;
+	repository: string;
+};
+
+export async function validateRepository(
+	args: ValidateRepositoryArgs,
+): Promise<void> {
+	const { manager, repository } = args;
+
+	return listrRun([
+		{
+			title: `Validating repository...`,
+			task: async (_, task) => {
+				// Update Sentry context for the repository name
+				updateSentryContext({ repositoryName: repository });
+
+				const repositoryExists = await manager.prismicRepository.checkExists({
+					domain: repository,
+				});
+				if (!repositoryExists) {
+					throw new Error(`Repository ${repository} does not exist.`);
+				}
+
+				const userRepositories = await manager.prismicRepository.readAll();
+				const userSelectedRepository = userRepositories.find(
+					(repo) => repo.domain === repository,
+				);
+				if (!userSelectedRepository) {
+					throw new Error(`You're not part of the repository ${repository}.`);
+				}
+
+				const hasWriteAccess = await manager.prismicRepository.hasWriteAccess(
+					userSelectedRepository,
+				);
+				if (!hasWriteAccess) {
+					throw new Error(
+						`You do not have administrator access to repository ${repository}.`,
+					);
+				}
+
+				task.title = `Validated repository (${repository})`;
+			},
+		},
+	]);
+}

package/src/core/slices.ts

@@ -0,0 +1,67 @@
+import type { PrismicManager } from "@prismicio/manager";
+
+import { listrRun } from "../utils/listr";
+
+type SaveSlicesArgs = {
+	manager: PrismicManager;
+};
+
+export async function saveSlices(args: SaveSlicesArgs): Promise<void> {
+	const { manager } = args;
+
+	// Save slices to local directory
+	await listrRun([
+		{
+			title: "Fetching Prismic slices...",
+			task: async (_, parentTask) => {
+				const slices = await manager.slices.fetchRemoteSlices();
+
+				parentTask.title = "Saving Prismic slices changes...";
+
+				const localSlices = await manager.slices.readAllSlices();
+
+				// Handle slices update
+				for (const remoteSlice of slices) {
+					const localSlice = localSlices.models.find(
+						(local) => local.model.id === remoteSlice.id,
+					);
+					if (localSlice) {
+						await manager.slices.updateSlice({
+							libraryID: localSlice.libraryID,
+							model: remoteSlice,
+						});
+					}
+				}
+
+				// Handle slices deletion
+				for (const localSlice of localSlices.models) {
+					const existsRemotely = slices.some(
+						(slice) => slice.id === localSlice.model.id,
+					);
+					if (!existsRemotely) {
+						await manager.slices.deleteSlice({
+							libraryID: localSlice.libraryID,
+							sliceID: localSlice.model.id,
+						});
+					}
+				}
+
+				// Handle slices creation
+				const defaultLibraryID = await manager.slices.getDefaultLibraryID();
+				for (const remoteSlice of slices) {
+					const existsLocally = localSlices.models.some(
+						(localSlice) => localSlice.model.id === remoteSlice.id,
+					);
+					if (!existsLocally) {
+						await manager.slices.createSlice({
+							libraryID: defaultLibraryID,
+							model: remoteSlice,
+						});
+					}
+				}
+
+				parentTask.title = "Prismic slices changes saved";
+			},
+		},
+	]);
+}

package/src/core/version.ts

@@ -0,0 +1,50 @@
+import type { PrismicManager } from "@prismicio/manager";
+import semver from "semver";
+
+import { listrRun } from "../utils/listr";
+
+type CheckCLIVersionArgs = {
+	manager: PrismicManager;
+	currentVersion: string;
+};
+
+/**
+ * Checks if the current CLI version is the latest available version. Throws an
+ * Error if the version is outdated.
+ *
+ * @param args - Arguments object containing the manager and current version.
+ *
+ * @throws Error If the current version is not the latest.
+ */
+export async function checkCLIVersion(
+	args: CheckCLIVersionArgs,
+): Promise<void> {
+	await listrRun([
+		{
+			title: "Checking CLI version...",
+			task: async (_, parentTask) => {
+				// Skip version check if current version is a pre-release (alpha, beta, rc, etc.)
+				if (semver.prerelease(args.currentVersion) !== null) {
+					parentTask.title =
+						"CLI version is a pre-release, skipping version check";
+				} else {
+					const isLatestVersion =
+						await args.manager.versions.checkIsCLIVersionLatest({
+							currentVersion: args.currentVersion,
+						});
+
+					if (!isLatestVersion) {
+						const latestVersion =
+							await args.manager.versions.getLatestCLIVersion();
+
+						throw new Error(
+							`You are using an outdated version (${args.currentVersion}). The latest version is ${latestVersion}.`,
+						);
+					}
+
+					parentTask.title = "CLI version is up to date";
+				}
+			},
+		},
+	]);
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { run } from "./cli";

package/src/utils/error.ts

@@ -0,0 +1,40 @@
+import semver from "semver";
+
+import * as pkg from "../../package.json";
+
+/**
+ * Checks if we should show errors in the console. Errors are shown in
+ * development mode or when using a pre-release version.
+ *
+ * @returns Whether to show errors.
+ */
+const shouldShowErrors = (): boolean => {
+	// Show errors in development mode
+	if (import.meta.env.DEV) {
+		return true;
+	}
+
+	// Show errors if it's a pre-release version
+	if (semver.prerelease(pkg.version) !== null) {
+		return true;
+	}
+
+	return false;
+};
+
+/**
+ * Handles errors that should not break the CLI by logging them in
+ * dev/pre-release mode, or silently failing otherwise.
+ *
+ * @param error - The error that occurred.
+ * @param context - Context about what operation failed.
+ */
+export function handleSilentError(error: unknown, context: string): void {
+	if (shouldShowErrors()) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		console.error(
+			`[${context}] Failed: ${errorMessage}`,
+			error instanceof Error ? error : undefined,
+		);
+	}
+}

package/src/utils/listr.ts

@@ -0,0 +1,13 @@
+import { Listr, type ListrTask, type ListrOptions } from "listr2";
+
+type ListrArgs = [tasks: ListrTask[], options?: ListrOptions];
+
+export const listr = (...[tasks, options]: ListrArgs): Listr => {
+	return new Listr(tasks, options);
+};
+
+export const listrRun = async (
+	...[tasks, options]: ListrArgs
+): Promise<void> => {
+	return listr(tasks, options).run();
+};

package/src/utils/output.ts

@@ -0,0 +1,45 @@
+import chalk from "chalk";
+
+import { version as pkgVersion } from "../../package.json";
+
+export function displayHeader(): void {
+	console.info(
+		chalk.cyan.bold("┌" + "─".repeat(48) + "┐\n") +
+			chalk.white("  Prismic ") +
+			chalk.gray(`v${pkgVersion}\n`) +
+			chalk.cyan.bold("└" + "─".repeat(48) + "┘\n"),
+	);
+}
+
+export function displaySuccess(message: string, context?: string): void {
+	console.info("\n" + chalk.green.bold("✓ Success"));
+	console.info(chalk.green("─".repeat(50)));
+	console.info(chalk.green(message));
+	if (context) {
+		console.info(chalk.gray(context + "\n"));
+	} else {
+		console.info();
+	}
+}
+
+export function displayError(error: unknown): void {
+	const errorMessage = error instanceof Error ? error.message : String(error);
+	const errorStack =
+		error instanceof Error && error.stack ? error.stack : undefined;
+
+	console.error("\n" + chalk.red.bold("✕ Error"));
+	console.error(chalk.red("─".repeat(50)));
+	console.error(chalk.red(errorMessage) + "\n");
+
+	if (errorStack) {
+		console.error(chalk.gray("Stack trace:"));
+		console.error(chalk.gray(errorStack) + "\n");
+	}
+
+	console.error(
+		chalk.gray("─".repeat(50)) +
+			chalk.gray("\nNeed help?") +
+			chalk.white("\n  • Documentation: https://prismic.io/docs") +
+			chalk.white("\n  • Raise an issue: https://community.prismic.io\n"),
+	);
+}

package/src/utils/package.ts

@@ -0,0 +1,29 @@
+import semver from "semver";
+
+type PackageManifest = { name: string; version: string };
+type PackageInfo = { environment: string; release: string };
+
+export function getPackageInfo(pkg: PackageManifest): PackageInfo {
+	const parsedPkgVersion = semver.parse(pkg.version);
+	if (parsedPkgVersion === null) {
+		throw new Error(
+			`Package \`${pkg.name}\` has an invalid version \`${pkg.version}\` in its manifest.`,
+		);
+	}
+
+	let environment;
+	if (parsedPkgVersion.prerelease.length === 0) {
+		environment = import.meta.env.MODE || "production";
+	} else if (
+		parsedPkgVersion.prerelease[0] === "alpha" ||
+		parsedPkgVersion.prerelease[0] === "beta"
+	) {
+		environment = parsedPkgVersion.prerelease[0];
+	} else {
+		throw new Error(
+			`Invalid package version: \`${pkg.name}@${parsedPkgVersion.version}\`. The first prerelease component \`${parsedPkgVersion.prerelease[0]}\` must be either \`alpha\` or \`beta\`.`,
+		);
+	}
+
+	return { environment, release: parsedPkgVersion.version };
+}

package/src/utils/sentry.ts

@@ -0,0 +1,104 @@
+import { PrismicUserProfile } from "@prismicio/manager";
+import * as Sentry from "@sentry/node";
+
+import * as pkg from "../../package.json";
+
+import { handleSilentError } from "./error";
+import { getPackageInfo } from "./package";
+
+const SENTRY_DSN =
+	import.meta.env.VITE_SENTRY_DSN ||
+	"https://e1886b1775bd397cd1afc60bfd2ebfc8@o146123.ingest.us.sentry.io/4510445143588864";
+
+/**
+ * Checks whether or not Sentry is enabled.
+ *
+ * Sentry is enabled automatically in production but can be disabled by setting
+ * `VITE_ENABLE_SENTRY` to `false`.
+ *
+ * @returns Whether or not Sentry is enabled.
+ */
+const checkIsSentryEnabled = (): boolean =>
+	import.meta.env.VITE_ENABLE_SENTRY === undefined
+		? import.meta.env.PROD
+		: import.meta.env.VITE_ENABLE_SENTRY === "true";
+
+export async function trackSentryError(error: unknown): Promise<void> {
+	try {
+		if (!checkIsSentryEnabled()) {
+			return;
+		}
+
+		Sentry.captureException(error, {
+			...(error instanceof Error
+				? { extra: { cause: error.cause, fullCommand: process.argv.join(" ") } }
+				: {}),
+		});
+
+		// Flush Sentry events before process exit
+		await Sentry.flush();
+	} catch (sentryError) {
+		handleSilentError(sentryError, "Sentry tracking error");
+	}
+}
+
+export function setupSentry(): void {
+	try {
+		if (!checkIsSentryEnabled()) {
+			return;
+		}
+
+		const { environment, release } = getPackageInfo(pkg);
+
+		Sentry.init({
+			dsn: SENTRY_DSN,
+			release,
+			environment,
+			// Increase the default truncation length of 250 to 2500 (x10)
+			// to have enough details in Sentry
+			maxValueLength: 2_500,
+		});
+	} catch (error) {
+		handleSilentError(error, "Sentry setup error");
+	}
+}
+
+type UpdateSentryContextArgs = {
+	repositoryName?: string;
+	framework?: string;
+	userProfile?: PrismicUserProfile;
+};
+
+export async function updateSentryContext({
+	repositoryName,
+	framework,
+	userProfile,
+}: UpdateSentryContextArgs): Promise<void> {
+	try {
+		if (!checkIsSentryEnabled()) {
+			return;
+		}
+
+		if (userProfile) {
+			Sentry.setUser({ id: userProfile.shortId });
+		}
+
+		if (repositoryName) {
+			Sentry.setTag("repository", repositoryName);
+			Sentry.setContext("Repository Data", {
+				name: repositoryName,
+			});
+		}
+
+		if (framework) {
+			Sentry.setTag("framework", framework);
+		}
+
+		Sentry.setContext("Process", {
+			"Command used": process.argv.join(" "),
+			cwd: process.cwd(),
+		});
+	} catch (error) {
+		handleSilentError(error, "Sentry context update error");
+	}
+}

package/src/utils/telemetry.ts

@@ -0,0 +1,70 @@
+import type { PrismicManager } from "@prismicio/manager";
+
+import { name as pkgName, version as pkgVersion } from "../../package.json";
+
+import { handleSilentError } from "./error";
+
+type InitTelemetryArgs = {
+	manager: PrismicManager;
+	commandType: "init" | "sync";
+	repositoryName?: string;
+};
+
+export async function initTelemetry(args: InitTelemetryArgs): Promise<void> {
+	const { manager, commandType, repositoryName } = args;
+
+	await manager.telemetry.initTelemetry({
+		appName: pkgName,
+		appVersion: pkgVersion,
+	});
+
+	// Get repository name from project config if not provided
+	let resolvedRepositoryName = repositoryName;
+	if (!resolvedRepositoryName) {
+		resolvedRepositoryName = await manager.project.getRepositoryName();
+	}
+
+	await manager.telemetry.track({
+		event: "prismic-cli:start",
+		repository: resolvedRepositoryName,
+		commandType,
+		fullCommand: process.argv.join(" "),
+	});
+}
+
+type TrackErrorTelemetryArgs = {
+	manager: PrismicManager;
+	error: unknown;
+	commandType: "init" | "sync";
+};
+
+export async function trackErrorTelemetry(
+	args: TrackErrorTelemetryArgs,
+): Promise<void> {
+	const { manager, error, commandType } = args;
+
+	// Transform error to string and prevent hitting Segment 500kb API limit
+	const safeError = (error instanceof Error ? error.message : `${error}`).slice(
+		0,
+		512,
+	);
+
+	let repositoryName;
+	try {
+		repositoryName = await manager.project.getRepositoryName();
+	} catch (error) {
+		handleSilentError(
+			error,
+			"Telemetry track error while getting repository name",
+		);
+	}
+
+	await manager.telemetry.track({
+		event: "prismic-cli:end",
+		commandType,
+		repository: repositoryName,
+		fullCommand: process.argv.join(" "),
+		success: false,
+		error: safeError,
+	});
+}