@wrikka/create-docs 0.1.0

package/src/adapters/github/github-pull.ts

@@ -0,0 +1,340 @@
+/**
+ * Build-time GitHub docs puller.
+ *
+ * Given a list of remote GitHub repositories (or local directories), fetch the
+ * docs tree and write markdown + frontmatter files to a local directory. The
+ * output is consumed by `createStaticDataSource()` in the Solid runtime: files
+ * are organised under `docs/{collectionId}/...` and `sources.json` /
+ * `manifest.json` are emitted next to them.
+ */
+
+import {
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import * as path from "node:path";
+import { parseFrontmatter } from "../../runtime/content";
+
+export interface GitHubSource {
+	/** Collection id used in the URL and sidebar. */
+	id: string;
+	/** Human-readable label. Defaults to the repo name. */
+	label?: string;
+	/** Short description for the collection. */
+	description?: string;
+	/** Repository URL or `owner/repo`. */
+	repo: string;
+	/** Branch or tag. */
+	branch?: string;
+	/** Path inside the repo where the docs live. Defaults to `docs`. */
+	docsDir?: string;
+	/** Iconify icon class. */
+	icon?: string;
+	/** Optional local docs directory; when set, files are copied instead of fetching from GitHub. */
+	localDir?: string;
+	/** When true, continue with a warning if this source cannot be fetched. */
+	optional?: boolean;
+}
+
+export interface GitHubPullOptions {
+	/** Output directory for pulled docs and the generated manifest. */
+	outDir: string;
+	/** GitHub sources. */
+	sources: GitHubSource[];
+	/** Optional token for private repositories and higher rate limits. */
+	token?: string;
+	/** Optional GitHub API base URL. */
+	apiBase?: string;
+	/** Optional raw base URL. */
+	rawBase?: string;
+}
+
+export interface PullResult {
+	/** Collection metadata written to `sources.json`. */
+	collections: Array<{
+		id: string;
+		label: string;
+		description?: string;
+		icon?: string;
+		repoUrl?: string;
+	}>;
+	/** Number of files written. */
+	filesWritten: number;
+	/** Output directory. */
+	outDir: string;
+	/** Manifest for SEO and server-side consumers. */
+	manifest: DocsManifest;
+}
+
+export interface DocsManifest {
+	collections: PullResult["collections"];
+	docs: Record<
+		string,
+		Array<{
+			id: string;
+			label: string;
+			category: string;
+			description: string;
+			path: string;
+			type: "md";
+		}>
+	>;
+}
+
+interface RepoRef {
+	owner: string;
+	name: string;
+}
+
+function parseRepo(repo: string): RepoRef {
+	const clean = repo
+		.replace(/https?:\/\/github\.com\//, "")
+		.replace(/\.git$/, "");
+	const parts = clean.split("/");
+	if (parts.length < 2) {
+		throw new Error(`Invalid repo: ${repo}`);
+	}
+	return { owner: parts[0] as string, name: parts[1] as string };
+}
+
+function authHeaders(token?: string): Record<string, string> {
+	const headers: Record<string, string> = {
+		Accept: "application/vnd.github+json",
+		"X-GitHub-Api-Version": "2022-11-28",
+		"User-Agent": "create-docs",
+	};
+	if (token) {
+		headers.Authorization = `Bearer ${token}`;
+	}
+	return headers;
+}
+
+function toPosix(p: string): string {
+	return p.replace(/\\/g, "/");
+}
+
+function relativeWithinDocs(filePath: string, docsDir: string): string {
+	const normalized = toPosix(filePath).replace(/^\//, "");
+	const prefix = toPosix(docsDir).replace(/\/$/, "").replace(/^\//, "");
+	if (
+		prefix &&
+		(normalized === prefix || normalized.startsWith(`${prefix}/`))
+	) {
+		return normalized.slice(prefix.length + (prefix ? 1 : 0));
+	}
+	return normalized;
+}
+
+interface TreeItem {
+	path: string;
+	mode: string;
+	type: string;
+	sha: string;
+	size?: number;
+	url: string;
+}
+
+async function fetchTree(
+	ref: RepoRef,
+	branch: string,
+	token: string | undefined,
+	apiBase: string,
+): Promise<TreeItem[]> {
+	const url = `${apiBase}/repos/${ref.owner}/${ref.name}/git/trees/${encodeURIComponent(branch)}?recursive=1`;
+	const res = await fetch(url, { headers: authHeaders(token) });
+	if (!res.ok) {
+		const text = await res.text();
+		throw new Error(`GitHub API error ${res.status}: ${text}`);
+	}
+	const data = (await res.json()) as { tree?: TreeItem[] };
+	return data.tree ?? [];
+}
+
+async function fetchRaw(
+	ref: RepoRef,
+	branch: string,
+	filePath: string,
+	rawBase: string,
+	token: string | undefined,
+): Promise<string> {
+	const url = `${rawBase}/${ref.owner}/${ref.name}/${encodeURIComponent(branch)}/${toPosix(filePath)}`;
+	const headers: Record<string, string> = {};
+	if (token) headers.Authorization = `Bearer ${token}`;
+	const res = await fetch(url, { headers });
+	if (!res.ok) {
+		throw new Error(`Failed to fetch ${url}: ${res.status}`);
+	}
+	return res.text();
+}
+
+function makeDocId(relativePath: string): string {
+	return relativePath.replace(/\.(md|mdx)$/i, "").replace(/[/\\]/g, "--");
+}
+
+interface LocalFile {
+	relative: string;
+	absolute: string;
+}
+
+function scanLocalDir(dir: string, prefix = ""): LocalFile[] {
+	const items: LocalFile[] = [];
+	for (const name of readdirSync(dir)) {
+		const absolute = path.join(dir, name);
+		const relative = prefix ? `${prefix}/${name}` : name;
+		if (statSync(absolute).isDirectory()) {
+			items.push(...scanLocalDir(absolute, relative));
+		} else if (/\.(md|mdx)$/i.test(name) || /^_dir\.ya?ml$/i.test(name)) {
+			items.push({ relative, absolute });
+		}
+	}
+	return items;
+}
+
+function addDocToManifest(
+	docs: DocsManifest["docs"],
+	collectionId: string,
+	raw: string,
+	docPath: string,
+): void {
+	const { data: fm, content } = parseFrontmatter(raw);
+	const parts = docPath.split("/");
+	const dir = parts.slice(0, -1).join("/");
+	const file = parts[parts.length - 1] ?? "";
+	const category =
+		fm.category ?? (dir ? dir.split("/").pop() : "Docs") ?? "Docs";
+	const label = fm.title ?? file.replace(/\.(md|mdx)$/i, "");
+	const description =
+		fm.description ??
+		content
+			.split("\n")
+			.find((l) => l.trim() && !l.startsWith("#"))
+			?.trim() ??
+		"";
+
+	docs[collectionId] ??= [];
+	const list = docs[collectionId];
+	list.push({
+		id: makeDocId(docPath),
+		label,
+		category,
+		description,
+		path: docPath,
+		type: "md",
+	});
+}
+
+export async function pullFromGitHub(
+	options: GitHubPullOptions,
+): Promise<PullResult> {
+	const {
+		outDir,
+		sources,
+		token = process.env.GITHUB_TOKEN,
+		apiBase = "https://api.github.com",
+		rawBase = "https://raw.githubusercontent.com",
+	} = options;
+
+	const resolvedOut = path.resolve(outDir);
+	const docsOut = path.join(resolvedOut, "docs");
+	const collections: PullResult["collections"] = [];
+	const docs: DocsManifest["docs"] = {};
+	let filesWritten = 0;
+
+	for (const source of sources) {
+		try {
+			const ref = parseRepo(source.repo);
+			const repoUrl = `https://github.com/${ref.owner}/${ref.name}`;
+			const branch = source.branch ?? "main";
+			const docsDir = source.docsDir ?? "docs";
+			const collectionId = source.id;
+
+			const collectionOut = path.join(docsOut, collectionId);
+			mkdirSync(collectionOut, { recursive: true });
+
+			// Local mode: copy files from a local directory.
+			if (source.localDir && statSync(source.localDir).isDirectory()) {
+				const localFiles = scanLocalDir(source.localDir);
+				for (const { relative, absolute } of localFiles) {
+					const content = readFileSync(absolute, "utf8");
+					const target = path.join(collectionOut, ...relative.split(/[/\\]/));
+					mkdirSync(path.dirname(target), { recursive: true });
+					writeFileSync(target, content, "utf8");
+					filesWritten++;
+
+					if (/\.(md|mdx)$/i.test(relative)) {
+						addDocToManifest(docs, collectionId, content, toPosix(relative));
+					}
+				}
+			} else {
+				const tree = await fetchTree(ref, branch, token, apiBase);
+
+				// Collect markdown and _dir.yml files under docsDir.
+				const wanted: TreeItem[] = [];
+				for (const item of tree) {
+					if (item.type !== "blob") continue;
+					const relative = relativeWithinDocs(item.path, docsDir);
+					if (relative === item.path && docsDir !== "") continue;
+					if (
+						/\.(md|mdx)$/i.test(relative) ||
+						/^_dir\.ya?ml$/i.test(path.basename(relative))
+					) {
+						wanted.push(item);
+					}
+				}
+
+				for (const item of wanted) {
+					const relative = relativeWithinDocs(item.path, docsDir);
+					const target = path.join(collectionOut, ...relative.split("/"));
+					mkdirSync(path.dirname(target), { recursive: true });
+
+					const raw = await fetchRaw(ref, branch, item.path, rawBase, token);
+					writeFileSync(target, raw, "utf8");
+					filesWritten++;
+
+					if (/\.(md|mdx)$/i.test(relative)) {
+						addDocToManifest(docs, collectionId, raw, toPosix(relative));
+					}
+				}
+			}
+
+			docs[collectionId] = (docs[collectionId] ?? []).sort((a, b) =>
+				a.id.localeCompare(b.id),
+			);
+
+			collections.push({
+				id: collectionId,
+				label: source.label ?? ref.name,
+				description: source.description,
+				icon: source.icon,
+				repoUrl,
+			});
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			if (source.optional) {
+				console.warn(
+					`[create-docs] Skipped optional source "${source.id}": ${message}`,
+				);
+			} else {
+				throw new Error(`Failed to pull source "${source.id}": ${message}`);
+			}
+		}
+	}
+
+	mkdirSync(resolvedOut, { recursive: true });
+	const manifest: DocsManifest = { collections, docs };
+	writeFileSync(
+		path.join(resolvedOut, "sources.json"),
+		JSON.stringify(collections, null, "\t"),
+		"utf8",
+	);
+	writeFileSync(
+		path.join(resolvedOut, "manifest.json"),
+		JSON.stringify(manifest, null, "\t"),
+		"utf8",
+	);
+
+	return { collections, filesWritten, outDir: resolvedOut, manifest };
+}

package/src/adapters/index.ts

@@ -0,0 +1,6 @@
+export * from "./config";
+export * from "./fs";
+export * from "./git";
+export { pullFromGitHub } from "./github/github-pull";
+export * from "./velite";
+export * from "./vite";

package/src/adapters/velite.ts

@@ -0,0 +1,112 @@
+/**
+ * Velite Adapter
+ *
+ * Adapter layer for Velite content processing.
+ * Wraps Velite's build function with framework-agnostic interface.
+ *
+ * ## Architecture
+ * - Adapter Layer: I/O implementation for Velite
+ * - No business logic, pure wrapper functions
+ * - Framework-agnostic content API
+ */
+
+import { build } from "velite";
+
+/**
+ * Velite adapter options
+ */
+export interface VeliteAdapterOptions {
+	/** Path to velite.config.ts file */
+	configPath?: string;
+	/** Watch mode for development */
+	watch?: boolean;
+}
+
+/**
+ * Velite build result
+ */
+export interface VeliteBuildResult {
+	/** Success status */
+	success: boolean;
+	/** Error message if failed */
+	error?: string;
+	/** Output data directory */
+	outputDir?: string;
+	/** Assets output directory */
+	assetsDir?: string;
+}
+
+/**
+ * Velite adapter interface
+ */
+export interface VeliteAdapter {
+	/** Run Velite build */
+	build: () => Promise<VeliteBuildResult>;
+	/** Path to velite.config.ts file */
+	configPath: string;
+	/** Watch mode for development */
+	watch: boolean;
+}
+
+/**
+ * Create Velite adapter
+ *
+ * @param options - Adapter options
+ * @returns Build function
+ */
+export const createVeliteAdapter = (
+	options: VeliteAdapterOptions = {},
+): VeliteAdapter => {
+	const { configPath = "velite.config.ts", watch = false } = options;
+
+	/**
+	 * Run Velite build
+	 *
+	 * @returns Build result
+	 */
+	const buildVelite = async (): Promise<VeliteBuildResult> => {
+		try {
+			const buildOptions: Parameters<typeof build>[0] = {
+				config: configPath,
+				watch,
+			};
+
+			await build(buildOptions);
+
+			return {
+				success: true,
+				outputDir: ".velite",
+				assetsDir: "public/static",
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	};
+
+	return {
+		build: buildVelite,
+		configPath,
+		watch,
+	};
+};
+
+/**
+ * Default Velite adapter instance
+ */
+export const defaultVeliteAdapter: VeliteAdapter = createVeliteAdapter();
+
+/**
+ * Convenience function to build Velite content
+ *
+ * @param options - Build options
+ * @returns Build result
+ */
+export const buildVelite = async (
+	options: VeliteAdapterOptions = {},
+): Promise<VeliteBuildResult> => {
+	const adapter = createVeliteAdapter(options);
+	return adapter.build();
+};

package/src/adapters/vite/docs-watcher.ts

@@ -0,0 +1,36 @@
+/**
+ * Vite server-backed docs watcher.
+ * Wires node:fs to the plugin's DocsWatcher port using the Vite dev server's
+ * own file-watching facility.
+ */
+import * as fs from "node:fs/promises";
+import type { DocsWatcher } from "@create-docs/modules/plugin";
+import { SUPPORTED_EXTENSIONS } from "@create-docs/shared/constants";
+
+export const createNodeDocsWatcher = (): DocsWatcher => ({
+	watch(docsDir: string, onChange: (filePath: string) => void) {
+		const ac = new AbortController();
+		const iterator = fs
+			.watch(docsDir, { recursive: true, signal: ac.signal } as fs.WatchOptions)
+			[Symbol.asyncIterator]();
+		const consume = async (): Promise<void> => {
+			try {
+				for await (const event of iterator) {
+					const filename = (event as { filename?: unknown }).filename;
+					if (typeof filename !== "string") return;
+					if (!SUPPORTED_EXTENSIONS.some((ext) => filename.endsWith(ext)))
+						return;
+					onChange(filename);
+				}
+			} catch {
+				// aborted — exit silently
+			}
+		};
+		void consume();
+		return {
+			close: () => {
+				ac.abort();
+			},
+		};
+	},
+});

package/src/adapters/vite/index.ts

@@ -0,0 +1,2 @@
+export { createNodeDocsWatcher } from "./docs-watcher";
+export { createPollingWatcher } from "./polling-watcher";

package/src/adapters/vite/polling-watcher.ts

@@ -0,0 +1,89 @@
+/**
+ * Polling-based watcher fallback.
+ *
+ * `fs.watch` with `recursive: true` is unreliable on Linux (inotify misses
+ * sub-directory events until a file is touched). This walker periodically
+ * diffs the directory tree and emits change events for any file whose mtime
+ * or presence has changed since the last scan.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { SUPPORTED_EXTENSIONS } from "@create-docs/shared/constants";
+
+export interface PollingWatcherOptions {
+	readonly intervalMs?: number;
+}
+
+interface FileSnapshot {
+	readonly mtimeMs: number;
+	readonly size: number;
+}
+
+const isSupported = (name: string): boolean =>
+	SUPPORTED_EXTENSIONS.some((ext) => name.endsWith(ext));
+
+const snapshotDir = async (dir: string): Promise<Map<string, FileSnapshot>> => {
+	const out = new Map<string, FileSnapshot>();
+	const walk = async (current: string): Promise<void> => {
+		let entries: import("node:fs").Dirent[];
+		try {
+			entries = await fs.readdir(current, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const full = path.join(current, entry.name);
+			if (entry.isDirectory()) {
+				await walk(full);
+			} else if (entry.isFile() && isSupported(entry.name)) {
+				try {
+					const s = await fs.stat(full);
+					out.set(full, { mtimeMs: s.mtimeMs, size: s.size });
+				} catch {
+					// file vanished between readdir and stat - ignore
+				}
+			}
+		}
+	};
+	await walk(dir);
+	return out;
+};
+
+export const createPollingWatcher = (
+	opts: PollingWatcherOptions = {},
+): {
+	watch: (
+		dir: string,
+		onChange: (filePath: string) => void,
+	) => { close: () => void };
+} => {
+	const interval = opts.intervalMs ?? 300;
+	return {
+		watch(dir, onChange) {
+			let stopped = false;
+			let prev: Promise<Map<string, FileSnapshot>> = snapshotDir(dir);
+			const tick = async (): Promise<void> => {
+				if (stopped) return;
+				const next = await snapshotDir(dir);
+				const before = await prev;
+				for (const [file, snap] of next) {
+					const old = before.get(file);
+					if (!old || old.mtimeMs !== snap.mtimeMs || old.size !== snap.size) {
+						onChange(file);
+					}
+				}
+				for (const file of before.keys()) {
+					if (!next.has(file)) onChange(file);
+				}
+				prev = Promise.resolve(next);
+				if (!stopped) setTimeout(tick, interval);
+			};
+			void tick();
+			return {
+				close: () => {
+					stopped = true;
+				},
+			};
+		},
+	};
+};

package/src/code-block-enhancements/index.ts

@@ -0,0 +1,3 @@
+export type CodeBlock = unknown;
+export type CodeBlockOptions = unknown;
+export const enhanceCodeBlocks = () => null;

package/src/config/index.ts

@@ -0,0 +1,15 @@
+export type ApiConfig = unknown;
+export type ApiEndpoint = unknown;
+export type AuthType = unknown;
+export type DocsConfig = unknown;
+export type DocsPluginOptions = unknown;
+export type EditLinkConfig = unknown;
+export type HttpMethod = unknown;
+export type LastUpdatedConfig = unknown;
+export type ResolvedDocsConfig = unknown;
+export type SearchConfig = unknown;
+export type SiteConfig = unknown;
+export type ThemeConfig = unknown;
+export const defaultDocsConfig = () => null;
+export const resolveConfig = () => null;
+export const validateDocsConfig = () => null;

package/src/content/index.ts

@@ -0,0 +1,11 @@
+export type BadgeVariant = unknown;
+export type DocFile = unknown;
+export type DocId = unknown;
+export type DocPage = unknown;
+export type DocSlug = unknown;
+export type FilePath = unknown;
+export type Frontmatter = unknown;
+export type ParsedContent = unknown;
+export const buildDocPage = () => null;
+export const buildDocPageFromRaw = () => null;
+export const parseFrontmatter = () => null;

package/src/content-validation/index.ts

@@ -0,0 +1,5 @@
+export type ContentValidator = unknown;
+export type ValidationError = unknown;
+export type ValidationOptions = unknown;
+export type ValidationResult = unknown;
+export const validate = () => null;