@farming-labs/docs 0.1.1-beta.2 → 0.1.1

package/dist/cli/index.d.mts

@@ -1,5 +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 { parseFlags };
+export { parseCommandAlias, parseFlags };

package/dist/cli/index.mjs

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
+import "../api-reference-wh4_pwG8.mjs";
+import { createFilesystemDocsMcpSource, resolveDocsMcpConfig, runDocsMcpStdio } from "../mcp.mjs";
+import "../server.mjs";
+import fs, { existsSync, readFileSync } from "node:fs";
+import path, { join, resolve } from "node:path";
 import pc from "picocolors";
 import * as p from "@clack/prompts";
 import { execSync, spawn } from "node:child_process";
@@ -3414,6 +3417,92 @@ function scaffoldNuxt(cwd, cfg, globalCssRelPath, write, skipped, written) {
 	}
 }
 
+//#endregion
+//#region src/cli/mcp.ts
+const FILE_EXTS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js"
+];
+async function runMcp(options = {}) {
+	const rootDir = process.cwd();
+	const content = readFileSync(resolveDocsConfigPath(rootDir, options.configPath), "utf-8");
+	const entry = readStringProperty(content, "entry") ?? "docs";
+	const contentDir = readStringProperty(content, "contentDir") ?? entry;
+	const navTitle = readNavTitle(content);
+	const mcp = readMcpConfig(content);
+	await runDocsMcpStdio({
+		source: createFilesystemDocsMcpSource({
+			rootDir,
+			entry,
+			contentDir,
+			siteTitle: navTitle ?? "Documentation"
+		}),
+		mcp: resolveDocsMcpConfig(mcp ?? true, { defaultName: navTitle ?? "@farming-labs/docs" }),
+		defaultName: navTitle ?? "@farming-labs/docs"
+	});
+}
+function resolveDocsConfigPath(rootDir, explicitPath) {
+	if (explicitPath) {
+		const resolvedPath = resolve(rootDir, explicitPath);
+		if (!existsSync(resolvedPath)) throw new Error(`Could not find docs config at ${explicitPath}.`);
+		return resolvedPath;
+	}
+	for (const ext of FILE_EXTS) {
+		const configPath = join(rootDir, `docs.config.${ext}`);
+		if (existsSync(configPath)) return configPath;
+	}
+	throw new Error("Could not find docs.config.ts or docs.config.tsx in the current project. Use --config to point at a custom path.");
+}
+function readStringProperty(content, key) {
+	return content.match(new RegExp(`${key}\\s*:\\s*["']([^"']+)["']`))?.[1];
+}
+function readNavTitle(content) {
+	const block = extractObjectLiteral(content, "nav");
+	if (!block) return void 0;
+	return readStringProperty(block, "title");
+}
+function readMcpConfig(content) {
+	if (content.match(/mcp\s*:\s*false/)) return false;
+	if (content.match(/mcp\s*:\s*true/)) return true;
+	const block = extractObjectLiteral(content, "mcp");
+	if (!block) return void 0;
+	return {
+		enabled: readBooleanProperty(block, "enabled"),
+		route: readStringProperty(block, "route"),
+		name: readStringProperty(block, "name"),
+		version: readStringProperty(block, "version"),
+		tools: {
+			listPages: readBooleanProperty(block, "listPages"),
+			readPage: readBooleanProperty(block, "readPage"),
+			searchDocs: readBooleanProperty(block, "searchDocs"),
+			getNavigation: readBooleanProperty(block, "getNavigation")
+		}
+	};
+}
+function readBooleanProperty(content, key) {
+	const match = content.match(new RegExp(`${key}\\s*:\\s*(true|false)`));
+	return match ? match[1] === "true" : void 0;
+}
+function extractObjectLiteral(content, key) {
+	const keyIndex = content.search(new RegExp(`${key}\\s*:\\s*\\{`));
+	if (keyIndex === -1) return void 0;
+	const braceStart = content.indexOf("{", keyIndex);
+	if (braceStart === -1) return void 0;
+	let depth = 0;
+	for (let index = braceStart; index < content.length; index += 1) {
+		const char = content[index];
+		if (char === "{") {
+			depth += 1;
+			continue;
+		}
+		if (char !== "}") continue;
+		depth -= 1;
+		if (depth === 0) return content.slice(braceStart + 1, index);
+	}
+}
+
 //#endregion
 //#region src/cli/upgrade.ts
 /**
@@ -3550,6 +3639,17 @@ async function upgrade(options = {}) {
 //#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 = {};
@@ -3572,6 +3672,7 @@ function parseFlags(argv) {
 }
 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,
@@ -3580,13 +3681,15 @@ async function main() {
 		apiReference: typeof flags["api-reference"] === "boolean" ? flags["api-reference"] : void 0,
 		apiRouteRoot: typeof flags["api-route-root"] === "string" ? flags["api-route-root"] : void 0
 	};
-	if (!command || command === "init") await init(initOptions);
-	else if (command === "upgrade") await upgrade({
+	const mcpOptions = { configPath: typeof flags.config === "string" ? flags.config : void 0 };
+	if (!parsedCommand.command || parsedCommand.command === "init") await init(initOptions);
+	else if (parsedCommand.command === "mcp") await runMcp(mcpOptions);
+	else if (parsedCommand.command === "upgrade") 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" : "latest"
+		tag: args.includes("--beta") ? "beta" : args.includes("--latest") ? "latest" : parsedCommand.tag ?? "latest"
 	});
-	else if (command === "--help" || command === "-h") printHelp();
-	else if (command === "--version" || command === "-v") printVersion();
+	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();
@@ -3603,6 +3706,7 @@ ${pc.dim("Usage:")}
 
 ${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:")}
@@ -3617,10 +3721,15 @@ ${pc.dim("Options for 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
@@ -3636,4 +3745,4 @@ main().catch((err) => {
 });
 
 //#endregion
-export { parseFlags };
+export { parseCommandAlias, parseFlags };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as SidebarNode, C as PageActionsConfig, D as SidebarComponentProps, E as PageTwitter, F as UIConfig, M as SidebarTree, N as ThemeToggleConfig, O as SidebarConfig, P as TypographyConfig, S as OrderingItem, T as PageOpenGraph, _ as LlmsTxtConfig, a as CopyMarkdownConfig, b as OpenDocsProvider, c as DocsFeedbackValue, d as DocsNav, f as DocsTheme, g as LastUpdatedConfig, h as GithubConfig, i as CodeBlockCopyData, j as SidebarPageNode, k as SidebarFolderNode, l as DocsI18nConfig, m as FontStyle, n as ApiReferenceConfig, o as DocsConfig, p as FeedbackConfig, r as BreadcrumbConfig, s as DocsFeedbackData, t as AIConfig, u as DocsMetadata, v as OGConfig, w as PageFrontmatter, x as OpenGraphImage, y as OpenDocsConfig } from "./types-DpijZMth.mjs";
+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-Bd3kyFF1.mjs";
 
 //#region src/define-docs.d.ts
 /**
@@ -97,4 +97,4 @@ declare function buildPageOpenGraph(page: Pick<PageFrontmatter, "title" | "descr
  */
 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 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 };
+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

@@ -16,6 +16,7 @@ function defineDocs(config) {
 		components: config.components,
 		onCopyClick: config.onCopyClick,
 		feedback: config.feedback,
+		mcp: config.mcp,
 		icons: config.icons,
 		pageActions: config.pageActions,
 		lastUpdated: config.lastUpdated,

package/dist/mcp.d.mts

@@ -0,0 +1,86 @@
+import { u as DocsMcpConfig, w as OrderingItem } from "./types-Bd3kyFF1.mjs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
+
+//#region src/mcp.d.ts
+interface DocsMcpPage {
+  slug: string;
+  url: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  content: string;
+  rawContent?: string;
+}
+interface DocsMcpPageNode {
+  type: "page";
+  name: string;
+  url: string;
+  icon?: string;
+  description?: string;
+}
+interface DocsMcpFolderNode {
+  type: "folder";
+  name: string;
+  icon?: string;
+  index?: DocsMcpPageNode;
+  children: DocsMcpNavigationNode[];
+}
+type DocsMcpNavigationNode = DocsMcpPageNode | DocsMcpFolderNode;
+interface DocsMcpNavigationTree {
+  name: string;
+  children: DocsMcpNavigationNode[];
+}
+interface DocsMcpSource {
+  entry?: string;
+  siteTitle?: string;
+  getPages(locale?: string): DocsMcpPage[] | Promise<DocsMcpPage[]>;
+  getNavigation(locale?: string): DocsMcpNavigationTree | Promise<DocsMcpNavigationTree>;
+}
+interface DocsMcpResolvedConfig {
+  enabled: boolean;
+  route: string;
+  name: string;
+  version: string;
+  tools: {
+    listPages: boolean;
+    readPage: boolean;
+    searchDocs: boolean;
+    getNavigation: boolean;
+  };
+}
+interface DocsMcpHttpHandlers {
+  GET: (context: {
+    request: Request;
+  }) => Promise<Response>;
+  POST: (context: {
+    request: Request;
+  }) => Promise<Response>;
+  DELETE: (context: {
+    request: Request;
+  }) => Promise<Response>;
+}
+interface CreateDocsMcpServerOptions {
+  source: DocsMcpSource;
+  mcp?: boolean | DocsMcpConfig;
+  defaultName?: string;
+  defaultVersion?: string;
+}
+interface CreateFilesystemDocsMcpSourceOptions {
+  rootDir?: string;
+  entry?: string;
+  contentDir?: string;
+  siteTitle?: string;
+  ordering?: "alphabetical" | "numeric" | OrderingItem[];
+}
+declare function normalizeDocsMcpRoute(route?: string): string;
+declare function resolveDocsMcpConfig(mcp?: boolean | DocsMcpConfig, defaults?: {
+  defaultName?: string;
+  defaultVersion?: string;
+  defaultRoute?: string;
+}): DocsMcpResolvedConfig;
+declare function createFilesystemDocsMcpSource(options?: CreateFilesystemDocsMcpSourceOptions): DocsMcpSource;
+declare function createDocsMcpServer(options: CreateDocsMcpServerOptions): Promise<McpServer>;
+declare function createDocsMcpHttpHandler(options: CreateDocsMcpServerOptions): DocsMcpHttpHandlers;
+declare function runDocsMcpStdio(options: CreateDocsMcpServerOptions): Promise<void>;
+//#endregion
+export { DocsMcpFolderNode, DocsMcpHttpHandlers, DocsMcpNavigationNode, DocsMcpNavigationTree, DocsMcpPage, DocsMcpPageNode, DocsMcpResolvedConfig, DocsMcpSource, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio };