@angeloashmore/prismic-cli-poc 0.0.0-canary.5da487c → 0.0.0-canary.63deeeb

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@angeloashmore/prismic-cli-poc",
-	"version": "0.0.0-canary.5da487c",
+	"version": "0.0.0-canary.63deeeb",
 	"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

@@ -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";
 	}
 }
 
@@ -86,7 +123,7 @@ function computeNextStep(
 	sliceStatuses: TypeWithStatus[],
 	slicesWithMissingComponents: 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 +136,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 +147,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
@@ -166,7 +203,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 +213,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(