@farming-labs/docs 0.1.1 → 0.1.3

package/dist/search-ChhShKMO.mjs

@@ -0,0 +1,99 @@
+import { n as createAlgoliaSearchAdapter, o as createTypesenseSearchAdapter, t as buildDocsSearchDocuments } from "./search-BS6C5N1i.mjs";
+import "./api-reference-DlfH-Y9c.mjs";
+import { createFilesystemDocsMcpSource } from "./mcp.mjs";
+import "./server.mjs";
+import { a as readStringProperty, n as loadProjectEnv, o as resolveDocsConfigPath, s as resolveDocsContentDir } from "./config-CSywk3ou.mjs";
+import { readFileSync } from "node:fs";
+import pc from "picocolors";
+
+//#region src/cli/search.ts
+function getEnvValue(loadedEnv, key) {
+	return process.env[key] ?? loadedEnv[key];
+}
+function resolveSearchSyncProvider(options, loadedEnv) {
+	if (options.typesense && options.algolia) throw new Error("Use only one provider flag: --typesense or --algolia.");
+	if (options.typesense) return "typesense";
+	if (options.algolia) return "algolia";
+	if (options.provider === "typesense" || options.provider === "algolia") return options.provider;
+	if (options.provider) throw new Error(`Unsupported search provider: ${options.provider}.`);
+	if (options.baseUrl || getEnvValue(loadedEnv, "TYPESENSE_URL")) return "typesense";
+	if (options.appId || getEnvValue(loadedEnv, "ALGOLIA_APP_ID")) return "algolia";
+	throw new Error("Could not determine a search provider. Use --typesense, --algolia, or --provider <name>.");
+}
+function resolveTypesenseSyncConfig(options, loadedEnv) {
+	const baseUrl = options.baseUrl ?? getEnvValue(loadedEnv, "TYPESENSE_URL") ?? getEnvValue(loadedEnv, "TYPESENSE_BASE_URL");
+	const collection = options.collection ?? getEnvValue(loadedEnv, "TYPESENSE_COLLECTION") ?? "docs";
+	const apiKey = options.apiKey ?? getEnvValue(loadedEnv, "TYPESENSE_SEARCH_API_KEY") ?? getEnvValue(loadedEnv, "TYPESENSE_API_KEY");
+	const adminApiKey = options.adminApiKey ?? getEnvValue(loadedEnv, "TYPESENSE_ADMIN_API_KEY") ?? getEnvValue(loadedEnv, "TYPESENSE_API_KEY");
+	const mode = options.mode === "hybrid" ? "hybrid" : "keyword";
+	const ollamaModel = options.ollamaModel ?? getEnvValue(loadedEnv, "TYPESENSE_OLLAMA_MODEL");
+	const ollamaBaseUrl = options.ollamaBaseUrl ?? getEnvValue(loadedEnv, "TYPESENSE_OLLAMA_BASE_URL");
+	if (!baseUrl) throw new Error("Missing Typesense base URL. Set TYPESENSE_URL or pass --base-url.");
+	if (!apiKey) throw new Error("Missing Typesense API key. Set TYPESENSE_API_KEY or pass --api-key.");
+	if (!adminApiKey) throw new Error("Missing Typesense admin-capable key for sync. Set TYPESENSE_ADMIN_API_KEY or pass --admin-api-key.");
+	return {
+		provider: "typesense",
+		baseUrl,
+		collection,
+		apiKey,
+		adminApiKey,
+		mode,
+		...mode === "hybrid" ? ollamaModel ? { embeddings: {
+			provider: "ollama",
+			model: ollamaModel,
+			baseUrl: ollamaBaseUrl
+		} } : (() => {
+			throw new Error("Typesense hybrid sync needs an embeddings model. Set TYPESENSE_OLLAMA_MODEL or pass --ollama-model.");
+		})() : {}
+	};
+}
+function resolveAlgoliaSyncConfig(options, loadedEnv) {
+	const appId = options.appId ?? getEnvValue(loadedEnv, "ALGOLIA_APP_ID");
+	const indexName = options.indexName ?? getEnvValue(loadedEnv, "ALGOLIA_INDEX_NAME") ?? "docs";
+	const adminApiKey = options.adminApiKey ?? getEnvValue(loadedEnv, "ALGOLIA_ADMIN_API_KEY");
+	const searchApiKey = options.searchApiKey ?? getEnvValue(loadedEnv, "ALGOLIA_SEARCH_API_KEY") ?? adminApiKey;
+	if (!appId) throw new Error("Missing Algolia app id. Set ALGOLIA_APP_ID or pass --app-id.");
+	if (!adminApiKey) throw new Error("Missing Algolia admin API key for sync. Set ALGOLIA_ADMIN_API_KEY or pass --admin-api-key.");
+	if (!searchApiKey) throw new Error("Missing Algolia search API key. Set ALGOLIA_SEARCH_API_KEY or pass --search-api-key.");
+	return {
+		provider: "algolia",
+		appId,
+		indexName,
+		searchApiKey,
+		adminApiKey
+	};
+}
+async function syncSearch(options = {}) {
+	const rootDir = process.cwd();
+	const configContent = readFileSync(resolveDocsConfigPath(rootDir, options.configPath), "utf-8");
+	const loadedEnv = loadProjectEnv(rootDir);
+	const provider = resolveSearchSyncProvider(options, loadedEnv);
+	const entry = readStringProperty(configContent, "entry") ?? "docs";
+	const contentDir = resolveDocsContentDir(rootDir, configContent, entry);
+	const source = createFilesystemDocsMcpSource({
+		rootDir,
+		entry,
+		contentDir,
+		siteTitle: "Documentation"
+	});
+	const pages = await source.getPages();
+	const documents = buildDocsSearchDocuments(pages);
+	const context = {
+		pages,
+		documents,
+		siteTitle: source.siteTitle
+	};
+	if (documents.length === 0) throw new Error(`No docs content was found under ${contentDir}.`);
+	if (provider === "typesense") {
+		const config = resolveTypesenseSyncConfig(options, loadedEnv);
+		await createTypesenseSearchAdapter(config).index?.(context);
+		console.log(pc.green(`Synced ${documents.length} docs search documents to Typesense collection "${config.collection}".`));
+		return;
+	}
+	const config = resolveAlgoliaSyncConfig(options, loadedEnv);
+	await createAlgoliaSearchAdapter(config).index?.(context);
+	console.log(pc.green(`Synced ${documents.length} docs search documents to Algolia index "${config.indexName}".`));
+}
+
+//#endregion
+export { syncSearch };

package/dist/search-KzREATdM.d.mts

@@ -0,0 +1,21 @@
+import { E as DocsSearchSourcePage, N as McpDocsSearchConfig, Z as TypesenseDocsSearchConfig, b as DocsSearchConfig, g as DocsSearchAdapter, n as AlgoliaDocsSearchConfig, s as CustomDocsSearchConfig, v as DocsSearchAdapterFactory, w as DocsSearchResult, x as DocsSearchDocument, y as DocsSearchChunkingConfig } from "./types-BAulrjlV.mjs";
+
+//#region src/search.d.ts
+declare function buildDocsSearchDocuments(pages: DocsSearchSourcePage[], chunking?: DocsSearchChunkingConfig): DocsSearchDocument[];
+declare function createSimpleSearchAdapter(): DocsSearchAdapter;
+declare function createTypesenseSearchAdapter(config: TypesenseDocsSearchConfig): DocsSearchAdapter;
+declare function resolveSearchRequestConfig(search: boolean | DocsSearchConfig | undefined, requestUrl?: string): boolean | DocsSearchConfig | undefined;
+declare function createMcpSearchAdapter(config: McpDocsSearchConfig): DocsSearchAdapter;
+declare function createAlgoliaSearchAdapter(config: AlgoliaDocsSearchConfig): DocsSearchAdapter;
+declare function performDocsSearch(options: {
+  pages: DocsSearchSourcePage[];
+  query: string;
+  search?: boolean | DocsSearchConfig;
+  locale?: string;
+  pathname?: string;
+  siteTitle?: string;
+  limit?: number;
+}): Promise<DocsSearchResult[]>;
+declare function createCustomSearchAdapter(adapter: DocsSearchAdapter | DocsSearchAdapterFactory): CustomDocsSearchConfig;
+//#endregion
+export { createSimpleSearchAdapter as a, resolveSearchRequestConfig as c, createMcpSearchAdapter as i, createAlgoliaSearchAdapter as n, createTypesenseSearchAdapter as o, createCustomSearchAdapter as r, performDocsSearch as s, buildDocsSearchDocuments as t };

package/dist/server.d.mts

@@ -1,4 +1,5 @@
-import { o as DocsConfig } from "./types-Bd3kyFF1.mjs";
+import { C as DocsSearchQuery, E as DocsSearchSourcePage, N as McpDocsSearchConfig, _ as DocsSearchAdapterContext, b as DocsSearchConfig, c as DocsConfig, g as DocsSearchAdapter, v as DocsSearchAdapterFactory, w as DocsSearchResult, x as DocsSearchDocument } from "./types-BAulrjlV.mjs";
+import { a as createSimpleSearchAdapter, c as resolveSearchRequestConfig, i as createMcpSearchAdapter, n as createAlgoliaSearchAdapter, o as createTypesenseSearchAdapter, r as createCustomSearchAdapter, s as performDocsSearch, t as buildDocsSearchDocuments } from "./search-KzREATdM.mjs";
 import { DocsMcpHttpHandlers, DocsMcpNavigationNode, DocsMcpNavigationTree, DocsMcpPage, DocsMcpResolvedConfig, DocsMcpSource, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio } from "./mcp.mjs";
 
 //#region src/api-reference.d.ts
@@ -36,4 +37,4 @@ declare function buildApiReferenceOpenApiDocumentAsync(config: DocsConfig, optio
 declare function buildApiReferenceHtmlDocument(config: DocsConfig, options: BuildApiReferenceHtmlOptions): string;
 declare function buildApiReferenceHtmlDocumentAsync(config: DocsConfig, options: BuildApiReferenceHtmlOptions): Promise<string>;
 //#endregion
-export { type ApiReferenceFramework, type ApiReferenceRoute, type DocsMcpHttpHandlers, type DocsMcpNavigationNode, type DocsMcpNavigationTree, type DocsMcpPage, type DocsMcpResolvedConfig, type DocsMcpSource, type ResolvedApiReferenceConfig, buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveApiReferenceConfig, resolveDocsMcpConfig, runDocsMcpStdio };
+export { type ApiReferenceFramework, type ApiReferenceRoute, type DocsMcpHttpHandlers, type DocsMcpNavigationNode, type DocsMcpNavigationTree, type DocsMcpPage, type DocsMcpResolvedConfig, type DocsMcpSource, type DocsSearchAdapter, type DocsSearchAdapterContext, type DocsSearchAdapterFactory, type DocsSearchConfig, type DocsSearchDocument, type DocsSearchQuery, type DocsSearchResult, type DocsSearchSourcePage, type McpDocsSearchConfig, type ResolvedApiReferenceConfig, buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, buildDocsSearchDocuments, createAlgoliaSearchAdapter, createCustomSearchAdapter, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, createMcpSearchAdapter, createSimpleSearchAdapter, createTypesenseSearchAdapter, normalizeDocsMcpRoute, performDocsSearch, resolveApiReferenceConfig, resolveDocsMcpConfig, resolveSearchRequestConfig, runDocsMcpStdio };

package/dist/server.mjs

@@ -1,4 +1,5 @@
-import { a as buildApiReferencePageTitle, i as buildApiReferenceOpenApiDocumentAsync, n as buildApiReferenceHtmlDocumentAsync, o as buildApiReferenceScalarCss, r as buildApiReferenceOpenApiDocument, s as resolveApiReferenceConfig, t as buildApiReferenceHtmlDocument } from "./api-reference-wh4_pwG8.mjs";
+import { a as createSimpleSearchAdapter, c as resolveSearchRequestConfig, i as createMcpSearchAdapter, n as createAlgoliaSearchAdapter, o as createTypesenseSearchAdapter, r as createCustomSearchAdapter, s as performDocsSearch, t as buildDocsSearchDocuments } from "./search-BS6C5N1i.mjs";
+import { a as buildApiReferencePageTitle, i as buildApiReferenceOpenApiDocumentAsync, n as buildApiReferenceHtmlDocumentAsync, o as buildApiReferenceScalarCss, r as buildApiReferenceOpenApiDocument, s as resolveApiReferenceConfig, t as buildApiReferenceHtmlDocument } from "./api-reference-DlfH-Y9c.mjs";
 import { createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio } from "./mcp.mjs";
 
-export { buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveApiReferenceConfig, resolveDocsMcpConfig, runDocsMcpStdio };
+export { buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, buildDocsSearchDocuments, createAlgoliaSearchAdapter, createCustomSearchAdapter, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, createMcpSearchAdapter, createSimpleSearchAdapter, createTypesenseSearchAdapter, normalizeDocsMcpRoute, performDocsSearch, resolveApiReferenceConfig, resolveDocsMcpConfig, resolveSearchRequestConfig, runDocsMcpStdio };

package/dist/{types-Bd3kyFF1.d.mts → types-BAulrjlV.d.mts}

@@ -614,6 +614,144 @@ interface DocsMcpConfig {
   /** Fine-grained tool toggles. Omitted tools stay enabled. */
   tools?: DocsMcpToolsConfig;
 }
+type DocsSearchResultType = "page" | "heading" | "text";
+interface DocsSearchSourcePage {
+  title: string;
+  url: string;
+  content: string;
+  description?: string;
+  rawContent?: string;
+  type?: "page" | "api" | "code" | "changelog";
+  locale?: string;
+  framework?: string;
+  version?: string;
+  tags?: string[];
+}
+interface DocsSearchDocument {
+  id: string;
+  url: string;
+  title: string;
+  content: string;
+  description?: string;
+  section?: string;
+  type: DocsSearchResultType;
+  locale?: string;
+  framework?: string;
+  version?: string;
+  tags?: string[];
+}
+interface DocsSearchResult {
+  id: string;
+  url: string;
+  content: string;
+  description?: string;
+  type: DocsSearchResultType;
+  score?: number;
+  section?: string;
+}
+interface DocsSearchQuery {
+  query: string;
+  limit?: number;
+  locale?: string;
+  pathname?: string;
+}
+interface DocsSearchAdapterContext {
+  pages: DocsSearchSourcePage[];
+  documents: DocsSearchDocument[];
+  locale?: string;
+  pathname?: string;
+  siteTitle?: string;
+}
+interface DocsSearchAdapter {
+  name: string;
+  index?(context: DocsSearchAdapterContext): Promise<void>;
+  search(query: DocsSearchQuery, context: DocsSearchAdapterContext): Promise<DocsSearchResult[]>;
+}
+type DocsSearchAdapterFactory = (context: DocsSearchAdapterContext) => DocsSearchAdapter | Promise<DocsSearchAdapter>;
+interface DocsSearchChunkingConfig {
+  /**
+   * How docs content should be chunked before searching.
+   *
+   * - `"page"` keeps one search document per page
+   * - `"section"` splits pages by headings and improves precision
+   *
+   * @default "section"
+   */
+  strategy?: "page" | "section";
+}
+interface DocsSearchEmbeddingsConfig {
+  /**
+   * Embeddings provider used for hybrid / semantic search.
+   * The initial built-in provider is Ollama for local or self-hosted setups.
+   */
+  provider: "ollama";
+  /** Embedding model id, e.g. `embeddinggemma`. */
+  model: string;
+  /** Base URL of the embedding API. @default "http://127.0.0.1:11434" */
+  baseUrl?: string;
+}
+interface SimpleDocsSearchConfig {
+  provider?: "simple";
+  enabled?: boolean;
+  maxResults?: number;
+  chunking?: DocsSearchChunkingConfig;
+}
+interface AlgoliaDocsSearchConfig {
+  provider: "algolia";
+  enabled?: boolean;
+  appId: string;
+  indexName: string;
+  searchApiKey: string;
+  adminApiKey?: string;
+  maxResults?: number;
+  syncOnSearch?: boolean;
+  chunking?: DocsSearchChunkingConfig;
+}
+interface TypesenseDocsSearchConfig {
+  provider: "typesense";
+  enabled?: boolean;
+  baseUrl: string;
+  collection: string;
+  apiKey: string;
+  adminApiKey?: string;
+  maxResults?: number;
+  syncOnSearch?: boolean;
+  queryBy?: string[];
+  mode?: "keyword" | "hybrid";
+  embeddings?: DocsSearchEmbeddingsConfig;
+  chunking?: DocsSearchChunkingConfig;
+}
+interface McpDocsSearchConfig {
+  provider: "mcp";
+  enabled?: boolean;
+  /**
+   * Streamable HTTP MCP endpoint. Relative paths like `/api/docs/mcp` are resolved
+   * against the current docs API request URL.
+   */
+  endpoint: string;
+  /**
+   * Optional extra headers passed to the MCP endpoint on initialize/tool calls.
+   */
+  headers?: Record<string, string>;
+  /**
+   * MCP tool name used for search. Defaults to `search_docs`.
+   */
+  toolName?: string;
+  /**
+   * Override the MCP protocol version header when needed.
+   */
+  protocolVersion?: string;
+  maxResults?: number;
+  chunking?: DocsSearchChunkingConfig;
+}
+interface CustomDocsSearchConfig {
+  provider: "custom";
+  enabled?: boolean;
+  adapter: DocsSearchAdapter | DocsSearchAdapterFactory;
+  maxResults?: number;
+  chunking?: DocsSearchChunkingConfig;
+}
+type DocsSearchConfig = SimpleDocsSearchConfig | AlgoliaDocsSearchConfig | McpDocsSearchConfig | TypesenseDocsSearchConfig | CustomDocsSearchConfig;
 interface LastUpdatedConfig {
   /**
    * Whether to show the "Last updated" date.
@@ -1353,6 +1491,16 @@ interface DocsConfig {
    * ```
    */
   pageActions?: PageActionsConfig;
+  /**
+   * Built-in docs search configuration.
+   *
+   * - `true` or omitted → use the built-in simple search
+   * - `{ provider: "typesense", ... }` → use Typesense
+   * - `{ provider: "algolia", ... }` → use Algolia
+   * - `{ provider: "custom", adapter }` → use a custom adapter
+   * - `false` → disable docs search
+   */
+  search?: boolean | DocsSearchConfig;
   /**
    * Configuration for the "Last updated" date display.
    *
@@ -1481,4 +1629,4 @@ interface DocsConfig {
   og?: OGConfig;
 }
 //#endregion
-export { SidebarConfig as A, OpenGraphImage as C, PageOpenGraph as D, PageFrontmatter as E, ThemeToggleConfig as F, TypographyConfig as I, UIConfig as L, SidebarNode as M, SidebarPageNode as N, PageTwitter as O, SidebarTree as P, OpenDocsProvider as S, PageActionsConfig as T, GithubConfig as _, CopyMarkdownConfig as a, OGConfig as b, DocsFeedbackValue as c, DocsMcpToolsConfig as d, DocsMetadata as f, FontStyle as g, FeedbackConfig as h, CodeBlockCopyData as i, SidebarFolderNode as j, SidebarComponentProps as k, DocsI18nConfig as l, DocsTheme as m, ApiReferenceConfig as n, DocsConfig as o, DocsNav as p, BreadcrumbConfig as r, DocsFeedbackData as s, AIConfig as t, DocsMcpConfig as u, LastUpdatedConfig as v, OrderingItem as w, OpenDocsConfig as x, LlmsTxtConfig as y };
+export { UIConfig as $, GithubConfig as A, PageFrontmatter as B, DocsSearchQuery as C, DocsTheme as D, DocsSearchSourcePage as E, OpenDocsConfig as F, SidebarFolderNode as G, PageTwitter as H, OpenDocsProvider as I, SidebarTree as J, SidebarNode as K, OpenGraphImage as L, LlmsTxtConfig as M, McpDocsSearchConfig as N, FeedbackConfig as O, OGConfig as P, TypographyConfig as Q, OrderingItem as R, DocsSearchEmbeddingsConfig as S, DocsSearchResultType as T, SidebarComponentProps as U, PageOpenGraph as V, SidebarConfig as W, ThemeToggleConfig as X, SimpleDocsSearchConfig as Y, TypesenseDocsSearchConfig as Z, DocsSearchAdapterContext as _, CodeBlockCopyData as a, DocsSearchConfig as b, DocsConfig as c, DocsI18nConfig as d, DocsMcpConfig as f, DocsSearchAdapter as g, DocsNav as h, BreadcrumbConfig as i, LastUpdatedConfig as j, FontStyle as k, DocsFeedbackData as l, DocsMetadata as m, AlgoliaDocsSearchConfig as n, CopyMarkdownConfig as o, DocsMcpToolsConfig as p, SidebarPageNode as q, ApiReferenceConfig as r, CustomDocsSearchConfig as s, AIConfig as t, DocsFeedbackValue as u, DocsSearchAdapterFactory as v, DocsSearchResult as w, DocsSearchDocument as x, DocsSearchChunkingConfig as y, PageActionsConfig as z };

package/dist/upgrade-J_kkv-ti.mjs

@@ -0,0 +1,138 @@
+import { c as installCommand, i as detectPackageManagerFromLockfile, o as exec, s as fileExists, t as detectFramework } from "./utils-CRhME2g-.mjs";
+import path from "node:path";
+import pc from "picocolors";
+import * as p from "@clack/prompts";
+
+//#region src/cli/upgrade.ts
+/**
+* Upgrade @farming-labs/* packages to latest.
+* Detects framework from package.json by default, or use --framework (next, tanstack-start, nuxt, sveltekit, astro).
+*/
+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"
+	],
+	sveltekit: [
+		"@farming-labs/docs",
+		"@farming-labs/svelte",
+		"@farming-labs/svelte-theme"
+	],
+	astro: [
+		"@farming-labs/docs",
+		"@farming-labs/astro",
+		"@farming-labs/astro-theme"
+	]
+};
+function presetFromFramework(fw) {
+	return fw === "nextjs" ? "next" : fw;
+}
+function frameworkFromPreset(preset) {
+	return preset === "next" ? "nextjs" : preset;
+}
+/** Return package list for a framework (for testing and CLI). */
+function getPackagesForFramework(framework) {
+	return PACKAGES_BY_FRAMEWORK[framework];
+}
+/** Build the install command for upgrade (for testing). */
+function buildUpgradeCommand(framework, tag, pm) {
+	const packagesWithTag = PACKAGES_BY_FRAMEWORK[framework].map((name) => `${name}@${tag}`);
+	return `${installCommand(pm)} ${packagesWithTag.join(" ")}`;
+}
+async function upgrade(options = {}) {
+	const cwd = process.cwd();
+	const tag = options.tag ?? "latest";
+	p.intro(pc.bgCyan(pc.black(" @farming-labs/docs upgrade ")));
+	if (!fileExists(path.join(cwd, "package.json"))) {
+		p.log.error("No package.json found in the current directory. Run this from your project root.");
+		process.exit(1);
+	}
+	let framework = null;
+	let preset;
+	if (options.framework) {
+		const raw = options.framework.toLowerCase().trim();
+		const normalized = raw === "nextjs" ? "next" : raw;
+		if (!PRESETS.includes(normalized)) {
+			p.log.error(`Invalid framework ${pc.cyan(options.framework)}. Use one of: ${PRESETS.map((t) => pc.cyan(t)).join(", ")}`);
+			process.exit(1);
+		}
+		preset = normalized;
+		framework = frameworkFromPreset(preset);
+	} else {
+		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);
+		}
+		framework = detected;
+		preset = presetFromFramework(framework);
+	}
+	let pm = detectPackageManagerFromLockfile(cwd);
+	if (pm) p.log.info(`Detected ${pc.cyan(pm)} from lockfile`);
+	else {
+		const pmAnswer = await p.select({
+			message: "Which package manager do you want to use for this upgrade?",
+			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)) {
+			p.outro(pc.red("Upgrade cancelled."));
+			process.exit(0);
+		}
+		pm = pmAnswer;
+		p.log.info(`Using ${pc.cyan(pm)} as package manager`);
+	}
+	const cmd = buildUpgradeCommand(framework, tag, pm);
+	const packages = getPackagesForFramework(framework);
+	p.log.step(`Upgrading ${preset} docs packages to ${tag}...`);
+	p.log.message(pc.dim(packages.join(", ")));
+	try {
+		exec(cmd, cwd);
+		p.log.success(`Packages upgraded to ${tag}.`);
+		p.outro(pc.green("Done. Run your dev server to confirm everything works."));
+	} catch {
+		p.log.error("Upgrade failed. Try running manually:\n  " + pc.cyan(cmd));
+		process.exit(1);
+	}
+}
+
+//#endregion
+export { upgrade };

package/dist/utils-CRhME2g-.mjs

@@ -0,0 +1,145 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execSync, spawn } from "node:child_process";
+
+//#region src/cli/utils.ts
+function detectFramework(cwd) {
+	const pkgPath = path.join(cwd, "package.json");
+	if (!fs.existsSync(pkgPath)) return null;
+	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+	const allDeps = {
+		...pkg.dependencies,
+		...pkg.devDependencies
+	};
+	if (allDeps["next"]) return "nextjs";
+	if (allDeps["@tanstack/react-start"]) return "tanstack-start";
+	if (allDeps["@sveltejs/kit"]) return "sveltekit";
+	if (allDeps["astro"]) return "astro";
+	if (allDeps["nuxt"]) return "nuxt";
+	return null;
+}
+function detectPackageManagerFromLockfile(cwd) {
+	if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+	if (fs.existsSync(path.join(cwd, "bun.lockb")) || fs.existsSync(path.join(cwd, "bun.lock"))) return "bun";
+	if (fs.existsSync(path.join(cwd, "yarn.lock"))) return "yarn";
+	if (fs.existsSync(path.join(cwd, "package-lock.json"))) return "npm";
+	return null;
+}
+function installCommand(pm) {
+	return pm === "yarn" ? "yarn add" : `${pm} add`;
+}
+function devInstallCommand(pm) {
+	if (pm === "yarn") return "yarn add -D";
+	if (pm === "npm") return "npm install -D";
+	return `${pm} add -D`;
+}
+/**
+* Write a file, creating parent directories as needed.
+* Returns true if the file was written, false if it already existed and was skipped.
+*/
+function writeFileSafe(filePath, content, overwrite = false) {
+	if (fs.existsSync(filePath) && !overwrite) return false;
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.writeFileSync(filePath, content, "utf-8");
+	return true;
+}
+/**
+* Check if a file exists.
+*/
+function fileExists(filePath) {
+	return fs.existsSync(filePath);
+}
+/**
+* Read a file, returning null if it does not exist.
+*/
+function readFileSafe(filePath) {
+	if (!fs.existsSync(filePath)) return null;
+	return fs.readFileSync(filePath, "utf-8");
+}
+/** Common locations where global CSS files live in Next.js / SvelteKit projects. */
+const GLOBAL_CSS_CANDIDATES = [
+	"app/globals.css",
+	"app/global.css",
+	"src/app/globals.css",
+	"src/app/global.css",
+	"src/app.css",
+	"src/styles/app.css",
+	"styles/globals.css",
+	"styles/global.css",
+	"src/styles/globals.css",
+	"src/styles/global.css",
+	"assets/css/main.css",
+	"assets/main.css"
+];
+/**
+* Find existing global CSS files in the project.
+* Returns relative paths that exist.
+*/
+function detectGlobalCssFiles(cwd) {
+	return GLOBAL_CSS_CANDIDATES.filter((rel) => fs.existsSync(path.join(cwd, rel)));
+}
+/**
+* Detect whether the Next.js project uses `app` or `src/app` for the App Router.
+* Returns the directory that exists; if both exist, prefers src/app; if neither, returns null.
+*/
+function detectNextAppDir(cwd) {
+	const hasSrcApp = fs.existsSync(path.join(cwd, "src", "app"));
+	const hasApp = fs.existsSync(path.join(cwd, "app"));
+	if (hasSrcApp) return "src/app";
+	if (hasApp) return "app";
+	return null;
+}
+/**
+* Run a shell command synchronously, inheriting stdio.
+*/
+function exec(command, cwd) {
+	execSync(command, {
+		cwd,
+		stdio: "inherit"
+	});
+}
+/**
+* Spawn a process and wait for a specific string in stdout,
+* then resolve with the child process (still running).
+*/
+function spawnAndWaitFor(command, args, cwd, waitFor, timeoutMs = 6e4) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			cwd,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			shell: true
+		});
+		let output = "";
+		const timer = setTimeout(() => {
+			child.kill();
+			reject(/* @__PURE__ */ new Error(`Timed out waiting for "${waitFor}" after ${timeoutMs}ms`));
+		}, timeoutMs);
+		child.stdout?.on("data", (data) => {
+			const text = data.toString();
+			output += text;
+			process.stdout.write(text);
+			if (output.includes(waitFor)) {
+				clearTimeout(timer);
+				resolve(child);
+			}
+		});
+		child.stderr?.on("data", (data) => {
+			process.stderr.write(data.toString());
+		});
+		child.on("error", (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			if (!output.includes(waitFor)) reject(/* @__PURE__ */ new Error(`Process exited with code ${code} before "${waitFor}" appeared`));
+		});
+	});
+}
+
+//#endregion
+export { devInstallCommand as a, installCommand as c, writeFileSafe as d, detectPackageManagerFromLockfile as i, readFileSafe as l, detectGlobalCssFiles as n, exec as o, detectNextAppDir as r, fileExists as s, detectFramework as t, spawnAndWaitFor as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",