@wrikka/create-docs 0.1.0

package/scripts/generate-docs-index.ts

@@ -0,0 +1,111 @@
+import {
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { load as parseYaml } from "js-yaml";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+
+const collections = [
+	{ id: "docs", dir: join(root, "docs") },
+	{ id: "api", dir: join(root, "api") },
+	{ id: "showcase", dir: join(root, "showcase") },
+];
+
+function walk(dir: string): string[] {
+	let entries: string[] = [];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return [];
+	}
+	const files: string[] = [];
+	for (const entry of entries) {
+		const full = join(dir, entry);
+		const stat = statSync(full);
+		if (stat.isDirectory()) {
+			files.push(...walk(full));
+		} else if (stat.isFile()) {
+			files.push(full);
+		}
+	}
+	return files;
+}
+
+function stripMarkdown(md: string): string {
+	return md
+		.replace(/```[\s\S]*?```/g, " ")
+		.replace(/`[^`]*`/g, " ")
+		.replace(/!\[[^\]]*\]\([^)]*\)/g, " ")
+		.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+		.replace(/^#{1,6}\s+/gm, "")
+		.replace(/[*_~`]/g, "")
+		.replace(/<[^>]+>/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+function parseFrontmatter(content: string) {
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+	if (!match) {
+		return { frontmatter: {} as Record<string, unknown>, body: content };
+	}
+	let frontmatter: Record<string, unknown> = {};
+	try {
+		frontmatter = (parseYaml(match[1]) ?? {}) as Record<string, unknown>;
+	} catch {
+		frontmatter = {};
+	}
+	return { frontmatter, body: content.slice(match[0].length) };
+}
+
+const docs: Array<{
+	collection: string;
+	id: string;
+	title: string;
+	description: string;
+	text: string;
+	content: string;
+}> = [];
+
+for (const collection of collections) {
+	const files = walk(collection.dir);
+	for (const file of files) {
+		if (!file.endsWith(".md")) continue;
+		const rel = relative(collection.dir, file)
+			.replace(/\\/g, "/")
+			.replace(/\.md$/, "");
+		const raw = readFileSync(file, "utf8");
+		const { frontmatter, body } = parseFrontmatter(raw);
+		const title =
+			typeof frontmatter.title === "string" ? frontmatter.title : rel;
+		const description =
+			typeof frontmatter.description === "string"
+				? frontmatter.description
+				: "";
+		docs.push({
+			collection: collection.id,
+			id: rel,
+			title,
+			description,
+			text: stripMarkdown(body),
+			content: body,
+		});
+	}
+}
+
+const outDir = process.argv.includes("--dev")
+	? join(root, "dev", "dist")
+	: join(root, "dist");
+mkdirSync(outDir, { recursive: true });
+writeFileSync(
+	join(outDir, "search-index.json"),
+	JSON.stringify({ docs }, null, 2),
+);
+
+console.log(`Generated ${docs.length} docs index entries`);

package/scripts/github-pull.ts

@@ -0,0 +1,124 @@
+#!/usr/bin/env bun
+/**
+ * Build-time helper: pull markdown docs from one or more GitHub repositories.
+ *
+ * Usage:
+ *   bun scripts/github-pull.ts --config create-docs.config.ts
+ *
+ * Config file (create-docs.config.ts):
+ *   export default {
+ *     outDir: "./docs-remote",
+ *     sources: [
+ *       { id: "rust-packages", repo: "wrikka/rust-packages", branch: "main", docsDir: "docs" },
+ *     ],
+ *   };
+ */
+
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { pullFromGitHub } from "../src/adapters/github/github-pull";
+
+function parseArgs(argv: string[]) {
+	const args: Record<string, string | undefined> = {};
+	let i = 0;
+	while (i < argv.length) {
+		const a = argv[i];
+		if (a === "--config" || a === "-c") {
+			args.config = argv[++i];
+		} else if (a.startsWith("--config=")) {
+			args.config = a.slice("--config=".length);
+		} else if (a === "--out" || a === "-o") {
+			args.out = argv[++i];
+		} else if (a.startsWith("--out=")) {
+			args.out = a.slice("--out=".length);
+		} else if (a === "--token" || a === "-t") {
+			args.token = argv[++i];
+		} else if (a.startsWith("--token=")) {
+			args.token = a.slice("--token=".length);
+		} else if (a === "--help" || a === "-h") {
+			args.help = "1";
+		}
+		i++;
+	}
+	return args;
+}
+
+function usage() {
+	console.log(`
+Usage: bun scripts/github-pull.ts --config <create-docs.config.ts>
+
+Options:
+  -c, --config    Path to the pull config file (default: create-docs.config.ts)
+  -o, --out       Override output directory from the config
+  -t, --token     GitHub token (or set GITHUB_TOKEN)
+  -h, --help      Show this message
+
+Config example:
+  export default {
+    outDir: "./docs-remote",
+    sources: [
+      { id: "rust-packages", repo: "wrikka/rust-packages", branch: "main", docsDir: "docs" },
+    ],
+  };
+`);
+}
+
+interface PullConfig {
+	outDir?: string;
+	sources: Array<{
+		id: string;
+		repo: string;
+		branch?: string;
+		docsDir?: string;
+		label?: string;
+		description?: string;
+		icon?: string;
+	}>;
+}
+
+async function loadConfig(configPath: string): Promise<PullConfig> {
+	const abs = path.isAbsolute(configPath)
+		? configPath
+		: path.resolve(process.cwd(), configPath);
+	if (!existsSync(abs)) {
+		throw new Error(`Config not found: ${abs}`);
+	}
+	const mod = (await import(pathToFileURL(abs).href)) as {
+		default?: PullConfig;
+	};
+	if (!mod.default) {
+		throw new Error(`Config must have a default export: ${abs}`);
+	}
+	return mod.default;
+}
+
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	if (args.help) {
+		usage();
+		process.exit(0);
+	}
+
+	const configPath = args.config ?? "create-docs.config.ts";
+	const config = await loadConfig(configPath);
+	const outDir = args.out ?? config.outDir ?? "docs-remote";
+
+	const result = await pullFromGitHub({
+		outDir,
+		sources: config.sources,
+		token: args.token ?? process.env.GITHUB_TOKEN,
+	});
+
+	console.log(
+		`Pulled ${result.filesWritten} files for ${result.collections.length} collection(s) to ${result.outDir}`,
+	);
+	for (const c of result.collections) {
+		console.log(`  - ${c.id}: ${c.label}`);
+	}
+}
+
+main().catch((err) => {
+	console.error(err instanceof Error ? err.message : err);
+	process.exit(1);
+});

package/src/adapters/config/index.ts

@@ -0,0 +1 @@
+export { createNodeConfigLoader } from "./node-config-loader";

package/src/adapters/config/node-config-loader.ts

@@ -0,0 +1,36 @@
+/**
+ * Node FS-backed config loader.
+ * Tries to dynamically import `${cwd}/${configPath}` and returns its default export.
+ * Returns `null` if the file doesn't exist (caller falls back to defaults).
+ */
+
+import * as path from "node:path";
+import type { ConfigLoader, DocsConfig } from "@create-docs/modules/config";
+import { FilePath } from "@create-docs/modules/content/types";
+import type { AppError } from "@create-docs/shared/errors";
+import { parseError } from "@create-docs/shared/errors";
+import { err, ok, type Result } from "@create-docs/shared/types/result";
+import { nodeFileReader } from "../fs";
+
+export const createNodeConfigLoader = (): ConfigLoader => ({
+	async load(
+		cwd: string,
+		configPath: string,
+	): Promise<Result<Partial<DocsConfig> | null, AppError>> {
+		const fullPath = path.isAbsolute(configPath)
+			? configPath
+			: path.join(cwd, configPath);
+		const fp = FilePath(fullPath);
+		const exists = await nodeFileReader.exists(fp);
+		if (!exists) return ok(null);
+
+		try {
+			// Dynamic import — works in ESM context. CJS/TS configs require the bundler to transform.
+			const url = new URL(`file:///${fullPath.replace(/\\/g, "/")}`).href;
+			const mod: { default?: Partial<DocsConfig> } = await import(url);
+			return ok(mod.default ?? {});
+		} catch (e) {
+			return err(parseError(fullPath, "Failed to load config", e));
+		}
+	},
+});

package/src/adapters/fs/fs-docs-loader.ts

@@ -0,0 +1,31 @@
+/**
+ * File-system-backed DocsLoader — composes the FS adapter with the
+ * processDocsWorkflow use case from the content module.
+ */
+
+import * as path from "node:path";
+import type { ResolvedDocsConfig } from "@create-docs/modules/config";
+import type { DocPage } from "@create-docs/modules/content";
+import { processDocsWorkflow } from "@create-docs/modules/content";
+import type { DocsLoader } from "@create-docs/modules/plugin";
+import type { AppError } from "@create-docs/shared/errors";
+import type { Result } from "@create-docs/shared/types/result";
+import { nodeDirectoryScanner, nodeFileReader } from "../fs";
+
+export const createFsDocsLoader = (): DocsLoader => ({
+	async loadAll(
+		config: ResolvedDocsConfig,
+	): Promise<Result<readonly DocPage[], AppError>> {
+		const reader = nodeFileReader;
+		const scanner = nodeDirectoryScanner;
+		const docsDir = path.isAbsolute(config.docsDir)
+			? config.docsDir
+			: path.resolve(process.cwd(), config.docsDir);
+		return processDocsWorkflow({
+			scanner,
+			reader,
+			docsDir,
+			editLink: config.editLink,
+		});
+	},
+});

package/src/adapters/fs/index.ts

@@ -0,0 +1,12 @@
+export { createFsDocsLoader } from "./fs-docs-loader";
+export {
+	createMemoryDirectoryScanner,
+	createMemoryFileReader,
+	memoryFileSystem,
+} from "./memory-fs";
+export {
+	nodeDirectoryScanner,
+	nodeFileReader,
+	nodeFileWatcher,
+	safeJoin,
+} from "./node-fs";

package/src/adapters/fs/memory-fs.ts

@@ -0,0 +1,60 @@
+/**
+ * In-memory FS adapter for tests and SSR scenarios.
+ * Implements FileReader + DirectoryScanner without touching the disk.
+ */
+
+import type {
+	DirectoryEntry,
+	DirectoryScanner,
+	FilePath,
+	FileReader,
+} from "@create-docs/modules/content";
+import type { AppError } from "@create-docs/shared/errors";
+import { fileNotFound } from "@create-docs/shared/errors";
+import { err, ok, type Result } from "@create-docs/shared/types/result";
+
+export interface MemoryFileSystem {
+	readonly files: ReadonlyMap<string, string>;
+	readonly directories: ReadonlyMap<string, readonly string[]>;
+}
+
+export const memoryFileSystem = (
+	files: ReadonlyMap<string, string>,
+	directories: ReadonlyMap<string, readonly string[]>,
+): MemoryFileSystem => ({ files, directories });
+
+export const createMemoryFileReader = (fs: MemoryFileSystem): FileReader => ({
+	async read(filePath: FilePath): Promise<Result<string, AppError>> {
+		const content = fs.files.get(String(filePath));
+		if (content === undefined) return err(fileNotFound(String(filePath)));
+		return ok(content);
+	},
+	async exists(filePath: FilePath): Promise<boolean> {
+		return fs.files.has(String(filePath));
+	},
+	async stat(
+		filePath: FilePath,
+	): Promise<Result<{ mtimeMs: number; size: number }, AppError>> {
+		const content = fs.files.get(String(filePath));
+		if (content === undefined) return err(fileNotFound(String(filePath)));
+		return ok({ mtimeMs: 0, size: content.length });
+	},
+});
+
+export const createMemoryDirectoryScanner = (
+	fs: MemoryFileSystem,
+): DirectoryScanner => ({
+	async list(
+		dirPath: string,
+	): Promise<Result<readonly DirectoryEntry[], AppError>> {
+		const entries = fs.directories.get(dirPath);
+		if (entries === undefined) return err(fileNotFound(dirPath));
+		return ok(
+			entries.map((name) => ({
+				name,
+				isDirectory: !name.includes("."),
+				path: `${dirPath.replace(/\/$/, "")}/${name}`,
+			})),
+		);
+	},
+});

package/src/adapters/fs/node-fs.ts

@@ -0,0 +1,116 @@
+/**
+ * Node FS adapter — concrete implementation of the content module's FileReader
+ * and DirectoryScanner ports. This is the ONLY place where node:fs/promises is used.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type {
+	DirectoryEntry,
+	DirectoryScanner,
+	FilePath,
+	FileReader,
+	FileWatcher,
+} from "@create-docs/modules/content";
+import type { AppError } from "@create-docs/shared/errors";
+import { fileNotFound, ioError } from "@create-docs/shared/errors";
+import { err, ok, type Result } from "@create-docs/shared/types/result";
+
+/**
+ * Path-traversal safe join. Rejects any attempt to resolve to a path outside
+ * the configured root. Throws an Error containing the absolute resolved path
+ * on violation; callers should treat as AppError.io_error upstream.
+ */
+export const safeJoin = (root: string, requested: string): string => {
+	const absRoot = path.resolve(root);
+	const cleaned = requested.replace(/^[\\/]+/, "");
+	const candidate = path.resolve(absRoot, cleaned);
+	const rel = path.relative(absRoot, candidate);
+	if (rel.startsWith("..") || rel === ".." || path.isAbsolute(rel)) {
+		throw new Error(`Path traversal blocked: ${requested} -> ${candidate}`);
+	}
+	return candidate;
+};
+
+export const nodeFileReader: FileReader = {
+	async read(filePath: FilePath): Promise<Result<string, AppError>> {
+		try {
+			const content = await fs.readFile(String(filePath), "utf-8");
+			return ok(content);
+		} catch (e) {
+			const code = (e as NodeJS.ErrnoException).code;
+			if (code === "ENOENT") return err(fileNotFound(String(filePath), e));
+			return err(ioError(String(filePath), "Failed to read file", e));
+		}
+	},
+	async exists(filePath: FilePath): Promise<boolean> {
+		try {
+			await fs.access(String(filePath));
+			return true;
+		} catch {
+			return false;
+		}
+	},
+	async stat(
+		filePath: FilePath,
+	): Promise<Result<{ mtimeMs: number; size: number }, AppError>> {
+		try {
+			const s = await fs.stat(String(filePath));
+			return ok({ mtimeMs: s.mtimeMs, size: s.size });
+		} catch (e) {
+			const code = (e as NodeJS.ErrnoException).code;
+			if (code === "ENOENT") return err(fileNotFound(String(filePath), e));
+			return err(ioError(String(filePath), "Failed to stat file", e));
+		}
+	},
+};
+
+export const nodeDirectoryScanner: DirectoryScanner = {
+	async list(
+		dirPath: string,
+	): Promise<Result<readonly DirectoryEntry[], AppError>> {
+		try {
+			const entries = await fs.readdir(dirPath, { withFileTypes: true });
+			return ok(
+				entries.map((entry) => ({
+					name: entry.name,
+					isDirectory: entry.isDirectory(),
+					path: path.join(dirPath, entry.name),
+				})),
+			);
+		} catch (e) {
+			const code = (e as NodeJS.ErrnoException).code;
+			if (code === "ENOENT") return err(fileNotFound(dirPath, e));
+			return err(ioError(dirPath, "Failed to read directory", e));
+		}
+	},
+};
+
+export const nodeFileWatcher: FileWatcher = {
+	watch(dir, handlers) {
+		const ac = new AbortController();
+		const iterator = fs
+			.watch(dir, { 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" &&
+						(filename.endsWith(".md") || filename.endsWith(".mdoc"))
+					) {
+						handlers.onChange(filename);
+					}
+				}
+			} catch (e) {
+				handlers.onError(e);
+			}
+		};
+		void consume();
+		return {
+			close: () => {
+				ac.abort();
+			},
+		};
+	},
+};

package/src/adapters/git/index.ts

@@ -0,0 +1,164 @@
+/**
+ * Git Adapter
+ *
+ * Adapter layer for Git operations using simple-git
+ */
+
+import simpleGit, { type SimpleGit } from "simple-git";
+import type {
+	CommitOptions,
+	GitAdapter,
+	GitStatus,
+	PushOptions,
+} from "../../modules/live-editor/ports";
+
+interface GitFile {
+	path: string;
+	index: string;
+	working_dir: string;
+}
+
+// Git adapter state
+export interface SimpleGitAdapterState {
+	readonly git: SimpleGit;
+}
+
+export const createSimpleGitAdapterState = (
+	cwd: string = process.cwd(),
+): SimpleGitAdapterState => ({
+	git: simpleGit(cwd),
+});
+
+// Pure functions for git operations
+export const gitGetCurrentBranch = async (
+	state: SimpleGitAdapterState,
+): Promise<string> => {
+	const branch = await state.git.branch();
+	return branch.current;
+};
+
+export const gitGetStatus = async (
+	state: SimpleGitAdapterState,
+): Promise<GitStatus> => {
+	const status = await state.git.status();
+	const branch = await gitGetCurrentBranch(state);
+
+	return {
+		branch,
+		hasChanges: status.files.length > 0,
+		untracked: status.files
+			.filter((f: GitFile) => f.working_dir === "?")
+			.map((f: GitFile) => f.path),
+		modified: status.files
+			.filter((f: GitFile) => f.working_dir === "M")
+			.map((f: GitFile) => f.path),
+		staged: status.files
+			.filter((f: GitFile) => f.index === "M")
+			.map((f: GitFile) => f.path),
+	};
+};
+
+export const gitCommit = async (
+	state: SimpleGitAdapterState,
+	options: CommitOptions,
+): Promise<void> => {
+	await state.git.add(".");
+	if (options.author && options.email) {
+		await state.git.commit([
+			options.message,
+			"--author",
+			`${options.author} <${options.email}>`,
+		]);
+	} else {
+		await state.git.commit(options.message);
+	}
+};
+
+export const gitPush = async (
+	state: SimpleGitAdapterState,
+	options: PushOptions = {},
+): Promise<void> => {
+	const remote = options.remote || "origin";
+	const branch = options.branch || (await gitGetCurrentBranch(state));
+
+	if (options.force) {
+		await state.git.push(["--force", remote, branch]);
+	} else {
+		await state.git.push(remote, branch);
+	}
+};
+
+export const gitStageFile = async (
+	state: SimpleGitAdapterState,
+	path: string,
+): Promise<void> => {
+	await state.git.add(path);
+};
+
+export const gitUnstageFile = async (
+	state: SimpleGitAdapterState,
+	path: string,
+): Promise<void> => {
+	await state.git.reset(["--mixed", path]);
+};
+
+export const gitDiscardChanges = async (
+	state: SimpleGitAdapterState,
+	path: string,
+): Promise<void> => {
+	await state.git.checkout(path, { "--": path });
+};
+
+/**
+ * SimpleGit adapter implementation
+ */
+export class SimpleGitAdapter implements GitAdapter {
+	private state: SimpleGitAdapterState;
+
+	constructor(cwd: string = process.cwd()) {
+		this.state = createSimpleGitAdapterState(cwd);
+	}
+
+	getState(): SimpleGitAdapterState {
+		return this.state;
+	}
+
+	setState(state: SimpleGitAdapterState): void {
+		this.state = state;
+	}
+
+	async getCurrentBranch(): Promise<string> {
+		return gitGetCurrentBranch(this.state);
+	}
+
+	async getStatus(): Promise<GitStatus> {
+		return gitGetStatus(this.state);
+	}
+
+	async commit(options: CommitOptions): Promise<void> {
+		return gitCommit(this.state, options);
+	}
+
+	async push(options: PushOptions = {}): Promise<void> {
+		return gitPush(this.state, options);
+	}
+
+	async stageFile(path: string): Promise<void> {
+		return gitStageFile(this.state, path);
+	}
+
+	async unstageFile(path: string): Promise<void> {
+		return gitUnstageFile(this.state, path);
+	}
+
+	async discardChanges(path: string): Promise<void> {
+		return gitDiscardChanges(this.state, path);
+	}
+}
+
+/**
+ * Create Git adapter
+ */
+export const createGitAdapter = (cwd?: string): GitAdapter => {
+	return new SimpleGitAdapter(cwd);
+};