@wrikka/create-docs 0.1.0

package/src/modules/external-search/domain/operations/search-operations.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure external search operations.
+ * No I/O. No exceptions thrown. Returns Result types.
+ */
+
+import type { Result } from "@create-docs/shared/types";
+import { err, ok } from "@create-docs/shared/types";
+import type {
+	ExternalSearchConfig,
+	ExternalSearchResult,
+} from "../../types/search";
+
+export type ExternalSearchError = {
+	readonly kind: "external-search-error";
+	readonly message: string;
+};
+
+/**
+ * Search external index with query.
+ */
+export const searchExternal = (
+	_query: string,
+	_config: ExternalSearchConfig,
+): Result<readonly ExternalSearchResult[], ExternalSearchError> => {
+	try {
+		// This will be implemented via adapter
+		// For now, return empty array
+		return ok([]);
+	} catch (error) {
+		return err({
+			kind: "external-search-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Index documents to external search.
+ */
+export const indexToExternal = (
+	_docs: readonly unknown[],
+	_config: ExternalSearchConfig,
+): Result<void, ExternalSearchError> => {
+	try {
+		// This will be implemented via adapter
+		return ok(undefined);
+	} catch (error) {
+		return err({
+			kind: "external-search-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};

package/src/modules/external-search/domain/validators/index.ts

@@ -0,0 +1,55 @@
+// External Search Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Search Endpoint Schema
+ */
+export const searchEndpointSchema: Type = type("string >= 1").narrow(
+	(endpoint: string) =>
+		endpoint.startsWith("http://") || endpoint.startsWith("https://"),
+);
+
+export type SearchEndpoint = typeof searchEndpointSchema.infer;
+
+/**
+ * Search URL Schema
+ */
+export const searchUrlSchema: Type = type("string >= 1").narrow(
+	(url: string) => url.startsWith("http://") || url.startsWith("https://"),
+);
+
+export type SearchUrl = typeof searchUrlSchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate search endpoint using Arktype
+ */
+export const validateSearchEndpoint = (endpoint: unknown): SearchEndpoint => {
+	const result = searchEndpointSchema(endpoint);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Search endpoint must be a valid URL");
+	}
+	return result as SearchEndpoint;
+};
+
+/**
+ * Validate search URL using Arktype
+ */
+export const validateSearchUrl = (url: unknown): SearchUrl => {
+	const result = searchUrlSchema(url);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Search URL must be a valid URL");
+	}
+	return result as SearchUrl;
+};

package/src/modules/external-search/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Public API for the external-search module.
+ */
+
+export { createAlgoliaAdapter } from "./application/algolia-adapter";
+export { createMeilisearchAdapter } from "./application/meilisearch-adapter";
+export * from "./domain/operations/search-operations";
+export * from "./ports/external-search-port";
+export * from "./types/search";

package/src/modules/external-search/ports/external-search-port.ts

@@ -0,0 +1,23 @@
+/**
+ * Port for external search operations.
+ */
+
+export type ExternalSearchPort = {
+	/**
+	 * Search external index.
+	 */
+	readonly search: (
+		query: string,
+		config: unknown,
+	) => Promise<readonly unknown[]>;
+
+	/**
+	 * Index documents to external search.
+	 */
+	readonly index: (docs: readonly unknown[], config: unknown) => Promise<void>;
+
+	/**
+	 * Clear external index.
+	 */
+	readonly clear: (config: unknown) => Promise<void>;
+};

package/src/modules/external-search/types/search.ts

@@ -0,0 +1,19 @@
+/**
+ * External search types for Algolia/MeiliSearch integration.
+ */
+
+export type ExternalSearchConfig = {
+	readonly provider: "algolia" | "meilisearch" | "local";
+	readonly appId?: string;
+	readonly apiKey?: string;
+	readonly indexName?: string;
+	readonly host?: string;
+};
+
+export type ExternalSearchResult = {
+	readonly id: string;
+	readonly title: string;
+	readonly description?: string;
+	readonly url: string;
+	readonly score?: number;
+};

package/src/modules/git-history/application/simple-git-adapter.ts

@@ -0,0 +1,46 @@
+/**
+ * Simple-git adapter implementation.
+ * Provides git history using simple-git library.
+ */
+
+import { ioError, pluginError } from "@create-docs/shared/errors";
+import { simpleGit } from "simple-git";
+import type { GitHistoryPort } from "../ports/git-history-port";
+import type { GitCommit } from "../types/git-history";
+
+export const createSimpleGitAdapter = (): GitHistoryPort => {
+	const git = simpleGit();
+
+	return {
+		getLog: async (filePath: string, config?: unknown) => {
+			try {
+				const maxCommits =
+					config && typeof config === "object" && "maxCommits" in config
+						? (config as { maxCommits: number }).maxCommits
+						: 10;
+
+				const log = await git.log({ file: filePath, maxCount: maxCommits });
+
+				return log.all.map((commit) => ({
+					hash: commit.hash,
+					author: commit.author_name,
+					date: commit.date,
+					message: commit.message,
+				})) as GitCommit[];
+			} catch (error) {
+				throw pluginError("Git log failed", {
+					context: { filePath, config, error: String(error) },
+				});
+			}
+		},
+
+		getFileAtCommit: async (filePath: string, commit: string) => {
+			try {
+				const content = await git.show([`${commit}:${filePath}`]);
+				return content;
+			} catch (error) {
+				throw ioError(filePath, "Git show failed", error);
+			}
+		},
+	};
+};

package/src/modules/git-history/domain/events/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Domain events for git history
+ */
+export interface HistoryLoadedEvent {
+	readonly type: "HISTORY_LOADED";
+	readonly timestamp: number;
+	readonly commitCount: number;
+}
+
+export interface CommitSelectedEvent {
+	readonly type: "COMMIT_SELECTED";
+	readonly timestamp: number;
+	readonly commitHash: string;
+}
+
+export type GitHistoryDomainEvent = HistoryLoadedEvent | CommitSelectedEvent;
+
+export const createHistoryLoadedEvent = (
+	commitCount: number,
+	now: number = Date.now(),
+): HistoryLoadedEvent => ({
+	type: "HISTORY_LOADED",
+	timestamp: now,
+	commitCount,
+});
+
+export const createCommitSelectedEvent = (
+	commitHash: string,
+	now: number = Date.now(),
+): CommitSelectedEvent => ({
+	type: "COMMIT_SELECTED",
+	timestamp: now,
+	commitHash,
+});

package/src/modules/git-history/domain/models/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Domain models for git history
+ */
+export interface GitCommit {
+	readonly hash: string;
+	readonly message: string;
+	readonly author: string;
+	readonly timestamp: number;
+	readonly branch: string;
+}
+
+export const createGitCommit = (
+	hash: string,
+	message: string,
+	author: string,
+	branch: string,
+	options?: { timestamp?: number },
+	now: number = Date.now(),
+): GitCommit => ({
+	hash,
+	message,
+	author,
+	branch,
+	timestamp: options?.timestamp ?? now,
+});

package/src/modules/git-history/domain/operations/git-history-operations.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure git history operations.
+ * No I/O. No exceptions thrown. Returns Result types.
+ */
+
+import type { Result } from "@create-docs/shared/types";
+import { err, ok } from "@create-docs/shared/types";
+import type { GitCommit } from "../../types/git-history";
+
+export type GitHistoryError = {
+	readonly kind: "git-history-error";
+	readonly message: string;
+};
+
+/**
+ * Filter commits by date range.
+ */
+export const filterCommitsByDate = (
+	commits: readonly GitCommit[],
+	since: string,
+	until: string,
+): Result<readonly GitCommit[], GitHistoryError> => {
+	try {
+		const sinceDate = new Date(since);
+		const untilDate = new Date(until);
+
+		const filtered = commits.filter((commit) => {
+			const commitDate = new Date(commit.date);
+			return commitDate >= sinceDate && commitDate <= untilDate;
+		});
+
+		return ok(filtered);
+	} catch (error) {
+		return err({
+			kind: "git-history-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Limit commits to max count.
+ */
+export const limitCommits = (
+	commits: readonly GitCommit[],
+	max: number,
+): readonly GitCommit[] => {
+	return commits.slice(0, max);
+};
+
+/**
+ * Format commit for display.
+ */
+export const formatCommit = (commit: GitCommit): string => {
+	return `${commit.hash.slice(0, 7)} - ${commit.message} (${commit.author})`;
+};

package/src/modules/git-history/domain/validators/index.ts

@@ -0,0 +1,52 @@
+// Git History Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Commit Hash Schema
+ */
+export const commitHashSchema: Type = type(/^[a-f0-9]{40}$/);
+
+export type CommitHash = typeof commitHashSchema.infer;
+
+/**
+ * Branch Name Schema
+ */
+export const branchNameSchema: Type = type("string >= 1");
+
+export type BranchName = typeof branchNameSchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate commit hash using Arktype
+ */
+export const validateCommitHash = (hash: unknown): CommitHash => {
+	const result = commitHashSchema(hash);
+	if (result instanceof type.errors) {
+		throw new ValidationError(
+			"Commit hash must be a valid 40-character hex string",
+		);
+	}
+	return result as CommitHash;
+};
+
+/**
+ * Validate branch name using Arktype
+ */
+export const validateBranchName = (name: unknown): BranchName => {
+	const result = branchNameSchema(name);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Branch name must be a non-empty string");
+	}
+	return result as BranchName;
+};

package/src/modules/git-history/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public API for the git-history module.
+ */
+
+export { createSimpleGitAdapter } from "./application/simple-git-adapter";
+export * from "./domain/operations/git-history-operations";
+export * from "./ports/git-history-port";
+export * from "./types/git-history";

package/src/modules/git-history/ports/git-history-port.ts

@@ -0,0 +1,21 @@
+/**
+ * Port for git history operations.
+ */
+
+export type GitHistoryPort = {
+	/**
+	 * Get git log for a file.
+	 */
+	readonly getLog: (
+		filePath: string,
+		config: unknown,
+	) => Promise<readonly unknown[]>;
+
+	/**
+	 * Get file content at specific commit.
+	 */
+	readonly getFileAtCommit: (
+		filePath: string,
+		commit: string,
+	) => Promise<string>;
+};

package/src/modules/git-history/types/git-history.ts

@@ -0,0 +1,15 @@
+/**
+ * Git history types for version tracking.
+ */
+
+export type GitCommit = {
+	readonly hash: string;
+	readonly author: string;
+	readonly date: string;
+	readonly message: string;
+};
+
+export type GitHistoryConfig = {
+	readonly enabled: boolean;
+	readonly maxCommits: number;
+};

package/src/modules/i18n/application/fs-locale-loader.ts

@@ -0,0 +1,39 @@
+/**
+ * File system adapter for locale loading.
+ */
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { LocaleLoaderPort } from "../ports/locale-loader-port";
+
+export const createFsLocaleLoader = (): LocaleLoaderPort => ({
+	scanLocales: async (docsDir: string) => {
+		try {
+			const entries = await readdir(docsDir, { withFileTypes: true });
+			return entries
+				.filter((entry) => entry.isDirectory())
+				.map((entry) => entry.name);
+		} catch {
+			return [];
+		}
+	},
+
+	loadLocaleDocs: async (locale: string, docsDir: string) => {
+		try {
+			const localeDir = join(docsDir, locale);
+			const entries = await readdir(localeDir, {
+				withFileTypes: true,
+				recursive: true,
+			});
+			return entries
+				.filter(
+					(entry) =>
+						entry.isFile() &&
+						(entry.name.endsWith(".md") || entry.name.endsWith(".mdoc")),
+				)
+				.map((entry) => join(entry.parentPath, entry.name));
+		} catch {
+			return [];
+		}
+	},
+});

package/src/modules/i18n/domain/events/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Domain events for i18n
+ */
+export interface LocaleChangedEvent {
+	readonly type: "LOCALE_CHANGED";
+	readonly timestamp: number;
+	readonly localeCode: string;
+}
+
+export interface TranslationLoadedEvent {
+	readonly type: "TRANSLATION_LOADED";
+	readonly timestamp: number;
+	readonly language: string;
+}
+
+export type I18nDomainEvent = LocaleChangedEvent | TranslationLoadedEvent;
+
+export const createLocaleChangedEvent = (
+	localeCode: string,
+	now: number = Date.now(),
+): LocaleChangedEvent => ({
+	type: "LOCALE_CHANGED",
+	timestamp: now,
+	localeCode,
+});
+
+export const createTranslationLoadedEvent = (
+	language: string,
+	now: number = Date.now(),
+): TranslationLoadedEvent => ({
+	type: "TRANSLATION_LOADED",
+	timestamp: now,
+	language,
+});

package/src/modules/i18n/domain/models/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Domain models for i18n
+ */
+export interface Translation {
+	readonly key: string;
+	readonly value: string;
+	readonly language: string;
+}
+
+export interface Locale {
+	readonly code: string;
+	readonly name: string;
+	readonly rtl: boolean;
+}
+
+export const createTranslation = (
+	key: string,
+	value: string,
+	language: string,
+): Translation => ({
+	key,
+	value,
+	language,
+});
+
+export const createLocale = (
+	code: string,
+	name: string,
+	rtl: boolean = false,
+): Locale => ({
+	code,
+	name,
+	rtl,
+});

package/src/modules/i18n/domain/operations/locale-operations.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure locale operations.
+ * No I/O. No exceptions thrown.
+ */
+
+import type {
+	Locale,
+	LocaleConfig,
+	LocalizedDocPage,
+} from "../../types/locale";
+
+/**
+ * Extract locale from a slug path.
+ * Example: "en/getting-started/introduction" -> "en"
+ */
+export const extractLocaleFromSlug = (
+	slug: string,
+	locales: readonly Locale[],
+): Locale | null => {
+	const parts = slug.split("/");
+	const firstPart = parts[0];
+	if (firstPart && locales.includes(firstPart)) {
+		return firstPart;
+	}
+	return null;
+};
+
+/**
+ * Remove locale prefix from a slug.
+ * Example: "en/getting-started/introduction" -> "getting-started/introduction"
+ */
+export const removeLocaleFromSlug = (slug: string, locale: Locale): string => {
+	return slug.startsWith(`${locale}/`) ? slug.slice(locale.length + 1) : slug;
+};
+
+/**
+ * Add locale prefix to a slug.
+ * Example: "getting-started/introduction" + "en" -> "en/getting-started/introduction"
+ */
+export const addLocaleToSlug = (slug: string, locale: Locale): string => {
+	return `${locale}/${slug}`;
+};
+
+/**
+ * Group doc pages by locale.
+ */
+export const groupDocsByLocale = (
+	pages: readonly LocalizedDocPage[],
+): Readonly<Record<Locale, readonly LocalizedDocPage[]>> => {
+	const groups: Record<string, LocalizedDocPage[]> = {};
+	for (const page of pages) {
+		const { locale } = page;
+		if (!groups[locale]) {
+			groups[locale] = [];
+		}
+		groups[locale].push(page);
+	}
+	return groups;
+};
+
+/**
+ * Validate locale config.
+ */
+export const validateLocaleConfig = (config: LocaleConfig): boolean => {
+	if (!config.defaultLocale || !config.locales.includes(config.defaultLocale)) {
+		return false;
+	}
+	for (const locale of config.locales) {
+		if (!config.localePaths[locale]) {
+			return false;
+		}
+	}
+	return true;
+};

package/src/modules/i18n/domain/validators/index.ts

@@ -0,0 +1,52 @@
+// I18n Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Locale Code Schema
+ */
+export const localeCodeSchema: Type = type("string").narrow(
+	(code: string) => code.length === 2,
+);
+
+export type LocaleCode = typeof localeCodeSchema.infer;
+
+/**
+ * Translation Key Schema
+ */
+export const translationKeySchema: Type = type("string >= 1");
+
+export type TranslationKey = typeof translationKeySchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate locale code using Arktype
+ */
+export const validateLocaleCode = (code: unknown): LocaleCode => {
+	const result = localeCodeSchema(code);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Locale code must be a 2-character string");
+	}
+	return result as LocaleCode;
+};
+
+/**
+ * Validate translation key using Arktype
+ */
+export const validateTranslationKey = (key: unknown): TranslationKey => {
+	const result = translationKeySchema(key);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Translation key must be a non-empty string");
+	}
+	return result as TranslationKey;
+};

package/src/modules/i18n/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public API for the i18n module.
+ */
+
+export { createFsLocaleLoader } from "./application/fs-locale-loader";
+export * from "./domain/operations/locale-operations";
+export * from "./ports/locale-loader-port";
+export * from "./types/locale";

package/src/modules/i18n/ports/locale-loader-port.ts

@@ -0,0 +1,18 @@
+/**
+ * Port for locale loading operations.
+ */
+
+export type LocaleLoaderPort = {
+	/**
+	 * Scan docs directory for locale-specific folders.
+	 */
+	readonly scanLocales: (docsDir: string) => Promise<readonly string[]>;
+
+	/**
+	 * Load docs for a specific locale.
+	 */
+	readonly loadLocaleDocs: (
+		locale: string,
+		docsDir: string,
+	) => Promise<readonly string[]>;
+};