prismic 0.0.0-pr.28.59bf330

package/src/docs-list.ts

@@ -0,0 +1,131 @@
+import { parseArgs } from "node:util";
+
+const HELP = `
+List documentation pages from Prismic's docs site.
+
+USAGE
+  prismic docs list [flags]
+
+FLAGS
+  -h, --help   Show help for command
+
+EXAMPLES
+  prismic docs list
+`.trim();
+
+const ROOT_SITEMAP_URL = "https://prismic.io/docs/sitemap.xml";
+
+function decodeXmlEntities(input: string): string {
+	return input
+		.replaceAll("&", "&")
+		.replaceAll("&lt;", "<")
+		.replaceAll("&gt;", ">")
+		.replaceAll("&quot;", '"')
+		.replaceAll("&apos;", "'");
+}
+
+function extractLocEntries(xml: string): string[] {
+	const locPattern = /<loc>(.*?)<\/loc>/g;
+	const entries: string[] = [];
+	let match = locPattern.exec(xml);
+
+	while (match) {
+		entries.push(decodeXmlEntities(match[1]).trim());
+		match = locPattern.exec(xml);
+	}
+
+	return entries.filter(Boolean);
+}
+
+async function fetchXml(url: string): Promise<{ ok: true; xml: string } | { ok: false; error: string }> {
+	try {
+		const response = await fetch(url);
+		if (!response.ok) {
+			return {
+				ok: false,
+				error: `Failed to fetch sitemap: ${response.status} (${url})`,
+			};
+		}
+
+		return {
+			ok: true,
+			xml: await response.text(),
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { ok: false, error: `Network error while fetching sitemap ${url}: ${message}` };
+	}
+}
+
+function toDocsPath(urlString: string): string | null {
+	try {
+		const url = new URL(urlString);
+		if (url.hostname !== "prismic.io") {
+			return null;
+		}
+
+		if (!url.pathname.startsWith("/docs/")) {
+			return null;
+		}
+
+		return url.pathname.replace(/^\/docs\//, "").replace(/^\/+|\/+$/g, "");
+	} catch {
+		return null;
+	}
+}
+
+export async function docsList(): Promise<void> {
+	const {
+		values: { help },
+	} = parseArgs({
+		args: process.argv.slice(4),
+		options: {
+			help: { type: "boolean", short: "h" },
+		},
+		allowPositionals: true,
+	});
+
+	if (help) {
+		console.info(HELP);
+		return;
+	}
+
+	const rootResult = await fetchXml(ROOT_SITEMAP_URL);
+	if (!rootResult.ok) {
+		console.error(rootResult.error);
+		process.exitCode = 1;
+		return;
+	}
+
+	const nestedSitemapUrls = extractLocEntries(rootResult.xml);
+	if (nestedSitemapUrls.length === 0) {
+		console.error(`No nested sitemaps found in ${ROOT_SITEMAP_URL}`);
+		process.exitCode = 1;
+		return;
+	}
+
+	const nestedResults = await Promise.all(nestedSitemapUrls.map((url) => fetchXml(url)));
+	const failedFetch = nestedResults.find((result) => !result.ok);
+	if (failedFetch && !failedFetch.ok) {
+		console.error(failedFetch.error);
+		process.exitCode = 1;
+		return;
+	}
+
+	const paths = new Set<string>();
+
+	for (const nestedResult of nestedResults) {
+		if (!nestedResult.ok) continue;
+
+		for (const url of extractLocEntries(nestedResult.xml)) {
+			const path = toDocsPath(url);
+			if (path) {
+				paths.add(path);
+			}
+		}
+	}
+
+	for (const path of [...paths].sort((a, b) => a.localeCompare(b))) {
+		console.info(path);
+	}
+}

package/src/docs.ts

@@ -0,0 +1,54 @@
+import { parseArgs } from "node:util";
+import { docsFetch } from "./docs-fetch";
+import { docsList } from "./docs-list";
+
+const HELP = `
+Fetch and list documentation from Prismic's docs site.
+
+USAGE
+  prismic docs <command> [flags]
+
+COMMANDS
+  fetch      Fetch and display a documentation page
+  list       List documentation pages
+
+FLAGS
+  -h, --help   Show help for command
+
+EXAMPLES
+  prismic docs fetch nextjs
+  prismic docs fetch nextjs#set-up-a-prismic-client
+  prismic docs list
+
+LEARN MORE
+  Use \`prismic docs <command> --help\` for more information about a command.
+`.trim();
+
+export async function docs(): Promise<void> {
+	const {
+		positionals: [subcommand],
+	} = parseArgs({
+		args: process.argv.slice(3),
+		options: {
+			help: { type: "boolean", short: "h" },
+		},
+		allowPositionals: true,
+		strict: false,
+	});
+
+	switch (subcommand) {
+		case "fetch":
+			await docsFetch();
+			break;
+		case "list":
+			await docsList();
+			break;
+		default: {
+			if (subcommand) {
+				console.error(`Unknown docs subcommand: ${subcommand}\n`);
+				process.exitCode = 1;
+			}
+			console.info(HELP);
+		}
+	}
+}

package/src/env.d.ts

@@ -0,0 +1,12 @@
+interface ImportMetaEnv {
+	readonly MODE: string;
+	readonly DEV: boolean;
+	readonly PROD: boolean;
+	readonly PRISMIC_SENTRY_DSN: string | undefined;
+	readonly PRISMIC_SENTRY_ENVIRONMENT: string | undefined;
+	readonly PRISMIC_SENTRY_ENABLED: string | undefined;
+}
+
+interface ImportMeta {
+	readonly env: ImportMetaEnv;
+}

package/src/framework/index.ts

@@ -0,0 +1,399 @@
+import type { CustomType, SharedSlice } from "@prismicio/types-internal/lib/customtypes";
+
+import { pascalCase } from "change-case";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { glob } from "tinyglobby";
+import * as v from "valibot";
+
+import { readConfig } from "../lib/config";
+import { exists, findUpward } from "../lib/file";
+import { stringify } from "../lib/json";
+import { addDependencies } from "../lib/packageJson";
+import { dedent } from "../lib/string";
+import { appendTrailingSlash } from "../lib/url";
+
+export abstract class FrameworkAdapter {
+	abstract readonly id: Framework;
+
+	abstract getDependencies(): Promise<Record<string, string>>;
+
+	abstract getClientFilePath(): Promise<string | null>;
+
+	abstract getSlicesDirectoryPath(): Promise<string>;
+
+	abstract getSliceComponentExtensions(): string[];
+
+	abstract getRoutePath(route: string): Promise<{ path: string; extensions: string[] } | null>;
+
+	abstract createSliceComponent(
+		model: SharedSlice,
+		sliceDirectory: URL,
+	): Promise<{ componentPath: URL }>;
+
+	abstract getSliceImportPath(relativeDirectory: string): string;
+
+	abstract getDefaultSliceLibraryPath(projectRoot: URL): Promise<URL>;
+
+	async initProject(): Promise<void> {
+		const deps = await this.getDependencies();
+		await addDependencies(deps);
+		const libraries = await this.#getSliceLibraries();
+		for (const library of libraries) {
+			await this.#updateSliceLibraryIndexFile(library);
+		}
+	}
+
+	async createSlice(
+		model: SharedSlice,
+		library: URL,
+	): Promise<{ modelPath: URL; componentPath: URL; indexPath: URL }> {
+		const { modelPath } = await this.#writeSliceModel(model, library);
+		const sliceDirectory = await this.#getSliceDirectory(model.name, library);
+		const { componentPath } = await this.createSliceComponent(model, sliceDirectory);
+		const { indexPath } = await this.#updateSliceLibraryIndexFile(library);
+		return { modelPath, componentPath, indexPath };
+	}
+
+	async readSlice(sliceId: string): Promise<SharedSlice> {
+		const slice = await this.#findSlice(sliceId);
+		return slice.model;
+	}
+
+	async updateSlice(model: SharedSlice): Promise<{ modelPath: URL; indexPath: URL }> {
+		const existingSlice = await this.#findSlice(model.id);
+		const { modelPath } = await this.#writeSliceModel(model, existingSlice.library);
+		const { indexPath } = await this.#updateSliceLibraryIndexFile(existingSlice.library);
+		return { modelPath, indexPath };
+	}
+
+	async renameSlice(model: SharedSlice): Promise<{ modelPath: URL; indexPath: URL }> {
+		const existingSlice = await this.#findSlice(model.id);
+		const newSliceDirectory = await this.#getSliceDirectory(model.name, existingSlice.library);
+		await rename(existingSlice.directory, newSliceDirectory);
+		const { modelPath } = await this.#writeSliceModel(model, existingSlice.library);
+		const { indexPath } = await this.#updateSliceLibraryIndexFile(existingSlice.library);
+		return { modelPath, indexPath };
+	}
+
+	async deleteSlice(sliceId: string): Promise<{ sliceDirectory: URL; indexPath: URL }> {
+		const slice = await this.#findSlice(sliceId);
+		await rm(slice.directory, { recursive: true });
+		const { indexPath } = await this.#updateSliceLibraryIndexFile(slice.library);
+		return { sliceDirectory: slice.directory, indexPath };
+	}
+
+	async getSlices(library?: URL): Promise<{ library: URL; directory: URL; model: SharedSlice }[]> {
+		const libraryDirs = library ? [library] : await this.#getSliceLibraries();
+		const allSlices: {
+			library: URL;
+			directory: URL;
+			model: SharedSlice;
+		}[] = [];
+
+		for (const libraryDir of libraryDirs) {
+			const modelGlob = new URL("*/model.json", libraryDir);
+			const sliceModelPaths = Array.from(
+				await glob(fileURLToPath(modelGlob), { absolute: true }),
+				(path) => pathToFileURL(path),
+			);
+			const slices = await Promise.all(
+				sliceModelPaths.map(async (sliceModelPath) => {
+					const directory = new URL(".", sliceModelPath);
+					const model = await readFile(sliceModelPath, "utf8");
+					return {
+						library: libraryDir,
+						directory,
+						model: JSON.parse(model),
+					};
+				}),
+			);
+			allSlices.push(...slices);
+		}
+
+		return allSlices;
+	}
+
+	async getDefaultSliceLibrary(): Promise<URL> {
+		const dirs = await this.#getSliceLibraries();
+		return dirs[0];
+	}
+
+	async createCustomType(model: CustomType): Promise<{ modelPath: URL }> {
+		const { modelPath } = await this.#writeCustomType(model);
+		return { modelPath };
+	}
+
+	async readCustomType(customTypeId: string): Promise<CustomType> {
+		const customTypeDirectory = await this.#getCustomTypeDirectory(customTypeId);
+		const modelPath = new URL("index.json", customTypeDirectory);
+		const model = await readFile(modelPath, "utf8");
+		const json = JSON.parse(model);
+		return json;
+	}
+
+	async updateCustomType(model: CustomType): Promise<{ modelPath: URL }> {
+		const { modelPath } = await this.#writeCustomType(model);
+		return { modelPath };
+	}
+
+	async renameCustomType(model: CustomType): Promise<{ modelPath: URL }> {
+		const existingCustomTypeDirectory = await this.#getCustomTypeDirectory(model.id);
+		const newCustomTypeDirectory = await this.#getCustomTypeDirectory(model.id);
+		await rename(existingCustomTypeDirectory, newCustomTypeDirectory);
+		const { modelPath } = await this.#writeCustomType(model);
+		return { modelPath };
+	}
+
+	async deleteCustomType(customTypeId: string): Promise<{ customTypeDirectory: URL }> {
+		const customTypeDirectory = await this.#getCustomTypeDirectory(customTypeId);
+		await rm(customTypeDirectory, { recursive: true });
+		return { customTypeDirectory };
+	}
+
+	async getCustomTypes(): Promise<{ directory: URL; model: CustomType }[]> {
+		const customTypesDirectory = await this.#getCustomTypesDirectory();
+		const modelGlob = new URL("*/index.json", customTypesDirectory);
+		const customTypeModelPaths = Array.from(
+			await glob(fileURLToPath(modelGlob), { absolute: true }),
+			(path) => pathToFileURL(path),
+		);
+		const customTypes = await Promise.all(
+			customTypeModelPaths.map(async (customTypeModelPath) => {
+				const directory = new URL(".", customTypeModelPath);
+				const model = await readFile(customTypeModelPath, "utf8");
+				return {
+					directory,
+					model: JSON.parse(model),
+				};
+			}),
+		);
+		return customTypes;
+	}
+
+	async getProjectRoot(): Promise<URL> {
+		const packageJsonPath = await findUpward("package.json");
+		if (!packageJsonPath) {
+			throw new Error("No package.json found");
+		}
+		const projectRoot = new URL("./", packageJsonPath);
+		return projectRoot;
+	}
+
+	protected async checkIsTypeScriptProject(): Promise<boolean> {
+		const projectRoot = await this.getProjectRoot();
+		const tsconfigPath = new URL("tsconfig.json", projectRoot);
+		const isTypeScriptProject = await exists(tsconfigPath);
+		return isTypeScriptProject;
+	}
+
+	protected async getJsFileExtension(): Promise<string> {
+		const isTypeScriptProject = await this.checkIsTypeScriptProject();
+		const jsFileExtension = isTypeScriptProject ? "ts" : "js";
+		return jsFileExtension;
+	}
+
+	async #findSlice(sliceId: string): Promise<{ library: URL; directory: URL; model: SharedSlice }> {
+		const slices = await this.getSlices();
+		const slice = slices.find((slice) => slice.model.id === sliceId);
+		if (!slice) throw new Error(`No slice found with ID: ${sliceId}`);
+		return slice;
+	}
+
+	async #writeSliceModel(model: SharedSlice, library: URL): Promise<{ modelPath: URL }> {
+		const sliceDirectory = await this.#getSliceDirectory(model.name, library);
+		await mkdir(sliceDirectory, { recursive: true });
+		const modelPath = new URL("model.json", sliceDirectory);
+		const formattedModel = this.#formatModel(model);
+		await writeFile(modelPath, formattedModel);
+		return { modelPath };
+	}
+
+	async #getSliceDirectory(sliceName: string, library: URL): Promise<URL> {
+		const sliceDirectoryName = pascalCase(sliceName);
+		const sliceDirectory = appendTrailingSlash(new URL(sliceDirectoryName, library));
+		return sliceDirectory;
+	}
+
+	async #getSliceLibraries(): Promise<URL[]> {
+		const projectRoot = await this.getProjectRoot();
+		const configResult = await readConfig();
+		const sliceLibraries = configResult.ok ? configResult.config.libraries : undefined;
+
+		if (sliceLibraries?.length) {
+			return sliceLibraries.map((sliceLibrary) => {
+				const withoutLeadingSlash = sliceLibrary.replace(/^\//, "");
+				return appendTrailingSlash(new URL(withoutLeadingSlash, projectRoot));
+			});
+		}
+
+		return [await this.getDefaultSliceLibraryPath(projectRoot)];
+	}
+
+	async #updateSliceLibraryIndexFile(library: URL): Promise<{ indexPath: URL }> {
+		const slices = await this.getSlices(library);
+		const contents = await this.generateSliceLibraryIndexContents(slices);
+		const extension = await this.getJsFileExtension();
+		const filename = `index.${extension}`;
+		const indexPath = new URL(filename, library);
+		await writeFile(indexPath, contents);
+		return { indexPath };
+	}
+
+	protected async generateSliceLibraryIndexContents(
+		slices: { library: URL; directory: URL; model: SharedSlice }[],
+	): Promise<string> {
+		const imports = slices.map((slice) => {
+			const componentName = pascalCase(slice.model.name);
+			const relativeDirectory = relative(
+				fileURLToPath(slice.library),
+				fileURLToPath(slice.directory),
+			);
+			return `import ${componentName} from "${this.getSliceImportPath(relativeDirectory)}";`;
+		});
+		const componentLines = slices.map((slice) => {
+			const componentName = pascalCase(slice.model.name);
+			return `${slice.model.id}: ${componentName}`;
+		});
+		return dedent`
+			// Code generated by Prismic. DO NOT EDIT.
+
+			${imports.join("\n")}
+
+			export const components = {
+				${componentLines.join(",\n")}
+			};
+		`;
+	}
+
+	async #writeCustomType(model: CustomType): Promise<{ modelPath: URL }> {
+		const customTypeDirectory = await this.#getCustomTypeDirectory(model.id);
+		await mkdir(customTypeDirectory, { recursive: true });
+		const modelPath = new URL("index.json", customTypeDirectory);
+		const formattedModel = this.#formatModel(model);
+		await writeFile(modelPath, formattedModel);
+		return { modelPath };
+	}
+
+	async #getCustomTypeDirectory(customTypeId: string): Promise<URL> {
+		const customTypesDirectory = await this.#getCustomTypesDirectory();
+		const customTypeDirectoryName = customTypeId;
+		const customTypeDirectory = appendTrailingSlash(
+			new URL(customTypeDirectoryName, customTypesDirectory),
+		);
+		return customTypeDirectory;
+	}
+
+	async #getCustomTypesDirectory(): Promise<URL> {
+		const projectRoot = await this.getProjectRoot();
+		const customTypesDirectory = new URL(`customtypes/`, projectRoot);
+		return customTypesDirectory;
+	}
+
+	#formatModel(model: CustomType | SharedSlice): string {
+		const formattedModel = stringify(model);
+		return formattedModel;
+	}
+}
+
+export function getDocsPath(framework: Framework): string {
+	switch (framework) {
+		case "next":
+			return "nextjs/with-cli";
+		case "nuxt":
+			return "nuxt/with-cli";
+		case "sveltekit":
+			return "sveltekit/with-cli";
+	}
+}
+
+export function getWriteComponentsAnchor(framework: Framework): string {
+	switch (framework) {
+		case "nuxt":
+			return "#write-vue-components";
+		case "sveltekit":
+			return "#write-svelte-components";
+		default:
+			return "#write-react-components";
+	}
+}
+
+export function getClientSetupAnchor(framework: Framework): string {
+	switch (framework) {
+		case "nuxt":
+			return "#configure-the-modules-prismic-client";
+		default:
+			return "#set-up-a-prismic-client";
+	}
+}
+
+export function getPreviewSetupAnchor(framework: Framework): string {
+	switch (framework) {
+		case "next":
+			return "#set-up-previews-in-next-js";
+		case "sveltekit":
+			return "#set-up-previews-in-sveltekit";
+		default:
+			return "";
+	}
+}
+
+const PackageJsonSchema = v.object({
+	dependencies: v.optional(v.record(v.string(), v.string())),
+	devDependencies: v.optional(v.record(v.string(), v.string())),
+});
+
+export type Framework = "next" | "nuxt" | "sveltekit";
+
+export async function requireFramework(): Promise<FrameworkAdapter | undefined> {
+	const framework = await getFramework();
+	if (!framework) {
+		console.error("No supported framework found (Next.js, Nuxt, or SvelteKit required)");
+		console.error("Ensure your project has the framework listed as a dependency in package.json");
+		process.exitCode = 1;
+		return undefined;
+	}
+	return framework;
+}
+
+export async function getFramework(): Promise<FrameworkAdapter | undefined> {
+	const id = await detectFramework();
+	switch (id) {
+		case "next": {
+			const { NextJsFramework } = await import("./nextjs");
+			return new NextJsFramework();
+		}
+		case "nuxt": {
+			const { NuxtFramework } = await import("./nuxt");
+			return new NuxtFramework();
+		}
+		case "sveltekit": {
+			const { SvelteKitFramework } = await import("./sveltekit");
+			return new SvelteKitFramework();
+		}
+		default:
+			return undefined;
+	}
+}
+
+async function detectFramework(): Promise<Framework | undefined> {
+	const packageJsonPath = await findUpward("package.json");
+	if (!packageJsonPath) return undefined;
+
+	try {
+		const contents = await readFile(packageJsonPath, "utf8");
+		const { dependencies = {}, devDependencies = {} } = v.parse(
+			PackageJsonSchema,
+			JSON.parse(contents),
+		);
+		const allDeps = { ...dependencies, ...devDependencies };
+		if ("next" in allDeps) return "next";
+		if ("nuxt" in allDeps) return "nuxt";
+		if ("@sveltejs/kit" in allDeps) return "sveltekit";
+	} catch {
+		// Continue with undefined
+	}
+
+	return undefined;
+}