@angeloashmore/prismic-cli-poc 0.0.0-pr.9.92b6b39 → 0.0.0-pr.9.e40beab

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@angeloashmore/prismic-cli-poc",
-	"version": "0.0.0-pr.9.92b6b39",
+	"version": "0.0.0-pr.9.e40beab",
 	"description": "A proof-of-concept developer CLI for Prismic.",
 	"keywords": [
 		"prismic",

package/src/docs-fetch.ts

@@ -0,0 +1,146 @@
+import { parseArgs } from "node:util";
+
+const HELP = `
+Fetch and display documentation from Prismic's docs site.
+
+USAGE
+  prismic docs fetch <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 fetch nextjs
+  prismic docs fetch 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.
+	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;
+
+	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}` };
+	}
+
+	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 docsFetch(): Promise<void> {
+	const {
+		positionals: [pathArg],
+		values: { help },
+	} = parseArgs({
+		args: process.argv.slice(4),
+		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/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

@@ -1,149 +1,54 @@
 import { parseArgs } from "node:util";
+import { docsFetch } from "./docs-fetch";
+import { docsList } from "./docs-list";
 
 const HELP = `
-Fetch and display documentation from Prismic's docs site.
+Fetch and list documentation from Prismic's docs site.
 
 USAGE
-  prismic docs <path> [flags]
+  prismic docs <command> [flags]
 
-ARGUMENTS
-  path    Documentation path with optional anchor (e.g., "nextjs" or "nextjs#set-up-a-prismic-client")
+COMMANDS
+  fetch      Fetch and display a documentation page
+  list       List documentation pages
 
 FLAGS
   -h, --help   Show help for command
 
 EXAMPLES
-  prismic docs nextjs
-  prismic docs nextjs#set-up-a-prismic-client
+  prismic docs fetch nextjs
+  prismic docs fetch nextjs#set-up-a-prismic-client
+  prismic docs list
 
 LEARN MORE
-  Visit https://prismic.io/docs for the full documentation.
+  Use \`prismic docs <command> --help\` for more information about a command.
 `.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 },
+		positionals: [subcommand],
 	} = parseArgs({
 		args: process.argv.slice(3),
 		options: {
 			help: { type: "boolean", short: "h" },
 		},
 		allowPositionals: true,
+		strict: false,
 	});
 
-	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;
+	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);
 		}
-		output = extractResult.content;
 	}
-
-	console.info(output);
 }

package/src/index.ts

@@ -42,7 +42,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
+  docs        Fetch and list documentation from Prismic
   skill       Manage Prismic AI skills
   preview     Manage preview configurations
   token       Manage API tokens in a repository

package/src/page-type-add-field-boolean.ts

@@ -232,7 +232,7 @@ export async function pageTypeAddFieldBoolean(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-color.ts

@@ -218,7 +218,7 @@ export async function pageTypeAddFieldColor(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-date.ts

@@ -221,7 +221,7 @@ export async function pageTypeAddFieldDate(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-embed.ts

@@ -218,7 +218,7 @@ export async function pageTypeAddFieldEmbed(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-geo-point.ts

@@ -215,7 +215,7 @@ export async function pageTypeAddFieldGeoPoint(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-group.ts

@@ -192,7 +192,7 @@ export async function pageTypeAddFieldGroup(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-image.ts

@@ -218,7 +218,7 @@ export async function pageTypeAddFieldImage(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-key-text.ts

@@ -218,7 +218,7 @@ export async function pageTypeAddFieldKeyText(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-link.ts

@@ -241,7 +241,7 @@ export async function pageTypeAddFieldLink(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-number.ts

@@ -250,7 +250,7 @@ export async function pageTypeAddFieldNumber(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-rich-text.ts

@@ -242,7 +242,7 @@ export async function pageTypeAddFieldRichText(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-select.ts

@@ -224,7 +224,7 @@ export async function pageTypeAddFieldSelect(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-timestamp.ts

@@ -221,7 +221,7 @@ export async function pageTypeAddFieldTimestamp(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-add-field-uid.ts

@@ -201,7 +201,7 @@ export async function pageTypeAddFieldUid(): Promise<void> {
 	if (frameworkInfo?.framework) {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}#write-page-components\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}#write-page-components\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/page-type-create.ts

@@ -151,7 +151,7 @@ export async function pageTypeCreate(): Promise<void> {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		const anchor = getWritePageComponentsAnchor(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}${anchor}\` to learn how to implement a page file`,
+			`      Run \`prismic docs fetch ${docsPath}${anchor}\` to learn how to implement a page file`,
 		);
 	}
 }

package/src/repo-create.ts

@@ -160,7 +160,7 @@ export async function repoCreate(): Promise<void> {
 		const clientFile = getClientFilePath(frameworkInfo);
 		const fileDesc = clientFile ? `creating ${clientFile}` : "configuring Prismic";
 		console.info();
-		console.info(`Next: Run \`prismic docs ${docsPath}${anchor}\` for instructions on ${fileDesc}`);
+		console.info(`Next: Run \`prismic docs fetch ${docsPath}${anchor}\` for instructions on ${fileDesc}`);
 	}
 }
 

package/src/skill-install.ts

@@ -36,7 +36,7 @@ For Prismic-related tasks, use the \`prismic\` CLI first.
 
 1. Discover capabilities with \`prismic --help\`.
 2. Inspect details with \`prismic <command> --help\`.
-3. Use \`prismic docs <path>\` when documentation is needed.
+3. Use \`prismic docs list\` to discover docs paths, then \`prismic docs fetch <path>\` when documentation is needed.
 4. Prefer CLI workflows over direct API/manual changes.
 5. If the CLI does not support a required operation, state that explicitly, then use the next-best fallback.
 `.trim();
@@ -79,7 +79,7 @@ export async function findGlobalSkillInstallTargets(config?: {
 
 export async function skillInstall(): Promise<void> {
 	const {
-		values: { dryRun, help },
+		values: { "dry-run": dryRun, help },
 	} = parseArgs({
 		args: process.argv.slice(4), // skip: node, script, "skill", "install"
 		options: {

package/src/skill-uninstall.ts

@@ -21,7 +21,7 @@ LEARN MORE
 
 export async function skillUninstall(): Promise<void> {
 	const {
-		values: { dryRun, help },
+		values: { "dry-run": dryRun, help },
 	} = parseArgs({
 		args: process.argv.slice(4), // skip: node, script, "skill", "uninstall"
 		options: {

package/src/slice-add-field-boolean.ts

@@ -234,7 +234,7 @@ export async function sliceAddFieldBoolean(): Promise<void> {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		const anchor = getWriteComponentsAnchor(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}${anchor}\` to learn how to implement the slice's component`,
+			`      Run \`prismic docs fetch ${docsPath}${anchor}\` to learn how to implement the slice's component`,
 		);
 	}
 }

package/src/slice-add-field-color.ts

@@ -220,7 +220,7 @@ export async function sliceAddFieldColor(): Promise<void> {
 		const docsPath = getDocsPath(frameworkInfo.framework);
 		const anchor = getWriteComponentsAnchor(frameworkInfo.framework);
 		console.info(
-			`      Run \`prismic docs ${docsPath}${anchor}\` to learn how to implement the slice's component`,
+			`      Run \`prismic docs fetch ${docsPath}${anchor}\` to learn how to implement the slice's component`,
 		);
 	}
 }