@farming-labs/docs 0.2.62 → 0.2.64

package/dist/metadata-DWExHQnx.mjs

@@ -0,0 +1,237 @@
+import { Jt as normalizePageAgentFrontmatter, qt as hasStructuredPageAgentContract } from "./agent-DKKptIgy.mjs";
+
+//#region src/metadata.ts
+/**
+* Resolve page title using metadata titleTemplate.
+* %s is replaced with page title.
+*/
+function resolveTitle(pageTitle, metadata) {
+	return (metadata?.titleTemplate ?? "%s").replace("%s", pageTitle);
+}
+/**
+* Resolve OG image URL for a page.
+* Prefers page.openGraph.images[0], then page.ogImage, then config endpoint/default.
+*/
+function resolveOGImage(page, ogConfig, baseUrl) {
+	if (page.openGraph?.images?.length) return resolveImageUrl(page.openGraph.images[0].url, baseUrl);
+	if (!ogConfig?.enabled) return void 0;
+	if (page.ogImage) return resolveImageUrl(page.ogImage, baseUrl);
+	if (ogConfig.type === "dynamic" && ogConfig.endpoint) return `${baseUrl ?? ""}${ogConfig.endpoint}`;
+	return ogConfig.defaultImage;
+}
+function resolveImageUrl(url, baseUrl) {
+	if (url.startsWith("/") || url.startsWith("http")) return url;
+	const base = baseUrl ?? "";
+	return `${base}${base.length > 0 && !base.endsWith("/") ? "/" : ""}${url}`;
+}
+/**
+* Build the Open Graph metadata object for a page.
+* When the page has openGraph in frontmatter, uses it (with title/description filled from page if omitted).
+* Otherwise uses ogImage or config (dynamic endpoint / defaultImage).
+*/
+function buildPageOpenGraph(page, ogConfig, baseUrl) {
+	if (page.openGraph) {
+		const images = page.openGraph.images?.length ? page.openGraph.images.map((img) => ({
+			url: resolveImageUrl(img.url, baseUrl),
+			width: img.width ?? 1200,
+			height: img.height ?? 630
+		})) : void 0;
+		return {
+			title: page.openGraph.title ?? page.title,
+			description: page.openGraph.description ?? page.description,
+			...images && { images }
+		};
+	}
+	const url = resolveOGImage(page, ogConfig, baseUrl);
+	if (!url) return void 0;
+	return {
+		title: page.title,
+		...page.description && { description: page.description },
+		images: [{
+			url,
+			width: 1200,
+			height: 630
+		}]
+	};
+}
+/**
+* Build the Twitter card metadata object for a page.
+* When the page has twitter in frontmatter, uses it.
+* Otherwise builds from ogImage or config (dynamic endpoint).
+*/
+function buildPageTwitter(page, ogConfig, baseUrl) {
+	if (page.twitter) {
+		const images = page.twitter.images?.length ? page.twitter.images.map((url) => resolveImageUrl(url, baseUrl)) : void 0;
+		return {
+			...page.twitter.card && { card: page.twitter.card },
+			...page.twitter.title !== void 0 && { title: page.twitter.title },
+			...page.twitter.description !== void 0 && { description: page.twitter.description },
+			...images && { images }
+		};
+	}
+	const url = resolveOGImage(page, ogConfig, baseUrl);
+	if (!url) return void 0;
+	return {
+		card: "summary_large_image",
+		title: page.title,
+		...page.description && { description: page.description },
+		images: [url]
+	};
+}
+function normalizeBaseUrl(value) {
+	if (!value) return void 0;
+	try {
+		const url = new URL(value);
+		if (url.protocol !== "http:" && url.protocol !== "https:") return void 0;
+		return url.toString().replace(/\/+$/, "");
+	} catch {
+		return;
+	}
+}
+function absolutizeUrl(url, baseUrl) {
+	const base = normalizeBaseUrl(baseUrl);
+	if (!base) return url;
+	try {
+		return new URL(url, `${base}/`).toString();
+	} catch {
+		return url;
+	}
+}
+function titleFromSegment(segment) {
+	return segment.replace(/\.[a-z0-9]+$/i, "").replace(/[-_]+/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function normalizeRoutePath(url) {
+	try {
+		return new URL(url, "https://farming-labs.local").pathname.replace(/\/+$/, "") || "/";
+	} catch {
+		return `/${url.replace(/^\/+/, "")}`.replace(/\/+$/, "") || "/";
+	}
+}
+function buildDefaultBreadcrumbs(input) {
+	const routePath = normalizeRoutePath(input.url);
+	const entry = (input.entry ?? "docs").replace(/^\/+|\/+$/g, "") || "docs";
+	const segments = routePath.split("/").filter(Boolean);
+	const entryParts = entry.split("/").filter(Boolean);
+	const contentSegments = segments.slice(0, entryParts.length).join("/") === entryParts.join("/") ? segments.slice(entryParts.length) : segments;
+	const breadcrumbs = [{
+		name: titleFromSegment(entryParts[entryParts.length - 1] ?? "Docs"),
+		url: `/${entry}`
+	}];
+	let current = `/${entry}`;
+	contentSegments.forEach((segment, index) => {
+		current = `${current}/${segment}`.replace(/\/+/g, "/");
+		breadcrumbs.push({
+			name: index === contentSegments.length - 1 ? input.title : titleFromSegment(segment),
+			url: current
+		});
+	});
+	return breadcrumbs;
+}
+function normalizeDateModified(value) {
+	if (!value) return void 0;
+	const date = new Date(value);
+	return Number.isNaN(date.getTime()) ? value : date.toISOString();
+}
+function buildAgentContractHowTo(value, fallback) {
+	const agent = normalizePageAgentFrontmatter(value);
+	if (!agent || !hasStructuredPageAgentContract(agent)) return void 0;
+	const steps = [];
+	for (const command of agent.commands ?? []) {
+		const run = typeof command === "string" ? command : command.run;
+		const description = typeof command === "string" ? void 0 : command.description;
+		const cwd = typeof command === "string" ? void 0 : command.cwd;
+		steps.push({
+			"@type": "HowToStep",
+			position: steps.length + 1,
+			name: description ?? "Run command",
+			text: cwd ? `${run} (from ${cwd})` : run
+		});
+	}
+	for (const verification of agent.verification ?? []) {
+		const description = typeof verification === "string" ? verification : verification.description ?? "Verify the result";
+		const details = typeof verification === "string" ? verification : [verification.run, verification.expect ? `Expected: ${verification.expect}` : void 0].filter(Boolean).join(". ");
+		steps.push({
+			"@type": "HowToStep",
+			position: steps.length + 1,
+			name: description,
+			text: details || description
+		});
+	}
+	const supplies = [...(agent.prerequisites ?? []).map((name) => ({
+		"@type": "HowToSupply",
+		name
+	})), ...(agent.files ?? []).map((name) => ({
+		"@type": "HowToSupply",
+		name
+	}))];
+	const about = Object.entries(agent.appliesTo ?? {}).flatMap(([kind, values]) => (typeof values === "string" ? [values] : values ?? []).map((name) => ({
+		"@type": "Thing",
+		name: `${kind}: ${name}`
+	})));
+	return {
+		"@type": "HowTo",
+		name: agent.task ?? fallback.title,
+		...agent.outcome ?? fallback.description ? { description: agent.outcome ?? fallback.description } : {},
+		...about.length > 0 ? { about } : {},
+		...supplies.length > 0 ? { supply: supplies } : {},
+		...steps.length > 0 ? { step: steps } : {}
+	};
+}
+/**
+* Resolve the public docs site URL from existing agent-facing config.
+*
+* The framework intentionally reuses `sitemap.baseUrl`, `llmsTxt.baseUrl`,
+* `robots.baseUrl`, or `ai.docsUrl` instead of requiring another setting.
+*/
+function resolveDocsMetadataBaseUrl(config) {
+	return [
+		typeof config.sitemap === "object" ? config.sitemap.baseUrl : void 0,
+		typeof config.llmsTxt === "object" ? config.llmsTxt.baseUrl : void 0,
+		typeof config.robots === "object" ? config.robots.baseUrl : void 0,
+		config.ai?.docsUrl
+	].map((value) => normalizeBaseUrl(value)).find((value) => Boolean(value));
+}
+/**
+* Build Schema.org JSON-LD for a docs page.
+*
+* The shape follows Vercel's agent readability guidance: a `TechArticle`
+* with title, description, canonical URL, freshness, and breadcrumbs.
+*/
+function buildDocsPageStructuredData(input) {
+	const breadcrumbs = input.breadcrumbs?.length ? input.breadcrumbs : buildDefaultBreadcrumbs(input);
+	const result = {
+		"@context": "https://schema.org",
+		"@type": "TechArticle",
+		headline: input.title,
+		name: input.title,
+		url: absolutizeUrl(input.url, input.baseUrl),
+		mainEntityOfPage: {
+			"@type": "WebPage",
+			"@id": absolutizeUrl(input.url, input.baseUrl)
+		},
+		breadcrumb: {
+			"@type": "BreadcrumbList",
+			itemListElement: breadcrumbs.map((item, index) => ({
+				"@type": "ListItem",
+				position: index + 1,
+				name: item.name,
+				item: absolutizeUrl(item.url, input.baseUrl)
+			}))
+		}
+	};
+	if (input.description) result.description = input.description;
+	const agentContract = buildAgentContractHowTo(input.agent, input);
+	if (agentContract) result.mainEntity = agentContract;
+	const dateModified = normalizeDateModified(input.dateModified);
+	if (dateModified) result.dateModified = dateModified;
+	return result;
+}
+/**
+* Serialize Schema.org JSON-LD for safe insertion into a `<script>` tag.
+*/
+function renderDocsPageStructuredDataJson(input) {
+	return JSON.stringify(buildDocsPageStructuredData(input)).replace(/</g, "\\u003c");
+}
+
+//#endregion
+export { resolveDocsMetadataBaseUrl as a, renderDocsPageStructuredDataJson as i, buildPageOpenGraph as n, resolveOGImage as o, buildPageTwitter as r, resolveTitle as s, buildDocsPageStructuredData as t };

package/dist/package-version-n5AFur8a.mjs

@@ -0,0 +1,128 @@
+import { i as detectPackageManagerFromProject, l as formatPackageManagerDetection, t as detectFramework, u as installCommand } from "./utils-DpiIioYb.mjs";
+import pc from "picocolors";
+import * as p from "@clack/prompts";
+
+//#region src/cli/package-version.ts
+const PRESETS = [
+	"next",
+	"tanstack-start",
+	"nuxt",
+	"sveltekit",
+	"astro"
+];
+const PACKAGES_BY_FRAMEWORK = {
+	nextjs: [
+		"@farming-labs/docs",
+		"@farming-labs/theme",
+		"@farming-labs/next"
+	],
+	"tanstack-start": [
+		"@farming-labs/docs",
+		"@farming-labs/theme",
+		"@farming-labs/tanstack-start"
+	],
+	nuxt: [
+		"@farming-labs/docs",
+		"@farming-labs/nuxt",
+		"@farming-labs/nuxt-theme",
+		"@farming-labs/theme"
+	],
+	sveltekit: [
+		"@farming-labs/docs",
+		"@farming-labs/svelte",
+		"@farming-labs/svelte-theme",
+		"@farming-labs/theme"
+	],
+	astro: [
+		"@farming-labs/docs",
+		"@farming-labs/astro",
+		"@farming-labs/astro-theme",
+		"@farming-labs/theme"
+	]
+};
+function presetFromFramework(fw) {
+	return fw === "nextjs" ? "next" : fw;
+}
+function frameworkFromPreset(preset) {
+	return preset === "next" ? "nextjs" : preset;
+}
+function getPackagesForFramework(framework) {
+	return PACKAGES_BY_FRAMEWORK[framework];
+}
+const exactSemverPattern = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function validateUpgradeVersion(version) {
+	const normalized = version.trim();
+	if (!exactSemverPattern.test(normalized)) throw new Error(`Invalid version "${version}". Use an exact semver version like 0.1.104.`);
+	return normalized;
+}
+function buildDocsPackageInstallCommand(framework, target, pm) {
+	const packagesWithTarget = getPackagesForFramework(framework).map((name) => `${name}@${target}`);
+	return `${installCommand(pm)} ${packagesWithTarget.join(" ")}`;
+}
+function resolveDocsPackageFramework(cwd, rawFramework) {
+	if (rawFramework) {
+		const raw = rawFramework.toLowerCase().trim();
+		const normalized = raw === "nextjs" ? "next" : raw;
+		if (!PRESETS.includes(normalized)) {
+			p.log.error(`Invalid framework ${pc.cyan(rawFramework)}. Use one of: ${PRESETS.map((t) => pc.cyan(t)).join(", ")}`);
+			process.exit(1);
+		}
+		const preset = normalized;
+		return {
+			framework: frameworkFromPreset(preset),
+			preset
+		};
+	}
+	const detected = detectFramework(cwd);
+	if (!detected) {
+		p.log.error("Could not detect a supported framework (Next.js, TanStack Start, Nuxt, SvelteKit, Astro). Use " + pc.cyan("--framework <next|tanstack-start|nuxt|sveltekit|astro>") + " to specify.");
+		process.exit(1);
+	}
+	return {
+		framework: detected,
+		preset: presetFromFramework(detected)
+	};
+}
+async function resolveDocsPackageManager(cwd, command) {
+	const detected = detectPackageManagerFromProject(cwd);
+	if (detected) {
+		p.log.info(`Detected ${pc.cyan(detected.packageManager)} from ${formatPackageManagerDetection(cwd, detected)}`);
+		return detected.packageManager;
+	}
+	const pmAnswer = await p.select({
+		message: `Which package manager do you want to use for this ${command}?`,
+		options: [
+			{
+				value: "pnpm",
+				label: "pnpm",
+				hint: "Use pnpm add"
+			},
+			{
+				value: "npm",
+				label: "npm",
+				hint: "Use npm add"
+			},
+			{
+				value: "yarn",
+				label: "yarn",
+				hint: "Use yarn add"
+			},
+			{
+				value: "bun",
+				label: "bun",
+				hint: "Use bun add"
+			}
+		]
+	});
+	if (p.isCancel(pmAnswer)) {
+		const label = command === "upgrade" ? "Upgrade" : "Downgrade";
+		p.outro(pc.red(`${label} cancelled.`));
+		process.exit(0);
+	}
+	const pm = pmAnswer;
+	p.log.info(`Using ${pc.cyan(pm)} as package manager`);
+	return pm;
+}
+
+//#endregion
+export { getPackagesForFramework as a, resolveDocsPackageManager as c, frameworkFromPreset as i, validateUpgradeVersion as l, PRESETS as n, presetFromFramework as o, buildDocsPackageInstallCommand as r, resolveDocsPackageFramework as s, PACKAGES_BY_FRAMEWORK as t };