@angeloashmore/prismic-cli-poc 0.0.0-pr.7.1e5b475 → 0.0.0-pr.8.b80fefa

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@angeloashmore/prismic-cli-poc",
-	"version": "0.0.0-pr.7.1e5b475",
+	"version": "0.0.0-pr.8.b80fefa",
 	"description": "A proof-of-concept developer CLI for Prismic.",
 	"keywords": [
 		"prismic",

package/src/custom-type-create.ts

@@ -59,7 +59,14 @@ export async function customTypeCreate(): Promise<void> {
 		status: true,
 		format: "custom",
 		json: {
-			Main: {},
+			Main: single
+				? {}
+				: {
+						uid: {
+							type: "UID",
+							config: { label: "UID", placeholder: "" },
+						},
+					},
 		},
 	} satisfies CustomType;
 

package/src/docs.ts

@@ -0,0 +1,149 @@
+import { parseArgs } from "node:util";
+
+const HELP = `
+Fetch and display documentation from Prismic's docs site.
+
+USAGE
+  prismic docs <path> [flags]
+
+ARGUMENTS
+  path    Documentation path with optional anchor (e.g., "nextjs" or "nextjs#set-up-a-prismic-client")
+
+FLAGS
+  -h, --help   Show help for command
+
+EXAMPLES
+  prismic docs nextjs
+  prismic docs nextjs#set-up-a-prismic-client
+
+LEARN MORE
+  Visit https://prismic.io/docs for the full documentation.
+`.trim();
+
+function parsePathAndAnchor(input: string): { path: string; anchor?: string } {
+	const hashIndex = input.indexOf("#");
+	if (hashIndex === -1) {
+		return { path: input };
+	}
+	return {
+		path: input.slice(0, hashIndex),
+		anchor: input.slice(hashIndex + 1),
+	};
+}
+
+async function fetchMarkdown(
+	url: string,
+): Promise<{ ok: true; content: string } | { ok: false; error: string }> {
+	try {
+		const response = await fetch(url);
+		if (response.status === 404) {
+			return { ok: false, error: `Documentation not found: ${url}` };
+		}
+		if (!response.ok) {
+			return {
+				ok: false,
+				error: `Failed to fetch documentation: ${response.status}`,
+			};
+		}
+		const content = await response.text();
+		return { ok: true, content };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { ok: false, error: `Network error: ${message}` };
+	}
+}
+
+function anchorToHeadingPattern(anchor: string): RegExp {
+	// Convert kebab-case anchor to a pattern that matches the heading text
+	// Each hyphen/space becomes a flexible match for hyphens or spaces
+	const pattern = anchor
+		.split("-")
+		.map((word) => word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+		.join("[\\s-]+");
+	return new RegExp(`^(#{1,6})\\s+${pattern}\\s*$`, "im");
+}
+
+function extractSection(
+	markdown: string,
+	anchor: string,
+): { ok: true; content: string } | { ok: false; error: string } {
+	const lines = markdown.split("\n");
+	const headingPattern = anchorToHeadingPattern(anchor);
+
+	let startIndex = -1;
+	let headingLevel = 0;
+
+	// Find the matching heading
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].match(headingPattern);
+		if (match) {
+			startIndex = i;
+			headingLevel = match[1].length;
+			break;
+		}
+	}
+
+	if (startIndex === -1) {
+		return { ok: false, error: `Anchor not found: #${anchor}` };
+	}
+
+	// Find the end of this section (next heading of equal or lower level number)
+	let endIndex = lines.length;
+	for (let i = startIndex + 1; i < lines.length; i++) {
+		const headingMatch = lines[i].match(/^(#{1,6})\s/);
+		if (headingMatch && headingMatch[1].length <= headingLevel) {
+			endIndex = i;
+			break;
+		}
+	}
+
+	const content = lines.slice(startIndex, endIndex).join("\n").trim();
+	return { ok: true, content };
+}
+
+export async function docs(): Promise<void> {
+	const {
+		positionals: [pathArg],
+		values: { help },
+	} = parseArgs({
+		args: process.argv.slice(3),
+		options: {
+			help: { type: "boolean", short: "h" },
+		},
+		allowPositionals: true,
+	});
+
+	if (help) {
+		console.info(HELP);
+		return;
+	}
+
+	if (!pathArg) {
+		console.info(HELP);
+		return;
+	}
+
+	const { path, anchor } = parsePathAndAnchor(pathArg);
+	const url = `https://prismic.io/docs/${path}.md`;
+
+	const fetchResult = await fetchMarkdown(url);
+	if (!fetchResult.ok) {
+		console.error(fetchResult.error);
+		process.exitCode = 1;
+		return;
+	}
+
+	let output = fetchResult.content;
+
+	if (anchor) {
+		const extractResult = extractSection(output, anchor);
+		if (!extractResult.ok) {
+			console.error(extractResult.error);
+			process.exitCode = 1;
+			return;
+		}
+		output = extractResult.content;
+	}
+
+	console.info(output);
+}

package/src/index.ts

@@ -5,6 +5,7 @@ import { parseArgs } from "node:util";
 import packageJson from "../package.json" with { type: "json" };
 import { codegen } from "./codegen";
 import { customType } from "./custom-type";
+import { docs } from "./docs";
 import { init } from "./init";
 import { locale } from "./locale";
 import { login } from "./login";
@@ -40,6 +41,7 @@ COMMANDS
   pull        Pull types and slices from Prismic
   push        Push types and slices to Prismic
   codegen     Generate code from Prismic models
+  docs        Fetch documentation from Prismic
   preview     Manage preview configurations
   token       Manage API tokens in a repository
   webhook     Manage webhooks in a repository
@@ -107,6 +109,9 @@ if (version) {
 		case "codegen":
 			await codegen();
 			break;
+		case "docs":
+			await docs();
+			break;
 		case "preview":
 			await preview();
 			break;

package/src/page-type-create.ts

@@ -59,8 +59,38 @@ export async function pageTypeCreate(): Promise<void> {
 		status: true,
 		format: "page",
 		json: {
-			Main: {},
-			"SEO & Metadata": {},
+			Main: single
+				? {}
+				: {
+						uid: {
+							type: "UID",
+							config: { label: "UID", placeholder: "" },
+						},
+					},
+			"SEO & Metadata": {
+				meta_title: {
+					type: "Text",
+					config: {
+						label: "Meta Title",
+						placeholder: "A title of the page used for social media and search engines",
+					},
+				},
+				meta_description: {
+					type: "Text",
+					config: {
+						label: "Meta Description",
+						placeholder: "A brief summary of the page",
+					},
+				},
+				meta_image: {
+					type: "Image",
+					config: {
+						label: "Meta Image",
+						constraint: { width: 2400, height: 1260 },
+						thumbnails: [],
+					},
+				},
+			},
 		},
 	} satisfies CustomType;
 

package/src/status.ts

@@ -66,16 +66,53 @@ type NextStep = {
 	message: string;
 };
 
-function getDocsUrl(framework: Framework | undefined): string {
+function getDocsPath(framework: Framework | undefined): string {
 	switch (framework) {
 		case "next":
-			return "https://prismic.io/docs/nextjs/with-cli";
+			return "nextjs/with-cli";
 		case "nuxt":
-			return "https://prismic.io/docs/nuxt/with-cli";
+			return "nuxt/with-cli";
 		case "sveltekit":
-			return "https://prismic.io/docs/sveltekit/with-cli";
+			return "sveltekit/with-cli";
 		default:
-			return "https://prismic.io/docs";
+			return "";
+	}
+}
+
+function getDocsRef(docsPath: string, anchor?: string): string {
+	if (!docsPath) return "";
+	const fullPath = anchor ? `${docsPath}${anchor}` : docsPath;
+	return ` (run \`prismic docs ${fullPath}\`)`;
+}
+
+function getClientSetupAnchor(framework: Framework | undefined): string {
+	switch (framework) {
+		case "nuxt":
+			return "#configure-the-modules-prismic-client";
+		default:
+			return "#set-up-a-prismic-client";
+	}
+}
+
+function getPreviewSetupAnchor(framework: Framework | undefined): string {
+	switch (framework) {
+		case "next":
+			return "#set-up-previews-in-next-js";
+		case "sveltekit":
+			return "#set-up-previews-in-sveltekit";
+		default:
+			return "";
+	}
+}
+
+function getWriteComponentsAnchor(framework: Framework | undefined): string {
+	switch (framework) {
+		case "nuxt":
+			return "#write-vue-components";
+		case "sveltekit":
+			return "#write-svelte-components";
+		default:
+			return "#write-react-components";
 	}
 }
 
@@ -85,8 +122,9 @@ function computeNextStep(
 	typeStatuses: TypeWithStatus[],
 	sliceStatuses: TypeWithStatus[],
 	slicesWithMissingComponents: string[],
+	slicesReadyToConnect: string[],
 ): NextStep | undefined {
-	const docsUrl = getDocsUrl(frameworkInfo.framework);
+	const docsPath = getDocsPath(frameworkInfo.framework);
 
 	// 1. Setup - missing dependencies
 	const setupSection = sections.find((s) => s.title === "Setup");
@@ -99,7 +137,7 @@ function computeNextStep(
 	// 2. Setup - missing client file
 	const missingClientFile = setupSection?.items.find((i) => !i.done && i.hint?.includes("client"));
 	if (missingClientFile) {
-		return { message: `Create a ${missingClientFile.label} file (see ${docsUrl})` };
+		return { message: `Create a ${missingClientFile.label} file${getDocsRef(docsPath, getClientSetupAnchor(frameworkInfo.framework))}` };
 	}
 
 	// 3-7. Preview section (in order: local files, then remote config)
@@ -110,21 +148,21 @@ function computeNextStep(
 			(i) => i.label === "/slice-simulator route" && !i.done,
 		);
 		if (sliceSimRoute) {
-			return { message: `Create the /slice-simulator route (see ${docsUrl})` };
+			return { message: `Create the /slice-simulator route${getDocsRef(docsPath, "#set-up-live-previewing")}` };
 		}
 
 		const apiPreview = previewSection.items.find(
 			(i) => i.label === "/api/preview endpoint" && !i.done,
 		);
 		if (apiPreview) {
-			return { message: `Create the /api/preview route (see ${docsUrl})` };
+			return { message: `Create the /api/preview route${getDocsRef(docsPath, getPreviewSetupAnchor(frameworkInfo.framework))}` };
 		}
 
 		const exitPreview = previewSection.items.find(
 			(i) => i.label === "/api/exit-preview endpoint" && !i.done,
 		);
 		if (exitPreview) {
-			return { message: `Create the /api/exit-preview route (see ${docsUrl})` };
+			return { message: `Create the /api/exit-preview route${getDocsRef(docsPath, getPreviewSetupAnchor(frameworkInfo.framework))}` };
 		}
 
 		// Remote config
@@ -151,6 +189,15 @@ function computeNextStep(
 		return { message: `Pull remote models with 'prismic pull'` };
 	}
 
+	// 8.5 Slices ready to connect to a page type (before pushing)
+	if (slicesReadyToConnect.length > 0) {
+		const sorted = [...slicesReadyToConnect].sort();
+		const sliceName = sorted[0];
+		return {
+			message: `Connect ${sliceName} to a page type with 'prismic page-type connect-slice <type-id> ${sliceName}'`,
+		};
+	}
+
 	// 9. Models to push
 	const hasToPush =
 		typeStatuses.some((t) => t.status === "to_push") ||
@@ -166,7 +213,7 @@ function computeNextStep(
 		const slicesDir = getSlicesDirectory(frameworkInfo);
 		const ext = getSliceComponentExtensions(frameworkInfo.framework)[0];
 		const path = `${slicesDir}${sliceName}/index${ext}`;
-		return { message: `Implement the ${sliceName} slice component at ${path} (see ${docsUrl})` };
+		return { message: `Implement the ${sliceName} slice component at ${path}${getDocsRef(docsPath, getWriteComponentsAnchor(frameworkInfo.framework))}` };
 	}
 
 	// 11-12. Deployment (Next.js only)
@@ -176,7 +223,7 @@ function computeNextStep(
 			(i) => i.label === "/api/revalidate endpoint" && !i.done,
 		);
 		if (revalidateEndpoint) {
-			return { message: `Create the /api/revalidate route for ISR (see ${docsUrl})` };
+			return { message: `Create the /api/revalidate route for ISR${getDocsRef(docsPath, "#handle-content-changes")}` };
 		}
 
 		const webhook = deploymentSection.items.find(
@@ -261,6 +308,7 @@ export async function status(): Promise<void> {
 	let typeStatuses: TypeWithStatus[] = [];
 	let sliceStatuses: TypeWithStatus[] = [];
 	let slicesWithMissingComponents: string[] = [];
+	let slicesReadyToConnect: string[] = [];
 
 	// Setup section
 	const setupSection = await buildSetupSection(frameworkInfo, installedDeps);
@@ -283,10 +331,17 @@ export async function status(): Promise<void> {
 			section: slicesSection,
 			statuses,
 			missingComponents,
-		} = await buildSlicesSection(localSlicesResult.value, remoteSlicesResult.value, frameworkInfo);
+			slicesReadyToConnect: readyToConnect,
+		} = await buildSlicesSection(
+			localSlicesResult.value,
+			remoteSlicesResult.value,
+			frameworkInfo,
+			localTypesResult.ok ? localTypesResult.value : [],
+		);
 		sections.push(slicesSection);
 		sliceStatuses = statuses;
 		slicesWithMissingComponents = missingComponents;
+		slicesReadyToConnect = readyToConnect;
 	}
 
 	// Preview section
@@ -318,6 +373,7 @@ export async function status(): Promise<void> {
 		typeStatuses,
 		sliceStatuses,
 		slicesWithMissingComponents,
+		slicesReadyToConnect,
 	);
 	if (nextStep) {
 		console.info(`Next: ${nextStep.message}`);
@@ -554,23 +610,66 @@ function statusToHint(status: TypeStatus): string | undefined {
 }
 
 // Slices Section
+function sliceHasFields(slice: SharedSlice): boolean {
+	for (const variation of slice.variations) {
+		const primaryFields = Object.keys(variation.primary ?? {});
+		const itemFields = Object.keys(variation.items ?? {});
+		if (primaryFields.length > 0 || itemFields.length > 0) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function isSliceConnectedToAnyType(sliceId: string, localTypes: CustomType[]): boolean {
+	for (const type of localTypes) {
+		for (const tabFields of Object.values(type.json)) {
+			for (const field of Object.values(tabFields as Record<string, unknown>)) {
+				const typedField = field as {
+					type?: string;
+					config?: { choices?: Record<string, unknown> };
+				};
+				if (typedField.type === "Slices" && typedField.config?.choices?.[sliceId]) {
+					return true;
+				}
+			}
+		}
+	}
+	return false;
+}
+
 async function buildSlicesSection(
 	localSlices: SharedSlice[],
 	remoteSlices: SharedSlice[],
 	info: FrameworkInfo,
+	localTypes: CustomType[],
 ): Promise<{
 	section: StatusSection;
 	statuses: TypeWithStatus[];
 	missingComponents: string[];
+	slicesReadyToConnect: string[];
 }> {
 	const sliceStatuses = computeTypeStatus(localSlices, remoteSlices);
 	const items: StatusItem[] = [];
 	const missingComponents: string[] = [];
+	const slicesReadyToConnect: string[] = [];
 
 	const slicesDir = getSlicesDirectory(info);
 	const extensions = getSliceComponentExtensions(info.framework);
 
 	for (const slice of sliceStatuses) {
+		const localSlice = localSlices.find((s) => s.id === slice.id);
+
+		// Track slices that have fields but aren't connected to any type
+		// These should be connected before pushing
+		if (localSlice) {
+			const hasFields = sliceHasFields(localSlice);
+			const isConnected = isSliceConnectedToAnyType(slice.id, localTypes);
+
+			if (hasFields && !isConnected) {
+				slicesReadyToConnect.push(slice.label);
+			}
+		}
 		// Check if component is implemented
 		const componentExists = await checkSliceComponent(info, slicesDir, slice.id, extensions);
 
@@ -600,6 +699,7 @@ async function buildSlicesSection(
 		section: { title: "Slices", items },
 		statuses: sliceStatuses,
 		missingComponents,
+		slicesReadyToConnect,
 	};
 }