@angeloashmore/prismic-cli-poc 0.0.0-pr.8.b80fefa → 0.0.0-pr.9.5366ece

package/src/repo-create.ts

@@ -2,6 +2,7 @@ import { parseArgs } from "node:util";
 
 import { isAuthenticated, readHost } from "./lib/auth";
 import { createConfig, readConfig, updateConfig } from "./lib/config";
+import { type Framework, detectFrameworkInfo, getClientFilePath } from "./lib/framework";
 import { stringify } from "./lib/json";
 import { ForbiddenRequestError, request } from "./lib/request";
 import { getRepoUrl } from "./lib/url";
@@ -31,6 +32,26 @@ LEARN MORE
 
 const DOMAIN_REGEX = /^[a-zA-Z0-9][-a-zA-Z0-9]{2,}[a-zA-Z0-9]$/;
 
+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";
+	}
+}
+
+function getClientSetupAnchor(framework: Framework): string {
+	switch (framework) {
+		case "nuxt":
+			return "#configure-the-modules-prismic-client";
+		default:
+			return "#set-up-a-prismic-client";
+	}
+}
+
 export async function repoCreate(): Promise<void> {
 	const {
 		values: { help, name, "no-config": noConfig, replace },
@@ -81,6 +102,23 @@ export async function repoCreate(): Promise<void> {
 		return;
 	}
 
+	// Check if domain is available
+	const available = await checkDomainAvailable(domain);
+	if (!available.ok) {
+		if (available.error instanceof ForbiddenRequestError) {
+			handleUnauthenticated();
+		} else {
+			console.error(`Failed to check domain availability: ${stringify(available.error)}`);
+			process.exitCode = 1;
+		}
+		return;
+	}
+	if (!available.value) {
+		console.error(`Repository name "${domain}" is already taken.`);
+		process.exitCode = 1;
+		return;
+	}
+
 	const response = await createRepository(domain, name);
 	if (!response.ok) {
 		if (response.error instanceof ForbiddenRequestError) {
@@ -113,6 +151,27 @@ export async function repoCreate(): Promise<void> {
 
 	console.info(`Repository created: ${domain}`);
 	console.info(`URL: ${await getRepoUrl(domain)}`);
+
+	// Print framework-specific next steps
+	const frameworkInfo = await detectFrameworkInfo();
+	if (frameworkInfo?.framework) {
+		const docsPath = getDocsPath(frameworkInfo.framework);
+		const anchor = getClientSetupAnchor(frameworkInfo.framework);
+		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}`);
+	}
+}
+
+async function checkDomainAvailable(domain: string) {
+	const url = new URL(`/app/dashboard/repositories/${domain}/exists`, await readHost());
+	const response = await request<string>(url);
+	if (!response.ok) {
+		return response;
+	}
+	// Endpoint returns "false" when repository exists, "true" when available
+	return { ok: true as const, value: response.value === "true" };
 }
 
 async function createRepository(domain: string, name = domain) {

package/src/skill-install.ts

@@ -0,0 +1,177 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+
+import { exists } from "./lib/file";
+import { appendTrailingSlash } from "./lib/url";
+
+const HELP = `
+Install the Prismic skill into supported global AI tool skill directories.
+
+USAGE
+  prismic skill install [flags]
+
+FLAGS
+  -h, --help   Show help for command
+
+LEARN MORE
+  This command currently installs to global/user tool directories only.
+`.trim();
+
+const SKILL_ID = "prismic";
+const SKILL_FILENAME = "SKILL.md";
+
+export const PRISMIC_SKILL_TEMPLATE = `
+---
+name: prismic
+description: Use when a task involves Prismic setup, repository configuration, content modeling, content type or slice changes, localization, previews, API tokens, webhooks, syncing local models, or reading Prismic documentation.
+allowed-tools: Bash(prismic *)
+---
+
+# Prismic Workflows
+
+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.
+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();
+
+export type SkillInstallTarget = {
+	tool: string;
+	baseDir: URL;
+	skillsDir: URL;
+	skillDir: URL;
+	skillFile: URL;
+};
+
+export async function findGlobalSkillInstallTargets(config?: {
+	homeDir?: string;
+}): Promise<SkillInstallTarget[]> {
+	const homeURL = appendTrailingSlash(pathToFileURL(config?.homeDir ?? homedir()));
+	const codexBaseURL = new URL(".codex/", homeURL);
+
+	const candidates: SkillInstallTarget[] = [
+		createTarget("Claude", new URL(".claude/", homeURL), new URL(".claude/skills/", homeURL)),
+		createTarget("Cursor", new URL(".cursor/", homeURL), new URL(".cursor/skills/", homeURL)),
+		createTarget("Gemini", new URL(".gemini/", homeURL), new URL(".gemini/skills/", homeURL)),
+		createTarget(
+			"OpenCode",
+			new URL(".config/opencode/", homeURL),
+			new URL(".config/opencode/skill/", homeURL),
+		),
+		createTarget("Codex", codexBaseURL, new URL("skills/", codexBaseURL)),
+	];
+
+	const targets: SkillInstallTarget[] = [];
+	for (const target of candidates) {
+		if (await exists(target.baseDir)) {
+			targets.push(target);
+		}
+	}
+
+	return targets;
+}
+
+export async function skillInstall(): Promise<void> {
+	const {
+		values: { help },
+	} = parseArgs({
+		args: process.argv.slice(4), // skip: node, script, "skill", "install"
+		options: {
+			help: { type: "boolean", short: "h" },
+		},
+		allowPositionals: true,
+		strict: false,
+	});
+
+	if (help) {
+		console.info(HELP);
+		return;
+	}
+
+	const targets = await findGlobalSkillInstallTargets();
+
+	if (targets.length === 0) {
+		console.error(
+			"No supported global AI tool directories were detected (Claude, Cursor, Gemini, OpenCode, Codex).",
+		);
+		process.exitCode = 1;
+		return;
+	}
+
+	const conflicts: SkillInstallTarget[] = [];
+	conflicts.push(...(await findExistingSkillConflicts(targets)));
+
+	if (conflicts.length > 0) {
+		console.error("Skill already exists in one or more targets:");
+		for (const conflict of conflicts) {
+			console.error(`- ${fileURLToPath(conflict.skillFile)}`);
+		}
+		console.error("Nothing was installed. Remove existing files and retry.");
+		process.exitCode = 1;
+		return;
+	}
+
+	const installResult = await installSkillTemplateToTargets(PRISMIC_SKILL_TEMPLATE, targets);
+	if (!installResult.ok) {
+		console.error(`Failed to install skill for ${installResult.target.tool}: ${installResult.error}`);
+		console.error(`Path: ${fileURLToPath(installResult.target.skillFile)}`);
+		process.exitCode = 1;
+		return;
+	}
+	const installedPaths = installResult.installedPaths;
+
+	for (const installedPath of installedPaths) {
+		console.info(`Installed: ${installedPath}`);
+	}
+	console.info(`Installed ${installedPaths.length} Prismic skill file(s).`);
+}
+
+export async function findExistingSkillConflicts(
+	targets: SkillInstallTarget[],
+): Promise<SkillInstallTarget[]> {
+	const conflicts: SkillInstallTarget[] = [];
+	for (const target of targets) {
+		if (await exists(target.skillFile)) {
+			conflicts.push(target);
+		}
+	}
+	return conflicts;
+}
+
+export async function installSkillTemplateToTargets(
+	template: string,
+	targets: SkillInstallTarget[],
+): Promise<
+	| { ok: true; installedPaths: string[] }
+	| { ok: false; target: SkillInstallTarget; error: string }
+> {
+	const installedPaths: string[] = [];
+	for (const target of targets) {
+		try {
+			await mkdir(target.skillDir, { recursive: true });
+			await writeFile(target.skillFile, template);
+			installedPaths.push(fileURLToPath(target.skillFile));
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return { ok: false, target, error: message };
+		}
+	}
+
+	return { ok: true, installedPaths };
+}
+
+function createTarget(tool: string, baseDir: URL, skillsDir: URL): SkillInstallTarget {
+	const skillDir = new URL(`${SKILL_ID}/`, skillsDir);
+	return {
+		tool,
+		baseDir,
+		skillsDir,
+		skillDir,
+		skillFile: new URL(SKILL_FILENAME, skillDir),
+	};
+}

package/src/skill-uninstall.ts

@@ -0,0 +1,85 @@
+import { rm, rmdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+import { exists } from "./lib/file";
+import { findGlobalSkillInstallTargets } from "./skill-install";
+
+const HELP = `
+Uninstall the Prismic skill from supported global AI tool skill directories.
+
+USAGE
+  prismic skill uninstall [flags]
+
+FLAGS
+  -h, --help   Show help for command
+
+LEARN MORE
+  This command currently uninstalls from global/user tool directories only.
+`.trim();
+
+export async function skillUninstall(): Promise<void> {
+	const {
+		values: { help },
+	} = parseArgs({
+		args: process.argv.slice(4), // skip: node, script, "skill", "uninstall"
+		options: {
+			help: { type: "boolean", short: "h" },
+		},
+		allowPositionals: true,
+		strict: false,
+	});
+
+	if (help) {
+		console.info(HELP);
+		return;
+	}
+
+	const targets = await findGlobalSkillInstallTargets();
+
+	const removedSkillFiles: string[] = [];
+
+	for (const target of targets) {
+		if (!(await exists(target.skillFile))) {
+			continue;
+		}
+
+		try {
+			await rm(target.skillFile);
+			removedSkillFiles.push(fileURLToPath(target.skillFile));
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			console.error(`Failed to remove skill for ${target.tool}: ${message}`);
+			console.error(`Path: ${fileURLToPath(target.skillFile)}`);
+			process.exitCode = 1;
+			return;
+		}
+
+		try {
+			await rmdir(target.skillDir);
+		} catch (error) {
+			if (error && typeof error === "object" && "code" in error) {
+				const code = String(error.code);
+				if (code === "ENOTEMPTY" || code === "ENOENT") {
+					continue;
+				}
+			}
+
+			const message = error instanceof Error ? error.message : String(error);
+			console.error(`Failed to clean up skill directory for ${target.tool}: ${message}`);
+			console.error(`Path: ${fileURLToPath(target.skillDir)}`);
+			process.exitCode = 1;
+			return;
+		}
+	}
+
+	if (removedSkillFiles.length === 0) {
+		console.info("No Prismic skill installation found. Nothing to uninstall.");
+		return;
+	}
+
+	for (const removedSkillFile of removedSkillFiles) {
+		console.info(`Removed: ${removedSkillFile}`);
+	}
+	console.info(`Uninstalled ${removedSkillFiles.length} Prismic skill file(s).`);
+}

package/src/skill.ts

@@ -0,0 +1,50 @@
+import { parseArgs } from "node:util";
+
+import { skillInstall } from "./skill-install";
+import { skillUninstall } from "./skill-uninstall";
+
+const HELP = `
+Manage Prismic skills in supported AI tool directories.
+
+USAGE
+  prismic skill <command> [flags]
+
+COMMANDS
+  install    Install the Prismic skill into detected global skill directories
+  uninstall  Uninstall the Prismic skill from detected global skill directories
+
+FLAGS
+  -h, --help   Show help for command
+
+LEARN MORE
+  Use \`prismic skill <command> --help\` for more information about a command.
+`.trim();
+
+export async function skill(): Promise<void> {
+	const {
+		positionals: [subcommand],
+	} = parseArgs({
+		args: process.argv.slice(3), // skip: node, script, "skill"
+		options: {
+			help: { type: "boolean", short: "h" },
+		},
+		allowPositionals: true,
+		strict: false,
+	});
+
+	switch (subcommand) {
+		case "install":
+			await skillInstall();
+			break;
+		case "uninstall":
+			await skillUninstall();
+			break;
+		default: {
+			if (subcommand) {
+				console.error(`Unknown skill subcommand: ${subcommand}\n`);
+				process.exitCode = 1;
+			}
+			console.info(HELP);
+		}
+	}
+}

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

@@ -4,6 +4,8 @@ import { writeFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
 
 import { buildTypes } from "./codegen-types";
+import { findGroupInVariation, isGroupField, parseFieldPath, validateNestedFieldPath } from "./lib/field-path";
+import { type Framework, detectFrameworkInfo } from "./lib/framework";
 import { stringify } from "./lib/json";
 import { findSliceModel } from "./lib/slice";
 import { humanReadable } from "./lib/string";
@@ -33,6 +35,28 @@ EXAMPLES
   prismic slice add-field boolean product available --true-label "In Stock" --false-label "Out of Stock"
 `.trim();
 
+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";
+	}
+}
+
+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 async function sliceAddFieldBoolean(): Promise<void> {
 	const {
 		values: {
@@ -78,6 +102,15 @@ export async function sliceAddFieldBoolean(): Promise<void> {
 		return;
 	}
 
+	// Parse and validate field path
+	const fieldPath = parseFieldPath(fieldId);
+	const pathValidation = validateNestedFieldPath(fieldPath);
+	if (!pathValidation.ok) {
+		console.error(pathValidation.error);
+		process.exitCode = 1;
+		return;
+	}
+
 	// Find the slice model
 	const result = await findSliceModel(sliceId);
 	if (!result.ok) {
@@ -113,28 +146,55 @@ export async function sliceAddFieldBoolean(): Promise<void> {
 		targetVariation.primary = {};
 	}
 
-	// Check if field already exists in any variation
-	for (const v of model.variations) {
-		if (v.primary?.[fieldId]) {
-			console.error(`Field "${fieldId}" already exists in variation "${v.id}"`);
-			process.exitCode = 1;
-			return;
-		}
-	}
-
 	// Build field definition
 	const fieldDefinition: BooleanField = {
 		type: "Boolean",
 		config: {
-			label: label ?? humanReadable(fieldId),
+			label: label ?? humanReadable(fieldPath.type === "nested" ? fieldPath.nestedFieldId : fieldId),
 			...(defaultValue && { default_value: true }),
 			...(trueLabel && { placeholder_true: trueLabel }),
 			...(falseLabel && { placeholder_false: falseLabel }),
 		},
 	};
 
-	// Add field to variation
-	targetVariation.primary[fieldId] = fieldDefinition;
+	// Add field to variation (with nested field support)
+	if (fieldPath.type === "nested") {
+		const groupResult = findGroupInVariation(targetVariation.primary, fieldPath.groupId, targetVariation.id);
+		if (!groupResult.ok) {
+			console.error(groupResult.error);
+			process.exitCode = 1;
+			return;
+		}
+		// Check if nested field already exists
+		if (groupResult.group.config.fields[fieldPath.nestedFieldId]) {
+			console.error(
+				`Field "${fieldPath.nestedFieldId}" already exists in group "${fieldPath.groupId}"`,
+			);
+			process.exitCode = 1;
+			return;
+		}
+		groupResult.group.config.fields[fieldPath.nestedFieldId] = fieldDefinition;
+	} else {
+		// Check if field already exists in any variation (at top level or in groups)
+		for (const v of model.variations) {
+			if (v.primary?.[fieldId]) {
+				console.error(`Field "${fieldId}" already exists in variation "${v.id}"`);
+				process.exitCode = 1;
+				return;
+			}
+			// Also check inside groups
+			for (const [groupFieldId, groupField] of Object.entries(v.primary ?? {})) {
+				if (isGroupField(groupField) && groupField.config.fields[fieldId]) {
+					console.error(
+						`Field "${fieldId}" already exists in group "${groupFieldId}" in variation "${v.id}"`,
+					);
+					process.exitCode = 1;
+					return;
+				}
+			}
+		}
+		targetVariation.primary[fieldId] = fieldDefinition;
+	}
 
 	// Write updated model
 	try {
@@ -149,9 +209,15 @@ export async function sliceAddFieldBoolean(): Promise<void> {
 		return;
 	}
 
-	console.info(
-		`Added field "${fieldId}" (Boolean) to "${targetVariation.id}" variation in ${sliceId}`,
-	);
+	if (fieldPath.type === "nested") {
+		console.info(
+			`Added field "${fieldPath.nestedFieldId}" (Boolean) to group "${fieldPath.groupId}" in ${sliceId}`,
+		);
+	} else {
+		console.info(
+			`Added field "${fieldId}" (Boolean) to "${targetVariation.id}" variation in ${sliceId}`,
+		);
+	}
 
 	try {
 		await buildTypes({ output: types });
@@ -162,5 +228,13 @@ export async function sliceAddFieldBoolean(): Promise<void> {
 
 	console.info();
 	console.info("Next: Add more fields with `prismic slice add-field`");
-	console.info("      Run `prismic status` when done to find next steps");
+
+	const frameworkInfo = await detectFrameworkInfo();
+	if (frameworkInfo?.framework) {
+		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`,
+		);
+	}
 }

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

@@ -4,6 +4,8 @@ import { writeFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
 
 import { buildTypes } from "./codegen-types";
+import { findGroupInVariation, isGroupField, parseFieldPath, validateNestedFieldPath } from "./lib/field-path";
+import { type Framework, detectFrameworkInfo } from "./lib/framework";
 import { stringify } from "./lib/json";
 import { findSliceModel } from "./lib/slice";
 import { humanReadable } from "./lib/string";
@@ -31,6 +33,28 @@ EXAMPLES
   prismic slice add-field color banner theme_color --variation "dark"
 `.trim();
 
+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";
+	}
+}
+
+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 async function sliceAddFieldColor(): Promise<void> {
 	const {
 		values: { help, variation, label, placeholder, types },
@@ -66,6 +90,15 @@ export async function sliceAddFieldColor(): Promise<void> {
 		return;
 	}
 
+	// Parse and validate field path
+	const fieldPath = parseFieldPath(fieldId);
+	const pathValidation = validateNestedFieldPath(fieldPath);
+	if (!pathValidation.ok) {
+		console.error(pathValidation.error);
+		process.exitCode = 1;
+		return;
+	}
+
 	// Find the slice model
 	const result = await findSliceModel(sliceId);
 	if (!result.ok) {
@@ -101,26 +134,53 @@ export async function sliceAddFieldColor(): Promise<void> {
 		targetVariation.primary = {};
 	}
 
-	// Check if field already exists in any variation
-	for (const v of model.variations) {
-		if (v.primary?.[fieldId]) {
-			console.error(`Field "${fieldId}" already exists in variation "${v.id}"`);
-			process.exitCode = 1;
-			return;
-		}
-	}
-
 	// Build field definition
 	const fieldDefinition: Color = {
 		type: "Color",
 		config: {
-			label: label ?? humanReadable(fieldId),
+			label: label ?? humanReadable(fieldPath.type === "nested" ? fieldPath.nestedFieldId : fieldId),
 			...(placeholder && { placeholder }),
 		},
 	};
 
-	// Add field to variation
-	targetVariation.primary[fieldId] = fieldDefinition;
+	// Add field to variation (with nested field support)
+	if (fieldPath.type === "nested") {
+		const groupResult = findGroupInVariation(targetVariation.primary, fieldPath.groupId, targetVariation.id);
+		if (!groupResult.ok) {
+			console.error(groupResult.error);
+			process.exitCode = 1;
+			return;
+		}
+		// Check if nested field already exists
+		if (groupResult.group.config.fields[fieldPath.nestedFieldId]) {
+			console.error(
+				`Field "${fieldPath.nestedFieldId}" already exists in group "${fieldPath.groupId}"`,
+			);
+			process.exitCode = 1;
+			return;
+		}
+		groupResult.group.config.fields[fieldPath.nestedFieldId] = fieldDefinition;
+	} else {
+		// Check if field already exists in any variation (at top level or in groups)
+		for (const v of model.variations) {
+			if (v.primary?.[fieldId]) {
+				console.error(`Field "${fieldId}" already exists in variation "${v.id}"`);
+				process.exitCode = 1;
+				return;
+			}
+			// Also check inside groups
+			for (const [groupFieldId, groupField] of Object.entries(v.primary ?? {})) {
+				if (isGroupField(groupField) && groupField.config.fields[fieldId]) {
+					console.error(
+						`Field "${fieldId}" already exists in group "${groupFieldId}" in variation "${v.id}"`,
+					);
+					process.exitCode = 1;
+					return;
+				}
+			}
+		}
+		targetVariation.primary[fieldId] = fieldDefinition;
+	}
 
 	// Write updated model
 	try {
@@ -135,9 +195,15 @@ export async function sliceAddFieldColor(): Promise<void> {
 		return;
 	}
 
-	console.info(
-		`Added field "${fieldId}" (Color) to "${targetVariation.id}" variation in ${sliceId}`,
-	);
+	if (fieldPath.type === "nested") {
+		console.info(
+			`Added field "${fieldPath.nestedFieldId}" (Color) to group "${fieldPath.groupId}" in ${sliceId}`,
+		);
+	} else {
+		console.info(
+			`Added field "${fieldId}" (Color) to "${targetVariation.id}" variation in ${sliceId}`,
+		);
+	}
 
 	try {
 		await buildTypes({ output: types });
@@ -148,5 +214,13 @@ export async function sliceAddFieldColor(): Promise<void> {
 
 	console.info();
 	console.info("Next: Add more fields with `prismic slice add-field`");
-	console.info("      Run `prismic status` when done to find next steps");
+
+	const frameworkInfo = await detectFrameworkInfo();
+	if (frameworkInfo?.framework) {
+		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`,
+		);
+	}
 }