@angeloashmore/prismic-cli-poc 0.0.0-pr.4.d609497 → 0.0.0-pr.5.f8fb51a

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@angeloashmore/prismic-cli-poc",
-	"version": "0.0.0-pr.4.d609497",
+	"version": "0.0.0-pr.5.f8fb51a",
 	"description": "A proof-of-concept developer CLI for Prismic.",
 	"keywords": [
 		"prismic",

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/status.ts

@@ -14,6 +14,7 @@ import {
 } from "./lib/custom-types-api";
 import { exists } from "./lib/file";
 import {
+	type Framework,
 	type FrameworkInfo,
 	detectFrameworkInfo,
 	getClientFilePath,
@@ -29,6 +30,9 @@ import { getWebhooks } from "./webhook-view";
 const HELP = `
 Show the status of the current Prismic project.
 
+Includes a "Next:" step showing the most important action to take based on
+project state.
+
 By default, this command reads the repository from prismic.config.json at the
 project root.
 
@@ -58,6 +62,172 @@ type StatusSection = {
 	items: StatusItem[];
 };
 
+type NextStep = {
+	message: string;
+};
+
+function getDocsPath(framework: Framework | undefined): string {
+	switch (framework) {
+		case "next":
+			return "nextjs/with-cli";
+		case "nuxt":
+			return "nuxt/with-cli";
+		case "sveltekit":
+			return "sveltekit/with-cli";
+		default:
+			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";
+	}
+}
+
+function computeNextStep(
+	sections: StatusSection[],
+	frameworkInfo: FrameworkInfo,
+	typeStatuses: TypeWithStatus[],
+	sliceStatuses: TypeWithStatus[],
+	slicesWithMissingComponents: string[],
+): NextStep | undefined {
+	const docsPath = getDocsPath(frameworkInfo.framework);
+
+	// 1. Setup - missing dependencies
+	const setupSection = sections.find((s) => s.title === "Setup");
+	const missingDeps = setupSection?.items.filter((i) => !i.done && i.hint === "not installed");
+	if (missingDeps && missingDeps.length > 0) {
+		const depsList = missingDeps.map((d) => d.label).join(" ");
+		return { message: `Install Prismic packages with 'npm install ${depsList}'` };
+	}
+
+	// 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${getDocsRef(docsPath, getClientSetupAnchor(frameworkInfo.framework))}` };
+	}
+
+	// 3-7. Preview section (in order: local files, then remote config)
+	const previewSection = sections.find((s) => s.title === "Preview");
+	if (previewSection) {
+		// Local files first
+		const sliceSimRoute = previewSection.items.find(
+			(i) => i.label === "/slice-simulator route" && !i.done,
+		);
+		if (sliceSimRoute) {
+			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${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${getDocsRef(docsPath, getPreviewSetupAnchor(frameworkInfo.framework))}` };
+		}
+
+		// Remote config
+		const simulatorUrl = previewSection.items.find(
+			(i) => i.label === "Slice simulator URL" && !i.done,
+		);
+		if (simulatorUrl) {
+			return { message: `Configure the slice simulator URL with 'prismic preview set-simulator'` };
+		}
+
+		const previewEnv = previewSection.items.find(
+			(i) => i.label === "Preview environment" && !i.done,
+		);
+		if (previewEnv) {
+			return { message: `Add a preview environment with 'prismic preview add'` };
+		}
+	}
+
+	// 8. Models to pull
+	const hasToPull =
+		typeStatuses.some((t) => t.status === "to_pull") ||
+		sliceStatuses.some((s) => s.status === "to_pull");
+	if (hasToPull) {
+		return { message: `Pull remote models with 'prismic pull'` };
+	}
+
+	// 9. Models to push
+	const hasToPush =
+		typeStatuses.some((t) => t.status === "to_push") ||
+		sliceStatuses.some((s) => s.status === "to_push");
+	if (hasToPush) {
+		return { message: `Push local models with 'prismic push'` };
+	}
+
+	// 10. Slice components to implement (first alphabetically)
+	if (slicesWithMissingComponents.length > 0) {
+		const sorted = [...slicesWithMissingComponents].sort();
+		const sliceName = sorted[0];
+		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}${getDocsRef(docsPath, getWriteComponentsAnchor(frameworkInfo.framework))}` };
+	}
+
+	// 11-12. Deployment (Next.js only)
+	const deploymentSection = sections.find((s) => s.title === "Deployment");
+	if (deploymentSection) {
+		const revalidateEndpoint = deploymentSection.items.find(
+			(i) => i.label === "/api/revalidate endpoint" && !i.done,
+		);
+		if (revalidateEndpoint) {
+			return { message: `Create the /api/revalidate route for ISR${getDocsRef(docsPath, "#handle-content-changes")}` };
+		}
+
+		const webhook = deploymentSection.items.find(
+			(i) => i.label === "Revalidation webhook" && !i.done,
+		);
+		if (webhook) {
+			return { message: `Create a revalidation webhook with 'prismic webhook create'` };
+		}
+	}
+
+	// All complete
+	return undefined;
+}
+
 export async function status(): Promise<void> {
 	const {
 		values: { help, repo = await safeGetRepositoryFromConfig() },
@@ -118,39 +288,42 @@ export async function status(): Promise<void> {
 
 	// Print repository header
 	const repoUrl = await getRepoUrl(repo);
-	console.info(`Repository:         ${repo}`);
-	console.info(`URL:                ${repoUrl.href}`);
-
-	if (repoInfoResult.ok) {
-		const accessLevel = formatApiAccess(repoInfoResult.value.api_access);
-		console.info(`Content API Access: ${accessLevel}`);
-	}
+	console.info(`Repository: ${repo}`);
+	console.info(`URL:        ${repoUrl.href}`);
 	console.info("");
 
 	const sections: StatusSection[] = [];
 
+	// Track statuses for next step computation
+	let typeStatuses: TypeWithStatus[] = [];
+	let sliceStatuses: TypeWithStatus[] = [];
+	let slicesWithMissingComponents: string[] = [];
+
 	// Setup section
 	const setupSection = await buildSetupSection(frameworkInfo, installedDeps);
 	sections.push(setupSection);
 
 	// Types sections (Page Types and Custom Types)
 	if (localTypesResult.ok && remoteTypesResult.ok) {
-		const { pageTypes, customTypes } = buildTypeSections(
+		const { pageTypes, customTypes, allTypeStatuses } = buildTypeSections(
 			localTypesResult.value,
 			remoteTypesResult.value,
 		);
 		sections.push(pageTypes);
 		sections.push(customTypes);
+		typeStatuses = allTypeStatuses;
 	}
 
 	// Slices section
 	if (localSlicesResult.ok && remoteSlicesResult.ok) {
-		const slicesSection = await buildSlicesSection(
-			localSlicesResult.value,
-			remoteSlicesResult.value,
-			frameworkInfo,
-		);
+		const {
+			section: slicesSection,
+			statuses,
+			missingComponents,
+		} = await buildSlicesSection(localSlicesResult.value, remoteSlicesResult.value, frameworkInfo);
 		sections.push(slicesSection);
+		sliceStatuses = statuses;
+		slicesWithMissingComponents = missingComponents;
 	}
 
 	// Preview section
@@ -174,6 +347,18 @@ export async function status(): Promise<void> {
 	for (const section of sections) {
 		printSection(section);
 	}
+
+	// Print next step
+	const nextStep = computeNextStep(
+		sections,
+		frameworkInfo,
+		typeStatuses,
+		sliceStatuses,
+		slicesWithMissingComponents,
+	);
+	if (nextStep) {
+		console.info(`Next: ${nextStep.message}`);
+	}
 }
 
 function printSection(section: StatusSection): void {
@@ -208,9 +393,8 @@ function printSection(section: StatusSection): void {
 	console.info("");
 }
 
-// Repository Info
+// Repository Info (from /core/repository)
 const RepositoryInfoSchema = v.object({
-	api_access: v.optional(v.string()),
 	simulator_url: v.optional(v.string()),
 });
 type RepositoryInfo = v.InferOutput<typeof RepositoryInfoSchema>;
@@ -226,19 +410,6 @@ async function fetchRepositoryInfo(
 	return { ok: false };
 }
 
-function formatApiAccess(access: string | undefined): string {
-	switch (access) {
-		case "private":
-			return "Private";
-		case "open":
-			return "Open";
-		case "master_only":
-			return "Master only";
-		default:
-			return access || "Unknown";
-	}
-}
-
 // Previews
 const PreviewSchema = v.object({
 	id: v.string(),
@@ -371,7 +542,7 @@ function computeTypeStatus<T extends { id: string }>(local: T[], remote: T[]): T
 function buildTypeSections(
 	localTypes: CustomType[],
 	remoteTypes: CustomType[],
-): { pageTypes: StatusSection; customTypes: StatusSection } {
+): { pageTypes: StatusSection; customTypes: StatusSection; allTypeStatuses: TypeWithStatus[] } {
 	const typeStatuses = computeTypeStatus(localTypes, remoteTypes);
 
 	// Separate by format
@@ -404,6 +575,7 @@ function buildTypeSections(
 	return {
 		pageTypes: { title: "Page Types", items: pageTypeItems },
 		customTypes: { title: "Custom Types", items: customTypeItems },
+		allTypeStatuses: typeStatuses,
 	};
 }
 
@@ -423,9 +595,14 @@ async function buildSlicesSection(
 	localSlices: SharedSlice[],
 	remoteSlices: SharedSlice[],
 	info: FrameworkInfo,
-): Promise<StatusSection> {
+): Promise<{
+	section: StatusSection;
+	statuses: TypeWithStatus[];
+	missingComponents: string[];
+}> {
 	const sliceStatuses = computeTypeStatus(localSlices, remoteSlices);
 	const items: StatusItem[] = [];
+	const missingComponents: string[] = [];
 
 	const slicesDir = getSlicesDirectory(info);
 	const extensions = getSliceComponentExtensions(info.framework);
@@ -446,6 +623,7 @@ async function buildSlicesSection(
 				label: slice.label,
 				hint: "missing component",
 			});
+			missingComponents.push(slice.label);
 		} else {
 			items.push({
 				done: false,
@@ -455,7 +633,11 @@ async function buildSlicesSection(
 		}
 	}
 
-	return { title: "Slices", items };
+	return {
+		section: { title: "Slices", items },
+		statuses: sliceStatuses,
+		missingComponents,
+	};
 }
 
 async function checkSliceComponent(