@farming-labs/docs 0.1.1-beta.4 → 0.1.2

package/dist/cli/index.d.mts

@@ -0,0 +1,12 @@
+//#region src/cli/index.d.ts
+declare const UPGRADE_TAGS: readonly ["latest", "beta"];
+type UpgradeTag = (typeof UPGRADE_TAGS)[number];
+/** Normalize command aliases like `upgrade@beta` into the base command + dist-tag. */
+declare function parseCommandAlias(rawCommand?: string): {
+  command?: string;
+  tag?: UpgradeTag;
+};
+/** Parse flags like --template next, --name my-docs, --theme concrete, --entry docs, --framework astro (exported for tests). */
+declare function parseFlags(argv: string[]): Record<string, string | boolean | undefined>;
+//#endregion
+export { parseCommandAlias, parseFlags };

package/dist/cli/index.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import pc from "picocolors";
+
+//#region src/cli/index.ts
+const args = process.argv.slice(2);
+const command = args[0];
+const UPGRADE_TAGS = ["latest", "beta"];
+/** Normalize command aliases like `upgrade@beta` into the base command + dist-tag. */
+function parseCommandAlias(rawCommand) {
+	if (!rawCommand) return {};
+	const [baseCommand, rawTag] = rawCommand.split("@");
+	if (baseCommand === "upgrade" && rawTag && UPGRADE_TAGS.includes(rawTag)) return {
+		command: "upgrade",
+		tag: rawTag
+	};
+	return { command: rawCommand };
+}
+/** Parse flags like --template next, --name my-docs, --theme concrete, --entry docs, --framework astro (exported for tests). */
+function parseFlags(argv) {
+	const flags = {};
+	const booleanFlags = new Set(["api-reference"]);
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg.startsWith("--") && arg.includes("=")) {
+			const [key, value] = arg.slice(2).split("=");
+			if (key.startsWith("no-")) flags[key.slice(3)] = false;
+			else if (booleanFlags.has(key) && value === "true") flags[key] = true;
+			else if (booleanFlags.has(key) && value === "false") flags[key] = false;
+			else flags[key] = value;
+		} else if (arg.startsWith("--") && argv[i + 1] && !argv[i + 1].startsWith("--")) {
+			flags[arg.slice(2)] = argv[i + 1];
+			i++;
+		} else if (arg.startsWith("--no-")) flags[arg.slice(5)] = false;
+		else if (arg.startsWith("--") && booleanFlags.has(arg.slice(2))) flags[arg.slice(2)] = true;
+	}
+	return flags;
+}
+async function main() {
+	const flags = parseFlags(args);
+	const parsedCommand = parseCommandAlias(command);
+	const initOptions = {
+		template: typeof flags.template === "string" ? flags.template : void 0,
+		name: typeof flags.name === "string" ? flags.name : void 0,
+		theme: typeof flags.theme === "string" ? flags.theme : void 0,
+		entry: typeof flags.entry === "string" ? flags.entry : void 0,
+		apiReference: typeof flags["api-reference"] === "boolean" ? flags["api-reference"] : void 0,
+		apiRouteRoot: typeof flags["api-route-root"] === "string" ? flags["api-route-root"] : void 0
+	};
+	const mcpOptions = { configPath: typeof flags.config === "string" ? flags.config : void 0 };
+	if (!parsedCommand.command || parsedCommand.command === "init") {
+		const { init } = await import("../init-N0bZQFRd.mjs");
+		await init(initOptions);
+	} else if (parsedCommand.command === "mcp") {
+		const { runMcp } = await import("../mcp-8rCBy2-U.mjs");
+		await runMcp(mcpOptions);
+	} else if (parsedCommand.command === "upgrade") {
+		const { upgrade } = await import("../upgrade-BbEyR_JB.mjs");
+		await upgrade({
+			framework: (typeof flags.framework === "string" ? flags.framework : void 0) ?? (args[1] && !args[1].startsWith("--") ? args[1] : void 0),
+			tag: args.includes("--beta") ? "beta" : args.includes("--latest") ? "latest" : parsedCommand.tag ?? "latest"
+		});
+	} else if (parsedCommand.command === "--help" || parsedCommand.command === "-h") printHelp();
+	else if (parsedCommand.command === "--version" || parsedCommand.command === "-v") printVersion();
+	else {
+		console.error(pc.red(`Unknown command: ${command}`));
+		console.error();
+		printHelp();
+		process.exit(1);
+	}
+}
+function printHelp() {
+	console.log(`
+${pc.bold("@farming-labs/docs")} — Documentation framework CLI
+
+${pc.dim("Usage:")}
+  npx @farming-labs/docs@latest ${pc.cyan("<command>")}
+
+${pc.dim("Commands:")}
+  ${pc.cyan("init")}     Scaffold docs in your project (default)
+  ${pc.cyan("mcp")}      Run the built-in docs MCP server over stdio
+  ${pc.cyan("upgrade")}  Upgrade @farming-labs/* packages to latest (auto-detect or use --framework)
+
+${pc.dim("Supported frameworks:")}
+  Next.js, TanStack Start, SvelteKit, Astro, Nuxt
+
+${pc.dim("Options for init:")}
+  ${pc.cyan("--template <name>")}  Bootstrap a project (${pc.dim("next")}, ${pc.dim("nuxt")}, ${pc.dim("sveltekit")}, ${pc.dim("astro")}, ${pc.dim("tanstack-start")}); use with ${pc.cyan("--name")}
+  ${pc.cyan("--name <project>")}  Project folder name when using ${pc.cyan("--template")}; prompt if omitted (e.g. ${pc.dim("my-docs")})
+  ${pc.cyan("--theme <name>")}     Skip theme prompt (e.g. ${pc.dim("darksharp")}, ${pc.dim("concrete")})
+  ${pc.cyan("--entry <path>")}     Skip entry path prompt (e.g. ${pc.dim("docs")})
+  ${pc.cyan("--api-reference")}    Scaffold API reference support during ${pc.cyan("init")}
+  ${pc.cyan("--no-api-reference")} Skip API reference scaffold during ${pc.cyan("init")}
+  ${pc.cyan("--api-route-root <path>")}  Override the API route root scanned by ${pc.cyan("apiReference.routeRoot")} (e.g. ${pc.dim("api")}, ${pc.dim("internal-api")})
+
+${pc.dim("Options for mcp:")}
+  ${pc.cyan("--config <path>")}     Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
+
+${pc.dim("Options for upgrade:")}
+  ${pc.cyan("--framework <name>")}  Explicit framework (${pc.dim("next")}, ${pc.dim("tanstack-start")}, ${pc.dim("nuxt")}, ${pc.dim("sveltekit")}, ${pc.dim("astro")}); omit to auto-detect
+  ${pc.cyan("--latest")}            Install latest stable (default)
+  ${pc.cyan("--beta")}             Install beta versions
+  ${pc.cyan("upgrade@beta")}       Shortcut for ${pc.cyan("upgrade --beta")}
+  ${pc.cyan("upgrade@latest")}     Shortcut for ${pc.cyan("upgrade --latest")}
+
+  ${pc.cyan("-h, --help")}         Show this help message
+  ${pc.cyan("-v, --version")}     Show version
+`);
+}
+function printVersion() {
+	console.log("0.1.0");
+}
+main().catch((err) => {
+	console.error(pc.red("An unexpected error occurred:"));
+	console.error(err);
+	process.exit(1);
+});
+
+//#endregion
+export { parseCommandAlias, parseFlags };

package/dist/index.d.mts

@@ -0,0 +1,100 @@
+import { A as SidebarConfig, C as OpenGraphImage, D as PageOpenGraph, E as PageFrontmatter, F as ThemeToggleConfig, I as TypographyConfig, L as UIConfig, M as SidebarNode, N as SidebarPageNode, O as PageTwitter, P as SidebarTree, S as OpenDocsProvider, T as PageActionsConfig, _ as GithubConfig, a as CopyMarkdownConfig, b as OGConfig, c as DocsFeedbackValue, d as DocsMcpToolsConfig, f as DocsMetadata, g as FontStyle, h as FeedbackConfig, i as CodeBlockCopyData, j as SidebarFolderNode, k as SidebarComponentProps, l as DocsI18nConfig, m as DocsTheme, n as ApiReferenceConfig, o as DocsConfig, p as DocsNav, r as BreadcrumbConfig, s as DocsFeedbackData, t as AIConfig, u as DocsMcpConfig, v as LastUpdatedConfig, w as OrderingItem, x as OpenDocsConfig, y as LlmsTxtConfig } from "./types-dqnMXLdw.mjs";
+
+//#region src/define-docs.d.ts
+/**
+ * Define docs configuration. Validates and returns the config.
+ */
+declare function defineDocs(config: DocsConfig): DocsConfig;
+//#endregion
+//#region src/utils.d.ts
+/**
+ * Deep merge utility for theme overrides.
+ * Merges objects recursively; later values override earlier ones.
+ */
+declare function deepMerge<T extends Record<string, unknown>>(target: T, ...sources: Partial<T>[]): T;
+//#endregion
+//#region src/create-theme.d.ts
+/**
+ * Create a theme preset factory.
+ *
+ * Returns a function that accepts optional overrides and deep-merges them
+ * with the base theme defaults. This is the same pattern used by the
+ * built-in `fumadocs()`, `darksharp()`, and `pixelBorder()` presets.
+ *
+ * @param baseTheme - The default theme configuration
+ * @returns A factory function `(overrides?) => DocsTheme`
+ *
+ * @example
+ * ```ts
+ * import { createTheme } from "@farming-labs/docs";
+ *
+ * export const myTheme = createTheme({
+ *   name: "my-theme",
+ *   ui: {
+ *     colors: { primary: "#6366f1" },
+ *     layout: { contentWidth: 800 },
+ *   },
+ * });
+ * ```
+ */
+declare function createTheme(baseTheme: DocsTheme): (overrides?: Partial<DocsTheme>) => DocsTheme;
+/**
+ * Extend an existing theme preset with additional defaults.
+ *
+ * Useful when you want to build on top of an existing theme (e.g. fumadocs)
+ * rather than starting from scratch.
+ *
+ * @example
+ * ```ts
+ * import { extendTheme } from "@farming-labs/docs";
+ * import { fumadocs } from "@farming-labs/theme/default";
+ *
+ * // Start with fumadocs defaults, override some values
+ * export const myTheme = extendTheme(fumadocs(), {
+ *   name: "my-custom-fumadocs",
+ *   ui: { colors: { primary: "#22c55e" } },
+ * });
+ * ```
+ */
+declare function extendTheme(baseTheme: DocsTheme, extensions: Partial<DocsTheme>): DocsTheme;
+//#endregion
+//#region src/i18n.d.ts
+interface ResolvedDocsI18n {
+  locales: string[];
+  defaultLocale: string;
+}
+interface DocsPathMatch {
+  /** Slug path relative to the docs root (no leading slash). */
+  slug: string;
+  /** Entry path used for URLs (no locale segment). */
+  entryPath: string;
+}
+declare function resolveDocsI18n(config?: DocsI18nConfig | null): ResolvedDocsI18n | null;
+declare function resolveDocsLocale(searchParams: URLSearchParams, i18n?: ResolvedDocsI18n | null): string | undefined;
+declare function resolveDocsPath(pathname: string, entry: string): DocsPathMatch;
+//#endregion
+//#region src/metadata.d.ts
+/**
+ * Resolve page title using metadata titleTemplate.
+ * %s is replaced with page title.
+ */
+declare function resolveTitle(pageTitle: string, metadata?: DocsMetadata): string;
+/**
+ * Resolve OG image URL for a page.
+ * Prefers page.openGraph.images[0], then page.ogImage, then config endpoint/default.
+ */
+declare function resolveOGImage(page: PageFrontmatter, ogConfig?: OGConfig, baseUrl?: string): string | undefined;
+/**
+ * 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).
+ */
+declare function buildPageOpenGraph(page: Pick<PageFrontmatter, "title" | "description" | "ogImage" | "openGraph">, ogConfig?: OGConfig, baseUrl?: string): PageOpenGraph | undefined;
+/**
+ * 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).
+ */
+declare function buildPageTwitter(page: Pick<PageFrontmatter, "title" | "description" | "ogImage" | "openGraph" | "twitter">, ogConfig?: OGConfig, baseUrl?: string): PageTwitter | undefined;
+//#endregion
+export { type AIConfig, type ApiReferenceConfig, type BreadcrumbConfig, type CodeBlockCopyData, type CopyMarkdownConfig, type DocsConfig, type DocsFeedbackData, type DocsFeedbackValue, type DocsI18nConfig, type DocsMcpConfig, type DocsMcpToolsConfig, type DocsMetadata, type DocsNav, type DocsPathMatch, type DocsTheme, type FeedbackConfig, type FontStyle, type GithubConfig, type LastUpdatedConfig, type LlmsTxtConfig, type OGConfig, type OpenDocsConfig, type OpenDocsProvider, type OpenGraphImage, type OrderingItem, type PageActionsConfig, type PageFrontmatter, type PageOpenGraph, type PageTwitter, type ResolvedDocsI18n, type SidebarComponentProps, type SidebarConfig, type SidebarFolderNode, type SidebarNode, type SidebarPageNode, type SidebarTree, type ThemeToggleConfig, type TypographyConfig, type UIConfig, buildPageOpenGraph, buildPageTwitter, createTheme, deepMerge, defineDocs, extendTheme, resolveDocsI18n, resolveDocsLocale, resolveDocsPath, resolveOGImage, resolveTitle };

package/dist/index.mjs

@@ -0,0 +1,227 @@
+//#region src/define-docs.ts
+/**
+* Define docs configuration. Validates and returns the config.
+*/
+function defineDocs(config) {
+	return {
+		entry: config.entry ?? "docs",
+		contentDir: config.contentDir,
+		i18n: config.i18n,
+		theme: config.theme,
+		nav: config.nav,
+		github: config.github,
+		themeToggle: config.themeToggle,
+		breadcrumb: config.breadcrumb,
+		sidebar: config.sidebar,
+		components: config.components,
+		onCopyClick: config.onCopyClick,
+		feedback: config.feedback,
+		mcp: config.mcp,
+		icons: config.icons,
+		pageActions: config.pageActions,
+		lastUpdated: config.lastUpdated,
+		llmsTxt: config.llmsTxt,
+		ai: config.ai,
+		ordering: config.ordering,
+		metadata: config.metadata,
+		og: config.og,
+		apiReference: config.apiReference
+	};
+}
+
+//#endregion
+//#region src/utils.ts
+/**
+* Deep merge utility for theme overrides.
+* Merges objects recursively; later values override earlier ones.
+*/
+function deepMerge(target, ...sources) {
+	if (!sources.length) return target;
+	const source = sources.shift();
+	if (!source) return target;
+	const result = { ...target };
+	for (const key of Object.keys(source)) {
+		const sourceVal = source[key];
+		const targetVal = result[key];
+		if (sourceVal && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal && typeof targetVal === "object" && !Array.isArray(targetVal)) result[key] = deepMerge(targetVal, sourceVal);
+		else if (sourceVal !== void 0) result[key] = sourceVal;
+	}
+	if (sources.length) return deepMerge(result, ...sources);
+	return result;
+}
+
+//#endregion
+//#region src/create-theme.ts
+/**
+* Create a theme preset factory.
+*
+* Returns a function that accepts optional overrides and deep-merges them
+* with the base theme defaults. This is the same pattern used by the
+* built-in `fumadocs()`, `darksharp()`, and `pixelBorder()` presets.
+*
+* @param baseTheme - The default theme configuration
+* @returns A factory function `(overrides?) => DocsTheme`
+*
+* @example
+* ```ts
+* import { createTheme } from "@farming-labs/docs";
+*
+* export const myTheme = createTheme({
+*   name: "my-theme",
+*   ui: {
+*     colors: { primary: "#6366f1" },
+*     layout: { contentWidth: 800 },
+*   },
+* });
+* ```
+*/
+function createTheme(baseTheme) {
+	return function themeFactory(overrides = {}) {
+		const merged = deepMerge(baseTheme, overrides);
+		if (overrides.ui?.colors) merged._userColorOverrides = { ...overrides.ui.colors };
+		return merged;
+	};
+}
+/**
+* Extend an existing theme preset with additional defaults.
+*
+* Useful when you want to build on top of an existing theme (e.g. fumadocs)
+* rather than starting from scratch.
+*
+* @example
+* ```ts
+* import { extendTheme } from "@farming-labs/docs";
+* import { fumadocs } from "@farming-labs/theme/default";
+*
+* // Start with fumadocs defaults, override some values
+* export const myTheme = extendTheme(fumadocs(), {
+*   name: "my-custom-fumadocs",
+*   ui: { colors: { primary: "#22c55e" } },
+* });
+* ```
+*/
+function extendTheme(baseTheme, extensions) {
+	return deepMerge(baseTheme, extensions);
+}
+
+//#endregion
+//#region src/i18n.ts
+function normalizeSegment(value) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+function splitSegments(value) {
+	const cleaned = normalizeSegment(value);
+	return cleaned ? cleaned.split("/").filter(Boolean) : [];
+}
+function resolveDocsI18n(config) {
+	if (!config || !Array.isArray(config.locales)) return null;
+	const locales = Array.from(new Set(config.locales.map((l) => l.trim()).filter(Boolean)));
+	if (locales.length === 0) return null;
+	return {
+		locales,
+		defaultLocale: config.defaultLocale && locales.includes(config.defaultLocale) ? config.defaultLocale : locales[0]
+	};
+}
+function resolveDocsLocale(searchParams, i18n) {
+	if (!i18n) return void 0;
+	const raw = searchParams.get("lang") ?? searchParams.get("locale");
+	if (!raw) return void 0;
+	if (i18n.locales.includes(raw)) return raw;
+	return i18n.defaultLocale;
+}
+function resolveDocsPath(pathname, entry) {
+	const entryBase = normalizeSegment(entry || "docs") || "docs";
+	const entryParts = splitSegments(entryBase);
+	const pathParts = splitSegments(pathname);
+	let rest = pathParts;
+	if (entryParts.length > 0) {
+		if (pathParts.slice(0, entryParts.length).join("/") === entryParts.join("/")) rest = pathParts.slice(entryParts.length);
+	}
+	return {
+		slug: rest.join("/"),
+		entryPath: entryBase
+	};
+}
+
+//#endregion
+//#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]
+	};
+}
+
+//#endregion
+export { buildPageOpenGraph, buildPageTwitter, createTheme, deepMerge, defineDocs, extendTheme, resolveDocsI18n, resolveDocsLocale, resolveDocsPath, resolveOGImage, resolveTitle };